OpenVX Neural Network Extension  7505566
Tensor API

The Tensor API for Deep Convolutional Networks Functions. More...

## Typedefs

typedef struct _vx_tensor_t * vx_tensor
The multidimensional data object (Tensor). More...

typedef struct
The addressing of a tensor view patch structure is used by the Host only to address elements in a tensor view patch. More...

typedef struct _vx_tensor_view_t * vx_tensor_view
The multi dimensional view data structure. More...

## Enumerations

enum  vx_context_attribute_e { VX_CONTEXT_MAX_TENSOR_DIMENSIONS }
A list of context attributes. More...

enum  vx_tensor_attribute_e {
VX_TENSOR_NUM_OF_DIMS = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_TENSOR << 8)) + 0x0,
VX_TENSOR_DIMS = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_TENSOR << 8)) + 0x1,
VX_TENSOR_DATA_TYPE = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_TENSOR << 8)) + 0x2,
VX_TENSOR_FIXED_POINT_POS = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_TENSOR << 8)) + 0x4
}
tensor Data attributes. More...

## Functions

vx_status vxCopyTensorPatch (vx_tensor tensor, vx_tensor_view view, vx_tensor_addressing user_addr, void *user_ptr, vx_enum usage, vx_enum user_mem_type)
Allows the application to copy a view patch from/into an tensor object . More...

vx_object_array vxCreateImageObjectArrayFromTensor (vx_tensor tensor, vx_rectangle_t rect, vx_uint32 array_size, vx_uint32 stride, vx_df_image image_format)
Creates an array of images into the multi-dimension data, this can be a adjacent 2D images or not depending on the stride value. The stride value is representing bytes in the third dimension. The OpenVX image object that points to a three dimension data and access it as an array of images. This has to be portion of the third lowest dimension, and the stride correspond to that third dimension. The returned Object array is an array of images. Where the image data is pointing to a specific memory in the input tensor. More...

vx_tensor vxCreateTensor (vx_context context, vx_uint32 num_of_dims, vx_uint32 *sizes, vx_enum data_format, vx_uint8 fixed_point_pos)
Creates an opaque reference to a tensor data buffer. More...

Create an opaque reference to a tensor addressing object. More...

vx_tensor vxCreateTensorFromView (vx_tensor tensor, vx_tensor_view view)
Creates a tensor data from another tensor data given a view. This second reference refers to the data in the original tensor data. Updates to this tensor data updates the parent tensor data. The view must be defined within the dimensions of the parent tensor data. More...

vx_tensor_view vxCreateTensorView (vx_context context, vx_uint32 *view_array_start, vx_uint32 *view_array_end, vx_uint8 numViewDimensions)
Create an opaque reference to a tensor view object. More...

vx_tensor vxCreateVirtualTensor (vx_graph graph, vx_uint32 num_of_dims, vx_uint32 *sizes, vx_enum data_format, vx_uint8 fixed_point_pos)
Creates an opaque reference to a tensor data buffer with no direct user access. This function allows setting the tensor data dimensions or data format. More...

vx_status vxQueryTensor (vx_tensor tensor, vx_enum attribute, void *ptr, vx_size size)
Retrieves various attributes of a tensor data. More...

vx_status vxReleaseTensor (vx_tensor *tensor)
Releases a reference to a tensor data object. The object may not be garbage collected until its total reference count is zero. More...

Releases a reference to a tensor data addressing object. The object may not be garbage collected until its total reference count is zero. More...

vx_status vxReleaseTensorView (vx_tensor_view *tensor_view)
Releases a reference to a tensor data view object. The object may not be garbage collected until its total reference count is zero. More...

vx_node vxTensorAddNode (vx_graph graph, vx_tensor in1, vx_tensor in2, vx_enum policy, vx_tensor out)
[Graph] Performs arithmetic addition on element values in the input tensor data's. More...

vx_node vxTensorMultiplyNode (vx_graph graph, vx_tensor in1, vx_tensor in2, vx_scalar scale, vx_enum overflow_policy, vx_enum rounding_policy, vx_tensor out)
[Graph] Performs element wise multiplications on element values in the input tensor data's with a scale. More...

vx_node vxTensorSubtractNode (vx_graph graph, vx_tensor in1, vx_tensor in2, vx_enum policy, vx_tensor out)
[Graph] Performs arithmetic subtraction on element values in the input tensor data's. More...

vx_node vxTensorTableLookupNode (vx_graph graph, vx_tensor in1, vx_lut lut, vx_tensor out)
[Graph] Performs LUT on element values in the input tensor data's. More...

