Known gotchas: IOMMU, firmware blob, HEVC UAPI, compositor vs decode, VOP2 cfg_done, multi-core VDPU381

README.md

@@ -181,6 +181,34 @@ HEVC once the stretch goal is viable.
 Patches upstreamed along the way (v4l2-request to FFmpeg, VDPU346 to
 linux-media) count double — they benefit the whole fleet.
 
+## Known gotchas / watch-for
+
+Sign-posting only — details in linked sources. If you hit one of these,
+expand the bullet with your specific find.
+
+- **IOMMU faults.** Collabora's Feb 2026 VDPU381 landing included specific
+  IOMMU fixes. If dmesg shows rockchip-iommu faults during decode, check
+  you're on a kernel that carries the fixes, not just the driver.
+  ([Collabora post](https://www.collabora.com/news-and-blog/news-and-events/rk3588-and-rk3576-video-decoders-support-merged-in-the-upstream-linux-kernel.html))
+- **Firmware blob.** rkvdec / rkvdec2 need a firmware file under
+  `/lib/firmware/rockchip/` (varies by SoC). Missing blob → driver probe
+  fails silently (no /dev/videoN). Check linux-firmware package currency.
+- **HEVC UAPI version gating.** New explicit RPS controls arrived with
+  the Feb 2026 landing; GStreamer 1.28 + FFmpeg-preliminary honour them.
+  Older userspace on a newer kernel (or vice versa) fails in unintuitive
+  ways. Pin both sides when diagnosing.
+- **Compositor-bound ≠ decode-bound.** The 2023 clehaxze result saw 80%
+  CPU at 1080p60 H.264 — that was the compositor + dmabuf path, not
+  decode. Always attribute CPU with `perf top` / `top -H` before calling
+  decode slow. Use `mpv --vo=null` to isolate the decode path.
+- **VOP2 cfg_done (RK3588).** Decoded frames appear via VP0/VP1/VP2; if
+  the shadow-register latch dance is wrong, frames don't show. See
+  `feedback_rk3588_cfg_done.md` + `project_bin_vp0_theory.md` in noether
+  memory. Touches Coulomb / Bin territory — if it gets there, ask.
+- **Multi-core VDPU381 on RK3588.** Silicon has two decoder cores;
+  upstream multi-core support is still landing. Until then, ampere /
+  boltzmann run on one core and under-deliver vs headline specs.
+
 ## Build infrastructure
 
 Fourier touches two kinds of builds: userspace (FFmpeg + patches, GStreamer,