Skip to content

Latest commit

 

History

History
873 lines (789 loc) · 51.5 KB

development.md

File metadata and controls

873 lines (789 loc) · 51.5 KB

Developing piegpu

How the RPi side works inside, for changing it. Elsewhere:

Supported for now: the Raspberry Pi Zero / Zero W and the Zero 2 W; where a model is named below, the fact was measured on that one.

The I2S link

  • Receive: cyclic DMA from the PCM receive FIFO into a 1 MB ring buffer. The CPU parses packets from the ring and drives READY from its fill level.
  • Replies: a second self-looping DMA control block plays a 1 MB transmit ring of idle words into the PCM transmit FIFO for as long as the Pico clocks. A reply is written about 1024 words ahead of the DMA's read position and zeroed again once the DMA has passed it.

Rendering

  • Vertex processing on the ARM: transform, GL ES 1.1 lighting (up to 4 lights, no spot lights, infinite viewer), texture matrix, per-vertex fog, primitive assembly, clipping (near, far and a guard band), flat shading (last vertex), two-sided lighting (facing per triangle). Screen-space triangles go to the V3D in NV shader mode.
  • Guard band: vertices stay within 800 px outside the viewport. Measured on the hardware at 320×240: up to x −960 … 1280 px renders, x −1120 … 1440 px loses triangles, although the 12.4 fixed-point format reaches ±2048.
  • Points and lines are screen-space quads, 1 pixel and LINE_WIDTH wide.
  • Jobs: each render target's draws are one V3D job (binning, then rendering 64×64 tiles). Colour is loaded from memory unless cleared; depth and stencil are stored after every job (T-format, about 80 µs at 320×240) and loaded unless cleared. A frame that switches targets renders several jobs. The rendering list takes up to 43 bytes a tile, and its buffer is sized for the largest screen's 32×32 tiles (a fixed 16 KB overflowed at 1920×1080: 510 tiles).
  • Texture targets are level 0 of a texture, in its tiled layout (T or LT RGBA8888, the tile buffer's format), not y-flipped: rows in GL order.
  • Stencil: every fragment shader writes the three TLB stencil setup words from uniforms (Mesa's encoding); with the test off they say "always pass, keep".
  • Early Z (CGeometry::DepthBits), as in Mesa's vc4 (vc4_state.c, vc4_emit.c): the V3D tests fragments against a reduced-resolution copy of the tile's Z buffer before shading them (configuration bits 16, early Z, and 17, its updates; the reference guide's "Z and Stencil": the shader's TLB Z writes update the copy). The tile rendering mode's early-Z direction (bit 10) is lt/le, so the test is on for LESS and LEQUAL only, and not when rejecting a fragment early would skip a stencil op (the fail or depth fail op isn't KEEP; Mesa checks the depth fail op alone) or when a program's fragment shader writes its own depth (gl_FragDepthEXT: Mesa's disable_early_z, PGPU_SH_FS_WRITES_Z in the blob). Shaders that discard keep it: they write Z conditionally (Mesa's discard_cond, the alpha test here), so a discarded fragment updates nothing. Updates are on with depth writes (Mesa sets them always; only draws that write Z change the buffer). Mesa's HW-2905 case (a full-resolution tile load with multisampling) can't happen: depth is loaded with general loads, one sample a pixel. It helps depth-tested draws hidden behind nearer ones drawn before them. Measured on the Zero 2 W at 1920x1080 (60 s each, the same host binaries): antigrav's night race 30.8 → 32.6 fps (render 29.7–34.1 → 28.3–32.2 ms); flight unchanged (about 22.5 fps: its sky and clouds are drawn without the depth test, and the aircraft on top of them). dEQP-GLES2's subset, the first 1557 cases: the same results as without it.
  • Scissor and the viewport become the V3D's clip window; polygon offset is its depth offset (factor and units as in Mesa's vc4). An empty clip window doesn't clip everything on the V3D: such draws are skipped.
  • V3D state that persists across jobs: the line width keeps its value from the previous job (measured: lines drew wrongly after wide-line tests), so each job emits it before first use; the depth offset is treated the same.
  • Programs run in the V3D's GL shader mode: the binner runs the coordinate shader, the renderer the vertex and fragment shaders, and the hardware clips. Each draw gets a shader record, attribute records pointing straight into the buffers, and uniform streams resolved at draw time. Buffers used by a program draw are copied on write for the rest of the frame (§6.3). The viewport has a negative y scale on the panel, because its rows go top to bottom.
  • Program fragment shaders are compiled by Mesa for an RGBA8888 window framebuffer with blending off; glslc replaces the final colour write with one of two endings (devtools/qpuasm.py): reorder Mesa's BGRA into the tile buffer's RGBA (8 instructions), or load the tile buffer's colour and blend per channel with 48 coefficient uniforms, which cover every blend factor and equation, the constant colour and the colour mask (about 75 instructions).
  • Fixed-function fragment shaders: 40 built-in QPU programs (gpu/shaders.py, generated with devtools/qpuasm.py): texture environment (none, MODULATE, REPLACE, DECAL, BLEND) × fog × alpha test × blending. Blending and the colour mask are done in the shader (tile buffer colour read), with the same coefficients as programs; SRC_ALPHA_SATURATE is approximated by SRC_ALPHA. For A8 textures the texel's RGB is taken as 1 (GL ES 1.1 environments).
  • Textures: converted at upload to RGBA8888 (R in byte 0) in Mesa's tiled layouts (LT for levels up to 16 pixels, else T), levels smallest first with level 0 page aligned, cube faces as whole mip trees; rows bottom-up as sent. ETC1 is decoded on the ARM. (Raster RGBA32R, used before, reads rows at a stride of max(width, 4) texels: verified with widths 1, 2, 4, 8 and 64.)