vx_node vxTensorTransposeNode (vx_graph graph, vx_tensor in, vx_tensor out, vx_uint32 dim1, vx_uint32 dim2)
[Graph] Performs transpose on the input tensor. The node transpose the tensor according to a specified 2 indexes in the tensor (0-based indexing) More...

## Detailed Description

The Tensor API for Deep Convolutional Networks Functions.

The tensor is a multidimensional opaque object.Since the object have no visibility to the programmer. Vendors can introduce many optimization possibilities. An example of such optimization can be found in the following article.http://arxiv.org/abs/1510.00149

## Typedef Documentation

 typedef struct _vx_tensor_t* vx_tensor

The multidimensional data object (Tensor).

vxCreateTensor

Definition at line 89 of file vx_khr_cnn.h.

The addressing of a tensor view patch structure is used by the Host only to address elements in a tensor view patch.

vxCopyTensorPatch

Definition at line 103 of file vx_khr_cnn.h.

 typedef struct _vx_tensor_view_t* vx_tensor_view

The multi dimensional view data structure.

Used to split tensors into several views. Or concatenate several view into one tensor.

vxCreateTensorFromView

Definition at line 96 of file vx_khr_cnn.h.

## Enumeration Type Documentation

A list of context attributes.

Enumerator
VX_CONTEXT_MAX_TENSOR_DIMENSIONS

tensor Data max num of dimensions supported by HW.

Definition at line 71 of file vx_khr_cnn.h.

tensor Data attributes.

Enumerator
VX_TENSOR_NUM_OF_DIMS

Number of dimensions.

VX_TENSOR_DIMS

Dimension sizes.

VX_TENSOR_DATA_TYPE

tensor Data element data type. vx_type_e

VX_TENSOR_FIXED_POINT_POS

fixed point position when the input element type is int16.

Definition at line 55 of file vx_khr_cnn.h.

## Function Documentation

 vx_status vxCopyTensorPatch ( vx_tensor tensor, vx_tensor_view view, vx_tensor_addressing user_addr, void * user_ptr, vx_enum usage, vx_enum user_mem_type )

Allows the application to copy a view patch from/into an tensor object .

Parameters
 [in] tensor The reference to the tensor object that is the source or the destination of the copy. [in] view Optional parameter of type vx_tensor_view. The coordinates of the view patch. The patch must be within the bounds of the tensor. (start[index],end[index]) gives the coordinates of the view element out of the patch. Must be 0 <= start < end <= number of elements in the tensor dimension. see vxCreateTensorView. If NULL is given instead of the object. Then the function behaves as if view was the size of the full tensor. [in] user_addr The address of a structure describing the layout of the user memory location pointed by user_ptr. In the structure, dim[index], stride[index] fields must be provided, other fields are ignored by the function. The layout of the user memory must follow a row major order. see vxCreateTensorAddressing [in] user_ptr The address of the memory location where to store the requested data if the copy was requested in read mode, or from where to get the data to store into the tensor object if the copy was requested in write mode. The accessible memory must be large enough to contain the specified patch with the specified layout: accessible memory in bytes >= (end[last_dimension] - start[last_dimension]) * stride[last_dimension]. see vxCreateTensorAddressing and vxCreateTensorView. [in] usage This declares the effect of the copy with regard to the tensor object using the vx_accessor_e enumeration. Only VX_READ_ONLY and VX_WRITE_ONLY are supported: VX_READ_ONLY means that data is copied from the tensor object into the application memory VX_WRITE_ONLY means that data is copied into the tensor object from the application memory [in] user_mem_type A vx_memory_type_e enumeration that specifies the memory type of the memory referenced by the user_addr.
Returns
A vx_status_e enumeration.
Return values
 VX_ERROR_OPTIMIZED_AWAY This is a reference to a virtual tensor that cannot be accessed by the application. VX_ERROR_INVALID_REFERENCE The tensor reference is not actually an tensor reference. VX_ERROR_INVALID_PARAMETERS An other parameter is incorrect.
 vx_object_array vxCreateImageObjectArrayFromTensor ( vx_tensor tensor, vx_rectangle_t rect, vx_uint32 array_size, vx_uint32 stride, vx_df_image image_format )

Creates an array of images into the multi-dimension data, this can be a adjacent 2D images or not depending on the stride value. The stride value is representing bytes in the third dimension. The OpenVX image object that points to a three dimension data and access it as an array of images. This has to be portion of the third lowest dimension, and the stride correspond to that third dimension. The returned Object array is an array of images. Where the image data is pointing to a specific memory in the input tensor.

