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

diff --git a/userspace/cuda/tools/ghidra_decompile_at.sh b/userspace/cuda/tools/ghidra_decompile_at.sh
new file mode 100755
index 0000000..1fa9035
--- /dev/null
+++ b/userspace/cuda/tools/ghidra_decompile_at.sh
@@ -0,0 +1,29 @@
+#!/bin/bash
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# ghidra_decompile_at.sh - decompile the function containing a file virtual
+# address from an already analyzed project. Version-agnostic replacement for
+# the per-version helper (same idea, any project/binary).
+#
+# Usage: ghidra_decompile_at.sh <project_dir> <project_name> <program> <hex_vaddr> [outfile]
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+GHIDRA_HOME="${GHIDRA_HOME:-/snap/ghidra/current/ghidra}"
+ANALYZE="$GHIDRA_HOME/support/analyzeHeadless"
+export GHIDRA_HEADLESS_MAXMEM="${GHIDRA_HEADLESS_MAXMEM:-12G}"
+
+PROJECT_DIR="${1:?usage: $0 <project_dir> <project_name> <program> <hex_vaddr> [outfile]}"
+PROJECT_NAME="${2:?}"
+PROGRAM="${3:?}"
+VADDR="${4:?}"
+OUT="${5:-$PROJECT_DIR/fn_${VADDR}.c}"
+
+"$ANALYZE" "$PROJECT_DIR" "$PROJECT_NAME" \
+    -process "$PROGRAM" -readOnly -noanalysis \
+    -scriptPath "$HERE/ghidra" \
+    -postScript DecompileAt.java "$VADDR" "$OUT" \
+    2>&1 | tail -3
+
+[ -f "$OUT" ] || { echo "[FAIL] no output"; exit 1; }
+echo "[ok] $OUT"