Struct nvml_wrapper::NVML

pub struct NVML;

The main struct that this library revolves around.

According to NVIDIA's documentation, "It is the user's responsibility to call nvmlInit() before calling any other methods, and nvmlShutdown() once NVML is no longer being used." This struct is used to enforce those rules.

Also according to NVIDIA's documentation, "NVML is thread-safe so it is safe to make simultaneous NVML calls from multiple threads." In the Rust world, this translates to NVML being Send + Sync. You can .clone() an Arc wrapped NVML and enjoy using it on any thread.

NOTE: If you care about possible errors returned from nvmlShutdown(), use the .shutdown() method on this struct. The Drop implementation ignores errors.

When reading documentation on this struct and its members, remember that a lot of it, especially in regards to errors returned, is copied from NVIDIA's docs. While they can be found online here, the hosted docs are outdated and do not accurately reflect the version of NVML that this library is written for; beware. You should ideally read the doc comments on an up-to-date NVML API header. Such a header can be downloaded as part of the CUDA toolkit.

Methods

impl NVML

fn init() -> Result<Self>

Handles NVML initilization and must be called before doing anything else.

This static function can be called multiple times and multiple NVML structs can be used at the same time. NVIDIA's docs state that "A reference count of the number of initializations is maintained. Shutdown only occurs when the reference count reaches zero."

In practice, there should be no need to create multiple NVML structs; wrap this struct in an Arc and go that route.

Note that this will initialize NVML but not any GPUs. This means that NVML can communicate with a GPU even when other GPUs in a system are bad or unstable.

Errors

• DriverNotLoaded, if the NVIDIA driver is not running
• NoPermission, if NVML does not have permission to talk to the driver
• Unknown, on any unexpected error

fn shutdown(self) -> Result<()>

Use this to shutdown NVML and release allocated resources if you care about handling potential errors (the Drop implementation ignores errors!).

Errors

• Uninitialized, if the library has not been successfully initialized
• Unknown, on any unexpected error

fn device_count(&self) -> Result<u32>

Get the number of compute devices in the system (compute device == one GPU).

Note that this may return devices you do not have permission to access.

Errors

• Uninitialized, if the library has not been successfully initialized
• Unknown, on any unexpected error

fn sys_driver_version(&self) -> Result<String>

Gets the version of the system's graphics driver and returns it as an alphanumeric string.

Errors

• Uninitialized, if the library has not been successfully initialized
• Utf8Error, if the string obtained from the C function is not valid Utf8

fn sys_nvml_version(&self) -> Result<String>

Gets the version of the system's NVML library and returns it as an alphanumeric string.

Errors

• Uninitialized, if the library has not been successfully initialized
• Utf8Error, if the string obtained from the C function is not valid Utf8

fn sys_process_name(&self, pid: u32, length: usize) -> Result<String>

Gets the name of the process for the given process ID, cropped to the provided length.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if the length is 0 (if this is returned without length being 0, file an issue)
• NotFound, if the process does not exist
• NoPermission, if the user doesn't have permission to perform the operation
• Utf8Error, if the string obtained from the C function is not valid UTF-8. NVIDIA's docs say that the string encoding is ANSI, so this may very well happen.
• Unknown, on any unexpected error

fn device_by_index(&self, index: u32) -> Result<Device>

Acquire the handle for a particular device based on its index (starts at 0).

Usage of this function causes NVML to initialize the target GPU. Additional GPUs may be initialized if the target GPU is an SLI slave.

You can determine valid indices by using .get_device_count(). This function doesn't call that for you, but the actual C function to get the device handle will return an error in the case of an invalid index. This means that the InvalidArg error will be returned if you pass in an invalid index.

NVIDIA's docs state that "The order in which NVML enumerates devices has no guarantees of consistency between reboots. For that reason it is recommended that devices be looked up by their PCI ids or UUID." In this library, that translates into usage of .device_by_uuid() and .device_by_pci_bus_id().

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 index is invalid
• InsufficientPower, if any attached devices have improperly attached external power cables
• NoPermission, if the user doesn't have permission to talk to this device
• IrqIssue, if the NVIDIA kernel detected an interrupt issue with the attached GPUs
• GpuLost, if the target GPU has fallen off the bus or is otherwise inaccessible
• Unknown, on any unexpected error

