M1-16 Path B: BIOS real-mode I/O closes trampoline gap

[UnbreakableMJ]

Summary

• M1-16 Path B: every BIOS interrupt call now runs in real
  mode before CR0.PE. Protected-mode kmain consumes a
  BootDataBundle at phys 0x1000 and never returns to real
  mode. The legacy call_bios_int 32→real→32 trampoline that
  returned AH=0x01 is gated behind the legacy_trampoline
  Cargo feature for regression comparison.
• Re-enables bios-boot-smoke in the boot-smoke suite
  (deferred since db68d69 while M1-16 was incomplete). CI's
  qemu-smoke job now boots the real BIOS chain (stage1 MBR +
  stage2 + FAT32 partition) end-to-end and asserts the
  ZAMAK / LIMINE_PROTOCOL_OK serial sentinels alongside
  the existing UEFI case.
• Closes the last `[~]` `boot-smoke` item in `TODO.md`
  (`155 → 156` done; `3 → 2` partial). Deletes the working
  design doc `M1-16-PATH-B.md`.

Known follow-up: `zamak_core::config::parse` infinite-loops
in the Path B i686 codegen even with the memset/memcpy
intrinsics fixed. Until that's diagnosed the BIOS path uses
a hard-coded `/kernel.elf` entry (TODO in `kmain`); UEFI is
unaffected.

Test plan

• `qemu-smoke` CI job: `bios-boot-smoke` PASSes (new) and
  `uefi-boot-smoke` still PASSes.
• `qemu-smoke` CI job: `asm-wrapper-state-check` +
  `uefi-linux-boot` still PASS (regression canaries).
• `clippy` job clean against both default and
  `--features legacy_trampoline`.
• `fmt` job clean.
• `cargo test -p zamak-core` clean — new
  `ram_fat32::tests` 9 cases plus the existing 221.
• `deny` / `audit` jobs clean.
• `cross` job: AArch64 / RISC-V / LoongArch builds still
  clean.

Locally verified: all four QEMU cases PASS under QEMU 9.x in
a `nix-shell -p gcc -p mtools -p util-linux -p binutils -p
qemu -p OVMF` environment.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added FAT32 filesystem walker (zamak-core::ram_fat32) with long-filename support

• Bug Fixes

  • Fixed BIOS memory operations to eliminate recursive calls
  • Fixed HHDM paging sizing to properly handle non-usable memory entries and cap at 16 GiB

• Tests

  • Re-enabled BIOS boot end-to-end smoke testing

• Chores

  • Introduced optional legacy_trampoline feature for backward compatibility
  • Restructured BIOS boot flow with improved BootDataBundle handoff to kernel

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This pull request implements the M1-16 Path B BIOS restructuring, transitioning the boot flow to perform all BIOS I/O entirely in real mode before entering protected mode, with results passed to kmain via a BootDataBundle at fixed physical address 0x1000. Includes new real-mode orchestration routines, FAT32 filesystem walker, and inline-assembly memory utilities. Legacy trampoline now gated by optional legacy_trampoline feature.

Changes

Cohort / File(s)	Summary
Documentation CHANGELOG.md, TODO.md, M1-16-PATH-B.md	Recorded completion of M1-16 Path B BIOS restructuring, updated test coverage status, and deleted the now-implemented design document.
Build Configuration zamak-bios/Cargo.toml	Added optional legacy_trampoline Cargo feature to conditionally include legacy BIOS trampoline code.
Boot Data Structure zamak-bios/src/boot_bundle.rs	New ABI-focused module defining BootDataBundle layout at physical 0x1000 with packed E820Entry, VbeModeInfo, and bundle structs, plus unsafe accessors and compile-time layout assertions.
Real-Mode BIOS Orchestration zamak-bios/src/rm_io.rs	New 1000+ line module embedding 16-bit assembly wrappers for BIOS interrupts (INT 13h extended disk read, INT 15h E820 enumeration, INT 10h VBE modes), unreal-mode transitions, and phase B orchestration that populates BootDataBundle at 0x1000.
Boot Entry Point zamak-bios/src/entry.rs	Refactored to call real-mode rm_phaseb_orchestrate before entering protected mode; kmain now receives BootDataBundle physical address instead of boot drive ID; legacy call_bios_int trampoline moved to conditional legacy_trampoline feature block.
Kernel Entry Logic zamak-bios/src/main.rs	New non-legacy kmain(bundle_phys: u32) path consuming BootDataBundle, performing E820→Limine conversion, mounting FAT32, loading kernel ELF via custom minimal parser, fulfilling Limine requests, setting up paging, and jumping to long mode. Conditional compilation gates legacy trampoline dependencies (disk, mmap, vbe, fat32, input).
FAT32 Filesystem Walker zamak-core/src/ram_fat32.rs	New borrowed-slice FAT32 parser supporting directory traversal, VFAT long-filename reconstruction with case-insensitive matching, and cluster-chain file reads, with synthesized test images validating parsing and edge cases.
Shared Data Structures zamak-bios/src/mmap.rs, zamak-bios/src/vbe.rs	Refactored to import E820Entry and VbeModeInfo from crate::boot_bundle instead of local definitions, eliminating duplication and ensuring consistent packed layout across boot phases.
Memory Utilities zamak-bios/src/utils.rs	Replaced Rust pointer-based memset/memcpy/memmove with explicit inline rep assembly instructions to avoid recursive self-calls; updated memcmp to indexed loop to prevent libcall lowering.
Paging Setup zamak-bios/src/paging.rs	Fixed HHDM sizing to derive limit from highest usable E820 entries only (ignoring reserved/ACPI/MMIO) and capped at new HHDM_MAX_BYTES (16 GiB) to constrain page-table allocation.
FAT32 Cleanup zamak-bios/src/fat32.rs	Removed extraneous whitespace in Fat32::parse.
Module Exports zamak-bios/src/main.rs, zamak-core/src/lib.rs	Added pub mod boot_bundle and pub mod rm_io to BIOS exports; added pub mod ram_fat32 to core exports; added conditional feature-gated module declarations.
CI Test Activation zamak-test/src/main.rs	Re-enabled bios-boot-smoke end-to-end test case, validating BIOS boot chain against same serial sentinel patterns (ZAMAK, LIMINE_PROTOCOL_OK) as UEFI path.

