NVIDIA DRIVE OS Linux SDK API Reference

5.2.3 Release
For Test and Development only

Detailed Description

NvMedia DLA runtime APIs for accessing the DLA hardware engine for deep learning operations.

Modules

 DLA Specific Types
 Defines specific types for DLA.
 

Macros

#define NVMEDIA_DLA_VERSION_MAJOR   3
 Major version number. More...
 
#define NVMEDIA_DLA_VERSION_MINOR   6
 Minor version number. More...
 

Functions

NvMediaStatus NvMediaDlaGetVersion (NvMediaVersion *version)
 Returns the version information for the NvMediaDla library. More...
 
NvMediaStatus NvMediaDlaPingById (const uint32_t dlaId)
 Checks the status of the DLA engine. More...
 
NvMediaDlaNvMediaDlaCreate (void)
 Creates a default context for NvMediaDla. More...
 
NvMediaStatus NvMediaDlaDestroy (NvMediaDla *dla)
 Destroys a DLA engine instance created by NvMediaDlaCreate(). More...
 
NvMediaStatus NvMediaDlaGetUMDVersion (const NvMediaDla *dla, NvMediaDlaUMDVersion *version)
 Returns the version information for the NvMedia DLA UMD library. More...
 
NvMediaStatus NvMediaDlaGetNumEngines (const NvMediaDla *dla, uint16_t *numEngines)
 Returns the number of DLA hardware engines available. More...
 
NvMediaStatus NvMediaDlaGetMaxOutstandingTasks (const NvMediaDla *dla, uint32_t *maxOutstandingTasks)
 Returns the maximum number of tasks that can be queued to an instance of an engine. More...
 
NvMediaStatus NvMediaDlaInit (NvMediaDla *dla, uint32_t dlaId, uint32_t numTasks)
 Configures the context for a particular DLA engine. More...
 
NvMediaStatus NvMediaDlaGetInstanceId (const NvMediaDla *dla, uint32_t *dlaId)
 Returns the instance id of the NvMediaDla. More...
 
NvMediaStatus NvMediaDlaGetNumTasks (const NvMediaDla *dla, uint32_t *numTasks)
 Returns the number of outstanding tasks of NvMediaDla. More...
 
NvMediaStatus NvMediaDlaLoadableCreate (NvMediaDla *dla, NvMediaDlaLoadable **loadable)
 Creates a loadable handle. More...
 
NvMediaStatus NvMediaDlaLoadableDestroy (const NvMediaDla *dla, NvMediaDlaLoadable *loadable)
 Destroys a loadable handle. More...
 
NvMediaStatus NvMediaDlaAppendLoadable (const NvMediaDla *dla, const NvMediaDlaBinaryLoadable binaryLoadable, NvMediaDlaLoadable *loadable)
 Appends a loadable to the NvMediaDla context. More...
 
NvMediaStatus NvMediaDlaSetCurrentLoadable (NvMediaDla *dla, const NvMediaDlaLoadable *loadable)
 Sets the current loadable for the NvMediaDla. More...
 
NvMediaStatus NvMediaDlaGetNumOfInputTensors (const NvMediaDla *dla, int32_t *numOfInputTensors)
 Gets the number of input tensors for the current loadable in the NvMediaDla context. More...
 
NvMediaStatus NvMediaDlaGetInputTensorDescriptor (const NvMediaDla *dla, const uint32_t idx, NvMediaDlaTensorDescriptor *descriptor)
 Gets the input tensor descriptor for the current loadable in the NvMediaDla context. More...
 
NvMediaStatus NvMediaDlaGetNumOfOutputTensors (const NvMediaDla *dla, int32_t *numOfOutputTensors)
 Gets the number of output tensors for the current loadable in the NvMediaDla context. More...
 
NvMediaStatus NvMediaDlaGetOutputTensorDescriptor (const NvMediaDla *dla, const uint32_t idx, NvMediaDlaTensorDescriptor *descriptor)
 Gets the output tensor descriptor for the current loadable in the NvMediaDla context. More...
 
NvMediaStatus NvMediaDlaDataRegister (const NvMediaDla *dla, const NvMediaDlaData *dlaData, uint32_t flags)
 Registers an NvMediaDlaData for use with an NvMediaDla handle. More...
 
NvMediaStatus NvMediaDlaDataUnregister (const NvMediaDla *dla, const NvMediaDlaData *dlaData)
 Unregisters an NvMediaDlaData after use. More...
 
