Repository navigation
Add the Pi 5 PIO engine for HUB75, through the kernel's /dev/pio0 interface - #258
Conversation
MoonLight gains its own engine for driving HUB75 panels from a Raspberry Pi 5's PIO, and the Linux arm64 build compiles Raspberry Pi's piolib into the program from a pinned submodule, with its license in every arm64 package. The HUB75 driver offers the engine in the next pull request (3b), so the card and its saved settings are main's. On a Pi 5 wall, with the whole of PR 3, the engine refreshes at the moonpi build's rate while MoonLight takes 60-67% CPU against 69-94%.
KPI: 256lights | Host:2747KB | tick:9/7/7/7/1/7/166/8/7/7us(FPS:111111/142857/142857/142857/1000000/142857/6024/125000/142857/142857) | src:436(107329) | test:309(76538) | functions-over:332
Commit: src +3481/-15 lines | test +2716/-3 lines | code findings 1729 -> 1727 (duplicated block -2) | duplicated lines 3605 -> 3597 (-8)
**Core**
- Hub75Pio.h, new: the seam MoonLight's Pi 5 PIO engine sits behind. `Hub75PioOptions` (rows, cols, panels per lane, 1 to 3 lanes, scan 8/16/32, depth 2 to 8, pixel clock up to 40 MHz, extra dark words before each latch, clock edge); open, a push of packed RGB that returns at once, correction, fps, stalled, submit errors, the warning, the close error and close. Open, close, push, correction and fps share one task, and a push never overlaps a close. The host test port: modes Off, Record and Stub, the levers, and `Hub75PioTestPort`, the record of what the seam was handed. A header of its own beside platform.h, as Hub75Bus.h and edid.h are. Its lead names all six kernel drivers whose pins the panels take (I2C1, SPI0, UART0, 1-wire, I2S, PWM).
- machine.h and host/platform_host_machine.cpp, new: `Machine` (Esp32, Pi5, PiGpio, Other). An ESP32 build knows it at compile time; a host reads /proc/device-tree/compatible once, and where that cannot be read (a container that masks it) the Model line of /proc/cpuinfo. The two parsers are pure; the test levers include a rest the test binaries set to Other. Its reader is 3b's driver: in src, only its own files call `machine()` (git grep of the index).
- platform.h: `Hub75Backend::Pio`, and `hub75BackendLabel` inline ("Pi PIO", "Parlio", "LCD_CAM"), which replaces the copies in the three ports.
- Hub75Encode.h: names its two callers, the bus output's `show` and the PIO engine's `encodeLane`.
- esp32/platform_esp32_hub75.cpp: the ESP32 port refuses `Pio` ("Pi PIO drives a Raspberry Pi's header, not an ESP32") and its two label copies go. host/platform_host.cpp: the host answers `Pio`'s availability through the PIO seam.
- host/platform_host_pio.cpp, new: the seam on every host. Record keeps options and frames in a recorder (host/hub75_recorder.h, new, a lock-free triple buffer); Stub opens the real engine on the stub backend through the branch a Pi takes; Off opens the engine on piolib where piolib is linked, and a build without it refuses with "needs a Raspberry Pi build with piolib". The host refuses without /dev/pio0 and on kernels 6.18.39 to 6.18.59, which stall a PIO reopen; a pixel clock above the benched 20 MHz opens with a warning; the test binary's gate refuses the real backend first. The engine is one per process and outlives exit, since a refresh thread stuck in the kernel may still read it.
- rpi/hub75.pio and rpi/hub75.pio.h (pioasm's output, checked in): one state machine drives GPIO 2 to 27 as a 26-pin OUT range, the clock on side-set (GPIO 17), five PIO cycles a pixel clock, in a rising-edge and a falling-edge variant. Its structure follows pico-examples' and pimoroni-pico's hub75 programs; no code is adapted.
- rpi/hub75_rpi_common.h: the engine base: one open sequence with the steps as hooks, the encode and refresh threads, the triple buffers, the refresh-rate window, the publish handshake (seq_cst atomics), the join with a deadline, and the stop signals blocked on the refresh thread.
- rpi/hub75_pio_engine.h, .cpp: the render thread publishes RGB into a triple buffer and returns; an encode thread encodes the newest frame per lane with `hub75Encode` (a second caller beside the bus output), repacks the three lanes into 32-bit words and hands them over through a second triple buffer; the refresh thread submits the newest encoded frame and submits it again until a newer one arrives. Brightness is read once a frame, and a failed encode keeps the last good frame. Shutdown joins the encode thread, joins the refresh thread within 3 s, submits a blank as deep as the DMA ring (`xferBufCount` x `xferBufSize`) and frees the buffers. A submit in flight past the stall time reads as stalled and the rate falls to 0; a refresh thread still stuck at the deadline is reported by the close, which keeps the buffers, and only the first close pays the deadline.
- rpi/hub75_pio_repack.h, .cpp, rpi/hub75_pio_pins.h, rpi/hub75_board_pins.h: the repack's lookup tables built from the pin map; compile-time checks that the lane and shared pins sit in GPIO 2 to 27, off CLK, each on its own GPIO; the active-3 board's pinout from hzeller's `regular` mapping (pin facts only, `@attribution rpi-rgb-led-matrix`), with the config.txt lines for the pins a kernel driver may own (I2C1, SPI0, UART0, 1-wire, I2S, PWM).
- rpi/hub75_pio_backend.h, .cpp, rpi/hub75_pio_backend_piolib.cpp: the `PioBackend` interface (open, start, submit, blank and stop, close) and its factory, which refuses the real backend in a test binary before piolib is reached. The piolib backend gives errno and strerror on every failure and the node's owner, group and mode on a refused /dev/pio0. The submit semantics per kernel: on 6.12 a submit returns at delivery with a 1 s timeout; from 6.18.39 it returns once queued and blocks only while every bounce buffer is busy, with no timeout.
- rpi/hub75_pio_backend_stub.h, .cpp: the stub backend: a Blocking model (6.12) and a Ring model (6.18.39 and later), the kernel's limits on the ring, faults (open, start, submits, a hang, a slow copy, an early FIFO-empty stop) and records (the start configuration with its program, the blanks, each frame's identity).
- rpi/hub75_pio_c_api.h, .c: a C shim of eleven functions over piolib, since piolib.h compiles as C only: `pio_open(0)` once for the process, `pio_select` before each call that reads the current instance, and the last state machine preferred on a reopen, so the kernel hands that state machine's DMA channel back rather than leaving it held.
- rpi/hub75_pio_options.h, .cpp: the option rules as a table, built on every host, MSVC included, so the recorder refuses what the engine refuses; the depth's upper bound is `kHub75EncodeMaxBitDepth`.
**Scripts/MoonDeck**
- ci/package_host.py: `copyright_text()`, a Debian machine-readable copyright file: a GPL-3+ stanza for every Linux package, and on arm64 piolib's BSD-3-Clause license, verbatim from the submodule. It goes into the .deb (/usr/share/doc/moonlight/copyright, amd64 included), the tarball (COPYRIGHT) and, on arm64, a `COPYRIGHT-linux-arm64-v<version>.txt` release asset beside the bare program.
- ci/release_stage.py: the generated release container copies that file into the image.
- ci/linux/postinst: adds the service user to the group that owns /dev/pio0, read from the node; a missing node, root and an unknown group are left alone.
- check/check_docgen.py, check/check_code.py, check/check_clang_tidy.py: `src/platform/rpi/hub75.pio.h`, pioasm's output, joins each one's list of generated and vendored files.
**Tests**
- Eight new files in test/unit/core, 112 cases (`grep -c ^TEST_CASE`), listed in test/CMakeLists.txt; the six engine files build where the engine builds (`MM_HUB75_PIO_ENGINE`, not MSVC).
- unit_platform_hub75pio.cpp, 32 cases: the seam in each mode: the kernel and /dev/pio0 refusals, the canvas, frames and correction handed over, the recorder's rate, the test binary's gate, availability, a push after the close, the engine reached through Stub mode (from another task too), failed submits, the warning above 20 MHz, a close that finds the refresh thread stuck.
- unit_platform_hub75pio_engine.cpp, 20 cases: the option refusals, a red pixel's word, the repack tables, latch blanking, 8-bit, the divider, buffers and edge program the backend starts with, the ring-deep blank, a backend that will not open or start, failed and timed-out submits, the frame records, the Ring model, a direct engine open refused at the factory.
- unit_platform_hub75pio_buffer.cpp, 19 cases: the double buffer: whole frames under racing publishes, the newest frame wins, the cadence holds during an encode, a failed encode keeps the frame, three lanes each on their own pins, brightness, the shutdown order, a publish racing the shutdown, an early FIFO-empty poll, the stop signals, the triple buffer's slots, a stuck submit read as a stall.
- unit_platform_hub75pio_stub.cpp, 15 cases: the stub's two models, faults and limits; the upper time bounds run at 10 kHz, a 200 ms margin for a loaded sanitizer runner.
- unit_platform_hub75pio_piolib.cpp, 11 cases: the piolib backend's source over a scripted shim, on builds without piolib: the errno and permission texts, the start order, the blank, drain and stop order.
- unit_platform_hub75pio_c_api.cpp, 7 cases: the C shim compiled against piolib_fake/piolib.h, a declarations-only stand-in: one open, select first, the same-state-machine preference and its fallback, a failed DMA configure forgotten.
- unit_platform_machine.cpp, 6 cases: the compatible and cpuinfo parsers, the rest at Other, the real host read once. unit_platform_hub75pio_options.cpp, 2 cases: the rules and the recorder's agreement.
- hub75_engine_bench.h, new: waits on the stub's submits and the walls the engine tests open.
- test_main.cpp: an explicit main: the fixtures reset before the run, and each case starts with the machine at Other and the real PIO refused; after the run, a case that reached the real backend fails it, once every reporter has written. scenario_runner.cpp: the same two levers. light/hub75_port.h: `PioPortGuard`, `PioHost` and `PioAvailable` beside `PortGuard`.
- Host (macOS), on the staged tree on fda0318 (MoonModules#256): 3,592 of 3,592 cases, 494,475 assertions; the scenarios pass.
**Docs/CI**
- .gitmodules, third_party/rpi-utils, new: the repository's first submodule: github.com/AnjinMeili/rpi-utils, a fork of raspberrypi/utils, pinned at d59c22e (branch moonlight): upstream's bb3e262 plus one patch to piolib/pio_rp1.c (+1/-10): `rp1_ioctl` returns -ETIMEDOUT and -EREMOTEIO to the caller, where stock piolib ends the process through `pio_panic()`. To be offered to raspberrypi/utils.
- CMakeLists.txt: the engine sources on GCC and Clang (`MM_HUB75_PIO_HAS_ENGINE`), the seam and options on MSVC too. On Linux aarch64, `mm_piolib`, a static library of the submodule's piolib.c, library_piochips.c and pio_rp1.c (LIBRARY_BUILD=1, piolib's parameter assertions off, its warnings off, position independent, Threads), with the piolib backend and the C shim (`MM_HUB75_PIO_HAVE_PIOLIB`). `MM_REQUIRE_PIOLIB` makes a missing submodule a configure error: set in the arm64 release job and implied by packaging on aarch64, as libcurl is required for a release. `-Wnon-virtual-dtor` applies to C++ only.
- .github/workflows/release.yml: the arm64 job checks out the submodule and sets `MM_REQUIRE_PIOLIB`; `third_party/**` joins both path filters; the release attaches the arm64 COPYRIGHT asset.
- Dockerfile: the image carries the package's copyright file.
- docs/reference/attributions.md: rows for pico-examples, pimoroni-pico and piolib (its notice and where each arm64 form carries it); hzeller's row reads `hzeller / rpi-rgb-led-matrix`, the pin facts' source.
- docs/reference/installing-on-linux.md: the service user's groups include, on a Pi 5, the one that owns /dev/pio0.
- No MIGRATING entry: the HUB75 card, its options and its saved values are main's.
- docs/reference/metrics: code.json from check_code (1,729 → 1,727), repo-health from the KPI gate. prose.json stays as main has it: run_gates' prose gate fails on this Mac's Vale 3.27 for a clean fda0318 and for this tree alike (EmDash 843 → 889, SelfReference 14 → 16, Temporal 155 → 157 in both runs), while CI's findings.yml installs Vale 3.21.0; 3a's added lines carry 0 errors and 41 Negation warnings. The run: 14 passed, 1 failed (prose), 6 skipped (five because no file they read changed, improv because it needs a port).
**Reviews**
- Round 1 (moonpi's PIO program and engine, before the rewrite): `shown` froze at the last good rate while every submit failed: flagged, done (a failed submit moves the rate window, so the rate falls to 0, and the seam reports the count).
- Round 1: the encode ran in series with the submit, so the second encoded buffer protected nothing: flagged, done (an encode thread and a triple encoded buffer, James's decision for a real double buffer).
- Round 1: the DMA feed runs behind the wire above 5 MHz, and the program called underrun harmless: flagged, done (hub75.pio says a stall lengthens the stalled word, lit or dark, and the seam warns above the benched 20 MHz, a warning in place of a cap, as decided).
- Round 1: pico-examples and pimoroni-pico uncredited, and a sentence in hub75.pio at odds with the hzeller pin facts: flagged, done (hub75.pio, `@attribution pico-examples, pimoroni-pico` on hub75_pio_engine.h, the attributions rows).
- Round 1: `__BYTE_ORDER__` breaks an MSVC build: flagged, done (`std::endian`, and the engine kept out of MSVC builds; the Windows build itself is round 9's W1).
- Round 1: shutdown kept every frame buffer: flagged, done (freed after both joins and any publish in flight).
- Round 1: the program length taken from the wrap bounds: flagged, done (`std::size` of the program, and a static_assert that both edge variants match).
- Round 1: British spellings and `--` dashes: flagged, done.
- Round 1: a redundant copy of each lane's strip: flagged, done.
- Round 1: brightness read once per lane: flagged, done (once per frame).
- Round 1: half of a rule that could not fire (a uint8_t times a uint8_t past 65,535): flagged, done.
- Round 1: no compile-time check that the lane pins fit the OUT range: flagged, done (`pinsFitWideWord`).
- Round 1: no test ties the checked-in program words to the pin count and the cycles per pixel clock: flagged, deferred: the engine's plumbing may be reworked (James: "we may need to replumb anyhow"); cases already pin the program each clock edge loads and its length (round 3's T-03).
- Round 1: two unsourced figures in hub75.pio: flagged, partly: the 20-30 ns strobe figure is gone, the strobe's width left to the driver chip's datasheet; the side-set precedence's RP2040 datasheet citation for RP1's PIO is deferred, since the plumbing may be reworked.
- Round 1: rate and refresh readouts left stale after shutdown: flagged, done (zeroed).
- Round 1: `PICO_NO_HARDWARE` leaked into the translation unit: flagged, done (`#undef`).
- Round 1: Hub75Encode.h named the bus output as its one caller, and the engine is a second: flagged, done (it names both).
- Round 2 (moonpi's backend and C API, against piolib and the RP1 kernel driver): the blank-first shutdown could stop the state machine on a lit word on kernels from 6.18.39: flagged, done (the blank covers the DMA ring).
- Round 2: a wedged state machine exits the process on 6.12 and hangs the close from 6.18.39: flagged, done in James's order: the bounded join, then a wedged spare state machine on the wall (6.18.60: the submit blocks until a signal, other state machines run on), then the fork's patch (d59c22e) returning -ETIMEDOUT and -EREMOTEIO.
- Round 2: the backend's "frame done" contract held for 6.12 only, and the stub modeled only 6.12: flagged, done (both kernels' semantics in hub75_pio_backend.h, and the stub's Ring model).
- Round 2: the `pio0` macro exits the process on a failed open: flagged, done (`pio_open(0)` once, its errno reported; piolib still exits if it cannot start its IRQ thread).
- Round 2: `hub75_pio_init_sm` checked an error piolib leaves unset: flagged, done (it returns nothing, and its header says why).
- Round 2: the state machine's configuration leaned on piolib's thread-local current instance: flagged, done (`pio_select` first).
- Round 2: the panels take GPIO 2 to 27 from whatever kernel driver owns them: flagged, done in the docs (hub75_board_pins.h names the config.txt lines); round 7 kept it to docs, since no stable interface says which driver owns a pin's mux.
- Round 2: the `piollib` file name and `--` dashes: flagged, done.
- Round 2: the permission message guessed the group: flagged, done (the node's owner, group and mode, and round 7's H1).
- Round 2: two error messages dropped the errno: flagged, done.
- Round 2: a piolib parameter assertion refuses the program's pins (base 2 plus 26 pins reaches 28): flagged, done (`PARAM_ASSERTIONS_DISABLE_ALL=1`, PUBLIC, in CMake).
- Round 2: a SIGTERM inside a submit could tear one frame: flagged, done (stop signals blocked on the refresh thread).
- Round 2: stub details: flagged, partly: an unstarted submit answers -ENODEV and a start requires an open (done); the capture comment says frames past its 1 MiB cap are read back truncated, the cap kept at 1 MiB; the capture still allocates a copy per submit, in test code.
- Round 2: the FIFO depth claims: flagged, done (hub75_pio_backend.h, hub75_pio_c_api.h and .c say 8 words per direction and that the sources leave the joined depth unstated).
- Round 2: a reopen on another state machine leaves the old DMA claim held: flagged, done (the shim prefers the last state machine; round 7 read both kernels' reconfigure path).
- Round 3 (moonpi's host test port and tests, by mutants): the seam's real-engine branch ran on the bench alone: flagged, done (Stub mode).
- Round 3: a stub that could not fail: flagged, done (faults on open, start, submits and the encode).
- Round 3: nothing checked what the engine hands the backend: flagged, done (the stub records the start configuration, the blanks and each frame; cases for the edge's program, the divider, the length and the blank's depth).
- Round 3: the engine tests ran one lane at full brightness: flagged, done (a three-lane case and the brightness cases).
- Round 3: the recorder had no rate lever: flagged, done at the seam (`setTestHub75PioFps`, `Stalled`, `SubmitErrors`); the output's readout cases come with 3b.
- Round 3: `realOpen_` a plain bool across tasks, its contract unstated: flagged, done (atomic, the one-task rule on `hub75PioOpen`).
- Round 3: the stub modeled only 6.12's blocking submit: flagged, done (the Ring model, with a switch to Blocking).
- Round 3: `waitForWord` copied 2,048 words at most: flagged, done.
- Round 3: cases skipped on a piolib build counted as passes: flagged, done (compiled only where they run).
- Round 3: a core test included the light bench: flagged, done (the guards in hub75_port.h).
- Round 3: stale seam text (an empty warning, the 6.18.60 note, the kernels the gate admits): flagged, partly: `hub75PioWarning` carries the clause above 20 MHz and hub75_pio_backend.h states each kernel's semantics (done); the rest of the warning surface and platform_host_pio.cpp's "6.18.60 ... runs it again" are deferred, since the plumbing may be reworked.
- Round 3: the recorder and the engine met in no test: flagged, done (Stub mode).
- Round 3: a second bus guard beside `PortGuard`: flagged, done (the PIO guards sit beside it; the light tests' guard comes with 3b).
- Round 4 (moonpi's light side and CMake): CMake for the decided submodule: flagged, done (the `mm_piolib` block as proposed, with `MM_REQUIRE_PIOLIB`).
- Round 4: the rpi sources in the Windows build: flagged, done (engine sources under `NOT MSVC`, the option rules in a file every host builds).
- Round 4: the depth range written as literals: flagged, done for 3a (the engine's rule in hub75_pio_options.h bounds the depth by `kHub75EncodeMaxBitDepth`; the output's range takes it in 3b).
- Round 4: where the PIO credits live: flagged, done for 3a (`@attribution rpi-rgb-led-matrix` on hub75_board_pins.h; the output's own line comes with 3b).
- Round 4: a saved PIO card losing its settings on a boot without the PIO (R-01): flagged, deferred to 3b, where the light side and its docs land.
- Round 4: the PIO output on the heap, outside the memory readout and the module contract (R-02): flagged, deferred to 3b, where the light side and its docs land.
- Round 4: `hub75HoldWords` absent upstream, which the canvas calls (R-05): flagged, deferred to 3b, where the light side and its docs land.
- Round 4: the scan derived from rows, shutting out panels the engine drives (R-07): flagged, deferred to 3b, where the light side and its docs land.
- Round 4: the sibling claim's boot-order rule undocumented (R-08): flagged, deferred to 3b, where the light side and its docs land.
- Round 4: the quoted rates being wire rates (R-09): flagged, deferred to 3b, where the light side and its docs land.
- Round 5 (U1, the seam and the test port): a test pinned the one-frame blank as behavior: flagged, done (it asserts the ring-deep blank).
- Round 5: the "show no frame while submits fail" check compared a count with itself: flagged, done (it waits for five more failures, then checks both counts).
- Round 5: the stub's submit fault returned -ETIMEDOUT, which the backend did not return: flagged, done (-EIO, or the code a test sets; with the fork's patch -ETIMEDOUT returns too, and a case covers it).
- Round 5: the stub could not show an early stop or the kernel's limits: flagged, done.
- Round 5: the Windows build broken from this change on: flagged, done in round 9's CMake.
- Round 5: the one-task rule rests on two core behaviors left unstated: flagged, done (platform_host_pio.cpp's "One task" names both; 3b pins the driver's Tree scope).
- Round 5: a case still an empty pass on piolib builds: flagged, done.
- Round 5: the stub's upper time bounds could flake under load: flagged, done (10 kHz, a 200 ms margin).
- Round 5: a stale capture comment: flagged, done.
- Round 5: brightness holding across opens, undocumented: flagged, done (`hub75PioCorrection`'s line).
- Round 5: platform.h at 1,802 lines with the PIO block: flagged, done (Hub75Pio.h; platform.h stays at its 1,713).
- Round 5: an S3 build for the ESP32 port's `Pio` guard and the inline label: flagged, done (the S3 builds at the gate).
- Round 6 (U2, the engine's threads and shutdown, by mutants): every close while wedged paid the 3 s deadline again: flagged, done (only the first does, with its case).
- Round 6: the triple buffer's handoff unpinned, a broken handoff surviving every case: flagged, done (a deterministic case on the slots, and the torn-frame case paced).
- Round 6: a submit stuck in the kernel froze the rate: flagged, done (`stalled()`, and the rate reads 0 meanwhile).
- Round 6: the backend header still described a synchronous submit: flagged, done in round 7.
- Round 6: the publish handshake's ordering uncommented, and one path skipping its wait: flagged, done (the seq_cst note, the wait in `releaseBuffers`).
- Round 6: the early-FIFO case had power at 8-bit only: flagged, done (it records whether a frame chunk was in flight).
- Round 6: the warning wrote "20 MHz" beside the constant that holds it: flagged, done (formatted from `kPioBenchedPixelClockHz`).
- Round 6: the idle encode thread polls every 500 µs: flagged, deferred: the engine's plumbing may be reworked (James: "we may need to replumb anyhow"); the thread is off the render path.
- Round 6: Windows still open: flagged, done in round 9.
- Round 6: the engine's destructor detaches a thread that may still read it: flagged, done (the seam's engine lives for the process).
- Round 7 (U3, the backend and C shim, against piolib and both kernels): the permission message could name group root: flagged, done (the group named only when the node grants it read and write, a udev rule pointed to otherwise).
- Round 7: the pin conflicts missed I2S and PWM: flagged, done.
- Round 7: the C shim's own logic ran on the Pi alone: flagged, done (unit_platform_hub75pio_c_api.cpp over a piolib stand-in).
- Round 7: piolib scans for /dev/pio* once a process: flagged, done (the message says a node that appears later needs a restart).
- Round 7: `getpwuid` and `getgrgid` are not reentrant: flagged, done (the `_r` forms).
- Round 8 (U5, the light side): five check_docgen errors once the files are staged: flagged, done for 3a (the two dangling `@xref`s in hub75_pio_backend.h, and `hub75.pio.h` exempted as generated); the class comment and help.json come with 3b.
- Round 8: docgen warnings rising by 38 in PR 3's new files: flagged, done (1,708, the ratchet's count).
- Round 9 (U4, CMake and CI): MSVC reasoned about, unbuilt: flagged, open: the MSVC Windows build is verified by CI on the pull request (release.yml's Windows job).
- Round 9: the arm64 tarball, bare program and container image carried piolib without its notice: flagged, done (the tarball's COPYRIGHT, the copyright file in both container images, the release asset beside the bare program and the attributions row; James judged the asset with the page enough for BSD-3 clause 2).
- Round 9: the C shim's test relying on link order where piolib is linked: flagged, done (the file compiles to nothing there, and test/CMakeLists.txt says so).
- Round 9: the Debian copyright stanzas (GPL-3+, piolib's years, the amd64 package): flagged, done.
- Round 9: gcc-12 `-Werror` failures in the test build: flagged, accepted: they are main's (Mdns.h:42, unit_StateDocument.cpp:432), and CI builds the tests with other compilers.
- Round 9: the aarch64 container run before the PR: flagged, done (3,566 cases passed, 239 of them PIO and HUB75, with piolib linked, on an earlier whole-PR-3 tree with piolib at bb3e262).
- Round 10 (U5 round 2, the machine query): a Pi 5 in a container reads as Other: flagged, done (the cpuinfo Model line answers when the device tree cannot be read).
- Round 10: `brcm,bcm2712` matched by exact length: flagged, done (a prefix).
- Round 10: the earlier-Pi test loop read each list's first string only: flagged, done (`sizeof`).
- Round 11 (U6, the docs): the container case missing from the docs' "Which output" (D1): flagged, deferred to 3b, where the light side and its docs land.
- Round 11: plan text in the bench reference page (D2): flagged, deferred to 3b, where the light side and its docs land.
- Round 11: a sentence describing its own text (D3): flagged, deferred to 3b, where the light side and its docs land.
- Round 11: the PWM row naming one overlay (D4): flagged, deferred to 3b, where the light side and its docs land.
- Round 11: an effect of `latchBlank` nothing measured (D5): flagged, deferred to 3b, where the light side and its docs land.
- Round 11: the hold-words rule worded loosely (D6): flagged, deferred to 3b, where the light side and its docs land.
- Round 11: the bench page's encode remark describing moonpi's architecture (D7): flagged, deferred to 3b, where the light side and its docs land.
- Bench (U7, the Runner on the wall): the tests read the real machine, so on a Pi 5 two cases would open the real /dev/pio0: flagged, done (the test binary rests at Other and refuses real opens before piolib).
- Bench: the .deb's postinst gave the service user no access to /dev/pio0: flagged, done (the node's own group).
- Round 12 (the test isolation): a direct engine open passed the seam's gate: flagged, done (the gate sits in the backend factory too).
- Round 12: static initializers ran before the listener's first reset: flagged, done (main resets first).
- Round 12: `exit(1)` inside a reporter callback could cut the JUnit report: flagged, done (an explicit main).
- Round 12: the scenario runner could open the real PIO: flagged, done (its main sets both levers).
- Round 13 (pre-flight, the gates on the whole PR 3 tree): check_code rose 1,730 → 1,737 on 5880449: flagged, done for 3a, which measured 1,728 there and 1,727 on fda0318 (tables and helpers in the machine parsers, `realOpenRefusal`, the stub's submit split, test helpers, `readNode`'s buffer off the stack).
- Round 14 (the split): code.json at 1,728 missing from 3a: flagged, done.
- Round 14: two 3a comments named 3b-only code: flagged, done (reworded).
- Round 14: `hasHub75Pio` defined in 3a and read in 3b alone: flagged, done (it moves to 3b).
- Round 14: 3a ships the packaging with no path to the PIO in its driver: flagged, done (stated here: the driver arrives in 3b).
- Round 14: the submodule pinned at the patched d59c22e: flagged, done.
- Claim check (the checker on these drafts, against the tree): hub75_board_pins.h's lead named the Pi 3/4 engine and hub75_gpio_pins.h, which 3a lacks: flagged, done (it names the PIO engine, whose bits hub75_pio_pins.h builds).
- Claim check: hub75_board_pins.h named "the PWM overlays" and gave `dtoverlay=pwm` alone: flagged, done (PWM on GPIO 12, 13, 18 and 19 when a PWM overlay is loaded; no PWM overlay, `dtoverlay=pwm` or its variants).
- Claim check: Hub75Pio.h's lead listed four of the six kernel drivers whose pins the panels take: flagged, done (I2S and PWM added).
- Claim check: `hub75PioPush`'s comment said the refresh thread encodes: flagged, done (the encode thread encodes it and the refresh thread submits it).
- Claim check: platform_host_pio.cpp said the engine drives the panels from its refresh thread, in its lead and at the push: flagged, done (its own encode and refresh threads).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the
|
There was a problem hiding this comment.
🟡 Changes recommended
Shutdown defects can cause use-after-free or indefinite hangs, while test changes introduce Windows link failures, Linux assertion failures, and unintended access to live panels.
8 open issues
Run blank submission within the bounded worker shutdown · New Keep backend state alive until a detached worker exits · New Restrict missing-piolib test to builds without piolib · New Compare EBUSY text against the platform's strerror result · New Use the cross-platform test accessor for backend opens · New Make the package fixture independent of host license paths · New Apply recorded brightness when opening the seam · New Handle allocation failures and release partial buffers · New
What changed in this PR
Adds the platform foundation for Raspberry Pi 5 HUB75 output: a PIO engine behind a host-facing interface, machine detection, and packaged piolib support. Driver integration remains in PR 3b; existing HUB75 driver options stay unchanged.
Changes:
- Adds asynchronous encoding and refresh, triple buffering, PIO backends, and shutdown handling.
- Builds piolib from a pinned submodule on Linux arm64 and distributes its license with release artifacts.
- Adds hardware-isolated tests and updates build checks, documentation, and metrics.
| File | Description |
|---|---|
test/unit/test_main.cpp |
Sets hardware-safe defaults and checks real-backend usage. |
test/unit/light/hub75_port.h |
Adds PIO test guards and host overrides. |
test/unit/core/unit_platform_machine.cpp |
Tests machine detection and overrides. |
test/unit/core/unit_platform_hub75pio_stub.cpp |
Tests stub timing, faults, and shutdown records. |
test/unit/core/unit_platform_hub75pio_piolib.cpp |
Tests backend behavior through a scripted shim. |
test/unit/core/unit_platform_hub75pio_options.cpp |
Tests shared option validation. |
test/unit/core/unit_platform_hub75pio_c_api.cpp |
Tests the C shim with fake piolib calls. |
test/unit/core/piolib_fake/piolib.h |
Declares the piolib test stand-in. |
test/unit/core/hub75_engine_bench.h |
Adds shared engine test helpers. |
test/scenario_runner.cpp |
Disables real PIO access in scenarios. |
test/CMakeLists.txt |
Registers platform and engine tests. |
src/platform/rpi/hub75.pio.h |
Adds generated PIO instructions. |
src/platform/rpi/hub75.pio |
Defines rising- and falling-edge PIO programs. |
src/platform/rpi/hub75_pio_repack.h |
Declares slot packing and latch blanking. |
src/platform/rpi/hub75_pio_repack.cpp |
Implements wide-word packing. |
src/platform/rpi/hub75_pio_pins.h |
Defines and validates PIO pin positions. |
src/platform/rpi/hub75_pio_options.h |
Defines reusable option rules. |
src/platform/rpi/hub75_pio_options.cpp |
Validates PIO geometry and settings. |
src/platform/rpi/hub75_pio_engine.h |
Declares the engine and lifecycle contract. |
src/platform/rpi/hub75_pio_engine.cpp |
Implements encoding, refresh, and shutdown. |
src/platform/rpi/hub75_pio_c_api.h |
Declares the C interface to piolib. |
src/platform/rpi/hub75_pio_c_api.c |
Wraps piolib configuration and transfers. |
src/platform/rpi/hub75_pio_backend.h |
Defines backend operations and clock calculation. |
src/platform/rpi/hub75_pio_backend.cpp |
Adds backend selection, gating, and diagnostics. |
src/platform/rpi/hub75_pio_backend_stub.h |
Exposes stub faults and records. |
src/platform/rpi/hub75_pio_backend_stub.cpp |
Simulates blocking and queued transfers. |
src/platform/rpi/hub75_pio_backend_piolib.cpp |
Implements the real PIO backend. |
src/platform/rpi/hub75_board_pins.h |
Defines the active-3 adapter pin map. |
src/platform/platform.h |
Adds the PIO backend enum and shared labels. |
src/platform/machine.h |
Declares machine classification and test overrides. |
src/platform/Hub75Pio.h |
Defines the public PIO interface and test port. |
src/platform/Hub75Encode.h |
Updates documentation to name the engine caller. |
src/platform/host/platform_host.cpp |
Delegates PIO availability to its interface. |
src/platform/host/platform_host_machine.cpp |
Detects Pi models from kernel information. |
src/platform/host/hub75_recorder.h |
Records test frames through triple buffering. |
src/platform/esp32/platform_esp32_hub75.cpp |
Rejects PIO and removes duplicate labels. |
moondeck/ci/release_stage.py |
Copies copyright notices into release containers. |
moondeck/ci/package_host.py |
Adds notices to Linux packages and release assets. |
moondeck/ci/linux/postinst |
Grants the service user the PIO device’s group. |
moondeck/check/check_docgen.py |
Exempts the generated PIO header. |
moondeck/check/check_code.py |
Excludes generated instructions from code metrics. |
moondeck/check/check_clang_tidy.py |
Filters diagnostics for the generated header. |
docs/reference/metrics/repo-health.md |
Refreshes the repository health report. |
docs/reference/metrics/repo-health.json |
Updates recorded size and health measurements. |
docs/reference/metrics/code.json |
Updates code-check totals. |
docs/reference/installing-on-linux.md |
Documents PIO service-group access. |
docs/reference/attributions.md |
Credits PIO sources and documents license distribution. |
Dockerfile |
Carries package notices into container images. |
CMakeLists.txt |
Adds platform sources and arm64 piolib compilation. |
.gitmodules |
Declares the rpi-utils submodule source. |
.github/workflows/release.yml |
Fetches and requires piolib for arm64 releases. |
Review effort: Balanced
| if (!backend_->blankAndStop(blank_.data(), | ||
| static_cast<uint32_t>(blank_.size() * 4), | ||
| error)) { |
There was a problem hiding this comment.
Thanks, fixed in 6a22ca2. The refresh thread now sends the ring-deep blank itself on its way out, so the join deadline covers it, and close makes no submit at all. The stop is firmware-message calls only (disable the SM, set the pins to the dark word, clear the FIFOs), which the kernel bounds, so they run even with a thread stuck in a submit. On the Pi 5 wall (6.18.60), an opt-in test opened and closed the real PIO twice, and OE read high (dark) afterwards.
| /// Shuts the engine down, so a destroyed engine is stopped; an engine whose refresh thread is stuck detaches it. | ||
| ~Hub75PioEngine() { | ||
| shutdown(); | ||
| if (refreshThread_.joinable()) refreshThread_.detach(); |
There was a problem hiding this comment.
Thanks. Leaving this one as it is: the one production engine is created once and never destroyed (*new Hub75PioEngine in platform_host_pio.cpp), so detach-then-free can't happen there. In the tests, the wedge cases now release the hang in a guard before the engine goes, and the real-PIO case keeps a wedged engine alive the same way the seam does. If an engine ever gets a shorter life, this needs revisiting.
| mm::platform::setTestHub75PioReal(true); // with the gate open the refusal is the build's: no piolib here, so nothing real is made | ||
| CHECK_FALSE(engine.open(pioSmall(), error)); | ||
| CHECK(error == "needs a Raspberry Pi build with piolib"); |
There was a problem hiding this comment.
Thanks, fixed in 6a22ca2. A test binary reaches the real PIO only when a case reopens the gate and the run sets MM_TEST_REAL_PIO=1; test_main fails any run that opened it without opting in. One case uses the opt-in. It's built only with piolib and meant for a Pi with MoonLight's service stopped.
| shim.claimRc = -EBUSY; | ||
| CHECK_FALSE(b.backend->open(b.error)); | ||
| CHECK(contains(b.error, "cannot claim a PIO state machine")); | ||
| CHECK(contains(b.error, "Resource busy")); |
| doctest::Context context(argc, argv); | ||
| int result = context.run(); | ||
| if (context.shouldExit()) return result; // a query such as --list-test-cases | ||
| if (const uint32_t opens = mm::platform::pioBackendRealOpens()) { |
There was a problem hiding this comment.
Thanks, fixed in 6a22ca2. test_main now counts through the seam's hub75PioTestRealOpens(), which is defined on every build. No CI job builds the tests on Windows, so this was checked by reading the build files, not by an MSVC build.
| " source repository (https://github.com/MoonModules/MoonLight), and on Debian systems in\n" | ||
| " /usr/share/common-licenses/GPL-3.\n") | ||
| if arch == "arm64": | ||
| body = "\n".join(" " + line if line.strip() else " ." for line in PIOLIB_LICENSE.read_text(encoding="utf-8").strip().splitlines()) |
There was a problem hiding this comment.
Thanks, fixed in 6a22ca2. The fixture pins linux_arch to amd64, so the three tests pass on an arm64 machine without the submodule. The real packaging keeps its licence check.
|
|
||
| void hub75PioCorrection(uint8_t brightness) MM_NONBLOCKING { | ||
| rec_.setBrightness(brightness); | ||
| if (realOpen_.load(std::memory_order_acquire)) engine_.setBrightness(brightness); |
There was a problem hiding this comment.
Thanks, fixed in 6a22ca2. The correction now reaches the engine whether it's open or not. A test pins your example: correction 0, open, push white, and the frame comes out dark.
| if (!admit(o, error)) return false; | ||
| options_ = o; | ||
| sizeTheWall(); | ||
| allocate(); |
There was a problem hiding this comment.
Thanks, fixed in 6a22ca2. Open sums the wall's buffer bytes and refuses a wall that needs more than MemAvailable, with both figures in MB. A bad_alloc that still gets through frees the partial buffers and refuses with a reason.
For the maintainers: there's deliberately no size ceiling. If it fits in the memory available, it opens. Off Linux the memory figure isn't read, so only the bad_alloc backstop applies there. A fixed ceiling would be a policy call, and it's one rule row if you want one.
Nothing changes for a user. The Pi 5 PIO comments say what the code does in positive form, which brings the prose ratchet back to its committed count under CI's Vale, and one PIO test reads the error text from the C library instead of from macOS's wording, so it passes on Linux. KPI: 256lights | Host:2747KB | tick:9/7/7/7/1/7/167/8/7/7us(FPS:111111/142857/142857/142857/1000000/142857/5988/125000/142857/142857) | src:436(107329) | test:309(76539) | functions-over:332 Commit: src +44/-44 lines | test +27/-26 lines | duplicated lines 3597 -> 3597 (+0) **Core** - Hub75Pio.h, machine.h, platform_host_pio.cpp and the src/platform/rpi files (hub75_rpi_common.h, hub75_pio_engine.cpp/.h, hub75_pio_backend.h, hub75_pio_backend_piolib.cpp, hub75_pio_backend_stub.h, hub75_pio_c_api.c/.h, hub75_board_pins.h): 81 comment phrases rewritten in positive form, each keeping its fact; comment text only. **Tests** - unit_platform_hub75pio_piolib.cpp: the refused claim's case compares the message with `std::strerror(EBUSY)`. It read "Resource busy", macOS's text; glibc's is "Device or resource busy", so the case failed on CI's three sanitizer lanes, the only Linux runs that build the fake piolib. - The seven unit_platform_hub75pio*.cpp files, hub75_engine_bench.h and the two lines scenario_runner.cpp gained in the first commit: comment text in positive form. - Host: 3,592 of 3,592 cases; the piolib file's 11 cases pass. **Docs/CI** - docs/reference/metrics: repo-health from collect_kpi. prose.json is unchanged: under Vale 3.21, the version findings.yml installs, the counts equal the committed ones (Negation 4,902, total 6,533). - Gates by run_gates.py on this tree with Vale 3.21 on the PATH: 11 run, 11 PASS, 9 skipped (no file they read changed, or a port to give). **Reviews** - CI on the first commit: check_prose's Negation count rose 4,902 to 4,983 under Vale 3.21: flagged, done (the 81 rewritten). The local gate ran Vale 3.27, which counts this rule lower, so the rise went unseen; the local check now runs CI's version. - CI on the first commit: the sanitizer lanes (address, thread, realtime) failed one case, the EBUSY text: flagged, done. The thread lane reported no race. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks, Anjin, and thanks to Friday's crew: this is a careful piece of work. The seam, the stub backend and the gate in What the review found sound, so it stays as it is through this round: the Three things block the merge, all for you to follow up. 1. Talk to the kernel's PIO interface instead of piolib, and drop the submodule. You asked on Discord about adding a library; here is my answer. A submodule, and one pinned to a personal fork, is against our architecture, so I looked for good reasons to allow it for now and found none:
So: one backend, One detail to get right: This removes the submodule and the fork patch, 2. Keep every blocking submit inside the shutdown deadline, and never free what a stuck thread uses (Copilot on
3. Keep the real backend out of reach on every build (Copilot on Also for this round, since you are doing one anyway:
For 3b, since 3a leaves A lead for later, not for this PR: the kernel's cyclic DMA ( The processes behind this review are in MoonWalk. Looking forward to the next round, and to the panels on the wall. |
…ck memory at open This answers Copilot's review of MoonModules#258. What changes for a user: - Closing the wall can no longer hang on a stuck PIO. If the PIO is stuck, the panel goes dark rather than holding its last row, and the message says whether the stop succeeded. - A wall whose buffers don't fit in the memory available is refused at open, with both figures in MB, rather than crashing. There is no size ceiling: if it fits, it opens. - A brightness set before the wall opens now applies from the first frame. KPI: 256lights | Host:2767KB | tick:10/7/7/7/1/7/164/7/7/7us(FPS:100000/142857/142857/142857/1000000/142857/6097/142857/142857/142857) | ESP32:2402KB | src:436(107670) | test:310(77541) | functions-over:332 Commit: src +567/-195 lines | test +1114/-89 lines | duplicated lines 3597 -> 3597 (+0) **Core** - hub75_pio_engine.cpp/.h, hub75_pio_backend.h, hub75_pio_backend_piolib.cpp, hub75_pio_backend_stub.cpp/.h, hub75_rpi_common.h: - The refresh thread submits the ring-deep blank as it leaves its loop, so the join deadline covers the one call that can block with no timeout (6.18.39 and later). It skips the blank after a failed last submit. - The join deadline scales with the wire time: the last frame plus the blank, doubled for the feed lag, with a 50% margin, and never under 3 s. A slow pixel clock then reads as slow, not as wedged. - The closing thread makes no submit. `blankAndStop` becomes `submitBlank` plus `stop(drain)`, made only of firmware-message calls: disable the SM, set the OUT pins to `kBlankWideWord`, clear the FIFOs, remove the program. - After a clean join with the blank sent, the stop first waits out the blank's wire time, doubled for the feed lag, then polls the FIFO for 100 ms. A FIFO still full is a note in the report, since the disable darkens the panel anyway. - When the deadline passes, the stop runs at once and the engine reports wedged, keeping its buffers. The stop's result is whether the panel is dark: the disable and the pin write succeeded, at this stop or an earlier one. The message says the panel is dark only then; otherwise it names the failure and says the panel may hold its last row. - On the wedged path, a stop that failed runs again at the next shutdown, until the disable and the pin write have both succeeded. On the clean path the backend closes, and a failed stop's text reaches the close error. - A thread that fails to start at open ends in the same bounded shutdown, so open can't hang on a stuck refresh thread. - The shared base's open refuses a running or wedged engine, before the engine's own option check. - A submit after the stop answers -ENODEV, so a thread released late makes no further transfer. - hub75_pio_c_api.c/.h: - A new `hub75_pio_set_pins` for the stop. It shares one helper, `set_out_pins`, with the start, so both write the same pin word and mask. - It and `hub75_pio_set_enabled` return 0 or a negative errno. piolib discards these two ioctls' results, so the shim reads errno and piolib's error flag around each call. - hub75_pio_backend.cpp/.h: - A test binary reaches the real PIO only when its case reopens the gate and `MM_TEST_REAL_PIO=1` is set. - The variable is read at each open, and the refusal names it. Only the value `1` opts in. - test_main fails a run that opened the real PIO unless the run opted in. - The rule is one function of the gate and the opt-in, `pioBackendGateRefuses`. - The gate's calls are named for what they do: `setPioBackendGateOpen`, `setTestHub75PioGateOpen`. - hub75_rpi_common.h, platform.h, platform_host.cpp: - Open sums the wall's buffer bytes and refuses when they exceed MemAvailable, read from /proc/meminfo a line at a time into a 128-byte buffer. Off Linux the figure is 0, which skips the check. - A `bad_alloc` during allocation frees the partial buffers and refuses with a reason. - platform_host_pio.cpp: the brightness correction reaches the engine whether or not it is open. - Hub75Pio.h: the comments on close, stall and the test gate match the new behavior. - Comments: - hub75_pio_backend.h, "Submit semantics": corrected per kernel line (6.6, 6.12 and 6.18.29 to .34 wait with a 1 s timeout per wait; 6.18.39 and later queue with no timeout), with the signal cases, issue #7642 and stock piolib from bb3e2622. - hub75_rpi_common.h: EINTR is possible from 6.18.53 only, for a handler without SA_RESTART. - hub75_pio_c_api.c: rewritten to match. **Tests** - unit_platform_hub75pio_buffer.cpp: - the refresh thread blanks and the closing thread makes no submit; - the blank is skipped after a failed submit; - a stuck submit ends with a stop without drain, the pins dark, the buffers kept and a later clean shutdown, and a clean shutdown stops with drain; - a failed stop on the wedged path says the panel may hold its last row; - a failed stop on the clean path is reported; a failed wedged stop is retried by the next shutdown, says dark once it works, and names the failure when it fails again; - an encode or refresh thread that fails to start at open ends bounded, with the refresh thread hung or free; - a wedge case that fails still releases the hung submit before the engine goes, so the rest of the run reports; - at a slow pixel clock a healthy shutdown finishes, since the deadline follows the wire time; - the memory refusal, exact to the byte, with the refresh rate back at 0, and the `bad_alloc` backstop; - a stuck submit's report says the backend stays held until a close after the thread returns. - unit_platform_hub75pio_piolib.cpp, unit_platform_hub75pio_c_api.cpp: - the stop's order, with no transfer; - drain and no drain; - -ENODEV after a stop; - a second stop repeats both calls while either failed, and its result follows them; - a failed disable or set-pins fails the stop and names the step; - the wait following the ring and clock; - the pin word and mask the same at start and stop; - errno and piolib's error flag reported by the shim. - unit_platform_hub75pio_stub.cpp, unit_platform_hub75pio_engine.cpp: - the ring model's stop; - a FIFO that stays full is a note on a dark panel, and the stop waits for the blank only when it went out; - the base refuses an open while running or wedged; - a stop while a submit hangs; - the wire-time arithmetic; - the `MM_TEST_REAL_PIO` gate on every build, and that values other than `1` (`0`, empty, `true`, `yes`, padded) do not opt in; - the no-piolib message where piolib is absent; - the gate rule's rows, the program's included; - built only with piolib: two open and close cycles on the wall's PIO when the run opts in and the seam would open PIO on that host, each shutdown finishing with no shutdown error; otherwise the case says it was skipped. - unit_platform_hub75pio.cpp: a correction set before open holds across it; a close whose stop failed publishes a close error, and a later close whose retry fails keeps it. - unit_platform_memory.cpp (new): the MemAvailable line parse. - test_main.cpp: counts real opens through the seam's `hub75PioTestRealOpens()`, which is defined on every build, MSVC included, and fails the run on one unless it opted in. - test_package_deb.py: the fixture pins `linux_arch` to amd64, so the tests pass on an arm64 machine without the submodule. - Before the fix: - the brightness case failed with 1,520 lit words, against 0 expected; - the three packaging cases failed with FileNotFoundError on an arm64 Mac; - the three shutdown cases failed on the old engine; - each later case was checked by a one-line mutant of the code it pins, except the Linux-only /proc/meminfo read, test_main's opted-in branch and the opted-in real-PIO case, which a macOS run cannot reach. - Host: 3,637 of 3,637 cases. **Docs/CI** - docs/reference/metrics: repo-health from collect_kpi. prose.json is unchanged under Vale 3.21. - Gates by run_gates.py on this tree with Vale 3.21 on the PATH (run-20261119-165946): 13 passed, 1 cached from a pass on the same inputs, 7 skipped (no file they read changed, or a port to give), 0 failed. - Bench, Pi 5 on kernel 6.18.60, with a probe running this program and pin start (run pi5-c1-probe-run-1119-022713-376): - With the SM disabled while lit, setting the dark word turned OE high. - Set pins and clear FIFOs each returned in under 0.04 ms while another thread was held in a submit, in 5 of 5 rounds. The disable was issued before that thread was held, so a disable with a thread already blocked is unmeasured. - Bench, the same Pi with this tree built there against the pinned piolib (runs pi5-pr3a-fix-build-1119-161357-421, pi5-pr3a-fix-test-1119-161515-380, pi5-pr3a-fix-real-pio-1119-161503-681): - with /dev/pio0 masked, 3,602 passed, 0 failed, 10 skipped, and the suite opened /dev/pio0 0 times; - with MoonLight stopped and `MM_TEST_REAL_PIO=1`, the opted-in case ran its two cycles on the wall's PIO: 17 of 17 assertions, and OE read high afterwards; - 6.12 is unchecked. **Reviews** - Copilot on MoonModules#258, C1, a blank submitted after the bounded join could hang close: flagged, done (the stop above, after a study of the RP1 PIO driver per kernel line). - C2, the destructor detaching a stuck thread: declined. The one production engine is never destroyed, and the wedge test releases the hang before the engine goes. - C3, a test reaching the real PIO on a build with piolib: flagged, done (the `MM_TEST_REAL_PIO` gate). - C4, the EBUSY text: already done in 548bbb5. - C5, an unresolved symbol in an MSVC test build: flagged, done. - C6, the packaging fixture on arm64: flagged, done. - C7, a correction set before open being lost: flagged, done. - C8, allocation throwing out of open: flagged, done (the memory check and the backstop). - Fable, pre-commit round on this change: all done. - Which drain the engine passes was unpinned: done (the stub records it). - "The panel is dark" was written before the stop ran: done (worded from the stop's result). - A figure in this message no log carried: done (dropped). - The bench wording overstated the disable: done. - An 8 KB stack buffer for /proc/meminfo against the 512-byte frame rule: done (a line at a time). - A fixed 3 s deadline made a slow healthy submit a permanent wedge: done (the deadline follows the wire time). - Nits: the opt-in value, the stub's dark flag at start, a stale comment, a PR named as merged, the gate's names, a 1 ms wall-time bound in a test, now 800 ms: done. - Opus, pre-commit round 2: seven findings, all done. - A failed stop was lost on the clean path and never retried on the wedged one: done (the retry and the close error above). - A cap on the blank wait could never bind: done (removed). - An unbounded join after a thread failed to start: done (the bounded shutdown). - Nits: a comment that said the stop always darkens, and three wordings in this message: done. - Fable, pre-commit round 3: all done. - A FIFO that stayed full reported a dark panel as maybe lit: done (the stop's result is the panel's state). - Three lines no test pinned (the pin-write retry, the program's gate, a refresh thread failing to start): done. - The wedge refusal sat in the engine's option check, not in the shared base: done. - `MM_TEST_REAL_PIO=1` opened nothing: done (the opted-in case). - Nits: dead code in close and the memory reader, a failed stop counted as a submit error, four comments, three wordings here, a failing wedge case that crashed the run: done. - Opus, pre-commit round 4, on round 3's fixes only: all done. - The memory refusal no longer zeroed the slot count and the rate, so the refresh rate read nonzero after it: done (the release restored and pinned). - The opted-in case reopened on a kernel the seam refuses for its reopen stall: done (it skips there). - Nits: a wedged engine destroyed by the case's guard, three comments and the wedge report's text, three wordings here, an unpinned clear in the stub: done. - Fable, pre-commit round 5, on round 4's fixes only: no bug and no behavior should-fix, so the rounds end. Its test fix, test nits and wordings: done. - The opted-in case's skip message printed the refusal as an address: done (printed as text). - Nits: the wedge report's new text unpinned, a check under the wrong label, a repeated stub check, four comments, one wording here: done. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks, ewowi, for the careful read, and for the answer on the library question. An apology first: I read your review only after pushing 6a22ca2 and replying on Copilot's threads, so two of those replies (C2 on the destructor, C8 on the ceiling) say the opposite of what you ask here. Your review wins, and those two are superseded by this. Where 6a22ca2 stands against your points, and what the next round does:
The rest:
Friday's crew is on it. Thanks again. |
This answers ewowi's review of MoonModules#258. What changes for a user: - On a Pi 5, MoonLight talks to /dev/pio0 through the kernel's own interface. A transfer that times out comes back as an ordinary error, and MoonLight keeps running. - MoonLight no longer needs piolib, a submodule or libpio0, so the arm64 package depends on nothing that a distribution may lack. - A start checks every step and names the one the kernel refused. piolib dropped those results. - A wall whose buffers total more than 256 MiB is refused, and the message gives its figure and the limit in MiB. The 256x192 wall needs 1.52 MiB at 6 bits and 1.80 MiB at 8. - A pixel clock under 50 kHz is refused with its reason. KPI: 256lights | Host:2767KB | tick:10/7/7/7/1/7/162/7/7/7us(FPS:100000/142857/142857/142857/1000000/142857/6172/142857/142857/142857) | ESP32:2402KB | src:438(108056) | test:308(77593) | functions-over:332 Commit: src +877/-705 lines | test +1570/-1040 lines | duplicated lines 3597 -> 3597 (+0) **Core** - hub75_pio_backend_rp1.cpp/.h, hub75_pio_rp1_uapi.h, hub75_pio_rp1_device.cpp (new): - The backend speaks /dev/pio0 through a small device seam. On Linux the real device is open, ioctl and close. - It uses the kernel's uapi interface (include/uapi/misc/rp1_pio_if.h, "GPL-2.0 + WITH Linux-syscall-note"). Only the structs, numbers and constants it uses are redeclared, each citing the header's lines on rpi-6.12.y and rpi-6.18.y. The layout is pinned by static_assert on size and on every field's offset, and on Linux against the kernel's own _IOW/_IOWR. - The registers (CLKDIV, EXECCTRL, SHIFTCTRL, PINCTRL) are packed from the kernel's include/linux/pio_rp1.h and the RP2040 datasheet's PIO tables, and reproduce the values piolib wrote. - Start: - claims an SM into a buffer with room for the copy-back that released kernels overrun; - configures the ring with CONFIG_XFER32 (64 KiB buffers); - adds the program; - sets the pins to the idle word, then the pindirs and the GPIO function; - inits the SM, clears the FIFOs and enables; - fails naming any step the kernel refuses. - Submit: one XFER_DATA32 call per whole frame, which the driver spreads over the ring. -errno on failure, -ENODEV after a stop, and the arguments rebuilt after an EINTR, which rewrites them. - Stop: unchanged in meaning. The stop disables the SM, sets the pins to the dark word, clears the FIFOs and removes the program, and repeats until the disable and the pin write have both succeeded. Its result is whether the panel is dark. A TX FIFO state that can't be read ends the drain wait with its own note. - Close releases everything: the kernel frees the SM, the DMA and the program with the file. - Removed: the rpi-utils submodule and .gitmodules entry, with its fork pin; hub75_pio_backend_piolib.cpp; hub75_pio_c_api.c/.h; mm_piolib with its `-w` and assertion workarounds; MM_REQUIRE_PIOLIB and MM_HUB75_PIO_HAVE_PIOLIB. The release job no longer fetches submodules. - hub75_pio_backend.cpp/.h: - The rp1 backend is the one real backend, on every Linux aarch64 build. A build without it is refused with "needs a Raspberry Pi 5 build (Linux aarch64)". - The test gate is open or closed. A test binary closes the gate before every case, a case that reopens it is refused before any backend opens, and the gate's refusals are counted on every build, so the one line between a test and /dev/pio0 is pinned on every CI host. - `MM_TEST_REAL_PIO` and its opted-in case are gone, so no test reaches the real backend. - hub75_pio_engine.h, hub75_pio_engine.cpp: the destructor joins a refresh thread that a shutdown found stuck, with no deadline, and never detaches it; then it runs the shutdown again for the stop's retry, the close and the buffers. The one production engine lives as long as the process. - hub75_pio_options.cpp/.h: - The ceiling is `kPioMaxBufferBytes`, a rule over `hub75PioBufferBytes`, which is the same total the engine allocates. - The floor is `kPioMinPixelClockHz`. The program takes 5 cycles a word, one word per pixel clock, so below about 16.4 kHz a 64 KiB chunk outlasts 6.12's 1 s wait. That is where a transfer can return 0 with the frame cut short; 50 kHz is three times that. - platform.h, platform_host.cpp, hub75_rpi_common.h: the MemAvailable check and its /proc/meminfo reader are removed, so the ceiling is the one limit. The `bad_alloc` backstop stays. - hub75_pio_backend.h, "Submit semantics" and "Control calls": rewritten in ioctl terms, each fact cited to the kernel's driver or firmware file and line, per kernel line. PR #7771 is recorded as merged (2026-11-19). - platform_host_pio.cpp: the refusal of kernels 6.18.39 to 6.18.59, whose reopen stall was measured through piolib, is kept. Its comment says whether the stall still happens without piolib is a bench question. - Packaging (package_host.py, release.yml): piolib's BSD stanza and the COPYRIGHT-linux-arm64 asset are gone; the copyright file is MoonLight's own on every arch. attributions.md credits the Raspberry Pi Linux kernel in piolib's place. - CMakeLists.txt: -Wnon-virtual-dtor applies to every source again, since no C file builds there. **Tests** - unit_platform_hub75pio_rp1.cpp (new, 43 cases) against fake_rp1_pio0.h, a fake /dev/pio0 that models the kernel's claims, programs (a fixed origin included), the per-SM and per-direction DMA, the transfer ring, the control calls and close. It pins: - the open and claim messages, and the claim buffer's room; - the start's order, each refused step, the program's words, and a refused empty program; - the pin word and mask the same at start and stop; - one XFER_DATA32 for a whole 256 KiB frame; - the stop's order, drain, retry and notes, including a FIFO state that can't be read; - -ENODEV after a stop; - a transfer stuck while the control calls return; - each register field at its bit; - the ioctl numbers, and the kernel constants the fake also reads, as literals; - the SM number in every call, on SM 3; - close releasing everything; - EINTR rebuilding the arguments; - removal at a nonzero origin, and a 32-word program; - the open and start guards, including a start after a failed start. - Every case of the piolib backend's tests has an rp1 counterpart: 13 of the 18 under the same name, 5 reworded. The C shim's cases went with the shim. - unit_platform_hub75pio_options.cpp: the floor, the ceiling and its exact boundary. - unit_platform_hub75pio_buffer.cpp: - the buffer total equals the allocation, for the 256x192 wall and for a small one; - a wedged engine whose hang is released is destroyed, the join returns and the backend is closed once, with a guard so a failing check can't hang the run. - unit_platform_hub75pio_engine.cpp: a program's gate opens by default; the closed gate refuses and is counted; the stub is never gated. - unit_platform_hub75pio.cpp: a build without the rp1 backend offers no PIO output on a Pi 5. - Removed: the piolib, C shim, MemAvailable and opt-in cases. - Each new case was checked by a one-line mutant of the code it pins. - Host: 3,651 of 3,651 cases. **Docs/CI** - docs/reference/metrics: repo-health from collect_kpi. code.json, docgen.json and prose.json are unchanged under Vale 3.21. - Gates by run_gates.py on this tree with Vale 3.21 on the PATH (run-20261119-223829): 13 passed, 2 cached from a pass on the same inputs, 6 skipped (no file they read changed, or a port to give), 0 failed. - A Linux aarch64 compile of the backend, the device and the rp1 tests in a container (g++ 11.4, -Wall -Wextra -Werror and the repo's extra warnings): no warning, and the rp1 cases passed, 39 of 39, in the commit review, before its last four were added. - Bench, the Pi 5 wall on kernel 6.18.60, this tree with 3b's light side laid over it, three lanes of two 128x64 panels (256x192), 8-bit: - Built as a release is, by release.yml's build-linux-arm64 job (GCC 12.3.0), like the program it was compared with, which was built from 548bbb5 with 3b on piolib. - The main loop read 965 to 994 fps against that program's 966 to 981. - The main thread took 25% of a core on both, and every other thread the same share. - piolib's interrupt thread is gone. - Runs pi5-install-image-1119-224805-626 and pi5-threads-sample-1119-224818-913, -224833-382, -225015-315. - Ten close-and-reopen cycles in one process (pi5-hub75-reopen-1119-224847-837): 136 fps shown each time, a median 2.01 s (1.95 to 2.06) to a shown rate. This pull request's description had 136 fps and 1.98 s on piolib. - OE read high after a service stop, and the kernel logged nothing (pi5-oe-after-stop-1119-213020-981 and -224948-764). - Built natively on the Pi with build_host.py (GCC 14.2), the masked suite passed 3,720, 0 failed, 10 skipped, and the suite opened /dev/pio0 0 times (pi5-pr3a-fix-test-1119-212806-445). - A native build runs the main loop at about half a release build's rate, for this tree (491 fps) and for the 548bbb5 source alike (493 to 498, pi5-bisect-build-1119-213904-555). - That gap belongs to the build, not to this change, and is not yet explained. - The wall was put back on its previous program afterwards. **Reviews** - ewowi on MoonModules#258 (2026-11-19): - 1, the kernel's ioctls instead of piolib: done (above). One correction to the review: the RP1 peripherals datasheet has no PIO register chapter, so the packing comes from the kernel's pio_rp1.h and the RP2040 datasheet. 65,532-byte pieces were never needed, since XFER_DATA32 takes a whole frame. - 2, the blank inside the deadline: already done in 6a22ca2 (the refresh thread sends it, with the stop signals blocked). The destructor: done (above). - 3, the real backend out of reach: done (above). - The ceiling, the clock floor: done, at 256 MiB and 50 kHz, both proposed to ewowi on the PR. Brightness while closed and the MSVC link: already done in 6a22ca2. The packaging fixture: went with the submodule. - For 3b: the seven points, carried to 3b. - The cyclic-DMA lead: for a measurement after 3b. Cyclic TX was first released in 6.18.60. - Corrections to 6a22ca2's Reviews section: it declined Copilot's C2 (the destructor detaching a stuck thread) and said there was "no size ceiling" for C8. ewowi's review, posted before 6a22ca2 but read after it, asks for both, and this commit does them. - Built in four batches, with one reviewer (Opus) kept on across them: - B1, the backend: 1 bug (a case that would reach /dev/pio0 on aarch64, already fixed by B2), 2 behavior should-fix (a public factory past the gate; a FIFO-state read error reported as "did not drain"), 4 test should-fix, nits: done. - B2, the removals: no bug, no behavior should-fix; 1 test should-fix, 2 wordings: done. - B3, the destructor, the gate, the ceiling and the floor: no bug, no behavior should-fix; 3 test should-fix (one could hang the test run; the gate line was pinned on no CI host), 3 nits: done. - B4, the docs, and a pass over the whole change: no bug, no behavior should-fix; 2 wordings, 3 nits: done. - A fresh reader (Fable) on the whole change at commit: no bug and no behavior should-fix, so the review rounds end here. Its test gaps, nits and wording: done. - Test gaps: the program's words, the gate's default, the SM number in five calls, two kernel constants the fake shared with the code, the stop's wait, two start guards. - Nits: the fake logging calls on a closed device; the destructor using the one teardown after its join. - Wording: a citation to research outside the repository, replaced by kernel sources; a review label in a test; units as MiB; a work plan that still named piolib; five lines of this message. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CI's checks job failed on 05bd1f8. Docgen found 50 errors in two of its new files, and check_code found two duplicated blocks in its new test file. The gates in 05bd1f8's message ran while the six new files were still untracked. check_docgen and check_code measure only the files git tracks, so neither saw them. This commit fixes what they found, and the gates have now run with the files tracked. KPI: 256lights | Host:2767KB | tick:10/7/7/7/1/7/163/8/7/7us(FPS:100000/142857/142857/142857/1000000/142857/6134/125000/142857/142857) | src:438(108056) | test:308(77598) | functions-over:332 Commit: src +42/-42 lines | test +29/-24 lines | duplicated lines 3597 -> 3597 (+0) **Core** - hub75_pio_rp1_uapi.h: a one-line `///<` on each of the 40 struct fields, saying what the kernel's field carries. The file-level line that ran to 415 characters is cut to fit the 400 limit, with its meaning kept. **Tests** - fake_rp1_pio0.h: `///<` on the three FakeTransfer fields. The comments on smOf, claim, addProgram, removeProgram, fifoState, configXfer and transfer are now their declarations' `///`. - unit_platform_hub75pio_rp1.cpp: two repeated blocks become the helpers openStartStop and checkSecondStartRefused. Every check in the four cases that used them stays. - Host: 3,651 of 3,651 cases. **Docs/CI** - docs/reference/metrics/repo-health: measured again with the new files tracked. Platform lines 29,913 -> 30,614, test lines 95,099 -> 96,507, unit tests 3,603 -> 3,646. 05bd1f8's figures left out its own new files. - Docgen: 0 errors and 1,671 warnings, with 28 over-wide doc lines, back to the committed counts. check_code: 1,727 findings, 820 duplicated blocks, back to the committed counts. - Gates by run_gates.py with Vale 3.21 on the PATH (run-20261120-005610): 12 passed, 9 skipped (no file they read changed, a cached pass on the same inputs, or a port to give), 0 failed. **Corrections to 05bd1f8's message** - Its Docs/CI line says the gates passed on "this tree" (run-20261119-223829). They passed with the six new files untracked, so docgen and check_code did not read them, and repo-health did not count them. - Its KPI line was not affected. **Reviews** - A fresh reader (Opus) on the code change, under the convergence rule: no bug and no behavior should-fix. - All 40 field comments match the kernel header on both lines. - With the helpers pasted back in, the test file is byte-identical to 05bd1f8's. - Its nits and wording: done. - The `reserved` fields are described as sent to the firmware with the rest of the struct, which is what both drivers do. - Line 13 names the `uintN_t` types. - A garbled sentence in the fake's claim comment, from before this change. - The helper comment now fits both callers. - A first wording of that comment raised the prose ratchet by one negation (a gate run caught it), so it was reworded. - Left as it is: a failing check inside a helper reports the helper's line, as doctest helpers do. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks Anjin, a08a79d settles the checks: green now. The one red job, the thread sanitizer, is a localhost timing flake in a NetworkReceive test, unrelated to this PR (hardened on next-iteration); I'll rerun it. On your two questions: 256 MiB and 50 kHz are fine as the ceiling and floor. The A/B/A' table on the ioctl backend can come with 3b's bench page, plus a 6.12 run if you have a Pi on that kernel. Two last things before the merge:
With those in, I'll run a last check and merge. |
|
The round on your review is up: 05bd1f8, "Drive the Pi 5 PIO through the kernel's ioctls and drop piolib". The commit message goes through your points one by one. In short:
Both figures are one constant each, so tell me if you'd prefer others. Wall readings on the Pi 5 (kernel 6.18.60, three lanes of two 128x64 panels, 256x192, 8-bit), with 3b's light side laid over this tree:
A side note, since it cost me a detour: a native Still open, for the bench rather than this PR:
The seven points for 3b and the cyclic DMA lead are carried over. CI: 05bd1f8 failed the docs check. My local gates ran while the new files were still untracked, so docgen and check_code skipped them. a08a79d documents the uapi fields and folds two duplicated test blocks, and One job is red on a08a79d, and I don't think it's this PR: Host tests: 3,651 of 3,651 pass. Thanks again for the review. |
ewowi asked on MoonModules#258 that the pull request carry no generated metrics: the merge regenerates them. code.json, repo-health.json and repo-health.md are back to main's content (830ecad), byte for byte. main's code.json holds 1,729 findings and 822 duplicated blocks. This tree measures 1,727 and 820 (check_code), so the ratchet still passes against main's counts. Docgen: 0 errors, 1,671 warnings, unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Both are in at cc23c8d: the three metric files are back to main's content, and the title and description now describe the ioctl backend. CI is green on it, the thread sanitizer included after your rerun. Thanks for the quick turnaround. |
|
Merged, thanks Anjin, and thanks to Friday's crew. What this brings: HUB75 panels driven from a Raspberry Pi 5's PIO through the kernel's own /dev/pio0 interface, with no library and no submodule, the structs pinned against both kernel lines, a stop that blanks within its deadline, and a test gate that keeps every build off the real PIO. From my side the merge only regenerates the metrics; nothing else changed. Looking forward to 3b: the bench page with the A/B/A' table on the ioctl backend, and a 6.12 run if you get the chance. |
Two conflicts resolved: test_main.cpp keeps both sides' per-test resets (the fleet time, the machine and the PIO gate) and main's own main(); release.yml keeps this branch's feed, sorted by semantic-version precedence, over main's sort by publish date. The suite runs in CI on the merge. Also: the sixth commit round's after-action review and steps 29 to 34 in Plan-20261117 (the hook counting -Wfunction-effects, a failing gate's findings kept whole, the gate's firmware in the last bench build, classified changes skipping the firmware, no new behavior in a fix round, the KPI tick every commit); repo-health regenerated by the KPI run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>


PR 3a of the Pi HUB75 series: the Raspberry Pi 5's PIO engine and everything the platform needs for it. MoonLight's own engine drives HUB75 panels from the RP1's PIO behind a seam,
Hub75Pio.h, and talks to/dev/pio0through the kernel's own ioctl interface, with no library and no submodule. A machine query,machine.h, says whether the program runs on an ESP32, a Pi 5, an earlier Pi or another host.The driver arrives in 3b. In this pull request the HUB75 driver offers the two ESP32 backends, as on main, so the card, its options and its saved values are main's and there is no MIGRATING entry. 3a ships the packaging with it (the copyright file, and the .deb giving its service user
/dev/pio0's group), so 3b is the light side alone: the output on PR 2'sHub75Outputinterface, the driver's case tree over the machine, the docs and help. 3b follows once this merges.What it changes.
src/platform/Hub75Pio.h, new: the seam. Open withHub75PioOptions, push packed RGB (returns at once), correction, fps, stalled, submit errors, a warning, the close error, close; and the host test port, with modes Off, Record and Stub. Open, close, push, correction and fps share one task.src/platform/rpi/, new, 19 files: the PIO program (hub75.pioand pioasm'shub75.pio.h), the engine (hub75_rpi_common.h,hub75_pio_engine.*), the repack and pins, the option rules, and thePioBackendinterface with two backends:hub75_pio_backend_rp1.cpp, the real one, over a small device seam (hub75_pio_rp1_device.cpp: open, ioctl, close), with the kernel's structs and numbers inhub75_pio_rp1_uapi.h;hub75Encodeand repacks the three lanes into 32-bit words; a refresh thread submits the newest encoded frame and submits it again until a newer one arrives. Two triple buffers sit between the three. On close, the refresh thread sends a blank as deep as the DMA ring as its last submit, with SIGINT, SIGTERM and SIGHUP blocked, and shutdown joins it within 3 s (longer for a wall that takes longer on the wire). After a clean join the stop waits for the blank to drain from the TX FIFO; it then disables the state machine, sets the pins to the dark word, clears the FIFOs and removes the program, and its result says whether the panel is dark. A stop that fails is tried again at the next shutdown. A refresh thread still stuck in the kernel is reported (wedged), and the engine's destructor joins it with no deadline and never detaches it.src/platform/host/platform_host_pio.cpp, new: the seam on every host. A build without the rp1 backend refuses with "needs a Raspberry Pi 5 build (Linux aarch64)"; the host refuses without/dev/pio0and on kernels 6.18.39 to 6.18.59, which stalled a PIO reopen when I measured them through piolib; a pixel clock above the benched 20 MHz opens with a warning.bad_allocbackstop stays.src/platform/machine.handplatform_host_machine.cpp, new: the device tree'scompatible, else/proc/cpuinfo's Model line (a container that masks the device tree). 3b's driver reads it.docs/reference/attributions.md: rows for pico-examples and pimoroni-pico, whose hub75 programs shaped the engine's, and for the Raspberry Pi Linux kernel, whose ioctl interface the backend redeclares; hzeller's row names rpi-rgb-led-matrix for the pin facts.platform.h:Hub75Backend::Pio, andhub75BackendLabelinline, replacing three copies in two ports (two in the ESP32 port, one in the host's). The ESP32 port refusesPio.Hub75Encode.hnames its second caller, the engine.CMakeLists.txt: the engine on GCC and Clang, the seam on MSVC too. The rp1 backend's logic builds wherever the engine does (GCC and Clang, so every host but MSVC), the device file on Linux, and the backend is chosen on Linux aarch64./dev/pio0, read from the node./dev/pio0(fake_rp1_pio0.h) that models the kernel's claims, programs, DMA, transfer ring and control calls, and an engine bench header. The test binaries close the real backend's gate before every case, count every refusal on every build, andtest_main.cppfails the run if any case reached the real backend.The kernel's interface. The backend uses
/dev/pio0's ioctls from Raspberry Pi's kernel,include/uapi/misc/rp1_pio_if.h("GPL-2.0 + WITH Linux-syscall-note"). It redeclares only the structs, numbers and constants it uses, each citing the header's lines on rpi-6.12.y and rpi-6.18.y, asFirmwareImage.hredefines ESP-IDF's image layout, andstatic_assertpins every size and field offset, and on Linux the numbers against the kernel's own_IOW/_IOWR. Two details from reading both kernel lines:PIO_IOC_SM_FIFO_STATEis_IOWon 6.12 and_IOWRon 6.18, so its number differs; both drivers dispatch on the number's NR and size, and the backend sends 6.18's.PIO_IOC_SM_XFER_DATA32takes a whole frame in one call, and the driver spreads it over its ring of buffers, so a frame goes out as one call.The SM config registers (CLKDIV, EXECCTRL, SHIFTCTRL, PINCTRL) are packed from the kernel's
include/linux/pio_rp1.hand the RP2040 datasheet's PIO tables, and a test pins each field at its bit. Closing the file releases the state machine, the DMA and the program.The size is over the guideline. 53 files, +8,386/−27 against fda0318 (#256), against 400 lines and ten files (
moonwalk/14-merge.yaml):src/platform/rpi/hub75.pio.his pioasm's output (85)src/platform/host/Hub75Pio.h,machine.h,platform.h, the ESP32 port andHub75Encode.h/dev/pio0, the engine bench header, and the test CMake and harnessIt is the first half of PR 3. I split PR 3 after the pre-flight measured 76 files and +9,008/−88, against the 3,000 lines estimated when one PR was chosen. 3a is the platform, which needs no light code; 3b is the light side on top of it. The generated metrics are left to the merge.
Costs, stated rather than fixed.
On the wall. Nothing in MoonLight drives the PIO until 3b, so these readings are of this engine and backend with 3b's light side laid over them, on my Pi 5 wall: three lanes of two 128x64 panels, 256x192, 8-bit, kernel 6.18.60. The program was built as a release is, by
release.yml's build-linux-arm64 job (GCC 12.3.0), and compared with the piolib program built the same way.The A/B/A' table against moonpi, taken on the piolib backend, moves to 3b's bench page, retaken on this backend, with a 6.12 run if I can get a Pi on that kernel. Readings still to take: ghosting at latchBlank 0 and 2, a dark ramp under underrun, the panel dark after a close by eye, heavy against light DMA, 100-cycle runs, and whether the 6.18.39 to 6.18.59 reopen stall still happens without piolib.
Commits.
Look at these first.
hub75_pio_backend_rp1.cppandhub75_pio_rp1_uapi.h: each ioctl call, and the redeclared structs and theirstatic_asserts, against the kernel'srp1_pio_if.hon both lines.Hub75Pio.h: the seam 3b's output calls, and its one-task rule (a push never overlaps a close), which rests onDrivers::preparejoining the encode worker and the driver's Tree scope (platform_host_pio.cpp, "One task").hub75_rpi_common.handhub75_pio_engine.*: the triple buffers, the publish handshake, the join with a deadline, the ring-deep blank, and the destructor's join.hub75_pio_backend.h's "Submit semantics" and "Control calls", per kernel line, cited to the driver's lines.test_main.cppand the backend's gate: the test binaries refuse the real PIO, somm_testson a Pi 5 leaves its panels alone.Two references point ahead to 3b:
hub75_pio_engine.hcites the bench recordhub75-bench.md, which 3b adds, and the pico-examples row linksdrivers.md#hub75, which describes the Pi 5 once 3b's docs land.Open. MSVC: CI's Windows job builds the seam and the option rules, and the engine stays out of MSVC builds; no CI job builds the tests on Windows.
Deferred. Four review items from the first rounds are still open: a test that decodes
hub75.pio.h's words againsthub75.pio,hub75.pio's RP2040-datasheet citation for the RP1, the encode thread's 500 µs idle poll, and the rest of the warning surface.Who did what. I work with agents, and I call them all Friday. This pull request is mostly theirs.
Hub75Bus.handedid.h; PR 2's test port; allocate-and-degrade, so a build without the backend refuses with its reason; and, from ewowi's review, the kernel's own interface in place of a library, declared with a citation asFirmwareImage.hdoes. The PIO program's structure follows the pico-examples and pimoroni-pico hub75 programs, and the pin facts are hzeller's; no code of theirs is adapted.moonpibranch it started from, which Friday and I built together; and my Pi 5 wall, which the agents may bench on.moonpionto main, and the move to the kernel's ioctls. The code, the tests, the packaging and this description are theirs: Claude Opus 5.5 coordinating; Sonnet developers, each kept on across a round's batches; Opus reviewers, kept on across the batches; a Fable researcher who read the ioctl interface at the kernel's source on both lines, with an Opus check of its claims; a fresh reader at each commit (Fable, then Opus); and a Haiku Runner that built, installed and benched the builds on the wall.Tested.
run_gates.pyon a08a79d's tree (run-20261120-005610): 12 passed, 0 failed, 9 skipped (no file they read changed, a cached pass, or a port to give). The host tests: 3,651 of 3,651.checks, the five builds (Android, Linux arm64 and x64, macOS, Windows) and the address, thread and realtime sanitizers.-Wall -Wextra -Werrorand the repository's extra warnings): no warning, and the rp1 cases passed, 39 of 39, before the last four were added./dev/pio0masked, and opened it 0 times.Not tested: the rp1 backend on a 6.12 kernel; 3a alone on the wall (the readings above lay 3b's light side over it); the tests under MSVC; and the readings listed under the wall.
🤖 Generated with Claude Code