Spacecraft-Software
diff --git a/‎.forgejo/workflows/ci.yml‎
Lines changed: 5 additions & 0 deletions b/‎.forgejo/workflows/ci.yml‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 5 additions & 0 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 23 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 23 additions & 0 deletions
diff --git a/‎Cargo.toml‎
Lines changed: 6 additions & 4 deletions b/‎Cargo.toml‎
Lines changed: 6 additions & 4 deletions
diff --git a/‎TODO.md‎
Lines changed: 5 additions & 5 deletions b/‎TODO.md‎
Lines changed: 5 additions & 5 deletions
diff --git a/‎zamak-core/src/linux_boot.rs‎
Lines changed: 227 additions & 0 deletions b/‎zamak-core/src/linux_boot.rs‎
Lines changed: 227 additions & 0 deletions
diff --git a/‎zamak-linux-stub-kernel/.cargo/config.toml‎
Lines changed: 17 additions & 0 deletions b/‎zamak-linux-stub-kernel/.cargo/config.toml‎
Lines changed: 17 additions & 0 deletions
diff --git a/‎zamak-linux-stub-kernel/Cargo.lock‎
Lines changed: 7 additions & 0 deletions b/‎zamak-linux-stub-kernel/Cargo.lock‎
Lines changed: 7 additions & 0 deletions
@@ -205,6 +205,11 @@ jobs:
           ZAMAK_UEFI_ESP: target/esp.img
           OVMF_DIR: /usr/share/OVMF
         run: cargo run -p zamak-test -- --suite boot-smoke --timeout 60
+      - name: run linux-bzimage suite under QEMU
+        env:
+          ZAMAK_LINUX_ESP: target/linux-esp.img
+          OVMF_DIR: /usr/share/OVMF
+        run: cargo run -p zamak-test -- --suite linux-bzimage --timeout 60
 
   sbom:
     runs-on: ubuntu-latest
 
@@ -205,6 +205,11 @@ jobs:
           ZAMAK_UEFI_ESP: target/esp.img
           OVMF_DIR: /usr/share/OVMF
         run: cargo run -p zamak-test -- --suite boot-smoke --timeout 60
+      - name: run linux-bzimage suite under QEMU
+        env:
+          ZAMAK_LINUX_ESP: target/linux-esp.img
+          OVMF_DIR: /usr/share/OVMF
+        run: cargo run -p zamak-test -- --suite linux-bzimage --timeout 60
 
   sbom:
     runs-on: ubuntu-latest
 
@@ -12,6 +12,29 @@ All dates use ISO 8601 format (YYYY-MM-DD).
 
 ## [Unreleased]
 
