# 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.