Detailed Description

The Tensor Processing API encompasses all NvMedia tensor related functionality.

Data Structures
struct	NvMediaTensorTaskStatus
	Holds the status of the latest operation for a tensor. More...

struct	NvMediaTensorAttr
	Holds tensor creation attributes. More...

struct	NvMediaTensorSurfaceMap
	Defines the tensor surface map descriptor used by NvMediaTensorLock(). More...

Macros
#define	NVMEDIA_TENSOR_VERSION_MAJOR (1u)
	Major version number. More...

#define	NVMEDIA_TENSOR_VERSION_MINOR (13u)
	Minor version number. More...

#define	NVMEDIA_TENSOR_VERSION_PATCH (0u)
	Patch version number. More...

#define	NVMTENSOR_4D_MAX_N (65536u)
	Defines the maximum supported number of tensor surfaces. More...

#define	NVMTENSOR_4D_MAX_C (8192u)
	Defines the maximum supported number of channels of a 4D tensor. More...

#define	NVMTENSOR_4D_MAX_H (8192u)
	Defines the maximum supported height of a 4D tensor. More...

#define	NVMTENSOR_4D_MAX_W (8192u)
	Defines the maximum supported width of a 4D tensor. More...

#define	NVMTENSOR_4D_MAX_X (1024u)
	Defines the maximum supported x value of a 4D tensor. More...

#define	NVMEDIA_TENSOR_TIMEOUT_INFINITE
	This macro tells NvMediaTensorGetStatus() and NvMediaTensorLock() APIs to block infinitely till the operation finishes. More...

#define	NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED (0x00000001u)
	Specifies that the tensor CPU accesses are uncached. More...

#define	NVM_TENSOR_ATTR_CPU_ACCESS_CACHED (0x00000002u)
	Specifies that the tensor CPU accesses are cacheable. More...

#define	NVM_TENSOR_ATTR_CPU_ACCESS_UNMAPPED (0x00000003u)
	Specifies that the tensor CPU accesses are unmapped from the virtual address space of the current process. More...

#define	NVM_TENSOR_ATTR_ALLOC_NONE (0x00000000u)
	Specifies that the tensor allocation is on Soc DRAM. More...

#define	NVM_TENSOR_INIT_ATTR(x)
	A helper macro to initialize tensor creation attributes. More...

#define	NVM_TENSOR_DEFINE_ATTR(x)
	A helper macro to define tensor creation attributes. More...

#define	NVM_TENSOR_SET_ATTR_4D(attr, N, C, H, W, order, datatype, bpe, accesstype, alloctype, X)
	A helper macro to set 4-D tensor creation attributes. More...

Typedefs
typedef struct NvMediaTensor	NvMediaTensor
	A handle representing tensor objects. More...

Enumerations
enum	NvMediaTensorAttrType { NVM_TENSOR_ATTR_DATA_TYPE = 0, NVM_TENSOR_ATTR_BITS_PER_ELEMENT, NVM_TENSOR_ATTR_DIMENSION_ORDER, NVM_TENSOR_ATTR_CPU_ACCESS, NVM_TENSOR_ATTR_ALLOC_TYPE, NVM_TENSOR_ATTR_4D_N, NVM_TENSOR_ATTR_4D_C, NVM_TENSOR_ATTR_4D_H, NVM_TENSOR_ATTR_4D_W, NVM_TENSOR_ATTR_4D_X, NVM_TENSOR_ATTR_MAX }
	Defines attribute types for creating NvMedia Tensor. More...

enum	NvMediaTensorLockAccess { NVMEDIA_TENSOR_ACCESS_READ = (1 << 0), NVMEDIA_TENSOR_ACCESS_WRITE = (1 << 1), NVMEDIA_TENSOR_ACCESS_READ_WRITE = (NVMEDIA_TENSOR_ACCESS_READ \| NVMEDIA_TENSOR_ACCESS_WRITE) }
	Defines tensor lock access types. More...

