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.