Difference between revisions of "Glossary"

From Open-IOV
Jump to navigation Jump to search
m (Re-sync page from tracked wiki source: fix cross-document links and diagram; refresh status)
m (Fix repository links: point to the cgit tree URLs)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{About message}}
= Glossary =
= Glossary =


<blockquote>'''Historical document — superseded.''' The authoritative glossary is [https://git.vgpu.io/open-iov/blob/master/docs/09-reference/glossary-and-faq.md <code>../docs/09-reference/glossary-and-faq.md</code>].</blockquote>
<blockquote>'''What this page is.''' The terms used across this wiki, the project's documents and its logs. Condensed from [https://git.vgpu.io/open-iov.git/tree/docs/09-reference/glossary-and-faq.md <code>../docs/09-reference/glossary-and-faq.md</code>]; the docs tree wins on disagreement. For questions, see [[FAQ|<code>FAQ.md</code>]].</blockquote>


== Terms &amp; Abbreviations ==
Status: 2026-10-12, tree <code>master @ 2f066727</code>.


=== General ===
== GPU, driver and virtualization ==


{| class="wikitable"
{| class="wikitable"
|-
|-
! Term
! Term
! Definition
! Meaning
|-
|-
| '''GSP'''
| '''BAR0 / BAR1 / BAR3'''
| GPU System Processor - NVIDIA's on-GPU RISC-V microcontroller
| PCI BAR windows of the GPU: register interface (16 MB), VRAM aperture (256 MB), instance/PRAMIN window.
|-
|-
| '''vGPU'''
| '''CUDASW'''
| Virtual GPU - Partitioned GPU for multi-tenant workloads
| The family of NVIDIA user-space software between applications and the driver: <code>libcuda</code>, <code>libcudart</code>, the JIT compiler, the fatbinary loader, and friends.
|-
|-
| '''VF'''
| '''Doorbell'''
| Virtual Function - Single vGPU instance with dedicated resources
| A register or memory location a driver writes to signal "new work is available" for a channel or queue.
|-
|-
| '''PF'''
| '''mdev'''
| Physical Function - Host GPU managing VFs (SR-IOV)
| Mediated device: the kernel mechanism that turns a physical device into virtual instances (VFIO).
|-
|-
| '''IOV'''
| '''vGPU'''
| I/O Virtualization - SR-IOV implementation
| Virtual GPU: the device this project presents to a guest.
|-
| '''RPC'''
| Remote Procedure Call - GSP-host communication protocol
|-
| '''BAR'''
| Base Address Register - PCIe memory-mapped I/O window
|-
|-
| '''WPR'''
| '''SRIOV / VF'''
| Write-Protected Region - VRAM area reserved for firmware
| Single-root I/O virtualization / virtual functions (hardware partitioning).
|-
|-
| '''SR-IOV'''
| '''IOMMU / SMMU'''
| Single Root I/O Virtualization - PCIe virtualization standard
| Platform DMA translation and isolation (Intel VT-d / AMD-Vi / ARM SMMU).
|}
|}


=== Firmware Architecture ===
== GSP, firmware and the RM ==


{| class="wikitable"
{| class="wikitable"
|-
|-
! Term
! Term
! Definition
! Meaning
|-
|-
| '''RV64IMAC'''
| '''GSP'''
| RISC-V 64-bit ISA with Integer, Multiply, Atomic, Compressed extensions
| GPU System Processor: the embedded RISC-V (RV64IMAC) that runs firmware containing the Resource Manager.
|-
|-
| '''Dispatcher'''
| '''GSP-RM'''
| Central RPC routing function (primary/secondary)
| The Resource Manager running on the GSP (the "self-hosted RM").
|-
|-
| '''Jump Table'''
| '''RM / RM API'''
| Array of function pointers for sub-command dispatch
| NVIDIA's Resource Manager and the API used to allocate objects and issue controls.
|-
|-
| '''Sub-Command'''
| '''RMCore'''
| Specific operation within an RPC type
| The RM's object system: classes, handles, parents, methods.
|-
|-
| '''Descriptor'''
| '''resserv / resource server'''
| Return structure with ID and echoed parameters
| The RM component that owns allocation authority, privileges and lifetimes.
|-
|-
| '''Entry Point'''
| '''FWSEC'''
| Firmware boot address (0x04009000)
| Firmware security processor stage of the GSP boot sequence.
|-
|-
| '''Frame Guard'''
| '''WPR'''
| Stack canary at 0x041DC350
| Write-Protected Region: the VRAM area reserved for firmware.
|}
 
=== Memory Management ===
 
{| class="wikitable"
|-
! Term
! Definition
|-
| '''VRAM'''
| Video RAM - GPU local memory
|-
| '''Sysmem'''
| System Memory - Host DRAM
|-
| '''Page Table'''
| GPU virtual-to-physical mapping tables
|-
| '''Pinning'''
| Locking pages for DMA access
|-
| '''Bounce Buffer'''
| Intermediate buffer for data transfer
|-
| '''Aperture'''
| Mappable BAR window size
|-
| '''Backing Store'''
| Memory backing emulated BAR regions
|}
 
=== RPC Types ===
 
{| class="wikitable"
|-
! RPC
! Name
! Purpose
|-
| 0x01
| '''ALLOC'''
| Allocate GPU memory
|-
| 0x02
| '''FREE'''
| Free GPU memory
|-
| 0x03
| '''MAP'''
| Map memory to VF address space
|-
| 0x04
| '''UNMAP'''
| Unmap memory from VF
|-
| 0x05
| '''PIN'''
| Pin pages for DMA
|-
| 0x06
| '''UNPIN'''
| Unpin pages
|-
| 0x07
| '''SCHEDULE'''
| VF scheduling control
|-
| 0x08
| '''YIELD'''
| Voluntary yield
|-
| 0x09
| '''NOTIFY'''
| Event notification
|-
| 0x0A
| '''BAR_TRAP'''
| BAR access emulation
|-
| 0x0B
| '''MIGRATE'''
| Live VF migration
|-
| 0xFF
| '''DEBUG'''
| Debug interface
|}
 
=== Migration ===
 
{| class="wikitable"
|-
! Term
! Definition
|-
| '''Pre-copy'''
| Iterative page transfer while VF runs
|-
| '''Post-copy'''
| Start VF on destination, fetch pages on demand
|-
| '''Quiesce'''
| Pause VF for consistent state snapshot
|-
|-
| '''Dirty Page'''
| '''MSGQ'''
| Page modified since last transfer
| The GSP message-queue transport: shared-memory element rings with a page table, plus doorbells.
|-
|-
| '''Cutover'''
| '''VGX version'''
| Switch execution from source to destination
| The version the guest announces during RPC negotiation; it selects message layouts.
|-
|-
| '''Token'''
| '''Reply fidelity'''
| Opaque migration context handle
| 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.
|}
|}


=== BAR Emulation ===
== Execution engines and memory ==


{| class="wikitable"
{| class="wikitable"
|-
|-
! Term
! Term
! Definition
! Meaning
|-
| '''BAR1'''
| 256 MB VRAM aperture (the register interface is BAR0, 16 MB; BAR3 is the instance/PRAMIN window)
|-
|-
| '''Bar1Rest'''
| '''CE'''
| BAR1 state restoration
| Copy Engine: a DMA engine; also used for UVM's internal work.
|-
|-
| '''ForceBarAccess'''
| '''GR'''
| Hypervisor bypass of VF permissions
| The graphics/compute engine that executes shaders (graphics pipelines and CUDA kernels).
|-
|-
| '''Aperture'''
| '''SEC2'''
| Configurable BAR window size/offset
| Secure copy engine used by UVM for protected operations.
|}
 
=== WPR (Write-Protected Region) ===
 
{| class="wikitable"
|-
! Term
! Definition
|-
|-
| '''Write Protect'''
| '''GPFIFO'''
| Trap on write access to region
| GPU FIFO: a ring of entries, each pointing to a push buffer for a channel.
|-
|-
| '''Read Protect'''
| '''Push buffer'''
| Trap on read access to region
| A stream of method calls (engine commands) submitted via a GPFIFO.
|-
|-
| '''NV_WPR'''
| '''PBDMA'''
| NVIDIA-specific WPR extensions
| The push-buffer DMA engine in the host scheduler that fetches and executes push buffers.
|-
|-
| '''Completion'''
| '''QMD'''
| Successful trap handling
| Queue Meta Data: the per-launch descriptor a GR channel reads to execute a kernel grid.
|-
|-
| '''Timeout'''
| '''USERD'''
| Trap handling exceeded time limit
| Per-channel control block in VRAM: PUT/GET pointers and control state.
|}
 
=== Hardware Registers ===
 
{| class="wikitable"
|-
|-
! Register
| '''Runlist'''
! Purpose
| The scheduler's list of channels eligible to run.
|-
|-
| '''Doorbell'''
| '''TSG'''
| Host→GSP notification (PCIe BAR0 + 0x1000)
| Time-Slice Group: channels sharing a scheduling slot.
|-
|-
| '''Message Ring'''
| '''Engine record / engine list'''
| Shared memory for RPC messages
| The per-engine descriptors (kind, instance, class, client type) the driver walks after <code>GPU_GET_ENGINES</code>; each must be self-consistent or the driver rewrites the following allocation.
|-
|-
| '''Cache Manager'''
| '''GMMU'''
| 0x429B428 - Flush/invalidate
| GPU Memory Management Unit: page tables, TLB, fault handling.
|-
|-
| '''Allocator Arena'''
| '''PDB'''
| 0x429B450 - Memory allocation
| Page Directory Base: root of a GPU page table.
|-
|-
| '''Global Error Flag'''
| '''PDE / PTE'''
| 0x04296048 - Global error state
| Page-directory entry / page-table entry.
|-
|-
| '''Stack Canary'''
| '''UVM'''
| 0x041DC350 - Frame integrity
| NVIDIA's unified memory module: VA spaces, page trees, faults, channel manager ([[UVM in the Guest|<code>UVM-in-the-Guest.md</code>]]).
|}
 
=== Tools &amp; Scripts ===
 
{| class="wikitable"
|-
|-
! Tool
| '''VA / PA / GPA / IOVA'''
! Purpose
| Virtual address / physical address / guest physical address / I/O virtual address.
|-
|-
| '''analyzeHeadless'''
| '''vidmem / sysmem / aperture'''
| Ghidra headless analyzer
| GPU local memory / system memory / how an address is qualified.
|-
|-
| '''DecompileFunctions.java'''
| '''Semaphore / tracker'''
| Ghidra script for batch decompilation
| A memory location written by the GPU to signal progress; UVM's tracker waits on it.
|-
|-
| '''trace_all_subsystems.py'''
| '''AMAPlib'''
| Binary analysis script
| NVIDIA's shared "address mapping" library: swizzling, bank/channel mapping, aperture rules.
|-
|-
| '''RPC_HANDLER_MAP.md'''
| '''HAL'''
| Complete RPC address map
| Hardware abstraction layer: per-generation functions that program registers and formats.
|-
|-
| '''FINAL_REPORT.md'''
| '''Class list (classDB)'''
| Full analysis report
| The RM classes reported as supported; engine queries are filtered against it, so the class list, engine list and capability controls must agree.
|}
|}


=== Debugging ===
== Method and tooling ==


{| class="wikitable"
{| class="wikitable"
|-
|-
! Term
! Term
! Definition
! Meaning
|-
| '''ebreak'''
| RISC-V breakpoint instruction (fatal in FW)
|-
| '''String Ref'''
| Cross-reference to string literal
|-
| '''XRef'''
| Cross-reference (code/data)
|-
| '''Pcode'''
| Ghidra's intermediate representation
|-
| '''VBIOS'''
| Video BIOS - firmware for GPU initialization
|}
 
=== Calling Convention (RISC-V) ===
 
{| class="wikitable"
|-
! Register
! ABI Name
! Purpose
|-
| x0
| zero
| Hardwired zero
|-
| x1
| ra
| Return address
|-
| x2
| sp
| Stack pointer
|-
| x3
| gp
| Global pointer
|-
| x4
| tp
| Thread pointer
|-
| x5-7
| t0-t2
| Temporaries
|-
| x8
| s0/fp
| Frame pointer
|-
| x9
| s1
| Callee-saved (RA save)
|-
| x10-11
| a0-a1
| Arguments/returns
|-
| x12
| s4
| Callee-saved (RA save)
|-
| x13-17
| a2-a6
| Arguments
|-
| x18-27
| s2-s11
| Callee-saved
|-
| x28-31
| t3-t6
| Temporaries
|}
 
=== Firmware Sections (ELF) ===
 
{| class="wikitable"
|-
! Section
! Purpose
|-
| <code>.text</code>
| Executable code
|-
| <code>.rodata</code>
| Read-only data
|-
| <code>.data</code>
| Initialized data
|-
| <code>.bss</code>
| Zero-initialized data
|-
| <code>.section_task_rm_*</code>
| Task-specific sections
|}
 
=== Migration Phases ===
 
{| class="wikitable"
|-
! Phase
! Description
|-
| '''QUERY'''
| Check migratability
|-
| '''PREPARE'''
| Quiesce, snapshot
|-
|-
| '''TRANSFER'''
| '''Host oracle / A-B harness'''
| Iterative page copy
| The same query or deterministic workload run against a bare-metal host driver and inside the guest, then diffed — the reference for what the guest should have seen.
|-
|-
| '''COMMIT'''
| '''File virtual address (<code>libcuda+0x...</code>)'''
| Final sync, cutover
| An address relative to the start of a shared object file, as distinct from a runtime mapping or a disassembler program address.
|-
|-
| '''CLEANUP'''
| '''Session (risc-v-gsp-rm-debugger)'''
| Release resources
| A recorded run of the firmware workbench — the unit of evidence ([[risc-v-gsp-rm-debugger|<code>Riscv-GSP-RM-Debugger.md</code>]]).
|}
|}


== File Naming Conventions ==
== Related pages ==
 
=== Decompiled Output ===
 
<pre>FUN_ram_&lt;ADDRESS&gt;_ram_&lt;ADDRESS&gt;.c</pre>
 
* <code>FUN_ram_057A1AC0_ram_057A1AC0.c</code> = Function at 0x057A1AC0
 
=== Ghidra Projects ===
 
<pre>gsp-&lt;purpose&gt;/</pre>
 
* <code>gsp-subcmds</code>, <code>gsp-rpc-handlers</code>, <code>gsp-bar-fns</code>, etc.
 
== References ==


* RISC-V ISA: https://riscv.org/technical/specifications/
* [[FAQ|<code>FAQ.md</code>]]
* SR-IOV Spec: https://pcisig.com/specifications/iov/
* [[System Overview|<code>System-Overview.md</code>]]
* Ghidra: https://ghidra-sre.org/
* [[GSP and GSP-RM|<code>GSP-and-GSP-RM.md</code>]]
* [[Introduction to GMMU|<code>Introduction-to-GMMU.md</code>]]

Latest revision as of 04:41, 12 October 2026

An absence of critical technical documentation has historically slowed growth and adoption of developer ecosystems for GPU virtualization.

This CC-BY-4.0 licensed content can either be used with attribution, or used as inspiration for new documentation, created by GPU vendors for public commercial distribution as developer documentation.

Where possible, this documentation will clearly label dates and versions of observed-but-not-guaranteed behaviour vs. vendor-documented stable interfaces/behaviour with guarantees of forward or backward compatibility.

Glossary

What this page is. The terms used across this wiki, the project's documents and its logs. Condensed from ../docs/09-reference/glossary-and-faq.md; the docs tree wins on disagreement. For questions, see FAQ.md.

Status: 2026-10-12, tree master @ 2f066727.

GPU, driver and virtualization

Term Meaning
BAR0 / BAR1 / BAR3 PCI BAR windows of the GPU: register interface (16 MB), VRAM aperture (256 MB), instance/PRAMIN window.
CUDASW The family of NVIDIA user-space software between applications and the driver: libcuda, libcudart, the JIT compiler, the fatbinary loader, and friends.
Doorbell A register or memory location a driver writes to signal "new work is available" for a channel or queue.
mdev Mediated device: the kernel mechanism that turns a physical device into virtual instances (VFIO).
vGPU Virtual GPU: the device this project presents to a guest.
SRIOV / VF Single-root I/O virtualization / virtual functions (hardware partitioning).
IOMMU / SMMU Platform DMA translation and isolation (Intel VT-d / AMD-Vi / ARM SMMU).

GSP, firmware and the RM

Term Meaning
GSP GPU System Processor: the embedded RISC-V (RV64IMAC) that runs firmware containing the Resource Manager.
GSP-RM The Resource Manager running on the GSP (the "self-hosted RM").
RM / RM API NVIDIA's Resource Manager and the API used to allocate objects and issue controls.
RMCore The RM's object system: classes, handles, parents, methods.
resserv / resource server The RM component that owns allocation authority, privileges and lifetimes.
FWSEC Firmware security processor stage of the GSP boot sequence.
WPR Write-Protected Region: the VRAM area reserved for firmware.
MSGQ The GSP message-queue transport: shared-memory element rings with a page table, plus doorbells.
VGX version The version the guest announces during RPC negotiation; it selects message layouts.
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.

Execution engines and memory

Term Meaning
CE Copy Engine: a DMA engine; also used for UVM's internal work.
GR The graphics/compute engine that executes shaders (graphics pipelines and CUDA kernels).
SEC2 Secure copy engine used by UVM for protected operations.
GPFIFO GPU FIFO: a ring of entries, each pointing to a push buffer for a channel.
Push buffer A stream of method calls (engine commands) submitted via a GPFIFO.
PBDMA The push-buffer DMA engine in the host scheduler that fetches and executes push buffers.
QMD Queue Meta Data: the per-launch descriptor a GR channel reads to execute a kernel grid.
USERD Per-channel control block in VRAM: PUT/GET pointers and control state.
Runlist The scheduler's list of channels eligible to run.
TSG Time-Slice Group: channels sharing a scheduling slot.
Engine record / engine list The per-engine descriptors (kind, instance, class, client type) the driver walks after GPU_GET_ENGINES; each must be self-consistent or the driver rewrites the following allocation.
GMMU GPU Memory Management Unit: page tables, TLB, fault handling.
PDB Page Directory Base: root of a GPU page table.
PDE / PTE Page-directory entry / page-table entry.
UVM NVIDIA's unified memory module: VA spaces, page trees, faults, channel manager (UVM-in-the-Guest.md).
VA / PA / GPA / IOVA Virtual address / physical address / guest physical address / I/O virtual address.
vidmem / sysmem / aperture GPU local memory / system memory / how an address is qualified.
Semaphore / tracker A memory location written by the GPU to signal progress; UVM's tracker waits on it.
AMAPlib NVIDIA's shared "address mapping" library: swizzling, bank/channel mapping, aperture rules.
HAL Hardware abstraction layer: per-generation functions that program registers and formats.
Class list (classDB) The RM classes reported as supported; engine queries are filtered against it, so the class list, engine list and capability controls must agree.

Method and tooling

Term Meaning
Host oracle / A-B harness The same query or deterministic workload run against a bare-metal host driver and inside the guest, then diffed — the reference for what the guest should have seen.
File virtual address (libcuda+0x...) An address relative to the start of a shared object file, as distinct from a runtime mapping or a disassembler program address.
Session (risc-v-gsp-rm-debugger) A recorded run of the firmware workbench — the unit of evidence (Riscv-GSP-RM-Debugger.md).

Related pages

Retrieved from "https://open-iov.org/index.php?title=Glossary&oldid=23988"