rust-osdev/bootloader

If you are using UEFI booting in v0.11, you cannot use the legacy PIC for interrupt handling and must set up the APIC instead.

Basic workflow:

1. Locate the RSDP (ACPI structure) using the physical address provided in boot_info.rsdp_addr.
2. Use the acpi crate's AcpiTables::from_rsdp function to load ACPI tables.
3. Use the platform_info() method on the tables and read the interrupt_model field of the returned PlatformInfo to determine the system's interrupt controller requirements.
4. Parse and set up the local and IO APIC.

The bootloader project is composed of three main parts that work together to boot a kernel:

1. bootloader_api library: A library included by the kernel. It provides the entry_point! macro, which encodes configuration and metadata into a special ELF section of the kernel binary.
2. BIOS and UEFI binaries: The actual bootloader implementations. They share a common library and are responsible for loading the kernel from a FAT partition at runtime. They read the configuration from the special ELF section created by the bootloader_api.
3. bootloader library: The top-level crate used by the user (typically in a build.rs script). It builds the BIOS/UEFI implementations and provides functions like UefiBoot and BiosBoot to create FAT-formatted bootable disk images containing the kernel.

The bootloader v0.11 release has replaced the bootimage tool. Instead, the bootloader crate provides functions to create bootable disk images directly from your kernel.

Workflow:

1. Build your kernel using cargo build --target x86_64-unknown-none.
2. Invoke a builder function (in your own build script or tool) that calls the disk image creation functions provided by the bootloader crate.

The first stage bootsector must fit within a 512-byte limit. To build it, use cargo build with the specific stage-1 profile, enabling core via build-std, and targeting the i386-code16-boot-sector.json target. After building the ELF, use objcopy to convert it to a raw binary and write it to the disk image.

Note: This process requires a custom target JSON file located at ../../i386-code16-boot-sector.json.

When using v0.11, you should build your kernel using the x86_64-unknown-none target. This is a Tier-2 target, so you no longer need bootimage, cargo-xbuild, or xargo. You can use rustup to manage the target.

1. Add the target: rustup target add x86_64-unknown-none

2. Build the kernel: cargo build --target x86_64-unknown-none

In bootloader v0.11, optional features (like map-physical-memory) are no longer enabled via Cargo features. Instead, you configure them using a BootloaderConfig instance passed to the entry_point! macro.

To use a custom configuration, define a static BOOTLOADER_CONFIG and pass it as a config argument to the entry_point! macro.

use bootloader_api::config::{BootloaderConfig, Mapping};

pub static BOOTLOADER_CONFIG: BootloaderConfig = {
    let mut config = BootloaderConfig::new_default();
    config.mappings.physical_memory = Some(Mapping::Dynamic);
    config
};

// add a `config` argument to the `entry_point` macro call
entry_point!(kernel_main, config = &BOOTLOADER_CONFIG);

To implement the automated disk image creation workflow, your project must meet the following configuration requirements:

• Cargo.toml: Must include the kernel as a build-dependency and include bootloader as a build-dependency. If using UEFI booting in QEMU, include ovmf-prebuilt.
• .cargo/config.toml: Must enable the unstable artifact-dependencies feature.
• rust-toolchain.toml: Must set the default toolchain to nightly to support experimental features like artifact dependencies.
• build.rs: Should contain the logic to call bootloader functions to create both BIOS and UEFI disk images.
• src/main.rs: Should contain the logic to launch the resulting image using QEMU (e.g., via cargo run bios or cargo run uefi).

To use the bootloader crate, you need a nightly Rust compiler with the llvm-tools-preview component installed. You can install this component using rustup.

rustup component add llvm-tools-preview

Because the bootsector is strictly limited to 512 bytes, you can use objdump to inspect the disassembled ELF file to identify large sections and attempt to reduce the size.

objdump -xsdS -M i8086,intel ../../target/i386-code16-boot-sector/stage-1/bootloader-x86_64-bios-boot-sector