Struct nvml_wrapper::device::Device

pub struct Device<'nvml> { /* private fields */ }

Struct that represents a device on the system.

Obtain a Device with the various methods available to you on the Nvml struct.

Lifetimes are used to enforce that each Device instance cannot be used after the Nvml instance it was obtained from is dropped:

use nvml_wrapper::Nvml;

let nvml = Nvml::init()?;
let device = nvml.device_by_index(0)?;

drop(nvml);

// This won't compile
device.fan_speed(0)?;

This means you shouldn’t have to worry about calls to Device methods returning Uninitialized errors.

Implementations

impl<'nvml> Device<'nvml>

pub unsafe fn new(device: nvmlDevice_t, nvml: &'nvml Nvml) -> Self

Create a new Device wrapper.

You will most likely never need to call this; see the methods available to you on the Nvml struct to get one.

Safety

It is your responsibility to ensure that the given nvmlDevice_t pointer is valid.

pub fn nvml(&self) -> &'nvml Nvml

Access the Nvml reference this struct wraps

pub unsafe fn handle(&self) -> nvmlDevice_t

Get the raw device handle contained in this struct

Sometimes necessary for C interop.

Safety

This is unsafe to prevent it from being used without care.

pub fn is_api_restricted(&self, api: Api) -> Result<bool, NvmlError>

Gets the root/admin permissions for the target API.

Only root users are able to call functions belonging to restricted APIs. See the documentation for the RestrictedApi enum for a list of those functions.

Non-root users can be granted access to these APIs through use of .set_api_restricted().

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or the apiType is invalid (may occur if the C lib changes dramatically?)
• NotSupported, if this query is not supported by this Device or this Device does not support the feature that is being queried (e.g. enabling/disabling auto boosted clocks is not supported by this Device).
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

Device Support

Supports all fully supported products.

pub fn applications_clock(&self, clock_type: Clock) -> Result<u32, NvmlError>

Gets the current clock setting that all applications will use unless an overspec situation occurs.

This setting can be changed using .set_applications_clocks().

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or the clockType is invalid (may occur if the C lib changes dramatically?)
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn auto_boosted_clocks_enabled( &self ) -> Result<AutoBoostClocksEnabledInfo, NvmlError>

Gets the current and default state of auto boosted clocks.

Auto boosted clocks are enabled by default on some hardware, allowing the GPU to run as fast as thermals will allow it to.

On Pascal and newer hardware, auto boosted clocks are controlled through application clocks. Use .set_applications_clocks() and .reset_applications_clocks() to control auto boost behavior.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support auto boosted clocks
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn bar1_memory_info(&self) -> Result<BAR1MemoryInfo, NvmlError>

Gets the total, available and used size of BAR1 memory.

BAR1 memory is used to map the FB (device memory) so that it can be directly accessed by the CPU or by 3rd party devices (peer-to-peer on the PCIe bus).

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this query
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn board_id(&self) -> Result<u32, NvmlError>

Gets the board ID for this Device, from 0-N.

Devices with the same boardID indicate GPUs connected to the same PLX. Use in conjunction with .is_multi_gpu_board() to determine if they are on the same board as well.

The boardID returned is a unique ID for the current config. Uniqueness and ordering across reboots and system configs is not guaranteed (i.e if a Tesla K40c returns 0x100 and the two GPUs on a Tesla K10 in the same system return 0x200, it is not guaranteed that they will always return those values. They will, however, always be different from each other).

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi or newer fully supported devices.

pub fn brand(&self) -> Result<Brand, NvmlError>

Gets the brand of this Device.

See the Brand enum for documentation of possible values.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, check that error’s docs for more info
• Unknown, on any unexpected error

pub fn bridge_chip_info(&self) -> Result<BridgeChipHierarchy, NvmlError>

Gets bridge chip information for all bridge chips on the board.

Only applicable to multi-GPU devices.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

Device Support

Supports all fully supported devices.

pub fn clock( &self, clock_type: Clock, clock_id: ClockId ) -> Result<u32, NvmlError>

Gets this Device’s current clock speed for the given Clock type and ClockId.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or clock_type is invalid (shouldn’t occur?)
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn max_customer_boost_clock( &self, clock_type: Clock ) -> Result<u32, NvmlError>

Gets this Device’s customer-defined maximum boost clock speed for the given Clock type.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or clock_type is invalid (shouldn’t occur?)
• NotSupported, if this Device or the clock_type on this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Pascal and newer fully supported devices.

pub fn compute_mode(&self) -> Result<ComputeMode, NvmlError>

Gets the current compute mode for this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, check that error’s docs for more info
• Unknown, on any unexpected error

pub fn cuda_compute_capability( &self ) -> Result<CudaComputeCapability, NvmlError>

Gets the CUDA compute capability of this Device.

The returned version numbers are the same as those returned by cuDeviceGetAttribute() from the CUDA API.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn clock_info(&self, clock_type: Clock) -> Result<u32, NvmlError>

Gets this Device’s current clock speed for the given Clock type.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device cannot report the specified clock
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi or newer fully supported devices.

pub fn running_compute_processes(&self) -> Result<Vec<ProcessInfo>, NvmlError>

Gets information about processes with a compute context running on this Device.

This only returns information about running compute processes (such as a CUDA application with an active context). Graphics applications (OpenGL, DirectX) won’t be listed by this function.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn running_compute_processes_count(&self) -> Result<u32, NvmlError>

Gets the number of processes with a compute context running on this Device.

This only returns the count of running compute processes (such as a CUDA application with an active context). Graphics applications (OpenGL, DirectX) won’t be counted by this function.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn current_pcie_link_gen(&self) -> Result<u32, NvmlError>

Gets the current PCIe link generation.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if PCIe link information is not available
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi or newer fully supported devices.

pub fn current_pcie_link_width(&self) -> Result<u32, NvmlError>

Gets the current PCIe link width.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if PCIe link information is not available
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi or newer fully supported devices.

pub fn decoder_utilization(&self) -> Result<UtilizationInfo, NvmlError>

Gets the current utilization and sampling size (sampling size in μs) for the Decoder.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn fbc_stats(&self) -> Result<FbcStats, NvmlError>

Gets global statistics for active frame buffer capture sessions on this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Maxwell or newer fully supported devices.

pub fn fbc_sessions_info(&self) -> Result<Vec<FbcSessionInfo>, NvmlError>

Gets information about active frame buffer capture sessions on this Device.

Note that information such as the horizontal and vertical resolutions, the average FPS, and the average latency will be zero if no frames have been captured since a session was started.

Errors

• UnexpectedVariant, for which you can read the docs for
• IncorrectBits, if bits are found in a session’s info flags that don’t match the flags in this wrapper
• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Maxwell or newer fully supported devices.

pub fn fbc_session_count(&self) -> Result<u32, NvmlError>

Gets the number of active frame buffer capture sessions on this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn default_applications_clock( &self, clock_type: Clock ) -> Result<u32, NvmlError>

Gets the default applications clock that this Device boots with or defaults to after reset_applications_clocks().

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn detailed_ecc_errors( &self, error_type: MemoryError, counter_type: EccCounter ) -> Result<EccErrorCounts, NvmlError>

👎Deprecated: use Device.memory_error_counter()

Not documenting this because it’s deprecated. Read NVIDIA’s docs if you must use it.

pub fn is_display_active(&self) -> Result<bool, NvmlError>

Gets the display active state for this Device.

This method indicates whether a display is initialized on this Device. For example, whether or not an X Server is attached to this device and has allocated memory for the screen.

A display can be active even when no monitor is physically attached to this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

pub fn is_display_connected(&self) -> Result<bool, NvmlError>

Gets whether a physical display is currently connected to any of this Device’s connectors.

This calls the C function nvmlDeviceGetDisplayMode.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

pub fn is_ecc_enabled(&self) -> Result<EccModeState, NvmlError>

Get the current and pending ECC modes for this Device.

Changing ECC modes requires a reboot. The “pending” ECC mode refers to the target mode following the next reboot.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices. Only applicable to devices with ECC. Requires InfoRom::ECC version 1.0 or higher.

pub fn encoder_utilization(&self) -> Result<UtilizationInfo, NvmlError>

Gets the current utilization and sampling size (sampling size in μs) for the Encoder.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn encoder_capacity(&self, for_type: EncoderType) -> Result<u32, NvmlError>

Gets the current capacity of this device’s encoder in macroblocks per second.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this device is invalid
• NotSupported, if this Device does not support the given for_type
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Maxwell or newer fully supported devices.

pub fn encoder_stats(&self) -> Result<EncoderStats, NvmlError>

Gets the current encoder stats for this device.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Maxwell or newer fully supported devices.

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

Gets information about active encoder sessions on this device.

Errors

• Uninitialized, if the library has not been successfully initialized
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, if an enum variant not defined in this wrapper gets returned in a field of an EncoderSessionInfo struct
• Unknown, on any unexpected error

Device Support

Supports Maxwell or newer fully supported devices.

pub fn enforced_power_limit(&self) -> Result<u32, NvmlError>

Gets the effective power limit in milliwatts that the driver enforces after taking into account all limiters.

Note: This can be different from the .power_management_limit() if other limits are set elswhere. This includes the out-of-band power limit interface.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn fan_speed(&self, fan_idx: u32) -> Result<u32, NvmlError>

Gets the intended operating speed of the specified fan as a percentage of the maximum fan speed (100%).

Note: The reported speed is the intended fan speed. If the fan is physically blocked and unable to spin, the output will not match the actual fan speed.

You can determine valid fan indices using Self::num_fans().

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or fan_idx is invalid
• NotSupported, if this Device does not have a fan or is newer than Maxwell
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports all discrete products with dedicated fans.

pub fn num_fans(&self) -> Result<u32, NvmlError>

Gets the number of fans on this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this Device does not have a fan
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports all discrete products with dedicated fans.

pub fn gpu_operation_mode(&self) -> Result<OperationModeState, NvmlError>

Gets the current GPU operation mode and the pending one (that it will switch to after a reboot).

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

Device Support

Supports GK110 M-class and X-class Tesla products from the Kepler family. Modes LowDP and AllOn are supported on fully supported GeForce products. Not supported on Quadro and Tesla C-class products.

pub fn running_graphics_processes(&self) -> Result<Vec<ProcessInfo>, NvmlError>

Gets information about processes with a graphics context running on this Device.

This only returns information about graphics based processes (OpenGL, DirectX, etc.).

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn running_graphics_processes_count(&self) -> Result<u32, NvmlError>

Gets the number of processes with a graphics context running on this Device.

This only returns the count of graphics based processes (OpenGL, DirectX).

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

pub fn process_utilization_stats<T>( &self, last_seen_timestamp: T ) -> Result<Vec<ProcessUtilizationSample>, NvmlError>

where T: Into<Option<u64>>,

Gets utilization stats for relevant currently running processes.

Utilization stats are returned for processes that had a non-zero utilization stat at some point during the target sample period. Passing None as the last_seen_timestamp will target all samples that the driver has buffered; passing a timestamp retrieved from a previous query will target samples taken since that timestamp.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Maxwell or newer fully supported devices.

pub fn index(&self) -> Result<u32, NvmlError>

Gets the NVML index of this Device.

Keep in mind that the order in which NVML enumerates devices has no guarantees of consistency between reboots. Also, the NVML index may not correlate with other APIs, such as the CUDA device index.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible

pub fn config_checksum(&self) -> Result<u32, NvmlError>

Gets the checksum of the config stored in this Device’s infoROM.

Can be used to make sure that two GPUs have the exact same configuration. The current checksum takes into account configuration stored in PWR and ECC infoROM objects. The checksum can change between driver released or when the user changes the configuration (e.g. disabling/enabling ECC).

Errors

• CorruptedInfoROM, if this Device’s checksum couldn’t be retrieved due to infoROM corruption
• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports all devices with an infoROM.

pub fn info_rom_image_version(&self) -> Result<String, NvmlError>

Gets the global infoROM image version.

This image version, just like the VBIOS version, uniquely describes the exact version of the infoROM flashed on the board, in contrast to the infoROM object version which is only an indicator of supported features.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not have an infoROM
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Utf8Error, if the string obtained from the C function is not valid Utf8
• Unknown, on any unexpected error

Device Support

Supports all devices with an infoROM.

pub fn info_rom_version(&self, object: InfoRom) -> Result<String, NvmlError>

Gets the version information for this Device’s infoROM object, for the passed in object type.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not have an infoROM
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Utf8Error, if the string obtained from the C function is not valid UTF-8
• Unknown, on any unexpected error

Device Support

Supports all devices with an infoROM.

Fermi and higher parts have non-volatile on-board memory for persisting device info, such as aggregate ECC counts. The version of the data structures in this memory may change from time to time.

pub fn max_clock_info(&self, clock_type: Clock) -> Result<u32, NvmlError>

Gets the maximum clock speeds for this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device cannot report the specified Clock
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices.

Note: On GPUs from the Fermi family, current P0 (Performance state 0?) clocks (reported by .clock_info()) can differ from max clocks by a few MHz.

pub fn max_pcie_link_gen(&self) -> Result<u32, NvmlError>

Gets the max PCIe link generation possible with this Device and system.

For a gen 2 PCIe device attached to a gen 1 PCIe bus, the max link generation this function will report is generation 1.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if PCIe link information is not available
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices.

pub fn max_pcie_link_width(&self) -> Result<u32, NvmlError>

Gets the maximum PCIe link width possible with this Device and system.

For a device with a 16x PCie bus width attached to an 8x PCIe system bus, this method will report a max link width of 8.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if PCIe link information is not available
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices.

pub fn memory_error_counter( &self, error_type: MemoryError, counter_type: EccCounter, location: MemoryLocation ) -> Result<u64, NvmlError>

Gets the requested memory error counter for this Device.

Only applicable to devices with ECC. Requires ECC mode to be enabled.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if error_type, counter_type, or location is invalid (shouldn’t occur?)
• NotSupported, if this Device does not support ECC error reporting for the specified memory
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices. Requires InfoRom::ECC version 2.0 or higher to report aggregate location-based memory error counts. Requires `InfoRom::ECC version 1.0 or higher to report all other memory error counts.

pub fn memory_info(&self) -> Result<MemoryInfo, NvmlError>

Gets the amount of used, free and total memory available on this Device, in bytes.

Note that enabling ECC reduces the amount of total available memory due to the extra required parity bits.

Also note that on Windows, most device memory is allocated and managed on startup by Windows.

Under Linux and Windows TCC (no physical display connected), the reported amount of used memory is equal to the sum of memory allocated by all active channels on this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn is_multi_gpu_board(&self) -> Result<bool, NvmlError>

Identifies whether or not this Device is on a multi-GPU board.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi or newer fully supported devices.

pub fn name(&self) -> Result<String, NvmlError>

The name of this Device, e.g. “Tesla C2070”.

The name is an alphanumeric string that denotes a particular product.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Utf8Error, if the string obtained from the C function is not valid Utf8
• Unknown, on any unexpected error

pub fn pci_info(&self) -> Result<PciInfo, NvmlError>

Gets the PCI attributes of this Device.

See PciInfo for details about the returned attributes.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• GpuLost, if the GPU has fallen off the bus or is otherwise inaccessible
• Utf8Error, if a string obtained from the C function is not valid Utf8
• Unknown, on any unexpected error

pub fn pcie_replay_counter(&self) -> Result<u32, NvmlError>

Gets the PCIe replay counter.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn pcie_throughput( &self, counter: PcieUtilCounter ) -> Result<u32, NvmlError>

Gets PCIe utilization information in KB/s.

The function called within this method is querying a byte counter over a 20ms interval and thus is the PCIE throughput over that interval.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or counter is invalid (shouldn’t occur?)
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Maxwell and newer fully supported devices.

Environment Support

This method is not supported on virtual machines running vGPUs.

pub fn performance_state(&self) -> Result<PerformanceState, NvmlError>

Gets the current performance state for this Device. 0 == max, 15 == min.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

Device Support

Supports Fermi or newer fully supported devices.

pub fn power_management_limit_default(&self) -> Result<u32, NvmlError>

Gets the default power management limit for this Device, in milliwatts.

This is the limit that this Device boots with.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn power_management_limit(&self) -> Result<u32, NvmlError>

Gets the power management limit associated with this Device.

The power limit defines the upper boundary for the card’s power draw. If the card’s total power draw reaches this limit, the power management algorithm kicks in.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi or newer fully supported devices.

This reading is only supported if power management mode is supported. See .is_power_management_algo_active(). Yes, it’s deprecated, but that’s what NVIDIA’s docs said to see.

pub fn power_management_limit_constraints( &self ) -> Result<PowerManagementConstraints, NvmlError>

Gets information about possible power management limit values for this Device, in milliwatts.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer fully supported devices.

pub fn is_power_management_algo_active(&self) -> Result<bool, NvmlError>

👎Deprecated: NVIDIA states that “this API has been deprecated.”

Not documenting this because it’s deprecated. Read NVIDIA’s docs if you must use it.

pub fn power_state(&self) -> Result<PerformanceState, NvmlError>

👎Deprecated: use .performance_state().

Not documenting this because it’s deprecated. Read NVIDIA’s docs if you must use it.

pub fn power_usage(&self) -> Result<u32, NvmlError>

Gets the power usage for this GPU and its associated circuitry (memory) in milliwatts.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support power readings
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices.

This reading is accurate to within +/- 5% of current power draw on Fermi and Kepler GPUs. It is only supported if power management mode is supported. See .is_power_management_algo_active(). Yes, that is deprecated, but that’s what NVIDIA’s docs say to see.

pub fn total_energy_consumption(&self) -> Result<u64, NvmlError>

Gets this device’s total energy consumption in millijoules (mJ) since the last driver reload.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support energy readings
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Volta and newer fully supported devices.

pub fn retired_pages( &self, cause: RetirementCause ) -> Result<Vec<RetiredPage>, NvmlError>

Gets the list of retired pages filtered by cause, including pages pending retirement.

I cannot verify that this method will work because the call within is not supported on my dev machine. Please verify for yourself that it works before you use it. If you are able to test it on your machine, please let me know if it works; if it doesn’t, I would love a PR.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device doesn’t support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn are_pages_pending_retired(&self) -> Result<bool, NvmlError>

Gets whether there are pages pending retirement (they need a reboot to fully retire).

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device doesn’t support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn samples<T>( &self, sample_type: Sampling, last_seen_timestamp: T ) -> Result<Vec<Sample>, NvmlError>

where T: Into<Option<u64>>,

Gets recent samples for this Device.

last_seen_timestamp represents the CPU timestamp in μs. Passing in None will fetch all samples maintained in the underlying buffer; you can alternatively pass in a timestamp retrieved from the date of the previous query in order to obtain more recent samples.

The advantage of using this method for samples in contrast to polling via existing methods is to get higher frequency data at a lower polling cost.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this query is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• NotFound, if sample entries are not found
• UnexpectedVariant, check that error’s docs for more info
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

Examples

use nvml_wrapper::enum_wrappers::device::Sampling;

// Passing `None` indicates that we want all `Power` samples in the sample buffer
let power_samples = device.samples(Sampling::Power, None)?;

// Take the first sample from the vector, if it exists...
if let Some(sample) = power_samples.get(0) {
    // ...and now we can get all `ProcessorClock` samples that exist with a later
    // timestamp than the `Power` sample.
    let newer_clock_samples = device.samples(Sampling::ProcessorClock, sample.timestamp)?;
}

pub fn field_values_for( &self, id_slice: &[FieldId] ) -> Result<Vec<Result<FieldValueSample, NvmlError>>, NvmlError>

Get values for the given slice of FieldIds.

NVIDIA’s docs say that if any of the FieldIds are populated by the same driver call, the samples for those IDs will be populated by a single call instead of a call per ID. It would appear, then, that this is essentially a “batch-request” API path for better performance.

There are too many field ID constants defined in the header to reasonably wrap them with an enum in this crate. Instead, I’ve re-exported the defined ID constants at nvml_wrapper::sys_exports::field_id::*; stick those constants in FieldIds for use with this function.

Errors

Outer Result

• InvalidArg, if id_slice has a length of zero

Inner Result

• UnexpectedVariant, check that error’s docs for more info

Device Support

Device support varies per FieldId that you pass in.

pub fn serial(&self) -> Result<String, NvmlError>

Gets the globally unique board serial number associated with this Device’s board as an alphanumeric string.

This serial number matches the serial number tag that is physically attached to the board.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device doesn’t support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Utf8Error, if the string obtained from the C function is not valid Utf8
• Unknown, on any unexpected error

Device Support

Supports all products with an infoROM.

pub fn board_part_number(&self) -> Result<String, NvmlError>

Gets the board part number for this Device.

The board part number is programmed into the board’s infoROM.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if the necessary VBIOS fields have not been filled
• GpuLost, if the target GPU has fellen off the bus or is otherwise inaccessible
• Utf8Error, if the string obtained from the C function is not valid Utf8
• Unknown, on any unexpected error

pub fn current_throttle_reasons(&self) -> Result<ThrottleReasons, NvmlError>

Gets current throttling reasons.

Note that multiple reasons can be affecting clocks at once.

The returned bitmask is created via the ThrottleReasons::from_bits_truncate method, meaning that any bits that don’t correspond to flags present in this version of the wrapper will be dropped.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports all fully supported devices.

pub fn current_throttle_reasons_strict( &self ) -> Result<ThrottleReasons, NvmlError>

Gets current throttling reasons, erroring if any bits correspond to non-present flags.

Note that multiple reasons can be affecting clocks at once.

Errors

• Uninitialized, if the library has not been successfully initialized
• IncorrectBits, if NVML returns any bits that do not correspond to flags in ThrottleReasons
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports all fully supported devices.

pub fn supported_throttle_reasons(&self) -> Result<ThrottleReasons, NvmlError>

Gets a bitmask of the supported throttle reasons.

These reasons can be returned by .current_throttle_reasons().

The returned bitmask is created via the ThrottleReasons::from_bits_truncate method, meaning that any bits that don’t correspond to flags present in this version of the wrapper will be dropped.

Errors

• Uninitialized, if the library has not been successfully initialized
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports all fully supported devices.

Environment Support

This method is not supported on virtual machines running vGPUs.

pub fn supported_throttle_reasons_strict( &self ) -> Result<ThrottleReasons, NvmlError>

Gets a bitmask of the supported throttle reasons, erroring if any bits correspond to non-present flags.

These reasons can be returned by .current_throttle_reasons().

Errors

• Uninitialized, if the library has not been successfully initialized
• IncorrectBits, if NVML returns any bits that do not correspond to flags in ThrottleReasons
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports all fully supported devices.

Environment Support

This method is not supported on virtual machines running vGPUs.

pub fn supported_graphics_clocks( &self, for_mem_clock: u32 ) -> Result<Vec<u32>, NvmlError>

Gets a Vec of possible graphics clocks that can be used as an arg for set_applications_clocks().

Errors

• Uninitialized, if the library has not been successfully initialized
• NotFound, if the specified for_mem_clock is not a supported frequency
• InvalidArg, if this Device is invalid
• NotSupported, if this Device doesn’t support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn supported_memory_clocks(&self) -> Result<Vec<u32>, NvmlError>

Gets a Vec of possible memory clocks that can be used as an arg for set_applications_clocks().

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device doesn’t support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn temperature(&self, sensor: TemperatureSensor) -> Result<u32, NvmlError>

Gets the current temperature readings for the given sensor, in °C.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or sensor is invalid (shouldn’t occur?)
• NotSupported, if this Device does not have the specified sensor
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn temperature_threshold( &self, threshold_type: TemperatureThreshold ) -> Result<u32, NvmlError>

Gets the temperature threshold for this Device and the specified threshold_type, in °C.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or threshold_type is invalid (shouldn’t occur?)
• NotSupported, if this Device does not have a temperature sensor or is unsupported
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn total_ecc_errors( &self, error_type: MemoryError, counter_type: EccCounter ) -> Result<u64, NvmlError>

Gets the total ECC error counts for this Device.

Only applicable to devices with ECC. The total error count is the sum of errors across each of the separate memory systems, i.e. the total set of errors across the entire device.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or either enum is invalid (shouldn’t occur?)
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices. Requires InfoRom::ECC version 1.0 or higher. Requires ECC mode to be enabled.

pub fn uuid(&self) -> Result<String, NvmlError>

Gets the globally unique immutable UUID associated with this Device as a 5 part hexadecimal string.

This UUID augments the immutable, board serial identifier. It is a globally unique identifier and is the only available identifier for pre-Fermi-architecture products. It does NOT correspond to any identifier printed on the board.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Utf8Error, if the string obtained from the C function is not valid Utf8
• Unknown, on any unexpected error

Examples

The UUID can be used to compare two Devices and find out if they represent the same physical device:

if device1.uuid()? == device2.uuid()? {
    println!("`device1` represents the same physical device that `device2` does.");
}

pub fn utilization_rates(&self) -> Result<Utilization, NvmlError>

Gets the current utilization rates for this Device’s major subsystems.

Note: During driver initialization when ECC is enabled, one can see high GPU and memory utilization readings. This is caused by the ECC memory scrubbing mechanism that is performed during driver initialization.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices.

pub fn vbios_version(&self) -> Result<String, NvmlError>

Gets the VBIOS version of this Device.

The VBIOS version may change from time to time.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Utf8Error, if the string obtained from the C function is not valid UTF-8
• Unknown, on any unexpected error

pub fn violation_status( &self, perf_policy: PerformancePolicy ) -> Result<ViolationTime, NvmlError>

Gets the duration of time during which this Device was throttled (lower than the requested clocks) due to power or thermal constraints.

This is important to users who are trying to understand if their GPUs throttle at any point while running applications. The difference in violation times at two different reference times gives the indication of a GPU throttling event.

Violation for thermal capping is not supported at this time.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if this Device is invalid or perf_policy is invalid (shouldn’t occur?)
• NotSupported, if this query is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible

Device Support

Supports Kepler or newer fully supported devices.

pub fn irq_num(&self) -> Result<u32, NvmlError>

Gets the interrupt number for this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this query is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible

pub fn num_cores(&self) -> Result<u32, NvmlError>

Gets the core count for this Device.

The cores represented in the count here are commonly referred to as “CUDA cores”.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this query is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible

pub fn power_source(&self) -> Result<PowerSource, NvmlError>

Gets the power source of this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this query is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible

pub fn memory_bus_width(&self) -> Result<u32, NvmlError>

Gets the memory bus width of this Device.

The returned value is in bits (i.e. 320 for a 320-bit bus width).

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this query is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible

pub fn max_pcie_link_speed(&self) -> Result<PcieLinkMaxSpeed, NvmlError>

Gets the max PCIe link speed for this Device.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this query is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible

pub fn pcie_link_speed(&self) -> Result<u32, NvmlError>

Gets the current PCIe link speed for this Device.

NVML docs say the returned value is in “MBPS”. Looking at the output of this function, however, seems to imply it actually returns the transfer rate per lane of the PCIe link in MT/s, not the combined multi-lane throughput. See PcieLinkMaxSpeed for the same discussion.

For example, on my machine currently:

Right now the device is connected via a PCIe gen 4 x16 interface and pcie_link_speed() returns 16000

This lines up with the “transfer rate per lane numbers” listed at https://en.wikipedia.org/wiki/PCI_Express. PCIe gen 4 provides 16.0 GT/s. Also, checking my machine at a different moment yields:

Right now the device is connected via a PCIe gen 2 x16 interface and pcie_link_speed() returns 5000

Which again lines up with the table on the page above; PCIe gen 2 provides 5.0 GT/s.

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this query is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible

pub fn bus_type(&self) -> Result<BusType, NvmlError>

Gets the type of bus by which this Device is connected.

Errors

• Uninitialized, if the library has not been successfully initialized

pub fn architecture(&self) -> Result<DeviceArchitecture, NvmlError>

Gets the architecture of this Device.

Errors

• Uninitialized, if the library has not been successfully initialized

pub fn is_on_same_board_as( &self, other_device: &Device<'_> ) -> Result<bool, NvmlError>

Checks if this Device and the passed-in device are on the same physical board.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if either Device is invalid
• NotSupported, if this check is not supported by this Device
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn reset_applications_clocks(&mut self) -> Result<(), NvmlError>

Resets the application clock to the default value.

This is the applications clock that will be used after a system reboot or a driver reload. The default value is a constant, but the current value be changed with .set_applications_clocks().

On Pascal and newer hardware, if clocks were previously locked with .set_applications_clocks(), this call will unlock clocks. This returns clocks to their default behavior of automatically boosting above base clocks as thermal limits allow.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer non-GeForce fully supported devices and Maxwell or newer GeForce devices.

pub fn set_auto_boosted_clocks( &mut self, enabled: bool ) -> Result<(), NvmlError>

Try to set the current state of auto boosted clocks on this Device.

Auto boosted clocks are enabled by default on some hardware, allowing the GPU to run as fast as thermals will allow it to. Auto boosted clocks should be disabled if fixed clock rates are desired.

On Pascal and newer hardware, auto boosted clocks are controlled through application clocks. Use .set_applications_clocks() and .reset_applications_clocks() to control auto boost behavior.

Non-root users may use this API by default, but access can be restricted by root using .set_api_restriction().

Note: persistence mode is required to modify the curent auto boost settings and therefore must be enabled.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support auto boosted clocks
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Not sure why nothing is said about NoPermission.

Device Support

Supports Kepler and newer fully supported devices.

pub fn set_auto_boosted_clocks_default( &mut self, enabled: bool ) -> Result<(), NvmlError>

Try to set the default state of auto boosted clocks on this Device.

This is the default state that auto boosted clocks will return to when no compute processes (e.g. CUDA application with an active context) are running.

Requires root/admin permissions.

Auto boosted clocks are enabled by default on some hardware, allowing the GPU to run as fast as thermals will allow it to. Auto boosted clocks should be disabled if fixed clock rates are desired.

On Pascal and newer hardware, auto boosted clocks are controlled through application clocks. Use .set_applications_clocks() and .reset_applications_clocks() to control auto boost behavior.

Errors

• Uninitialized, if the library has not been successfully initialized
• NoPermission, if the calling user does not have permission to change the default state
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support auto boosted clocks
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler or newer non-GeForce fully supported devices and Maxwell or newer GeForce devices.

pub fn validate_info_rom(&self) -> Result<(), NvmlError>

Reads the infoROM from this Device’s flash and verifies the checksum.

Errors

• Uninitialized, if the library has not been successfully initialized
• CorruptedInfoROM, if this Device’s infoROM is corrupted
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Not sure why InvalidArg is not mentioned.

Device Support

Supports all devices with an infoROM.

pub fn clear_accounting_pids(&mut self) -> Result<(), NvmlError>

Clears accounting information about all processes that have already terminated.

Requires root/admin permissions.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support this feature
• NoPermission, if the user doesn’t have permission to perform this operation
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn accounting_buffer_size(&self) -> Result<u32, NvmlError>

Gets the number of processes that the circular buffer with accounting PIDs can hold (in number of elements).

This is the max number of processes that accounting information will be stored for before the oldest process information will get overwritten by information about new processes.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support this feature or accounting mode is disabled
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn is_accounting_enabled(&self) -> Result<bool, NvmlError>

Gets whether or not per-process accounting mode is enabled.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support this feature
• UnexpectedVariant, for which you can read the docs for
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn accounting_pids(&self) -> Result<Vec<u32>, NvmlError>

Gets the list of processes that can be queried for accounting stats.

The list of processes returned can be in running or terminated state. Note that in the case of a PID collision some processes might not be accessible before the circular buffer is full.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support this feature or accounting mode is disabled
• Unknown, on any unexpected error

pub fn accounting_stats_for( &self, process_id: u32 ) -> Result<AccountingStats, NvmlError>

Gets a process’s accounting stats.

Accounting stats capture GPU utilization and other statistics across the lifetime of a process. Accounting stats can be queried during the lifetime of the process and after its termination. The time field in AccountingStats is reported as zero during the lifetime of the process and updated to the actual running time after its termination.

Accounting stats are kept in a circular buffer; newly created processes overwrite information regarding old processes.

Note:

• Accounting mode needs to be on. See .is_accounting_enabled().
• Only compute and graphics applications stats can be queried. Monitoring applications can’t be queried since they don’t contribute to GPU utilization.
• If a PID collision occurs, the stats of the latest process (the one that terminated last) will be reported.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotFound, if the process stats were not found
• NotSupported, if this Device does not support this feature or accounting mode is disabled
• Unknown, on any unexpected error

Device Support

Suports Kepler and newer fully supported devices.

Warning

On Kepler devices, per-process stats are accurate only if there’s one process running on this Device.

pub fn set_accounting(&mut self, enabled: bool) -> Result<(), NvmlError>

Enables or disables per-process accounting.

Requires root/admin permissions.

Note:

• This setting is not persistent and will default to disabled after the driver unloads. Enable persistence mode to be sure the setting doesn’t switch off to disabled.
• Enabling accounting mode has no negative impact on GPU performance.
• Disabling accounting clears accounting information for all PIDs

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support this feature
• NoPermission, if the user doesn’t have permission to perform this operation
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn clear_ecc_error_counts( &mut self, counter_type: EccCounter ) -> Result<(), NvmlError>

Clears the ECC error and other memory error counts for this Device.

Sets all of the specified ECC counters to 0, including both detailed and total counts. This operation takes effect immediately.

Requires root/admin permissions and ECC mode to be enabled.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid or counter_type is invalid (shouldn’t occur?)
• NotSupported, if this Device does not support this feature
• NoPermission, if the user doesn’t have permission to perform this operation
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices. Only applicable to devices with ECC. Requires InfoRom::ECC version 2.0 or higher to clear aggregate location-based ECC counts. Requires InfoRom::ECC version 1.0 or higher to clear all other ECC counts.

pub fn set_api_restricted( &mut self, api_type: Api, restricted: bool ) -> Result<(), NvmlError>

Changes the root/admin restrictions on certain APIs.

This method can be used by a root/admin user to give non root/admin users access to certain otherwise-restricted APIs. The new setting lasts for the lifetime of the NVIDIA driver; it is not persistent. See .is_api_restricted() to query current settings.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid or api_type is invalid (shouldn’t occur?)
• NotSupported, if this Device does not support changing API restrictions or this Device does not support the feature that API restrictions are being set for (e.g. enabling/disabling auto boosted clocks is not supported by this Device).
• NoPermission, if the user doesn’t have permission to perform this operation
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices.

pub fn set_applications_clocks( &mut self, mem_clock: u32, graphics_clock: u32 ) -> Result<(), NvmlError>

Sets clocks that applications will lock to.

Sets the clocks that compute and graphics applications will be running at. e.g. CUDA driver requests these clocks during context creation which means this property defines clocks at which CUDA applications will be running unless some overspec event occurs (e.g. over power, over thermal or external HW brake).

Can be used as a setting to request constant performance. Requires root/admin permissions.

On Pascal and newer hardware, this will automatically disable automatic boosting of clocks. On K80 and newer Kepler and Maxwell GPUs, users desiring fixed performance should also call .set_auto_boosted_clocks(false) to prevent clocks from automatically boosting above the clock value being set here.

You can determine valid mem_clock and graphics_clock arg values via Self::supported_memory_clocks() and Self::supported_graphics_clocks().

Note that after a system reboot or driver reload applications clocks go back to their default value.

See also Self::set_mem_locked_clocks().

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid or the clocks are not a valid combo
• NotSupported, if this Device does not support this feature
• NoPermission, if the user doesn’t have permission to perform this operation
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer non-GeForce fully supported devices and Maxwell or newer GeForce devices.

pub fn set_compute_mode(&mut self, mode: ComputeMode) -> Result<(), NvmlError>

Sets the compute mode for this Device.

The compute mode determines whether a GPU can be used for compute operations and whether it can be shared across contexts.

This operation takes effect immediately. Under Linux it is not persistent across reboots and always resets to Default. Under Windows it is persistent.

Under Windows, compute mode may only be set to Default when running in WDDM (physical display connected).

Requires root/admin permissions.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid or mode is invalid (shouldn’t occur?)
• NotSupported, if this Device does not support this feature
• NoPermission, if the user doesn’t have permission to perform this operation
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

pub fn set_gpu_locked_clocks( &mut self, setting: GpuLockedClocksSetting ) -> Result<(), NvmlError>

Lock this Device’s clocks to a specific frequency range.

This setting supercedes application clock values and takes effect regardless of whether or not any CUDA apps are running. It can be used to request constant performance.

After a system reboot or a driver reload the clocks go back to their default values.

Requires root/admin permissions.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the provided minimum and maximum clocks are not a valid combo
• NotSupported, if this Device does not support this feature
• NoPermission, if the user doesn’t have permission to perform this operation
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Volta and newer fully supported devices.

pub fn reset_gpu_locked_clocks(&mut self) -> Result<(), NvmlError>

Reset this Device’s clocks to their default values.

This resets to the same values that would be used after a reboot or driver reload (defaults to idle clocks but can be configured via Self::set_applications_clocks()).

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Volta and newer fully supported devices.

pub fn set_mem_locked_clocks( &mut self, min_clock_mhz: u32, max_clock_mhz: u32 ) -> Result<(), NvmlError>

Lock this Device’s memory clocks to a specific frequency range.

This setting supercedes application clock values and takes effect regardless of whether or not any CUDA apps are running. It can be used to request constant performance. See also Self::set_applications_clocks().

After a system reboot or a driver reload the clocks go back to their default values. See also Self::reset_mem_locked_clocks().

You can use Self::supported_memory_clocks() to determine valid frequency combinations to pass into this call.

Device Support

Supports Ampere and newer fully supported devices.

pub fn reset_mem_locked_clocks(&mut self) -> Result<(), NvmlError>

Reset this Device’s memory clocks to their default values.

This resets to the same values that would be used after a reboot or driver reload (defaults to idle clocks but can be configured via Self::set_applications_clocks()).

Errors

• Uninitialized, if the library has not been successfully initialized
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Ampere and newer fully supported devices.

pub fn set_ecc(&mut self, enabled: bool) -> Result<(), NvmlError>

Set whether or not ECC mode is enabled for this Device.

Requires root/admin permissions. Only applicable to devices with ECC.

This operation takes effect after the next reboot.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid
• NotSupported, if this Device does not support this feature
• NoPermission, if the user doesn’t have permission to perform this operation
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports Kepler and newer fully supported devices. Requires InfoRom::ECC version 1.0 or higher.

pub fn set_gpu_op_mode(&mut self, mode: OperationMode) -> Result<(), NvmlError>

Sets the GPU operation mode for this Device.

Requires root/admin permissions. Changing GOMs requires a reboot, a requirement that may be removed in the future.

Compute only GOMs don’t support graphics acceleration. Under Windows switching to these GOMs when the pending driver model is WDDM (physical display attached) is not supported.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid or mode is invalid (shouldn’t occur?)
• NotSupported, if this Device does not support GOMs or a specific mode
• NoPermission, if the user doesn’t have permission to perform this operation
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

Device Support

Supports GK110 M-class and X-class Tesla products from the Kepler family. Modes LowDP and AllOn are supported on fully supported GeForce products. Not supported on Quadro and Tesla C-class products.

pub fn set_power_management_limit( &mut self, limit: u32 ) -> Result<(), NvmlError>

Sets the power limit for this Device, in milliwatts.

This limit is not persistent across reboots or driver unloads. Enable persistent mode to prevent the driver from unloading when no application is using this Device.

Requires root/admin permissions. See .power_management_limit_constraints() to check the allowed range of values.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the Device is invalid or limit is out of range
• NotSupported, if this Device does not support this feature
• GpuLost, if this Device has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

For some reason NVIDIA does not mention NoPermission.

Device Support

Supports Kepler and newer fully supported devices.

pub fn link_wrapper_for(&self, link: u32) -> NvLink<'_, '_>

Obtain a struct that represents an NvLink.

NVIDIA does not provide any information as to how to obtain a valid NvLink value, so you’re on your own there.

Trait Implementations

impl<'nvml> Debug for Device<'nvml>

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

Formats the value using the given formatter.

impl<'nvml> Send for Device<'nvml>

impl<'nvml> Sync for Device<'nvml>