Module boot 

Bootloader-to-kernel handoff ABI (v2).

This module defines the data structures passed from the bootloader to the kernel at entry point. The kernel reads these structures to discover memory layout, ACPI tables, framebuffer configuration, and kernel modules.

Boot flow

UEFI/BIOS => bootloader => kernel_main(KernelArgs)

The bootloader populates KernelArgs in a reserved memory region, then jumps to the kernel entry point with a pointer to this structure in RDI (System V AMD64 ABI first argument).

ABI stability

The KernelArgs layout is frozen per ABI version. Changing the layout requires bumping STRAT9_BOOT_ABI_VERSION and updating both bootloader and kernel simultaneously.

Virtual memory layout (BOOTBOOT-inspired)

0xFFFF_DEAD_0000_0000  => Framebuffer (read-only after boot)
0xFFFF_BEEF_0000_0000  => Environment string (key=value)
0xFFFFFFFF_8000_0000  => Kernel code/data
0x0000_0000_0000_0000  => Identity map (first 4GB)

Example (kernel side)

unsafe fn kernel_main(args: *const KernelArgs) -> ! {
    let args = &*args;
    assert_eq!(args.magic, STRAT9_BOOT_MAGIC);
    assert_eq!(args.abi_version, STRAT9_BOOT_ABI_VERSION);

    // Memory map
    for region in unsafe { args.memory_regions() }.expect("invalid boot memory map") {
        match region.kind {
            MemoryKind::Free => { /* add to buddy allocator */ }
            _ => {}
        }
    }

    // Framebuffer (already mapped at 0xFFFF_DEAD_0000_0000)
    let fb = args.framebuffer_addr as *mut u32;

    // Environment (key=value pairs)
    if let Some(baud) = args.env_get("console.baud") {
        // baud = "115200"
    }

    // Modules
    for module in unsafe { args.modules() }.expect("invalid boot module table") {
        // module.name_str(), module.base, module.size
    }
}

Structs

KernelArgs

Bootloader-to-kernel handoff structure (ABI v2, 136 bytes).

MemoryKind

Memory region type identifier.

MemoryRegion

Memory region descriptor for the bootloader memory map.

ModuleEntry

A single loaded module (userspace binary or config file).

ModuleTable

Module table header + entries.

Constants

MAX_BOOT_MEMORY_REGIONS

Maximum number of descriptors accepted by the kernel’s boot-map work buffer.

MAX_BOOT_MODULES

Capacity of the fixed module table shared by the loader and kernel.

MODULE_TABLE_HEADER_SIZE 🔒

MODULE_TABLE_SIZE

STRAT9_BOOT_ABI_VERSION

ABI version for the boot handoff structure.

STRAT9_BOOT_MAGIC

Magic number validating the boot handoff ("ST9B" in ASCII).

Functions

checked_handoff_range 🔒

Pure metadata validation, performed before dereferencing a handoff address.

validate_module_name

Names shared by the ESP producer, loader and initfs consumer: 1..=63 ASCII letters/digits, ‘.’, ‘_’ or ‘-’. Reject path components and FAT-ambiguous dots.