Parameters
 [in] tensor The tensor data from which to extract the images. Has to be a 3d tensor. [in] rect Image coordinates within tensor data. [in] array_size Number of images to extract. [in] stride Delta between two images in the array. [in] image_format The requested image format. Should match the tensor data's data type.
Returns
An array of images pointing to the tensor data's data.
 vx_tensor vxCreateTensor ( vx_context context, vx_uint32 num_of_dims, vx_uint32 * sizes, vx_enum data_format, vx_uint8 fixed_point_pos )

Creates an opaque reference to a tensor data buffer.

Not guaranteed to exist until the vx_graph containing it has been verified.

Parameters
 [in] context The reference to the implementation context. [in] num_of_dims The number of dimensions. [in] sizes Dimensions sizes in elements. [in] data_format The vx_type_t that represents the data type of the tensor data elements. [in] fixed_point_pos Specifies the fixed point position when the input element type is int16, if 0 calculations are performed in integer math
Returns
A tensor data reference or zero when an error is encountered.

Create an opaque reference to a tensor addressing object.

Not guaranteed to exist until the vx_graph containing it has been verified.

Parameters
 [in] context The reference to the implementation context. [in] addressing_array_dimension a vx_uint32 array of sLength of patch in all dimensions in elements. [in] addressing_array_stride a vx_uint32 arrayStride in all dimensions in bytes. [in] numViewDimensions number of dimensions of view_array_start and view_array_end.
Returns
A tensor data view reference or zero when an error is encountered.
 vx_tensor vxCreateTensorFromView ( vx_tensor tensor, vx_tensor_view view )

Creates a tensor data from another tensor data given a view. This second reference refers to the data in the original tensor data. Updates to this tensor data updates the parent tensor data. The view must be defined within the dimensions of the parent tensor data.

Parameters
 [in] tensor The reference to the parent tensor data. [in] view The region of interest of a tensor view. Must contain points within the parent tensor data dimensions. vx_tensor_view
Returns
The reference to the sub-tensor or zero if the view is invalid.
 vx_tensor_view vxCreateTensorView ( vx_context context, vx_uint32 * view_array_start, vx_uint32 * view_array_end, vx_uint8 numViewDimensions )

Create an opaque reference to a tensor view object.

Not guaranteed to exist until the vx_graph containing it has been verified.

Parameters
 [in] context The reference to the implementation context. [in] view_array_start a vx_uint32 array of start values of the view. [in] view_array_end a vx_uint32 array of end values of the view. [in] numViewDimensions number of dimensions of view_array_start and view_array_end.
Returns
A tensor data view reference or zero when an error is encountered.
 vx_tensor vxCreateVirtualTensor ( vx_graph graph, vx_uint32 num_of_dims, vx_uint32 * sizes, vx_enum data_format, vx_uint8 fixed_point_pos )

Creates an opaque reference to a tensor data buffer with no direct user access. This function allows setting the tensor data dimensions or data format.

Virtual data objects allow users to connect various nodes within a graph via data references without access to that data, but they also permit the implementation to take maximum advantage of possible optimizations. Use this API to create a data reference to link two or more nodes together when the intermediate data are not required to be accessed by outside entities. This API in particular allows the user to define the tensor data format of the data without requiring the exact dimensions. Virtual objects are scoped within the graph they are declared a part of, and can't be shared outside of this scope.

Parameters
 [in] graph The reference to the parent graph. [in] num_of_dims The number of dimensions. [in] sizes Dimensions sizes in elements. [in] data_format The vx_type_t that represents the data type of the tensor data elements. [in] fixed_point_pos Specifies the fixed point position when the input element type is int16, if 0 calculations are performed in integer math
Returns
A tensor data reference or zero when an error is encountered.
Note
Passing this reference to vxCopyTensorPatch will return an error.
 vx_status vxQueryTensor ( vx_tensor tensor, vx_enum attribute, void * ptr, vx_size size )

Retrieves various attributes of a tensor data.

Parameters
 [in] tensor The reference to the tensor data to query. [in] attribute The attribute to query. Use a vx_tensor_attribute_e. [out] ptr The location at which to store the resulting value. [in] size The size of the container to which ptr points.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors. VX_ERROR_INVALID_REFERENCE If data is not a vx_tensor. VX_ERROR_INVALID_PARAMETERS If any of the other parameters are incorrect.
 vx_status vxReleaseTensor ( vx_tensor * tensor )

