/* StarForth — Steady-State Virtual Machine Runtime Copyright (c) 2023–2025 Robert A. James. All rights reserved. Licensed under the Starship License, Version 1.0 (SL-1.0). */ /** * rpi5_mailbox.c - VideoCore mailbox property-interface framebuffer * setup (FABRIC-3.md §IV.3 item 3, 2026-09-04). * * **Never run on real hardware** — the Pi 5 isn't in hand until * 2026-09-17 (FABRIC-3.md §II). Everything below is built from real, * cited sources rather than assumed, but is compile-only-verified. * * Register layout (offsets from `rpi5_mailbox_base()`, i.e. the * `mailbox` devicetree node's own translated base address — * `rpi5_dtb.c` already confirmed `0x107C013880` on real Pi 5 * hardware, matching a Pi-5-specific bare-metal reference * (main.lv/writeup/raspberry5_baremetal_framebuffer.md) independently * confirming the same `0x107C000000` SoC base + `0x13880` mailbox * offset this codebase's own devicetree-driven lookup already * produces — two independent sources agreeing is why this offset is * trusted, not just cited once): * * +0x00 MBOX0_READ (receive: VC -> ARM) * +0x18 MBOX0_STATUS (bit30 MBOX_EMPTY: nothing to read) * +0x20 MBOX1_WRITE (send: ARM -> VC) * +0x38 MBOX1_STATUS (bit31 MBOX_FULL: cannot write yet) * * (`+0x20/+0x38` per the same Pi-5-specific reference above, which * treats MBOX0/MBOX1 as two structurally identical 0x20-byte blocks * back to back — a real difference from older-chip tutorials, which * often describe a single shared status register at `+0x18` for both * directions. Trusted here because it's the one source actually * confirmed against Pi 5 hardware, not an older SoC.) * * Message encoding (official wiki: * github.com/raspberrypi/firmware/wiki/Mailbox-property-interface, * channel and buffer format; property tag IDs/lengths from the same * page): write `(buffer_addr & ~0xF) | channel` to MBOX1_WRITE; read * back the same encoded value from MBOX0_READ once available, confirming * it before trusting the buffer (the response overwrites the request * in place — same shared buffer, not a separate response buffer). No * bus-address translation applied to the buffer pointer itself * (confirmed against the same Pi-5-specific reference: it writes the * plain masked pointer, no added GPU-bus-alias bit, unlike the * classic 32-bit-Pi convention some older tutorials describe) — * genuinely different per-SoC-generation behavior, not an oversight. * * Buffer/tag format (official wiki, same page): u32 total size, u32 * request(0)/response(0x80000000|len) code, tags..., u32 end-tag(0). * Each tag: u32 id, u32 value-buffer size, u32 req-size/resp-flag, * value bytes padded to 4-byte alignment. Buffer itself must be * 16-byte aligned (only the upper 28 bits of its address travel * through the mailbox). */ #include "starkernel/rpi5_mailbox.h" #include "starkernel/rpi5_dtb.h" #include "starkernel/fdt.h" #define MBOX_OFF_READ 0x00u #define MBOX_OFF_STATUS0 0x18u #define MBOX_OFF_WRITE 0x20u #define MBOX_OFF_STATUS1 0x38u #define MBOX_FULL 0x80000000u #define MBOX_EMPTY 0x40000000u #define MBOX_CH_PROPERTY 8u #define MBOX_CODE_REQUEST 0x00000000u #define MBOX_CODE_RESPONSE_OK 0x80000000u #define TAG_SET_PHYS_SIZE 0x00048003u #define TAG_SET_VIRT_SIZE 0x00048004u #define TAG_SET_DEPTH 0x00048005u #define TAG_SET_PIXEL_ORDER 0x00048006u #define TAG_SET_VIRTUAL_OFFS 0x00048009u #define TAG_ALLOCATE_BUFFER 0x00040001u #define TAG_GET_PITCH 0x00040008u #define TAG_END 0x00000000u #define PIXEL_ORDER_RGB 1u /* per the wiki's own tag doc: 0=BGR, 1=RGB */ /* 16-byte-aligned static request/response buffer -- no allocator * exists this early in boot (this driver runs before kmalloc's own * init, same as every other pre-M6 boot step), and one buffer is * enough: this driver only ever has one request in flight, never * concurrent. Exact word count for the 7-tag sequence below, counted * word-by-word (not estimated): 2 [header] + 5 [phys size] + 5 [virt * size] + 4 [depth] + 4 [pixel order] + 5 [virtual offset] + 5 * [allocate] + 4 [get pitch] + 1 [end tag] = 35 words (140 bytes) -- * 40 gives real margin without the array itself getting large enough * to matter. (An earlier version of this comment claimed 32 words was * "generous headroom" for a 38-word estimate against a 32-word array * -- that was wrong on its own terms before even being checked against * the real 35-word count; recomputed properly this time, not * re-estimated.) */ static uint32_t g_mbox_buf[40] __attribute__((aligned(16))); static inline void mmio_write32(uint64_t addr, uint32_t val) { *(volatile uint32_t*) addr = val; } static inline uint32_t mmio_read32(uint64_t addr) { return *(volatile uint32_t*) addr; } /* Every wait on the mailbox is bounded (2026-10-14): this runs before any * console exists, so a VideoCore that never answers must cost a missing * framebuffer, not a silent hang. One second, by the architectural * counter -- there at any EL with no setup. */ static uint64_t counter_now(void) { uint64_t v; __asm__ volatile("isb\n\tmrs %0, cntpct_el0" : "=r"(v)); return v; } static uint64_t counter_freq(void) { uint64_t v; __asm__ volatile("mrs %0, cntfrq_el0" : "=r"(v)); return v ? v : 54000000u; /* the Pi 5's 54 MHz, if the firmware left it unset */ } /* The VideoCore reads and writes RAM directly, not through the ARM's * caches (the MMU and caches are on by now -- native_rpi5_entry.S): the * request goes out to RAM before it is sent, and the cached copy is * dropped before the answer is read. */ static void buffer_to_ram(void) { uint64_t a; for (a = (uint64_t)(uintptr_t)g_mbox_buf; a < (uint64_t)(uintptr_t)(g_mbox_buf + 40); a += 16) __asm__ volatile("dc civac, %0" :: "r"(a) : "memory"); __asm__ volatile("dsb sy" ::: "memory"); } /* fdt helpers for the bus-address translation below. */ static uint32_t mb_be32(const unsigned char *p) { return ((uint32_t)p[0] << 24) | ((uint32_t)p[1] << 16) | ((uint32_t)p[2] << 8) | p[3]; } static uint64_t mb_cells(const unsigned char *p, uint32_t n) { return n == 2 ? ((uint64_t)mb_be32(p) << 32) | mb_be32(p + 4) : mb_be32(p); } static uint32_t mb_cell_prop(const void *dtb, const void *node, const char *name, uint32_t otherwise) { uint32_t len; const void *v = fdt_find_prop_in_node(dtb, node, name, &len); return (v && len == 4) ? mb_be32((const unsigned char *)v) : otherwise; } static int mb_compatible(const void *dtb, const void *node, const char *want) { uint32_t len, i = 0, wl = 0; const char *c = (const char *)fdt_find_prop_in_node(dtb, node, "compatible", &len); while (want[wl]) wl++; while (c && i < len) { uint32_t l = 0, k; while (i + l < len && c[i + l]) l++; if (l == wl) { for (k = 0; k < l && c[i + k] == want[k]; k++) { } if (k == l) return 1; } i += l + 1; } return 0; } /* The path from the root to the first node compatible with `want`: * path[0] is the root, path[depth-1] the node. Depth-first. */ static int mb_find_path(const void *dtb, const void *node, const char *want, const void **path, int depth, int max) { const void *child = (const void *)0; if (depth >= max) return 0; path[depth] = node; if (mb_compatible(dtb, node, want)) return depth + 1; while ((child = fdt_next_child_node(dtb, node, child)) != (const void *)0) { int d = mb_find_path(dtb, child, want, path, depth + 1, max); if (d) return d; } return 0; } /* The firmware's framebuffer address is an address on the firmware's own * bus. It becomes an ARM physical address through the devicetree's * dma-ranges, from the firmware node up to the root (2026-10-14): a node * with none, or an empty one, maps one to one; otherwise the entry that * holds the address moves it into the parent's space. On the Pi 5 the * firmware node's is empty and /soc has none -- the address is already * physical. (The 0x3FFFFFFF mask this replaced was the Pi 4's habit: * there /soc's dma-ranges maps bus 0xC0000000 onto physical 0, which * this handles as well.) Returns 0, or -1 if no entry holds it. */ static int bus_to_phys(const void *dtb, uint64_t bus, uint64_t *phys) { const void *path[12]; int depth, i; const void *root = fdt_root_node(dtb); if (!root) return -1; depth = mb_find_path(dtb, root, "raspberrypi,bcm2835-firmware", path, 0, 12); if (depth < 2) return -1; for (i = depth - 1; i >= 1; i--) { uint32_t len, ca, pa, sz, entry, k; const unsigned char *r = (const unsigned char *)fdt_find_prop_in_node(dtb, path[i], "dma-ranges", &len); if (!r || len == 0) continue; /* one to one */ ca = mb_cell_prop(dtb, path[i], "#address-cells", 2); sz = mb_cell_prop(dtb, path[i], "#size-cells", 1); pa = mb_cell_prop(dtb, path[i - 1], "#address-cells", 2); if (ca < 1 || ca > 2 || pa < 1 || pa > 2 || sz < 1 || sz > 2) return -1; entry = (ca + pa + sz) * 4u; for (k = 0; k + entry <= len; k += entry) { uint64_t cb = mb_cells(r + k, ca); uint64_t pb = mb_cells(r + k + ca * 4u, pa); uint64_t n = mb_cells(r + k + (ca + pa) * 4u, sz); if (bus >= cb && bus - cb < n) { bus = pb + (bus - cb); break; } } if (k + entry > len) return -1; /* no entry holds it */ } *phys = bus; return 0; } /* Appends one tag (id, value-buffer size in bytes, request size in * bytes, then `nvalues` u32 value words) to g_mbox_buf starting at * word index *idx, advancing *idx past it (including alignment * padding -- every value here is a whole number of u32 words already, * so no padding math is actually needed, but the wiki's own format * allows non-multiple-of-4 value sizes in general; this driver's own * tags never do). */ static void append_tag(uint32_t* idx, uint32_t tag_id, uint32_t value_bytes, const uint32_t* values, uint32_t nvalues) { uint32_t i; g_mbox_buf[(*idx)++] = tag_id; g_mbox_buf[(*idx)++] = value_bytes; /* Request-size word: set equal to value_bytes (the value-buffer's * own size, which for TAG_ALLOCATE_BUFFER is 8 -- the response's * size, since the buffer must be big enough for whichever is * larger -- not the 4-byte true request payload). Common practice * across multiple reference implementations surveyed while writing * this, not a single spec-quoted number; firmware is not observed * to validate an exact match against the true request length. * Unverified against real hardware either way. */ g_mbox_buf[(*idx)++] = value_bytes; for (i = 0; i < nvalues; i++) g_mbox_buf[(*idx)++] = values[i]; } int rpi5_mailbox_get_framebuffer(const void* dtb, uint32_t width, uint32_t height, uint32_t bpp, Rpi5FramebufferInfo* out) { uint64_t base; uint32_t idx; uint32_t send_val; uint32_t v2[2]; if (!out) return -1; base = rpi5_mailbox_base(dtb); if (!base) return -2; /* mailbox node not found/malformed in the DTB */ idx = 2; /* words 0/1 are the header, filled in after tags are built */ v2[0] = width; v2[1] = height; append_tag(&idx, TAG_SET_PHYS_SIZE, 8, v2, 2); append_tag(&idx, TAG_SET_VIRT_SIZE, 8, v2, 2); v2[0] = bpp; append_tag(&idx, TAG_SET_DEPTH, 4, v2, 1); v2[0] = PIXEL_ORDER_RGB; append_tag(&idx, TAG_SET_PIXEL_ORDER, 4, v2, 1); v2[0] = 0; v2[1] = 0; /* virtual offset x,y -- always (0,0), no scrolling support */ append_tag(&idx, TAG_SET_VIRTUAL_OFFS, 8, v2, 2); v2[0] = 16; /* alignment request, bytes */ v2[1] = 0; /* response slot (base addr); request only sends v2[0] */ append_tag(&idx, TAG_ALLOCATE_BUFFER, 8, v2, 2); v2[0] = 0; append_tag(&idx, TAG_GET_PITCH, 4, v2, 1); g_mbox_buf[idx++] = TAG_END; g_mbox_buf[0] = idx * 4u; /* total buffer size, bytes */ g_mbox_buf[1] = MBOX_CODE_REQUEST; send_val = ((uint32_t) (uintptr_t) g_mbox_buf & ~0xFu) | MBOX_CH_PROPERTY; buffer_to_ram(); { uint64_t limit = counter_freq(); /* one second, for the whole exchange */ uint64_t t0 = counter_now(); while ((mmio_read32(base + MBOX_OFF_STATUS1) & MBOX_FULL) != 0) { /* MBOX1 (send) has no room yet */ if (counter_now() - t0 > limit) return -5; } mmio_write32(base + MBOX_OFF_WRITE, send_val); for (;;) { while ((mmio_read32(base + MBOX_OFF_STATUS0) & MBOX_EMPTY) != 0) { /* MBOX0 (receive) has nothing yet */ if (counter_now() - t0 > limit) return -5; } if (mmio_read32(base + MBOX_OFF_READ) == send_val) break; /* A message arrived, but not the one we sent (another channel's * traffic) -- discard and keep waiting, per the wiki's own * documented channel-matching convention. */ if (counter_now() - t0 > limit) return -5; } } buffer_to_ram(); /* drops the cached copy: what follows reads the answer */ if (g_mbox_buf[1] != MBOX_CODE_RESPONSE_OK) return -3; /* VC rejected the request */ /* Re-walk the tags to pull out the allocate-buffer and get-pitch * responses -- same fixed order they were sent in, so fixed word * offsets are safe to compute directly rather than re-parsing * generically (this driver only ever sends this one sequence). */ { uint32_t alloc_tag_value_off = 2 /* header */ + (3 + 2) /* phys size */ + (3 + 2) /* virt size */ + (3 + 1) /* depth */ + (3 + 1) /* pixel order */ + (3 + 2) /* virtual offset */ + 3; /* allocate-buffer tag header, then its value words */ uint32_t pitch_tag_value_off = alloc_tag_value_off + 2 /* alloc response: base+size */ + 3; /* get-pitch tag header, then its value word */ uint32_t fb_addr = g_mbox_buf[alloc_tag_value_off]; uint32_t fb_size = g_mbox_buf[alloc_tag_value_off + 1]; uint32_t pitch_bytes = g_mbox_buf[pitch_tag_value_off]; if (fb_addr == 0 || fb_size == 0 || pitch_bytes == 0) return -4; /* Allocate-buffer answers with an address on the firmware's bus: * translated by the devicetree (bus_to_phys(), above), not masked * by a rule from another chip. */ uint64_t fb_phys; if (bus_to_phys(dtb, fb_addr, &fb_phys) != 0) return -6; out->base = (void*) (uintptr_t) fb_phys; out->size = fb_size; out->width = width; out->height = height; out->pixels_per_scanline = pitch_bytes / (bpp / 8u); out->pixel_format = 0; /* PixelRedGreenBlueReserved8BitPerColor -- * matches PIXEL_ORDER_RGB requested above */ } return 0; }