From f874d709e5a45d63c8ee9ab6b0300195aa5d20a5 Mon Sep 17 00:00:00 2001
From: Arthur Hanson Rasmusson <arthur@vgpu.io>
Date: Wed, 23 Sep 2026 12:11:04 -0400
Subject: 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).
---
 userspace/cuda/tools/ghidra/ConfigureAnalysis.java | 84 ++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 userspace/cuda/tools/ghidra/ConfigureAnalysis.java

(limited to 'userspace/cuda/tools/ghidra/ConfigureAnalysis.java')

diff --git a/userspace/cuda/tools/ghidra/ConfigureAnalysis.java b/userspace/cuda/tools/ghidra/ConfigureAnalysis.java
new file mode 100644
index 0000000..71bb75e
--- /dev/null
+++ b/userspace/cuda/tools/ghidra/ConfigureAnalysis.java
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// ConfigureAnalysis.java - Ghidra pre-script used by the Open-IOV CUDA
+// tooling to make headless auto-analysis of a large stripped vendor library
+// tractable and reproducible.
+//
+// The CUDA userspace driver is a ~70 MB, fully stripped x86-64 shared object
+// with roughly a hundred thousand functions. The default analyzer set spends
+// the majority of its time in the two optional "identifier" analyzers, which
+// are not needed to obtain readable decompilation:
+//
+//   * Decompiler Parameter ID  - decompiles every function to recover
+//                                parameter types (very expensive, no value
+//                                for a stripped binary where we have no
+//                                type definitions for internal structs)
+//   * Function ID (FID)        - matches function bodies against .fidb
+//                                signature databases (liberal, and we have
+//                                no curated database for this toolchain)
+//
+// Everything else (disassembly, function start search, aggressive instruction
+// finder, exception handling, stack analysis, reference analyzers, ...) is
+// kept, because function discovery quality on a stripped binary depends on
+// them.
+//
+// Usage (analyzeHeadless):
+//   -preScript ConfigureAnalysis.java [verbose]
+//
+// Re-runnable: the same settings are applied on every analysis of a program.
+
+import ghidra.app.script.GhidraScript;
+import ghidra.framework.options.Options;
+
+public class ConfigureAnalysis extends GhidraScript {
+
+    private static final String[] DISABLE = {
+        "Decompiler Parameter ID",
+        "Function ID",
+    };
+
+    private static final String[] ENABLE = {
+        "Aggressive Instruction Finder",
+        "GCC Exception Handlers",
+        "Function Start Search",
+        "Shared Return Calls",
+        "Non-Returning Functions - Known",
+        "Non-Returning Functions - Discovered",
+    };
+
+    @Override
+    public void run() throws Exception {
+        boolean verbose = getScriptArgs().length > 0;
+        Options opts = currentProgram.getOptions("Analyzers");
+
+        if (verbose) {
+            println("[ConfigureAnalysis] analyzer options before:");
+            for (String name : opts.getOptionNames()) {
+                println("  " + name + " = " + opts.getObject(name, null));
+            }
+        }
+
+        for (String name : DISABLE) {
+            if (opts.contains(name)) {
+                opts.setBoolean(name, false);
+                println("[ConfigureAnalysis] disabled: " + name);
+            } else {
+                println("[ConfigureAnalysis] WARN not found: " + name);
+            }
+        }
+
+        for (String name : ENABLE) {
+            if (opts.contains(name)) {
+                opts.setBoolean(name, true);
+                println("[ConfigureAnalysis] enabled: " + name);
+            }
+        }
+
+        if (verbose) {
+            println("[ConfigureAnalysis] analyzer options after:");
+            for (String name : opts.getOptionNames()) {
+                println("  " + name + " = " + opts.getObject(name, null));
+            }
+        }
+    }
+}
-- 
cgit v1.2.3