struct boot_info -- Canonical Field Ownership Matrix

Owner: Boot Protocol ABI & Handoff Contract roadmap -- Canonical boot_info Field Ownership Table section. Single source of truth. include/kernel/boot_info.h has a file-top comment that points here rather than duplicating policy inline. Every field of struct boot_info (and its nested structs) is listed below with producer, first valid phase, consumer(s), lifetime, owning roadmap, and validation rule. Add a field -> add a row.

Machine-readable complement. Every build emits build/boot-info-abi.kernel.json and build/boot-info-abi.mirror.json (struct size + SHA-256 fingerprint + the per-field row set; current count printed by make boot-info-doc-coverage) via the boot_info ABI step of bash scripts/build.sh. The two JSONs are diffed by tools/boot-info-manifest/compare.sh; any field / offset / size drift between include/kernel/boot_info.h and src/boot/uefi/boot_info_mirror.h fails the build with the first mismatching field named. The row set includes indexed leaves for every array-of-struct member (mmap[0].*, gop_modes[0].*, config_table[0].*, rt_mmap[0].*, usb_devices[0].* plus nested endpoints[0].*) and element-size sentinels for every scalar array (usb_controller.dma_pages[0], uefi_boot_order[0], boot_device_path[0], hv_vendor[0], ...), so the manifest also catches same-size element-type changes the six pinned _Static_assert offsets miss.

How to read this doc

• Producer -- who writes the value. bootx64 is the UEFI bootloader (src/boot/uefi/bootx64.c). mb2 was the legacy GRUB/Multiboot2 path, removed 2026-05-19 when UEFI became the only supported boot path (see alternate boot support); fields marked mb2 below are no longer written. kernel marks fields written by kernel code AFTER boot_info handoff.
• First valid phase -- the earliest point a consumer can safely read the field. P0 = entry into boot_phase0, after boot_info_validate* succeeds; P1 = after boot_phase1 init order completes; P2 = after boot_phase2; P3 = after boot_phase3 / user-mode; K = set later by kernel code (not populated on entry).
• Consumer(s) -- primary kernel files or subsystems that read the field. Non-exhaustive; the column names representative callers.
• Lifetime -- how long the value remains meaningful. boot = valid only during boot, stale once the consumer has caught up. runtime = required for the whole OS lifetime (e.g., runtime services, hypervisor flags). handoff = valid only until PMM reclaims the underlying memory.
• Owning roadmap -- the TODO section whose scope includes this field's producer/consumer contract.
• Validation -- the check that rejects malformed data. boot_info_validate_* covers the header; individual subsystems own deeper validation (e.g., vmm_map_mmio_uc for MMIO ranges).

ABI invariants (enforced by _Static_assert in the header):

• boot_info_header is at offset 0, exactly 8 bytes.
• sizeof(struct boot_info) fits in uint16_t (header.size).
• Six critical count fields are pinned by offset between kernel and bootloader mirror: mmap_count, gop_mode_count, config_table_count, rt_mmap_count, usb_device_count, uefi_boot_current.
• boot_config.cmdline is at byte offset 32 (stable across versions); boot_config.config_found at 288; sizeof(struct boot_config) == 512.

Every version bump goes in both include/kernel/boot_info.h and src/boot/uefi/boot_info_mirror.h (the mirror header included by both src/boot/uefi/bootx64.c and the host manifest dumper tools/boot-info-manifest/dump-mirror.c). Current: BOOT_INFO_VERSION = 24.

Top-level struct boot_info fields

ABI header

Memory map

Basic memory (legacy)

Framebuffer

GOP mode list

ACPI

Module (GRUB legacy)

These fields predate the typed payload descriptor array in boot-protocol roadmap -- Optional Payload Descriptor Array section. §4 explicitly directs "Keep legacy single module_start/module_end as compatibility aliases until consumers migrate"; no kernel code outside the Multiboot2 parser reads these today.

See Legacy / Multiboot2-only block below for the full retain/deprecate breakdown.

Boot configuration (boot.conf)

