Struct nvml_wrapper::device::Device

source ·

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

Expand description

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§

source §

impl<'nvml> Device<'nvml>

source

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.

source

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

Access the Nvml reference this struct wraps

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

source

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.

source

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.

source

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.

source

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

source

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

source

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.

source

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

source

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

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

source

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.

source

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.

source

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

source

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

source

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

Gets the current and pending driver model for this Device.

On Windows, the device driver can run in either WDDM or WDM (TCC) modes. If a display is attached to the device it must run in WDDM mode. TCC mode is preferred if a display is not attached.

§Errors

Uninitialized, if the library has not been successfully initialized
InvalidArg, if this Device is invalid
NotSupported, if the platform is not Windows
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.

§Platform Support

Only supports Windows.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

source

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

source

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.

source

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

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

source

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.

source

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

source

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

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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)?;
}

source

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.

source

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.

source

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

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

source

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.

source

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.

source

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.");
}

source

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.

source

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

source

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.

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

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

Gets the architecture of this Device.

§Errors

Uninitialized, if the library has not been successfully initialized

source

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

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

source

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.

source

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.

source

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.

source

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.

source

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.

§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.

source

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

source

pub fn set_driver_model( &mut self, model: DriverModel, flags: Behavior ) -> Result<(), NvmlError>

Sets the driver model for this Device.

This operation takes effect after the next reboot. The model may only be set to WDDM when running in DEFAULT compute mode. Changing the model to WDDM is not supported when the GPU doesn’t support graphics acceleration or will not support it after a reboot.

On Windows platforms the device driver can run in either WDDM or WDM (TCC) mode. If a physical display is attached to a device it must run in WDDM mode.

It is possible to force the change to WDM (TCC) while the display is still attached with a Behavior of FORCE. This should only be done if the host is subsequently powered down and the display is detached from this Device before the next reboot.

Requires root/admin permissions.

§Errors

Uninitialized, if the library has not been successfully initialized
InvalidArg, if the Device is invalid or model 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 Fermi and newer fully supported devices.

§Platform Support

Only supports Windows.

§Examples

use nvml_wrapper::bitmasks::Behavior;
use nvml_wrapper::enum_wrappers::device::DriverModel;

device.set_driver_model(DriverModel::WDM, Behavior::DEFAULT)?;

// Force the change to WDM (TCC)
device.set_driver_model(DriverModel::WDM, Behavior::FORCE)?;

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.