debug(bios): instrument kmain + disk; isolates hang to trampoline

M1-16 progress — the BIOS boot chain is now diagnosed all the way
to the real culprit.

Observed serial output (`qemu-system-x86_64 -serial file:…`):

    ZAMAK Stage 1
    DL=80
    Loading Stage 2...
    ZPMD[]!01

Decoding the checkpoints (each byte is one `outb 0x3F8`):
  Z = zamak-bios real-mode entry reached
  P = 16→32-bit protected-mode switch succeeded
  M = kmain entered
  D = Disk::new returned
  [ = call_bios_int dispatched
  ] = call_bios_int returned
  ! = BIOS signaled non-zero AH
  01 = hex(AH) = 0x01 ("invalid function")

Same `INT 13h AH=0x42` (Extended Read) succeeds when issued from
stage1 directly in real mode, so the 32→real→32 trampoline in
`zamak-bios/src/entry.rs::call_bios_int` is leaving BIOS state
corrupted (IVT/A20/PIC/GDT/segment-descriptor-cache restore is
likely the culprit). Debugging the ~40-instruction trampoline is
non-trivial; see TODO.md for the two proposed paths forward.

Changes in this commit:

- `zamak-bios/src/main.rs`: added `mark(b: u8)` helper that
  `outb`s a single byte to COM1 — a lightweight breadcrumb that
  works in both real and protected mode without allocator or
  panic-path involvement. Sprinkled markers through `kmain`:
  entry (`M`), post-`Disk::new` (`D`), post-MBR-read (`m`),
  post-partition-scan (`P`), pre-FS-probe (`F`), post-mount
  (`f`), post-config-parse (`C`).

- `zamak-bios/src/main.rs`: kmain now reads sector 0, parses the
  MBR partition table (types 0x01/04/06/0B/0C/83), and passes
  the partition's starting LBA to `Fat32::parse` / `Ext2::mount`
  instead of hard-coding LBA 0. The disk image built by
  `build-images.sh` puts the FAT32 partition at LBA 4096 behind
  the sfdisk-written partition entry, so this fixes "wrong LBA"
  as a confounding variable.

