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.

1 files changed, 44 insertions, 5 deletions

diff --git a/userspace/cuda/570.144/annotations/subsystems.tsv b/userspace/cuda/570.144/annotations/subsystems.tsv
index 5a512bd..4d0c423 100644
--- a/userspace/cuda/570.144/annotations/subsystems.tsv
+++ b/userspace/cuda/570.144/annotations/subsystems.tsv
@@ -25,13 +25,52 @@
 # --- 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
+0x453ef0	cudaEngineContextRegisterHelper	engine-engines	per-engine registration: idx = record+0 kind (1 normalizes to 0), alloc handle, call create hook with the record, call bind hook, publish engine id at ctx+0x50+idx*4 and the record pointer at ctx[0x9488]+0x88+idx*8; called twice for engine index 0 (GR + secondary async CE)	decompiled+trace
+0x45a670	cudaDeviceInitEngineContexts	engine-engines	per-context engine-init hook installed at ctx+0x94b0; selects the 0x14-byte engine record for ctx+0x38 (GR at +0x2fec; copy at +0x300c+(idx-1)*0x14, +0x300c+(idx-2)*0x14 for idx 0xc..0x15; SEC2 at +0x350c; decomp copy at +0x351c+(idx-0x16)*0x14), checks existence via [table+0x4e00](table, record+0xc), calls the helper; for index 0 also registers the secondary record at *(table+0x4af0)+0x75c	decompiled+trace
+0x4676f0	cudaEngineContextCreateHook	engine-engines	create hook at [table+0x40]+0x530; reads record kind +0, instance +8, class +0xc; copies instance into RM alloc-param dword 1 only for kinds 2/3/5; passes record+0xc as the alloc class to 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); the typed pass recovered its 4 parameters and the field logic (run/analysis/typed/fn_0x4676f0.c)	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 with the record as params) and returns small status codes; class comes from the engine record, so a zeroed secondary record means class 0 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
+# --- engine record construction (the record identity and the COPY14 blocker; see docs/05 section 3.7) ---
+0x450ff0	cudaDeviceBuildEngineRecords	engine-engines	builds the 0x14-byte per-engine records from the GET_ENGINES_V2 list at device+0x2aa8 (count +0x2fe8): kind 1 GR -> +0x2fec (class device+0xd38), kind 3 copy -> +0x300c+n*0x14 (class +0xd44, caps bit0 = CE_GRCE also seeds the secondary record at *(device+0x4af0)+0x75c), kind 4 SEC2 -> +0x350c (class +0xd4c), kind 5 decomp copy -> +0x351c+n*0x14 (class +0xd50); fields +0 kind, +4 NV2080 engine type, +8 instance, +0xc class, +0x10 caps	decompiled+trace
+0x462770	cudaRmGetEngines	engine-engines	RM control AL wrapper for NV2080_CTRL_CMD_GPU_GET_ENGINES_V2: reads the engine list and classifies each raw NV2080 engine type into {kind, type, instance} records at 0x10-byte stride (GR 1..8 -> kind 1; copy 9..0x12 and 0x34..0x3d -> kind 3; decomp copy 0x40..0x53 -> kind 5; SEC2 0x26 -> kind 4; others skipped); called from 0x44ac20 via AL slot 0x1d8	decompiled
+0x44a170	cudaDeviceSupportsClass	engine-engines	device class-list membership callback installed at device+0x4e00 by the ABI table setup (0x458040 and 0x4494d0): returns true when class is in the class list at device+0xd90 (count +0xd98); the walker calls it with (device, record+0xc) before registering an engine	decompiled+trace
+0x458040	cudaDeviceAbiTableInit	engine-engines	builds the RM device state and installs the device ABI function table at device+0x4d18.. (engine builder +0x4d88, class callback +0x4e00 = 0x44a170, ctx table setup +0x4ef0, init caps +0x4d38); class list copied from the config block into device+0xd90/+0xd98	decompiled
+0x44ac20	cudaDeviceInitCaps	engine-engines	device init-caps path: calls the AL getEngines slot 0x1d8 (0x462770) to fill device+0x2aa8/+0x2fe8, then the ABI static-info hooks; the engine list it produces is what the record builder consumes	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
+0x45a670	cudaDeviceInitEngineContexts	engine-engines	CURRENT BLOCKER: the GET_ENGINES_V2 list has 6 engines in the guest (GR + CE0..4) vs 7 on the host oracle (adds async CE COPY14: engDesc 0x793ceb0e, NV2080 type 0x38, instance 14, paired class 0xc9b5); the classDB filter drops COPY14, so no copy record carries CE_GRCE (caps bit0, live guest 0xbc/0xfc) and the secondary record at *(table+0x4af0)+0x75c stays zero (host t=2 cls=0xc5b5); the zero class is rewritten to 0x41 (st 0x19) and the context rolls back. Record field map and builder chain in docs/05 section 3.7	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
+# --- wrapper callees verified in the 2026-09 name-candidate pass ---
+# Names proposed by tools/name_candidates.py (see name-candidates.tsv), each
+# verified by reading its body in the 570.144 corpus; source `wrapper-callee`
+# in names.tsv. Evidence: decompiled.
+0x1a36d0	impl_cuCtxGetApiVersion	api	current-context API version getter: resolves the thread context and returns its API-version field	decompiled (wrapper-callee)
+0x1a4900	impl_cuArrayGetMemoryRequirements	mem	array memory-requirements getter: refreshes the backing-store state under the context mutex and returns the allocation size	decompiled (wrapper-callee)
+0x1a5410	impl_cuArrayGetPlane	mem	array plane getter: validates the plane index and returns the plane handle	decompiled (wrapper-callee)
+0x1a5820	impl_cuDevicePrimaryCtxGetState	api	primary-context state getter: reads flags/active state under the device mutex	decompiled (wrapper-callee)
+0x1a6150	impl_cuDeviceRegisterAsyncNotification	api	device async-notification registration: allocates and links a notification record under the device mutex	decompiled (wrapper-callee)
+0x1a6430	impl_cuCtxAttach	api	context attach: increments the context attach refcount under the context lock	decompiled (wrapper-callee)
+0x1a66f0	impl_cuCtxGetCurrent	api	current-context getter: returns the calling thread's context from TLS	decompiled (wrapper-callee)
+0x1a6850	impl_cuCtxGetDevice	api	context device getter: resolves the current context and returns its device ordinal	decompiled (wrapper-callee)
+0x1a6960	impl_cuCtxGetFlags	api	context flags getter: composes flags from context fields under the context lock	decompiled (wrapper-callee)
+0x1a6af0	impl_cuFlushGPUDirectRDMAWrites	api	GPUDirect RDMA write flush: validates args and dispatches through the device op table	decompiled (wrapper-callee)
+0x1a6c50	impl_cuCtxGetExecAffinity	api	context exec-affinity getter: returns the affinity value under the context lock	decompiled (wrapper-callee)
+0x1a7320	impl_cuDeviceGetLuid	api	device LUID getter: bounds-checks the ordinal and calls the device op at table+0x5180	decompiled (wrapper-callee)
+0x1ae3d0	impl_cuDeviceComputeCapability	api	compute-capability getter: reads device attributes 0x4b/0x4c	decompiled (wrapper-callee)
+0x1ae550	impl_cuDeviceGetProperties	api	device properties getter: fills CUDA device properties from the device record	decompiled (wrapper-callee)
+0x1ae780	impl_cuDeviceGetAttribute	api	device attribute getter: validates the ordinal and reads one attribute (fast path for attribute 0x20080403)	decompiled (wrapper-callee)
+0x1be900	impl_cuCtxDestroy	api	context destroy: validates the handle, takes the context lock and tears the context down	decompiled (wrapper-callee)
+0x1da450	impl_cuMemFree	mem	device memory free: resolves the allocation under the context lock and frees it	decompiled (wrapper-callee)
+0x1da880	impl_cuMemFreeHost	mem	host memory free: frees pinned host memory (or routes to the device free path)	decompiled (wrapper-callee)
+0x1e9ab0	impl_cuModuleLoad	module	module load from file: reads the file and parses it into the context	decompiled (wrapper-callee)
+0x1e9d80	impl_cuModuleLoadData	module	module load from memory image: same path as file load with an in-memory image	decompiled (wrapper-callee)
+0x2891d0	impl_cuEventDestroy	sync	event destroy: unlinks and frees an event under the context mutex	decompiled (wrapper-callee)
+0x2a6bf0	impl_cuGraphDebugDotPrint	launch	graph DOT dump: writes the graph as a DOT debug file	decompiled (wrapper-callee)
+0x2ce4e0	impl_cuLinkCreate	jit	linker create: allocates and initializes the linker state	decompiled (wrapper-callee)
+0x2f9f00	impl_cuModuleGetGlobal	module	module global getter: resolves a named global through the module symbol table	decompiled (wrapper-callee)
+0x3c9250	impl_cuMemFreeAsync	mem	async device memory free: resolves the allocation and frees it on a stream	decompiled (wrapper-callee)
+0x400ec0	impl_cuMemAlloc	mem	device memory alloc: validates/derives the allocation descriptor and allocates	decompiled (wrapper-callee)
+0x402a30	impl_cuMemGetAddressRange	mem	allocation lookup: resolves the allocation containing an address under the context mutex	decompiled (wrapper-callee)
+0xd11d90	impl_cuStreamBeginCapture	stream	stream begin capture: validates the mode and starts capture under the stream lock	decompiled (wrapper-callee)
+0xd668f0	impl_cuLibraryGetUnifiedFunction	module	library function getter: resolves a named function through the library symbol table	decompiled (wrapper-callee)