NvMediaStatus NvMediaDlaLoadLoadable (NvMediaDla *dla)
 Loads the current loadable to the provided NvMediaDla context. More...
 
NvMediaStatus NvMediaDlaRemoveLoadable (NvMediaDla *dla)
 Removes the current loadable from the provided NvMediaDla context. More...
 
NvMediaStatus NvMediaDlaSubmit (NvMediaDla *dla, const NvMediaDlaArgs *inputArgs, const NvMediaDlaArgs *scratchpadArgs, const NvMediaDlaArgs *outputArgs, uint32_t taskTimeout)
 Submits a job to the DLA to run the network on a set of input NvMediaDla arguments and a timeout value. More...
 

Macro Definition Documentation

◆ NVMEDIA_DLA_VERSION_MAJOR

#define NVMEDIA_DLA_VERSION_MAJOR   3

Major version number.

Definition at line 47 of file nvmedia_dla.h.

◆ NVMEDIA_DLA_VERSION_MINOR

#define NVMEDIA_DLA_VERSION_MINOR   6

Minor version number.

Definition at line 49 of file nvmedia_dla.h.

Function Documentation

◆ NvMediaDlaAppendLoadable()

NvMediaStatus NvMediaDlaAppendLoadable ( const NvMediaDla dla,
const NvMediaDlaBinaryLoadable  binaryLoadable,
NvMediaDlaLoadable loadable 
)

Appends a loadable to the NvMediaDla context.

NvMediaDlaLoadLoadable() appends the value in loadable and returns to the calling function. Currently, only one loadable can be appended.

The application may call this function only once.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]binaryLoadableHolds a non-null pointer to NvMediaDlaBinaryLoadable.
Input range: The loadableSize must be greater than 0.
[in,out]loadableA pointer to an NvMediaDlaLoadable filled by NvMediaDla.
Input range: A non-null pointer to an NvMediaDlaLoadable.
Output range: A non-null pointer to a valid loadable if successful.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaCreate()

NvMediaDla* NvMediaDlaCreate ( void  )

Creates a default context for NvMediaDla.

Use the function NvMediaDlaInit() to initialize the newly-created context for use as an engine instance.

Returns
NvMediaDla A handle to the context.
Output range: A non-null pointer to an NvMediaDla if successful, or NULL otherwise.

◆ NvMediaDlaDataRegister()

NvMediaStatus NvMediaDlaDataRegister ( const NvMediaDla dla,
const NvMediaDlaData dlaData,
uint32_t  flags 
)

Registers an NvMediaDlaData for use with an NvMediaDla handle.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]dlaDataA pointer to NvMediaDlaData to register.
Input range: A non-null pointer to an NvMediaDlaData.
[in]flagsReserved for future use. Should be set to zero.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaDataUnregister()

NvMediaStatus NvMediaDlaDataUnregister ( const NvMediaDla dla,
const NvMediaDlaData dlaData 
)

Unregisters an NvMediaDlaData after use.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]dlaDataA pointer to a registered NvMediaDlaData.
Input range: A non-null pointer to an NvMediaDlaData registered with NvMediaDlaDataRegister().
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaDestroy()

NvMediaStatus NvMediaDlaDestroy ( NvMediaDla dla)

Destroys a DLA engine instance created by NvMediaDlaCreate().

Parameters
[in]dlaA handle to the instance to destroy.
Input range: A non-null pointer to an NvMediaDla instance created with NvMediaDlaCreate().
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetInputTensorDescriptor()

NvMediaStatus NvMediaDlaGetInputTensorDescriptor ( const NvMediaDla dla,
const uint32_t  idx,
NvMediaDlaTensorDescriptor descriptor 
)

Gets the input tensor descriptor for the current loadable in the NvMediaDla context.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]idxA tensor index.
Input range: A value between 0 (zero) and the result of NvMediaDlaGetNumOfInputTensors() - 1.
[in,out]descriptorDescriptor for the tensor.
Input range: A non-null pointer to an NvMediaDlaTensorDescriptor.
Output range: A non-null pointer to an NvMediaDlaTensorDescriptor if successful.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetInstanceId()

NvMediaStatus NvMediaDlaGetInstanceId ( const NvMediaDla dla,
uint32_t *  dlaId 
)

Returns the instance id of the NvMediaDla.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in,out]dlaIdA pointer to the NvMediaDla instance id.
Input range: A non-null pointer to an uint32_t.
Output range: A non-null pointer to an uint32_t between 0 (zero) and the result of NvMediaDlaGetNumEngines() - 1 if successful.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetMaxOutstandingTasks()