Releases a reference to a tensor data object. The object may not be garbage collected until its total reference count is zero.

Parameters
 [in] tensor The pointer to the tensor data to release.
Postcondition
After returning from this function the reference is zeroed.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors. VX_SUCCESS Success * An error occurred. See vx_status_e.

Releases a reference to a tensor data addressing object. The object may not be garbage collected until its total reference count is zero.

Parameters
Postcondition
After returning from this function the reference is zeroed.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors. VX_SUCCESS Success * An error occurred. See vx_status_e.
 vx_status vxReleaseTensorView ( vx_tensor_view * tensor_view )

Releases a reference to a tensor data view object. The object may not be garbage collected until its total reference count is zero.

Parameters
 [in] tensor_view The pointer to the tensor data view to release.
Postcondition
After returning from this function the reference is zeroed.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors. VX_SUCCESS Success * An error occurred. See vx_status_e.
 vx_node vxTensorAddNode ( vx_graph graph, vx_tensor in1, vx_tensor in2, vx_enum policy, vx_tensor out )

[Graph] Performs arithmetic addition on element values in the input tensor data's.

Parameters
 [in] graph The handle to the graph. [in] in1 input tensor data,. [in] in2 input tensor data, inputs must be of equal in dimensions. else, If in one of the vx_mddata dimension is 1. That dimension is considered as a const on all the dimension terms. And will perform as if the values are duplicated on all terms in that dimensions. After the expansion. The dimensions are equal. [in] policy A vx_convert_policy_e enumeration. [out] out The output tensor data with the same dimensions as the input tensor data's.
Returns
 vx_node.
Return values
 0 Node could not be created. * Node handle.
 vx_node vxTensorMultiplyNode ( vx_graph graph, vx_tensor in1, vx_tensor in2, vx_scalar scale, vx_enum overflow_policy, vx_enum rounding_policy, vx_tensor out )

[Graph] Performs element wise multiplications on element values in the input tensor data's with a scale.

Parameters
 [in] graph The handle to the graph. [in] in1 input tensor data. [in] in2 input tensor data, inputs must be of equal in dimensions. else, If in one of the vx_mddata dimension is 1. That dimension is considered as a const on all the dimension terms. And will perform as if the values are duplicated on all terms in that dimensions. After the expansion. The dimensions are equal. [in] scale The scale value. [in] overflow_policy A vx_convert_policy_e enumeration. [in] rounding_policy A vx_round_policy_e enumeration. [out] out The output tensor data with the same dimensions as the input tensor data's.
Returns
 vx_node.
Return values
 0 Node could not be created. * Node handle.
 vx_node vxTensorSubtractNode ( vx_graph graph, vx_tensor in1, vx_tensor in2, vx_enum policy, vx_tensor out )

[Graph] Performs arithmetic subtraction on element values in the input tensor data's.

Parameters
 [in] graph The handle to the graph. [in] in1 input tensor data. [in] in2 input tensor data, inputs must be of equal in dimensions. else, If in one of the vx_mddata dimension is 1. That dimension is considered as a const on all the dimension terms. And will perform as if the values are duplicated on all terms in that dimensions. After the expansion. The dimensions are equal. [in] policy A vx_convert_policy_e enumeration. [out] out The output tensor data with the same dimensions as the input tensor data's.
Returns
 vx_node.
Return values
 0 Node could not be created. * Node handle.
 vx_node vxTensorTableLookupNode ( vx_graph graph, vx_tensor in1, vx_lut lut, vx_tensor out )

[Graph] Performs LUT on element values in the input tensor data's.

Parameters
 [in] graph The handle to the graph. [in] in1 input tensor data. [in] lut of type vx_lut [out] out The output tensor data with the same dimensions as the input tensor data's.
Returns
 vx_node.
Return values
 0 Node could not be created. * Node handle.
 vx_node vxTensorTransposeNode ( vx_graph graph, vx_tensor in, vx_tensor out, vx_uint32 dim1, vx_uint32 dim2 )

[Graph] Performs transpose on the input tensor. The node transpose the tensor according to a specified 2 indexes in the tensor (0-based indexing)

Parameters
 [in] graph The handle to the graph. [in] in input tensor data, [out] out output tensor data, [in] dim1 that is transposed with dim 2. [in] dim2 that is transposed with dim 1.
Returns
 vx_node.
Return values
 0 Node could not be created. * Node handle.