+### Added
+
+- **M2-12 done** — end-to-end Linux bzImage boot smoke under QEMU
+  UEFI. New `zamak-linux-stub-kernel` freestanding crate emits a
+  spec-compliant protocol-2.15 bzImage (`HdrS` magic at 0x202,
+  `setup_sects = 1`, 64-bit entry at `load_addr + 0x200`) whose
+  kernel body prints `Linux version 0.0.0-zamak-stub` on COM1 and
+  exits via `isa-debug-exit`. `zamak-core::linux_boot` gains
+  `prepare_linux_boot()` — an orchestrator that walks
+  `SetupHeader` + allocates BootParams + populates E820 from a
+  caller-supplied `[MemoryRegion]`. `zamak-uefi` now dispatches
+  on `entry.protocol`: `"linux"` routes through a new
+  `load_linux_kernel()` that converts the UEFI memory map to E820,
+  allocates stable physical pages for kernel body + cmdline +
+  optional initrd + BootParams zero page, then hands off via
+  `handoff::jump_to_linux_kernel` (new) which sets RSI and does
+  a bare `jmp entry` without installing a ZAMAK PML4 (Linux uses
+  UEFI's identity map and sets up its own paging). `build-images.sh`
+  assembles `target/linux-esp.img` with the stub and a
+  `PROTOCOL=linux` config; CI's `qemu-smoke` job runs the new
+  `linux-bzimage` suite alongside `boot-smoke` and
+  `asm-verification`, all three green.
+
 ## [0.8.3] - 2026-04-24
 
 Third release-workflow patch. v0.8.2 produced 6/9 expected assets
 
@@ -13,11 +13,13 @@ members = [
     "zamak-test",
     "zamak-macros",
 ]
-# zamak-test-kernel is excluded from the workspace so its own
-# .cargo/config.toml (with `build-std`) can apply without the workspace's
-# stable-toolchain alias interfering. Build it explicitly with:
+# zamak-test-kernel + zamak-linux-stub-kernel are excluded from the
+# workspace so their own `.cargo/config.toml` (with `build-std`) can
+# apply without the workspace's stable-toolchain alias interfering.
+# Build them explicitly with:
 #     cargo +nightly build --manifest-path zamak-test-kernel/Cargo.toml --release
-exclude = ["zamak-test-kernel"]
+#     cargo +nightly build --manifest-path zamak-linux-stub-kernel/Cargo.toml --release
+exclude = ["zamak-test-kernel", "zamak-linux-stub-kernel"]
 resolver = "2"
 
 [profile.dev]
 
@@ -134,7 +134,7 @@ SPDX-FileCopyrightText: 2026 Mohamed Hammad
 | M2-9 | `[✓]` | VMM / HHDM mapping — full HHDM covering all physical memory via E820/UEFI memory map (§FR-MM-002) |
 | M2-10 | `[✓]` | `ExitBootServices()` retry logic — handled by `uefi` crate v0.24 internally (§6.2) |
 | M2-11 | `[✓]` | Linux Boot Protocol support — x86 bzImage setup header parsing, BootParams zero page, E820 population (§FR-PROTO-002) |
-| M2-12 | `[~]` | End-to-end Linux bzImage boot under QEMU UEFI — `linux-bzimage` suite + `ZAMAK_LINUX_ESP` env in `zamak-test`; awaits real bzImage + UEFI initrd in CI |
+| M2-12 | `[✓]` | End-to-end Linux bzImage boot under QEMU UEFI — new `zamak-linux-stub-kernel` crate produces a spec-compliant protocol-2.15 bzImage blob; `zamak-uefi` dispatches on `PROTOCOL=linux`, populates BootParams + E820 from UEFI mmap, jumps via a Linux-specific handoff that sets RSI pre-`jmp`. `cargo run -p zamak-test -- --suite linux-bzimage` prints `[PASS] uefi-linux-boot` locally and in CI. Real Linux kernel coverage is a future `linux-full-boot` suite. |
 | M2-13 | `[✓]` | Build and produce `BOOTX64.EFI` release artifact (`Makefile.uefi` with ESP image + QEMU target) |
 
 ---
@@ -306,7 +306,7 @@ SPDX-FileCopyrightText: 2026 Mohamed Hammad
 | Rust Guidelines | 5 | 0 | 0 |
 | POSIX | 2 | 0 | 0 |
 | M1 BIOS Boot | 15 | 1 | 0 |
-| M2 UEFI Boot | 12 | 1 | 0 |
+| M2 UEFI Boot | 13 | 0 | 0 |
 | M3 Config/Menu/Theme | 15 | 0 | 0 |
 | M4 Multi-arch | 7 | 1 | 0 |
 | M5 Feature Parity | 9 | 0 | 0 |
@@ -316,10 +316,10 @@ SPDX-FileCopyrightText: 2026 Mohamed Hammad
 | Testing | 7 | 0 | 0 |
 | CI/CD | 12 | 0 | 0 |
 | Release Artifacts | 10 | 0 | 0 |
-| **Total** | **154** | **4** | **0** |
+| **Total** | **155** | **3** | **0** |
 
-**No items are fully not-started.** The 4 remaining `[~]` items are:
+**No items are fully not-started.** The 3 remaining `[~]` items are:
 
-- **CI artifact confirmation** (2 items): `bios-boot-smoke` on `zamak-test-kernel` (M1-16) — needs real stage1 MBR chain; Linux bzImage UEFI smoke (M2-12) — needs a real bzImage committed or synthesized by CI. TEST-4 and TEST-5 are now `[✓]` for the UEFI x86-64 path.
+- **CI artifact confirmation** (1 item): `bios-boot-smoke` on `zamak-test-kernel` (M1-16) — needs the `call_bios_int` trampoline fix or real-mode I/O refactor. M2-12 now satisfied via the `zamak-linux-stub-kernel` synthetic bzImage; TEST-4 and TEST-5 are `[✓]` for the UEFI x86-64 path.
 - **LoongArch UEFI target** (M6-1): blocked on rustc upstream — `loongarch64-unknown-uefi` target does not yet exist, and `uefi-services`' `efiapi` ABI is unsupported on `loongarch64-unknown-none`. Paging builder + handoff code are implemented and compile for the bare-metal target; flips to `[✓]` when rustc lands the UEFI triple.
 - **Real hardware perf baseline** (M6-3): cold-boot timing requires bare-metal measurement on reference hardware.
@@ -44,6 +44,16 @@ pub enum LinuxBootError {
     InvalidSetupSects,
     /// The protected-mode kernel is empty.
     EmptyKernel,
+    /// Kernel load physical address doesn't fit in the `code32_start`
+    /// 32-bit field (> 4 GiB).
+    KernelLoadAddrOverflow,
+    /// Command-line physical address doesn't fit in `cmd_line_ptr`
+    /// (> 4 GiB).
+    CmdlineAddrOverflow,
+    /// Initramfs physical address doesn't fit in `ramdisk_image`
+    /// (> 4 GiB). Protocol 2.15 only widens this to 64 bits via
+    /// `ext_ramdisk_image`; stick to < 4 GiB until we wire it up.
+    InitrdAddrOverflow,
 }
 
 impl fmt::Display for LinuxBootError {
@@ -56,6 +66,11 @@ impl fmt::Display for LinuxBootError {
             }
             Self::InvalidSetupSects => write!(f, "setup_sects is zero"),
             Self::EmptyKernel => write!(f, "protected-mode kernel payload is empty"),
+            Self::KernelLoadAddrOverflow => {
+                write!(f, "kernel load address > 4 GiB")
+            }
+            Self::CmdlineAddrOverflow => write!(f, "cmdline address > 4 GiB"),
+            Self::InitrdAddrOverflow => write!(f, "initrd address > 4 GiB"),
         }
     }
 }
