userspace/cuda: complete the analysis pass

* Name recovery: name_candidates.py proposes the hand-written API-layer
  implementation for each exported wrapper by grouping version variants and
  intersecting their callees; 180 high-confidence proposals recorded in
  annotations/name-candidates.tsv, 29 of them body-verified and promoted to
  names.tsv with evidence in subsystems.tsv.
* Engine records: identified the 0x14-byte per-engine descriptor, mapped its
  fields (kind, engine type, instance, class id, CE caps) and the existence
  callback, and documented how the missing async copy engine (COPY14) leaves
  the secondary record zeroed and blocks context creation (docs/05 section
  3.7, public-safe).
* Targeted type recovery: AnalyzeFunctions.java runs the parameter-ID
  analyzer over a curated list of 80 functions; 16 improved materially and
  the typed decompilations are kept under the version run tree.
* Cross-version: cudatool.py fdematch measures how names transfer between
  patch versions (570.144 -> 570.211.01: exports 100%, verified internals
  ~70%, generated wrappers must be re-resolved by relocation, never by
  address arithmetic); documented in the upgrade playbook.
* Corpus tooling: diff_corpus.py (version-to-version corpus diff) and
  subsystem_digest.py (per-subsystem call trees).
* Deprecate the old per-version helpers whose address handling and analysis
  timeout produced wrong results.

Generated corpora and typed outputs remain untracked under the version run
tree.

2 files changed, 28 insertions, 0 deletions

diff --git a/userspace/cuda/570.144/scripts/ghidra_analyze.sh b/userspace/cuda/570.144/scripts/ghidra_analyze.sh
index b844300..eb8422b 100755
--- a/userspace/cuda/570.144/scripts/ghidra_analyze.sh
+++ b/userspace/cuda/570.144/scripts/ghidra_analyze.sh
@@ -1,6 +1,21 @@
 #!/bin/bash
 # SPDX-License-Identifier: BSD-3-Clause
 #
+# ###########################################################################
+# # WARNING: DEPRECATED - DO NOT USE FOR NEW ANALYSIS (kept for history).   #
+# #                                                                         #
+# # Two bugs make its output unusable:                                      #
+# #  1. It passes FILE virtual addresses to Ghidra, which loads these       #
+# #     binaries at image base 0x100000. Every address is 0x100000 too low, #
+# #     so the decompiled "functions" are the wrong ones.                   #
+# #  2. `-analysisTimeoutPerFile 0` does not mean "no timeout" in this      #
+# #     Ghidra build: it aborts auto-analysis immediately, producing an     #
+# #     analysed-looking project with no analysis at all.                   #
+# #                                                                         #
+# # Replacement: tools/ghidra_full_analysis.sh (plus                        #
+# # tools/ghidra/ConfigureAnalysis.java).                                   #
+# ###########################################################################
+#
 # ghidra_analyze.sh - import a library into a Ghidra project and run the full
 # auto-analysis once. The project is kept, so later decompilations are cheap:
 #
diff --git a/userspace/cuda/570.144/scripts/ghidra_decompile_project.sh b/userspace/cuda/570.144/scripts/ghidra_decompile_project.sh
index 66d7c90..b44b2b2 100755
--- a/userspace/cuda/570.144/scripts/ghidra_decompile_project.sh
+++ b/userspace/cuda/570.144/scripts/ghidra_decompile_project.sh
@@ -1,6 +1,19 @@
 #!/bin/bash
 # SPDX-License-Identifier: BSD-3-Clause
 #
+# ###########################################################################
+# # WARNING: DEPRECATED - DO NOT USE FOR NEW ANALYSIS (kept for history).   #
+# #                                                                         #
+# # It passes a FILE virtual address straight to 570.144/ghidra/            #
+# # DecompileAt.java, but Ghidra loads these binaries at image base         #
+# # 0x100000: the script resolves (and decompiles) the function 0x100000    #
+# # bytes too low. It also depends on a project produced by the broken      #
+# # ghidra_analyze.sh above.                                                #
+# #                                                                         #
+# # Replacement: tools/ghidra_decompile_at.sh, which translates the file    #
+# # vaddr with tools/ghidra/DecompileAt.java (file-vaddr aware).            #
+# ###########################################################################
+#
 # ghidra_decompile_project.sh - decompile a function from an already-analyzed
 # Ghidra project (run scripts/ghidra_analyze.sh once first). No re-import and
 # no analysis, so this takes seconds.