Struct VgpuInstance 

pub struct VgpuInstance(/* private fields */);

Implementations

impl VgpuInstance

pub const fn from_id(id: VgpuInstanceId) -> Self

pub const fn id(self) -> VgpuInstanceId

pub fn vgpu_type(self) -> Result<VgpuTypeId>

Returns the vGPU type of a vGPU instance.

Returns the vGPU type ID assigned to the vGPU instance.

For Kepler or newer fully supported devices.

Errors

Returns an error if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn placement_id(self) -> Result<VgpuPlacementId>

Query the placement ID of active vGPU instance.

When vGPU heterogeneous mode is enabled, returns the placement ID for the vGPU instance.

Errors

Returns an error if NVML rejects the versioned request, if the vGPU instance or query arguments are invalid, if the handle does not match an active vGPU instance, or if NVML reports an unexpected failure.

pub fn accounting_mode(self) -> Result<EnableState>

Queries the state of per process accounting mode on vGPU.

For Maxwell or newer fully supported devices.

Errors

Returns an error if the guest driver is not running, if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, if the vGPU does not support accounting, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn accounting_pids(self) -> Result<Vec<Pid>>

Returns processes running on this vGPU instance that have accounting stats. Returned processes can be running or terminated.

For Maxwell or newer fully supported devices.

This wrapper queries the required process count internally. It returns an empty list when no processes are available.

See VgpuInstance::accounting_stats for the per-process metrics.

With a PID collision, some processes may not be accessible before the circular buffer is full.

Errors

Returns an error if the internal PID buffer is too small, if NVML rejects the handle or process-count output, if the handle does not match an active vGPU instance, if the vGPU does not support accounting or accounting is disabled, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn accounting_stats(self, pid: Pid) -> Result<AccountingStats>

Queries process’s accounting stats.

For Maxwell or newer fully supported devices.

Accounting stats capture GPU utilization and other statistics across the lifetime of a process. Stats can be queried while the process is running and after it terminates. The reported running time remains 0 while the process is still running and is updated to the actual duration after termination. Accounting stats are kept in a circular buffer, newly created processes overwrite information about old processes.

The returned value includes the per-process accounting metrics exposed by NVML. Use VgpuInstance::accounting_pids to list processes with available stats.

• Accounting mode must be enabled. See VgpuInstance::accounting_mode.
• Only compute and graphics application stats can be queried. Monitoring application stats cannot be queried because they do not contribute to GPU utilization.
• With a PID collision, only stats for the latest process to terminate are reported.

Errors

Returns an error if NVML rejects the handle or stats output, if the handle does not match an active vGPU instance or stats are unavailable, if the vGPU does not support accounting or accounting is disabled, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn uuid(self) -> Result<String>

Returns the UUID of a vGPU instance.

The UUID is a globally unique identifier associated with the vGPU. It is returned as a five-part hexadecimal string that does not exceed 80 characters including the terminating NUL byte. This wrapper allocates the required NVML buffer internally.

For Kepler or newer fully supported devices.

Errors

Returns an error if the UUID buffer is too small, if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn vm_id(self) -> Result<VgpuVmId>

Returns the VM ID associated with a vGPU instance.

The VM ID is returned as a string that does not exceed 80 characters including the terminating NUL byte. This wrapper allocates the required NVML buffer internally.

The VM ID type identifies the platform-specific format of the returned string.

For Kepler or newer fully supported devices.

Errors

Returns an error if the VM ID buffer is too small, if NVML rejects the handle, VM ID, or VM ID type output, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn vm_driver_version(self) -> Result<String>

Returns the NVIDIA driver version installed in the VM associated with a vGPU.

The version is returned as an alphanumeric string. The version string does not exceed 80 bytes including the terminating NUL byte. This wrapper allocates the required NVML buffer internally.

VgpuInstance::vm_driver_version may be called at any time for a vGPU instance. The guest VM driver version is returned as Not Available if no NVIDIA driver is installed in the VM, or if the VM has not yet loaded and initialized the NVIDIA driver.

For Kepler or newer fully supported devices.

Errors

Returns an error if the internal driver-version buffer is too small, if NVML rejects the handle, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn mdev_uuid(self) -> Result<String>

Returns the MDEV UUID of a vGPU instance.

The MDEV UUID is a globally unique identifier of the mdev device assigned to the VM. It is returned as a five-part hexadecimal string that does not exceed 80 characters including the terminating NUL byte. The MDEV UUID is displayed only on KVM. This wrapper allocates the required NVML buffer internally.

For Maxwell or newer fully supported devices.

Errors

Returns an error if the mediated-device UUID buffer is too small, if NVML rejects the handle or UUID output, if the handle does not match an active vGPU instance, if the hypervisor is not KVM, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn framebuffer_usage(self) -> Result<u64>

Returns the framebuffer usage in bytes.

Framebuffer usage is the amount of vGPU framebuffer memory that is currently in use by the VM.

For Kepler or newer fully supported devices.

Errors

Returns an error if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn license_status(self) -> Result<bool>

