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)
Line 1: Line 1:
<blockquote>An absence of critical technical documentation has historically slowed growth and adoption of developer ecosystems for GPU virtualization.
= Glossary =


This [https://creativecommons.org/licenses/by/4.0/ 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.
<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>


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.</blockquote>
== Terms &amp; Abbreviations ==


== Definitions ==
=== General ===
This article will attempt to provide a glossary of common terms that are either related to/or often used in connection with virtualization for those who may need more context.


If you have suggestions on how to improve the glossary you can [https://openmdev.io/index.php/Main_Page#Getting_Started_Contributing_to_OpenMdev.io '''contribute'''] or join our [https://discord.gg/Rb9K9DYxKK '''community discussion thread'''] to make suggestions.
{| class="wikitable"
|-
! Term
! Definition
|-
| '''GSP'''
| GPU System Processor - NVIDIA's on-GPU RISC-V microcontroller
|-
| '''vGPU'''
| Virtual GPU - Partitioned GPU for multi-tenant workloads
|-
| '''VF'''
| Virtual Function - Single vGPU instance with dedicated resources
|-
| '''PF'''
| Physical Function - Host GPU managing VFs (SR-IOV)
|-
| '''IOV'''
| I/O Virtualization - SR-IOV implementation
|-
| '''RPC'''
| Remote Procedure Call - GSP-host communication protocol
|-
| '''BAR'''
| Base Address Register - PCIe memory-mapped I/O window
|-
| '''WPR'''
| Write-Protected Region - VRAM area reserved for firmware
|-
| '''SR-IOV'''
| Single Root I/O Virtualization - PCIe virtualization standard
|}


=== VFIO ===
=== Firmware Architecture ===
<blockquote>Kernel.org defines VFIO or Virtual Function Input Output as '''"an IOMMU/device agnostic framework for exposing direct device access to userspace, in a secure, IOMMU protected environment." [https://www.kernel.org/doc/Documentation/vfio.txt <nowiki>[1]</nowiki>]'''</blockquote>
[[File:VFIO Diagram.png|thumb|A diagram depicting direct VFIO passthrough of a GPU adapter.]]


=== Mdev ===
{| class="wikitable"
<blockquote>Kernel.org defines Virtual Function I/O (VFIO) Mediated devices as: '''"an IOMMU/device-agnostic framework for exposing direct device access to user space in a secure, IOMMU-protected environment... mediated core driver provides a common interface for mediated device management that can be used by drivers of different devices." [https://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git/tree/Documentation/driver-api/vfio-mediated-device.rst?h=driver-core-next&id=7de3697e9cbd4bd3d62bafa249d57990e1b8f294 <nowiki>[2]</nowiki>]'''</blockquote>
|-
[[File:VFIO-Mdev Diagram.png|thumb|A diagram depicting VFIO Mediated Device interacting with two vGPU guests.]]
! Term
! Definition
|-
| '''RV64IMAC'''
| RISC-V 64-bit ISA with Integer, Multiply, Atomic, Compressed extensions
|-
| '''Dispatcher'''
| Central RPC routing function (primary/secondary)
|-
| '''Jump Table'''
| Array of function pointers for sub-command dispatch
|-
| '''Sub-Command'''
| Specific operation within an RPC type
|-
| '''Descriptor'''
| Return structure with ID and echoed parameters
|-
| '''Entry Point'''
| Firmware boot address (0x04009000)
|-
| '''Frame Guard'''
| Stack canary at 0x041DC350
|}


=== Virtual CPU (vCPU) ===
=== Memory Management ===
<blockquote>A Virtual CPU (vCPU) is a CPU which has been virtualized to represent a percentage of the total hardware resource via preemptive scheduling.</blockquote>


=== Virtual GPU (vGPU) ===
{| class="wikitable"
<blockquote>A Virtual GPU (vGPU) is a GPU which has been virtualized to represent a percentage of the total hardware resource via preemptive scheduling or thread pinning (to [https://www.intel.com/content/www/us/en/docs/oneapi/optimization-guide-gpu/2023-0/intel-iris-xe-gpu-architecture.html EUs], or [https://www.nvidia.com/content/PDF/nvidia-ampere-ga-102-gpu-architecture-whitepaper-v2.pdf SMs]) and/or a partition of the device's Video Random Access Memory (VRAM).</blockquote>
|-
=== IVSHMEM ===
! Term
<blockquote>According to QEMU's GitHub repo: '''"The Inter-VM shared memory device (ivshmem) is designed to share a memory region between multiple QEMU processes running different guests and the host.  In order for all guests to be able to pick up the shared memory area, it is modeled by QEMU as a PCI device exposing said memory to the guest as a PCI BAR."''' '''[https://github.com/qemu/qemu/blob/master/docs/specs/ivshmem-spec.txt <nowiki>[3]</nowiki>]'''</blockquote>
! Definition
[[File:IVSHMEM.png|thumb|A diagram depicting an inter-vm shared memory device being used by two separate virtual machines.]]
|-
| '''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
|}


=== KVMFR (Looking Glass) ===
=== RPC Types ===
<blockquote>looking-glass.io defines Looking Glass as: '''"an open source application that allows the use of a KVM (Kernel-based Virtual Machine) configured for VGA PCI Pass-through without an attached physical monitor, keyboard or mouse."''' '''[https://looking-glass.io/ <nowiki>[4]</nowiki>]'''</blockquote>
[[File:KVMFR Looking Glass.png|thumb|A image posted by Gnif (Creator of the Looking Glass project) to a changelog thread on the Level1techs forum - an active community of VFIO users. ]]


=== NUMA Node ===
{| class="wikitable"
<blockquote>Infogalactic defines NUMA as: '''"''Non-uniform memory access (NUMA) is a'' computer memory design used in multiprocessing, where the memory access time depends on the memory location relative to the processor. Under NUMA, a processor can access its own local memory faster than non-local memory (memory local to another processor or memory shared between processors)." [https://infogalactic.com/info/Non-uniform_memory_access <nowiki>[5]</nowiki>]'''</blockquote>
|-
[[File:NUMA Node.png|thumb|A diagram depicting Non-Uniform Memory Access (NUMA) nodes.]]
! 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
|}


=== Application Binary Interface (ABI) ===
=== Migration ===
<blockquote>Infogalactic defines an ABI as '''"the interface between two program modules, one of which is often a library or operating system, at the level of machine code."''' '''[https://infogalactic.com/info/Application_binary_interface <nowiki>[6]</nowiki>]'''</blockquote>
[[File:Application Binary Interface (ABI).png|thumb|A diagram contrasting API and ABI as well as their respective roles in software compatibility.]]


=== SR-IOV ===
{| class="wikitable"
<blockquote>docs.microsoft.com defines SR-IOV as '''"The single root I/O virtualization (SR-IOV) interface is an extension to the PCI Express (PCIe) specification. SR-IOV allows a device, such as a network adapter, to separate access to its resources among various PCIe hardware functions." [https://archive.is/FcDoK <nowiki>[7]</nowiki>]'''</blockquote>
|-
[[File:SR-IOV.png|thumb|A diagram depicting host and guest interactions in a Single Root I/O Virtualization environment.]]
! 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'''
| Page modified since last transfer
|-
| '''Cutover'''
| Switch execution from source to destination
|-
| '''Token'''
| Opaque migration context handle
|}


=== GVT-g ===
=== BAR Emulation ===
<blockquote>wiki.archlinux.org defines Intel GVT-g as '''"a technology that provides mediated device passthrough for Intel GPUs (Broadwell and newer). It can be used to virtualize the GPU for multiple guest virtual machines, effectively providing near-native graphics performance in the virtual machine and still letting your host use the virtualized GPU normally." [https://wiki.archlinux.org/title/Intel_GVT-g <nowiki>[8]</nowiki>]'''</blockquote>
[[File:SR-IOV-Diagram.png|thumb|A diagram of Intel's GVT-g (Graphics Virtualization Technology g).]]


=== VirGL ===
{| class="wikitable"
<blockquote>[[File:Virgl.png|thumb|A diagram depicting GPU instruction redirects to a single host graphics driver.]]lwn.net defines Virgl as: '''"a way for guests running in a virtual machine (VM) to access the host GPU using OpenGL and other APIs... The virgl stack consists of an application running in the guest that sends OpenGL to the Mesa virgl driver, which uses the virtio-gpu driver in the guest kernel to communicate with QEMU on the host."''' '''[https://lwn.net/Articles/767970/ <nowiki>[9]</nowiki>]'''</blockquote>
|-
! Term
! Definition
|-
| '''BAR1'''
| 256 MB VRAM aperture (the register interface is BAR0, 16 MB; BAR3 is the instance/PRAMIN window)
|-
| '''Bar1Rest'''
| BAR1 state restoration
|-
| '''ForceBarAccess'''
| Hypervisor bypass of VF permissions
|-
| '''Aperture'''
| Configurable BAR window size/offset
|}
 
=== WPR (Write-Protected Region) ===
 
{| class="wikitable"
|-
! Term
! Definition
|-
| '''Write Protect'''
| Trap on write access to region
|-
| '''Read Protect'''
| Trap on read access to region
|-
| '''NV_WPR'''
| NVIDIA-specific WPR extensions
|-
| '''Completion'''
| Successful trap handling
|-
| '''Timeout'''
| Trap handling exceeded time limit
|}
 
=== Hardware Registers ===
 
{| class="wikitable"
|-
! Register
! Purpose
|-
| '''Doorbell'''
| Host→GSP notification (PCIe BAR0 + 0x1000)
|-
| '''Message Ring'''
| Shared memory for RPC messages
|-
| '''Cache Manager'''
| 0x429B428 - Flush/invalidate
|-
| '''Allocator Arena'''
| 0x429B450 - Memory allocation
|-
| '''Global Error Flag'''
| 0x04296048 - Global error state
|-
| '''Stack Canary'''
| 0x041DC350 - Frame integrity
|}
 
=== Tools &amp; Scripts ===
 
{| 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"
|-
! Term
! Definition
|-
| '''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'''
| 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/
* SR-IOV Spec: https://pcisig.com/specifications/iov/
* Ghidra: https://ghidra-sre.org/

Revision as of 04:10, 12 October 2026

Glossary

Historical document — superseded. The authoritative glossary is ../docs/09-reference/glossary-and-faq.md.

Terms & Abbreviations

General

Term Definition
GSP GPU System Processor - NVIDIA's on-GPU RISC-V microcontroller
vGPU Virtual GPU - Partitioned GPU for multi-tenant workloads
VF Virtual Function - Single vGPU instance with dedicated resources
PF Physical Function - Host GPU managing VFs (SR-IOV)
IOV I/O Virtualization - SR-IOV implementation
RPC Remote Procedure Call - GSP-host communication protocol
BAR Base Address Register - PCIe memory-mapped I/O window
WPR Write-Protected Region - VRAM area reserved for firmware
SR-IOV Single Root I/O Virtualization - PCIe virtualization standard

Firmware Architecture

Term Definition
RV64IMAC RISC-V 64-bit ISA with Integer, Multiply, Atomic, Compressed extensions
Dispatcher Central RPC routing function (primary/secondary)
Jump Table Array of function pointers for sub-command dispatch
Sub-Command Specific operation within an RPC type
Descriptor Return structure with ID and echoed parameters
Entry Point Firmware boot address (0x04009000)
Frame Guard Stack canary at 0x041DC350

Memory Management

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

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

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 Page modified since last transfer
Cutover Switch execution from source to destination
Token Opaque migration context handle

BAR Emulation

Term Definition
BAR1 256 MB VRAM aperture (the register interface is BAR0, 16 MB; BAR3 is the instance/PRAMIN window)
Bar1Rest BAR1 state restoration
ForceBarAccess Hypervisor bypass of VF permissions
Aperture Configurable BAR window size/offset

WPR (Write-Protected Region)

Term Definition
Write Protect Trap on write access to region
Read Protect Trap on read access to region
NV_WPR NVIDIA-specific WPR extensions
Completion Successful trap handling
Timeout Trap handling exceeded time limit

Hardware Registers

Register Purpose
Doorbell Host→GSP notification (PCIe BAR0 + 0x1000)
Message Ring Shared memory for RPC messages
Cache Manager 0x429B428 - Flush/invalidate
Allocator Arena 0x429B450 - Memory allocation
Global Error Flag 0x04296048 - Global error state
Stack Canary 0x041DC350 - Frame integrity

Tools & Scripts

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

Term Definition
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)

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)

Section Purpose
.text Executable code
.rodata Read-only data
.data Initialized data
.bss Zero-initialized data
.section_task_rm_* Task-specific sections

Migration Phases

Phase Description
QUERY Check migratability
PREPARE Quiesce, snapshot
TRANSFER Iterative page copy
COMMIT Final sync, cutover
CLEANUP Release resources

File Naming Conventions

Decompiled Output

FUN_ram_<ADDRESS>_ram_<ADDRESS>.c
  • FUN_ram_057A1AC0_ram_057A1AC0.c = Function at 0x057A1AC0

Ghidra Projects

gsp-<purpose>/
  • gsp-subcmds, gsp-rpc-handlers, gsp-bar-fns, etc.

References

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