Functions
void	NvMediaTensorDestroy (NvMediaTensor *tensor)
	Destroys a tensor object previously created by NvMediaTensorCreateFromNvSciBuf(). More...

NvMediaStatus	NvMediaTensorLock (NvMediaTensor tensor, NvMediaTensorLockAccess lockAccessType, NvMediaTensorSurfaceMap surfaceMap)
	Locks a tensor and returns the associated mapped pointers pointing to the tensor surface data. More...

void	NvMediaTensorUnlock (NvMediaTensor *tensor)
	Unlocks a tensor. More...

NvMediaStatus	NvMediaTensorGetStatus (NvMediaTensor tensor, uint32_t millisecondWait, NvMediaTensorTaskStatus status)
	Gets the status of the last operation for the tensor, and optionally waits for the operation to complete or time out. More...

NvMediaStatus	NvMediaTensorGetMetaData (const NvMediaTensor tensor, NvMediaTensorMetaData tensormetadata)
	Fills in the metadata information for the tensor. More...

NvMediaStatus	NvMediaTensorGetVersion (NvMediaVersion *version)
	Returns version information for the NvMediaTensor library. More...

Macro Definition Documentation

◆ NVM_TENSOR_ATTR_ALLOC_NONE

#define NVM_TENSOR_ATTR_ALLOC_NONE (0x00000000u)

Specifies that the tensor allocation is on Soc DRAM.

Definition at line 150 of file nvmedia_tensor.h.

◆ NVM_TENSOR_ATTR_CPU_ACCESS_CACHED

#define NVM_TENSOR_ATTR_CPU_ACCESS_CACHED (0x00000002u)

Specifies that the tensor CPU accesses are cacheable.

In this case, the tensor memory will be mapped and can be accessed with a mapping into the current process's virtual address space.

Definition at line 132 of file nvmedia_tensor.h.

◆ NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED

#define NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED (0x00000001u)

Specifies that the tensor CPU accesses are uncached.

In this case, the tensor memory will be mapped and can be accessed with a mapping into the current process's virtual address space.

Definition at line 126 of file nvmedia_tensor.h.

◆ NVM_TENSOR_ATTR_CPU_ACCESS_UNMAPPED

#define NVM_TENSOR_ATTR_CPU_ACCESS_UNMAPPED (0x00000003u)

Specifies that the tensor CPU accesses are unmapped from the virtual address space of the current process.

Definition at line 137 of file nvmedia_tensor.h.

◆ NVM_TENSOR_DEFINE_ATTR

#define NVM_TENSOR_DEFINE_ATTR ( x )

Value:

NvMediaTensorAttr x[NVM_TENSOR_ATTR_MAX]; \

NVM_TENSOR_INIT_ATTR(x); \

A helper macro to define tensor creation attributes.

Definition at line 202 of file nvmedia_tensor.h.

◆ NVM_TENSOR_INIT_ATTR

#define NVM_TENSOR_INIT_ATTR ( x )

A helper macro to initialize tensor creation attributes.

Parameters

x	The array to initialize with tensor creation attributes.

Definition at line 166 of file nvmedia_tensor.h.

◆ NVM_TENSOR_SET_ATTR_4D

#define NVM_TENSOR_SET_ATTR_4D	(	attr,
		N,
		C,
		H,
		W,
		order,
		datatype,
		bpe,
		accesstype,
		alloctype,
		X
	)

A helper macro to set 4-D tensor creation attributes.

The attr parameter must be defined before setting the values using NVM_TENSOR_SET_ATTR_4D. For example, to set the attributes for NCHW 4-D FP16 tensor:

NVM_TENSOR_SET_ATTR_4D(attr, N, C, H, W, NCHW, FLOAT, 16, UNCACHED, NONE, 32);

Parameters

