native_rpi5_entry.S: Pi 5 native (non-UEFI) boot entry stub (FABRIC-3.md §IV.3 item 1)

rpi5_native_start masks x0 down to the documented 32-bit DTB-pointer range
(the firmware's own entry protocol leaves the upper 32 bits unspecified),
stores it into g_rpi5_dtb_ptr for the still-open DTB->BootInfo constructor
(item 2) to read, then switches sp to a dedicated 2 MiB BSS stack -- this
path has no EDK2 boot stack to inherit, unlike every other entry path in
this codebase.

Intentionally halts (wfe/b loop) afterward rather than tail-calling into
item 2's constructor, which doesn't exist yet -- no stub function pretending
to be more than it is.

Not yet linked at the real 0x80000 load address; that needs its own linker
script/build target, not scoped into this item. Compiles and links into the
existing ARCH=aarch64 QEMU/UEFI acceptance build as dead code (ELF kernel
build's KERNEL_ASM wildcards every *.S in arch/aarch64/; nothing there
branches to it), same as rpi5_dtb.c/rpi5_mailbox.c before it.

Verified 3-arch boot to ok>/zuse)ok>.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019YcT3H2PQeyujrzjqS3Var

FABRIC-3.md

@@ -305,10 +305,20 @@ hypervisor" when `acpi_table` is `NULL` — no fix needed there).
 until now because QEMU's own UEFI firmware never publishes one; Pi 5 native boot removes that
 blocker for free.
 
