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 (Add page from tracked wiki source (2026 IA update))
Line 1: Line 1:
= 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/blob/master/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'''
| '''SRIOV / VF'''
| Remote Procedure Call - GSP-host communication protocol
| Single-root I/O virtualization / virtual functions (hardware partitioning).
|-
| '''BAR'''
| Base Address Register - PCIe memory-mapped I/O window
|-
| '''WPR'''
| Write-Protected Region - VRAM area reserved for firmware
|-
|-
| '''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
| '''MSGQ'''
| '''BAR_TRAP'''
| The GSP message-queue transport: shared-memory element rings with a page table, plus doorbells.
| BAR access emulation
|-
|-
| 0x0B
| '''VGX version'''
| '''MIGRATE'''
| The version the guest announces during RPC negotiation; it selects message layouts.
| Live VF migration
|-
|-
| 0xFF
| '''Reply fidelity'''
| '''DEBUG'''
| 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.
| Debug interface
|}
|}


=== Migration ===
== Execution engines and memory ==


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


=== Tools &amp; Scripts ===
== Method and tooling ==
 
{| class="wikitable"
|-
! Tool
! Purpose
|-
| '''analyzeHeadless'''
| Ghidra headless analyzer
|-
| '''DecompileFunctions.java'''
| Ghidra script for batch decompilation
|-
| '''trace_all_subsystems.py'''
| Binary analysis script
|-
| '''RPC_HANDLER_MAP.md'''
| Complete RPC address map
|-
| '''FINAL_REPORT.md'''
| Full analysis report
|}
 
=== Debugging ===


{| 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
| '''Host oracle / A-B harness'''
| s0/fp
| 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.
| Frame pointer
|-
|-
| x9
| '''File virtual address (<code>libcuda+0x...</code>)'''
| s1
| An address relative to the start of a shared object file, as distinct from a runtime mapping or a disassembler program address.
| Callee-saved (RA save)
|-
|-
| x10-11
| '''Session (risc-v-gsp-rm-debugger)'''
| a0-a1
| A recorded run of the firmware workbench — the unit of evidence ([[risc-v-gsp-rm-debugger|<code>Riscv-GSP-RM-Debugger.md</code>]]).
| 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) ===
== Related pages ==
 
{| 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'''
| Iterative page copy
|-
| '''COMMIT'''
| Final sync, cutover
|-
| '''CLEANUP'''
| Release resources
|}
 
== File Naming Conventions ==
 
=== 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>]]

Revision as of 04:22, 12 October 2026

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=23871"