attr	The attribute to set.
N	A tensor layout dimension for number of surfaces.
C	A tensor layout dimension for number of channels on the surface.
H	A tensor layout dimension for the height of the surface.
W	A tensor layout dimension for the width of the surface.
order	The order of the tensor elements.
datatype	The datatype for this tensor.
bpe	Specifies the bits per element.
accesstype	Specifies the access type.
alloctype	Specifies the allocation type.
X	A tensor layout dimension for X.

Definition at line 228 of file nvmedia_tensor.h.

◆ NVMEDIA_TENSOR_TIMEOUT_INFINITE

#define NVMEDIA_TENSOR_TIMEOUT_INFINITE

This macro tells NvMediaTensorGetStatus() and NvMediaTensorLock() APIs to block infinitely till the operation finishes.

Definition at line 72 of file nvmedia_tensor.h.

◆ NVMEDIA_TENSOR_VERSION_MAJOR

#define NVMEDIA_TENSOR_VERSION_MAJOR (1u)

Major version number.

Definition at line 50 of file nvmedia_tensor.h.

◆ NVMEDIA_TENSOR_VERSION_MINOR

#define NVMEDIA_TENSOR_VERSION_MINOR (13u)

Minor version number.

Definition at line 52 of file nvmedia_tensor.h.

◆ NVMEDIA_TENSOR_VERSION_PATCH

#define NVMEDIA_TENSOR_VERSION_PATCH (0u)

Patch version number.

Definition at line 54 of file nvmedia_tensor.h.

◆ NVMTENSOR_4D_MAX_C

#define NVMTENSOR_4D_MAX_C (8192u)

Defines the maximum supported number of channels of a 4D tensor.

Definition at line 59 of file nvmedia_tensor.h.

◆ NVMTENSOR_4D_MAX_H

#define NVMTENSOR_4D_MAX_H (8192u)

Defines the maximum supported height of a 4D tensor.

Definition at line 61 of file nvmedia_tensor.h.

◆ NVMTENSOR_4D_MAX_N

#define NVMTENSOR_4D_MAX_N (65536u)

Defines the maximum supported number of tensor surfaces.

Definition at line 57 of file nvmedia_tensor.h.

◆ NVMTENSOR_4D_MAX_W

#define NVMTENSOR_4D_MAX_W (8192u)

Defines the maximum supported width of a 4D tensor.

Definition at line 63 of file nvmedia_tensor.h.

◆ NVMTENSOR_4D_MAX_X

#define NVMTENSOR_4D_MAX_X (1024u)

Defines the maximum supported x value of a 4D tensor.

This value is only for NCxHWx order.

Definition at line 65 of file nvmedia_tensor.h.

Typedef Documentation

◆ NvMediaTensor

typedef struct NvMediaTensor NvMediaTensor

A handle representing tensor objects.

Definition at line 88 of file nvmedia_tensor.h.

Enumeration Type Documentation

◆ NvMediaTensorAttrType

enum NvMediaTensorAttrType

Defines attribute types for creating NvMedia Tensor.

The maximum supported NvMediaTensor size is (UINT32_MAX) = 4294967295 bytes.

Enumerator
NVM_TENSOR_ATTR_DATA_TYPE	Specifies the tensor data type.
NVM_TENSOR_ATTR_BITS_PER_ELEMENT	Defines the tensor bits per element.
NVM_TENSOR_ATTR_DIMENSION_ORDER	Defines the tensor dimension order.
NVM_TENSOR_ATTR_CPU_ACCESS	Defines the CPU access to tensor. (default: uncached)
NVM_TENSOR_ATTR_ALLOC_TYPE	Defines the allocation type, reserved. (default: none)
NVM_TENSOR_ATTR_4D_N	Attribute types for 4D tensors. Defines the number of tensor surfaces.
NVM_TENSOR_ATTR_4D_C	Defines the number of channels of a 4D tensor.
NVM_TENSOR_ATTR_4D_H	Defines the height of a 4D tensor.
NVM_TENSOR_ATTR_4D_W	Defines the width of a 4D tensor.
NVM_TENSOR_ATTR_4D_X	Defines the x value of a 4D tensor. This value is only for NCxHWx order
NVM_TENSOR_ATTR_MAX	Defines the maximum number of tensor creation attributes.

