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).
You need a nightly Rust compiler and cargo xbuild. You also need the llvm-tools-preview component, which can be installed through rustup component add llvm-tools-preview.
See our documentation.
This project consists of three separate entities:
builder binary to simplify the build process of the BIOS and UEFI binaries.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).
The build and boot process works the following way:
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.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.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.
llvm-tools rustup component should be installed. static or through a linker argument.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.bootloader_config.rs file in the cargo OUT_DIR. This file is then included by the UEFI/BIOS binaries.bin/uefi.rs or the bin/bios.rs:
bin/uefi.rs specifies an UEFI entry point function called efi_main. It uses the 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.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.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:
.bss sections, and allocating a stack with guard page. The relevant functions for these steps are set_up_mappings and load_kernel.BootInfo struct, which abstracts over the differences between BIOS and UEFI booting. This step is implemented in the create_boot_info function.switch_to_kernel and context_switch functions.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.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.
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 the bootloader prints debug information to the screen.
For more information on how to write a bootloader click here. The assembler files get imported through the global_asm feature. The assembler syntax definition used is the one llvm uses: GNU Assembly.
The purposes of the individual assembly stages in this project are the following:
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.Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.