UEFI Configuration Table

UEFI Runtime Services

TPM measured boot

USB discovery

Boot timing (FPDT + TSC)

Serial port

Last-boot error (NVRAM)

Boot device identity

UEFI boot variables

Boot partition

Removable media

Kernel-populated fields

These fields live inside struct boot_info but the bootloader never writes them. Kernel code fills them after its own subsystems come up; readers must gate on the corresponding producer completing. Including them in boot_info keeps diagnostic dumps and the registry populator simple, at the cost of a weaker ABI shape (changing the set of kernel-populated fields does not need a BOOT_INFO_VERSION bump as long as layout does not change).

Typed payload descriptor array

Bootloader publishes typed physical payloads that are consumed by kernel subsystems after handoff. The packed-prefix invariant + overlap / range / unknown-required validator lives in src/kernel/main/boot_payload.c and is wired from src/kernel/main/boot_hw.c immediately after the boot_info copy.

Capability negotiation

Tri-word bitmask negotiation between bootloader and kernel. caps_required asserts "producer could not have booted without this feature"; caps_present advertises "producer populated or supplied this feature"; caps_degraded advertises "producer intentionally skipped this feature and substituted a safe fallback". The classify+halt validator boot_caps_validate is wired from src/kernel/main/boot_hw.c after boot_payload_validate and BEFORE any capability-gated consumer runs. Known-bit mask is BOOT_CAP_MASK_KNOWN; bits outside the mask in caps_required reject (stale-kernel-on-newer-loader); unknown bits in caps_present / caps_degraded are tolerated for forward compat.

BOOT_CAP_* bit catalog (v7)

BOOT_CAP_MASK_KNOWN is the OR of every entry below; the validator's "unknown required" check rejects any caps_required bit outside this set, and the "every known bit must be classified" check requires each of these to appear in caps_present OR caps_degraded. The list is the single source of truth -- it drives BOOT_CAP_MASK_KNOWN in include/kernel/boot_info.h, the bit-name switch in src/kernel/main/boot_caps.c, the table-driven test in src/kernel/test/test_boot_caps.c, and this catalog. Adding a new bit requires updating all four.

Boot-path provenance

One shared decision record answering "what path did this boot take and why". Consumers (HKLM\SYSTEM\Boot\Decision populator, BlackBox transcription, recovery orchestrator, attestation narrative) read these four fields BEFORE inspecting per-path descriptors (recovery image, resume metadata, network provenance) so they know which descriptor to trust. Validator: boot_decision_validate wired from boot_hw.c after boot_caps_validate. Bumping any enum value or flag bit requires a BOOT_INFO_VERSION bump.

BOOT_PATH_* catalog (v12)

enum boot_path_type -- which boot flow ran. Value 0 is the UNSET sentinel (BSS-zero from a producer that never populated the field; validator rejects). The single source of truth lives in include/kernel/boot_info.h; this catalog must stay in sync.

BOOT_REASON_* catalog (v12)

enum boot_reason_code -- the policy reason for the selected path. Value 0 is the UNSET sentinel. Each reason has a row in the validator's per-reason policy table (reason_policy[] in src/kernel/main/boot_decision.c) that pins required path, forbidden paths, fallback-class membership, and the trigger flag the reason demands. Adding a reason without updating the policy table is a compile-time error (_Static_assert on table length).

BOOT_SOURCE_FLAG_* catalog (v12)

Closed bitmask of inputs that drove the decision. BOOT_SOURCE_FLAG_MASK_KNOWN is the OR of every entry below; unknown bits halt the validator (no forward-compat tolerance). Trigger flags participate in Rule 7a (reason demands flag) and Rule 7b (flag demands matching reason); informational flags carry no reason constraint.

Anti-rollback and security-version binding

