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
367 lines
15 KiB
C
367 lines
15 KiB
C
/*
|
||
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;
|
||
}
|