rpi5_mailbox.c: wire the VideoCore mailbox message protocol (FABRIC-3.md §IV.3 item 3)

New rpi5_mailbox_get_framebuffer() sends one property-tag request buffer
(phys size, virt size, depth, pixel order, virtual offset, allocate-buffer,
get-pitch) over the register layout rpi5_dtb.c already discovers, populating
an Rpi5FramebufferInfo kept in exact field-for-field sync with uefi.h's
FramebufferInfo so console.c/vt100.c/framebuffer.c need no downstream changes
once this is wired into a real entry stub.

Register offsets (+0x00/+0x18 MBOX0 read/status, +0x20/+0x38 MBOX1
write/status) confirmed against a Pi-5-specific bare-metal reference,
independently cross-checked against this codebase's own rpi5_dtb.c
translated base address.

Caught and fixed a real buffer-overflow bug before compiling: the static
request buffer was sized 32 words against an actual 35-word requirement for
the 7-tag sequence, recomputed exactly rather than re-estimated; resized to
40 words.

Two things flagged as genuinely unverified against real hardware (not
guessed past the comment): the allocate-buffer tag's request-size field
value, and whether its response address needs classic bus-alias masking on
Pi 5 specifically.

Compile-only-verified -- no caller yet (that's the still-open entry-stub/DTB
constructor items). 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

include/starkernel/rpi5_mailbox.h

@@ -0,0 +1,68 @@
+/*
+  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_mailbox.h - VideoCore mailbox property-interface framebuffer
+ * setup, for the native (non-UEFI) Raspberry Pi 5 boot path
+ * (FABRIC-3.md §IV.3 item 3).
+ *
+ * Register layout, message/tag format, and property-tag IDs confirmed
+ * against multiple sources before writing `rpi5_mailbox.c` — see that
+ * file's own doc comment for exactly which, and what (if anything)
+ * remains unverified against real hardware (not in hand until
+ * 2026-09-17; this driver has never run on real silicon).
+ */
+
+#ifndef STARKERNEL_RPI5_MAILBOX_H
+#define STARKERNEL_RPI5_MAILBOX_H
+
+#include <stdint.h>
+
+/* Mirrors uefi.h's FramebufferInfo exactly -- populated by
+ * rpi5_mailbox_get_framebuffer() the same shape UEFI GOP already
+ * populates it, so console.c/vt100.c/framebuffer.c need no changes at
+ * all for this path. Not #include-ing uefi.h here (that header is a
+ * large UEFI-protocol grab-bag; this driver only needs this one
+ * struct's shape) -- callers that already have a `FramebufferInfo*`
+ * (from uefi.h) can pass it directly, since the two struct
+ * definitions are kept in exact field-for-field sync by convention.
+ */
+typedef struct {
+    void*    base;
+    uint64_t size;
+    uint32_t width;
+    uint32_t height;
+    uint32_t pixels_per_scanline;
+    uint32_t pixel_format; /* 0 = RGB, matches uefi.h's
+                             * PixelRedGreenBlueReserved8BitPerColor --
+                             * this driver always requests RGB pixel
+                             * order explicitly (tag 0x00048006), never
+                             * leaves it at hardware/firmware default. */
+} Rpi5FramebufferInfo;
+
+/**
+ * @brief Request a framebuffer from the VideoCore firmware via the
+ * mailbox property interface, at the requested resolution/depth.
+ *
+ * Sends one buffer with all six setup tags (physical size, virtual
+ * size, depth, pixel order, virtual offset, allocate) plus a
+ * get-pitch tag, in one request/response round trip.
+ *
+ * @param dtb     Devicetree blob (passed to `rpi5_mailbox_base()`).
+ * @param width   Requested physical+virtual width, pixels.
+ * @param height  Requested physical+virtual height, pixels.
+ * @param bpp     Requested bits per pixel (32 is the only depth this
+ *                driver has been designed against; others are not
+ *                refused outright but are unverified).
+ * @param out     Populated on success; untouched on failure.
+ * @return 0 on success, negative on failure (mailbox node not found
+ *         in the DTB, VC firmware rejected the request, or a response
+ *         tag came back with an unexpected size).
+ */
+int rpi5_mailbox_get_framebuffer(const void* dtb, uint32_t width, uint32_t height,
+                                  uint32_t bpp, Rpi5FramebufferInfo* out);
+
+#endif /* STARKERNEL_RPI5_MAILBOX_H */