diff options
Diffstat (limited to 'docs/09-reference')
| -rw-r--r-- | docs/09-reference/glossary-and-faq.md | 27 | ||||
| -rw-r--r-- | docs/09-reference/legal-and-licensing.md | 30 |
2 files changed, 44 insertions, 13 deletions
diff --git a/docs/09-reference/glossary-and-faq.md b/docs/09-reference/glossary-and-faq.md index 255d1a6..2ec4faa 100644 --- a/docs/09-reference/glossary-and-faq.md +++ b/docs/09-reference/glossary-and-faq.md @@ -5,11 +5,15 @@ | Term | Meaning | |---|---| | **AMAPlib** | NVIDIA's shared "address mapping" library: swizzling, bank/channel mapping, aperture rules. Studied for page-table and memory-layout semantics. | +| **Async copy engine (COPY14)** | A copy-engine instance found in the host oracle's engine list but missing from the emulated list — engine descriptor `0x793ceb0e`, instance 14, client type `0x38`, class pair `0xc9b5`. Its absence is the current CUDA context-creation blocker. | | **BAR0 / BAR1 / BAR3** | PCI BAR windows of the GPU: register interface (16 MB), VRAM aperture (256 MB), instance/PRAMIN window. | | **CE** | Copy Engine: DMA engine; also used for UVM's internal work. | +| **Class list (classDB)** | The set of RM classes reported as supported (`GPU_GET_CLASSLIST`); engine queries are filtered against it, so the class list, engine list and caps controls must agree. | | **CUDASW** | The family of NVIDIA user-space software that sits between applications and the driver: `libcuda`, `libcudart`, JIT compiler, fatbinary loader, and friends. | | **Doorbell** | A register/memory location a driver writes to signal "new work is available" for a channel or queue. | | **Engine type** | Numeric identifier for an execution engine (`GR = 0x1`, `COPY0 = 0x9`, ...). | +| **Engine record / engine list** | The per-engine descriptors (kind, instance, class, client type) the driver walks after `GPU_GET_ENGINES`/`GET_ENGINES_V2`; each record must be self-consistent or the driver rewrites the following allocation. | +| **File virtual address (`libcuda+0x...`)** | An address relative to the start of a shared object file (e.g. a `libcuda` offset), as distinct from a runtime mapping or a Ghidra program address; public docs cite these. | | **FWSEC** | Firmware security processor stage of the GSP boot sequence. | | **GNND / GB10** | NVIDIA "Grace-Blackwell" systems-on-chip used in DGX Spark and Surface-class laptops; explicit portability targets. | | **GPFIFO** | GPU FIFO: a ring of entries, each pointing to a push buffer for a channel. | @@ -18,12 +22,15 @@ | **GSP-RM** | The Resource Manager running on the GSP ("self-hosted RM"). | | **GMMU** | GPU Memory Management Unit: page tables, TLB, fault handling. | | **HAL** | Hardware Abstraction Layer: per-generation functions that program registers and formats. | +| **Host oracle / A-B harness** | The same query or deterministic workload run against a bare-metal (host) driver and inside the guest, then diffed — our reference for what the guest should have seen. | | **mdev** | Mediated device: the kernel mechanism that turns a physical device into virtual instances (VFIO). | | **MSGQ** | The GSP message queue transport: shared-memory element rings with a page table, plus doorbells. | | **PBDMA** | Push-buffer DMA engine in the host scheduler that fetches and executes push buffers. | | **PDB** | Page Directory Base: root of a GPU page table. | | **PDE / PTE** | Page-directory entry / page-table entry. | | **Push buffer** | A stream of method calls (engine commands) submitted via a GPFIFO. | +| **QMD** | Queue Meta Data: the per-launch descriptor a GR channel reads to execute a kernel grid. | +| **Reply fidelity** | How completely an emulated reply matches what real hardware returns, as a ladder: status-only → coherent zeroed params → coherent values for consumed fields → exact values. | | **RMCore** | The RM's object system: classes, handles, parents, methods. | | **RM / RM API** | NVIDIA's Resource Manager and the API used to allocate objects and issue controls. | | **resserv / resource server** | The RM component that owns allocation authority, privileges and lifetimes. | @@ -57,10 +64,14 @@ GPU and Open-IOV is an independent module. Building NVIDIA's OpenRM modules from source is only needed for the native-vGPU-management workflows. **Why is `nvidia-smi` working but CUDA not?** -Because CUDA requires *execution*: kernels must run on real hardware. The -current state runs the entire initialization path (including UVM's start-up) -but stops short of executing engine work. See the known-knowns document for -the exact status and plan. +CUDA startup reaches `cuInit` / `cuDeviceGet`, but context creation is blocked: +the emulated engine list lacks the async copy engine (`COPY14`), so +`cuCtxCreate` returns `rc=999` (`CUDA_ERROR_UNKNOWN`) and memory allocation +never runs. (The earlier `libcuda` segfault on this path was fixed by echoing +the request params back in the alloc reply.) Once context creation is green, +CUDA still needs *execution*: kernels must run on real hardware. See the +known-knowns document for the exact status and plan; start at +[`../../userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md). **How is this legal / license-clean?** Open-IOV is BSD-3-Clause (GPL-2.0 for kernel modules that link GPL-only kernel @@ -85,9 +96,11 @@ MIG is a hardware partitioning mechanism; Open-IOV's scheduling policy can use it where available. It is part of the multi-tenancy work. **How fast is it?** -Initialization currently completes in the same order of magnitude as native; -execution forwarding is not implemented yet. Performance claims follow the -published methodology in the operations docs. +No published numbers yet: execution forwarding is not implemented, and even +the initialization path has not been measured under the project's methodology. +Any performance claim will come with the methodology and the measurements +together (see +[`../05-operations/01-performance-correctness-security.md`](../05-operations/01-performance-correctness-security.md)). **Where do I report bugs or ask for help?** Open an issue with the standard captures listed in the debugging document. A diff --git a/docs/09-reference/legal-and-licensing.md b/docs/09-reference/legal-and-licensing.md index 74f1363..57aad43 100644 --- a/docs/09-reference/legal-and-licensing.md +++ b/docs/09-reference/legal-and-licensing.md @@ -30,9 +30,12 @@ In this repository you will find: * **GSP firmware images** (`firmware/**/*.fwimage.bin`) — fetched from public distribution channels (e.g. `linux-firmware`); used to understand and - emulate the firmware interface. -* **Decompiled firmware artifacts** (`firmware/**/decompiled/`) — our own - analysis output; kept for study and cited in the wiki. + emulate the firmware interface. They are **not distributed in this + repository**: like all firmware blobs they are gitignored and kept only as + local study material. +* **Decompiled/disassembled artifacts** (`firmware/**/decompiled/`) — our own + analysis output, kept locally for study and cited in the wiki. They are + gitignored and never committed. * **Reformatted interface tables** — IDs, structures and message layouts that we derived, published in `wiki/` and in this documentation tree. @@ -42,13 +45,28 @@ do not point readers at material we cannot redistribute, and do not redistribute third-party binaries as project content beyond what their terms allow. +**CUDA-userspace (`libcuda`) analysis rules:** + +* Decompiled or disassembled output is never committed; it is gitignored study + material. +* Cite userspace locations as `libcuda+0x...` *file virtual addresses*. Note + the Ghidra image-base caveat: that library is loaded at **`0x100000`**, so a + decompilation produced without translating the offset refers to the wrong + function. +* Tracked docs state facts and evidence; conclusions cite numeric IDs, code + offsets and recorded observations, never source locations. +* Name maps and indexes (`userspace/cuda/*/annotations/`) are our own work + product and may be tracked. + ## 3. Adversarial interoperability and the law We implement the *interface contract* so that unmodified NVIDIA software can talk to our device. We do not: * copy NVIDIA driver code into our kernel module, -* patch NVIDIA drivers or firmware, +* patch the guest, runtime or host driver at run time. The only patch series + we carry is build glue for the optional OpenRM submodule (`install.sh`); the + deployment path uses the distribution's NVIDIA driver as shipped, * defeat licensing for NVIDIA's own products (our device is our device; no impersonation of a licensed product identity). @@ -68,8 +86,8 @@ open an issue: we would rather over-comply than argue. contribution does not contain third-party material under incompatible terms. * Write original code. Describe behaviour, cite the evidence, and reimplement interfaces from observation rather than copying anyone's source. -* Do not commit firmware or ISO images unless they are explicitly permitted and - listed in `.gitattributes`/LFS policy. +* Do not commit firmware or ISO images: they are local study/deployment + material and are gitignored (see §2). ## 5. Export, safety and platform notes |