- `zamak-bios/src/disk.rs`: `read_sectors_internal` emits `[` /
  `]` around the `call_bios_int`, `.` on success, `!` + two
  hex digits on BIOS error. Only visible during manual M1-16
  bring-up (the test harness doesn't consume them).

- `TODO.md`: M1-16 note updated with the current symptom and
  the two paths forward (debug trampoline vs. do all BIOS I/O
  before leaving real mode, Limine-style).

Not affected: UEFI boot-smoke + asm-verification stay `[PASS]`
locally; clippy + fmt + the full workspace build remain clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

TODO.md

@@ -115,7 +115,7 @@ SPDX-FileCopyrightText: 2026 Mohamed Hammad
 | M1-13 | `[✓]` | KASLR: RDSEED → RDRAND → RDTSC fallback chain in `X86KaslrRng` with CPUID detection (§FR-MM-003) |
 | M1-14 | `[✓]` | BLAKE2B hash implementation in `zamak-core::blake2b` (pure `no_std`, RFC 7693) for `#hash` URI suffix (§FR-CFG-003) |
 | M1-15 | `[✓]` | ISO 9660 filesystem driver (`zamak-core::iso9660`) — read-only, supports path traversal, ECMA-119 |
-| M1-16 | `[~]` | End-to-end BIOS Limine-Protocol kernel boot under QEMU. UEFI case `[✓]`. BIOS chain runs through `_start → protected mode → kmain entry` under QEMU: (a) `build-images.sh` builds real MBR + stage2 + FAT32-partition disk at `target/zamak-bios.img`; (b) `zamak-stage1` writes progress to COM1 (0x3F8) directly (BIOS teletype doesn't route to serial in headless QEMU) and does extended-INT-13h in 64-sector chunks so `zamak-bios` > 32 KiB doesn't blow the 64 KiB segment boundary; (c) `zamak-bios` prints `Z` on real-mode entry and `P` after the 16→32 mode switch; (d) `smp`/`trampoline` modules feature-gated off (AP trampoline needs position-independent rewrite — separate scope). Current hang is inside `kmain()` — likely in the `call_bios_int` 32→real→32 round-trip or the FAT32/partition-table reads. Next step for whoever picks it up: add serial `outb 0x3F8` after every major kmain step (E820 fetch, disk init, partition probe, FAT32 mount, config read, kernel load, long-mode handoff) and iterate. `bios-boot-smoke` remains removed from the `boot-smoke` suite until kmain reaches kernel handoff. |
+| M1-16 | `[~]` | End-to-end BIOS Limine-Protocol kernel boot under QEMU. UEFI case `[✓]`. BIOS chain diagnosed all the way to the `call_bios_int` 32→real→32 trampoline. Observed serial: `ZAMAK Stage 1 / DL=80 / Loading Stage 2... / ZPMD[]!01`. Meaning: stage1 + stage2 + mode switch + `kmain` entry + `Disk::new` all work; the first `INT 13h AH=0x42` dispatched through the protected-mode-round-trip trampoline returns `AH=0x01` ("invalid function"). Same call issued **directly in real mode from stage1** succeeds, so the trampoline is leaving BIOS state wrong (likely IVT/A20/PIC/GDT not fully restored after the 32→real switch). Two paths forward for whoever picks this up: (A) debug the existing `zamak-bios/src/entry.rs` `call_bios_int` asm (non-trivial — ~40-instruction mode-transition block with CR0/segment/stack gymnastics), or (B) re-architect `zamak-bios` to do all BIOS I/O while still in real mode before the `ljmp 0x08, init_32` — simpler and matches how Limine's own stage3 does it. Build tooling (`build-images.sh`), stage1 multi-chunk INT 13h, MBR partition-table scan, and serial instrumentation are all in place. `bios-boot-smoke` remains removed from the suite until `call_bios_int` works or is refactored away. |
 
 ---
 

zamak-bios/src/disk.rs

@@ -93,6 +93,10 @@ impl Disk {
         regs.edx = self.drive_id as u32;
         regs.esi = DAP_ADDR; // DS:SI -> DAP.
 
+        // Serial breadcrumbs: '[' before the 32→real→32 mode round-trip,
+        // ']' after. If we see '[' but not ']' during M1-16 bring-up the
+        // `call_bios_int` trampoline is the culprit.
+        crate::mark(b'[');
         // SAFETY:
         //   Preconditions: DAP at 0x6000 is valid; drive_id is the BIOS boot drive
         //   Postconditions: sectors read to buffer_addr; regs updated with status
@@ -101,11 +105,19 @@ impl Disk {
         unsafe {
             call_bios_int(0x13, &mut regs);
         }
-
-        if (regs.eax >> 8) & 0xFF != 0 {
-            return Err((regs.eax >> 8) as u8);
+        crate::mark(b']');
+        let ah = ((regs.eax >> 8) & 0xFF) as u8;
+        if ah != 0 {
+            // Emit two hex digits of AH to serial so the bring-up log
+            // shows which BIOS error fired instead of a silent panic.
+            let hi = ah >> 4;
+            let lo = ah & 0x0F;
+            crate::mark(b'!');
+            crate::mark(if hi < 10 { b'0' + hi } else { b'A' + (hi - 10) });
+            crate::mark(if lo < 10 { b'0' + lo } else { b'A' + (lo - 10) });
+            return Err(ah);
         }
-
+        crate::mark(b'.'); // successful read
         Ok(())
     }
 }

zamak-bios/src/main.rs

@@ -187,13 +187,69 @@ fn fulfill_requests(
 use zamak_core::arch::x86 as arch;
 use zamak_core::rng::{KaslrRng, X86KaslrRng};
 
+/// Writes a single ASCII byte to COM1 (0x3F8). Used as a boot-progress
+/// checkpoint marker — the test harness doesn't consume these, they're
+/// for humans reading QEMU serial logs during M1-16 bring-up.
+#[inline(always)]
+fn mark(b: u8) {
+    // SAFETY:
+    //   Preconditions: COM1 (0x3F8) exists in every QEMU PC machine.
+    //   Postconditions: byte appears on -serial stdio output.
+    //   Clobbers: DX, AL (temps).
+    //   Worst-case: spurious byte appears on serial.
+    unsafe {
+        core::arch::asm!(
+            "mov dx, 0x3F8",
+            "out dx, al",
+            in("al") b,
+            out("dx") _,
+            options(nostack, nomem, preserves_flags),
+        );
+    }
+}
+
 #[no_mangle]
 pub extern "C" fn kmain(drive_id: u8) -> ! {
+    mark(b'M'); // kmain entry
+
     // 2. Initialize Disk
     let mut disk = Disk::new(drive_id);
     let mut disk_ext2 = disk.clone();
+    mark(b'D'); // Disk::new returned
+
+    // 3. Read the MBR partition table to find a FAT32 / EXT2 partition.
+    //    An unpartitioned disk would have the filesystem at LBA 0, but
+    //    `zamak-test/build-images.sh` stamps a proper MBR partition
+    //    table via `sfdisk`, so we follow that pointer.
+    use zamak_core::fs::BlockDevice;
+    let mut mbr_buf = [0u8; 512];
+    BlockDevice::read_sectors(&disk, 0, 1, &mut mbr_buf).expect("Failed to read MBR sector");
+    mark(b'm'); // MBR read
+    let mut part_lba: u64 = 0;
+    for i in 0..4 {
+        let base = 446 + i * 16;
+        let type_byte = mbr_buf[base + 4];
+        // 0x01=FAT12, 0x04=FAT16<32MB, 0x06=FAT16, 0x0B=FAT32/CHS,
+        // 0x0C=FAT32/LBA, 0x83=Linux (EXT*).
+        if matches!(type_byte, 0x01 | 0x04 | 0x06 | 0x0B | 0x0C | 0x83) {
+            let lba = u32::from_le_bytes([
+                mbr_buf[base + 8],
+                mbr_buf[base + 9],
+                mbr_buf[base + 10],
+                mbr_buf[base + 11],
+            ]);
+            if lba != 0 {
+                part_lba = lba as u64;
+                break;
+            }
+        }
+    }
+    if part_lba == 0 {
+        panic!("No FAT32/EXT2 partition entry in MBR");
+    }
+    mark(b'P'); // Partition LBA resolved
 
-    // 3. Mount Filesystem
+    // 4. Mount Filesystem
     // We try FAT32 first, then EXT2
     use crate::fat32::Fat32;
     use zamak_core::ext2::Ext2;
@@ -202,16 +258,18 @@ pub extern "C" fn kmain(drive_id: u8) -> ! {
     let mut fs_fat: Option<Fat32> = None;
     let mut fs_ext2: Option<Ext2> = None;
 
-    // Probe FAT32
-    if let Ok(f) = Fat32::parse(&mut disk, 0) {
+    mark(b'F'); // About to probe filesystems
+                // Probe FAT32
+    if let Ok(f) = Fat32::parse(&mut disk, part_lba) {
         fs_fat = Some(f);
     }
     // If not FAT32, probe EXT2
-    else if let Ok(f) = Ext2::mount(&mut disk_ext2, 0) {
+    else if let Ok(f) = Ext2::mount(&mut disk_ext2, part_lba) {
         fs_ext2 = Some(f);
     } else {
         panic!("No supported filesystem found on boot partition");
     }
+    mark(b'f'); // Filesystem mounted
 
     let fs: &dyn FileSystem = if let Some(ref f) = fs_fat {
         f
@@ -229,6 +287,7 @@ pub extern "C" fn kmain(drive_id: u8) -> ! {
     // Simple parser
     let config_str = core::str::from_utf8(&config_file_buf[..config_size]).unwrap_or("");
     let config = zamak_core::config::parse(config_str);
+    mark(b'C'); // Config parsed
 
     // 4. Initialize Graphics (VBE) for TUI
     let mut fb_opt = vbe::find_and_set_vbe_mode(1024, 768, 32);