The screen: panel and HDMI

  • Output: the V3D renders RGB565 directly into two alternating screen buffers. The ST7789 DMA driver sends them to the panel at 75 MHz (60 fps at 320×240). On HDMI the V3D renders straight into the pages of a three-page firmware framebuffer: one on screen, one waiting for the vertical sync that shows it, one being drawn; no copy (a DMA copy cost 2.6 ms of CPU a frame at 512×300: CPU-G 20% instead of 6%). The vertical sync is the frame count of the display scaler's channel for HDMI (HVS DISPSTAT1, bits 17:12; measured 60 a second), polled with a 100 ms timeout. The firmware's "wait for vsync" call, used before, has no timeout; with it, the RPi hung once as a monitor was switched on during a video (the log stopped, the watchdog reset it; where it hung isn't known), and since the change it hasn't. The video demo on 1024×600 went from 38–51 to 57–60 fps. A page flip is still a firmware call (SetVirtualOffset).
  • The firmware's framebuffer limits: three pages of a 1920×1080 screen make a framebuffer 1920×3240. With the firmware's default limits the allocation succeeded, but the firmware then stopped answering: the next mailbox call (the per-second ARM clock query) never returned, and the watchdog restarted the board, at every boot while that monitor was connected (measured on a Zero 2 W with a 1920×1080 monitor; 1024×1800 worked). config.txt sets max_framebuffer_width=2048 and max_framebuffer_height=4096 (room for three pages of 1920×1200); the firmware's defaults aren't documented. Circle's mailbox calls have no timeout, so any firmware call hangs the same way.
  • gpu_mem=192: with 128 MB, a 1920×1080 framebuffer left the video decoder "out of resources" (MMAL_ENOSPC, no frames) for a 2048×1152 texture; 192 MB plays it.
  • Screen size on HDMI (gpu/kernel.cpp, gpu/display/; the options output=, panel=, hdmi_pixels= are in the README's "Kernel command line"): the monitor's preferred mode (native: 1024×600 for a 1024×600 monitor), up to 1920×1200; a larger one, or one over hdmi_pixels, is divided by the smallest whole number that makes it fit (with hdmi_pixels=230400, 1920×1080 and 1280×720 give 640×360, 1024×600 gives 512×300). The width is a multiple of 16.
  • Panel detection (CPanelOutput::Detect): at boot the panel is reset and its registers read over MISO (GPIO9), bit-banged at about 500 kHz (the ST7789 reads slowly; the driver's SPI runs at 75 MHz), then the pins go back to SPI0. A panel answers RDDID (04h: a dummy bit, then its ID bytes) the same with MISO pulled up and pulled down, and releases the line after them; with nothing there the pull-up reads all ones and the pull-down all zeros. Measured: 1000 of 1000 reads the same with each pull (ID 81 81 B3). The ID bytes are the module maker's (IDSET, C1h, in the panel's NVM; the ST7789V datasheet's default is 85 85 52), and no register tells the glass's size (the controller's memory is 240×320 whatever is attached).
  • Hot plug: the HDMI hot-plug line is GPIO46 on a Zero, GPIO28 on a Zero 2 W (low while a monitor is connected), sampled every 20 ms; a change counts after 200 ms. The EDID is read over the DDC bus (BSC2, address 0x50, 100 kHz, about 12 ms), because the firmware's EDID property tag keeps answering with the EDID read at boot after the monitor is gone. At boot it's read at once; after a hot plug from 2 s on (the firmware reads it too, over the same bus, and sets HDMI up again); while a connected monitor doesn't answer, it's tried again every second.
  • The panel while the screen is on HDMI (ShowPanelNotice), four lines: Monitor and Native resolution (the monitor's EDID: its name and preferred mode), HDMI resolution (the signal the firmware sends: the pixel valve's size, the refresh measured; config.txt sets it at boot, so a mode forced there stays whatever monitor is plugged in) and Render resolution (the screen GL draws into, which the firmware scales to the signal).
  • The splash (ShowSplash) on the screen, panel or HDMI, while no host draws (none has ended a frame, or not for a second): at boot, after a screen change, when a monitor's EDID comes and when a PC's desktop lets go of the screen. It says what the screen is ("HDMI 1920x1080@60Hz ready"), the monitor, the render size, the board, its clocks, the host setting and the build. It's laid out for 320x240 and every font pixel drawn as a k × k square (the panel 1, 1024x600 2, 1920x1080 4); the host's first frame replaces it. At boot it's drawn after the renderer's start, which clears the framebuffer's pages.
  • A screen change waits for the frame's end (IsBetweenFrames), and a host killed in the middle of a frame never sends it: after a second with no packets mid-frame the frame is dropped (CCommands::AbandonFrame) and the screen changes.
  • HDMI mode: the firmware chooses it at boot and doesn't change it by itself later. config.txt has hdmi_force_hotplug=1, so that HDMI stays on (640×480) when the RPi boots without a monitor. By default the firmware prefers TV modes: for a 1024×600 monitor it sent 720×576 at 50 Hz, capping frames at 50 fps. hdmi_group=2 gave 1024×768 at 60 Hz; hdmi_mode=87 with hdmi_cvt=1024 600 60 gives that monitor's own mode (measured: 59.9 fps). Whenever the mode isn't the monitor's, the firmware scales our screen to it and the monitor scales that to its glass: 1024×600 through 640×480 (a monitor plugged in after boot) made text unreadable.
  • The monitor's own mode, asked for (CKernel::MatchHDMIMode, gpu/display/tv_service.cpp): the firmware has two services over VCHIQ for this (what vcgencmd and tvservice use on Linux; their messages: Circle's addon/vc4/interface/vmcs_host). When a monitor's EDID has come (at boot, or 2 s after a hot plug) and the mode sent isn't its preferred one, the general command hdmi_timings gives the firmware that mode's timing as the EDID has it (its first detailed timing: porches, sync widths and polarities, pixel clock) as the custom mode, and the TV service turns HDMI on in it (HDMI_ON_EXPLICIT, DMT 87; as HDMI if the EDID's CEA extension says the monitor takes sound, else as DVI); the pixel valve shows the new mode 350 ms later, and the framebuffer is made anew (CHDMIOutput::Forget). Not for an interlaced mode or one beyond a 162 MHz pixel clock or 1920×1200; hdmi_signal=boot on the kernel's command line turns it off. Measured, a 1024×600 monitor (50.25 MHz; 1024 + 44 + 88 + 188 across, 600 + 3 + 6 + 16 down): at boot from the firmware's 1024×768, and from 640×480 (set by hand, as after a boot without a monitor: the TV host line), the pixel valve read back the EDID's timing each time, the game going on at 60 fps. The host lines for trying things: FW text (a general command; hdmi_cvt 1024 600 60 6 0 0 0 answers with the timings it made), TV P | E dvi-or-hdmi group mode | S | R | M. Not verified: the picture on the monitor's glass (only what the RPi sends); sound over HDMI after the change; a real hot plug after a boot without a monitor; other monitors.