NvMediaStatus NvMediaDlaGetMaxOutstandingTasks ( const NvMediaDla dla,
uint32_t *  maxOutstandingTasks 
)

Returns the maximum number of tasks that can be queued to an instance of an engine.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in,out]maxOutstandingTasksA pointer to the maximum number of tasks that can be queued.
Input range: A non-null pointer to an uint32_t.
Output range: A non-null pointer to an uint32_t if successful, otherwise the value pointed to by numEngines remains unchanged.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetNumEngines()

NvMediaStatus NvMediaDlaGetNumEngines ( const NvMediaDla dla,
uint16_t *  numEngines 
)

Returns the number of DLA hardware engines available.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer an NvMediaDla instance created with NvMediaDlaCreate().
[in,out]numEnginesA pointer to the number of DLA hardware engines.
Input range: A non-null pointer to an uint16_t.
Output range: A non-null pointer to an uint16_t if successful, otherwise the value pointed to by numEngines remains unchanged.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetNumOfInputTensors()

NvMediaStatus NvMediaDlaGetNumOfInputTensors ( const NvMediaDla dla,
int32_t *  numOfInputTensors 
)

Gets the number of input tensors for the current loadable in the NvMediaDla context.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in,out]numOfInputTensorsThe number of input tensors.
Input range: A non-null pointer to an int32_t value.
Output range: A non-null pointer to an int32_t if successful.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetNumOfOutputTensors()

NvMediaStatus NvMediaDlaGetNumOfOutputTensors ( const NvMediaDla dla,
int32_t *  numOfOutputTensors 
)

Gets the number of output tensors for the current loadable in the NvMediaDla context.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in,out]numOfOutputTensorsThe number of output tensors.
Input range: A non-null pointer to an int32_t value.
Output range: A non-null pointer to an int32_t value if successful.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetNumTasks()

NvMediaStatus NvMediaDlaGetNumTasks ( const NvMediaDla dla,
uint32_t *  numTasks 
)

Returns the number of outstanding tasks of NvMediaDla.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in,out]numTasksA pointer to the number of outstanding tasks.
Input range: A non-null pointer to an uint32_t.
Output range: A non-null pointer to an uint32_t between 0 (zero) and the result of NvMediaDlaGetMaxOutstandingTasks() if successful.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetOutputTensorDescriptor()

NvMediaStatus NvMediaDlaGetOutputTensorDescriptor ( const NvMediaDla dla,
const uint32_t  idx,
NvMediaDlaTensorDescriptor descriptor 
)

Gets the output tensor descriptor for the current loadable in the NvMediaDla context.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]idxThe tensor index.
Input range: A value between 0 (zero) and the result of NvMediaDlaGetNumOfOutputTensors() - 1.
[in,out]descriptorA descriptor for the tensor.
Input range: A non-null pointer to an NvMediaDlaTensorDescriptor.
Output range: A non-null pointer to an NvMediaDlaTensorDescriptor if successful.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetUMDVersion()

NvMediaStatus NvMediaDlaGetUMDVersion ( const NvMediaDla dla,
NvMediaDlaUMDVersion version 
)

Returns the version information for the NvMedia DLA UMD library.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla instance created with NvMediaDlaCreate().
[in,out]versionA pointer to an NvMediaDlaUMDVersion structure filled by the NvMediaDla library.
Input range: A non-null pointer to an NvMediaDlaUMDVersion.
Output range: A non-null pointer to an NvMediaDlaUMDVersion if successful, otherwise the value pointed to by version remains unchanged.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaGetVersion()

NvMediaStatus NvMediaDlaGetVersion ( NvMediaVersion version)

Returns the version information for the NvMediaDla library.

Parameters
[in,out]versionA pointer to an NvMediaVersion structure filled by the NvMediaDla library.
Input range: A non-null pointer to an NvMediaVersion structure.
Output range: A non-null pointer to an NvMediaVersion structure if successful, otherwise the value pointed to by version remains unchanged.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaInit()

NvMediaStatus NvMediaDlaInit ( NvMediaDla dla,
uint32_t  dlaId,
uint32_t  numTasks 
)

Configures the context for a particular DLA engine.

Note
Once the dlaId and numTasks have been assigned, their values cannot be modified.
Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]dlaIdThe DLA engine ID.
Input range: An uint32_t value between 0 (zero) and the result of NvMediaDlaGetNumEngines() - 1.
[in]numTasksThe number of simultaneous tasks that can be submitted to a DLA instance at a time.
Input range: An uint32_t value between 1 and the result of NvMediaDlaGetMaxOutstandingTasks().
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaLoadableCreate()

