Array

Data Structures
struct	VPIArrayData
	Stores information about array characteristics and content. More...

Typedefs
typedef struct VPIArrayImpl *	VPIArray

Functions
VPIStatus	vpiArrayCreate (uint32_t capacity, VPIArrayType fmt, uint32_t flags, VPIArray *array)
	Create an empty array instance with the specified flags. More...
void	vpiArrayDestroy (VPIArray array)
	Destroy an array instance as well as all resources it owns. More...
VPIStatus	vpiArrayWrapHostMem (const VPIArrayData *arrayData, uint32_t flags, VPIArray *array)
	Create an array object by wrapping around an existing host-memory block. More...
VPIStatus	vpiArrayWrapCudaDeviceMem (const VPIArrayData *arrayData, uint32_t flags, VPIArray *array)
	Create an array object by wrapping around an existing device-memory (CUDA) block. More...
VPIStatus	vpiArrayInvalidate (VPIArray array)
	This method is useful for unmanaged arrays only (created with 'vpiArrayWrap*`). More...
VPIStatus	vpiArrayGetSize (VPIArray array, uint32_t *size)
	Get the array size in elements. More...
VPIStatus	vpiArraySetSize (VPIArray array, uint32_t size)
	Set the array size in elements. More...
VPIStatus	vpiArrayGetCapacity (VPIArray array, uint32_t *capacity)
	Get the array capacity in elements. More...
VPIStatus	vpiArrayGetStride (VPIArray array, uint32_t *stride)
	Get the array stride (distance between two consecutive elements) in bytes. More...
VPIStatus	vpiArrayGetFlags (VPIArray array, uint32_t *flags)
	Get the array flags. More...
VPIStatus	vpiArrayGetType (VPIArray array, VPIArrayType *type)
	Get the array type. More...
VPIStatus	vpiArrayLock (VPIArray array, VPILockMode mode, VPIArrayData *arrayData)
	Acquires the lock on array object and returns a pointer to array data. More...
VPIStatus	vpiArrayUnlock (VPIArray array)
	Releases the lock on array object. More...

Array creation flags
#define	VPI_ARRAY_DISABLE_PVA   VPI_BACKEND_DISABLE_PVA
	Array won't be used in a PVA stream.
#define	VPI_ARRAY_DISABLE_CPU   VPI_BACKEND_DISABLE_CPU
	Array won't be used in a CPU stream.
#define	VPI_ARRAY_DISABLE_CUDA   VPI_BACKEND_DISABLE_CUDA
	Array won't be used in a CUDA stream.
#define	VPI_ARRAY_ONLY_PVA   VPI_BACKEND_ONLY_PVA
	Array will only be used in a PVA stream.
#define	VPI_ARRAY_ONLY_CPU   VPI_BACKEND_ONLY_CPU
	Array will only be used in a CPU stream.
#define	VPI_ARRAY_ONLY_CUDA   VPI_BACKEND_ONLY_CUDA
	Array will only be used in a CUDA stream.

Deprecated array creation flags
#define	VPI_ARRAY_NO_PVA   VPI_ARRAY_DISABLE_PVA
	Deprecated.
#define	VPI_ARRAY_NO_CPU   VPI_ARRAY_DISABLE_CPU
	Deprecated.
#define	VPI_ARRAY_NO_CUDA   VPI_ARRAY_DISABLE_CUDA
	Deprecated.

Detailed Description

An abstract representation of a generic 1D array.

There are two ways of creating 1D array containers with the API. The most basic one is to use vpiArrayCreate to allocate and initialize an empty (zeroed) VPIArray object. The memory for the array data is allocated and managed by the backend implementation. Parameters such as capacity format are immutable and specified at the construction time. The internal memory layout is also backend-specific. More importantly, efficient exchange of array data between different hardware blocks might force the implementation to allocate the memory in multiple memory pools (e.g. dGPU and system DRAM). In some scenarios (to optimize performance and memory use) it might be beneficial to constrain the internal allocation policy to support only a particular set of backends. This is implemented with VPI_ARRAY_DISABLE_PVA / VPI_ARRAY_DISABLE_CPU / VPI_ARRAY_DISABLE_CUDA set of flags which are passed during array construction. For example, an array allocated with VPI_ARRAY_DISABLE_CUDA flag set, will not be readable or writable by any CUDA VPIStream instance.

To enable interop with existing host-side code, the user can also create an array object that will wrap user-allocated (and managed) array data. Similarly to vpiArrayCreate, array parameters passed to vpiArrayWrap*() are fixed. To prevent excessive copying, users can point to array data that resides directly in the CUDA device memory with vpiArrayWrapCudaDeviceMem.

The set of vpiArrayLock / vpiArrayUnlock allows to read from/write to the array data from the host. These functions are non-blocking and oblivious to the device command queue so it's up to the user to make sure that all pending operations using this array as input or output are finished. Also, depending on the VPIStream type lock/unlock operation might be time-consuming and, for example, involve copying data over PCIe bus for dGPUs.

---

Data Structure Documentation

VPIArrayData

struct VPIArrayData

Stores information about array characteristics and content.

Definition at line 120 of file Array.h.

Collaboration diagram for VPIArrayData:

Data Fields
uint32_t	capacity	Maximum number of elements that the array can hold.
void *	data	Points to the first element of the array.
uint32_t	size	Number of elements in the array.
uint32_t	stride	Size in bytes of each array element.
VPIArrayType	type	Type of each array element.

Typedef Documentation

VPIArray

typedef struct VPIArrayImpl* VPIArray

#include <vpi/Types.h>

A handle to an array.

Definition at line 146 of file Types.h.

Function Documentation

vpiArrayCreate()

VPIStatus vpiArrayCreate	(	uint32_t	capacity,
		VPIArrayType	fmt,
		uint32_t	flags,
		VPIArray *	array
	)

#include <vpi/Array.h>

Create an empty array instance with the specified flags.

Array data is zeroed. Maximum capacity of the array is fixed and defined at the construction-time.

Parameters

capacity	[in] capacity
fmt	[in] array format
flags	[in] flags
array	[out] pointer to array handle

Returns

an error code on failure else VPI_SUCCESS

vpiArrayDestroy()

void vpiArrayDestroy

(

VPIArray

array

)

#include <vpi/Array.h>

Destroy an array instance as well as all resources it owns.

Parameters

array

[in] array handle

vpiArrayGetCapacity()

VPIStatus vpiArrayGetCapacity	(	VPIArray	array,
		uint32_t *	capacity
	)

#include <vpi/Array.h>

Get the array capacity in elements.

Parameters

array	[in] an array handle
capacity	[out] a pointer to a variable which will be set to the capacity of the array

Returns

an error code on failure else VPI_SUCCESS

vpiArrayGetFlags()

VPIStatus vpiArrayGetFlags	(	VPIArray	array,
		uint32_t *	flags
	)

#include <vpi/Array.h>

Get the array flags.

Parameters

array	[in] an array handle
flags	[out] a pointer to where the flags will be written to

Returns

an error code on failure else VPI_SUCCESS

vpiArrayGetSize()

VPIStatus vpiArrayGetSize	(	VPIArray	array,
		uint32_t *	size
	)

#include <vpi/Array.h>

Get the array size in elements.

Parameters

array	[in] an array handle to a locked array
size	[out] a pointer to a variable which will be set to the size of the array

Returns

an error code on failure else VPI_SUCCESS

vpiArrayGetStride()

VPIStatus vpiArrayGetStride	(	VPIArray	array,
		uint32_t *	stride
	)

#include <vpi/Array.h>

Get the array stride (distance between two consecutive elements) in bytes.

Parameters

array	[in] an array handle
stride	[out] a pointer to a variable which will be set to the stride of the array

Returns

an error code on failure else VPI_SUCCESS

vpiArrayGetType()

VPIStatus vpiArrayGetType	(	VPIArray	array,
		VPIArrayType *	type
	)

#include <vpi/Array.h>

Get the array type.

Parameters

array	[in] an array handle
type	[out] a pointer to where the type will be written to

Returns

an error code on failure else VPI_SUCCESS

vpiArrayInvalidate()

VPIStatus vpiArrayInvalidate

(

VPIArray

array

)

#include <vpi/Array.h>

This method is useful for unmanaged arrays only (created with 'vpiArrayWrap*`).

If the underlying array data has been modified outside the API, use this method to mark the array as invalid. This will force the API to update its internal representation (e.g., re-upload to CUDA memory) when necessary.

Parameters

array

[in] an array handle

Returns

an error code on failure else VPI_SUCCESS

vpiArrayLock()

VPIStatus vpiArrayLock	(	VPIArray	array,
		VPILockMode	mode,
		VPIArrayData *	arrayData
	)

#include <vpi/Array.h>

Acquires the lock on array object and returns a pointer to array data.

Depending on the internal array representation, as well as the actual location in memory, this function might have a significant performance overhead (format conversion, layout conversion, device-to-host memory copy).

Parameters

array	[in] an array handle
mode	[in] Lock mode.
arrayData	[out] a pointer to a variable which will be set to the pointer to the array data

Returns

an error code on failure else VPI_SUCCESS

vpiArraySetSize()

VPIStatus vpiArraySetSize	(	VPIArray	array,
		uint32_t	size
	)

#include <vpi/Array.h>

Set the array size in elements.

Parameters

array	[in] an array handle to a locked array
size	[in] the size of the array

Returns

an error code on failure else VPI_SUCCESS

vpiArrayUnlock()

VPIStatus vpiArrayUnlock

(

VPIArray

array

)

#include <vpi/Array.h>

Releases the lock on array object.

This function might have a significant performance overhead (format conversion, layout conversion, host-to-device memory copy).

Parameters

array

[in] an array handle

Returns

an error code on failure else VPI_SUCCESS

vpiArrayWrapCudaDeviceMem()

VPIStatus vpiArrayWrapCudaDeviceMem	(	const VPIArrayData *	arrayData,
		uint32_t	flags,
		VPIArray *	array
	)

#include <vpi/Array.h>

Create an array object by wrapping around an existing device-memory (CUDA) block.

Stride between elements has to be at least as large as the element structure size. It also has to respect alignment requirements of the element data structure.

Parameters

arrayData	[in] data
flags	[in] flags
array	[out] pointer to an array handle

Returns

an error code on failure else VPI_SUCCESS

vpiArrayWrapHostMem()

VPIStatus vpiArrayWrapHostMem	(	const VPIArrayData *	arrayData,
		uint32_t	flags,
		VPIArray *	array
	)

#include <vpi/Array.h>

Create an array object by wrapping around an existing host-memory block.

Stride between elements has to be at least as large as the element structure size. It also has to respect alignment requirements of the element data structure.

Parameters

arrayData	[in] data
flags	[in] flags
array	[out] pointer to an array handle

Returns

an error code on failure else VPI_SUCCESS