The touch screen and Settings

  • The readings are noisy, and the SPI clock isn't why. Under a held finger a single sample of the XPT2046 is off by 2 pixels rms (up to 10), measured at 2, 1 and 0.5 MHz: 2.3, 2.1 and 1.6 pixels. Its low four bits come out as all ones or all zeros in two samples of three. Sampled one after another, a channel's samples show no settling (the first after the pressure's is the worst); there's no periodic part in the noise either. As it was read at first (three samples a channel, the best two averaged) a held finger's position changed direction 30 times a second, which made a slider flicker by a step or two.
  • So: eight samples a channel in a reading (150 us at 2 MHz; the frame rate on the panel is as before, 60), the middle four averaged; the position smoothed over the readings (a quarter of the way to each new one, at once if it's 12 pixels away) and reported 1.25 pixels behind the smoothed one, so it only moves when the finger does. On the recorded readings of a finger held and dragged that left 0 to 0.7 changes of direction a second.
  • Settings without a finger (how the menu was checked, the panel out of sight): the TOUCH x y ms host line (text mode) puts a finger on the panel at that pixel for so long, and stays where it was let go until a real one comes; lines sent while it's down move it (a drag). The screenshot (s) shows Settings while it's open: what it sent to the panel.

Video

  • Video (gpu/video/): MMAL (the Raspberry Pi userland's client, BSD-3, vendored in gpu/video/userland) talks to the firmware's components over Circle's VCHIQ. A stream is vc.ril.video_decode tunnelled to vc.ril.isp inside the VideoCore; the ISP scales to the texture's size and converts to RGBA, and its frames come into ARM memory (4 KB aligned buffers, by the VideoCore's DMA: the ARM copies nothing). The texture then points at the frame: raster RGBA (TMU type RGBA32R). The TMU reads raster rows at a power-of-two stride (measured: a 320-wide texture came out garbled, 512 right), hence the width rule. MMAL's zero-copy would need the firmware's VCSM service, which Circle lacks; it isn't needed.
  • Each frame is tiled once: the TMU samples raster rows about four times slower than a tiled texture (a 1024x576 quad on HDMI: 8.7 vs 2.05 ms), and at 60 fps a 24 fps frame is drawn 2.5 times. So a video texture has tiled storage of its own (CTextures::CreateExternal), and each new frame is copied into it once, between frames: a render-only V3D job whose tiles load the frame's raster rows and store T-format (CRenderer::CopyToTiled, CV3D::RunRender; no shader, no TMU). Without the storage, or if a copy fails, the TMU reads the raster frame. Measured on the Zero 2 W, HDMI 1024x600: GPU 71% → 35%.
  • VCHIQ's tasks run when the main loop yields (Circle's cooperative scheduler): the loop yields after at most 1 ms of commands. Measured: with 64 packets a turn and a fast host (a PC over USB), the decoder stopped after 11 frames. The V3D jobs yield too while they run (CV3D::SetWaitHandler, pointed at CScheduler::Yield): with 3–4 ms more work at a frame's end that didn't yield (a plain busy wait did the same), the decoder stopped for good after 4 frames.
  • Measured (720p H.264 test pattern, High profile with B-frames, 512×288 texture on the panel, from the P4): 30 video frames a second with none dropped, GL at 60 fps, the host's CPU 1–2%. Decoder to RGBA in ARM memory: 96 fps from 720p, 43 fps from 1080p (1024×576).
  • In 64 bit too (the Zero 2 W): MMAL's messages to the VideoCore have the VideoCore's 32-bit layout on any client (gpu/video/userland/interface/mmal/vc/mmal_vc_msgs.h); devtools/mmal-layout.py checks the layout against the 32-bit compiler's. Circle's vcos is used in 64 bit too (the fork's "vcos: build for AArch64 too"). The MMAL sources are built with -mstrict-align: they read VCHIQ's messages in place, in Circle's coherent region, which is Device memory in 64 bit, where unaligned accesses fault.
  • The encoder, tried (gpu/video/encode_test.cpp; the ENC host line, text mode: ENC [seconds [kbit/s [RGB|I420 [DUMP [frames a second]]]]]): the frames shown go to the firmware's H.264 encoder (vc.ril.video_encode: high profile, a key frame a second with its SPS and PPS), a line a second says what went in and came out, and with DUMP the stream follows (#H264 bytes frames microseconds, base64, #END), then the sound played meanwhile (#SOUND rate frames s16le-stereo: what the output that plays the effects took, with them, before the volume: CAudioSink's tap). devtools/record.py SECONDS OUT.mp4 does all that and has ffmpeg make an MP4 of the two (the video as it is, at the rate the frames came at; the sound as AAC). Its input takes the panel's frames as they are (RGB2, RGB565; the list it gives: I420 YV12 NV12 NV21 RGB2 RGB3 BGR3 RGBA BGRA YUYV YVYU UYVY VYUY SAND I422 EGLI OPQV). Measured on a Zero 2 W, the aquarium at 60 fps on the panel (320×240), 1000 kbit/s asked: 596 frames in in 10 s, none without a buffer, 0.17 ms each to hand over; 59.5 frames a second out, 999 kbit/s, a frame at most 3.3 KB, a key frame at most 16.6 KB; a frame came out 3 ms after it went in (5 ms at most); the renderer stayed at 60 fps. ffprobe on the PC: H.264 High, level 4.0, 320×240, no B frames, 596 frames; the colours right. 300 kbit/s asked gave 298; 4000 asked gave 2846. Making I420 here (a plain loop) cost 4.0 ms a frame: no reason to. A recording of 12 s with a Bluetooth speaker playing: 717 frames, 575488 frames of sound at 48 kHz (11.99 s); a feed asked for at 2.0 s is heard at 2.007 s and its pellets are first seen in frame 120 (2.009 s). Nothing is sent to the host yet.
  • A recording on the card (ENC seconds kbit/s RGB FILE; gpu/video/mp4_writer.cpp; devtools/record.py --card fetches it with the GETFILE host line, DELFILE removes it): the RPi writes the MP4 itself, as it records, RECnnn.MP4: the encoder's frames (their NAL units behind their lengths, the parameter sets in avcC, each frame with the time it was shown: the durations are what they were) and the sound as AAC (the encoder below; at a rate it doesn't take, as 16-bit PCM, sowt: 192 KB a second, and fewer players take it), in chunks of half a second, the index (moov) written when it ends. A recording that doesn't end (the power gone) has no index and can't be played. What costs: the card. Its driver (Circle's SDHOST) writes in the caller's time, 2.7 ms and 83 us a KB (16 KB: 4 ms; 64 KB: 8 ms; from a sector's start or not), so the main loop stands still that long; written between frames, that showed as 57 fps instead of 60. So the blocks are small (16 KB) and one goes out as a frame is about to be shown, in the wait for the panel to have taken the frame before (CRenderer::SetSlackRoutine): a minute of the aquarium recorded at 59.6 fps (3577 frames; the renderer's seconds 57 to 61), 1161 writes of 3 ms, 38 ms the longest, 115 KB waiting at most (the ring: 8 MB), no sound lost; closing the file 136 ms. Where the wait is short (the supersampled mode: 9 ms of rendering) a 32 s recording had seconds of 55 to 57 fps. ffprobe: H.264 High 60.000 s, PCM 60.009 s; ffmpeg decodes it whole; a feed heard at 4.159 s shows its pellets in the frame of 4.156 s. (Those numbers are of the sound as PCM, 317 KB a second to the card; as AAC it is 147: a minute is 8.9 MB instead of 19, 538 writes, the renderer's seconds 58 to 61.) Chromium plays the file, picture and sound. Not tried: another core for the writes (the SDHOST driver's interrupt is core 0's), other players, the Zero's one core, a full card.

Audio

The audio stream (protocol §7.13, gpu/audio/): AAC, MP3 or Ogg Vorbis decoded on the ARM, played on HDMI through the VideoCore's audio service, or on a Bluetooth speaker (below). The outputs are audio sinks (CAudioSink: the ring, the volume, the pause): HDMI's (CAudioOut) and the speaker's (CBTAudioOut).

  • Sound effects (protocol §7.14, CSounds): the host's sounds kept as 16-bit mono, 16 channels mixed (resampled, each with its volumes) into what an output takes for playing (CAudioSink::Take), after the stream's sound and before the volume: so an effect waits for the output only (HDMI: the two chunks the VideoCore holds), not for the 2 s ring. One output plays them: the stream's, or one kept running for them (the speaker's while it's there, else HDMI's at 48 kHz). A loop starts and stops through a 43 ms fade (it's cut anywhere in its wave); volumes are eased the same way. A channel's pitch (SOUND_PITCH) scales its step through the sound, from where it is: no click. antigrav's engines are one loop each, their note the craft's speed. Checked with the capture (PCM): a level's hum at 100 and 200 Hz, steps 4.4 a second, a door's grinding louder on its side; with a Pico as the host, 60 fps as before.
  • Output (CAudioOut): Circle's VCHIQ sound device (addon/vc4/sound), destination HDMI, 16-bit stereo in chunks of 2048 frames (43 ms at 48 kHz) from a 2 s ring; silence while the ring is empty. The chunks are handed over in VCHIQ's task, on core 0, when the main loop yields, and Circle's driver keeps only two queued in the VideoCore: with 480-frame chunks (20 ms) the VideoCore ran dry for a moment when a stream opened (the main loop busy 20–40 ms: MMAL's set-up, the first frames), a click; with 2048 frames it has 85 ms, and ran dry 0 times in three runs. The firmware sets HDMI up with audio from the monitor's EDID at boot: nothing in config.txt was needed for the Dell S2421H (a monitor without speakers gets no sound). One output a sample rate, kept for the whole run (the service is opened once a device); a stream's close stops it, the next stream starts it again.
  • Decoding AAC (aac.c): FAAD2 2.11.3's libfaad (gpu/audio/faad2, vendored unchanged; GPL 2 or later, so it can be linked with Circle's GPL 3), float out, more than two channels mixed down to stereo (FAAD2's downmatrix), mono doubled, converted to 16 bit (full scale: the volume is the output's, below). The decoders are a library of their own (audio_codecs in gpu/CMakeLists.txt): the gpu app's C flags force-include MMAL's header, and FAAD2 needs two shims for Circle, which has no C library (compat/: an assert.h found before Circle's, whose circle/macros.h redefines FAAD2's ALIGN; qsort, abs, and its three fprintfs to stderr dropped). Checked on a PC against ffmpeg: a stereo AAC file the same sample for sample (correlation 1.00000, at most 245 of 32768 apart); FAAD2 drops the first unit's priming frames, so the frames of unit k start at unit k's pts.
  • Encoding AAC (aac_enc.c, for the recorder's MP4): our own, small: AAC LC, a channel pair at 44.1 or 48 kHz, long blocks only (an MDCT of 2048 by way of a 512-point FFT; checked against the definition: 3e-7 off), no psychoacoustic model: each scale factor band's step is set from its level so that the quantiser's noise stays a fixed distance under it (27 dB up to 4 kHz, less above, 14 dB at the top; bands to 18.7 kHz), mid/side when the channels are much alike, for each band the cheaper of the two codebooks its largest number allows, no bit reservoir (an MP4 keeps each unit's size: a unit is as big as its sound asks, 1536 bytes at most). Its Huffman tables (aac_enc_tables.h) are made from FAAD2's decoding tables by tools/aacenc/gen_tables.c, which walks them and checks that every value has a codeword and that the codewords fill the code space. A unit is of the frames given the call before, so what the n-th unit decodes to are the n-th 1024 frames: no delay to tell a player of (ffmpeg: 0 frames late, from ADTS and from the MP4). On a PC (tools/aacenc/aac_enc_test.c, compare.py; ffmpeg decodes): a minute of the aquarium's sound: the noise 26.5 dB under the sound at 178 kbit/s; a full-scale tone 27.5 dB at 89; a chord apart in the two channels 26 dB at 147; white noise 348 kbit/s (and the bands above 18.7 kHz gone); silence 4; clicks 15 dB: with long blocks only, a click's noise is spread over its whole block (a pre-echo). No decoder's errors in any. On the Zero 2 W: 0.59 ms a unit (0.97 at most), 47 units a second, in the main loop; 174 kbit/s for the aquarium; a feed's pellets seen in the frame of 0.508 s, heard at 0.519 s. Not listened to by anyone yet.
  • Decoding MP3 (mp3.c): minimp3 (gpu/audio/minimp3, one header, vendored unchanged; CC0), MPEG-1, 2 and 2.5 audio layers 1 to 3, float out, mono doubled, to 16 bit as for AAC; its NEON code on the Zero 2 W (AArch64), plain C on the Zero. A sample is one whole frame: minimp3 takes a frame alone when it's exactly as long as its header says (mp3d_find_frame), and keeps the bit reservoir between calls; a frame at another sample rate than the stream's is refused. Its scratch space is on the stack (about 16 KB; Circle's stacks are 128 KB). Checked on a PC against ffmpeg with the host's reader (libpgpu/pgpu_mp3.c): the same sound to within 1 of 32768 (host-library.md).
  • Decoding Ogg Vorbis (vorbis.c): Tremor, Xiph's integer Vorbis decoder (libvorbisidec), with libogg's framing (gpu/audio/tremor, vendored unchanged; BSD-3-Clause; README.piegpu there says what's from where). stb_vorbis was tried first and dropped: it mis-decodes 6-channel files (its open issue nothings/stb#1594; 1 to 5 channels were right). libogg takes the pages apart and checks their CRCs, Tremor's synthesis layer decodes the packets (as libvorbis' is used, without vorbisfile), 32-bit fixed point out (16-bit samples shifted left 9, as its ov_read has it); mono doubled, 3 to 6 channels mixed down in Vorbis' order (FL C FR RL RR LFE: centre and rears at −3 dB, the LFE left out, normalized). A sample is one Ogg page: up to 64 KB, of any number of packets (seconds of sound), so a page is fed once and decoded 1024 frames a step as the output has room, each step's time the page's plus the frames before it (CAudio::DecodePage), and freed for the host when all of it is decoded; MaxUnit is 64 KB for it. A packet's sound overlaps the packet before, so a stream opened at a page in the middle (a jump) gives the first packet no sound: the first page then only primes the decoder (its sound dropped: its pages are numbered on from the header pages' when it's the stream's start), and the host starts one page early (pgpu_ogg_seek); the stream's first page again (a loop) resets the decoder (ogg_stream_reset, vorbis_synthesis_restart). Circle has no toupper, labs or memchr: tremor/compat/, force-included; alloca is the compiler's builtin. Checked on a PC against libvorbis and ffmpeg (host-library.md), and on the Zero 2 W: the demo track with jumps and loops, and 6-channel files (840 kbps) with 0 ms of silence. Not yet run on the Zero (its decoding in the main loop, 1024 frames a turn).
  • A core of its own: on the Zero 2 W the decoder runs on core 1 (CCores in gpu/kernel.h; Circle configured with ARM_ALLOW_MULTI_CORE, devtools/build-gpu.sh; cores 2 and 3 halt). On the Zero, one core, it runs in the main loop, up to 2 ms a turn. Between the cores: rings with one writer and one reader each and memory barriers, no locks. The compressed samples: Data (core 0) publishes a sample once its last chunk has come; the decoder frees it once decoded (the host's room). The frames: the decoder writes, GetChunk (VCHIQ's task, core 0) reads. The times: a mark (output frame, pts) for each decoded unit. Closing parks the decoder first: each side stores its flag, then a full barrier, then reads the other's, so at least one sees the other.
  • The clock: the time being heard is the newest mark at or before the frame being played (frames read from the ring less the two chunks the VideoCore holds, plus the time since the last chunk was asked for, at most a chunk: so it runs smoothly, not in 43 ms steps), plus the frames since it. (With the steps, a video frame was dropped now and then: 38 in 70 s once; smoothed, 0 in three 25 s runs.) A video stream opened with the audio (CVideo::SetClock) shows the frame due at that time, and its first frame until the sound starts. If the sound runs dry the clock stops, and the picture waits. Not measured: the delay after the VideoCore (the camera sees only the panel, so the picture against the sound can't be timed).
  • Volume: volume= on the command line (percent, default 10), and VOLUME for a stream. It's applied where the chunks go to the VideoCore (CAudioOut::GetChunk), ramped across a chunk (a step would click), so a change is heard after the two chunks the VideoCore holds (under 0.1 s). The decoders applied it at first: then a change came after all the decoded sound waiting in the ring, about 1.3 s.
  • Closing a stream cancels the output (Circle's Cancel, which waits for the chunks queued in the VideoCore to complete). The VideoCore can report more completed than was written (seen after it ran dry, by 17232 bytes); Circle compared those counts unsigned, took the difference for a queue that never ends, and waited for good: the watchdog restarted the RPi (a jump in the media demo closes and opens the stream). piegpu's fork compares them signed, and waits at most 500 ms, logging it if it has to stop anyway.
  • The VideoCore running dry is flagged in its completion messages: bit 30 of their byte count (undocumented; Circle's driver masked bits 31–30 off, Linux's takes such a count as an underrun). piegpu's fork counts them (GetCompleteFlagCount, the last's bits and time). Shown on purpose by the SOUNDTEST host line (text mode): a tone, the main loop stalled for 150 ms without yielding: one completion with 0x40000000, at the stall's end, and a chunk asked for 151.5 ms after the one before.
  • Debugging clicks: the output keeps the last 20 s of what it handed to the VideoCore and each chunk's time, frames from the ring and the ring's level. The PCM host line dumps them, with the completion flags; devtools/pcmdump.py fetches that (text mode: after the session), writes a WAV (devtools/logs/pcm.wav) and lists late chunks, chunks padded with silence and jumps in the samples.
  • Verified on the Zero 2 W with the Dell S2421H, the trailer through video_host (now media_host): the webcam's microphone recording cross-correlated with the trailer's audio decoded on the PC: 2 s windows over 40 s all within ±4 ms of their expected place, across the loop (period 33.0 s) too; 1843 units, 0 broken, 30 ms of silence at the start; decoded on core 1. With the decoder in the main loop: the same sound (8 s of recording = 7.996 s of trailer). The Zero: builds, not run.

Bluetooth: a speaker

gpu/bt/, in the kernels built with PGPU_WIRELESS. Everything runs in the main loop (CBluetooth::Update); only the UART's bytes move in an interrupt.

File What
bt_uart the PL011 on GPIO32/33, RTS/CTS on GPIO30/31 (ALT3), two rings filled and emptied by its interrupt
bt_hci H4 packets: commands one at a time, events, L2CAP frames cut into the controller's packets and put together again, as many under way as it has buffers (8 of 1021 bytes)
bluetooth the controller's set-up, the inquiry and the names, the connection, pairing, the bonds, which channel is what
bt_l2cap channels and their signalling, basic mode
bt_sdp one service record (an A2DP source), the three requests answered from it
bt_avdtp the stream: discovered, configured, opened, started, suspended, reconfigured; the speaker's own commands answered
bt_audio the audio sink: the ring's frames paced by the clock, resampled if need be, encoded, packed as media packets
  • The controller (a Zero W's BCM43438; a Zero 2 W's answers the same, word for word) answers its reset at 115200 baud with flow control, with no patch file loaded: HCI 4.1, manufacturer 15. It comes with the address AA:AA:AA:AA:AA:AA: it's given B8:27:EB and the board's serial number's low three bytes xor AA (Broadcom's command FC01). Then 921600 baud (FC18: its answer at the old rate). It keeps that rate through an HCI reset, so switching Bluetooth on again tries both rates.
  • A connection, as it went with a JBL GO: called (1.3 s), authentication asked, no key, pairing with no input or output on our side (the numeric comparison confirmed by itself), the key kept, encryption on, the signalling channel (PSM 0x19), the end points discovered (one SBC sink, every option, bitpool 2-53, SCMS-T offered and not taken), configured, opened, the transport channel: 1.6 s from the answer to a stream. The speaker then asked for AVCTP and searched our record for an AVRCP target (refused and none then; there since: the volume, below).
  • A speaker that calls back (switched on again, or after our restart) opens the stream's signalling channel itself, at once. Opened from our side too, each side took its own for the signalling and the other's for the transport, and our first command was never answered (a JBL GO: the board then gave up and went on to the next speaker). So with the speaker's call the channel is left to it (ours only after 1.5 s without); with our call it's ours. Measured after: its call, 0.8 s to an open stream.
  • The volume (bt_avrcp): AVCTP on PSM 0x17, AVRCP's vendor commands in single packets. We ask to be told of the speaker's volume (RegisterNotification, event 0x0D: answered with the volume it has, then once at each change, asked again each time) and set it (SetAbsoluteVolume, 0 … 127; CKernel::UpdateSpeakerVolume keeps it and the audio's volume the same, and CAudio sends the sound whole meanwhile). The speaker's commands to a player are answered (what we are, our company, no events; buttons accepted, the volume ones counted). Two records more for it (bt_sdp): AVRCP 1.4's target and controller. As it went with a JBL GO: it lists event 0x0D and opens the channel itself 1.4 s after the stream starts when it called; on a channel we opened just then it answered what it can do, but rejected the volume's two commands after 2 s each (REJECTED, status 3). So its channel is the one used (ours closed if both are there), and after its call ours is opened only after 6 s without. BT TRACE logs the frames, BT RC type pdu bytes sends a command by hand, BT VOLUME n is the bar.
  • The sound's pace is ours: an SBC frame (128 samples) for every 2.9 ms that passed since the last call, five frames a media packet (608 bytes: one baseband packet). After the main loop was away for longer than 250 ms that sound is skipped. A media packet isn't queued behind 8 others: with the controller's 8 that's 230 ms of a stalled link, and the packet is dropped.
  • Measured with this PC as the speaker (its adapter also serves a mouse and a keyboard): of about 1500 packets of a 20 s stream 0 to 94 were dropped from run to run, with the main loop never away for more than 36 ms: the link, not the loop. With the JBL GO none of 835.
  • BlueZ refuses AVDTP's reconfigure (error 0x19): its stream stays at the rate it was configured with, and sound of the other rate is resampled (linear interpolation). The JBL GO takes it.
  • Testing without a speaker in the room: a PC with BlueZ is a sink too. It has to be discoverable and pairable and needs an agent that says yes (a few lines of Python on D-Bus); PipeWire then shows the stream as bluez_input.<address>, and what it plays can be recorded from the monitor of the sink it's linked to. The BT host line drives the stack by hand: ON, OFF, SCAN, STOP, LIST, CONNECT address, DISCONNECT, FORGET address, TEST.

The run log: a restart explains itself

An RPi that restarts on its own used to leave nothing behind:

  • A crash can't report itself. An exception, a failed assertion or LOGPANIC halts the CPU. Its message goes through the logger to the USB serial port, but the USB gadget needs the interrupts that the crash just lost, so the message never leaves the board.
  • A hang has no message at all.

In both cases devlink's hardware watchdog (DEVLINK_WATCHDOG_SECONDS, 10 s) restarts the board, and the next run started blank.

Now each run keeps its log in RAM that survives a restart. At boot, the next run says how the previous one ended and shows its last lines.

Code What it does
devtools/runlog.{h,cpp} CRunLog: the ring, the event hook, the report
piegpu's fork of Circle (github.com/anight/circle, branch piegpu) Circle leaves the top of the ARM memory to the app (the commit "Memory: MEM_PERSISTENT_SIZE …")
devtools/build-gpu.sh Circle's option MEM_PERSISTENT_SIZE=0x10000 (CIRCLE_DEFINES)
gpu/kernel.cpp m_RunLog.Initialize () right after the logger's; Report () after the boot lines
gpu/main.cpp, gpu/install/installer.cpp, devtools/devlink.cpp Mark the restarts that were asked for

Which RAM survives a restart

This was measured, not taken from documentation. A probe build wrote marker words at chosen addresses, restarted the board with reboot () (a watchdog reset), and logged which markers were still there. Results on the Zero 2 W, with gpu_mem=128, so the ARM gets 384 MB up to 0x18000000:

Addresses After a restart
0x120000–0x3E0000: the kernel area past the image, the stacks, the start of the gap in Circle's memory map zeroed
0x3F0000 and up, to 0x4F0000 kept
0x08000000–0x16FF0000: the heap's upper part kept
0x17F00000–0x17FFFFF0: the top of the ARM memory kept
  • Who clears it: the boot firmware, not Circle. Circle clears only its bss (lib/sysinit.cpp).
  • Where it stops: somewhere between 0x3E0000 and 0x3F0000. That's not a documented or round number, so the log doesn't rely on it.
  • The heap: it survives but belongs to the heap, so the log can't use it either.

Keeping the top of the ARM memory out of Circle's hands

Circle hands all the ARM memory the firmware reports (PROPTAG_GET_ARM_MEMORY) to its heap and page allocator. piegpu's fork subtracts MEM_PERSISTENT_SIZE from that size in CMemorySystem (lib/memory.cpp and lib/memory64.cpp). The top 64 KB is then the app's: no allocator ever returns it. The run log finds it with the same property tag, at nBaseAddress + nSize - MEM_PERSISTENT_SIZE.

build-gpu.sh configures each board's build with MEM_PERSISTENT_SIZE (Circle's CMake option CIRCLE_DEFINES). Without it, runlog.cpp stops the build with an #error, rather than writing to memory the heap might use.

How the reserved memory is mapped differs between the boards, because the memory now lies above what Circle thinks is RAM:

  • Zero 2 W, 64 bit: Circle maps it as Device memory (64 KB pages), which is uncached. Writes reach RAM directly. Accesses have to be aligned, which they are: the header is u32s and the ring is bytes.
  • Zero, 32 bit: Circle maps 1 MB sections, and the one holding the top 64 KB starts below the reduced size, so it's normal cached memory. A reset doesn't write the data cache back, so every write is followed by CleanAndInvalidateDataCacheRange () over what changed (CRunLog::Flush). That's harmless on the Zero 2 W.

Layout

top of ARM memory - 64 KB
┌──────────────────────────────────────────────┐
│ header, 6 × u32                              │
│   Magic     0x52554E4C ("RUNL")              │
│   Check     ~Magic ^ nRun                    │
│   nRun      runs since power-on              │
│   End       EndRunning / EndPanic /          │
│             EndRestart                       │
│   nIn       write position in the ring       │
│   bWrapped  the ring has wrapped             │
├──────────────────────────────────────────────┤
│ ring: 64 KB - 24 bytes of text, one line per │
│ message: "<seconds>.<hundredths> <source>:   │
│ <message>\n"                                 │
└──────────────────────────────────────────────┘

After power-on the RAM holds random bits. A header only counts as the previous run's if all of these hold:

  • the magic matches;
  • Check matches nRun;
  • End is a known ending;
  • nIn lies inside the ring.

Otherwise the run is "Run 1 since power-on". The text read back is sanitized: anything that isn't printable ASCII or a newline becomes ?.

Writing: from the logger's event hook

CLogger::Write () does three things, in this order:

  1. queues an event (WriteEvent: source, severity, message) and calls the registered event notification handler;
  2. sends the formatted line to its target device (devlink's serial port, once a host is connected);
  3. for LogPanic, calls the panic handler and halts.

CRunLog::EventHandler is that notification handler. It drains the event queue with ReadEvent (), and for every message the log level lets through, appends one line to the ring and flushes it. Step 1 comes before the USB write, so a panic's message is in RAM before anything can go wrong on the way out. A LogPanic event also sets End = EndPanic.

This covers every crash path in Circle:

  • CExceptionHandler logs the exception, the stack words, the PC, the fault address and so on at LogPanic through CLogger::Write;
  • assert () and LOGPANIC () go the same way.

Nothing else in the app reads the logger's event queue. A new user of ReadEvent () or RegisterEventNotificationHandler () would compete with the run log.

How a run ends

End Set by Report at the next boot
EndRunning Initialize (), at boot "stopped without a word (hang: the watchdog; or a reset)", with its last lines
EndPanic the event hook, on a LogPanic message "crashed", with its last lines (the panic or exception last)
EndRestart CRunLog::Restarting (), before a reboot () that was asked for "restarted as asked", no lines

Restarting () is called:

  • before the reboot on the host's reboot magic: CDevLink calls its RegisterRebootHandler hook, which the kernel points at CRunLog::Restarting, because devlink is shared with apps that don't have a run log;
  • on the installer's PGI REBOOT;
  • on ShutdownReboot in main.cpp.

The page's Reset and Stop send the reboot magic, so they count as asked for. A new way to restart must call Restarting () too, or its restarts will show up as "stopped without a word".

Reading: at the next boot

Initialize () runs right after the logger's Initialize (), before this run logs anything:

  1. checks the header;
  2. copies the previous run's last 10 lines (MaxLines) into m_PreviousLines;
  3. starts this run's header (nRun + 1, EndRunning, an empty ring);
  4. registers the event hook.

Report () then logs the result, after the build and throttle lines. The report is ordinary log output: devtools/run.sh --log shows it, because devlink replays the boot log when a host connects.

Getters for the page or the installer's INFO: GetPreviousEnd () with GetEndName () (none / stopped / crash / restart), GetRun () and GetPreviousLines ().

The report covers only the run just before this one. The next restart replaces it. In particular, the page restarts an RPi that doesn't answer when it connects, and that restart overwrites a crash report before the page could show it.

Testing it

This is how it was verified on the Zero 2 W. The test commands were temporary: they were not committed. A host line in CKernel::HostInput () ended the run in one of three ways:

else if (strcmp (m_HostLine, "CRASHTEST panic") == 0)
{
	LOGPANIC ("Test panic %u", 42);
}
else if (strcmp (m_HostLine, "CRASHTEST abort") == 0)
{
	LOGNOTE ("Writing to 0xFFFFFFF0");
	*(volatile u32 *) (uintptr) 0xFFFFFFF0 = 1;	// data abort
}
else if (strcmp (m_HostLine, "CRASHTEST hang") == 0)
{
	LOGNOTE ("Hanging, IRQs off");
	DisableIRQs ();
	for (;;);			// the watchdog restarts it after 10 s
}

The fourth case, a restart that was asked for, is devtools/run.sh --reboot. After each ending, wait about 25 s, then run devtools/run.sh --log and look for the runlog: lines. Results:

Ending Report
Asked-for restart "Run 2 since power-on (the previous one restarted as asked)"
Panic "crashed", with gpu: Test panic 42 as the last line
Data abort "crashed", with except: Synchronous exception (PC 0x818A4, EC 0x25, ISS 0x46, FAR 0xFFFFFFF0, …) and the stack lines
Hang "stopped without a word", with gpu: Hanging, IRQs off as the last line

Never make a test crash happen at boot: the board would crash on every start, and its card would have to be written again: from the installer page, after starting the board over USB with the card taken out, or on a PC.

Not verified yet

  • The Zero (32 bit): it builds, but no test has run on it. Its firmware may clear or use other areas. The address test above is the way to check.
  • A short power cut: unplugging the Zero 2 W's USB cable and plugging it back in gave "Run 1 since power-on" (three times, verified). A cut of a fraction of a second might leave the header in the RAM; the report would then say "stopped without a word".

The control list checker

A V3D job is two control lists that the renderer writes byte by byte: a binning list (the draws) and a rendering list (per 64x64 tile: loads, the tile's sublist, stores). A wrong address, size or stride in them makes the V3D write over other memory or hang, with no message. Since the V3D reads the lists by DMA, nothing on the ARM side notices until something else breaks. The checker (drivers/v3dcheck.{h,cpp}) reads both lists before each job runs, in the spirit of Mesa's vc4 kernel validator (vc4_validate.c), and refuses a job that fails: the job isn't run, the log says which list, which packet and why.

Code What it does
drivers/v3dcheck.{h,cpp} V3DCheckJob: the checks
drivers/v3d.{h,cpp} the region table (AddRegion, RemoveRegion, InRegion), NewBlock/DeleteBlock, the hook (SetJobCheck) that RunJob and RunRender call first
gpu/kernel.cpp sets the hook, unless clcheck=off
gpu/textures.cpp, programs.cpp, commands.cpp, video/video.cpp allocate what the V3D reads or writes with CV3D::NewBlock (textures, shader code, GL buffers, depth/stencil buffers, video frames)
gpu/display/hdmi_output.cpp registers the firmware's framebuffer

What it checks

  • Packets: only the ones this renderer emits, each whole and inside its list. Anything else is "not a packet this renderer emits": a change to the renderer that adds a packet has to add it here too.
  • Shape: binning: the binning mode, START_TILE_BINNING, then draws, FLUSH last. Rendering: the rendering mode first, tile coordinates inside the frame, stores after tile coordinates, one end-of-frame store, last.
  • Every address, with its extent, inside one registered block of memory:
    • the render target (the rendering mode's buffer: raster, T or LT, 16 or 32 bits a pixel) and every general tile load and store;
    • the binner's tile memory and tile state;
    • the sublists the rendering list branches to;
    • shader records (GL and NV), the shaders' code and uniform streams;
    • index buffers, and each vertex attribute over the vertices a draw really uses. For an indexed draw that means reading the index buffer for the smallest and largest index: piegpu points converted vertex data below its start (the V3D adds index x stride), so the range can't start at 0. The largest index must not exceed the draw's max index.

Not checked: texture addresses. They are in the uniform streams, and only the shader code says which words are texture configs (Mesa's kernel parses the shader for that).

The region table

Every block the V3D may touch is registered, by its bus address and size, in a table sorted by address (1024 entries, binary search). CV3D::Alloc adds its blocks itself; the rest come from CV3D::NewBlock/DeleteBlock, which replace new u8[]/delete [] wherever the V3D reads or writes the memory; the HDMI framebuffer, which the firmware allocates, is added and removed by CHDMIOutput. A new kind of V3D memory must be registered the same way, or its jobs are refused ("not the V3D's"). If the table ever fills up, the checker logs it once and stops judging addresses rather than refuse valid jobs.

When a job is refused

RunJob or RunRender returns FALSE, as after a timeout: that job's pixels are missing, everything else goes on. The first ten refusals are logged, then every 1000th, e.g.:

v3dcheck: Job refused (1 so far): rendering list +43, packet 28: store Z/stencil at C4000000 (2490368 bytes): not the V3D's

(That one is real: a test build that put the depth buffer's store 9 MB past its start, the kind of bug that corrupts memory silently. The job wasn't run, the board went on at 60 fps with nothing rendered, and only the first ten refusals were logged.) The run log keeps these lines across a restart.

Cost and verification

Measured on the Zero 2 W, HDMI 1024x600 (one job a frame):

Demo Check time per job
gears 170 us
flight 260 us
toy-voronoi 240 us
video (the frame copy is a second, smaller job) 130 us

Nearly all of it is the rendering list (160 tiles, about 1,400 packets, 6.9 KB); the binning list takes about 10 us. That's 1-2% of a 60 fps frame. These were measured with the ARM at 600 MHz (the firmware's starting clock, cpu=low; a plain byte-by-byte read of the same 6.9 KB took 45 us); at its maximum, 1000 MHz, gears' check takes 103 us. A job refused costs nothing more.

Verified with the check on: the demos, the video, gltest (the same 19 known failures on HDMI as without it) and dEQP-GLES2's 2015-case subset (1999 pass, 16 fail: the same cases as before), with no job refused; and the refusal above. clcheck=off turns it off.