Foundry-Boot/doc/boot_process.md

Boot Process and System Layout

Disk Layout

FAT32 Partition
┌─────────────────────────┐
│ /                       │
├─────────────────────────┤
│ ├── EFI/               │
│ │   └── BOOT/          │
│ │       └── BOOTX64.EFI│ <- UEFI bootloader
├─────────────────────────┤
│ ├── boot/              │
│ │   └── bootloader.bin │ <- BIOS bootloader
├─────────────────────────┤
│ └── kernel             │ <- Main kernel binary
└─────────────────────────┘

Kernel Binary Format

Kernel Header Structure
┌─────────────────────────┐
│ Magic Number (4 bytes)  │ 0x00
├─────────────────────────┤
│ Entry Point (8 bytes)   │ 0x04
├─────────────────────────┤
│ Stack Pointer (8 bytes) │ 0x0C
├─────────────────────────┤
│ Flags (4 bytes)         │ 0x14
├─────────────────────────┤
│ Text Offset (4 bytes)   │ 0x18
├─────────────────────────┤
│ Text Size (4 bytes)     │ 0x1C
├─────────────────────────┤
│ Data Offset (4 bytes)   │ 0x20
├─────────────────────────┤
│ Data Size (4 bytes)     │ 0x24
└─────────────────────────┘

Memory Layout (After Boot)

Virtual Memory Layout
┌─────────────────────┐ 0xFFFFFFFF_FFFFFFFF
│    Higher Half      │
├─────────────────────┤ 0xFFFFFFFF_FF600000
│     Recursive       │
│    Page Mapping     │
├─────────────────────┤ 0xFFFFFFFF_C0000000
│   Kernel Stacks     │
├─────────────────────┤ 
│   Kernel Heap       │
├─────────────────────┤ 0xFFFFFFFF_80000000
│   Kernel Code       │
├─────────────────────┤ 0x00007FFF_FFFFFFFF
│       Guard         │
├─────────────────────┤ 0x00007FFF_00000000
│    User Space       │
├─────────────────────┤ 0x0000000000400000
│       Guard         │
└─────────────────────┘ 0x0000000000000000

Physical Memory Layout
┌─────────────────────┐
│    Available RAM    │
├─────────────────────┤ 
│   Kernel Binary     │ <- Loaded at 1MB (0x100000)
├─────────────────────┤
│   Reserved/BIOS     │
└─────────────────────┘ 0x00000000

Boot Process

BIOS Boot Flow

1. BIOS loads MBR (stage1.bin)
2. Stage 1 bootloader:
   • Loads Stage 2 bootloader (stage2.bin) starting at sector 2048
3. Stage 2 bootloader:
   • Switches to protected mode
   • Sets up initial page tables
   • Finds and loads kernel from FAT32
   • Enables long mode
   • Jumps to kernel entry point

UEFI Boot Flow

1. UEFI firmware loads BOOTX64.EFI
2. UEFI bootloader:
   • Gets memory map
   • Finds and loads kernel
   • Exits boot services
   • Sets up page tables
   • Enables long mode
   • Jumps to kernel entry point

Kernel Entry Point

extern "C" {
   fn kmain(magic: u64, boot_info: *const BootInfo) -> !;
}

Common Boot Environment

Both bootloaders must provide:

CPU State

- Long mode enabled
- Paging enabled
- Interrupts disabled
- GDT set up for long mode
- IDT not required (kernel will set up)

Register State

RAX = Boot magic value (e.g., 0xCAFEBABE)
RBX = Pointer to boot info structure
RCX = 0
RDX = 0
RSI = 0
RDI = 0
RBP = 0
RSP = Valid stack pointer (as specified in kernel header)

Boot Info Structure

struct BootInfo {
    uint64_t magic;          // Boot info magic number
    uint64_t mem_map_addr;   // Physical address of memory map
    uint64_t mem_map_size;   // Size of memory map
    uint64_t fb_addr;        // Framebuffer address (if available)
    uint32_t fb_width;       // Framebuffer width
    uint32_t fb_height;      // Framebuffer height
    uint32_t fb_pitch;       // Framebuffer pitch
    uint8_t  fb_bpp;         // Bits per pixel
    uint8_t  boot_type;      // 0 = BIOS, 1 = UEFI
    uint8_t  reserved[6];    // Padding to 64-bit align
};

Required Kernel Features

1. Position-independent code (PIC)
2. No assumptions about physical memory layout beyond boot info
3. Own interrupt handling
4. Own memory management after boot

Development Notes

1. Kernel must be compiled with:

   • No red zone
   • No MMX/SSE initially
   • Position-independent code
   • No standard library dependencies

2. Testing can be done with:

   # BIOS boot
   qemu-system-x86_64 disk.img
   
   # UEFI boot
   qemu-system-x86_64 -bios /usr/share/OVMF/OVMF_CODE.fd disk.img