fn device_by_pci_bus_id<S: AsRef<str>>(&self, pci_bus_id: S) -> Result<Device> where
    Vec<u8>: From<S>, 

Acquire the handle for a particular device based on its PCI bus ID.

Usage of this function causes NVML to initialize the target GPU. Additional GPUs may be initialized if the target GPU is an SLI slave.

The bus ID corresponds to the bus_id returned by Device.pci_info().

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if pci_bus_id is invalid
• NotFound, if pci_bus_id does not match a valid device on the system
• InsufficientPower, if any attached devices have improperly attached external power cables
• NoPermission, if the user doesn't have permission to talk to this device
• IrqIssue, if the NVIDIA kernel detected an interrupt issue with the attached GPUs
• GpuLost, if the target GPU has fallen off the bus or is otherwise inaccessible
• NulError, for which you can read the docs on std::ffi::NulError
• Unknown, on any unexpected error

fn device_by_serial<S: AsRef<str>>(&self, board_serial: S) -> Result<Device> where
    Vec<u8>: From<S>, 

Deprecated

: use .device_by_uuid(), this errors on dual GPU boards

Not documenting this because it's deprecated and does not seem to work anymore.

fn device_by_uuid<S: AsRef<str>>(&self, uuid: S) -> Result<Device> where
    Vec<u8>: From<S>, 

Acquire the handle for a particular device based on its globally unique immutable UUID.

Usage of this function causes NVML to initialize the target GPU. Additional GPUs may be initialized as the function called within searches for the target GPU.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if uuid is invalid
• NotFound, if uuid does not match a valid device on the system
• InsufficientPower, if any attached devices have improperly attached external power cables
• IrqIssue, if the NVIDIA kernel detected an interrupt issue with the attached GPUs
• GpuLost, if the target GPU has fallen off the bus or is otherwise inaccessible
• NulError, for which you can read the docs on std::ffi::NulError
• Unknown, on any unexpected error

NVIDIA doesn't mention NoPermission for this one. Strange!

fn unit_by_index(&self, index: u32) -> Result<Unit>

Acquire the handle for a particular Unit based on its index.

Valid indices are derived from the count returned by .unit_count(). For example, if unit_count is 2 the valid indices are 0 and 1, corresponding to UNIT 0 and UNIT 1.

Note that the order in which NVML enumerates units has no guarantees of consistency between reboots.

Errors

• Uninitialized, if the library has not been successfully initialized
• InvalidArg, if index is invalid
• Unknown, on any unexpected error

Device Support

For S-class products.

fn are_devices_on_same_board(device1: &Device, device2: &Device) -> Result<bool>

Checks if the passed-in Devices are on the same physical board.

Note: this is the same as Device.is_on_same_board_as().

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

fn hic_versions(&self) -> Result<Vec<HwbcEntry>>

Gets the IDs and firmware versions for any Host Interface Cards in the system.

Errors

• Uninitialized, if the library has not been successfully initialized

Device Support

Supports S-class products.

fn hic_count(&self) -> Result<u32>

Gets the count of Host Interface Cards in the system.

Errors

• Uninitialized, if the library has not been successfully initialized

Device Support

Supports S-class products.

fn unit_count(&self) -> Result<u32>

Gets the number of units in the system.

Errors

• Uninitialized, if the library has not been successfully initialized
• Unknown, on any unexpected error

Device Support

Supports S-class products.

fn create_event_set(&self) -> Result<EventSet>

Create an empty set of events.

Errors

• Uninitialized, if the library has not been successfully initialized
• Unknown, on any unexpected error

Device Support

Supports Fermi and newer fully supported devices.

Trait Implementations

impl Debug for NVML

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Send for NVML

impl Sync for NVML

impl Drop for NVML

This Drop implementation ignores errors! Use the .shutdown() method on the NVML struct if you care about handling them.

fn drop(&mut self)

A method called when the value goes out of scope.