NVIDIA DRIVE OS Linux SDK API Reference
6.0.3 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 
50 #define NVMTENSOR_4D_MAX_N (65536u)
51 
52 #define NVMTENSOR_4D_MAX_C (8192u)
53 
54 #define NVMTENSOR_4D_MAX_H (8192u)
55 
56 #define NVMTENSOR_4D_MAX_W (8192u)
57 
58 #define NVMTENSOR_4D_MAX_X (1024u)
59 
65 #define NVMEDIA_TENSOR_TIMEOUT_INFINITE (0xFFFFFFFFu)
66 
71 typedef struct {
73  NvMediaStatus status;
75  uint32_t durationUs;
76 } NvMediaTensorTaskStatus;
77 
81 typedef struct NvMediaTensor NvMediaTensor;
82 
87 typedef enum {
89  NVM_TENSOR_ATTR_DATA_TYPE = 0,
91  NVM_TENSOR_ATTR_BITS_PER_ELEMENT,
93  NVM_TENSOR_ATTR_DIMENSION_ORDER,
95  NVM_TENSOR_ATTR_CPU_ACCESS,
97  NVM_TENSOR_ATTR_ALLOC_TYPE,
101  NVM_TENSOR_ATTR_4D_N,
103  NVM_TENSOR_ATTR_4D_C,
105  NVM_TENSOR_ATTR_4D_H,
107  NVM_TENSOR_ATTR_4D_W,
109  NVM_TENSOR_ATTR_4D_X,
111  NVM_TENSOR_ATTR_MAX
112 } NvMediaTensorAttrType;
113 
119 #define NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED (0x00000001u)
120 
125 #define NVM_TENSOR_ATTR_CPU_ACCESS_CACHED (0x00000002u)
126 
130 #define NVM_TENSOR_ATTR_CPU_ACCESS_UNMAPPED (0x00000003u)
131 
132 #if NV_BUILD_CONFIGURATION_EXPOSING_T19X
133 
137 #define NVM_TENSOR_ATTR_ALLOC_RESERVED (0x00000010u)
138 #endif
139 
143 #define NVM_TENSOR_ATTR_ALLOC_NONE (0x00000000u)
144 
148 typedef struct {
150  NvMediaTensorAttrType type;
152  uint32_t value;
153 } NvMediaTensorAttr;
154 
159 #define NVM_TENSOR_INIT_ATTR(x) \
160 { \
161  x[0].type = NVM_TENSOR_ATTR_DATA_TYPE; \
162  x[0].value = 0; \
163  \
164  x[1].type = NVM_TENSOR_ATTR_4D_N; \
165  x[1].value = 0; \
166  \
167  x[2].type = NVM_TENSOR_ATTR_4D_C; \
168  x[2].value = 0; \
169  \
170  x[3].type = NVM_TENSOR_ATTR_4D_H; \
171  x[3].value = 0; \
172  \
173  x[4].type = NVM_TENSOR_ATTR_4D_W; \
174  x[4].value = 0; \
175  \
176  x[5].type = NVM_TENSOR_ATTR_4D_X; \
177  x[5].value = 0; \
178  \
179  x[6].type = NVM_TENSOR_ATTR_BITS_PER_ELEMENT; \
180  x[6].value = 0; \
181  \
182  x[7].type = NVM_TENSOR_ATTR_DIMENSION_ORDER; \
183  x[7].value = 0; \
184  \
185  x[8].type = NVM_TENSOR_ATTR_CPU_ACCESS; \
186  x[8].value = 0; \
187  \
188  x[9].type = NVM_TENSOR_ATTR_ALLOC_TYPE; \
189  x[9].value = 0; \
190 }
191 
195 #define NVM_TENSOR_DEFINE_ATTR(x) \
196  NvMediaTensorAttr x[NVM_TENSOR_ATTR_MAX]; \
197  NVM_TENSOR_INIT_ATTR(x); \
198 
199 
221 #define NVM_TENSOR_SET_ATTR_4D(attr, N, C, H, W, order, datatype, bpe, accesstype, alloctype, X)\
222 { \
223  attr[0].type = NVM_TENSOR_ATTR_DATA_TYPE; \
224  attr[0].value = NVM_TENSOR_ATTR_DATA_TYPE_##datatype; \
225  \
226  attr[1].type = NVM_TENSOR_ATTR_4D_N; \
227  attr[1].value = N; \
228  \
229  attr[2].type = NVM_TENSOR_ATTR_4D_C; \
230  attr[2].value = C; \
231  \
232  attr[3].type = NVM_TENSOR_ATTR_4D_H; \
233  attr[3].value = H; \
234  \
235  attr[4].type = NVM_TENSOR_ATTR_4D_W; \
236  attr[4].value = W; \
237  \
238  attr[5].type = NVM_TENSOR_ATTR_4D_X; \
239  attr[5].value = X; \
240  \
241  attr[6].type = NVM_TENSOR_ATTR_BITS_PER_ELEMENT; \
242  attr[6].value = NVM_TENSOR_ATTR_BITS_PER_ELEMENT_##bpe; \
243  \
244  attr[7].type = NVM_TENSOR_ATTR_DIMENSION_ORDER; \
245  attr[7].value = NVM_TENSOR_ATTR_DIMENSION_ORDER_##order; \
246  \
247  attr[8].type = NVM_TENSOR_ATTR_CPU_ACCESS; \
248  attr[8].value = NVM_TENSOR_ATTR_CPU_ACCESS_##accesstype; \
249  \
250  attr[9].type = NVM_TENSOR_ATTR_ALLOC_TYPE; \
251  attr[9].value = NVM_TENSOR_ATTR_ALLOC_##alloctype; \
252 }
253 
258 typedef enum {
260  NVMEDIA_TENSOR_ACCESS_READ = (1 << 0),
262  NVMEDIA_TENSOR_ACCESS_WRITE = (1 << 1),
264  NVMEDIA_TENSOR_ACCESS_READ_WRITE = (NVMEDIA_TENSOR_ACCESS_READ | NVMEDIA_TENSOR_ACCESS_WRITE)
265 } NvMediaTensorLockAccess;
266 
274 typedef struct {
276  uint32_t size;
278  void *mapping;
279 } NvMediaTensorSurfaceMap;
280 
300 void
301 NvMediaTensorDestroy(
302  NvMediaTensor *tensor
303 );
304 
340 NvMediaStatus
341 NvMediaTensorLock(
342  NvMediaTensor *tensor,
343  NvMediaTensorLockAccess lockAccessType,
344  NvMediaTensorSurfaceMap *surfaceMap
345 );
346 
368 void
369 NvMediaTensorUnlock(
370  NvMediaTensor *tensor
371 );
372 
400 NvMediaStatus
401 NvMediaTensorGetStatus(
402  NvMediaTensor *tensor,
403  uint32_t millisecondWait,
404  NvMediaTensorTaskStatus *status
405 );
406 
431 NvMediaStatus
432 NvMediaTensorGetMetaData(
433  const NvMediaTensor *tensor,
434  NvMediaTensorMetaData *tensormetadata
435 );
436 
460 NvMediaStatus
461 NvMediaTensorGetVersion(
462  NvMediaVersion *version
463 );
464 
467 /*
468  * \defgroup history_nvmedia_tensor History
469  * Provides change history for the NvMedia Tensor API.
470  *
471  * \section history_nvmedia_tensor Version History
472  *
473  * <b> Version 1.0 </b> May 22, 2017
474  * - Initial release
475  *
476  * <b> Version 1.2 </b> Jun 21, 2019
477  * - Fix Minor Misra Violations
478  *
479  * <b> Version 1.3 </b> Jun 22, 2019
480  * - Deprecate the NvMediaTensorCreate API
481  * in support of NvSciBuf APIs
482  *
483  * <b> Version 1.4 </b> Dec 9, 2019
484  * - Add const to NvMediaGetTensorMetaData
485  * in support of Misra rule 8.13
486  *
487  * <b> Version 1.5 </b> Jan 10, 2020
488  * - In NvMediaTensorLock API fix data type of
489  * lockAccessType parameter
490  *
491  * <b> Version 1.6 </b> Jan 15, 2020
492  * - Fix the comments for: NvMediaTensorGetMetaData,
493  * NvMediaTensorGetStatus, NvMediaTensorLock
494  *
495  * <b> Version 1.7 </b> Feb 13, 2020
496  * - Fix the comments for: NvMediaTensorLock,
497  * NvMediaTensorGetStatus, NvMediaTensorGetMetaData
498  * - Rearranged NvMediaTensorDestroy
499  *
500  * <b> Version 1.8 </b> Mar 25, 2020
501  * - Fix the doxygen comments for most functions
502  * - Fixed NvMediaTensorDestroy misra violation 8.3
503  *
504  * <b> Version 1.9 </b> Apr 14, 2020
505  * - Updated Doxygen comments for enums, macros and structs
506  *
507  * <b> Version 1.10 </b> May 7, 2020
508  * - Updated Doxygen comments for NvMediaTensor struct
509  *
510  * <b> Version 1.11 </b> June 5, 2020
511  * - Added NvMediaTensorGetVersion API
512  *
513  * <b> Version 1.12 </b> June 17, 2020
514  * - Added Max Tensor dimension macros
515  *
516  * <b> Version 1.13 </b> August 27, 2021
517  * - Update doxygen comments for all APIs to have Thread safety information and API Group information
518  *
519  *
520  **/
523 #ifdef __cplusplus
524 } /* extern "C" */
525 #endif
526 
527 #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:71
NVM_TENSOR_ATTR_4D_W
@ NVM_TENSOR_ATTR_4D_W
Defines the width of a 4D tensor.
Definition: nvmedia_tensor.h:107
nvmedia_core.h
NVIDIA Media Interface: Core
nvmedia_tensormetadata.h
NVIDIA Media Interface: Tensor Metadata Interface
NVMEDIA_TENSOR_ACCESS_WRITE
@ NVMEDIA_TENSOR_ACCESS_WRITE
Write access.
Definition: nvmedia_tensor.h:262
NvMediaTensorAttr::type
NvMediaTensorAttrType type
Holds tensor creation attribute type.
Definition: nvmedia_tensor.h:150
NvMediaTensorSurfaceMap
Defines the tensor surface map descriptor used by NvMediaTensorLock().
Definition: nvmedia_tensor.h:274
NvMediaTensorSurfaceMap::size
uint32_t size
Total size of the tensor.
Definition: nvmedia_tensor.h:276
NvMediaTensorLockAccess
NvMediaTensorLockAccess
Defines tensor lock access types.
Definition: nvmedia_tensor.h:258
NvMediaTensorAttrType
NvMediaTensorAttrType
Defines attribute types for creating NvMedia Tensor.
Definition: nvmedia_tensor.h:87
NVM_TENSOR_ATTR_CPU_ACCESS
@ NVM_TENSOR_ATTR_CPU_ACCESS
Defines the CPU access to tensor.
Definition: nvmedia_tensor.h:95
NvMediaTensorTaskStatus::durationUs
uint32_t durationUs
Duration of the operation in microseconds.
Definition: nvmedia_tensor.h:75
NvMediaTensorLock
NvMediaStatus NvMediaTensorLock(NvMediaTensor *tensor, NvMediaTensorLockAccess lockAccessType, NvMediaTensorSurfaceMap *surfaceMap)
Locks a tensor and returns the associated mapped pointers pointing to the tensor surface data.
NvMediaVersion
Holds NvMedia version information.
Definition: tvmr/include/nvmedia_core.h:237
NVM_TENSOR_ATTR_BITS_PER_ELEMENT
@ NVM_TENSOR_ATTR_BITS_PER_ELEMENT
Defines the tensor bits per element.
Definition: nvmedia_tensor.h:91
NvMediaTensorGetMetaData
NvMediaStatus NvMediaTensorGetMetaData(const NvMediaTensor *tensor, NvMediaTensorMetaData *tensormetadata)
Fills in the metadata information for the tensor.
NVM_TENSOR_ATTR_DIMENSION_ORDER
@ NVM_TENSOR_ATTR_DIMENSION_ORDER
Defines the tensor dimension order.
Definition: nvmedia_tensor.h:93
NvMediaTensor
struct NvMediaTensor NvMediaTensor
A handle representing tensor objects.
Definition: nvmedia_tensor.h:81
NVM_TENSOR_ATTR_4D_C
@ NVM_TENSOR_ATTR_4D_C
Defines the number of channels of a 4D tensor.
Definition: nvmedia_tensor.h:103
NVM_TENSOR_ATTR_MAX
@ NVM_TENSOR_ATTR_MAX
Defines the maximum number of tensor creation attributes.
Definition: nvmedia_tensor.h:111
NVMEDIA_TENSOR_ACCESS_READ
@ NVMEDIA_TENSOR_ACCESS_READ
Read access.
Definition: nvmedia_tensor.h:260
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:278
NvMediaStatus
NvMediaStatus
Defines all possible error codes.
Definition: tvmr/include/nvmedia_core.h:180
NVM_TENSOR_ATTR_ALLOC_TYPE
@ NVM_TENSOR_ATTR_ALLOC_TYPE
Defines the allocation type, reserved.
Definition: nvmedia_tensor.h:97
NVM_TENSOR_ATTR_4D_X
@ NVM_TENSOR_ATTR_4D_X
Defines the x value of a 4D tensor.
Definition: nvmedia_tensor.h:109
NvMediaTensorAttr
Holds tensor creation attributes.
Definition: nvmedia_tensor.h:148
NVM_TENSOR_ATTR_DATA_TYPE
@ NVM_TENSOR_ATTR_DATA_TYPE
Specifies the tensor data type.
Definition: nvmedia_tensor.h:89
NVMEDIA_TENSOR_ACCESS_READ_WRITE
@ NVMEDIA_TENSOR_ACCESS_READ_WRITE
Read/Write access.
Definition: nvmedia_tensor.h:264
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:105
NvMediaTensorUnlock
void NvMediaTensorUnlock(NvMediaTensor *tensor)
Unlocks a tensor.
NvMediaTensorAttr::value
uint32_t value
Holds tensor creation attribute value.
Definition: nvmedia_tensor.h:152
NvMediaTensorTaskStatus::status
NvMediaStatus status
Holds the return status of the operation as an error code of type - NvMediaStatus.
Definition: nvmedia_tensor.h:73
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:101