diff options
Diffstat (limited to 'docs/README.md')
| -rw-r--r-- | docs/README.md | 97 |
1 files changed, 56 insertions, 41 deletions
diff --git a/docs/README.md b/docs/README.md index 24b2a21..81f02c8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,33 +31,41 @@ generations (Turing, Ampere, Hopper, Grace-Hopper, Grace-Blackwell, GB10, ...) and many driver versions — without any of those ecosystems, operating systems, drivers or devices having to change. +```mermaid +flowchart TB + subgraph VM["Guest VM - stock drivers, stock applications"] + A["CUDA / OpenGL / Vulkan applications"] + B["Userspace stack - libcuda, libcudart, libGLX, libvulkan"] + C["Stock nvidia.ko - RM core and UVM"] + A --> B --> C + end + subgraph HYP["Hypervisor - KVM and QEMU"] + D["VFIO mdev transport + IOMMU isolation"] + end + subgraph MOD["open-iov-vfio.ko - the only host component"] + E["Virtual device - BARs, config space, MSI-X"] + F["GSP boot + GSP-RM emulation"] + G["Memory model + work path"] + H["Execution backend - real GSP session"] + E --> F --> G --> H + end + C -->|"emulated PCIe"| D --> E + H --> I["Physical GPU - engines, GMMU, VRAM"] + classDef done fill:#d5f5d5,stroke:#1e7a1e + classDef wip fill:#fff3cd,stroke:#9a7b1a + classDef plan fill:#f8d7da,stroke:#9a1a1a + classDef hw fill:#e2e8f0,stroke:#4a5568 + class E,F done + class G wip + class H plan + class I hw ``` - ┌─────────────────────────────────────────────┐ - │ GUEST VM │ - │ stock nvidia.ko + CUDA / OpenGL / Vulkan │ - └──────────────┬──────────────────────────────┘ - │ PCIe (emulated device) - ┌───────────────────────────────┴───────────────────────────────┐ - │ HYPERVISOR (KVM/Xen) │ - │ VFIO / mdev transport, IOMMU isolation │ - └───────────────────────────────┬───────────────────────────────┘ - │ - ┌───────────────────────────────┴───────────────────────────────┐ - │ HOST: open-iov-vfio.ko (this project) │ - │ • virtual GPU device (BARs, config space, MSI-X) │ - │ • GSP / GSP-RM interface emulation (RPC, msgq, controls) │ - │ • memory model + GPU work forwarding to the physical GPU │ - └───────────────────────────────┬───────────────────────────────┘ - │ - ┌──────────────┴──────────────┐ - │ UNMODIFIED host nvidia.ko │ - │ (or GPU passthrough path) │ - └──────────────┬──────────────┘ - │ - ┌───────┴────────┐ - │ NVIDIA GPU │ - └────────────────┘ -``` + +The full visual map — every component, status tag and interaction — is in +[`03-architecture/09-full-system-picture.md`](03-architecture/09-full-system-picture.md) +(end-to-end) and +[`03-architecture/10-interaction-and-scheduling.md`](03-architecture/10-interaction-and-scheduling.md) +(call paths, queues, interrupts, scheduling). ## 2. Why does this need to exist? @@ -118,6 +126,11 @@ control; the chosen backend — a module-owned GPU running its real GSP firmware as the resource-manager server — is specified in [`03-architecture/08-physical-gpu-integration.md`](03-architecture/08-physical-gpu-integration.md). +For the visual end-state map and the cross-component call paths, see +[`03-architecture/09-full-system-picture.md`](03-architecture/09-full-system-picture.md) +and +[`03-architecture/10-interaction-and-scheduling.md`](03-architecture/10-interaction-and-scheduling.md). + ## 4. How to read these docs (progressive disclosure) Read in order if you are new. Jump directly if you know what you need. @@ -135,21 +148,23 @@ Read in order if you are new. Jump directly if you know what you need. | 2 | [The AI edge and the ecosystem](01-orientation/02-the-ai-edge-and-ecosystem.md) | everyone | 15 min | | 3 | [Install and first run](02-getting-started/01-install-and-first-run.md) | users, evaluators | 20 min | | 4 | [System overview](03-architecture/01-system-overview.md) | everyone technical | 20 min | -| 5 | [Guest stack and CUDASW](03-architecture/02-guest-stack-and-cudasw.md) | developers | 25 min | -| 6 | [GSP and GSP-RM](03-architecture/03-gsp-and-gsp-rm.md) | developers | 30 min | -| 7 | [UVM](03-architecture/04-uvm.md) | developers | 25 min | -| 8 | [GMMU, AMAPlib, HALs, runlist, GR](03-architecture/05-gmmu-amap-hal-gr.md) | developers | 25 min | -| 9 | [Host module and hybrid model](03-architecture/06-host-module-and-hybrid-model.md) | developers | 25 min | -| 10 | [Driver lifecycle field guide](03-architecture/07-driver-lifecycle-field-guide.md) | developers, debuggers | 30 min | -| 11 | [Physical GPU integration](03-architecture/08-physical-gpu-integration.md) | developers, architects | 20 min | -| 12 | [Known-knowns and known-unknowns](04-implementation/01-known-knowns-and-unknowns.md) | everyone technical | 25 min | -| 13 | [Practical challenges and adversarial interoperability](04-implementation/02-practical-challenges-and-adversarial-interop.md) | developers, stakeholders | 20 min | -| 14 | [Performance, correctness, security](05-operations/01-performance-correctness-security.md) | developers, auditors | 25 min | -| 15 | [Debugging and maintenance workflows](05-operations/02-debugging-and-maintenance-workflows.md) | developers, maintainers | 25 min | -| 16 | [Hardware and software matrix](06-portability/hardware-software-matrix.md) | developers, integrators | 20 min | -| 17 | [Developer onboarding and standards](07-developers/onboarding-and-standards.md) | contributors | 20 min | -| 18 | [HAAEEP and collaboration](08-ecosystem/haaeep-and-collaboration.md) | stakeholders, partners | 20 min | -| 19 | [Glossary and FAQ](09-reference/glossary-and-faq.md) | everyone | reference | +| 5 | [The full system picture](03-architecture/09-full-system-picture.md) | everyone technical | 30 min | +| 6 | [Interaction and scheduling](03-architecture/10-interaction-and-scheduling.md) | developers | 30 min | +| 7 | [Guest stack and CUDASW](03-architecture/02-guest-stack-and-cudasw.md) | developers | 25 min | +| 8 | [GSP and GSP-RM](03-architecture/03-gsp-and-gsp-rm.md) | developers | 30 min | +| 9 | [UVM](03-architecture/04-uvm.md) | developers | 25 min | +| 10 | [GMMU, AMAPlib, HALs, runlist, GR](03-architecture/05-gmmu-amap-hal-gr.md) | developers | 25 min | +| 11 | [Host module and hybrid model](03-architecture/06-host-module-and-hybrid-model.md) | developers | 25 min | +| 12 | [Driver lifecycle field guide](03-architecture/07-driver-lifecycle-field-guide.md) | developers, debuggers | 30 min | +| 13 | [Physical GPU integration](03-architecture/08-physical-gpu-integration.md) | developers, architects | 20 min | +| 14 | [Known-knowns and known-unknowns](04-implementation/01-known-knowns-and-unknowns.md) | everyone technical | 25 min | +| 15 | [Practical challenges and adversarial interoperability](04-implementation/02-practical-challenges-and-adversarial-interop.md) | developers, stakeholders | 20 min | +| 16 | [Performance, correctness, security](05-operations/01-performance-correctness-security.md) | developers, auditors | 25 min | +| 17 | [Debugging and maintenance workflows](05-operations/02-debugging-and-maintenance-workflows.md) | developers, maintainers | 25 min | +| 18 | [Hardware and software matrix](06-portability/hardware-software-matrix.md) | developers, integrators | 20 min | +| 19 | [Developer onboarding and standards](07-developers/onboarding-and-standards.md) | contributors | 20 min | +| 20 | [HAAEEP and collaboration](08-ecosystem/haaeep-and-collaboration.md) | stakeholders, partners | 20 min | +| 21 | [Glossary and FAQ](09-reference/glossary-and-faq.md) | everyone | reference | Deep-dive material lives in [`../wiki/`](../wiki/README.md) (firmware decompilation record, address reference, historical protocol notes). Wiki |