Monotonic anti-rollback counter bound to UEFI NVRAM variable IPOSRequiredSecVersion. The bootloader reads it early and refuses to jump when the kernel's os_loader_security_version is below the stored required_security_version. The kernel ships with a build-time signed value; after a successful Phase 3 proof-of-life (POST16_BOOT_OK), an opt-in policy may raise the NVRAM counter via UEFI RT SetVariable so future boots refuse older-signed kernels. Write timing is load-bearing: a pre-jump update would brick the system on a crash before POST16_BOOT_OK. Validator: boot_rollback_validate wired from boot_hw.c after boot_decision_validate.

EFI System Partition integrity

Pre-load sanity gate written by esp_integrity_check() in src/boot/uefi/bootx64.c. Catches obvious corruption / wrong-partition cases before the bootloader trusts the disk for kernel.exe + BOOTX64.EFI. Mirrors what Win11 BootMgr surfaces (FAT32 + GPT type GUID) and what Linux exposes via efibootmgr UUID. The trust anchor for the legacy split path is the Secure Boot signature on BOOTX64.EFI itself; this gate is corruption / wrong-partition detection, not adversary defense. Surfaced post-boot at HKLM\HARDWARE\BOOT\ESP\{Uuid, SizeMB, FilesystemType, TypeGuidValid} via boot_device_populate_registry in src/kernel/main/boot_hw.c.

Bootloader build identity

64-byte packed struct boot_loader_identity populated by the UEFI bootloader from compile-time constants emitted by tools/boot-info-manifest/gen-loader-identity.sh into build/boot_loader_identity.h. Surfaces the producer's git commit + commit time + label so triage tools (kernel fatal screen, BlackBox transcript, NVRAM fault record, HKLM\SYSTEM\Boot\Decision\Loader{GitSha,BuildTime,BuildLabel}) can attribute drift / rollback / stale-loader faults to a specific bootloader image. Zero git_sha[] is the "loader did not populate" sentinel for back-compat with stale bootloaders against fresh kernels.

UKI signed-payload addresses (v14)

Six uint64 fields appended after loader_identity. Populated by detect_uki_sections() + uki_copy_payloads_to_loader_data() in bootx64.c after walking the LoadedImage PE section table for .initrd / .recovery / .modules. Each payload is copied out of LoadedImage memory into AllocatePages-allocated EfiLoaderData pages so the kernel-physical address survives ExitBootServices. Zero addr means the section was absent in the UKI (back-compat with UKI builds shipping no payload sections). Set ONLY when boot_info.flags & BOOT_FLAG_INVOKED_VIA_UKI; ignored on the legacy split path. Provides whole-chain Secure Boot signature coverage of load-bearing payloads.

Extended UEFI boot-variable capability surface (v15)

Four read-only firmware capability fields appended after the v14 UKI cluster. Populated by the UEFI bootloader pre-EBS from BootCurrent's Boot####.Attributes (UEFI 2.10 spec 3.1.3), the BootOptionSupport and OsIndicationsSupported globals (UEFI 2.10 spec 3.1.4 + 8.5.4), and the Boot#### Description string. Persisted in the registry under HKLM\SYSTEM\Boot\Device\ for diagnostics / BCDEdit-equivalent surfacing. Read-only; OsIndicationsSupported is the firmware capability variable, distinct from the OsIndications write-path capsule trigger banned by the UEFI hardening TODO.

Local boot device path detail (v16)

Per-bus identifiers extracted from the boot device's UEFI device path: NVMe NamespaceId + NamespaceUuid (EUI-64) per UEFI 2.10 spec 10.3.4.21, leaf PCI Device + Function per UEFI 2.10 spec 10.3.2.1. Win11 surfaces these via MSFT_Disk.UniqueId + BusType; Linux exposes them via /sys/class/nvme/nvmeX/nsid + sysfs PCI BDF. Persisted in HKLM\SYSTEM\Boot\Device\ as NamespaceId, NamespaceEui64, PciDevice, PciFunction for diagnostics + storage-stack provenance. Sentinels: boot_nvme_nsid=0 and boot_nvme_eui64 all-zero when not NVMe; boot_pci_device=0xFF and boot_pci_function=0xFF when not on PCI.

Local boot device path detail (v17)

