NVIDIA DRIVE OS Linux SDK API Reference

5.2.3 Release
For Test and Development only
GPU access API: Library (safety subset)

Detailed Description

Data Structures

struct  NvRmGpuLibOpenAttrRec
 Extensible attribute structure for NvRmGpuLibOpen() More...
 
struct  NvRmGpuLibDeviceListEntryRec
 Device list entry. More...
 

Macros

#define NVRM_GPU_DEFINE_LIB_OPEN_ATTR(x)   NVRM_GPU_ATTR_NAMESPACE(NvRmGpuLibOpenAttr) x = { 0U }
 Definer macro for NvRmGpuLibOpenAttr. More...
 

Typedefs

typedef struct NvRmGpuLibRec NvRmGpuLib
 Library handle. More...
 
typedef struct NvRmGpuLibOpenAttrRec NvRmGpuLibOpenAttr
 Extensible attribute structure for NvRmGpuLibOpen() More...
 
typedef struct NvRmGpuLibDeviceListEntryRec NvRmGpuLibDeviceListEntry
 Device list entry. More...
 

Enumerations

enum  NvRmGpuLibDeviceState {
  NvRmGpuLibDeviceState_Attached,
  NvRmGpuLibDeviceState_Detached,
  NvRmGpuLibDeviceState_InsufficientPrivileges,
  NvRmGpuLibDeviceState_Unknown
}
 Device attachment state. More...
 

Functions

NvRmGpuLibNvRmGpuLibOpen (const NvRmGpuLibOpenAttr *attr)
 Opens a new instance of the nvrm_gpu library. More...
 
NvError NvRmGpuLibClose (NvRmGpuLib *hLib)
 Closes the library and releases all resources. More...
 
const NvRmGpuLibDeviceListEntryNvRmGpuLibListDevices (NvRmGpuLib *hLib, size_t *pNumDevices)
 Returns the list of probed GPUs. More...
 

Macro Definition Documentation

◆ NVRM_GPU_DEFINE_LIB_OPEN_ATTR

#define NVRM_GPU_DEFINE_LIB_OPEN_ATTR (   x)    NVRM_GPU_ATTR_NAMESPACE(NvRmGpuLibOpenAttr) x = { 0U }

Definer macro for NvRmGpuLibOpenAttr.

This macro defines a variable of type NvRmGpuLibOpenAttr with the default values.

Definition at line 177 of file nvrm_gpu.h.

Typedef Documentation

◆ NvRmGpuLib

typedef struct NvRmGpuLibRec NvRmGpuLib

Library handle.

See also
NvRmGpuLibOpen()
NvRmGpuLibGetInfo()
NvRmGpuLibClose()

Definition at line 124 of file nvrm_gpu.h.

◆ NvRmGpuLibDeviceListEntry

◆ NvRmGpuLibOpenAttr

Extensible attribute structure for NvRmGpuLibOpen()

This structure specifies the attributes for opening the nvrm_gpu library. Use NVRM_GPU_DEFINE_LIB_OPEN_ATTR() to define the attribute struct with defaults.

Example:

// define libOpenAttr with default values
NVRM_GPU_DEFINE_LIB_OPEN_ATTR(libOpenAttr);

// open the library
NvRmGpuLib *hLib = NvRmGpuLibOpen(&libOpenAttr);
See also
NvRmGpuLibOpen()

Enumeration Type Documentation

◆ NvRmGpuLibDeviceState

Device attachment state.

See also
NvRmGpuLibListDevices(), NvRmGpuLibDeviceListEntry
NvRmGpuDeviceOpen()
NvRmGpuLibAttachDevice(), NvRmGpuLibDetachDevice()
Enumerator
NvRmGpuLibDeviceState_Attached 

Device is attached and may be opened with NvRmGpuDeviceOpen()

NvRmGpuLibDeviceState_Detached 

Device is detached and powered off.

Device must be attached before it can be opened.

NvRmGpuLibDeviceState_InsufficientPrivileges 

Device exists, but not enough privileges to access.

NvRmGpuLibDeviceState_Unknown 

Device state is not known.

Prober failed to determine device state.

Definition at line 267 of file nvrm_gpu.h.

Function Documentation

◆ NvRmGpuLibClose()

NvError NvRmGpuLibClose ( NvRmGpuLib hLib)

Closes the library and releases all resources.

Parameters
[in]hLibLibrary handle. May be NULL, in which case this function is a no-op.
Returns
The usual NvError code
Return values
NvSuccessThe library was closed and all related resources were freed successfully
NvError_*Unspecified error. The error code is returned for diagnostic purposes. The library object is closed regardless but some resources may have failed to close gracefully.
Remarks
Every resource attached to the library must be closed before closing the library to avoid leaks and dangling pointers. In debug builds, nvrm_gpu will keep track of the associated resource and it will assert in case this contract is violated.
See also
NvRmGpuLibOpen()
NvRmGpuDeviceClose()

◆ NvRmGpuLibListDevices()

const NvRmGpuLibDeviceListEntry* NvRmGpuLibListDevices ( NvRmGpuLib hLib,
size_t *  pNumDevices 
)

Returns the list of probed GPUs.

Returns the list of probed GPUs. The list is valid until the library handle is closed.

Parameters
[in]hLibLibrary handle
[out]pNumDevicesNon-NULL Pointer to receive the number of entries in the list
Returns
Pointer to the list of probed GPUs (C array). The caller must not attempt to free the pointer.
Remarks
The first device listed is considered the primary GPU.
The device index numbers returned are non-negative, unique and in ascending order. Numbering may be discontiguous, and specifically, the index numbers will likely not start at 0.
See also
NvRmGpuDeviceOpen()
NvRmGpuLibAttachDevice()
NvRmGpuLibDetachDevice()

◆ NvRmGpuLibOpen()

NvRmGpuLib* NvRmGpuLibOpen ( const NvRmGpuLibOpenAttr attr)

Opens a new instance of the nvrm_gpu library.

This function creates a new library handle and initializes the library if necessary. After the library is no longer used, the library handle should be closed with NvRmGpuLibClose() to avoid memory leaks.

Parameters
[in]attrExtensible library open attributes, or NULL for defaults. Currently unused.
Returns
Library handle, or NULL if the library could not be initialized.
Remarks
There can be multiple concurrent instances of the library in the process. Global shared data used by the library is internally reference counted: the first instance will initialize the shared resources; and when the last instance is closed, the shared resources are freed.
If the library initialization fails, an error message is printed on stderr with an error code for diagnostics.

Example:

// open the library
NvRmGpuLib *hLib = NvRmGpuLibOpen(NULL);

if (hLib != NULL)
{
    NvRmGpuDevice *hDevice = NULL;
    NvError err;

    err = NvRmGpuDeviceOpen(hLib, NVRM_GPU_DEVICE_INDEX_DEFAULT, NULL, &hDevice);
    if (err == NvSuccess)
    {
        // use the device
        ...

        // all done, close the device
        NvRmGpuDeviceClose(hDevice);
    }
    else
    {
        // deal with the error
    }

    /// all done, close the library
    NvRmGpuLibClose(hLib);
}
else
{
    // deal with the error
}
See also
NvRmGpuLibClose()