Definition at line 94 of file nvmedia_tensor.h.

◆ NvMediaTensorLockAccess

enum NvMediaTensorLockAccess

Defines tensor lock access types.

Enumerator
NVMEDIA_TENSOR_ACCESS_READ	Read access.
NVMEDIA_TENSOR_ACCESS_WRITE	Write access.
NVMEDIA_TENSOR_ACCESS_READ_WRITE	Read/Write access.

Definition at line 265 of file nvmedia_tensor.h.

Function Documentation

◆ NvMediaTensorDestroy()

void NvMediaTensorDestroy ( NvMediaTensor * tensor )

Destroys a tensor object previously created by NvMediaTensorCreateFromNvSciBuf().

Parameters

[in] tensor The tensor to destroy.
Input range: A valid, non-null pointer to NvMediaTensor.

Precondition

NvMediaTensor must have been created

Usage considerations

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

◆ NvMediaTensorGetMetaData()

NvMediaStatus NvMediaTensorGetMetaData	(	const NvMediaTensor *	tensor,
		NvMediaTensorMetaData *	tensormetadata
	)

Fills in the metadata information for the tensor.

Parameters

[in]	tensor	The tensor object to get metadata from. Input range: A valid, non-null pointer to NvMediaTensor.
[in,out]	tensormetadata	A pointer to a NvMediaTensorMetaData structure where tensor metadata is copied. This should be a non-NULL value

Returns: NvMediaStatus, the completion status of the operation:

Return values

NVMEDIA_STATUS_OK	if the function is successful.
NVMEDIA_STATUS_BAD_PARAMETER	if any of the arguments are NULL or invalid.
NVMEDIA_STATUS_INVALID_STATE	if the API is triggered in the DRIVEOS state that is not allowed as per the API Group.

Precondition: None

Usage considerations

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

◆ NvMediaTensorGetStatus()

NvMediaStatus NvMediaTensorGetStatus	(	NvMediaTensor *	tensor,
		uint32_t	millisecondWait,
		NvMediaTensorTaskStatus *	status
	)

Gets the status of the last operation for the tensor, and optionally waits for the operation to complete or time out.

Parameters

[in]	tensor	The handle to the tensor object. Input range: A valid, non-null pointer to NvMediaTensor.
[in]	millisecondWait	Time in milliseconds to wait for the operation to complete before getting the status. Recommended value is NVMEDIA_TENSOR_TIMEOUT_INFINITE.
[out]	status	The status of the operation. Input range: A valid, non-null pointer to NvMediaTensorTaskStatus.

Returns: NvMediaStatus, the completion status of the operation:

Return values

NVMEDIA_STATUS_OK	if the function is successful.
NVMEDIA_STATUS_TIMEOUT	- if the wait on the tensor timed out. if the task execution exceeded the user input value
NVMEDIA_STATUS_OUT_OF_MEMORY	- if memory related DLA error occured
NVMEDIA_STATUS_PFSD_ERROR	if a failure occurs during permanent fault diagnostics
NVMEDIA_STATUS_BAD_PARAMETER	if any of the arguments are NULL or invalid.
NVMEDIA_STATUS_ERROR	- if an internal DLA SW stack error occured. if the input task status is not success, this error is returned for remaining tasks in the chain
NVMEDIA_STATUS_INVALID_STATE	- if the API is triggered in the DRIVEOS state that is not allowed as per the API Group.

Precondition

The user must have submitted a task to the DLA engine before calling this function.
The user must call this API only for output NvMediaTensors filled by NvMediaDlaSubmit().

Usage considerations

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

◆ NvMediaTensorGetVersion()

NvMediaStatus NvMediaTensorGetVersion ( NvMediaVersion * version )

Returns version information for the NvMediaTensor library.

Parameters

