# NVIDIA DRIVE OS Linux SDK API Reference

##### 5.2.6 Release For Test and Development only
Tensor Handling API

## Detailed Description

The Tensor Processing API encompasses all NvMedia tensor related functionality.

## Data Structures

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   (12u)
Minor 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_RESERVED   (0x00000010u)
Specifies that the tensor allocation is on CVRAM. 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...

## Functions

void NvMediaTensorDestroy (NvMediaTensor *tensor)
Destroys a tensor object previously created by NvMediaTensorCreateFromNvSciBuf(). 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...

Fills in the metadata information for the tensor. More...

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

## ◆ NVM_TENSOR_ATTR_ALLOC_NONE

 #define NVM_TENSOR_ATTR_ALLOC_NONE   (0x00000000u)

Specifies that the tensor allocation is on Soc DRAM.

Definition at line 140 of file nvmedia_tensor.h.

## ◆ NVM_TENSOR_ATTR_ALLOC_RESERVED

 #define NVM_TENSOR_ATTR_ALLOC_RESERVED   (0x00000010u)

Specifies that the tensor allocation is on CVRAM.

CVSRAM is currently not supported in the Safety build.

Definition at line 136 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 125 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 119 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 130 of file nvmedia_tensor.h.

## ◆ NVM_TENSOR_DEFINE_ATTR

 #define NVM_TENSOR_DEFINE_ATTR ( x )
Value:
NVM_TENSOR_INIT_ATTR(x); \

A helper macro to define tensor creation attributes.

Definition at line 192 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 156 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 218 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 65 of file nvmedia_tensor.h.

## ◆ NVMEDIA_TENSOR_VERSION_MAJOR

 #define NVMEDIA_TENSOR_VERSION_MAJOR   (1u)

Major version number.

Definition at line 45 of file nvmedia_tensor.h.

## ◆ NVMEDIA_TENSOR_VERSION_MINOR

 #define NVMEDIA_TENSOR_VERSION_MINOR   (12u)

Minor version number.

Definition at line 47 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 52 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 54 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 50 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 56 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 58 of file nvmedia_tensor.h.

## ◆ NvMediaTensor

 typedef struct NvMediaTensor NvMediaTensor

A handle representing tensor objects.

Definition at line 81 of file nvmedia_tensor.h.

## ◆ 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

(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 87 of file nvmedia_tensor.h.

## ◆ NvMediaTensorDestroy()

 void NvMediaTensorDestroy ( NvMediaTensor * tensor )

Destroys a tensor object previously created by NvMediaTensorCreateFromNvSciBuf().

Parameters
 [in] tensor The tensor to destroy.

Fills in the metadata information for the tensor.

Parameters
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.

## ◆ 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. [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.
Returns
NvMediaStatus, the completion status of the operation:
Return values
 NVMEDIA_STATUS_OK if the function is successful. NVMEDIA_STATUS_ERROR if an error occurred. NVMEDIA_STATUS_BAD_PARAMETER if any of the arguments are NULL or invalid.

## ◆ NvMediaTensorGetVersion()

 NvMediaStatus NvMediaTensorGetVersion ( NvMediaVersion * version )

Returns version information for the NvMediaTensor library.

Parameters
 [out] version A pointer to a structure in which the function may 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.
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.
Definition: nvmedia_tensor.h:218
NVM_TENSOR_ATTR_MAX
@ NVM_TENSOR_ATTR_MAX
Defines the maximum number of tensor creation attributes.
Definition: nvmedia_tensor.h:111
NvMediaTensorAttr
Holds tensor creation attributes.
Definition: nvmedia_tensor.h:145