Media role detected from /IPOS/role.txt on the ESP and on the BlackBox service partition before kernel load (boot-media role-detection feature, owning TODO 01-boot-platform/TODO-06). The bootloader reads role.txt from both partitions on the same physical disk as the booted ESP and cross-checks the contents; mismatch falls back to BOOT_MEDIA_ROLE_NORMAL and sets boot_media_role_mismatch=1. Absent BlackBox marker is NOT a mismatch (single-partition media is legal). When the role is INSTALLER, RECOVERY, or DIAGNOSTICS, the bootloader also sets boot_path to the matching enum and boot_reason = BOOT_REASON_MEDIA_ROLE_MARKER so Registry / recovery / attestation consumers see a coherent decision record.

Source precedence (3-source contract): The bootloader resolves boot_media_role from at most three sources in order. The first source that returns a non-UNSET value wins; later sources are not consulted.

1. UKI .cmdline token -- when boot_info.flags & BOOT_FLAG_INVOKED_VIA_UKI, parse the media_role=NAME token from the signed .cmdline PE section via uki_cmdline_extract_media_role(). UKI cmdline is covered by the firmware-Secure-Boot whole-chain signature, so this is the most authoritative source. A UKI legitimately staged on top of an existing on-disk role marker (recovery UKI on a normal install) is the EXPECTED case; UKI override is CLEAN, no boot_media_role_mismatch flag is set.
2. DHCP option (network boot, planned) -- PXE/HTTP-served kernel will read a vendor DHCP option carrying the role. Currently blocked on 01-boot-platform/TODO-25 (network boot infrastructure).
3. ESP /IPOS/role.txt -- the disk-side fallback documented above. Cross-checked against BlackBox/role.txt on the same disk.

Default BOOT_MEDIA_ROLE_NORMAL when all three sources report UNSET.

Firmware trust landscape (v18)

Trust signals read by the kernel from UEFI runtime services after ExitBootServices. Populated by uefi_secureboot_init() in src/kernel/uefi_runtime.c alongside the existing secure_boot_enabled / setup-mode reads. v18 is the partial-ship subset of the artifact-signing / manifest-verification feature (owning TODO 01-boot-platform/TODO-06); the bootloader-side manifest signature path is blocked on crypto vendor work tracked in 09-desktop-shell/TODO-07-cng-crypto.md (primitives) and 15-installer-release/TODO-01-release-artifacts.md (release-side signing). The boot_decision degraded-trust rule emits one [WARN] klog line per set bit (advisory, non-fatal); boot_device_populate_registry surfaces these to HKLM\SYSTEM\Boot\Trust\*.

Boot policy selection (v19)

Result of the boot-entry policy ladder (boot-entry policy feature, owning TODO 01-boot-platform/TODO-07). The bootloader runs the precedence ladder (hotkey > watchdog > A/B > recovery > store-default > fallback) over the parsed bootentries.json envelope set and writes the chosen entry id + reason here, plus the per-entry rejected list. Parallel to boot_path / boot_reason: those are the path-flow axis (where the kernel loads from); these are the policy-ladder axis (why this specific entry beat others). When the chosen entry implies a path change (recovery, diagnostics), the loader updates boot_path / boot_reason as well.

Policy audit surface (v20)

Surface for the per-decision boot policy audit trail (boot-entry audit feature, owning TODO 01-boot-platform/TODO-07). The bootloader reads the ImpossibleOS-BootSticky UEFI variable (single 256-byte record, exceptional-only -- per-boot history goes to X:\Boot\history.jsonl) and surfaces the relevant bits here. The kernel's boot_audit_publish() consumes this block plus the v19 selection block to compose one JSONL line per boot, then acks consumed triggers via uefi_var_set post-publish. Bootloader is read-only on the sticky var.

OS-visible Loader UEFI variables (v21)

Surface for the systemd-boot Boot Loader Interface compatibility feature (boot-entry loader-vars feature, owning TODO 01-boot-platform/TODO-07). The bootloader publishes 11 read-only Loader* UEFI variables under vendor GUID 4a67b082-0a4c-41cf-b6c7-440b29bb8c4f after the policy decision and consumes 2 one-shot vars (LoaderEntryOneShot, LoaderConfigTimeoutOneShot) early in policy invoke. See docs/boot/loader-vars.md for the full variable inventory + feature bitmap.

