evidence · 5.4 KiB

vglite-validation.md

Committed at docs/research/vglite-validation.md. This is what grounds the requirements that cite it.

Open raw source

K230 bounded VG-Lite validation

This optional source-built package advances only the unresolved GPU gates. It does not join the image closure, open the framebuffer, acquire DRM master, create a framebuffer, set a CRTC, select a plane, restart a service, or modify the panel. The board coordinator is the sole operator.

The prior private-buffer evidence is deliberately retained: RGBX opaque scale passed exactly (transcript); the partially saturated RGBA test changed a color channel and remains a failed exact-color result (transcript). Neither result establishes RGB565 output, alpha fidelity, dma-buf sharing, scanout, a wlroots renderer, or video acceleration.

Source and ABI

nix/vglite-validation.nix compiles libvg_lite.so from the same narrow, pinned kendryte/k230_linux_sdk revision 1104236db4d1e47873bd68924f912747b820228c as the prior probe. It builds no vendor userspace binary and installs the source tree’s Vivante MIT notice. The pinned 6.6.36 Xuantie kernel registers /dev/vg_lite; its API has one context, so run no other VG-Lite process during the test.

The C908 cache instruction spelling is grounded in the pinned kernel’s arch/riscv/include/asm/errata_list.h: the cross assembler cannot spell the SDK mnemonic, so the derivation carries the kernel-documented encodings. This is C908-specific and not a portable library claim.

Subtests and claims

rgb565 uses private source and destination GPU allocations. The source names the API format VG_LITE_BGR565: vendor source maps it to hardware format 0x01, distinct from VG_LITE_RGB565 (0x21), and the physical initial run showed that this is the API variant required to produce DRM/Pixman little-endian RGB565 memory (red = 0xf800, blue = 0x001f). It clears an four nonuniform red/green/blue/black quadrants, point-scales by two, calls vg_lite_finish, and requires exact RGB565 samples at the outer corners and both sides of each horizontal and vertical boundary. It proves only private RGB565 rendering.

alpha prints source, initial target, and SRC_OVER target RGBA samples after each required completion. It calculates both straight-alpha and premultiplied models from the observed source and initial target. It succeeds only when the observed blend matches one model exactly; a mismatch is an explicit renderer blocker, not a successful API-call result.

dmabuf opens a board-provided DRM node and uses only dumb-create, PRIME handle export, dumb-map, and dumb-destroy. It maps the private dumb allocation on the CPU, passes its mapping plus PRIME fd to vg_lite_map using that same VG_LITE_BGR565 format, clears it, waits, prints its four original CPU-mapping corners before requiring every pixel to be 0xf800 RGB565. The source has no drmSetMaster, drmModeSetCrtc, add-FB, plane, or atomic call. Prefer /dev/dri/renderD128; if the board has no render node, pass /dev/dri/card0 as the explicit second argument. Opening card0 still does not request master, but this test must run only under the board coordinator while the shell owns the display.

benchmark uses the same nonuniform RGB565 source and nearest 2x transform in both GPU and Pixman paths, validates their output before timing, then measures 128x128-to-256x256 and 284x616-to-568x1232 cases. After validation it emits three rounds, each reporting monotonic-wall and process-CPU time for per-operation GPU submit-plus-finish latency, batched GPU throughput ending in one finish, and Pixman. CPU time is required because comparable wall time can still conceal CPU released for decode. These are diagnostic timings, not a frame-time or speedup claim.

Build and board procedure

Host-only build:

nix build .#k230-vglite-validation --max-jobs 1 --cores 8

The coordinator transfers the resulting executable and, with the shell left running, records one transcript per subtest:

/nix/store/...-k230-vglite-validation/bin/k230-vglite-validation rgb565
/nix/store/...-k230-vglite-validation/bin/k230-vglite-validation alpha
/nix/store/...-k230-vglite-validation/bin/k230-vglite-validation dmabuf /dev/dri/renderD128
/nix/store/...-k230-vglite-validation/bin/k230-vglite-validation benchmark

If renderD128 does not exist, the coordinator may explicitly substitute /dev/dri/card0, without stopping Sway or seatd. Each run must show its *_BEGIN, operation result, *_END, and overall exit status. Capture the output under docs/evidence/video-acceleration/; a host build or QEMU run cannot prove the GPU or DRM driver.

Integration gate

Keep Pixman as the shell renderer unless all board evidence is present:

  1. exact RGB565 private-buffer results;
  2. documented alpha/color behavior acceptable for the proposed renderer;
  3. successful imported dumb-buffer write observed through the CPU map; and
  4. a renderer design that specifies cache/fence ownership and proves an actual scanout frame without disrupting the shell.

Even a passing dma-buf test proves allocation/export/import only. It does not prove DRM scanout, display-buffer sharing with the live compositor, video buffer compatibility, or a compositor integration. If the three-round CPU results do not show a material and repeatable CPU reduction at panel geometry, retain Pixman and scope no renderer rewrite. If they do, the next proposal must still define cache/fence ownership, renderer texture operations, and a non-disruptive scanout proof before integration.