[out] version A valid, non-NULL pointer to NvMediaVersion to store version information.

Returns: NvMediaStatus, the completion status of the operation:

Return values

NVMEDIA_STATUS_OK	if the function call is successful.
NVMEDIA_STATUS_BAD_PARAMETER	if version is invalid.
NVMEDIA_STATUS_INVALID_STATE	if the API is triggered in the DRIVEOS state that is not allowed as per the API Group.

Precondition: None

Usage considerations

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

◆ NvMediaTensorLock()

NvMediaStatus NvMediaTensorLock	(	NvMediaTensor *	tensor,
		NvMediaTensorLockAccess	lockAccessType,
		NvMediaTensorSurfaceMap *	surfaceMap
	)

Locks a tensor and returns the associated mapped pointers pointing to the tensor surface data.

The CPU can only access tensors created with the NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED or NVM_TENSOR_ATTR_CPU_ACCESS_CACHED attributes.

If a tensor is currently in use by an internal engine, this function waits until the operation completes.

Parameters

[in]	tensor	A pointer to the tensor object. Input range: A valid, non-null pointer to NvMediaTensor.
[in]	lockAccessType	Specifies the NvMediaTensorLockAccess type. Input range: Any enum value defined by NvMediaTensorLockAccess.
[out]	surfaceMap	A pointer to the surface descriptors. Input range: A valid, non-null pointer to NvMediaTensorSurfaceMap.

Returns: NvMediaStatus The completion status of the operation:

Return values

NVMEDIA_STATUS_OK	if the function is successful.
NVMEDIA_STATUS_BAD_PARAMETER	if any of the arguments are NULL or invalid.
NVMEDIA_STATUS_TIMEOUT	if the wait on the tensor timed out.
NVMEDIA_STATUS_ERROR	if an error occurred.
NVMEDIA_STATUS_INVALID_STATE	if the API is triggered in the DRIVEOS state that is not allowed as per the API Group.

Precondition

tensor must not be already locked

Usage considerations

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

◆ NvMediaTensorUnlock()

void NvMediaTensorUnlock ( NvMediaTensor * tensor )

Unlocks a tensor.

Releases the lock applied on NvMediaTensor using NvMediaTensorLock.

Parameters

[in] tensor The tensor object to unlock.
Input range: A valid, non-null pointer to NvMediaTensor.

Precondition

tensor must have been locked using NvMediaTensorLock()

Usage considerations

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

NVIDIA DRIVE OS Linux SDK API Reference

6.0.9 Release

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ NVM_TENSOR_ATTR_ALLOC_NONE

◆ NVM_TENSOR_ATTR_CPU_ACCESS_CACHED

◆ NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED

◆ NVM_TENSOR_ATTR_CPU_ACCESS_UNMAPPED

◆ NVM_TENSOR_DEFINE_ATTR

◆ NVM_TENSOR_INIT_ATTR

◆ NVM_TENSOR_SET_ATTR_4D

◆ NVMEDIA_TENSOR_TIMEOUT_INFINITE

◆ NVMEDIA_TENSOR_VERSION_MAJOR

◆ NVMEDIA_TENSOR_VERSION_MINOR

◆ NVMEDIA_TENSOR_VERSION_PATCH

◆ NVMTENSOR_4D_MAX_C

◆ NVMTENSOR_4D_MAX_H

◆ NVMTENSOR_4D_MAX_N

◆ NVMTENSOR_4D_MAX_W

◆ NVMTENSOR_4D_MAX_X

Typedef Documentation

◆ NvMediaTensor

Enumeration Type Documentation

◆ NvMediaTensorAttrType

◆ NvMediaTensorLockAccess

Function Documentation

◆ NvMediaTensorDestroy()

◆ NvMediaTensorGetMetaData()

◆ NvMediaTensorGetStatus()

◆ NvMediaTensorGetVersion()

◆ NvMediaTensorLock()

◆ NvMediaTensorUnlock()