-1. **Entry stub**: new `boot/native_rpi5_entry.S` (or similar) — linked at `0x80000`, receives
+1. **Entry stub — DONE 2026-09-04.** New
-   `x0` = DTB pointer per the researched protocol (§IV.1), minimal early setup (stack — either
+   `src/starkernel/arch/aarch64/native_rpi5_entry.S` / `include/starkernel/rpi5_native_entry.h`:
-   a small fixed BSS region, matching `BootInfo.kernel_stack_base`'s existing "zero = fall
+   `rpi5_native_start` masks `x0` down to the documented 32-bit DTB-pointer range (§IV.1: the
-   back to 2 MiB BSS stack" convention, or something new if that's insufficient this early).
+   firmware leaves the upper 32 bits of the register unspecified), stores it into
+   `g_rpi5_dtb_ptr` for item 2's still-open constructor to read, then switches `sp` to a
+   dedicated 2 MiB BSS stack (this path has no EDK2 boot stack to inherit — there is no EDK2 at
+   all here, unlike every other entry path this codebase has). Intentionally halts (`wfe`/`b`
+   loop) afterward rather than tail-calling into item 2's constructor, which doesn't exist yet.
+   **Not yet linked at `0x80000`** — that needs its own linker script/build target (item 6's own
+   `config.txt` work is the sibling piece; the separate-image build itself is not scoped into
+   this item). Verified 3-arch boot to `ok>`/`zuse)ok>` — `Makefile.starkernel`'s `KERNEL_ASM`
+   wildcards every `*.S` in `arch/aarch64/`, so this file compiles and links into the existing
+   QEMU/UEFI acceptance build as dead code (unreferenced symbol, nothing there ever branches to
+   it), same as `rpi5_dtb.c`/`rpi5_mailbox.c` before it.
 2. **DTB → `BootInfo` constructor**: new C function populating the *existing* `BootInfo`
    struct (`include/starkernel/uefi.h`) from the DTB instead of UEFI protocols — `dtb` = the
    real pointer, `acpi_table` = `NULL` (already the correct value for "no ACPI," per IV's own

capsules/BLOCK_MAP.md

@@ -1,5 +1,5 @@
 # Capsule Block Manifest — Auto-generated
-<!-- Generated by mkcapsule --manifest  2026-09-04T17:58:05Z -->
+<!-- Generated by mkcapsule --manifest  2026-09-04T18:10:39Z -->
 <!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh.  -->
 <!-- Hand-written justifications and immutability notes live  -->
 <!-- in MANIFEST.md alongside this auto-generated index.      -->

include/starkernel/rpi5_native_entry.h

@@ -0,0 +1,32 @@
+/*
+  StarForth — Steady-State Virtual Machine Runtime
+  Copyright (c) 2023–2025 Robert A. James. All rights reserved.
+  Licensed under the StarForth License, Version 1.0.
+ */
+
+/**
+ * rpi5_native_entry.h - Raspberry Pi 5 native (non-UEFI) boot entry point
+ * (FABRIC-3.md §IV.3 item 1).
+ *
+ * `native_rpi5_entry.S`'s `rpi5_native_start` is the very first code that
+ * runs on this path -- entered directly by Pi 5 firmware, no UEFI, no
+ * ACPI, none of `boot/uefi_loader.c`'s PE-loader shape applies. It masks
+ * the firmware's raw entry register down to the documented 32-bit DTB
+ * pointer (§IV.1: upper 32 bits of the 64-bit register are unspecified)
+ * and stores it here, then establishes its own dedicated stack (this path
+ * has no EDK2 boot stack to inherit) and halts.
+ *
+ * `g_rpi5_dtb_ptr` is this stub's one real output -- the still-open
+ * DTB->BootInfo constructor (§IV.3 item 2) reads it from here once it
+ * exists; nothing calls that constructor yet, so `rpi5_native_start`
+ * halts rather than tail-calling into a function that isn't real.
+ */
+
+#ifndef STARKERNEL_RPI5_NATIVE_ENTRY_H
+#define STARKERNEL_RPI5_NATIVE_ENTRY_H
+
+#include <stdint.h>
+
+extern uint64_t g_rpi5_dtb_ptr;
+
+#endif /* STARKERNEL_RPI5_NATIVE_ENTRY_H */

src/starkernel/arch/aarch64/native_rpi5_entry.S

@@ -0,0 +1,76 @@
+/*
+ * native_rpi5_entry.S (aarch64) - Raspberry Pi 5 native (non-UEFI) entry
+ * stub (FABRIC-3.md §IV.3 item 1, 2026-09-04).
+ *
+ * **Never run on real hardware** -- the Pi 5 isn't in hand until
+ * 2026-09-17 (FABRIC-3.md §II). Compile-only-verified.
+ *
+ * Entered directly by Pi 5 firmware at the classic bare-metal load address
+ * 0x80000 (item 6, `config.txt`'s `os_check=0`, is still open -- that's
+ * what actually gets a real image loaded there; this file is just the
+ * code that would run once it is). No UEFI, no ACPI -- none of
+ * `boot/uefi_loader.c`'s PE-loader shape applies on this path. Per
+ * FABRIC-3.md §IV.1's own researched entry protocol:
+ *
+ *   x0 = 32-bit DTB pointer, upper 32 bits of the 64-bit register
+ *        UNSPECIFIED -- must mask before use.
+ *   x1-x3 = reserved / zero, unused here.
+ *
+ * This stub's own job, and nothing more yet: mask and capture that DTB
+ * pointer into `g_rpi5_dtb_ptr` (declared in
+ * `include/starkernel/rpi5_native_entry.h`) where the still-open
+ * DTB->BootInfo constructor (§IV.3 item 2) can find it, then establish a
+ * dedicated stack -- this path has no EDK2 boot stack to inherit, there is
+ * no EDK2 at all here. It intentionally halts afterward rather than
+ * tail-calling into a function that does not exist yet; wiring that call
+ * is item 2's own job, not this one's.
+ *
+ * Build-system note: `Makefile.starkernel`'s `KERNEL_ASM` wildcards every
+ * `*.S` file in this directory into the monolithic kernel ELF build (not
+ * the PE/COFF loader build -- that list is explicit, boot.S/isr.S only,
+ * see the Makefile), so this file *does* compile and link into the
+ * existing ARCH=aarch64 QEMU/UEFI acceptance build. Nothing there ever
+ * branches to `rpi5_native_start` -- it is dead code in that build by
+ * design, exactly like `rpi5_dtb.c`/`rpi5_mailbox.c` before it. A real,
+ * separately-linked Pi 5 native boot image (its own linker script placing
+ * this code at 0x80000) does not exist yet -- that is a build-system task,
+ * not scoped into this item.
+ */
+
+    .section .bss
+    .align 8
+    .global g_rpi5_dtb_ptr
+g_rpi5_dtb_ptr:
+    .space 8                       /* uint64_t -- masked DTB pointer */
+
+    .align 4
+g_rpi5_native_stack:
+    .space 0x200000                 /* 2 MiB, same convention as the
+                                      * amd64/riscv64 kernel_entry.S
+                                      * BSS stacks */
+g_rpi5_native_stack_top:
+
+    .section .text
+    .global rpi5_native_start
+rpi5_native_start:
+    /* Mask x0 to its documented 32-bit DTB-pointer range (§IV.1: the
+     * upper 32 bits of the 64-bit register are unspecified by the
+     * firmware's own entry protocol). */
+    mov     x1, #0xffffffff
+    and     x0, x0, x1
+
+    adrp    x2, g_rpi5_dtb_ptr
+    add     x2, x2, :lo12:g_rpi5_dtb_ptr
+    str     x0, [x2]
+
+    /* Establish this path's own dedicated stack. */
+    adrp    x0, g_rpi5_native_stack_top
+    add     x0, x0, :lo12:g_rpi5_native_stack_top
+    mov     sp, x0
+
+    /* §IV.3 item 2 (DTB->BootInfo constructor) does not exist yet --
+     * halt rather than branch to a function that isn't real. Replace
+     * this loop with a tail call once that item lands. */
+.Lhalt:
+    wfe
+    b       .Lhalt