Multi-GPU GOP handles (v23)

Per-GOP-handle enumeration appended at the struct tail (TODO-27 sec4). init_gop() enumerates every EFI_GRAPHICS_OUTPUT_PROTOCOL handle via LocateHandleBuffer (iGPU + dGPU, or multiple panels), records one boot_gop_handle per handle, and selects the PRIMARY by device-path match against gST->ConsoleOutHandle (then EFI_CONSOLE_OUT_DEVICE_GUID marker, then largest resolution). The primary drives boot_info.fb unchanged; secondaries carry geometry for the kernel multi-head driver (04-drivers-hardware/TODO-17 sec6 display_register_head()). gop_handle_count==0 ONLY when no GOP handle was exported (headless / no display / enumeration failed); a successful single-GPU boot publishes gop_handle_count==1 with gop_handles[0] primary. A count==0 consumer falls back to boot_info.fb (zeroed on headless) and must NOT treat count==0 as the single-head case -- that is count==1.

Nested struct: boot_payload_desc

48-byte ABI-pinned descriptor. Kernel enum boot_payload_type maps well-known values (MODULE, INITRD, RECOVERY_IMAGE, HIBERNATION_META, TPM_EVENT_LOG, NETWORK_CONFIG, RANDOM_SEED, USB_HANDOVER); unknown values are SKIPPED for type-specific validation unless BOOT_PAYLOAD_FLAG_REQUIRED is set on the descriptor (required-unknown forces a fatal boot failure).

Legacy / Multiboot2-only fields (historical)

The repo currently supports ONE boot path: UEFI (src/boot/uefi/bootx64.c). The Multiboot2 parser, header asm, 32-bit entry stub, and grub.cfg were deleted under the alt-boot unsupported policy (TODO-08 closed; see docs/boot/alt-boot.md).

The fields below remain in struct boot_info for ABI stability -- removing them would shift offsets and force a BOOT_INFO_VERSION bump. The UEFI bootloader fills them when applicable; no kernel consumer reads them today.

These fields no longer reflect any active code path; removing them is gated on a future ABI version bump.

Nested struct: boot_mmap_entry

Per-region entry in boot_info.mmap[]. Producer and consumer are the same for every row; the table records per-field validation.

Nested struct: boot_uefi_guid

Used wherever a UEFI GUID needs to be carried over (config tables, well-known GUID constants).

Nested struct: boot_uefi_config_entry

Nested struct: boot_rt_mem_entry

Region record for SetVirtualAddressMap.

Nested struct: boot_uefi_runtime

EFI runtime-service function pointers + state flag. Bootloader uses PE/COFF ms_abi; kernel casts at use time to sysv calling convention.

Nested struct: boot_framebuffer

Nested struct: boot_gop_mode

One row per GOP mode enumerated pre-ExitBootServices.

Nested struct: boot_gop_handle

32-byte ABI-pinned record (TODO-27 sec4). One per enumerated GOP handle. fb_addr/fb_size/fb_valid are set ONLY when the handle's framebuffer passed the full primary-publish validation (non-zero base, supported pixel format, pitch>=width, no height*pitch*4 overflow, FrameBufferSize covers the surface); a secondary head whose mode was never SetMode-configured records geometry with fb_addr=0/fb_valid=0 so the kernel never maps a stale or non-display MMIO range.

Nested struct: boot_config

Mirror struct in src/boot/uefi/bootx64.c. cmdline at offset 32, config_found at 288, total size 512 -- all three pinned by _Static_assert in the header. Each flag below is 0 | 1 unless noted.

Nested struct: boot_usb_endpoint

Nested struct: boot_usb_device

One row per USB device discovered via EFI_USB_IO_PROTOCOL pre-ExitBootServices. Consumer (xHCI driver) skips re-enumeration after taking over the controller.

Nested struct: boot_usb_controller

xHCI DMA state allocated by the bootloader in EfiLoaderData. Survives ExitBootServices if the kernel calls pmm_mark_region_used for each non-zero physical address.

Nested struct: timing

FPDT-sourced fields come from the firmware performance record (nanoseconds since some firmware-defined epoch). TSC-sourced fields are raw rdtsc ticks captured by the bootloader. Consumer is the boot performance dashboard / X:\Perf\ staging; all TSC timestamps must be monotonically non-decreasing.

Kernel boot stack (v24)

The run the kernel executes on from the handoff onward. The bootloader AllocatePages it below 4 GiB pre-ExitBootServices, fills the whole run with BOOT_KSTACK_POISON, and switches RSP to its top in jump_to_kernel before calling the kernel entry. Before this existed the kernel ran on the firmware's own EfiLoaderData stack, which pmm_init frees into the allocator while it is in use. The kernel validates the bounds in boot_stack_init() (Phase 0, before pmm_init), confirms its own RSP lies inside them, reserves the run through boot_reserved (BOOT_RESERVED_BOOT_STACK), guards the lowest page once vmm_init is up, and recovers the high-water mark from the poison.

It is not a boot-only run. task.c:592-608 keeps it as PID 0's permanent kernel stack (stack_base = 0, "boot stack, don't free"), and PID 0 goes on to run the compositor loop, which never returns. Size it for that lifetime, not for early boot. Measured peaks (QEMU, 2026-08-28): 9,528 bytes at the end of Phase 1; 38,368 bytes in compositor steady state on a production boot; 99,472 bytes cumulative on a test=1 boot, where the in-kernel test runner is the deepest path.

WHERE the run may not be placed, and which phase refuses it. The geometry rules above are necessary and not sufficient: a correctly-shaped run in the wrong place is still fatal, and a third-party v24 producer that reads only the size and alignment columns can publish one. Every forbidden interval below is half-open [lo, hi), and each is refused by BOTH halves so a producer that skips one is still caught.

Two further contract terms a producer owes: the whole run (guard page INCLUDED) must be filled with BOOT_KSTACK_POISON before RSP is switched to it, and RSP must already be inside the published usable span when the kernel entry is called. The kernel proves both -- an unpoisoned or differently-poisoned run halts at boot_stack_install_guard with a named pattern-mismatch message, and an unswitched RSP halts at boot_stack_init.

Update protocol

When adding a field:

1. Decide producer + consumer + first-valid phase before touching boot_info.h. Update this doc first.
2. Add the field to struct boot_info (or the appropriate nested struct) in include/kernel/boot_info.h. Add the matching field (same name, same type, same order) to src/boot/uefi/boot_info_mirror.h in the same commit. Bootloader uses UINT8/16/32/64 spellings; kernel uses uint8_t/16/32/64_t.
3. Add a matching F(new_field) line to tools/boot-info-manifest/dump-fields.inc. If the new field is an array-of-struct, also add representative F(new_field[0].leaf) rows for every element leaf. If it is a scalar array with multi-byte elements, add F(new_field[0]) as an element-size sentinel. Without this step the manifest compare passes while the struct definitions disagree.
4. Bump BOOT_INFO_VERSION in BOTH files unless the field fits into an existing _reserved/_pad region without shifting any documented offset.
5. Extend the _Static_assert offset pins in both headers if the field shifts a mirrored count field.
6. Wire the producer, wire the consumer, add a unit test that reads the field through the real layout (not a synthetic fixture).
7. Add a row here.
8. bash scripts/build.sh invokes the boot_info ABI stage automatically -- a clean build proves kernel/bootloader manifests agree.

When a field becomes stale:

1. Mark it deprecate in the Legacy block above. Include the replacement owner roadmap.
2. Do NOT remove it until the version bump that drops the Multiboot2 path (or the replacement feature fully displaces it), so existing bootloaders keep parsing clean.
3. Prefix removed-candidate fields with /* DEPRECATED: ... */ in the header when the window opens.