From 13f46e60760cc0855484cc69de913ea34f55c24f Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Wed, 23 Sep 2026 12:11:10 -0400 Subject: docs: refresh status, supersede stale material, link the CUDA analysis * Status now matches the live state: guest driver probe and nvidia-smi work; cuInit/device queries work; cuCtxCreate returns 999 because the emulated engine list is missing the async copy engine (COPY14). The userspace libcuda segfault is recorded as solved, with its mechanism (an RM allocation reply must echo request parameters; zeroing them corrupted the caller's saved frame pointer). * Correct the emulation claims: only a subset of RM controls are special-cased; the rest return a success reply with zeroed parameters whose consumed fields are still being corrected; allocation replies are coherent but no server-side object model exists. * Add the eight-point emulation checklist and reply-fidelity ladder as explicit gates, documented in userspace/cuda and linked from the architecture, implementation and operations docs. * Fix operational errors: build/test commands, module load order, mdev type names, LFS references, debugfs claims, in-repo firmware claims, CI claims, portability matrix (guest status, config layout, userspace driver facts). * Mark historical material: one superseded banner per legacy document with a pointer to its replacement; STATE.md marked as a 2026-09-21 snapshot. * Wiki: fix the index, add status banners and in-place factual corrections (msgq transport vs legacy mailbox, BAR definitions, error statuses, migration, glossary), and note the archived 2023 imports. --- docs/02-getting-started/01-install-and-first-run.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) (limited to 'docs/02-getting-started/01-install-and-first-run.md') diff --git a/docs/02-getting-started/01-install-and-first-run.md b/docs/02-getting-started/01-install-and-first-run.md index e0e71cb..f323dbb 100644 --- a/docs/02-getting-started/01-install-and-first-run.md +++ b/docs/02-getting-started/01-install-and-first-run.md @@ -100,8 +100,12 @@ Inside the guest (the reference guest has SSH and a guest agent configured): ```bash sudo apt update sudo apt install -y linux-headers-generic build-essential -# Install the stock NVIDIA driver matching the firmware/driver profile -sudo apt install -y nvidia-driver-570-open +# Install the stock NVIDIA driver matching the emulation profile. +# The validated combination is the stock 570.144 Linux runfile (same driver +# version as the emulation target). The distro 570.x package can install a +# different 570 build; if you use it, keep the version notes from the +# hardware/software matrix at hand. +sudo sh ./NVIDIA-Linux-x86_64-570.144.run sudo reboot ``` @@ -126,10 +130,12 @@ cd cuda-samples/Samples/1_Utilities/deviceQuery && make && ./deviceQuery ``` **Expectation today:** driver probe, `nvidia-smi`, device enumeration, and the -early CUDA start-up path work; full kernel execution is the active work item. -Read the honest status in +first CUDA calls (`cuInit`, device queries) work. `cuCtxCreate` still fails +with `999` because the emulated engine list is missing the async copy engine; +full kernel execution is not reached yet. Before drawing conclusions from a +CUDA failure, read the honest status in [`../04-implementation/01-known-knowns-and-unknowns.md`](../04-implementation/01-known-knowns-and-unknowns.md) -before drawing conclusions from a CUDA failure. +and the debugger's guide [`../../userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md). ## 7. Day-to-day operations @@ -166,7 +172,7 @@ Developer debug knobs (module parameters) are documented in | No mdev type for your GPU | [hardware matrix](../06-portability/hardware-software-matrix.md) | | Guest sees wrong PCIe link speed/width | root-port attachment + config-space mirror (debugging doc) | | `nvidia.ko` probe fails in guest | guest dmesg + `lspci -vvv` + handoff "driver lifecycle" | -| `nvidia-smi` works, CUDA does not | expected today; see the known-knowns doc | +| `nvidia-smi` works, CUDA does not | expected today (`cuCtxCreate` = 999, engine-list gap); see [`../04-implementation/01-known-knowns-and-unknowns.md`](../04-implementation/01-known-knowns-and-unknowns.md) and [`../../userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md) | | VM boot fails or the guest hangs | `scripts/stack_manager.sh cleanup-crash`, then reboot | ## 10. Uninstall -- cgit v1.2.3