Files
LithosAnanke/kernel/src/arch/aarch64/rpi5_mailbox.c
T
Claude 16b9747d33 chore(license): the source headers name the Starship License 1.0 (SL-1.0), as LICENSE does [skip ci]
347 headers said "Licensed under the StarForth License, Version 1.0" -- a
shortening (Captain Bob, 2026-11-08: "License file SL I think I shortened
accidently"); LICENSE is, and has been since the first commit, the
Starship License 1.0 (SL-1.0, SPDX LicenseRef-Starship-1.0). 349 files,
566 occurrences, now "Starship License, Version 1.0 (SL-1.0)".

Left as they are, pending a ruling: docs/patent/ (the patent figures),
docs/formal/ (the citable volumes) and the generated reports under
docs/working/experiments/ (32 files). Comments and license text only:
the amd64 kernel builds, every changed script parses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GE3SDvQn5EoxdGufk84zz2
2026-11-08 17:54:24 +00:00

367 lines
15 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
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;
}