|
1 | 1 | # bootloader |
2 | 2 |
|
3 | | -[](https://dev.azure.com/rust-osdev/bootloader/_build/latest?definitionId=1&branchName=master) [](https://gitter.im/rust-osdev/bootloader?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
4 | | - |
5 | | -An experimental x86 bootloader written in Rust and inline assembly. |
6 | | - |
7 | | -Written for the [second edition](https://github.com/phil-opp/blog_os/issues/360) of the [Writing an OS in Rust](https://os.phil-opp.com) series. |
8 | | - |
9 | | -## Design |
10 | | - |
11 | | -When you press the power button the computer loads the BIOS from some flash memory stored on the motherboard. |
12 | | -The BIOS initializes and self tests the hardware then loads the first 512 bytes into memory from the media device |
13 | | -(i.e. the cdrom or floppy disk). If the last two bytes equal 0xAA55 then the BIOS will jump to location 0x7C00 effectively |
14 | | -transferring control to the bootloader. At this point the CPU is running in 16 bit mode, |
15 | | -meaning only the 16 bit registers are available. Also since the BIOS only loads the first 512 bytes this means our bootloader |
16 | | -code has to stay below that limit, otherwise we’ll hit uninitialised memory! |
17 | | -Using [Bios interrupt calls](https://en.wikipedia.org/wiki/BIOS_interrupt_call) the bootloader prints debug information to the screen. |
18 | | -For more information on how to write a bootloader click [here](http://3zanders.co.uk/2017/10/13/writing-a-bootloader/). |
19 | | -The assembler files get imported through the [global_asm feature](https://doc.rust-lang.org/unstable-book/library-features/global-asm.html). |
20 | | -The assembler syntax definition used is the one llvm uses: [GNU Assembly](http://microelectronics.esa.int/erc32/doc/as.pdf). |
21 | | - |
22 | | -* stage_1.s |
23 | | -This stage initializes the stack, enables the A20 line, loads the rest of |
24 | | -the bootloader from disk, and jumps to stage_2. |
25 | | - |
26 | | -* stage_2.s |
27 | | -This stage sets the target operating mode, loads the kernel from disk, |
28 | | -creates an e820 memory map, enters protected mode, and jumps to the |
29 | | -third stage. |
30 | | - |
31 | | -* stage_3.s |
32 | | -This stage performs some checks on the CPU (cpuid, long mode), sets up an |
33 | | -initial page table mapping (identity map the bootloader, map the P4 |
34 | | -recursively, map the kernel blob to 4MB), enables paging, switches to long |
35 | | -mode, and jumps to stage_4. |
36 | | - |
37 | | - |
38 | | -## Build chain |
39 | | -The file `.cargo/config` defines an llvm target file called `x86_64-bootloader.json`. |
40 | | -This file defines the architecture sets freestanding flags and tells llvm to use the linker script `linker.ld`. |
41 | | - |
42 | | -The linker script tells the linker at which offsets the sections should be mapped to. In our case it tells the linker |
43 | | -that the bootloader asm files stage_0-3.s should be mapped to the very beginning of the executable. Read more about linker scripts |
44 | | -[here](https://www.sourceware.org/binutils/docs/ld/Scripts.html) |
45 | | - |
46 | | -Another important role plays the file `build.rs`. |
47 | | -Placing a file named `build.rs` in the root of a package will cause |
48 | | -Cargo to compile that script and execute it just before building the package. |
49 | | -You can read more about it [here](https://doc.rust-lang.org/cargo/reference/build-scripts.html). |
50 | | -The `build.rs` file execute the llvm tools you installed with `rustup component add llvm-tools-preview` |
51 | | -in this order: |
52 | | - |
53 | | -* Check size of .text section of the kernel if it's too small throw an error |
54 | | -```bash |
55 | | -llvm-size "../../target/x86_64-os/debug/svm_kernel" |
56 | | -``` |
57 | | - |
58 | | -* Strip debug symbols from kernel to make loading faster |
59 | | -```bash |
60 | | -llvm-objcopy "--strip-debug" "../../target/x86_64-os/debug/svm_kernel" "target/x86_64-bootloader/debug/build/bootloader-c8df27c930d8f65a/out/kernel_stripped-svm_kernel" |
61 | | -``` |
62 | | -* Rename the .data section to .kernel in the stripped kernel. |
63 | | - Objcopy when using `--binary-architecture` flag creates three synthetic symbols |
64 | | - `_binary_objfile_start`, `_binary_objfile_end`, `_binary_objfile_size.`. |
65 | | -These symbols use the project / binary name which is why we have to rename them to something more generic |
66 | | -to be able to reference them. |
67 | | -```bash |
68 | | -llvm-objcopy "-I" "binary" "-O" "elf64-x86-64" "--binary-architecture=i386:x86-64" "--rename-section" ".data=.kernel" "--redefine-sym" "_binary_kernel_stripped_svm_kernel_start=_kernel_start_addr" "--redefine-sym" "_binary_kernel_stripped_svm_kernel_end=_kernel_end_addr" "--redefine-sym" "_binary_kernel_stripped_svm_kernel_size=_kernel_size" "target/x86_64-bootloader/debug/build/bootloader-c8df27c930d8f65a/out/kernel_stripped-svm_kernel" "target/x86_64-bootloader/debug/build/bootloader-c8df27c930d8f65a/out/kernel_bin-svm_kernel.o" |
69 | | -``` |
70 | | -* Now create a static library out of it |
71 | | -```bash |
72 | | -llvm-ar "crs" "bootloader/target/x86_64-bootloader/debug/build/bootloader-c8df27c930d8f65a/out/libkernel_bin-svm_kernel.a" "target/x86_64-bootloader/debug/build/bootloader-c8df27c930d8f65a/out/kernel_bin-svm_kernel.o" |
73 | | -``` |
74 | | -Afterwards `build.rs` tells cargo to use the newly created static library to link against your kernel, with the help of the linker script everything gets placed correctly in the |
75 | | -resulting elf file. |
76 | | -The last step is to strip away the elf header from the resulting elf binary so that the bios can jump directly to the bootloader `stage_1.s`. This is done with: |
77 | | -```bash |
78 | | -cargo objcopy -- -I elf64-x86-64 -O binary --binary-architecture=i386:x86-64 \ |
79 | | - target/x86_64-bootloader/release/bootloader target/x86_64-bootloader/release/bootloader.bin |
80 | | -``` |
81 | | - |
82 | | - |
83 | | -## Configuration |
84 | | - |
85 | | -The bootloader exposes a few variables which can be configured through the `Cargo.toml` of your kernel: |
86 | | - |
87 | | -```toml |
88 | | -[package.metadata.bootloader] |
89 | | -# The address at which the kernel stack is placed. If not provided, the bootloader |
90 | | -# dynamically searches for a location. |
91 | | -kernel-stack-address = "0xFFFFFF8000000000" |
92 | | - |
93 | | -# The size of the kernel stack, given in number of 4KiB pages. Defaults to 512. |
94 | | -kernel-stack-size = 128 |
95 | | - |
96 | | -# The virtual address offset from which physical memory is mapped, as described in |
97 | | -# https://os.phil-opp.com/paging-implementation/#map-the-complete-physical-memory |
98 | | -# Only applies if the `map_physical_memory` feature of the crate is enabled. |
99 | | -# If not provided, the bootloader dynamically searches for a location. |
100 | | -physical-memory-offset = "0xFFFF800000000000" |
101 | | - |
102 | | -# The address at which the bootinfo struct will be placed. if not provided, |
103 | | -# the bootloader will dynamically search for a location. |
104 | | -boot-info-address = "0xFFFFFFFF80000000" |
105 | | -``` |
106 | | - |
107 | | -Note that the addresses **must** be given as strings (in either hex or decimal format), as [TOML](https://github.com/toml-lang/toml) does not support unsigned 64-bit integers. |
| 3 | +[](https://docs.rs/bootloader) |
| 4 | +[](https://github.com/rust-osdev/bootloader/actions/workflows/build.yml) |
| 5 | +[](https://gitter.im/rust-osdev/bootloader?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
| 6 | + |
| 7 | +An experimental x86_64 bootloader that works on both BIOS and UEFI systems. Written in Rust and some inline assembly, buildable on all platforms without additional build-time dependencies (just some `rustup` components). |
108 | 8 |
|
109 | 9 | ## Requirements |
110 | 10 |
|
111 | 11 | You need a nightly [Rust](https://www.rust-lang.org) compiler and [cargo xbuild](https://github.com/rust-osdev/cargo-xbuild). You also need the `llvm-tools-preview` component, which can be installed through `rustup component add llvm-tools-preview`. |
112 | 12 |
|
113 | | -## Build |
114 | | - |
115 | | -The simplest way to use the bootloader is in combination with the [bootimage](https://github.com/rust-osdev/bootimage) tool. This crate **requires at least bootimage 0.7.7**. With the tool installed, you can add a normal cargo dependency on the `bootloader` crate to your kernel and then run `bootimage build` to create a bootable disk image. You can also execute `bootimage run` to run your kernel in [QEMU](https://www.qemu.org/) (needs to be installed). |
116 | | - |
117 | | -To compile the bootloader manually, you need to invoke `cargo xbuild` with two environment variables: |
118 | | -* `KERNEL`: points to your kernel executable (in the ELF format) |
119 | | -* `KERNEL_MANIFEST`: points to the `Cargo.toml` describing your kernel |
120 | | - |
121 | | -For example: |
122 | | -``` |
123 | | -KERNEL=/path/to/your/kernel/target/debug/your_kernel KERNEL_MANIFEST=/path/to/your/kernel/Cargo.toml cargo xbuild |
124 | | -``` |
125 | | - |
126 | | -As an example, you can build the bootloader with example kernel from the `example-kernel` directory with the following commands: |
127 | | - |
128 | | -``` |
129 | | -cd example-kernel |
130 | | -cargo xbuild |
131 | | -cd .. |
132 | | -KERNEL=example-kernel/target/x86_64-example-kernel/debug/example-kernel KERNEL_MANIFEST=example-kernel/Cargo.toml cargo xbuild --release --features binary |
133 | | -``` |
| 13 | +## Usage |
134 | 14 |
|
135 | | -The `binary` feature is required to enable the dependencies required for compiling the bootloader executable. The command results in a bootloader executable at `target/x86_64-bootloader.json/release/bootloader`. This executable is still an ELF file, which can't be run directly. |
| 15 | +See our [documentation](https://docs.rs/bootloader). |
136 | 16 |
|
137 | | -## Run |
| 17 | +## Architecture |
138 | 18 |
|
139 | | -To run the compiled bootloader executable, you need to convert it to a binary file. You can use the `llvm-objcopy` tools that ships with the `llvm-tools-preview` rustup component. The easiest way to use this tool is using [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils), which can be installed through `cargo install cargo-binutils`. Then you can perform the conversion with the following command: |
| 19 | +This project consists of three separate entities: |
140 | 20 |
|
141 | | -``` |
142 | | -cargo objcopy -- -I elf64-x86-64 -O binary --binary-architecture=i386:x86-64 \ |
143 | | - target/x86_64-bootloader/release/bootloader target/x86_64-bootloader/release/bootloader.bin |
144 | | -``` |
| 21 | +- A library with the entry point and boot info definitions that kernels can include as a normal cargo dependency. |
| 22 | +- BIOS and UEFI binaries that contain the actual bootloader implementation. |
| 23 | +- A `builder` binary to simplify the build process of the BIOS and UEFI binaries. |
145 | 24 |
|
146 | | -You can run the `bootloader.bin` file using [QEMU](https://www.qemu.org/): |
| 25 | +These three entities are currently all combined in a single crate using cargo feature flags. The reason for this is that the kernel and bootloader must use the exact same version of the `BootInfo` struct to prevent undefined behavior (we did not stabilize the boot info format yet, so it might change between versions). |
147 | 26 |
|
148 | | -``` |
149 | | -qemu-system-x86_64 -drive format=raw,file=target/x86_64-bootloader/release/bootloader.bin |
150 | | -``` |
| 27 | +### Build and Boot |
151 | 28 |
|
152 | | -Or burn it to an USB drive to boot it on real hardware: |
| 29 | +The build and boot process works the following way: |
153 | 30 |
|
154 | | -``` |
155 | | -dd if=target/x86_64-bootloader/release/bootloader.bin of=/dev/sdX && sync |
156 | | -``` |
| 31 | +- The `builder` binary is a small command line tool that takes the path to the kernel manifest and binary as arguments. Optionally, it allows to override the cargo target and output dirs. It also accepts a `--quiet` switch and allows to only build the BIOS or UEFI binary instead of both. |
| 32 | +- After parsing the arguments, the `builder` binary invokes the actual build command for the BIOS/UEFI binaries, which includes the correct `--target` and `--features` arguments (and `-Zbuild-std`). The kernel manifest and binary paths are passed as `KERNEL_MANIFEST` and `KERNEL` environment variables. |
| 33 | +- The next step in the build process is the `build.rs` build script. It only does something when building the BIOS/UEFI binaries (indicated by the `binary` feature), otherwise it is a no-op. |
| 34 | + - The script first runs some sanity checks, e.g. the kernel manifest and binary should be specified in env variables and should exist, the correct target triple should be used, and the `llvm-tools` rustup component should be installed. |
| 35 | + - Then it copies the kernel executable and strips the debug symbols from it to make it smaller. This does not affect the original kernel binary. The stripped binary is then converted to a byte array and provided to the BIOS/UEFI binaries, either as a Rust `static` or through a linker argument. |
| 36 | + - Next, the bootloader configuration is parsed, which can be specified in a `package.metadata.bootloader` table in the kernel manifest file. This requires some custom string parsing since TOML does not support unsigned 64-bit integers. Parse errors are turned into `compile_error!` calls to give nicer error messages. |
| 37 | + - After parsing the configuration, it is written as a Rust struct definition into a new `bootloader_config.rs` file in the cargo `OUT_DIR`. This file is then included by the UEFI/BIOS binaries. |
| 38 | +- After the build script, the compilation continues with either the `bin/uefi.rs` or the `bin/bios.rs`: |
| 39 | + - The `bin/uefi.rs` specifies an UEFI entry point function called `efi_main`. It uses the [`uefi`](https://docs.rs/uefi/0.8.0/uefi/) crate to set up a pixel-based framebuffer using the UEFI GOP protocol. Then it exits the UEFI boot services and stores the physical memory map. The final step is to create some page table abstractions and call into `load_and_switch_to_kernel` function that is shared with the BIOS boot code. |
| 40 | + - The `bin/bios.rs` function does not provide a direct entry point. Instead it includes several assembly files (`asm/stage-*.rs`) that implement the CPU initialization (from real mode to long mode), the framebuffer setup (via VESA), and the memory map creation (via a BIOS call). The assembly stages are explained in more detail below. After the assembly stages, the execution jumps to the `bootloader_main` function in `bios.rs`. There we set up some additional identity mapping, translate the memory map and framebuffer into Rust structs, detect the RSDP table, and create some page table abstractions. Then we call into the `load_and_switch_to_kernel` function like the `bin/uefi.rs`. |
| 41 | +- The common `load_and_switch_to_kernel` function is defined in `src/binary/mod.rs`. This is also the file that includes the `bootloader_config.rs` generated by the build script. The `load_and_switch_to_kernel` functions performs the following steps: |
| 42 | + - Parse the kernel binary and map it in a new page table. This includes setting up the correct permissions for each page, initializing `.bss` sections, and allocating a stack with guard page. The relevant functions for these steps are `set_up_mappings` and `load_kernel`. |
| 43 | + - Create the `BootInfo` struct, which abstracts over the differences between BIOS and UEFI booting. This step is implemented in the `create_boot_info` function. |
| 44 | + - Do a context switch and jump to the kernel entry point function. This involves identity-mapping the context switch function itself in both the kernel and bootloader page tables to prevent a page fault after switching page tables. This switch step is implemented in the `switch_to_kernel` and `context_switch` functions. |
| 45 | +- As a last step after a successful build, the `builder` binary turns the compiled bootloader executable (includes the kernel) into a bootable disk image. For UEFI, this means that a FAT partition and a GPT disk image are created. For BIOS, the `llvm-objcopy` tool is used to convert the `bootloader` executable to a flat binary, as it already contains a basic MBR. |
157 | 46 |
|
158 | | -Where sdX is the device name of your USB stick. **Be careful** to choose the correct device name, because everything on that device is overwritten. |
| 47 | +### BIOS Assembly Stages |
159 | 48 |
|
160 | | -## Debugging |
161 | | -Set a breakpoint at address `0x7c00`. Disassemble instructions with gdb: |
162 | | -```bash |
163 | | -qemu-system-x86_64 -drive format=raw,file=target/x86_64-bootloader/release/bootloader.bin -s -S |
164 | | -``` |
165 | | -``` |
166 | | -(gdb) target remote: 1234 |
167 | | -(gdb) b *0x7c00 |
168 | | -(gdb) x/i $rip |
169 | | -``` |
| 49 | +When you press the power button the computer loads the BIOS from some flash memory stored on the motherboard. The BIOS initializes and self tests the hardware then loads the first 512 bytes into memory from the media device (i.e. the cdrom or floppy disk). If the last two bytes equal 0xAA55 then the BIOS will jump to location 0x7C00 effectively transferring control to the bootloader. |
170 | 50 |
|
171 | | -If you use the `-enable-kvm` flag you need to use hardware breakpoints `hb`. |
| 51 | +At this point the CPU is running in 16 bit mode, meaning only the 16 bit registers are available. Also since the BIOS only loads the first 512 bytes this means our bootloader code has to stay below that limit, otherwise we’ll hit uninitialised memory! Using [Bios interrupt calls](https://en.wikipedia.org/wiki/BIOS_interrupt_call) the bootloader prints debug information to the screen. |
172 | 52 |
|
173 | | -## Features |
174 | | -The bootloader crate can be configured through some cargo features: |
| 53 | +For more information on how to write a bootloader click [here](http://3zanders.co.uk/2017/10/13/writing-a-bootloader/). The assembler files get imported through the [global_asm feature](https://doc.rust-lang.org/unstable-book/library-features/global-asm.html). The assembler syntax definition used is the one llvm uses: [GNU Assembly](http://microelectronics.esa.int/erc32/doc/as.pdf). |
175 | 54 |
|
176 | | -- `vga_320x200`: This feature switches the VGA hardware to mode 0x13, a graphics mode with resolution 320x200 and 256 colors per pixel. The framebuffer is linear and lives at address `0xa0000`. |
177 | | -- `recursive_page_table`: Maps the level 4 page table recursively and adds the [`recursive_page_table_address`](https://docs.rs/bootloader/0.4.0/bootloader/bootinfo/struct.BootInfo.html#structfield.recursive_page_table_addr) field to the passed `BootInfo`. |
178 | | -- `map_physical_memory`: Maps the complete physical memory in the virtual address space and passes a [`physical_memory_offset`](https://docs.rs/bootloader/0.4.0/bootloader/bootinfo/struct.BootInfo.html#structfield.physical_memory_offset) field in the `BootInfo`. |
179 | | -- `sse` enables sse instruction support |
180 | | -- The virtual address where the physical memory should be mapped is configurable by setting the `physical-memory-offset` field in the kernel's `Cargo.toml`, as explained in [Configuration](#Configuration). |
| 55 | +The purposes of the individual assembly stages in this project are the following: |
181 | 56 |
|
| 57 | +- stage_1.s: This stage initializes the stack, enables the A20 line, loads the rest of the bootloader from disk, and jumps to stage_2. |
| 58 | +- stage_2.s: This stage sets the target operating mode, loads the kernel from disk,creates an e820 memory map, enters protected mode, and jumps to the third stage. |
| 59 | +- stage_3.s: This stage performs some checks on the CPU (cpuid, long mode), sets up an initial page table mapping (identity map the bootloader, map the P4 recursively, map the kernel blob to 4MB), enables paging, switches to long mode, and jumps to stage_4. |
182 | 60 |
|
183 | | -## Advanced Documentation |
184 | | -See these guides for advanced usage of this crate: |
| 61 | +## Future Plans |
185 | 62 |
|
186 | | -- [Chainloading](doc/chainloading.md) |
187 | | -- Higher Half Kernel - TODO |
| 63 | +- [ ] Allow to configure the desired screen resolution. Right now we just use the first available VESA screen mode on BIOS and the default GOP mode on UEFI. |
| 64 | +- [ ] Create a `multiboot2` compatible disk image in addition to the BIOS and UEFI disk images. This would make it possible to use it on top of the GRUB bootloader. |
| 65 | +- [ ] Rewrite most of the BIOS assembly stages in Rust. This has already started. |
| 66 | +- [ ] Instead of linking the kernel bytes directly with the bootloader, use a filesystem (e.g. FAT) and load the kernel as a separate file. |
| 67 | +- [ ] Stabilize the boot info format and make it possible to check the version at runtime. |
| 68 | +- [ ] Instead of searching the bootloader source in the cargo cache on building, use the upcoming ["artifact dependencies"](https://github.com/rust-lang/cargo/issues/9096) feature of cargo to download the builder binary separately. Requires doing a boot info version check on build time. |
| 69 | +- [ ] Transform this "Future Plans" list into issues and a roadmap. |
188 | 70 |
|
189 | 71 | ## License |
190 | 72 |
|
|
0 commit comments