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, 37 insertions, 0 deletions

diff --git a/userspace/cuda/570.144/annotations/subsystems.tsv b/userspace/cuda/570.144/annotations/subsystems.tsv
new file mode 100644
index 0000000..5a512bd
--- /dev/null
+++ b/userspace/cuda/570.144/annotations/subsystems.tsv
@@ -0,0 +1,37 @@
+# Open-IOV CUDA 570.144 subsystem index (tracked)
+#
+# Format: file_vaddr<TAB>name<TAB>subsystem<TAB>role<TAB>evidence
+# Addresses are FILE virtual addresses (libcuda+0x...). See README.md.
+#
+# subsystem values: api | engine | engine-engines | mem | stream | launch | sync |
+#                   module | rm | uvm | jit | table | unknown
+# evidence: decompiled (address inspected in the 570.144 corpus), trace (live),
+#           relocation (derived from the stub), todo (open question)
+#
+# --- public API entry stubs (generated) ---
+0x310060	cuInit	api	exported entry stub; checks destroyed-state then jumps through interposition slot	relocation
+0x310360	cuCtxCreate_v2	api	exported entry stub	relocation
+0x310b20	cuMemAlloc_v2	api	exported entry stub	relocation
+0x3106e0	cuModuleLoadData	api	exported entry stub	relocation
+0x36f420	cuLaunchKernel	api	exported entry stub	relocation
+0x36f3c0	cuStreamSynchronize	api	exported entry stub	relocation
+# --- generated wrappers (tracing/tool dispatch) ---
+0x31b7f0	wrapper_cuInit	api	initial interposition target for cuInit	relocation
+0x3206d0	wrapper_cuCtxCreate_v2	api	initial interposition target for cuCtxCreate_v2	relocation
+0x329830	wrapper_cuMemAlloc_v2	api	initial interposition target for cuMemAlloc_v2	relocation
+0x324ed0	wrapper_cuModuleLoadData	api	initial interposition target for cuModuleLoadData	relocation
+0x3810f0	wrapper_cuLaunchKernel	api	initial interposition target for cuLaunchKernel	relocation
+0x380b40	wrapper_cuStreamSynchronize	api	initial interposition target for cuStreamSynchronize	relocation
+# --- engine/context bring-up (the cuCtxCreate path: crash solved, engine topology blocking; see docs/05) ---
+0x3a9c20	cudaHandlePoolAlloc	engine	bitmap handle allocator: lock, scan 64-bit words for first zero bit, return base + index*64 + bit	decompiled
+0x3a2f50	cudaHandlePoolFree	engine	clears the handle bit under the pool mutex	decompiled
+0x453ef0	cudaEngineContextRegisterHelper	engine-engines	per-engine registration: alloc handle, call create hook, call bind hook, publish engine id + descriptor into context arrays; called twice for engine index 0 (GR + secondary async CE)	decompiled+trace
+0x45a670	cudaDeviceInitEngineContexts	engine-engines	walks 0x14-byte engine records (base+0x2fec for GR; +0x300c+(idx-1)*0x14; +0x350c; +0x351c+(idx-0x16)*0x14), checks engine existence via [table+0x4e00], calls the helper; sees only GR + CE0..4 because the GET_ENGINES_V2/classDB filter drops the async CE (see docs/05 section 3.6)	decompiled+trace
+0x4676f0	cudaEngineContextCreateHook	engine-engines	hook at [table+0x40]+0x530; selects instance/class from the engine descriptor and calls rmEngineContextAlloc; its saved rbp was zeroed by the alloc reply's 16-byte class-params copy-back (crash solved, see docs/05 section 3.5)	decompiled+trace
+0x481360	rmEngineContextAlloc	rm	builds NV_ESC_RM_ALLOC requests per class (0x80 device, 0x5/0x79 per-class table, 0x2080 subdevice array of 32, default generic) and returns small status codes; with a zeroed secondary engine record the class is rewritten to NV01_ROOT_CLIENT (0x41), status 0x19, and the context rolls back (rc=999)	decompiled+trace
+0x453cc0	cudaEngineContextCleanup	engine-engines	failure-path cleanup of an engine context; runs on the rolled-back context (rc=999)	decompiled
+# --- CURRENT BLOCKER (2026-09-23): engine list / classDB consistency (async CE COPY14) ---
+0x45a670	cudaDeviceInitEngineContexts	engine-engines	CURRENT BLOCKER: classDB-filtered engine list has 6 engines in the guest (GR + CE0..4) vs 7 on the host oracle (adds async CE COPY14: engDesc 0x793ceb0e, instance 14, client type 0x38, class 0xc9b5); without a classDB entry the walker reads a zeroed secondary record and the RM alloc is rejected (class 0x41, st 0x19). Record layout above; see docs/05 section 3.6	decompiled+trace
+# --- open questions ---
+0x4a7e90	FUN_004a7e90	unknown	called by every generated wrapper; likely tool/trace dispatch or thread-data helper	todo
+0x2cb940	FUN_002cb940	unknown	large function (10 KB) reachable from the cuInit wrapper; candidate init implementation	todo