Sequence Diagram(s)

sequenceDiagram
    participant RM as Real Mode
    participant BIOS as BIOS Interrupts
    participant BD as BootDataBundle<br/>(0x1000)
    participant MEM as System Memory<br/>(E820)
    participant DISK as Disk Controller
    
    RM->>RM: _start: preserve boot drive<br/>enable interrupts
    RM->>RM: Call rm_phaseb_orchestrate
    
    RM->>BIOS: INT 15h AX=E820h<br/>(enumerate memory)
    BIOS-->>RM: E820 entries
    RM->>BD: Store E820 table
    
    RM->>DISK: INT 13h AH=42h<br/>(read MBR)
    DISK-->>RM: MBR sector
    RM->>RM: Scan partition table<br/>for FAT32/Linux
    
    RM->>RM: Enter unreal mode<br/>(flat addressing)
    RM->>DISK: INT 13h AH=42h<br/>(chunk reads)
    DISK-->>RM: Kernel partition image
    RM->>MEM: Copy to high memory<br/>(via rm_memcpy_to_high)
    
    RM->>BIOS: INT 15h AX=E820h<br/>(scan for RSDP)
    RM->>BD: Store RSDP pointer
    
    RM->>BD: Stamp ZBDL_MAGIC last
    RM->>RM: Disable interrupts<br/>Enter protected mode
    RM-->>RM: Return (0x1000 ready)

Loading

sequenceDiagram
    participant PM as Protected Mode
    participant Bundle as BootDataBundle<br/>(0x1000)
    participant FS as FAT32 Walker<br/>(ram_fat32)
    participant ELF as ELF Loader
    participant MM as Paging System
    participant LM as Long Mode
    
    PM->>PM: init_32: set stack (0x8000)<br/>call kmain(bundle_phys=0x1000)
    PM->>Bundle: Read BootDataBundle
    Bundle-->>PM: E820 entries, boot drive,<br/>kernel partition loaded
    
    PM->>FS: Parse FAT32 boot sector<br/>(from loaded partition)
    FS-->>PM: FAT32 metadata
    PM->>FS: find_path("/kernel.elf")
    FS-->>PM: Directory entry facts
    PM->>FS: read_file() into fixed window<br/>(0x2000000)
    FS-->>PM: Kernel ELF buffer
    
    PM->>ELF: Parse ELF64 header
    ELF-->>PM: PT_LOAD segments
    PM->>ELF: Copy segments to load window
    ELF-->>PM: Kernel image ready
    
    PM->>PM: Scan ELF for Limine requests
    PM->>MM: Fulfill Limine requests<br/>(memory map, framebuffer, etc.)
    PM->>MM: Build identity/HHDM paging
    MM-->>PM: Page tables set
    
    PM->>PM: Store long-mode entry (0x5FF0)
    PM->>LM: Call enter_long_mode
    LM-->>PM: init_64 (64-bit kernel exec)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 Huzzah! The Path B bunny hops,
Real-mode BIOS never stops,
Boot data bundled, 0x1000 deep,
FAT32 walks where clusters leap,
No trampoline—just pure, swift flow! 🎯

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: implementing M1-16 Path B architecture where BIOS real-mode I/O runs before protected mode, closing the gap left by the legacy trampoline.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch m1-16-path-b

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}