# panvk-bifrost

**Claude-assisted completion of Panfrost/PanVk Vulkan support for the PineTab2 (Rockchip RK3566, Mali-G52 r1 MC1, PAN_ARCH 7) — as of 2026-05-23.**

This repository is the source-of-truth lineage for the patched-Mesa packages
[`mesa-panvk-bifrost`](https://git.reauktion.de/marfrit/marfrit-packages/src/branch/main/arch/mesa-panvk-bifrost)
and
[`mesa-panvk-bifrost-video`](https://git.reauktion.de/marfrit/marfrit-packages/src/branch/main/arch/mesa-panvk-bifrost-video)
in [marfrit-packages](https://git.reauktion.de/marfrit/marfrit-packages).
Those packages carry the deliverable `.patch` files; this repo carries the
**phase docs, design notes, evidence, and reasoning chain** that produced them.

## What the packages enable

| Package | Capability | Status |
|---|---|---|
| `mesa-panvk-bifrost` | Vulkan compositor for Chromium/Brave on Bifrost-class Mali (Robustness2 + nullDescriptor + VK1.1/1.2 + VK_EXT_transform_feedback + XFB primitive decomposition) | r1–r4 shipped; brave-vulkan launcher works |
| `mesa-panvk-bifrost-video` | `VK_KHR_video_decode_h264` backed by the SoC's V4L2-stateless hantro VPU | r5.video1 shipped 2026-05-22; byte-exact validated against ffmpeg+libva-v4l2-request-fourier (48/48 unique BBB display frames) |

## Layout

```
mesa-panvk-bifrost/        — r1..r4 campaign (Vulkan compositor enablement)
    iter1..iter18/         — per-iteration phase docs (Phase 0..8)
    phase0_evidence/       — logs, chrome://gpu dumps, vulkaninfo snapshots
    phase0_findings*.md    — per-iteration substrate findings
    phase[1-8]_*.md        — phase docs by phase number

mesa-panvk-bifrost-video/  — sibling campaign (Vulkan video decode)
    phase0_findings.md     — substrate (existing v4l2 stack on hantro)
    phase1_source_map.md   — Mesa code regions touched
    phase2_design.md       — D1–D10 design decisions
    phase4_progress.md     — commit-by-commit implementation log
    probe_vkvideo.c        — baseline probe (FAIL → PASS gate)
    README.md              — sibling campaign overview

evidence/                  — frozen .tgz source snapshots at each milestone
    phase5_post_review_*   — POST-review source (basis for 0005 patch)
    v8_commit8_*           — full multi-frame state
    v7f_commit7f_*         — single-frame byte-exact state
    DECODE_RAN_*           — first end-to-end decode (still all-zero output)
    FINAL_*                — pre-review final state
    commits_1*             — incremental commit snapshots
    brave_libva_trace_*    — chromeos pipeline ImageProcessor wall reproduction
```

## Reading order

If you want the **end state and reasoning** quickly:

1. `mesa-panvk-bifrost-video/README.md` — what shipped + how byte-exact validation works
2. `mesa-panvk-bifrost-video/phase4_progress.md` — implementation log
3. `mesa-panvk-bifrost/iter17/` — XFB primitive decomposition (r4 close)
4. `mesa-panvk-bifrost/phase0_findings.md` — campaign substrate

If you want the **reproducibility material**:

- The `evidence/*.tgz` files are byte-pinned snapshots of `/home/mfritsche/mesa-build/mesa-26.0.6/src/panfrost/vulkan/` on the development host at each milestone. They are referenced from the marfrit-packages PKGBUILD patch-generation flow.
- The actual patches (`0001-…-bifrost.patch` etc.) live in
  [`marfrit-packages/arch/mesa-panvk-bifrost{,-video}/`](https://git.reauktion.de/marfrit/marfrit-packages).
- Base substrate for diff generation: vanilla `mesa-26.0.6.tar.xz` from
  [`archive.mesa3d.org`](https://archive.mesa3d.org/mesa-26.0.6.tar.xz).

## Hardware scope

- **PineTab2** (Pine64, RK3566, Mali-G52 r1 MC1) — primary development + validation target. All campaign work runs against this device.
- Other Bifrost SBCs (RK3568, RK3399 with G52 variants, etc.) may benefit
  but haven't been tested.
- RK3588 / Mali-G610 is a separate stack — Valhall, not Bifrost — handled
  via different campaigns.

## Process notes (retrofit, 2026-05-23)

This repository was created **after** the campaigns it documents had already
shipped. The packages, patches, and per-iteration docs all existed as either
marfrit-packages commits or local working-tree files; this repo is the
retrofit that puts the lineage under version control with a single canonical
URL the PKGBUILD `url=` field points at.

Future campaigns in the same family should be opened **here from day one**
so each iter is a branch/commit rather than a snapshot.

## License

MIT (see `LICENSE`). Same as upstream Mesa.

## Cross-references

- [marfrit-packages](https://git.reauktion.de/marfrit/marfrit-packages) — PKGBUILDs + CI
- [packages.reauktion.de](https://packages.reauktion.de/arch/aarch64/) — published .pkg.tar.xz artifacts
- [marfrit/fourier#1](https://git.reauktion.de/marfrit/fourier/issues/1) — ffmpeg-vulkan-h264 consumer wall (SYNC_FD handle-type missing; separate from this campaign)