@@ -346,6 +361,116 @@ impl BootParams {
     }
 }
 
+/// Returned by [`prepare_linux_boot`]: a fully-populated
+/// `BootParams` zero page plus the 64-bit entry point the
+/// caller should jump to after ExitBootServices.
+pub struct LinuxBootImage {
+    /// Zero page to pass to the kernel (RSI at handoff).
+    pub boot_params: BootParams,
+    /// Physical address of the 64-bit kernel entry.
+    /// Always `kernel_load_phys + 0x200` per protocol 2.12+.
+    pub entry_point: u64,
+}
+
+impl fmt::Debug for LinuxBootImage {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        // BootParams is a 4 KiB blob; dumping its bytes is not
+        // useful in logs. Print just the entry point and let the
+        // struct name convey the rest.
+        f.debug_struct("LinuxBootImage")
+            .field("entry_point", &format_args!("{:#x}", self.entry_point))
+            .field("boot_params", &"<BootParams 4096-byte zero page>")
+            .finish()
+    }
+}
+
+/// One memory-map region in E820 terms. The caller translates
+/// its firmware memory map (UEFI GetMemoryMap, BIOS INT 15h E820,
+/// …) into a slice of these for [`prepare_linux_boot`].
+///
+/// E820 types follow the de-facto convention:
+/// `1 = usable`, `2 = reserved`, `3 = ACPI reclaimable`,
+/// `4 = ACPI NVS`, `5 = unusable`, `7 = persistent memory`.
+#[derive(Debug, Clone, Copy)]
+pub struct MemoryRegion {
+    pub base: u64,
+    pub length: u64,
+    pub typ: u32,
+}
+
+/// End-to-end preparation of a Linux 64-bit handoff.
+///
+/// The caller is expected to have already:
+///   * Read the bzImage into `bzimage: &[u8]`.
+///   * Allocated `kernel_size(&hdr, bzimage.len())` bytes of
+///     physical memory at `kernel_load_phys` (2-MiB-aligned when
+///     the kernel is relocatable, else at the returned
+///     `kernel_load_address(&hdr)`) and copied the kernel body
+///     (`bzimage[setup_size..]`) into it.
+///   * Allocated a writable page for the command line at
+///     `cmdline_phys` and stored an (optionally NUL-terminated)
+///     copy of `entry.cmdline`.
+///   * Allocated pages for an initramfs at `initrd.0` of length
+///     `initrd.1` bytes (or passed `None`).
+///   * Produced a firmware memory map as `memory_map`.
+///
+/// Returns a `LinuxBootImage` holding the fully-populated
+/// `BootParams` zero page and the 64-bit entry physical address.
+/// Call [`crate::arch`]-agnostic handoff code (e.g.
+/// `zamak-uefi::handoff::jump_to_linux_kernel`) with
+/// `image.boot_params.as_ptr() as u64` in RSI and
+/// `image.entry_point` in RIP.
+pub fn prepare_linux_boot(
+    bzimage: &[u8],
+    kernel_load_phys: u64,
+    cmdline_phys: u64,
+    initrd: Option<(u64, u32)>,
+    memory_map: &[MemoryRegion],
+) -> Result<LinuxBootImage, LinuxBootError> {
+    let header = parse_setup_header(bzimage)?;
+
+    let mut boot_params = BootParams::zeroed();
+    boot_params.populate_from_bzimage(bzimage, &header);
+
+    // Record where we actually loaded the kernel — the kernel
+    // uses this as its effective `code32_start` post-relocation.
+    let load_phys_u32: u32 = kernel_load_phys
+        .try_into()
+        .map_err(|_| LinuxBootError::KernelLoadAddrOverflow)?;
+    boot_params.set_code32_start(load_phys_u32);
+
+    let cmdline_phys_u32: u32 = cmdline_phys
+        .try_into()
+        .map_err(|_| LinuxBootError::CmdlineAddrOverflow)?;
+    boot_params.set_cmdline(cmdline_phys_u32);
+
+    if let Some((initrd_phys, initrd_size)) = initrd {
+        let initrd_phys_u32: u32 = initrd_phys
+            .try_into()
+            .map_err(|_| LinuxBootError::InitrdAddrOverflow)?;
+        boot_params.set_initrd(initrd_phys_u32, initrd_size);
+    }
+
+    for region in memory_map {
+        // Silently drop once the 128-entry table is full — the
+        // kernel tolerates a short E820, it just sees less RAM.
+        if !boot_params.add_e820_entry(region.base, region.length, region.typ) {
+            break;
+        }
+    }
+
+    // 64-bit entry is always 0x200 past the kernel's load
+    // physical base (Linux boot protocol 2.12+).
+    let entry_point = kernel_load_phys
+        .checked_add(0x200)
+        .ok_or(LinuxBootError::KernelLoadAddrOverflow)?;
+
+    Ok(LinuxBootImage {
+        boot_params,
+        entry_point,
+    })
+}
+
 // §3.9.7: Compile-time layout verification.
 const _: () = {
     assert!(
@@ -544,4 +669,106 @@ mod tests {
         bp.data[offsets::E820_ENTRIES] = offsets::E820_MAX as u8;
         assert!(!bp.add_e820_entry(0, 0x1000, 1));
     }
+
+    // ─── prepare_linux_boot orchestrator ────────────────────────
+
+    #[test]
+    fn prepare_rejects_tiny_bzimage() {
+        let err = prepare_linux_boot(&[0u8; 16], 0x1000_0000, 0x2000, None, &[]).unwrap_err();
+        assert_eq!(err, LinuxBootError::ImageTooSmall);
+    }
+
+    #[test]
+    fn prepare_rejects_bad_magic() {
+        let mut img = mk_bzimage(0x020F, true, 1);
+        // Corrupt the magic.
+        img[0x202] = 0xDE;
+        let err = prepare_linux_boot(&img, 0x1000_0000, 0x2000, None, &[]).unwrap_err();
+        assert_eq!(err, LinuxBootError::InvalidMagic);
+    }
+
+    #[test]
+    fn prepare_rejects_kernel_load_above_4gib() {
+        let img = mk_bzimage(0x020F, true, 1);
+        let err = prepare_linux_boot(&img, 0x1_0000_0000, 0x2000, None, &[]).unwrap_err();
+        assert_eq!(err, LinuxBootError::KernelLoadAddrOverflow);
+    }
+
+    #[test]
+    fn prepare_rejects_cmdline_above_4gib() {
+        let img = mk_bzimage(0x020F, true, 1);
+        let err = prepare_linux_boot(&img, 0x1000_0000, 0x1_0000_0000, None, &[]).unwrap_err();
+        assert_eq!(err, LinuxBootError::CmdlineAddrOverflow);
+    }
+
+    #[test]
+    fn prepare_rejects_initrd_above_4gib() {
+        let img = mk_bzimage(0x020F, true, 1);
+        let err = prepare_linux_boot(
+            &img,
+            0x1000_0000,
+            0x2000,
+            Some((0x1_0000_0000, 0x1000)),
+            &[],
+        )
+        .unwrap_err();
+        assert_eq!(err, LinuxBootError::InitrdAddrOverflow);
+    }
+
+    #[test]
+    fn prepare_happy_path_populates_boot_params() {
+        let img = mk_bzimage(0x020F, true, 1);
+        let mem_map = [
+            MemoryRegion {
+                base: 0,
+                length: 0x9F000,
+                typ: 1,
+            },
+            MemoryRegion {
+                base: 0x10_0000,
+                length: 0x1000_0000,
+                typ: 1,
+            },
+        ];
+        let boot = prepare_linux_boot(
+            &img,
+            0x0200_0000,                    // kernel at 32 MiB
+            0x0010_0000,                    // cmdline at 1 MiB
+            Some((0x0100_0000, 0x40_0000)), // initrd at 16 MiB, 4 MiB long
+            &mem_map,
+        )
+        .expect("prepare_linux_boot should succeed");
+
+        // Entry is always kernel_load_phys + 0x200.
+        assert_eq!(boot.entry_point, 0x0200_0000 + 0x200);
+
+        let bp = &boot.boot_params.data;
+
+        // code32_start (0x214) holds the kernel_load_phys.
+        assert_eq!(
+            u32::from_le_bytes(bp[0x214..0x218].try_into().unwrap()),
+            0x0200_0000,
+        );
+        // cmd_line_ptr (0x228).
+        assert_eq!(
+            u32::from_le_bytes(bp[0x228..0x22C].try_into().unwrap()),
+            0x0010_0000,
+        );
+        // ramdisk_image (0x218) / ramdisk_size (0x21C).
+        assert_eq!(
+            u32::from_le_bytes(bp[0x218..0x21C].try_into().unwrap()),
+            0x0100_0000,
+        );
+        assert_eq!(
+            u32::from_le_bytes(bp[0x21C..0x220].try_into().unwrap()),
+            0x40_0000,
+        );
+        // E820 entry count (0x1E8).
+        assert_eq!(bp[offsets::E820_ENTRIES], 2);
+        // First E820 entry at 0x2D0: base=0, len=0x9F000, typ=1.
+        let e0 = &bp[offsets::E820_TABLE..offsets::E820_TABLE + 20];
+        assert_eq!(u64::from_le_bytes(e0[0..8].try_into().unwrap()), 0);
+        assert_eq!(u64::from_le_bytes(e0[8..16].try_into().unwrap()), 0x9F000);
+        assert_eq!(u32::from_le_bytes(e0[16..20].try_into().unwrap()), 1);
+    }
 }
@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Mohamed Hammad
+
+[build]
+target = "x86_64-unknown-none"
+
+[target.x86_64-unknown-none]
+rustflags = [
+    "-C", "link-arg=-Tlinker.ld",
+    "-C", "link-arg=--no-dynamic-linker",
+    "-C", "relocation-model=static",
+    "-C", "code-model=kernel",
+]
+
+[unstable]
+build-std = ["core", "compiler_builtins"]
+build-std-features = ["compiler-builtins-mem"]