NvMedia Array

This topic explains how to use the NvMedia Array API.
NvMedia Array component provides interfaces to allocate and deallocate one-dimensional data. It consists of a set of APIs and attributes for the user to create a one-dimensional array of various types of data elements using NvSciBuf APIs. This component also provides the interfaces to manage memory locks on array for applications to access the array memory.
This topic assumes that you have a basic understanding of NvSciBuf. See Buffer Allocation for more information.
NvMedia arrays are used with NvMedia Vision Programming Interface (VPI) components.
NvMedia arrays can be created as follows:
Use NvSciBuf APIs to allocate arrays with NvMedia array attributes. Since NvSciBuf APIs facilitates data sharing between NvMedia and NVIDIA® CUDA®, the allocated arrays are accessible by the NvSciBuf APIs. See the Buffer Allocation API documentation for more information.

NvMedia Array Attributes

The following sections describe the array format attributes that NvMedia arrays may have.
Data Type Attribute
Array data type specified by one of following supported array attributes.
Data Type Attribute
Data Type
NVMEMDIA_ARRAY_TYPE_INT8
8-bit signed integer
NVMEMDIA_ARRAY_TYPE_UINT8
8-bit unsigned integer
NVMEMDIA_ARRAY_TYPE_UINT16
16-bit unsigned integer
NVMEMDIA_ARRAY_TYPE_INT16
16-bit signed integer
NVMEMDIA_ARRAY_TYPE_UINT32
32-bit unsigned integer
NVMEMDIA_ARRAY_TYPE_INT32
32-bit signed integer
NVMEMDIA_ARRAY_TYPE_FLOAT32
32-bit floating point
NVM_ARRAY_ATTR_CPU_ACCESS Attribute
Specifies the coherency policy to be used for array accesses from the CPU. The value may be:
NVM_ARRAY_ATTR_CPU_ACCESS_UNCACHED
Specifies that accesses from the CPU never cache data.
Setting this attribute results in the following behavior:
While writing to the array buffers from the CPU using NvMediaArrayLock() and NvMediaArrayUnlock(), NvMedia uses appropriate memory barriers before handing over the array buffer to hardware engines to ensure coherency.
NVM_ARRAY_ATTR_CPU_ACCESS_CACHED
Specifies that accesses from the CPU can pass through caches and store buffers.
Setting this attribute results in the following behavior:
While reading the array from the CPU using NvMediaArrayLock() and NvMediaArrayUnlock(), caches are invalidated as necessary to ensure that the CPU gets the latest data written by the hardware engines.
While writing the array from the CPU using NvMediaArrayLock() and NvMediaArrayUnlock(), caches are flushed as necessary before handing over the array buffers to hardware engines to ensure coherency.
In the cases above, the array memory is mapped, and it can be accessed with a mapping into the current process’s virtual address space.
If the attribute is not specified, the coherency policy defaults to NVM_ARRAY_ATTR_CPU_ACCESS_UNCACHED.

Array API Functions

This section describes NvMedia Array API functions that create a handle from NvSciBuf, destroy, and manage arrays.

NvMedia Array Creation and Destroy Functions

