Epic: #113 · Milestone: MC0 — Product & decisions
Why
The cheapest way to hit 60 fps UI and 4K video on a Pi 5 without writing a 3D GPU driver is to use what the VideoCore VII Hardware Video Scaler (HVS) does in hardware: compose several planes with per-plane scaling, format conversion and alpha, then feed the HDMI encoder. Linux's vc4 driver and bare-metal projects prove the path exists; we implement it in Home from public register documentation and observed behaviour, never by copying code.
Current state: kernel/src/video/compositor.home (2,158 lines) presents by copying a backbuffer to a hardcoded x86 address 0xFD000000; kernel/src/rpi/videocore7.home (1,416) and rp1_hdmi.home (1,200) exist but have never been compiled and their register maps are unverified.
Decision (recommended)
- Plane 0 (video): decoder output (HEVC hardware, or NEON-converted software frames) in a YUV plane at native resolution, scaled by the HVS. Zero-copy for the hardware path.
- Plane 1 (UI): ARGB8888 at 1920×1080 rendered by the Home compositor on the CPU with dirty rectangles and NEON blits; HVS scales to the panel mode (1080p or 4K). Rendering 4K UI on the CPU (≈2 GB/s of writes at 60 fps) is rejected for v1.
- Plane 2 (subtitles/OSD): optional separate ARGB plane to avoid redrawing the whole UI per subtitle change.
- Mode setting via the HDMI block (EDID → 1080p60 / 2160p60, RGB/YCbCr, infoframes); vsync from the HVS end-of-frame interrupt paces the UI loop; HDR10 = passthrough infoframes only (stretch).
- Fallback: mailbox-allocated single framebuffer (#73) so the first pixel does not wait on the HVS driver.
- V3D (OpenGL/Vulkan) is out of scope for v1;
kernel/src/video/opengl.home/vulkan.homeare frozen.
Tasks
docs/adr/ADR-MC5-display.mdwith a plane diagram, bandwidth math (per-frame bytes at 1080p/4K, DRAM budget), and the vsync/frame-pacing model.- Inventory the register knowledge available for HVS/HDMI on BCM2712 (public docs, DTB compatibles, observed firmware state) and list unknowns as risks.