NVIDIA DriveOS Linux NSR SDK API Reference
7.0.3.0 Release
nvmedia_tensor.h
Go to the documentation of this file.
1 /*
2  * SPDX-FileCopyrightText: Copyright (c) 2017-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3  * SPDX-License-Identifier: LicenseRef-NvidiaProprietary
4  *
5  * NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
6  * property and proprietary rights in and to this material, related
7  * documentation and any modifications thereto. Any use, reproduction,
8  * disclosure or distribution of this material and related documentation
9  * without an express license agreement from NVIDIA CORPORATION or
10  * its affiliates is strictly prohibited.
11  */
12 
21 #ifndef NVMEDIA_TENSOR_H
22 #define NVMEDIA_TENSOR_H
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 #include "nvmedia_core.h"
29 #include "nvmedia_tensormetadata.h"
30 
50 #define NVMEDIA_TENSOR_VERSION_MAJOR (1u)
51 
52 #define NVMEDIA_TENSOR_VERSION_MINOR (13u)
53 
54 #define NVMEDIA_TENSOR_VERSION_PATCH (0u)
55 
57 #define NVMTENSOR_4D_MAX_N (65536u)
58 
59 #define NVMTENSOR_4D_MAX_C (8192u)
60 
61 #define NVMTENSOR_4D_MAX_H (8192u)
62 
63 #define NVMTENSOR_4D_MAX_W (8192u)
64 
65 #define NVMTENSOR_4D_MAX_X (1024u)
66 
72 #define NVMEDIA_TENSOR_TIMEOUT_INFINITE (0xFFFFFFFFu)
73 
78 typedef struct {
80  NvMediaStatus status;
82  uint32_t durationUs;
83 } NvMediaTensorTaskStatus;
84 
88 typedef struct NvMediaTensor NvMediaTensor;
89 
94 typedef enum {
96  NVM_TENSOR_ATTR_DATA_TYPE = 0,
98  NVM_TENSOR_ATTR_BITS_PER_ELEMENT,
100  NVM_TENSOR_ATTR_DIMENSION_ORDER,
102  NVM_TENSOR_ATTR_CPU_ACCESS,
104  NVM_TENSOR_ATTR_ALLOC_TYPE,
108  NVM_TENSOR_ATTR_4D_N,
110  NVM_TENSOR_ATTR_4D_C,
112  NVM_TENSOR_ATTR_4D_H,
114  NVM_TENSOR_ATTR_4D_W,
116  NVM_TENSOR_ATTR_4D_X,
118  NVM_TENSOR_ATTR_MAX
119 } NvMediaTensorAttrType;
120 
126 #define NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED (0x00000001u)
127 
132 #define NVM_TENSOR_ATTR_CPU_ACCESS_CACHED (0x00000002u)
133 
137 #define NVM_TENSOR_ATTR_CPU_ACCESS_UNMAPPED (0x00000003u)
138 
139 #if NV_BUILD_CONFIGURATION_EXPOSING_T19X
140 
144 #define NVM_TENSOR_ATTR_ALLOC_RESERVED (0x00000010u)
145 #endif
146 
150 #define NVM_TENSOR_ATTR_ALLOC_NONE (0x00000000u)
151 
155 typedef struct {
157  NvMediaTensorAttrType type;
159  uint32_t value;
160 } NvMediaTensorAttr;
161 
166 #define NVM_TENSOR_INIT_ATTR(x) \
167 { \
168  x[0].type = NVM_TENSOR_ATTR_DATA_TYPE; \
169  x[0].value = 0; \
170  \
171  x[1].type = NVM_TENSOR_ATTR_4D_N; \
172  x[1].value = 0; \
173  \
174  x[2].type = NVM_TENSOR_ATTR_4D_C; \
175  x[2].value = 0; \
176  \
177  x[3].type = NVM_TENSOR_ATTR_4D_H; \
178  x[3].value = 0; \
179  \
180  x[4].type = NVM_TENSOR_ATTR_4D_W; \
181  x[4].value = 0; \
182  \
183  x[5].type = NVM_TENSOR_ATTR_4D_X; \
184  x[5].value = 0; \
185  \
186  x[6].type = NVM_TENSOR_ATTR_BITS_PER_ELEMENT; \
187  x[6].value = 0; \
188  \
189  x[7].type = NVM_TENSOR_ATTR_DIMENSION_ORDER; \
190  x[7].value = 0; \
191  \
192  x[8].type = NVM_TENSOR_ATTR_CPU_ACCESS; \
193  x[8].value = 0; \
194  \
195  x[9].type = NVM_TENSOR_ATTR_ALLOC_TYPE; \
196  x[9].value = 0; \
197 }
198 
202 #define NVM_TENSOR_DEFINE_ATTR(x) \
203  NvMediaTensorAttr x[NVM_TENSOR_ATTR_MAX]; \
204  NVM_TENSOR_INIT_ATTR(x); \
205 
206 
228 #define NVM_TENSOR_SET_ATTR_4D(attr, N, C, H, W, order, datatype, bpe, accesstype, alloctype, X)\
229 { \
230  attr[0].type = NVM_TENSOR_ATTR_DATA_TYPE; \
231  attr[0].value = NVM_TENSOR_ATTR_DATA_TYPE_##datatype; \
232  \
233  attr[1].type = NVM_TENSOR_ATTR_4D_N; \
234  attr[1].value = N; \
235  \
236  attr[2].type = NVM_TENSOR_ATTR_4D_C; \
237  attr[2].value = C; \
238  \
239  attr[3].type = NVM_TENSOR_ATTR_4D_H; \
240  attr[3].value = H; \
241  \
242  attr[4].type = NVM_TENSOR_ATTR_4D_W; \
243  attr[4].value = W; \
244  \
245  attr[5].type = NVM_TENSOR_ATTR_4D_X; \
246  attr[5].value = X; \
247  \
248  attr[6].type = NVM_TENSOR_ATTR_BITS_PER_ELEMENT; \
249  attr[6].value = NVM_TENSOR_ATTR_BITS_PER_ELEMENT_##bpe; \
250  \
251  attr[7].type = NVM_TENSOR_ATTR_DIMENSION_ORDER; \
252  attr[7].value = NVM_TENSOR_ATTR_DIMENSION_ORDER_##order; \
253  \
254  attr[8].type = NVM_TENSOR_ATTR_CPU_ACCESS; \
255  attr[8].value = NVM_TENSOR_ATTR_CPU_ACCESS_##accesstype; \
256  \
257  attr[9].type = NVM_TENSOR_ATTR_ALLOC_TYPE; \
258  attr[9].value = NVM_TENSOR_ATTR_ALLOC_##alloctype; \
259 }
260 
265 typedef enum {
267  NVMEDIA_TENSOR_ACCESS_READ = (1 << 0),
269  NVMEDIA_TENSOR_ACCESS_WRITE = (1 << 1),
271  NVMEDIA_TENSOR_ACCESS_READ_WRITE = (NVMEDIA_TENSOR_ACCESS_READ | NVMEDIA_TENSOR_ACCESS_WRITE)
272 } NvMediaTensorLockAccess;
273 
281 typedef struct {
283  uint32_t size;
285  void *mapping;
286 } NvMediaTensorSurfaceMap;
287 
313 void
314 NvMediaTensorDestroy(
315  NvMediaTensor *tensor
316 );
317 
364 NvMediaStatus
365 NvMediaTensorLock(
366  NvMediaTensor *tensor,
367  NvMediaTensorLockAccess lockAccessType,
368  NvMediaTensorSurfaceMap *surfaceMap
369 );
370 
399 void
400 NvMediaTensorUnlock(
401  NvMediaTensor *tensor
402 );
403 
448 NvMediaStatus
449 NvMediaTensorGetStatus(
450  NvMediaTensor *tensor,
451  uint32_t millisecondWait,
452  NvMediaTensorTaskStatus *status
453 );
454 
488 NvMediaStatus
489 NvMediaTensorGetMetaData(
490  const NvMediaTensor *tensor,
491  NvMediaTensorMetaData *tensormetadata
492 );
493 
523 NvMediaStatus
524 NvMediaTensorGetVersion(
525  NvMediaVersion *version
526 );
527 
530 /*
531  * \defgroup history_nvmedia_tensor History
532  * Provides change history for the NvMedia Tensor API.
533  *
534  * \section history_nvmedia_tensor Version History
535  *
536  * <b> Version 1.0 </b> May 22, 2017
537  * - Initial release
538  *
539  * <b> Version 1.2 </b> Jun 21, 2019
540  * - Fix Minor Misra Violations
541  *
542  * <b> Version 1.3 </b> Jun 22, 2019
543  * - Deprecate the NvMediaTensorCreate API
544  * in support of NvSciBuf APIs
545  *
546  * <b> Version 1.4 </b> Dec 9, 2019
547  * - Add const to NvMediaGetTensorMetaData
548  * in support of Misra rule 8.13
549  *
550  * <b> Version 1.5 </b> Jan 10, 2020
551  * - In NvMediaTensorLock API fix data type of
552  * lockAccessType parameter
553  *
554  * <b> Version 1.6 </b> Jan 15, 2020
555  * - Fix the comments for: NvMediaTensorGetMetaData,
556  * NvMediaTensorGetStatus, NvMediaTensorLock
557  *
558  * <b> Version 1.7 </b> Feb 13, 2020
559  * - Fix the comments for: NvMediaTensorLock,
560  * NvMediaTensorGetStatus, NvMediaTensorGetMetaData
561  * - Rearranged NvMediaTensorDestroy
562  *
563  * <b> Version 1.8 </b> Mar 25, 2020
564  * - Fix the doxygen comments for most functions
565  * - Fixed NvMediaTensorDestroy misra violation 8.3
566  *
567  * <b> Version 1.9 </b> Apr 14, 2020
568  * - Updated Doxygen comments for enums, macros and structs
569  *
570  * <b> Version 1.10 </b> May 7, 2020
571  * - Updated Doxygen comments for NvMediaTensor struct
572  *
573  * <b> Version 1.11 </b> June 5, 2020
574  * - Added NvMediaTensorGetVersion API
575  *
576  * <b> Version 1.12 </b> June 17, 2020
577  * - Added Max Tensor dimension macros
578  *
579  * <b> Version 1.13 </b> August 27, 2021
580  * - Update doxygen comments for all APIs to have Thread safety information and API Group information
581  *
582  * <b> Version 1.13 </b> February 08, 2022
583  * - Updated the doxygen comments with usage considerations for all APIs.
584  *
585  * <b> Version 1.13 </b> April 04, 2022
586  * - Update doxygen comments for NvMediaTensorLock and NvMediaTensorGetStatus APIs
587  *
588  * <b> Version 1.13.0 </b> May 10, 2022
589  * - Added patch version number macro: NVMEDIA_TENSOR_VERSION_PATCH.
590  *
591  **/
594 #ifdef __cplusplus
595 } /* extern "C" */
596 #endif
597 
598 #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:78
NVM_TENSOR_ATTR_4D_W
@ NVM_TENSOR_ATTR_4D_W
Defines the width of a 4D tensor.
Definition: nvmedia_tensor.h:114
nvmedia_tensormetadata.h
NVIDIA Media Interface: Tensor Metadata Interface
NvMediaTensorAttr::type
NvMediaTensorAttrType type
Holds tensor creation attribute type.
Definition: nvmedia_tensor.h:157
NvMediaTensorSurfaceMap
Defines the tensor surface map descriptor used by NvMediaTensorLock().
Definition: nvmedia_tensor.h:281
NvMediaTensorUnlock
void NvMediaTensorUnlock(NvMediaTensor *tensor)
Unlocks a tensor.
NvMediaTensorSurfaceMap::size
uint32_t size
Total size of the tensor.
Definition: nvmedia_tensor.h:283
NvMediaTensorAttrType
NvMediaTensorAttrType
Defines attribute types for creating NvMedia Tensor.
Definition: nvmedia_tensor.h:94
NvMediaStatus
NvMediaStatus
Defines all possible error codes.
Definition: nvmedia_core.h:108
NVM_TENSOR_ATTR_CPU_ACCESS
@ NVM_TENSOR_ATTR_CPU_ACCESS
Defines the CPU access to tensor.
Definition: nvmedia_tensor.h:102
NvMediaTensorTaskStatus::durationUs
uint32_t durationUs
Duration of the operation in microseconds.
Definition: nvmedia_tensor.h:82
NvMediaVersion
Holds NvMedia version information.
Definition: nvmedia_core.h:168
NVM_TENSOR_ATTR_BITS_PER_ELEMENT
@ NVM_TENSOR_ATTR_BITS_PER_ELEMENT
Defines the tensor bits per element.
Definition: nvmedia_tensor.h:98
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:100
NVMEDIA_TENSOR_ACCESS_WRITE
@ NVMEDIA_TENSOR_ACCESS_WRITE
Write access.
Definition: nvmedia_tensor.h:269
NvMediaTensor
struct NvMediaTensor NvMediaTensor
A handle representing tensor objects.
Definition: nvmedia_tensor.h:88
NVM_TENSOR_ATTR_4D_C
@ NVM_TENSOR_ATTR_4D_C
Defines the number of channels of a 4D tensor.
Definition: nvmedia_tensor.h:110
NVMEDIA_TENSOR_ACCESS_READ
@ NVMEDIA_TENSOR_ACCESS_READ
Read access.
Definition: nvmedia_tensor.h:267
NVM_TENSOR_ATTR_MAX
@ NVM_TENSOR_ATTR_MAX
Defines the maximum number of tensor creation attributes.
Definition: nvmedia_tensor.h:118
NvMediaTensorLockAccess
NvMediaTensorLockAccess
Defines tensor lock access types.
Definition: nvmedia_tensor.h:265
NVMEDIA_TENSOR_ACCESS_READ_WRITE
@ NVMEDIA_TENSOR_ACCESS_READ_WRITE
Read/Write access.
Definition: nvmedia_tensor.h:271
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:285
NVM_TENSOR_ATTR_ALLOC_TYPE
@ NVM_TENSOR_ATTR_ALLOC_TYPE
Defines the allocation type, reserved.
Definition: nvmedia_tensor.h:104
NVM_TENSOR_ATTR_4D_X
@ NVM_TENSOR_ATTR_4D_X
Defines the x value of a 4D tensor.
Definition: nvmedia_tensor.h:116
NvMediaTensorAttr
Holds tensor creation attributes.
Definition: nvmedia_tensor.h:155
NVM_TENSOR_ATTR_DATA_TYPE
@ NVM_TENSOR_ATTR_DATA_TYPE
Specifies the tensor data type.
Definition: nvmedia_tensor.h:96
NvMediaTensorMetaData
Holds the tensor metadata.
Definition: nvmedia_tensormetadata.h:428
NVM_TENSOR_ATTR_4D_H
@ NVM_TENSOR_ATTR_4D_H
Defines the height of a 4D tensor.
Definition: nvmedia_tensor.h:112
NvMediaTensorAttr::value
uint32_t value
Holds tensor creation attribute value.
Definition: nvmedia_tensor.h:159
NvMediaTensorTaskStatus::status
NvMediaStatus status
Holds the return status of the operation as an error code of type - NvMediaStatus.
Definition: nvmedia_tensor.h:80
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:108