GPU access API: Library (safety subset)

Detailed Description

Data Structures
struct	NvRmGpuLibVersionInfoRec
	The version information structure returned by NvRmGpuLibGetVersionInfo(). More...
struct	NvRmGpuLibOpenAttrRec
	Extensible attribute structure for NvRmGpuLibOpen() More...
struct	NvRmGpuLibDeviceListEntryRec
	Device list entry. More...

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

Typedefs
typedef struct NvRmGpuLibRec	NvRmGpuLib
	Library handle. More...
typedef struct NvRmGpuLibVersionInfoRec	NvRmGpuLibVersionInfo
	The version information structure returned by NvRmGpuLibGetVersionInfo(). 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_InsufficientPrivileges,   NvRmGpuLibDeviceState_Unknown }
	Device attachment state. More...

Functions
const NvRmGpuLibVersionInfo *	NvRmGpuLibGetVersionInfo (void)
	Returns the library version information. More...
NvRmGpuLib *	NvRmGpuLibOpen (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 NvRmGpuLibDeviceListEntry *	NvRmGpuLibListDevices (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

)

NvRmGpuLibOpenAttr x = { 0U }

Definer macro for NvRmGpuLibOpenAttr.

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

Definition at line 452 of file nvrm_gpu.h.

Typedef Documentation

NvRmGpuLib

typedef struct NvRmGpuLibRec NvRmGpuLib

Library handle.

See also

NvRmGpuLibOpen()

NvRmGpuLibGetInfo()

NvRmGpuLibClose()

Definition at line 336 of file nvrm_gpu.h.

NvRmGpuLibDeviceListEntry

typedef struct NvRmGpuLibDeviceListEntryRec NvRmGpuLibDeviceListEntry

Device list entry.

See also

NvRmGpuLibListDevices()

NvRmGpuLibOpenAttr

typedef struct NvRmGpuLibOpenAttrRec 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()

NvRmGpuLibVersionInfo

typedef struct NvRmGpuLibVersionInfoRec NvRmGpuLibVersionInfo

The version information structure returned by NvRmGpuLibGetVersionInfo().

Since

0.1.0

Enumeration Type Documentation

NvRmGpuLibDeviceState

enum NvRmGpuLibDeviceState

Device attachment state.

See also

NvRmGpuLibListDevices(), NvRmGpuLibDeviceListEntry

NvRmGpuDeviceOpen()

Enumerator
NvRmGpuLibDeviceState_Attached	Device is attached and may be opened with NvRmGpuDeviceOpen()
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 569 of file nvrm_gpu.h.

Function Documentation

NvRmGpuLibClose()

NvError NvRmGpuLibClose

(

NvRmGpuLib *

hLib

)

Closes the library and releases all resources.

Parameters

[in]

hLib

Library handle. May be NULL, in which case this function is a no-op.

Returns

The usual NvError code

Return values

NvSuccess	The 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.

See also

NvRmGpuLibOpen()

NvRmGpuDeviceClose()

Precondition

Library is opened successfully and all resources originating from the library are closed.

Usage considerations

• Allowed context for the API call
  • Thread-safe: Yes, with the following conditions:
    • No concurrent operations on the Library object ongoing in other threads.
  • Interrupt handler: No
  • Signal handler: No
  • Re-entrant: Yes
  • Async/Sync: Sync
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: Yes

NvRmGpuLibGetVersionInfo()

const NvRmGpuLibVersionInfo* NvRmGpuLibGetVersionInfo

(

void

)

Returns the library version information.

Remarks

This function may be called without opening the library.

This function is guaranteed to never break backwards compatibility, making it safe to call with the dlopen()/dlsym() pattern.

Since

0.1.0

Precondition

None.

Usage considerations

• Allowed context for the API call
  • Thread-safe: Yes
  • Interrupt handler: No
  • Signal handler: No
  • Re-entrant: Yes
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: Yes

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]	hLib	Library handle
[out]	pNumDevices	Non-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()

Precondition

Library is opened successfully.

Usage considerations

• Allowed context for the API call
  • Thread-safe: Yes
  • Interrupt handler: No
  • Signal handler: No
  • Re-entrant: Yes
  • Async/Sync: Sync
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No

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]

attr

Extensible 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()

Precondition

None.

Usage considerations

• Allowed context for the API call
  • Thread-safe: Yes
  • Interrupt handler: No
  • Signal handler: No
  • Re-entrant: Yes
  • Async/Sync: Sync
• Required privileges: None
• API group
  • Init: Yes
  • Runtime: No
  • De-Init: No