Squash commits for public release
This commit is contained in:
30
docs/boot.md
Normal file
30
docs/boot.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Bootloaders
|
||||
|
||||
The boot process of XKernel could be divided into 2 parts: bootloader(prekernel) and kernel. These parts are tight together and share the same ABI to prepare the required environment for the kernel.
|
||||
|
||||
### Kernel boot requirements
|
||||
|
||||
* VM is on.
|
||||
* Filled *boot args*.
|
||||
* All *kernel data* required for a kernel bootup (e.g. the kernel itself, boot args and vm translation tables) should be a continuous region of memory (both physical and virtual). This region is described with `boot_args->vaddr`, `boot_args->paddr` and `boot_args->kernel_data_size`.
|
||||
* After *kernel data* **4mb** should be mapped for a successful kernel boot process. This part is used for kernel structs (e.g physical allocation table) which are required before the kernel can set up its own vm translation tables.
|
||||
* Initial debug devices should be mapped (UART and/or framebuffer).
|
||||
* For 64-bit kernels all RAM should be mapped to itself.
|
||||
|
||||
### Prekernel
|
||||
|
||||
The kernel is an ELF file but there are some use cases when it is needed a raw binary image or an UEFI-capable image. In order to prepare the required environment for a kernel bootup there is a part called *prekernel*. It is a position independent raw binary which contains code to boot the kernel.
|
||||
|
||||
Raw image consists of prekernel, kernel and devtree.
|
||||
|
||||
### Bootloaders
|
||||
|
||||
An alternative to *prekernel* part is a standalone bootloader which could prepare the required environment for the kernel.
|
||||
|
||||
## Dirs
|
||||
|
||||
* [arm32](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/boot/arm32) Arm32 bootloader.
|
||||
* [arm64](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/boot/arm64) Arm64 bootloader.
|
||||
* [libboot](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/boot/libboot) Bootloader library.
|
||||
* [x86](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/boot/x86) x86 bootloader.
|
||||
* [x86_64](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/boot/x86_64) x86_64 bootloader.
|
||||
320
docs/build.md
Normal file
320
docs/build.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# Building OS
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The project uses GN Build System, please ensure that you have `gn` binary. If your system doesn't have the build system, please visit [instructions how to get a GN binary](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/docs/getting_gn.md)
|
||||
|
||||
### Getting QEMU
|
||||
|
||||
The project uses QEMU as a primary build and test target. Please follow [instructions how to get a QEMU binary](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/docs/getting_qemu.md).
|
||||
|
||||
### Tools for MacOS
|
||||
|
||||
```bash
|
||||
brew install --cask osxfuse
|
||||
|
||||
brew install coreutils qemu e2fsprogs nasm m4 autoconf libtool automake bash gcc@10 ninja
|
||||
|
||||
# install fuse-ext2
|
||||
```
|
||||
|
||||
`fuse-ext2` is not available as homebrew formula, download [sources](https://github.com/alperakcan/fuse-ext2) and compile it following [instructions](https://apple.stackexchange.com/questions/226981/how-do-i-install-fuse-ext2-to-use-with-osxfuse).
|
||||
|
||||
*Notes*:
|
||||
|
||||
* Make sure you have `xcode-tools` installed.
|
||||
|
||||
</br>
|
||||
|
||||
### Tools for Linux (Ubuntu)
|
||||
|
||||
```bash
|
||||
apt install build-essential curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs qemu-system-i386 qemu-utils nasm fuseext2 ninja
|
||||
```
|
||||
|
||||
</br>
|
||||
|
||||
|
||||
|
||||
### Tools for Windows (WSL2)
|
||||
|
||||
**Setting up WSL2**
|
||||
|
||||
1. **Enable WSL2** (requires Windows 10 version 2004+ or Windows 11):
|
||||
|
||||
```powershell
|
||||
|
||||
# Run in PowerShell as Administrator
|
||||
|
||||
wsl --install
|
||||
|
||||
```
|
||||
|
||||
This installs WSL2 with Ubuntu by default. Reboot when prompted.
|
||||
|
||||
|
||||
|
||||
2. **Install Ubuntu from Microsoft Store** (if not auto-installed):
|
||||
|
||||
- Open Microsoft Store
|
||||
|
||||
- Search for "Ubuntu" (recommend Ubuntu 22.04 LTS)
|
||||
|
||||
- Click "Get" and install
|
||||
|
||||
|
||||
|
||||
3. **Set WSL2 as default version** (if needed):
|
||||
|
||||
```powershell
|
||||
|
||||
wsl --set-default-version 2
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
4. **Launch Ubuntu** from Start Menu and create a user account.
|
||||
|
||||
|
||||
|
||||
**Installing Development Tools in WSL2**
|
||||
|
||||
|
||||
|
||||
Once inside your WSL2 Ubuntu terminal:
|
||||
|
||||
|
||||
|
||||
```bash
|
||||
|
||||
# Update package lists
|
||||
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
|
||||
|
||||
# Install build tools
|
||||
|
||||
sudo apt install build-essential curl libmpfr-dev libmpc-dev libgmp-dev \
|
||||
|
||||
e2fsprogs qemu-system-x86 qemu-system-arm qemu-system-misc \
|
||||
|
||||
qemu-utils nasm ninja-build git python3 python3-pip -y
|
||||
```
|
||||
**WSL2-Specific Notes**:
|
||||
|
||||
|
||||
|
||||
* **File Performance**: Keep your project files within the WSL2 filesystem rather than Windows filesystem (`/mnt/c/... `) for much better I/O performance.
|
||||
|
||||
* **GUI Applications**: WSL2 supports GUI apps natively on Windows 11. On Windows 10, you may need an X server like VcXsrv for QEMU's graphical output.
|
||||
|
||||
* **Memory Limits**: WSL2 defaults to 50% of host RAM. Create `%USERPROFILE%\.wslconfig` to adjust:
|
||||
|
||||
```ini
|
||||
|
||||
[wsl2]
|
||||
|
||||
memory=8GB
|
||||
|
||||
processors=4
|
||||
|
||||
```
|
||||
|
||||
* **Accessing WSL files from Windows**: Navigate to `\\wsl$\Ubuntu\home\<username>\` in File Explorer.
|
||||
|
||||
* **Restarting WSL**: If you encounter issues, restart WSL with `wsl --shutdown` in PowerShell, then relaunch.
|
||||
|
||||
|
||||
|
||||
</br>
|
||||
|
||||
## Cross-compiler
|
||||
|
||||
xOS could be compiled both with GNU and LLVM toochains.
|
||||
|
||||
*Note* that in GNU world, every host/target combination has its own set of binaries, headers, libraries, etc. So, choose GNU Toolchain based on target architecture you want to compile the OS to.
|
||||
|
||||
### GNU Toolchain for MacOS
|
||||
|
||||
***x86***
|
||||
|
||||
```bash
|
||||
brew install i686-elf-gcc
|
||||
```
|
||||
|
||||
***x86-64***
|
||||
|
||||
```bash
|
||||
brew install x86_64-elf-gcc
|
||||
```
|
||||
|
||||
***Arm64***
|
||||
|
||||
```bash
|
||||
brew install aarch64-elf-gcc
|
||||
```
|
||||
|
||||
</br>
|
||||
|
||||
### LLVM Toolchain for MacOS
|
||||
|
||||
```bash
|
||||
brew install llvm
|
||||
```
|
||||
|
||||
</br>
|
||||
|
||||
### GNU Toolchain for Linux (Ubuntu) and WSL2
|
||||
|
||||
***x86***
|
||||
|
||||
```bash
|
||||
./toolchains/scripts/i686-elf-tools.sh
|
||||
```
|
||||
|
||||
***Arm32***
|
||||
|
||||
```bash
|
||||
./toolchains/scripts/arm-none-eabi-tools.sh
|
||||
```
|
||||
|
||||
</br>
|
||||
|
||||
### LLVM Toolchain for Linux (Ubuntu) and WSL2
|
||||
```bash
|
||||
wget https://apt.llvm.org/llvm.sh
|
||||
chmod +x llvm.sh
|
||||
sudo ./llvm.sh 18
|
||||
```
|
||||
|
||||
Learn more on <https://apt.llvm.org>
|
||||
|
||||
### Python Dependencies
|
||||
|
||||
It's recommended to use a virtual environment to avoid conflicts with system packages.
|
||||
|
||||
**Create and activate a virtual environment:**
|
||||
|
||||
```bash
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
|
||||
# Activate on Linux/macOS/WSL2
|
||||
source venv/bin/activate
|
||||
```
|
||||
|
||||
**Install dependencies:**
|
||||
|
||||
```bash
|
||||
pip install -r utils/python_requirements.txt
|
||||
```
|
||||
|
||||
**Note**: Remember to activate the virtual environment each time you work on the project. To deactivate, simply run `deactivate`.
|
||||
|
||||
|
||||
|
||||
|
||||
## Building OS
|
||||
|
||||
Now we are ready to build the OS :)
|
||||
|
||||
### Generating Ninja
|
||||
|
||||
To generate ninja just run `./gn_gen.sh`. This command creates build directory `out/` and disk image for the OS.
|
||||
|
||||
***Note*** you can set some environment variables before running `./gn_gen.sh` to change some parameters, visit [Environment varibles](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/docs/build.md#environment-variables) to learn more.
|
||||
|
||||
#### **Options of ./gn_gen.sh**
|
||||
|
||||
* --target_arch|--target_cpu(deprecated) *value*
|
||||
* Sets target arch.
|
||||
* Possible values:
|
||||
* x86 *(default)*
|
||||
* x86_64
|
||||
* arm32 / arm
|
||||
* arm64 / aarch64
|
||||
* --host *value*
|
||||
* Sets toolchain to build the OS.
|
||||
* Possible values:
|
||||
* gnu *(default)*
|
||||
* llvm
|
||||
* --device_type *value*
|
||||
* Configures OS parts to work in either desktop or mobile mode.
|
||||
* Possible values:
|
||||
* d / desktop *(default)*
|
||||
* m / mobile
|
||||
* --test_method *value*
|
||||
* Possible values:
|
||||
* none *(default)*
|
||||
* tests
|
||||
* bench
|
||||
* --target_board *value*
|
||||
* See "Available targets" table below.
|
||||
* --dir *value*
|
||||
* Creates the build directory with the given name.
|
||||
* -y|--yes
|
||||
* Force yes all operations.
|
||||
* -h|--help
|
||||
* Prints all options of ./gn_gen.sh.
|
||||
|
||||
So to build xOS for Arm with LLVM you have to generate Ninja files with `./gn_gen.sh --target_arch arm32 --host llvm`
|
||||
|
||||
#### **Environment variables**
|
||||
|
||||
Another option how to configure the project is environment variables.
|
||||
|
||||
* `XOS_QEMU_SMP`
|
||||
* CPU cores count in the system.
|
||||
* `XOS_QEMU_X86`
|
||||
* Path to *qemu-system-i386* executable
|
||||
* `XOS_QEMU_X86_64`
|
||||
* Path to *qemu-system-x86_64* executable
|
||||
* `XOS_QEMU_ARM`
|
||||
* Path to *qemu-system-arm* executable
|
||||
* `XOS_QEMU_AA64`
|
||||
* Path to *qemu-system-aarch64* executable
|
||||
* `LLVM_BIN_PATH` *(Only with --host llvm)*
|
||||
* ***Must be set before `./gn_gen.sh`***
|
||||
* Path to LLVM bins.
|
||||
|
||||
</br>
|
||||
|
||||
### Building
|
||||
|
||||
Move to `out/` directory where the OS will be built. There are several scripts:
|
||||
|
||||
* `build.sh` - builds OS
|
||||
* `sync.sh` - synchronise files with the disk image
|
||||
* `run.sh` - launches QEMU or a real device
|
||||
|
||||
The right sequence to run the OS is to build, sync, launch or use `all.sh` which combine these 3 scripts.
|
||||
|
||||
**WSL2 Note**: QEMU graphical output works on Windows 11 by default. On Windows 10, you may need to set `DISPLAY` environment variable if using an X server:
|
||||
```bash
|
||||
export DISPLAY=:0
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
There are several scripts which might help you to debug the OS:
|
||||
|
||||
* `debug.sh` - launches QEMU in debug mode. Debug analog of `run.sh` (available only when run.sh uses QEMU)
|
||||
* `dll.sh` - Debug analog of `all.sh`.
|
||||
|
||||
Also you can run `gdb` or `lldb` from the `out/` directory, which will automatically load kernel symbols and connect to QEMU in debug mode.
|
||||
|
||||
### Available boards
|
||||
|
||||
***x86***
|
||||
|
||||
* `i386` - regular x86 (i386). (default)
|
||||
|
||||
***x86_64***
|
||||
|
||||
* `x86_64` - regular x86_64. (default)
|
||||
|
||||
***Arm32***
|
||||
|
||||
* `vexpress-a15` - QEMU's vexpress-a15 target. (default)
|
||||
26
docs/getting_gn.md
Normal file
26
docs/getting_gn.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# Getting GN
|
||||
|
||||
GN is a meta-build system that generates build files for Ninja.
|
||||
|
||||
## Getting a binary
|
||||
|
||||
You can download the latest version of GN binary for Linux and macOS from Google's build infrastructure
|
||||
|
||||
| MacOS | Linux |
|
||||
| ------------- | ------------- |
|
||||
| [amd64](https://chrome-infra-packages.appspot.com/dl/gn/gn/mac-amd64/+/latest)<br>[arm64](https://chrome-infra-packages.appspot.com/dl/gn/gn/mac-arm64/+/latest) | [amd64](https://chrome-infra-packages.appspot.com/dl/gn/gn/linux-amd64/+/latest)<br>[arm64](https://chrome-infra-packages.appspot.com/dl/gn/gn/linux-arm64/+/latest) |
|
||||
|
||||
Alternatively, you can build GN from source with a C++17 compiler:
|
||||
|
||||
```bash
|
||||
git clone https://gn.googlesource.com/gn
|
||||
cd gn
|
||||
python build/gen.py
|
||||
ninja -C out
|
||||
# To run tests:
|
||||
out/gn_unittests
|
||||
```
|
||||
|
||||
*Note:* On Linux and Mac, the default compiler is clang++, a recent version is expected to be found in PATH. This can be overridden by setting CC, CXX, and AR.
|
||||
|
||||
For more inforamtion, please visit: https://gn.googlesource.com/gn/
|
||||
15
docs/getting_qemu.md
Normal file
15
docs/getting_qemu.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Getting QEMU
|
||||
|
||||
QEMU is an emulator used for running and debugging xOS.
|
||||
|
||||
### QEMU for MacOS
|
||||
|
||||
```bash
|
||||
brew install qemu
|
||||
```
|
||||
|
||||
### Tools for Linux (Ubuntu)
|
||||
|
||||
```bash
|
||||
apt install qemu-utils qemu-system-i386 qemu-system-x86_64 qemu-system-arm
|
||||
```
|
||||
16
docs/kernel.md
Normal file
16
docs/kernel.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# XKernel
|
||||
|
||||
The XKernel is a unix-like kernel of xOS, supporting x86/x86-64, arm32 and arm64 architectures.
|
||||
|
||||
## Dirs
|
||||
|
||||
* [algo](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/algo) contains implementation of algorithms and data structures which are used inside the kernel.
|
||||
* [drivers](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/drivers) contains implementation of drivers for supported platforms.
|
||||
* [fs](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/fs) contains implementation of VFS and file systems which are supported.
|
||||
* [io](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/io) contains implementation of communication parts.
|
||||
* [libkern](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/libkern) is a support library for kernel.
|
||||
* [mem](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/mem) contains implementation of memory managers (both virtual and physical).
|
||||
* [platform](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/platform) contains platform specific code.
|
||||
* [syscalls](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/syscalls) contains implementation of syscalls.
|
||||
* [tasking](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/tasking) contains implementation of tasking-control mechanisms.
|
||||
* [time](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/kernel/kernel/time) contains implementation of a time manager.
|
||||
12
docs/libs.md
Normal file
12
docs/libs.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# Libraries
|
||||
|
||||
The userland of xOS contains several custom libraries
|
||||
|
||||
* [LibC](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/libs/libc) - the standard library for C.
|
||||
* [LibCxx](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/libs/libcxx) - the standard library for C++, targeting C++17 and above.
|
||||
* [LibObjC](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/libs/libobjc) - the Objective-C runtime library.
|
||||
* [LibAPI](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/libs/libapi) the standard API library.
|
||||
* [LibFoundation](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/libs/libfoundation) - provides a base layer of functionality for apps and libraries which are implemented in C++ and Objective-C.
|
||||
* [LibIPC](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/libs/libipc) - manages inter-prcess communication for C++.
|
||||
* [LibG](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/libs/libg) - provides low-level 2D rendering.
|
||||
* [LibUI](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/libs/libui) - provides the required tools to build UI applications.
|
||||
25
docs/target_apl.md
Normal file
25
docs/target_apl.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Target Apl
|
||||
|
||||
## Introduction
|
||||
|
||||
xOS gets support for `apl` target allowing to run the OS on a real i-device.
|
||||
|
||||
## How to boot
|
||||
|
||||
* Step 1: The process of compiling the OS is similar to other targets. You have to provide `apl` as a `target_board` to GN Build System. More information you can find [on this page](https://code.ayaantunio.me/ayaan/Custom-Operating-System/src/branch/master/docs/build.md).
|
||||
|
||||
* Step 2: To get access to the bootloader you have to jailbreak your i-device. The checkra1n environment is used. You can get the binary at [http://checkra.in/](http://checkra.in/).
|
||||
|
||||
* Step 3: After configuring GN you have to provide path to the checkra1n binary with a $CHECKRAIN env variable.
|
||||
|
||||
* Step 4: Run `./all.sh` from `out/` dir. This will compile the OS, prepare ramdisk and compile a custom version of pongoOS which is used as a bootloader.
|
||||
|
||||
|
||||
Note: to turn off xOS, [force reset](https://support.apple.com/en-gb/guide/iphone/iph8903c3ee6/15.0/ios/15.0) your device.
|
||||
|
||||
## Limitations
|
||||
|
||||
Support for `apl` target at a early stage of development. Currently only devices with A7-A9x are supported. We have also plans to get support for AIC and touchscreen.
|
||||
|
||||
|
||||
***NOTE: Please ensure you have a backup of your device before applying the jailbreak. While the data loss is unlikely, we are not responsible if something goes wrong. Use it on your own risk.***
|
||||
Reference in New Issue
Block a user