DriveWorks SDK Reference
3.0.4260 Release
For Test and Development only

DNNTensor Interface

Detailed Description

Defines DNNTensor module for managing tensor content.

Note
SW Release Applicability: These APIs are available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

Data Structures

struct  dwDNNTensor
 Exposes the content of a dwDNNTensorHandle_t. More...
 
struct  dwDNNTensorProperties
 Specifies DNNTensor properties. More...
 

Macros

#define DW_DNN_TENSOR_MAX_DIMENSIONS   9
 Maximum number of dimensions a tensor can have including batch dimension (N). More...
 

Typedefs

typedef struct dwDNNTensorObject const * dwConstDNNTensorHandle_t
 
typedef struct dwDNNTensorObject * dwDNNTensorHandle_t
 Handles representing Deep Neural Network interface. More...
 

Enumerations

enum  dwDNNTensorLayout {
  DW_DNN_TENSOR_LAYOUT_NCHW = 0,
  DW_DNN_TENSOR_LAYOUT_NHWC = 1,
  DW_DNN_TENSOR_LAYOUT_NCHWx = 2
}
 Specifies the layout of a tensor Here the letters in the suffix define: More...
 
enum  dwDNNTensorType {
  DW_DNN_TENSOR_TYPE_CPU = 0,
  DW_DNN_TENSOR_TYPE_CUDA = 1,
  DW_DNN_TENSOR_TYPE_NVMEDIA = 2
}
 Speficies the type of a tensor. More...
 

Functions

DW_API_PUBLIC dwStatus dwDNNTensor_create (dwDNNTensorHandle_t *tensorHandle, dwDNNTensorProperties properties, dwContextHandle_t ctx)
 Creates and allocates resources for a dwDNNTensorHandle_t based on the properties. More...
 
DW_API_PUBLIC dwStatus dwDNNTensor_destroy (dwDNNTensorHandle_t tensorHandle)
 Destroys the tensor handle and frees any memory created by dwDNNTensor_create(). More...
 
DW_API_PUBLIC dwStatus dwDNNTensor_getLayoutView (size_t *offset, size_t *stride, size_t *numElements, const uint32_t *indices, uint32_t numIndices, uint32_t dimension, const dwConstDNNTensorHandle_t tensorHandle)
 Returns coefficients to facilitate traversing the given dimension. More...
 
DW_API_PUBLIC dwStatus dwDNNTensor_getProperties (dwDNNTensorProperties *properties, dwConstDNNTensorHandle_t tensorHandle)
 Retrieves the properties of a dwDNNTensorHandle_t. More...
 
DW_API_PUBLIC dwStatus dwDNNTensor_getTensor (dwDNNTensor *tensor, dwDNNTensorHandle_t tensorHandle)
 Retrieves the dwDNNTensor of a dwDNNTensorHandle_t. More...
 
DW_API_PUBLIC dwStatus dwDNNTensor_lock (void **data, dwDNNTensorHandle_t tensorHandle)
 Locks the tensor and retrieves pointer to the data with write access. More...
 
DW_API_PUBLIC dwStatus dwDNNTensor_tryLock (bool *isLocked, void **data, dwDNNTensorHandle_t tensorHandle)
 Tries to lock the tensor. More...
 
DW_API_PUBLIC dwStatus dwDNNTensor_unlock (dwDNNTensorHandle_t tensorHandle)
 Unlocks the tensor, enabling other threads to lock the tensor and modify the content. More...
 

Data Structure Documentation

◆ dwDNNTensor

struct dwDNNTensor
Data Fields
dwDNNTensorProperties prop Defines the properties of the tensor.
const void * ptr Pointer to the tensor content on CPU/GPU or NvMedia.
Note
NvMedia content cannot be traversed using this pointer. dwDNNTensorStreamer should be used to stream NvMedia to CPU or GPU to be able to access the content.

◆ dwDNNTensorProperties

struct dwDNNTensorProperties
Data Fields
dwTrivialDataType dataType Data type of elements of the tensor.
uint32_t dimensionSize[DW_DNN_TENSOR_MAX_DIMENSIONS] Dimensions of the tensor to match the selected layout type.