pub fn license_info(self) -> Result<VgpuLicenseInfo>

Query the license information of the vGPU instance.

For Maxwell or newer fully supported devices.

Errors

Returns an error if the guest driver is not running, if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, or if NVML reports an unexpected failure.

pub fn frame_rate_limit(self) -> Result<u32>

Returns the frame rate limit set for the vGPU instance.

Returns the value of the frame-rate limit set for the vGPU instance.

For Kepler or newer fully supported devices.

Errors

Returns an error if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, if the frame-rate limiter is disabled for this vGPU type, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn ecc_mode(self) -> Result<EnableState>

Returns the current ECC mode of a vGPU instance.

Errors

Returns an error if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, if the vGPU does not support ECC mode, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn encoder_capacity(self) -> Result<u32>

Returns the encoder capacity of a vGPU instance, as a percentage of maximum encoder capacity with valid values in the range 0-100.

For Maxwell or newer fully supported devices.

Errors

Returns an error if NVML rejects the handle or encoder query, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn encoder_stats(self) -> Result<EncoderStats>

Returns the current encoder statistics of a vGPU instance.

For Maxwell or newer fully supported devices.

Errors

Returns an error if NVML rejects the handle or query arguments, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn encoder_sessions(self) -> Result<Vec<EncoderSessionInfo>>

Returns information about all active encoder sessions on a vGPU instance.

This wrapper queries the required session count first, then returns the active encoder sessions as a Vec.

For Maxwell or newer fully supported devices.

Errors

Returns an error if the internal session buffer is too small, if NVML rejects the handle or reports an invalid session count, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn fbc_stats(self) -> Result<FbcStats>

Returns the active frame buffer capture sessions statistics of a vGPU instance.

For Maxwell or newer fully supported devices.

Errors

Returns an error if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn fbc_sessions(self) -> Result<Vec<FbcSessionInfo>>

Returns information about active frame buffer capture sessions on a vGPU instance.

This wrapper queries the required session count first, then returns the active FBC sessions as a Vec.

For Maxwell or newer fully supported devices.

h_resolution, v_resolution, average_fps, and average_latency may be zero if no new frames were captured since the session started.

Errors

Returns an error if the internal session buffer is too small, if NVML rejects the handle or reports an invalid session count, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn gpu_instance_id(self) -> Result<u32>

Returns the GPU instance ID for the given vGPU instance. Returns a valid GPU instance ID for MIG-backed vGPU instances; otherwise returns INVALID_GPU_INSTANCE_ID.

For Kepler or newer fully supported devices.

Errors

Returns an error if NVML rejects the handle or query arguments, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn gpu_pci_id(self) -> Result<String>

Returns the PCI ID of the given vGPU instance, that is, the PCI ID of the GPU as seen inside the VM.

The vGPU PCI ID is returned as 00000000:00:00.0 if the NVIDIA driver is not installed on the vGPU instance.

Errors

Returns an error if the guest driver is not running, if the internal PCI ID buffer is too small, if NVML rejects the handle or output argument, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn runtime_state(self) -> Result<VgpuRuntimeState>

Returns the currently used runtime state size of the vGPU instance.

This size represents the maximum in-memory data size used by a vGPU instance during standard operation. This measurement is exclusive of frame buffer (FB) data size assigned to the vGPU instance.

For Maxwell or newer fully supported devices.

Errors

Returns an error if NVML rejects the versioned request, if the vGPU instance or query arguments are invalid, if the handle does not match an active vGPU instance, if NVML has not been initialized, or if NVML reports an unexpected failure.

pub fn metadata(self) -> Result<VgpuMetadata>

Returns vGPU metadata structure for a running vGPU. The structure contains information about the vGPU and its associated VM such as the currently installed NVIDIA guest driver version, together with host driver version and an opaque data section containing internal state.

VgpuInstance::metadata may be called at any time for a vGPU instance. Some fields in the returned structure are dependent on information obtained from the guest VM, which may not yet have reached a state where that information is available. The current state of these dependent fields is reflected in the info structure’s VgpuGuestInfoState field.

The VMM may choose to read and save the vGPU’s VM info as persistent metadata associated with the VM, and provide it to Virtual GPU Manager when creating a vGPU for subsequent instances of the VM.

This wrapper allocates the metadata buffer internally and retries if NVML reports it is too small.

Errors

Returns an error if the internal metadata buffer is too small after retrying, if NVML rejects the handle or metadata arguments, if the handle does not match an active vGPU instance, or if NVML reports an unexpected failure.

pub fn compatibility_with( self, library: &Library, pgpu_metadata: &PgpuMetadata, ) -> Result<VgpuCompatibility>

Trait Implementations

impl Clone for VgpuInstance

fn clone(&self) -> VgpuInstance

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VgpuInstance

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for VgpuInstance

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for VgpuInstance

fn eq(&self, other: &VgpuInstance) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for VgpuInstance

impl Eq for VgpuInstance

impl StructuralPartialEq for VgpuInstance