userspace/cuda: add CUDA userspace driver analysis, tooling and name maps

Add the analysis of the NVIDIA CUDA userspace driver used by Open-IOV VMs:

* docs/01-08: architecture (layers, object model, threads, sync, memory,
  channels, launch), build and execution model, the driver/kernel/GPU
  interface contract, virtualization approaches, the 570.144 decompilation
  map with the corrected libcuda crash path and the current engine-topology
  blocker, tooling, and a version-upgrade playbook.
* tools/: version-agnostic toolchain - stdlib ELF/interface toolkit
  (exports, unwind-table function map, wrapper resolution, version delta,
  crash address decode), callgraph walker, corpus annotator, and Ghidra
  analysis/decompilation/name-map scripts with resumable parallel drivers.
* 570.144/annotations/: our name map (exports + resolved wrappers + verified
  internals) and subsystem index, tracked so naming work accumulates.
* READ-ME-FIRST.md: reading guide with the fast lookup recipes.

The full decompiled corpus and annotated corpus stay untracked (vendor-
derived, gitignored under the version run/ tree).

1 files changed, 35 insertions, 0 deletions

diff --git a/userspace/cuda/570.144/annotations/README.md b/userspace/cuda/570.144/annotations/README.md
new file mode 100644
index 0000000..868c503
--- /dev/null
+++ b/userspace/cuda/570.144/annotations/README.md
@@ -0,0 +1,35 @@
+# Open-IOV CUDA analysis annotations (tracked)
+
+These files are our own work product: names, roles and evidence for functions
+in the CUDA userspace driver. They are tracked in git so that analysis effort
+accumulates across driver versions.
+
+## Files
+
+| File | Format | Purpose |
+|---|---|---|
+| `names.tsv` | `file_vaddr<TAB>name<TAB>source` | symbol map to apply to a Ghidra project (or any address-keyed analysis). `source` is `export`, `wrapper`, `verified`, or `todo`. |
+| `subsystems.tsv` | `file_vaddr<TAB>name<TAB>subsystem<TAB>role<TAB>evidence` | human-readable subsystem index: which function belongs to which layer and what it does, with the evidence for the claim. |
+
+Addresses are **file virtual addresses** (`libcuda+0x...`). Apply the map with
+`tools/ghidra/ApplyNameMap.java`; see `docs/06-tooling.md`.
+
+## How names.tsv is generated
+
+1. **Exports** — exact, from `.dynsym` (`tools/cudatool.py exports`).
+2. **Wrappers** — the generated `cu*` stubs jump through an interposition slot
+   whose initial value is a relocation to the generated wrapper function.
+   `tools/cudatool.py wrappers` resolves all of them; they are named
+   `wrapper_<export>`.
+3. **Verified internals** — functions read and understood during the
+   decompilation effort. Each is added by hand with evidence recorded in
+   `subsystems.tsv` and the public docs.
+4. **Transfers** — when a new driver version is analysed, apply the previous
+   map, check how many names land (`ApplyNameMap.java --dry-run`), fix the
+   misses, and record the delta for the version.
+
+## Rules
+
+* Never guess silently. A name without evidence is worse than `FUN_...`; put
+  open questions in `subsystems.tsv` with `evidence=todo` instead.
+* Names must describe behaviour, not vendor internals we cannot justify.