NvMediaStatus NvMediaDlaLoadableCreate ( NvMediaDla dla,
NvMediaDlaLoadable **  loadable 
)

Creates a loadable handle.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in,out]loadableA pointer to an NvMediaDlaLoadable.
Input range: A non-null pointer to an NvMediaDlaLoadable.
Output range: A non-null pointer to a valid loadable if successful.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaLoadableDestroy()

NvMediaStatus NvMediaDlaLoadableDestroy ( const NvMediaDla dla,
NvMediaDlaLoadable loadable 
)

Destroys a loadable handle.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]loadableA pointer to an NvMediaDlaLoadable.
Input range: A non-null pointer to an NvMediaDlaLoadable created with NvMediaDlaLoadableCreate().
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaLoadLoadable()

NvMediaStatus NvMediaDlaLoadLoadable ( NvMediaDla dla)

Loads the current loadable to the provided NvMediaDla context.

The loadable can be made current by calling NvMediaDlaSetCurrentLoadable().

Parameters
[in]dlaA handle to the DLA device.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaPingById()

NvMediaStatus NvMediaDlaPingById ( const uint32_t  dlaId)

Checks the status of the DLA engine.

This function sends a ping to the DLA engine identified by dlaId to fetch its status.

Parameters
[in]dlaIdId of the DLA engine to ping.
Input range: An uint32_t value between 0 (zero) and the result of NvMediaDlaGetNumEngines() - 1.
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaRemoveLoadable()

NvMediaStatus NvMediaDlaRemoveLoadable ( NvMediaDla dla)

Removes the current loadable from the provided NvMediaDla context.

The loadable can be made current by calling NvMediaDlaSetCurrentLoadable().

This function must be called after a call to NvMediaDlaLoadLoadable().

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaSetCurrentLoadable()

NvMediaStatus NvMediaDlaSetCurrentLoadable ( NvMediaDla dla,
const NvMediaDlaLoadable loadable 
)

Sets the current loadable for the NvMediaDla.

Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]loadableA pointer to an NvMediaDlaLoadable.
Input range: A non-null pointer to an NvMediaDlaLoadable created with NvMediaDlaLoadableCreate().
Returns
NvMediaStatus, the completion status of the operation:

◆ NvMediaDlaSubmit()

NvMediaStatus NvMediaDlaSubmit ( NvMediaDla dla,
const NvMediaDlaArgs inputArgs,
const NvMediaDlaArgs scratchpadArgs,
const NvMediaDlaArgs outputArgs,
uint32_t  taskTimeout 
)

Submits a job to the DLA to run the network on a set of input NvMediaDla arguments and a timeout value.

Note
The scratchpadArgs parameter is currently not supported. The application must pass a NULL in this argument.
Parameters
[in]dlaA handle to the DLA context.
Input range: A non-null pointer to an NvMediaDla created with NvMediaDlaCreate().
[in]inputArgsA pointer to input NvMediaDlaArgs.
Input range: A non-null pointer to a valid NvMediaDlaArgs. A valid NvMediaDlaArgs should meet the following restrictions:
[in]scratchpadArgsA pointer to scratchpad arguments for NvMediaDla.
Input range: A NULL value. This parameter is currently not supported. The application must pass NULL in this argument.
[in]outputArgsHolds output NvMediaDlaArgs.
Input range: A non-null pointer to a valid NvMediaDlaArgs. A valid NvMediaDlaArgs should meet the following restrictions:
  • NvMediaDlaArgs should hold a non-NULL NvMediaDlaData.
  • NvMediaDlaDataType of NvMediaDlaData shall be equal to NVMEDIA_DLA_DATA_TYPE_TENSOR.
  • NvMediaDlaDataPointer of NvMediaDlaData shall be non-NULL.
  • NvMediaTensor of NvMediaDlaDataPointer shall match the tensor descriptor that is queried by NvMediaDlaGetOutputTensorDescriptor.
  • numArgs of NvMediaDlaArgs shall be equal to number of tensors queried by NvMediaDlaGetNumOfOutputTensors.
[in]taskTimeoutThe maximum time allocated for completing the task (in milliseconds).
Input range: The valid range is from 1 millisecond to 1000000 milliseconds. The value 0 (zero) is mapped to 1000000 milliseconds.

The task will error out if it does not finish within the time set in taskTimeout. Error details can be obtained using NvMediaTensorGetStatus() for input/output tensors.

Returns
NvMediaStatus, the completion status of the operation: