NVIDIA DRIVE OS Linux SDK API Reference
6.0.4 Release
nvmedia_tensor.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017-2022, NVIDIA CORPORATION. All rights reserved. All
3  * information contained herein is proprietary and confidential to NVIDIA
4  * Corporation. Any use, reproduction, or disclosure without the written
5  * permission of NVIDIA Corporation is prohibited.
6  */
7 
16 #ifndef NVMEDIA_TENSOR_H
17 #define NVMEDIA_TENSOR_H
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 #include "nvmedia_core.h"
24 #include "nvmedia_tensormetadata.h"
25 
45 #define NVMEDIA_TENSOR_VERSION_MAJOR (1u)
46 
47 #define NVMEDIA_TENSOR_VERSION_MINOR (13u)
48 
49 #define NVMEDIA_TENSOR_VERSION_PATCH (0u)
50 
52 #define NVMTENSOR_4D_MAX_N (65536u)
53 
54 #define NVMTENSOR_4D_MAX_C (8192u)
55 
56 #define NVMTENSOR_4D_MAX_H (8192u)
57 
58 #define NVMTENSOR_4D_MAX_W (8192u)
59 
60 #define NVMTENSOR_4D_MAX_X (1024u)
61 
67 #define NVMEDIA_TENSOR_TIMEOUT_INFINITE (0xFFFFFFFFu)
68 
73 typedef struct {
75  NvMediaStatus status;
77  uint32_t durationUs;
78 } NvMediaTensorTaskStatus;
79 
83 typedef struct NvMediaTensor NvMediaTensor;
84 
89 typedef enum {
91  NVM_TENSOR_ATTR_DATA_TYPE = 0,
93  NVM_TENSOR_ATTR_BITS_PER_ELEMENT,
95  NVM_TENSOR_ATTR_DIMENSION_ORDER,
97  NVM_TENSOR_ATTR_CPU_ACCESS,
99  NVM_TENSOR_ATTR_ALLOC_TYPE,
103  NVM_TENSOR_ATTR_4D_N,
105  NVM_TENSOR_ATTR_4D_C,
107  NVM_TENSOR_ATTR_4D_H,
109  NVM_TENSOR_ATTR_4D_W,
111  NVM_TENSOR_ATTR_4D_X,
113  NVM_TENSOR_ATTR_MAX
114 } NvMediaTensorAttrType;
115 
121 #define NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED (0x00000001u)
122 
127 #define NVM_TENSOR_ATTR_CPU_ACCESS_CACHED (0x00000002u)
128 
132 #define NVM_TENSOR_ATTR_CPU_ACCESS_UNMAPPED (0x00000003u)
133 
134 #if NV_BUILD_CONFIGURATION_EXPOSING_T19X
135 
139 #define NVM_TENSOR_ATTR_ALLOC_RESERVED (0x00000010u)
140 #endif
141 
145 #define NVM_TENSOR_ATTR_ALLOC_NONE (0x00000000u)
146 
150 typedef struct {
152  NvMediaTensorAttrType type;
154  uint32_t value;
155 } NvMediaTensorAttr;
156 
161 #define NVM_TENSOR_INIT_ATTR(x) \
162 { \
163  x[0].type = NVM_TENSOR_ATTR_DATA_TYPE; \
164  x[0].value = 0; \
165  \
166  x[1].type = NVM_TENSOR_ATTR_4D_N; \
167  x[1].value = 0; \
168  \
169  x[2].type = NVM_TENSOR_ATTR_4D_C; \
170  x[2].value = 0; \
171  \
172  x[3].type = NVM_TENSOR_ATTR_4D_H; \
173  x[3].value = 0; \
174  \
175  x[4].type = NVM_TENSOR_ATTR_4D_W; \
176  x[4].value = 0; \
177  \
178  x[5].type = NVM_TENSOR_ATTR_4D_X; \
179  x[5].value = 0; \
180  \
181  x[6].type = NVM_TENSOR_ATTR_BITS_PER_ELEMENT; \
182  x[6].value = 0; \
183  \
184  x[7].type = NVM_TENSOR_ATTR_DIMENSION_ORDER; \
185  x[7].value = 0; \
186  \
187  x[8].type = NVM_TENSOR_ATTR_CPU_ACCESS; \
188  x[8].value = 0; \
189  \
190  x[9].type = NVM_TENSOR_ATTR_ALLOC_TYPE; \
191  x[9].value = 0; \
192 }
193 
197 #define NVM_TENSOR_DEFINE_ATTR(x) \
198  NvMediaTensorAttr x[NVM_TENSOR_ATTR_MAX]; \
199  NVM_TENSOR_INIT_ATTR(x); \
200 
201 
223 #define NVM_TENSOR_SET_ATTR_4D(attr, N, C, H, W, order, datatype, bpe, accesstype, alloctype, X)\
224 { \
225  attr[0].type = NVM_TENSOR_ATTR_DATA_TYPE; \
226  attr[0].value = NVM_TENSOR_ATTR_DATA_TYPE_##datatype; \
227  \
228  attr[1].type = NVM_TENSOR_ATTR_4D_N; \
229  attr[1].value = N; \
230  \
231  attr[2].type = NVM_TENSOR_ATTR_4D_C; \
232  attr[2].value = C; \
233  \
234  attr[3].type = NVM_TENSOR_ATTR_4D_H; \
235  attr[3].value = H; \
236  \
237  attr[4].type = NVM_TENSOR_ATTR_4D_W; \
238  attr[4].value = W; \
239  \
240  attr[5].type = NVM_TENSOR_ATTR_4D_X; \
241  attr[5].value = X; \
242  \
243  attr[6].type = NVM_TENSOR_ATTR_BITS_PER_ELEMENT; \
244  attr[6].value = NVM_TENSOR_ATTR_BITS_PER_ELEMENT_##bpe; \
245  \
246  attr[7].type = NVM_TENSOR_ATTR_DIMENSION_ORDER; \
247  attr[7].value = NVM_TENSOR_ATTR_DIMENSION_ORDER_##order; \
248  \
249  attr[8].type = NVM_TENSOR_ATTR_CPU_ACCESS; \
250  attr[8].value = NVM_TENSOR_ATTR_CPU_ACCESS_##accesstype; \
251  \
252  attr[9].type = NVM_TENSOR_ATTR_ALLOC_TYPE; \
253  attr[9].value = NVM_TENSOR_ATTR_ALLOC_##alloctype; \
254 }
255 
260 typedef enum {
262  NVMEDIA_TENSOR_ACCESS_READ = (1 << 0),
264  NVMEDIA_TENSOR_ACCESS_WRITE = (1 << 1),
266  NVMEDIA_TENSOR_ACCESS_READ_WRITE = (NVMEDIA_TENSOR_ACCESS_READ | NVMEDIA_TENSOR_ACCESS_WRITE)
267 } NvMediaTensorLockAccess;
268 
276 typedef struct {
278  uint32_t size;
280  void *mapping;
281 } NvMediaTensorSurfaceMap;
282 
302 void
303 NvMediaTensorDestroy(
304  NvMediaTensor *tensor
305 );
306 
342 NvMediaStatus
343 NvMediaTensorLock(
344  NvMediaTensor *tensor,
345  NvMediaTensorLockAccess lockAccessType,
346  NvMediaTensorSurfaceMap *surfaceMap
347 );
348 
370 void
371 NvMediaTensorUnlock(
372  NvMediaTensor *tensor
373 );
374 
403 NvMediaStatus
404 NvMediaTensorGetStatus(
405  NvMediaTensor *tensor,
406  uint32_t millisecondWait,
407  NvMediaTensorTaskStatus *status
408 );
409 
434 NvMediaStatus
435 NvMediaTensorGetMetaData(
436  const NvMediaTensor *tensor,
437  NvMediaTensorMetaData *tensormetadata
438 );
439 
463 NvMediaStatus
464 NvMediaTensorGetVersion(
465  NvMediaVersion *version
466 );
467 
470 /*
471  * \defgroup history_nvmedia_tensor History
472  * Provides change history for the NvMedia Tensor API.
473  *
474  * \section history_nvmedia_tensor Version History
475  *
476  * <b> Version 1.0 </b> May 22, 2017
477  * - Initial release
478  *
479  * <b> Version 1.2 </b> Jun 21, 2019
480  * - Fix Minor Misra Violations
481  *
482  * <b> Version 1.3 </b> Jun 22, 2019
483  * - Deprecate the NvMediaTensorCreate API
484  * in support of NvSciBuf APIs
485  *
486  * <b> Version 1.4 </b> Dec 9, 2019
487  * - Add const to NvMediaGetTensorMetaData
488  * in support of Misra rule 8.13
489  *
490  * <b> Version 1.5 </b> Jan 10, 2020
491  * - In NvMediaTensorLock API fix data type of
492  * lockAccessType parameter
493  *
494  * <b> Version 1.6 </b> Jan 15, 2020
495  * - Fix the comments for: NvMediaTensorGetMetaData,
496  * NvMediaTensorGetStatus, NvMediaTensorLock
497  *
498  * <b> Version 1.7 </b> Feb 13, 2020
499  * - Fix the comments for: NvMediaTensorLock,
500  * NvMediaTensorGetStatus, NvMediaTensorGetMetaData
501  * - Rearranged NvMediaTensorDestroy
502  *
503  * <b> Version 1.8 </b> Mar 25, 2020
504  * - Fix the doxygen comments for most functions
505  * - Fixed NvMediaTensorDestroy misra violation 8.3
506  *
507  * <b> Version 1.9 </b> Apr 14, 2020
508  * - Updated Doxygen comments for enums, macros and structs
509  *
510  * <b> Version 1.10 </b> May 7, 2020
511  * - Updated Doxygen comments for NvMediaTensor struct
512  *
513  * <b> Version 1.11 </b> June 5, 2020
514  * - Added NvMediaTensorGetVersion API
515  *
516  * <b> Version 1.12 </b> June 17, 2020
517  * - Added Max Tensor dimension macros
518  *
519  * <b> Version 1.13 </b> August 27, 2021
520  * - Update doxygen comments for all APIs to have Thread safety information and API Group information
521  *
522  * <b> Version 1.13 </b> February 08, 2022
523  * - Updated the doxygen comments with usage considerations for all APIs.
524  *
525  * <b> Version 1.13 </b> April 04, 2022
526  * - Update doxygen comments for NvMediaTensorLock and NvMediaTensorGetStatus APIs
527  *
528  * <b> Version 1.13.0 </b> May 10, 2022
529  * - Added patch version number macro: NVMEDIA_TENSOR_VERSION_PATCH.
530  *
531  **/
534 #ifdef __cplusplus
535 } /* extern "C" */
536 #endif
537 
538 #endif /* NVMEDIA_TENSOR_H */
NvMediaTensorGetVersion
NvMediaStatus NvMediaTensorGetVersion(NvMediaVersion *version)
Returns version information for the NvMediaTensor library.
NvMediaTensorTaskStatus
Holds the status of the latest operation for a tensor.
Definition: nvmedia_tensor.h:73
NVM_TENSOR_ATTR_4D_W
@ NVM_TENSOR_ATTR_4D_W
Defines the width of a 4D tensor.
Definition: nvmedia_tensor.h:109
nvmedia_tensormetadata.h
NVIDIA Media Interface: Tensor Metadata Interface
NvMediaTensorAttr::type
NvMediaTensorAttrType type
Holds tensor creation attribute type.
Definition: nvmedia_tensor.h:152
NvMediaTensorSurfaceMap
Defines the tensor surface map descriptor used by NvMediaTensorLock().
Definition: nvmedia_tensor.h:276
NvMediaTensorUnlock
void NvMediaTensorUnlock(NvMediaTensor *tensor)
Unlocks a tensor.
NvMediaTensorSurfaceMap::size
uint32_t size
Total size of the tensor.
Definition: nvmedia_tensor.h:278
NvMediaTensorAttrType
NvMediaTensorAttrType
Defines attribute types for creating NvMedia Tensor.
Definition: nvmedia_tensor.h:89
NvMediaStatus
NvMediaStatus
Defines all possible error codes.
Definition: nvmedia_core.h:104
NVM_TENSOR_ATTR_CPU_ACCESS
@ NVM_TENSOR_ATTR_CPU_ACCESS
Defines the CPU access to tensor.
Definition: nvmedia_tensor.h:97
NvMediaTensorTaskStatus::durationUs
uint32_t durationUs
Duration of the operation in microseconds.
Definition: nvmedia_tensor.h:77
NvMediaVersion
Holds NvMedia version information.
Definition: nvmedia_core.h:149
NVM_TENSOR_ATTR_BITS_PER_ELEMENT
@ NVM_TENSOR_ATTR_BITS_PER_ELEMENT
Defines the tensor bits per element.
Definition: nvmedia_tensor.h:93
NvMediaTensorGetMetaData
NvMediaStatus NvMediaTensorGetMetaData(const NvMediaTensor *tensor, NvMediaTensorMetaData *tensormetadata)
Fills in the metadata information for the tensor.
NvMediaTensorLock
NvMediaStatus NvMediaTensorLock(NvMediaTensor *tensor, NvMediaTensorLockAccess lockAccessType, NvMediaTensorSurfaceMap *surfaceMap)
Locks a tensor and returns the associated mapped pointers pointing to the tensor surface data.
NVM_TENSOR_ATTR_DIMENSION_ORDER
@ NVM_TENSOR_ATTR_DIMENSION_ORDER
Defines the tensor dimension order.
Definition: nvmedia_tensor.h:95
NVMEDIA_TENSOR_ACCESS_WRITE
@ NVMEDIA_TENSOR_ACCESS_WRITE
Write access.
Definition: nvmedia_tensor.h:264
NvMediaTensor
struct NvMediaTensor NvMediaTensor
A handle representing tensor objects.
Definition: nvmedia_tensor.h:83
NVM_TENSOR_ATTR_4D_C
@ NVM_TENSOR_ATTR_4D_C
Defines the number of channels of a 4D tensor.
Definition: nvmedia_tensor.h:105
NVMEDIA_TENSOR_ACCESS_READ
@ NVMEDIA_TENSOR_ACCESS_READ
Read access.
Definition: nvmedia_tensor.h:262
NVM_TENSOR_ATTR_MAX
@ NVM_TENSOR_ATTR_MAX
Defines the maximum number of tensor creation attributes.
Definition: nvmedia_tensor.h:113
NvMediaTensorLockAccess
NvMediaTensorLockAccess
Defines tensor lock access types.
Definition: nvmedia_tensor.h:260
NVMEDIA_TENSOR_ACCESS_READ_WRITE
@ NVMEDIA_TENSOR_ACCESS_READ_WRITE
Read/Write access.
Definition: nvmedia_tensor.h:266
nvmedia_core.h
NVIDIA Media Interface: Core
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 compl...
NvMediaTensorSurfaceMap::mapping
void * mapping
CPU accessible memory pointer of Tensor.
Definition: nvmedia_tensor.h:280
NVM_TENSOR_ATTR_ALLOC_TYPE
@ NVM_TENSOR_ATTR_ALLOC_TYPE
Defines the allocation type, reserved.
Definition: nvmedia_tensor.h:99
NVM_TENSOR_ATTR_4D_X
@ NVM_TENSOR_ATTR_4D_X
Defines the x value of a 4D tensor.
Definition: nvmedia_tensor.h:111
NvMediaTensorAttr
Holds tensor creation attributes.
Definition: nvmedia_tensor.h:150
NVM_TENSOR_ATTR_DATA_TYPE
@ NVM_TENSOR_ATTR_DATA_TYPE
Specifies the tensor data type.
Definition: nvmedia_tensor.h:91
NvMediaTensorMetaData
Holds the tensor metadata.
Definition: nvmedia_tensormetadata.h:423
NVM_TENSOR_ATTR_4D_H
@ NVM_TENSOR_ATTR_4D_H
Defines the height of a 4D tensor.
Definition: nvmedia_tensor.h:107
NvMediaTensorAttr::value
uint32_t value
Holds tensor creation attribute value.
Definition: nvmedia_tensor.h:154
NvMediaTensorTaskStatus::status
NvMediaStatus status
Holds the return status of the operation as an error code of type - NvMediaStatus.
Definition: nvmedia_tensor.h:75
NvMediaTensorDestroy
void NvMediaTensorDestroy(NvMediaTensor *tensor)
Destroys a tensor object previously created by NvMediaTensorCreateFromNvSciBuf().
NVM_TENSOR_ATTR_4D_N
@ NVM_TENSOR_ATTR_4D_N
Attribute types for 4D tensors.
Definition: nvmedia_tensor.h:103