These API functions create and destroy arrays.
NvMediaArrayCreateFromNvSciBuf()
Creates an NvMedia Array handle from an NvSciBuf created with the NvSciBuf API, after the required NvSciBuf attributes list is prepared.
Every hardware engine in an NVIDIA SoC can have a different alignment or stride constraints. Hence, sharing a buffer across various engines requires that buffer allocation satisfy the constraints of all of the engines that share the buffer. An engine whose constraints are not satisfied may fail to operate on the buffer. The allocation functions provided by the various NvMedia drivers only satisfy the constraints of the engines that are visible to them, and so cannot be used to allocate shared buffers.
NvSciBuf is a buffer allocation module that satisfies a common set of constraints that are compatible with all of the hardware engines. It thus can allocate buffers that are shareable across the hardware engines visible to various drivers.
This is a typical flow to allocate an NvSciBufObj, which can be mapped to an NvMediaArray:
1. The application creates an NvSciBufAttrList.
2. The application queries NvMedia to fill the NvSciBufAttrList by passing a set of NvMediaArray allocation attributes and an NvMediaType as input to NvMediaArrayFillNvSciBufAttrs().
3. The application may set any of the public NvSciBufAttribute values that NvMedia does not set.
For more details on NvSciBuf concepts, terminology, and the API, see Buffer Allocation User Guide.
The following NvSciBuf input attributes are set by NvMedia, and so must not be set by the application:
NvSciBufGeneralAttrKey_Types
NvSciBufGeneralAttrKey_NeedCpuAccess
NvSciBufGeneralAttrKey_EnableCpuCache
NvSciBufArrayAttrKey_DataType
NvSciBufArrayAttrKey_Stride
NvSciBufArrayAttrKey_Capacity
NvSciBufArrayAttrKey_Size
NvSciBufArrayAttrKey_Alignment
The following attributes are not set by NvMedia and so must be set by the application:
NvSciBufGeneralAttrKey_RequiredPerm
4. If the same NvSciBufObj object has to be shared with other user mode drivers (UMDs), the application can get the corresponding NvSciBufAttrList from the respective UMDs.
5. The application asks NvSciBuf to reconcile all of the filled NvSciBufAttrList objects, then allocate an NvSciBuf Object.
6. The application queries NvMedia to create an NvMediaArray from the allocated NvSciBuf Object by invoking NvMediaArrayCreateFromNvSciBuf().
7. The NvMediaArray can be passed as input and output to any of the NvMedia API functions that accept an NvMediaArray as a parameter.
Example: NvMedia Array Allocation with NvSciBuf
This is an example of how to allocate an NvMedia srray with NvSciBuf:
NvMediaDevice *device;
NvMediaStatus status;
NvSciError err;
NvSciBufModule module;
NvSciBufAttrList attrlist;
NvSciBufAttrList conflictlist;
NvSciBufObj bufObj;
NvMediaArray *array;
 
/*NvMedia related initialization. */
device = NvMediaDeviceCreate();
 
status = NvMediaArrayNvSciBufInit();
 
/*NvSciBuf related initialization. */
err = NvSciBufModuleOpen(&module);
NvSciBufAttrKeyValuePair attr_kvp = {NvSciBufGeneralAttrKey_RequiredPerm, &access_perm,
sizeof(access_perm)};
 
/*Create NvSciBuf attribute list. */
err = NvSciBufAttrListCreate(module, &attrlist);
err = NvSciBufAttrListSetAttrs(attrlist, &attr_kvp, 1);
 
/* Initialize ArrayAttrs as required. */
type = NVMEDIA_ARRAY_TYPE_UINT32;
Stride = REQUIRED_STRIDE;
numElements = REQUIRED_NUMELM;
/* Ask NvMedia to fill NvSciBufAttrs corresponding to
ArrayAttrs. */
 
status = NvMediaArrayFillNvSciBufAttrs(device,
type,
stride,
numElements,
arrayAttr,
numAllocAttr,
attrlist);
 
 
/* Reconcile the NvSciBufAttrs and then allocate an NvSciBufObj. */
err = NvSciBufAttrListReconcileAndObjAlloc(&attrlist, 1, bufobj, &conflictlist);
/* Create NvMediaImage from NvSciBufObj. */
status = NvMediaArrayCreateFromNvSciBuf(device, bufobj, &Array);
/* Free the NvSciBufAttrList which is no longer required. */
err = NvSciBufAttrListFree(attrlist);
/* Use the Array as input or output as supported. */
....
....
/* Free the resources after use. */
/* Destroy NvMediaArray. */
NvMediaArrayDestroy(array);
/* NvMedia related Deinit. */
NvMediaArrayNvSciBufDeinit();
NvMediaDeviceDestroy(device);
/* NvSciBuf related deinit. */
NvSciBufObjFree(bufobj);
NvSciBufModuleClose(module);
NvMediaArrayDestroy()
Destroys the previously allocated NvMedia Array object.
Example:
if (array) {
NvMediaArrayDestroy(array);
}