The order of dimensions is defined by the dwDNNTensorLayout by reading the last suffix of DW_DNN_TENSOR_LAYOUT_... in reverse order. For example given DW_DNN_TENSOR_LAYOUT_NCHW, dimensionSize should be set to: [0] = width, [1] = height, [2] = number of channels and [3] = batch size.

Note
Use dwDNNTensor_getLayoutView() to traverse the tensor in order to avoid having to compute the stride and offset for each dimension.
bool isGPUMapped Indicates whether the memory allocation should be mapped to GPU.

This allocates memory using cudaHostAlloc with cudaHostAllocMapped flag. This argument is only valid if tensor type is DW_DNN_TENSOR_TYPE_CPU or DW_DNN_TENSOR_TYPE_CUDA.

uint32_t numDimensions Number of dimensions of the tensor.
dwDNNTensorLayout tensorLayout Tensor layout.
dwDNNTensorType tensorType Tensor type.

Macro Definition Documentation

◆ DW_DNN_TENSOR_MAX_DIMENSIONS

#define DW_DNN_TENSOR_MAX_DIMENSIONS   9

Maximum number of dimensions a tensor can have including batch dimension (N).

Definition at line 63 of file Tensor.h.

Typedef Documentation

◆ dwConstDNNTensorHandle_t

typedef struct dwDNNTensorObject const* dwConstDNNTensorHandle_t

Definition at line 60 of file Tensor.h.

◆ dwDNNTensorHandle_t

typedef struct dwDNNTensorObject* dwDNNTensorHandle_t

Handles representing Deep Neural Network interface.

Definition at line 59 of file Tensor.h.

Enumeration Type Documentation

◆ dwDNNTensorLayout

Specifies the layout of a tensor Here the letters in the suffix define:

  • N: number of images in the batch
  • H: height of the image
  • W: width of the image
  • C: number of channels of the image
Enumerator
DW_DNN_TENSOR_LAYOUT_NCHW 

Planar tensor. This is the most common tensor layout.

DW_DNN_TENSOR_LAYOUT_NHWC 

Interleaved tensor.

DW_DNN_TENSOR_LAYOUT_NCHWx 

Tensor with both interleaved and planar channels.

The interleaved channels are fixed and the dimension size at index 0 is the number of actual interleaved channels on the last plane.

Definition at line 81 of file Tensor.h.

◆ dwDNNTensorType

Speficies the type of a tensor.

Enumerator
DW_DNN_TENSOR_TYPE_CPU 

CPU tensor.

DW_DNN_TENSOR_TYPE_CUDA 

CUDA tensor.

DW_DNN_TENSOR_TYPE_NVMEDIA 

NvMedia tensor.

Definition at line 66 of file Tensor.h.

Function Documentation

◆ dwDNNTensor_create()

DW_API_PUBLIC dwStatus dwDNNTensor_create ( dwDNNTensorHandle_t tensorHandle,
dwDNNTensorProperties  properties,
dwContextHandle_t  ctx 
)

Creates and allocates resources for a dwDNNTensorHandle_t based on the properties.

Parameters
[out]tensorHandleA tensor handle
[in]propertiesThe tensor properties
[in]ctxThe DriveWorks context.
Returns
DW_SUCCESS if the tensor was created successfully,
DW_INVALID_ARGUMENT if any of the given parameters is invalid,
DW_INVALID_HANDLE if the given conext handle is invalid.

◆ dwDNNTensor_destroy()

DW_API_PUBLIC dwStatus dwDNNTensor_destroy ( dwDNNTensorHandle_t  tensorHandle)

Destroys the tensor handle and frees any memory created by dwDNNTensor_create().

Parameters
[in]tensorHandleA tensor handle
Returns
DW_SUCCESS if the tensor was destroyed successfully,
DW_INVALID_HANDLE if the given tensor handle is invalid.

◆ dwDNNTensor_getLayoutView()

DW_API_PUBLIC dwStatus dwDNNTensor_getLayoutView ( size_t *  offset,
size_t *  stride,
size_t *  numElements,
const uint32_t *  indices,
uint32_t  numIndices,
uint32_t  dimension,
const dwConstDNNTensorHandle_t  tensorHandle 
)

Returns coefficients to facilitate traversing the given dimension.

The coefficients can be used to estimate the location in memory by: tensorData[idx * stride + offset] where idx is in [0, numElements)

Note
This function is not supported by NvMedia tensors. In order to access the content of the tensors in question, stream them to CPU or CUDA using dwDNNTensorStreamer.
Parameters
[out]offsetOffset. Stored in CPU.
[out]strideStride. Stored in CPU.
[out]numElementsNumber of elements in the given desired dimension. Stored in CPU.
[in]indicesList of indices having the same size as dimensions of the tensor and indicating the starting position of the traversal
[in]numIndicesNumber of given indices
[in]dimensionDimension to be traversed
[in]tensorHandleA tensor handle
Returns
DW_SUCCESS if the tensor was destroyed successfully,
DW_INVALID_HANDLE if the given tensor handle is invalid.

◆ dwDNNTensor_getProperties()

DW_API_PUBLIC dwStatus dwDNNTensor_getProperties ( dwDNNTensorProperties properties,
dwConstDNNTensorHandle_t  tensorHandle 
)

Retrieves the properties of a dwDNNTensorHandle_t.

Parameters
[out]propertiesA pointer to the properties
[in]tensorHandleA tensor handle
Returns
DW_SUCCESS if the tensor properties are retrieved successfully,
DW_INVALID_HANDLE if the given tensor handle is invalid.

◆ dwDNNTensor_getTensor()

DW_API_PUBLIC dwStatus dwDNNTensor_getTensor ( dwDNNTensor tensor,
dwDNNTensorHandle_t  tensorHandle 
)

Retrieves the dwDNNTensor of a dwDNNTensorHandle_t.

Note
Any modification to the data pointed by the tensor retrieved will modify the content of the original handle
Parameters
[out]tensorA pointer to the dwDNNTensor pointer
[in]tensorHandleA tensor handle
Returns
DW_SUCCESS if the dwDNNTensor is successfully retrieved,
DW_INVALID_ARGUMENT if the given tensor pointer or tensor handle is invalid.

◆ dwDNNTensor_lock()

DW_API_PUBLIC dwStatus dwDNNTensor_lock ( void **  data,
dwDNNTensorHandle_t  tensorHandle 
)

Locks the tensor and retrieves pointer to the data with write access.

Read access can also be achieved by dwDNNTensor_getTensor(). Locking a tensor will block any operation that shall modify the content.

Note
This function will block if the tensor is locked by another thread.
Parameters
[out]dataA pointer to the beginning of the tensor content.
[in]tensorHandleA tensor handle
Returns
DW_SUCCESS if the tensor is successfully locked and data is successfully retrieved,
DW_INVALID_ARGUMENT if the given data pointer or tensor handle is invalid.

◆ dwDNNTensor_tryLock()

DW_API_PUBLIC dwStatus dwDNNTensor_tryLock ( bool *  isLocked,
void **  data,
dwDNNTensorHandle_t  tensorHandle 
)

Tries to lock the tensor.

Returns immediately. If the lock operation is successful, isLocked is set to true, and the data points to the beginning of the content of the tensor. Otherwise, isLocked is set to false and the data points to nullptr.

Note
If the tensor has already been locked by the same thread, the behavior is undefined.
Parameters
[out]isLockedA flag indicating if the lock operation is successful.
[out]dataA pointer to the beginning of the tensor content if lock is successful.
[in]tensorHandleA tensor handle
Returns
DW_SUCCESS whether the lock is successful or not,
DW_INVALID_ARGUMENT if the given data pointer, isLocked or tensor handle is invalid.

◆ dwDNNTensor_unlock()

DW_API_PUBLIC dwStatus dwDNNTensor_unlock ( dwDNNTensorHandle_t  tensorHandle)

Unlocks the tensor, enabling other threads to lock the tensor and modify the content.

Parameters
[in]tensorHandleA tensor handle
Returns
DW_SUCCESS if the tensor is successfully unlocked,
DW_INVALID_ARGUMENT if the tensor handle is invalid.