Detailed Description

APIs for application interface accessible only on host.

Modules
	Raw Image Data Type APIs
	APIs creating and using raw image data type.

	Super Node Framework Type APIs
	APIs creating and using super node framework type.

	Kernel Helper APIs
	Helper APIs used used for host side kernel validation.

	Utility APIs
	Utility APIs available for the application running on the host.

	Platform OSAL APIs
	Platform operating system abstraction layer on the host.

	Debug APIs
	APIs for debug operations on the host.

	Real-time Trace APIs
	APIs for real-time event trace operations on the host.

	Resource Logging APIs
	APIs for resource logging on the host.

Defines
#define	TIVX_TARGET_MAX_NAME (64u)
	Max possible name of a target.

#define	TIVX_TARGET_HOST "HOST"
	String to name a OpenVX Host. More...

#define	TIVX_CONFIG_PATH_LENGTH (512u)
	Max size of config file path.

#define	TIVX_CONTROL_CMD_SEND_TO_ALL_REPLICATED_NODES ((uint32_t)-1)
	When sending a control command to a replicated node, this can be used to send control command to all replicated node. More...

#define	TIVX_MAX_CONFIG_PARAM_OBJECTS (12u)
	Max number of data objects that contribute to a configuration parameter's memory footprint.

#define	TIVX_CONFIG_PARAM_OBJECT_TYPE_DIM (2u)
	Number of dimensions of a configuration parameter's object type array.

#define	dimof(x) (sizeof(x)/sizeof(x[0]))
	Macro to find size of array.

Enumerations
enum	tivx_attribute_extensions_e { TIVX_NODE_TARGET_STRING = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x0, TIVX_USER_DATA_OBJECT_VALID_SIZE = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x1, TIVX_REFERENCE_TIMESTAMP = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x2, TIVX_REFERENCE_INVALID = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x3, TIVX_GRAPH_STREAM_EXECUTIONS = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x4, TIVX_KERNEL_TIMEOUT = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x5, TIVX_NODE_TIMEOUT = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x6, TIVX_GRAPH_TIMEOUT = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x7, TIVX_GRAPH_PIPELINE_DEPTH = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x8, TIVX_CONTEXT_NUM_USER_KERNEL_ID = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0x9, TIVX_IMAGE_IMAGEPATCH_ADDRESSING = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0xa, TIVX_TENSOR_STRIDES = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0xb, TIVX_CONTEXT_NUM_USER_LIBRARY_ID = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0xc, TIVX_NODE_IS_TIMED_OUT = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0xd, TIVX_REFERENCE_BUFFER_IS_ALLOCATED = VX_ATTRIBUTE_BASE(VX_ID_TI, (vx_enum)0) + 0xe }
	TI attribute extensions. More...

enum	tivx_df_image_e { TIVX_DF_IMAGE_P12 = VX_DF_IMAGE('P','0','1','2'), TIVX_DF_IMAGE_NV12_P12 = VX_DF_IMAGE('N','1','2','P'), TIVX_DF_IMAGE_RGB565 = VX_DF_IMAGE('R','5','6','5'), TIVX_DF_IMAGE_BGRX = VX_DF_IMAGE('B','G','R','A') }
	Based on the VX_DF_IMAGE definition. More...

enum	tivx_status_e { TIVX_STATUS_BASE = -(vx_int32)100, TIVX_ERROR_EVENT_TIMEOUT = (vx_int32)(TIVX_STATUS_BASE) + 1 }
	The enumeration of all TIVX operational error codes. More...

enum	tivx_memory_logging_e { TIVX_MEM_LOG_DEFAULT = 0, TIVX_MEM_LOG_OBJECT_DESCRIPTOR = 1, TIVX_MEM_LOG_GLOBAL = 2, TIVX_MEM_LOG_ALL = 3 }
	Enumerations of memory consumption tool's display modes. More...

Functions
void	tivxInit (void)
	Function to initialize OpenVX framework. More...

void	tivxDeInit (void)
	Function to de-initialize OpenVX framework. More...

void	tivxHostInit (void)
	Function to initialize OpenVX HOST side functionality. More...

void	tivxHostDeInit (void)
	Function to de-initialize OpenVX HOST side functionality. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxAddKernelTarget (vx_kernel kernel, const char *target_name)
	Associate a target with a kernel. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxSetKernelSinkDepth (vx_kernel kernel, uint32_t num_sink_bufs)
	Set the number of sink buffers. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxRegisterModule (const char *name, vx_publish_kernels_f publish, vx_unpublish_kernels_f unpublish)
	Register publish and unpublish functions against a module name. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxUnRegisterModule (const char *name)
	UnRegister publish and unpublish functions if previously registered. More...

vx_enum	tivxGetSelfCpuId (void)
	Return CPU ID of the CPU on which this API is called. More...

vx_node	tivxCreateNodeByKernelEnum (vx_graph graph, vx_enum kernelenum, vx_reference params[], vx_uint32 num)
	Utility function to create a node given parameter references and kernel enum. More...

vx_node	tivxCreateNodeByKernelRef (vx_graph graph, vx_kernel kernel, vx_reference params[], vx_uint32 num)
	Utility function to create a node given parameter references and kernel reference. More...

vx_node	tivxCreateNodeByKernelName (vx_graph graph, const char *kernel_name, vx_reference params[], vx_uint32 num)
	Utility function to create a node given parameter references and kernel name. More...

vx_bool	tivxIsReferenceVirtual (vx_reference ref)
	Utility function to check if the given reference is virtual or not. More...

vx_reference	tivxGetReferenceParent (vx_reference child_ref)
	Utility function to extract the parent reference from an element. More...

vx_bool	tivxIsTargetEnabled (const char target_name[])
	Utility function to know if target is enabled or not. More...

uint64_t	tivxPlatformGetTimeInUsecs (void)
	Get the time in micro seconds. More...

vx_status VX_API_CALL	tivxSetNodeParameterNumBufByIndex (vx_node node, vx_uint32 idx, vx_uint32 num_buf)
	Set number of buffers to allocate at output of a node parameter. More...

vx_status VX_API_CALL	tivxGetNodeParameterNumBufByIndex (vx_node node, vx_uint32 idx, vx_uint32 *num_buf)
	Get number of buffers to allocate at output of a node parameter. More...

vx_status VX_API_CALL	tivxSetGraphPipelineDepth (vx_graph graph, vx_uint32 pipeline_depth)
	Indicates to the implementation the depth of the graph pipeline. More...

vx_status VX_API_CALL	tivxNodeSendCommand (vx_node node, uint32_t replicate_nodex_idx, uint32_t node_cmd_id, vx_reference ref[], uint32_t num_refs)
	Send node specific Control command. More...

vx_status VX_API_CALL	tivxNodeSendCommandTimed (vx_node node, uint32_t replicate_nodex_idx, uint32_t node_cmd_id, vx_reference ref[], uint32_t num_refs, uint32_t timeout)
	Send node specific Control command. More...

vx_node	tivxGraphGetNode (vx_graph graph, uint32_t idx)
	This API is used to get a reference to a node within a graph at a given index within the graph. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxSetUserDataObjectAttribute (vx_user_data_object user_data_object, vx_enum attribute, const void *ptr, vx_size size)
	Sets attributes on the user data object. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxSetNodeTileSize (vx_node node, vx_uint32 block_width, vx_uint32 block_height)
	Sets the tile size for a given node in a graph. This is only valid for BAM-enabled kernels on C66 DSP. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxSetReferenceAttribute (vx_reference ref, vx_enum attribute, const void *ptr, vx_size size)
	Sets reference attributes for the below enums: TIVX_REFERENCE_TIMESTAMP. More...

VX_API_ENTRY vx_bool VX_API_CALL	tivxIsReferenceMetaFormatEqual (vx_reference ref1, vx_reference ref2)
	Check for equivalence between the meta formats of two reference objects. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxReferenceImportHandle (vx_reference ref, const void *addr[], const uint32_t size[], uint32_t num_entries)
	Updates a reference object with the supplied handles (pointers to memory). More...

VX_API_ENTRY vx_status VX_API_CALL	tivxReferenceExportHandle (const vx_reference ref, void addr[], uint32_t size[], uint32_t max_num_entries, uint32_t num_entries)
	Exports the handles from a reference object. More...

VX_API_ENTRY vx_reference VX_API_CALL	tivxCreateReferenceFromExemplar (vx_context context, vx_reference exemplar)
	Create reference from a exemplar object. More...

Macro Definition Documentation

◆ TIVX_TARGET_HOST

#define TIVX_TARGET_HOST "HOST"

String to name a OpenVX Host.

Host is not a unique target on its own. At system config "HOST" will map to one of available targets

Definition at line 104 of file tivx.h.

◆ TIVX_CONTROL_CMD_SEND_TO_ALL_REPLICATED_NODES

#define TIVX_CONTROL_CMD_SEND_TO_ALL_REPLICATED_NODES ((uint32_t)-1)

When sending a control command to a replicated node, this can be used to send control command to all replicated node.

Currently used as parameter in tivxNodeSendCommand API

Definition at line 128 of file tivx.h.

Enumeration Type Documentation

◆ tivx_attribute_extensions_e

enum tivx_attribute_extensions_e

TI attribute extensions.

TI attribute extensions to OpenVX

Enumerator
TIVX_NODE_TARGET_STRING	Returns the target string corresponding to the node.
TIVX_USER_DATA_OBJECT_VALID_SIZE	Sets the valid data size within the user data object.
TIVX_REFERENCE_TIMESTAMP	Returns the timestamp in micro-seconds corresponding to the given reference.
TIVX_REFERENCE_INVALID	Returns a boolean indicating whether or not a reference is invalid.
TIVX_GRAPH_STREAM_EXECUTIONS	Returns the graph stream executions. Read-only. Use a `vx_uint32` parameter.
TIVX_KERNEL_TIMEOUT	Set/Query the kernel level timeout parameter. Read-Write. Can be written at initialization as well as at runtime. Use a `vx_uint32` parameter. Refer to TIVX_DEFAULT_KERNEL_TIMEOUT for details on the default value used for this attribute.
TIVX_NODE_TIMEOUT	Set/Query the node level timeout parameter. Read-Write. Can be written at initialization as well as at runtime. This timeout attribute affects the operation of the node CREATE and DELETE target kernel functions. Use a `vx_uint32` parameter. Refer to TIVX_DEFAULT_KERNEL_TIMEOUT for details on the default value used for this attribute.
TIVX_GRAPH_TIMEOUT	Set/Query the graph level timeout parameter. Read-Write. Can be written at initialization as well as at runtime. This timeout attribute affects the operation of the following APIs. vxWaitGraph() vxGraphParameterDequeueDoneRef() vxStopGraphStreaming() Use a `vx_uint32` parameter. Refer to TIVX_DEFAULT_GRAPH_TIMEOUT for details on the default value used for this attribute.
TIVX_GRAPH_PIPELINE_DEPTH	Query the graph pipeline depth. Read-Only. Can be read at initialization as well as at runtime. Use a `vx_uint32` parameter. By default, this value is set to 1.
TIVX_CONTEXT_NUM_USER_KERNEL_ID	Query the context number of user kernel ID's. Read-Only. Can be read at initialization as well as at runtime. Use a `vx_uint32` parameter. By default, this value is set to 0.
TIVX_IMAGE_IMAGEPATCH_ADDRESSING	Query the imagepatch addressing structure from a vx_image. Read-Only. Can be read at initialization as well as at runtime. Use a `vx_imagepatch_addressing_t[TIVX_IMAGE_MAX_PLANES]` parameter.
TIVX_TENSOR_STRIDES	Query the strides from a vx_tensor object. Read-Only. Can be read at initialization as well as at runtime. Use an array of `vx_size * VX_TENSOR_NUMBER_OF_DIMS` parameter.
TIVX_CONTEXT_NUM_USER_LIBRARY_ID	Query the context number of user library ID's. Read-Only. Can be read at initialization as well as at runtime. Use a `vx_uint32` parameter. By default, this value is set to 0.
TIVX_NODE_IS_TIMED_OUT	Query the node to see if it has timed out. Read-Only. Can be read at initialization as well as at runtime. Use a `vx_bool` parameter. Refer to TIVX_DEFAULT_KERNEL_TIMEOUT for more details about node timeouts.
TIVX_REFERENCE_BUFFER_IS_ALLOCATED	Query the reference to see if the associated buffer has been allocated. Note that this is only applicable in the case that the buffer has been allocated by the framework. It does update if the buffer has been imported to or exported from the vx_reference. Read-Only. Can be read at initialization as well as at runtime. Use a `vx_bool` parameter.

Definition at line 226 of file tivx.h.

◆ tivx_df_image_e

enum tivx_df_image_e

Based on the VX_DF_IMAGE definition.

Note: Use vx_df_image to contain these values.

Enumerator
TIVX_DF_IMAGE_P12	A single plane of packed 12-bit data. The stride_x for this data format must be set to 0
TIVX_DF_IMAGE_NV12_P12	a NV12 frame of packed 12-bit data. The stride_x for this data format must be set to 0
TIVX_DF_IMAGE_RGB565	A single plane of packed 16-bit RGB565 data. The stride_x for this data format must be set to 2
TIVX_DF_IMAGE_BGRX	A single plane of 32-bit pixel as 4 interleaved 8-bit units of B then G then R data, then a don't care byte. This uses the BT709 full range by default.

Definition at line 330 of file tivx.h.

◆ tivx_status_e

enum tivx_status_e

The enumeration of all TIVX operational error codes.

Enumerator
TIVX_STATUS_BASE	Indicates the base for the TIVX error codes. Used for bounds checks only.
TIVX_ERROR_EVENT_TIMEOUT	Indicates that the wait operation on an event timed-out.

Definition at line 357 of file tivx.h.

◆ tivx_memory_logging_e

enum tivx_memory_logging_e

Enumerations of memory consumption tool's display modes.

Enumerator
TIVX_MEM_LOG_DEFAULT	Default display mode; Outputs only total global and obj desc memory.
TIVX_MEM_LOG_OBJECT_DESCRIPTOR	Obj Desc display mode; Outputs only the object descriptor memory info.
TIVX_MEM_LOG_GLOBAL	Global display mode; Outputs only the TIOVX global memory info.
TIVX_MEM_LOG_ALL	All display mode; Outputs all possible information.

Definition at line 568 of file tivx.h.

Function Documentation

◆ tivxInit()

void tivxInit ( void )

Function to initialize OpenVX framework.

Should be called during system init on all OpenVX HOST as well as OpenVX target CPUs

NOTE: In Vision SDK, this function is called during VIsion SDK system init so user need not call this explicitly

◆ tivxDeInit()

void tivxDeInit ( void )

Function to de-initialize OpenVX framework.

Should be called during system init on all OpenVX HOST as well as OpenVX target CPUs

NOTE: In Vision SDK, this function is called during VIsion SDK system init so user need not call this explicitly

◆ tivxHostInit()

void tivxHostInit ( void )

Function to initialize OpenVX HOST side functionality.

Should be called during system init after tivxInit() on HOST CPUs only

NOTE: In Vision SDK, this function is called during VIsion SDK system init so user need not call this explicitly

◆ tivxHostDeInit()

void tivxHostDeInit ( void )

Function to de-initialize OpenVX HOST side functionality.

Should be called during system init before tivxDeInit() on HOST CPUs only

NOTE: In Vision SDK, this function is called during VIsion SDK system init so user need not call this explicitly

◆ tivxAddKernelTarget()

VX_API_ENTRY vx_status VX_API_CALL tivxAddKernelTarget	(	vx_kernel	kernel,
		const char *	target_name
	)

Associate a target with a kernel.

Call multiple times for each supported target

If given target is not valid on current platform then error VX_ERROR_NOT_SUPPORTED is returned.

Typically VX_ERROR_NOT_SUPPORTED error should be ignored for this API, since this code is typically kept same across platforms

During graph verify however if user asks to run the kernel on a target not supported by this platform it results in a error and graph cannot execute.

◆ tivxSetKernelSinkDepth()

VX_API_ENTRY vx_status VX_API_CALL tivxSetKernelSinkDepth	(	vx_kernel	kernel,
		uint32_t	num_sink_bufs
	)

Set the number of sink buffers.

Parameters

[in]	kernel	Kernel reference
[in]	num_sink_bufs	Number of sink buffers

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	kernel is not a valid reference

◆ tivxRegisterModule()

VX_API_ENTRY vx_status VX_API_CALL tivxRegisterModule	(	const char *	name,
		vx_publish_kernels_f	publish,
		vx_unpublish_kernels_f	unpublish
	)

Register publish and unpublish functions against a module name.

These functions are invoked when vxLoadKernels is called with the registered name.

This is alternative instead of dynamically loading kernels during vxLoadKernels

Duplicate module names not checked by this API.

API is not reentrant, user is recommended to call all tivxRegisterModule during system init before vxCreateContext() from a single thread.

Modules registered against TIVX_MODULE_NAME are called during vxCreateContext so user MUST ensure tivxRegisterModule() is called for TIVX_MODULE_NAME module

◆ tivxUnRegisterModule()

VX_API_ENTRY vx_status VX_API_CALL tivxUnRegisterModule ( const char * name )

UnRegister publish and unpublish functions if previously registered.

Parameters

[in] name Module name to unregister

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_FAILURE	Unable to find module "name" in list of registered modules

◆ tivxGetSelfCpuId()

vx_enum tivxGetSelfCpuId ( void )

Return CPU ID of the CPU on which this API is called.

Returns: A vx_emum enumeration of the CPU_ID.

◆ tivxCreateNodeByKernelEnum()

vx_node tivxCreateNodeByKernelEnum	(	vx_graph	graph,
		vx_enum	kernelenum,
		vx_reference	params[],
		vx_uint32	num
	)

Utility function to create a node given parameter references and kernel enum.

Parameters

[in]	graph	Graph reference
[in]	kernelenum	Enumeration specifying a specific kernel
[in]	params	List of parameter references corresponding to the enumerated kernel
[in]	num	Number of parameter references in params list

Returns: A node reference vx_node. Any possible errors preventing a successful creation should be checked using vxGetStatus.

◆ tivxCreateNodeByKernelRef()

vx_node tivxCreateNodeByKernelRef	(	vx_graph	graph,
		vx_kernel	kernel,
		vx_reference	params[],
		vx_uint32	num
	)

Utility function to create a node given parameter references and kernel reference.

Parameters

[in]	graph	Graph reference
[in]	kernel	Kernel reference
[in]	params	List of parameter references corresponding to the kernel reference
[in]	num	Number of parameter references in params list

Returns: A node reference vx_node. Any possible errors preventing a successful creation should be checked using vxGetStatus.

◆ tivxCreateNodeByKernelName()

vx_node tivxCreateNodeByKernelName	(	vx_graph	graph,
		const char *	kernel_name,
		vx_reference	params[],
		vx_uint32	num
	)

Utility function to create a node given parameter references and kernel name.

Parameters

[in]	graph	Graph reference
[in]	kernel_name	String corresponding to the kernel name
[in]	params	List of parameter references corresponding to the kernel name
[in]	num	Number of parameter references in params list

Returns: A node reference vx_node. Any possible errors preventing a successful creation should be checked using vxGetStatus.

◆ tivxIsReferenceVirtual()

vx_bool tivxIsReferenceVirtual ( vx_reference ref )

Utility function to check if the given reference is virtual or not.

Parameters

[in] ref Reference to query

Returns: A vx_bool value.

Return values

vx_true_e	The reference is virtual.
vx_false_e	The reference is not virtual.

◆ tivxGetReferenceParent()

vx_reference tivxGetReferenceParent ( vx_reference child_ref )

Utility function to extract the parent reference from an element.

Parameters

[in] child_ref Child reference to query

Returns: vx_reference in case of success, else NULL

◆ tivxIsTargetEnabled()

vx_bool tivxIsTargetEnabled ( const char target_name[] )

Utility function to know if target is enabled or not.

Parameters

[in] target_name String specifying the target name

Returns: A vx_bool value.

Return values

vx_true_e	The target is enabled
vx_false_e	The target is not enabled

◆ tivxPlatformGetTimeInUsecs()

uint64_t tivxPlatformGetTimeInUsecs ( void )

Get the time in micro seconds.

Returns: Time in micro seconds.

◆ tivxSetNodeParameterNumBufByIndex()

vx_status VX_API_CALL tivxSetNodeParameterNumBufByIndex	(	vx_node	node,
		vx_uint32	idx,
		vx_uint32	num_buf
	)

Set number of buffers to allocate at output of a node parameter.

Graph to which the node belongs MUST be scheduled in VX_GRAPH_SCHEDULE_MODE_QUEUE_AUTO or VX_GRAPH_SCHEDULE_MODE_QUEUE_MANUAL mode.
The node parameter specified MUST be a output parameter.
The node parameter specified MUST NOT be an enqueueable graph parameter.

This API acts as a hint and framework may override user specified settings in case any of above conditions are not met.

Parameters

[in]	node	Node reference
[in]	idx	Node parameter index
[in]	num_buf	Number of buffers to allocate

◆ tivxGetNodeParameterNumBufByIndex()

vx_status VX_API_CALL tivxGetNodeParameterNumBufByIndex	(	vx_node	node,
		vx_uint32	idx,
		vx_uint32 *	num_buf
	)

Get number of buffers to allocate at output of a node parameter.

If the buffers have not been set by tivxSetNodeParameterNumBufByIndex and the graph is not in pipelining mode, the num_buf will be 0.
If the buffers have not been set by tivxSetNodeParameterNumBufByIndex the graph is in pipelining mode and not verified, the num_buf will be 0.
If the buffers have not been set by tivxSetNodeParameterNumBufByIndex the graph is in pipelining mode and verified, the num_buf will be set via the framework based on the number of nodes connected to that buffer.
If the buffers have been set by tivxSetNodeParameterNumBufByIndex, the num_buf will reflect this value regardless of if this is an optimal configuration.
The node parameter specified MUST be a output parameter.

Parameters

[in]	node	Node reference
[in]	idx	Node parameter index
[out]	num_buf	Number of buffers allocated at output parameter

◆ tivxSetGraphPipelineDepth()

vx_status VX_API_CALL tivxSetGraphPipelineDepth	(	vx_graph	graph,
		vx_uint32	pipeline_depth
	)

Indicates to the implementation the depth of the graph pipeline.

Parameters

[in]	graph	Graph reference
[in]	pipeline_depth	Pipeline depth; Max value is (TIVX_GRAPH_MAX_PIPELINE_DEPTH-1) else it will return an error

◆ tivxNodeSendCommand()

vx_status VX_API_CALL tivxNodeSendCommand	(	vx_node	node,
		uint32_t	replicate_nodex_idx,
		uint32_t	node_cmd_id,
		vx_reference	ref[],
		uint32_t	num_refs
	)

Send node specific Control command.

This API is used to send specific control command to the node. Refer to Node documentation for specific control command. Note that this API is blocking and does not return until command is executed by the node. This API is thread safe, ie multi commands can be sent to same or different nodes from different threads

Parameters

[in]	node	Reference of the node to which this command is to be sent.
[in]	replicate_nodex_idx	In case of a non-replicated node this should be 0, For a replicated node this is the index of the replicated node to which the command is targeted. To send same command to all replicated nodes use TIVX_CONTROL_CMD_SEND_TO_ALL_REPLICATED_NODES
[in]	node_cmd_id	Node specific control command id, refer to node specific interface file
[in,out]	ref[]	Node parameter, This is an array of references, required as parameters for this control command. They can be any OpenVX object, created using create API. They are bidirectional parameters, can be used for INPUT, OUTPUT or both. These parameters are a list of references, which are required for the control command on the given node. Refer to node documentation to get details about the parameters required for given control command. This reference must be allocated before calling this API. This can be done by calling either the vxMap/vxUnmap API or the vxCopy API associated with this data object. Caller of this API should explicitly release these refs after their usage is completed.
[in]	num_refs	Number of valid entries/references in ref[] array

◆ tivxNodeSendCommandTimed()

vx_status VX_API_CALL tivxNodeSendCommandTimed	(	vx_node	node,
		uint32_t	replicate_nodex_idx,
		uint32_t	node_cmd_id,
		vx_reference	ref[],
		uint32_t	num_refs,
		uint32_t	timeout
	)

Send node specific Control command.

This API is used to send specific control command to the node. Refer to Node documentation for specific control command. Note that this API blocks for at most 'timeout' milli-seconds i.e. the API returns either when the command execution finishes or if the timeout occurs, whichever occurs first. This API is thread safe, ie multi commands can be sent to same or different nodes from different threads

Parameters

[in]	node	Reference of the node to which this command is to be sent.
[in]	replicate_nodex_idx	In case of a non-replicated node this should be 0, For a replicated node this is the index of the replicated node to which the command is targeted. To send same command to all replicated nodes use TIVX_CONTROL_CMD_SEND_TO_ALL_REPLICATED_NODES
[in]	node_cmd_id	Node specific control command id, refer to node specific interface file
[in,out]	ref[]	Node parameter, This is an array of references, required as parameters for this control command. They can be any OpenVX object, created using create API. They are bidirectional parameters, can be used for INPUT, OUTPUT or both. These parameters are a list of references, which are required for the control command on the given node. Refer to node documentation to get details about the parameters required for given control command. This reference must be allocated before calling this API. This can be done by calling either the vxMap/vxUnmap API or the vxCopy API associated with this data object. Caller of this API should explicitly release these refs after their usage is completed.
[in]	num_refs	Number of valid entries/references in ref[] array
[in]	timeout	Timeout in units of msecs, use TIVX_EVENT_TIMEOUT_WAIT_FOREVER to wait forever

◆ tivxGraphGetNode()

vx_node tivxGraphGetNode	(	vx_graph	graph,
		uint32_t	idx
	)

This API is used to get a reference to a node within a graph at a given index within the graph.

Use vxQueryGraph with attribute VX_GRAPH_NUMNODES to get number of nodes within a graph. This API can be called only on a verified graph. Node returned by this API is not reference counted and should not be released by the user.

Parameters

[in]	graph	graph handle
[in]	idx	node index, value from 0 .. value returned by vxQueryGraph(VX_GRAPH_NUMNODES) - 1

Returns: vx_node in case of success, else NULL

◆ tivxSetUserDataObjectAttribute()

VX_API_ENTRY vx_status VX_API_CALL tivxSetUserDataObjectAttribute	(	vx_user_data_object	user_data_object,
		vx_enum	attribute,
		const void *	ptr,
		vx_size	size
	)

Sets attributes on the user data object.

Parameters

[in]	user_data_object	The reference to the user data object.
[in]	attribute	The attribute to modify. Use a `vx_user_data_object_attribute_e`.
[in]	ptr	The pointer to the value to which to set the attribute.
[in]	size	The size in bytes of the container to which ptr points.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the user_data_object is not a `vx_user_data_object`.
VX_ERROR_NOT_SUPPORTED	If the attribute is not a value supported on this implementation.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

◆ tivxSetNodeTileSize()

VX_API_ENTRY vx_status VX_API_CALL tivxSetNodeTileSize	(	vx_node	node,
		vx_uint32	block_width,
		vx_uint32	block_height
	)

Sets the tile size for a given node in a graph. This is only valid for BAM-enabled kernels on C66 DSP.

Parameters

[in]	node	The reference to the `vx_node` object.
[in]	block_width	The tile width in pixels.
[in]	block_height	The tile height in lines.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS if the tile size is set correctly.

◆ tivxSetReferenceAttribute()

VX_API_ENTRY vx_status VX_API_CALL tivxSetReferenceAttribute	(	vx_reference	ref,
		vx_enum	attribute,
		const void *	ptr,
		vx_size	size
	)

Sets reference attributes for the below enums: TIVX_REFERENCE_TIMESTAMP.

Parameters

[in]	ref	The reference object.
[in]	attribute	The attribute of the reference to be set.
[in]	ptr	The value of the reference attribute to be set.
[in]	size	The size of the value of the reference attribute to be set.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS if the attribute was set correctly.

◆ tivxIsReferenceMetaFormatEqual()

VX_API_ENTRY vx_bool VX_API_CALL tivxIsReferenceMetaFormatEqual	(	vx_reference	ref1,
		vx_reference	ref2
	)

Check for equivalence between the meta formats of two reference objects.

This API is used to check for equivalence between the meta formats of two reference objects. The function returns true if they are equal and false if not.

Parameters

[in]	ref1	First reference object to be compared.
[in]	ref2	Second reference object to be compared.

Returns: A _vx_bool_e enumeration.; vx_true_e in case of equal meta formats, vx_false else

◆ tivxReferenceImportHandle()

VX_API_ENTRY vx_status VX_API_CALL tivxReferenceImportHandle	(	vx_reference	ref,
		const void *	addr[],
		const uint32_t	size[],
		uint32_t	num_entries
	)

Updates a reference object with the supplied handles (pointers to memory).

Any existing handles in the reference object will be over-written with the new handles provided. No error will be reported. If the caller chooses to preserve the existing handles then the caller should use tivxReferenceExportHandle for retrieving the current handles before invoking this function.

The following conditions regarding 'addr' must be TRUE:

allocated using appMemAlloc or tivxMemAlloc on ARM using the APP_MEM_HEAP_DDR or TIVX_MEM_EXTERNAL memory region respectively
- This API ensures that the memory is allocated in the necessary shared memory region which can be used by OpenVX
freed using appMemFree or tivxMemFree on ARM
memory block is contiguous

Only the following reference object types are supported:

VX_TYPE_IMAGE (note: subimages of images are not supported; also, subimages of an image will not be retained across export/import)
VX_TYPE_TENSOR
VX_TYPE_USER_DATA_OBJECT
VX_TYPE_ARRAY
VX_TYPE_DISTRIBUTION
VX_TYPE_MATRIX
VX_TYPE_CONVOLUTION
VX_TYPE_PYRAMID
TIVX_TYPE_RAW_IMAGE

The memory being imported to an OpenVX reference must adhere to the semantics of how the framework allocates memory. This is of particular note for a few OpenVX objects listed below.

For VX_TYPE_IMAGE references, multi-plane images shall be imported as a single entry. The reason for this is that the framework allocates multi-plane images as a single contiguous memory buffer. Therefore, if this is exported, it can also be freed as a single contiguous memory buffer rather than as separate buffers.
For VX_TYPE_PYRAMID objects, each pyramid level is allocated as a separate buffer and thus must be imported as a single entry per level. Additionally, in the case that the pyramid levels are multi-plane images, these entries must be allocated as a single contiguous buffer with a size of all planes of the image.
For TIVX_TYPE_RAW_IMAGE objects with multiple exposures, these are allocated by the framework as separate buffers and thus must be imported as separate entries.

Please note the important details below on semantics about the usage of the reference import and export. Errors will occur if the below requirements are not adhered to.

When calling the tivxReferenceExportHandle API on a vx_reference to obtain a handle and subsequently calling the tivxReferenceImportHandle API to import the handle to a separate vx_reference, the two references must be of the same type and have the same meta information. This can be confirmed by using the tivxIsReferenceMetaFormatEqual API.
The handle exported by the tivxReferenceExportHandle API will only be valid while the originally allocated handle is valid. For example, if a handle is exported from ref1 and imported into ref2, and then ref1 is released access to ref2 will result in attempting to access memory which has already been freed. It is therefore the responsibility of the application to ensure that the original memory allocation lifetime exceeds the lifetime of exported handle.
In the example in the bullet above, in the case that ref1 must be released prior to ref2, the suggested approach is to import a NULL pointer to ref1, followed by a release of the reference. At this point, ref2 has sole possession of the buffer while ref1 has no buffer dedicated to that reference. An implementation of this approach can be found in the associated test cases located at tiovx/conformance_tests/test_tiovx/test_tivxMem.c.
If memory has already been allocated to a vx_reference and the tivxReferenceImportHandle API is called on the vx_reference, the previous buffer will be discarded and the vx_reference will now use the imported buffer. A log in the VX_ZONE_INFO log level will be thrown on the console in this scenario to note that a buffer is being overridden. Because this can be a dangerous situation, the tivxReferenceExportHandle API shall be called on the vx_reference in question. The previous buffer can be used as required in the application before ultimately being freed by way of the tivxMemFree API.
The tivxReferenceExportHandle API and tivxReferenceImportHandle API must not be called if the reference has been enqueued to a vx_graph. This can cause a scenario where the graph overwrites the buffer contents and is thus is not in a state where it can be read by the application.

Finally, please refer to the usage section of the TIOVX documentation for further information and diagrams showcasing the proper usage of these API's.

Parameters

[in,out]	ref	The reference object to be updated.
[in]	addr	An array of pointers for holding the handles. The entries can be NULL.
[in]	size	An array of sizes corresponding to handles. The entries will be looked at if the corresponding handle is not NULL.
[in]	num_entries	Number of valid entries in addr[]. This should match the number of handles expected to be maintained internally by 'ref' (ex:- for an image object with multiple planes, num_extries > 1).

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	if the import operation is successful. The 'ref' object will have the internal handles updated.
VX_FAILURE	if the operation is unsuccessful. The state of the reference object is not changed. A failure can occur for the following reasons: Unsupported reference object type The argument check fails The handle check fails i.e. the handles have not been allocated using appMemAlloc()/tivxMemAlloc() The number of handles specified is less than the number expected by the reference object.

◆ tivxReferenceExportHandle()

VX_API_ENTRY vx_status VX_API_CALL tivxReferenceExportHandle	(	const vx_reference	ref,
		void *	addr[],
		uint32_t	size[],
		uint32_t	max_num_entries,
		uint32_t *	num_entries
	)

Exports the handles from a reference object.

It is the responsibility of the caller to make sure that the addr array is dimensioned to hold all the handles expected from the reference object.

Only the following reference object types are supported:

VX_TYPE_IMAGE (note: subimages of images are not supported; also, subimages of an image will not be retained across export/import)
VX_TYPE_TENSOR
VX_TYPE_USER_DATA_OBJECT
VX_TYPE_ARRAY
VX_TYPE_DISTRIBUTION
VX_TYPE_MATRIX
VX_TYPE_CONVOLUTION
VX_TYPE_PYRAMID
TIVX_TYPE_RAW_IMAGE

The memory exported from an OpenVX reference adheres to the semantics of how the framework allocates memory. This is of particular note for a few OpenVX objects listed below.

For VX_TYPE_IMAGE references, multi-plane images are exported as a single entry. The reason for this is that the framework allocates multi-plane images as a single contiguous memory buffer. Therefore, once this is exported, it can also be freed as a single contiguous memory buffer rather than as separate buffers.
For VX_TYPE_PYRAMID objects, each pyramid level is allocated as a separate buffer and will be exported as a single entry per level. Additionally, in the case that the pyramid levels are multi-plane images, these entries are provided as a single contiguous buffer with a size of all planes of the image.
For TIVX_TYPE_RAW_IMAGE objects with multiple exposures, these are allocated by the framework as separate buffers and thus are exported as separate entries.

Please note the important details below on semantics about the usage of the reference import and export. Errors will occur if the below requirements are not adhered to.

When calling the tivxReferenceExportHandle API on a vx_reference to obtain a handle and subsequently calling the tivxReferenceImportHandle API to import the handle to a separate vx_reference, the two references must be of the same type and have the same meta information. This can be confirmed by using the tivxIsReferenceMetaFormatEqual API.
The handle exported by the tivxReferenceExportHandle API will only be valid while the originally allocated handle is valid. For example, if a handle is exported from ref1 and imported into ref2, and then ref1 is released access to ref2 will result in attempting to access memory which has already been freed. It is therefore the responsibility of the application to ensure that the original memory allocation lifetime exceeds the lifetime of exported handle.
In the example in the bullet above, in the case that ref1 must be released prior to ref2, the suggested approach is to import a NULL pointer to ref1, followed by a release of the reference. At this point, ref2 has sole possession of the buffer while ref1 has no buffer dedicated to that reference. An implementation of this approach can be found in the associated test cases located at tiovx/conformance_tests/test_tiovx/test_tivxMem.c.
If memory has already been allocated to a vx_reference and the tivxReferenceImportHandle API is called on the vx_reference, the previous buffer will be discarded and the vx_reference will now use the imported buffer. A log in the VX_ZONE_INFO log level will be thrown on the console in this scenario to note that a buffer is being overridden. Because this can be a dangerous situation, the tivxReferenceExportHandle API shall be called on the vx_reference in question. The previous buffer can be used as required in the application before ultimately being freed by way of the tivxMemFree API.
The tivxReferenceExportHandle API and tivxReferenceImportHandle API must not be called if the reference has been enqueued to a vx_graph. This can cause a scenario where the graph overwrites the buffer contents and is thus is not in a state where it can be read by the application.

Finally, please refer to the usage section of the TIOVX documentation for further information and diagrams showcasing the proper usage of these API's.

Parameters

[in]	ref	The reference object to export the handles from.
[out]	addr	An array of pointers for holding the handles.
[out]	size	An array of sizes corresponding to handles. The entries will be looked
[in]	max_num_entries	Maximum number of entries to export.
[out]	num_entries	Number of valid entries in addr[]. This should match the number of handles expected to be maintained internally by 'ref' (ex:- for an image object with multiple planes, num_extries > 1).

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	if the export operation is successful. The 'addr' object will be populated with 'num_entries' handles. size[i] will correspond to the handle addr[i].
VX_FAILURE	if the operation is unsuccessful. The state of the reference object is not changed. A failure can occur for the following reasons: Unsupported reference object type The argument check fails The max number of handles specified is less than the number expected to be exported by the reference object.

◆ tivxCreateReferenceFromExemplar()

VX_API_ENTRY vx_reference VX_API_CALL tivxCreateReferenceFromExemplar	(	vx_context	context,
		vx_reference	exemplar
	)

Create reference from a exemplar object.

This API is used to create a new reference using the same meta information as an already created reference object.

Parameters

[in]	context	The reference to the implementation context.
[in]	exemplar	The exemplar object.

Returns: vx_reference. Any possible errors preventing a successful creation should be checked using vxGetStatus.

Detailed Description

Modules

Defines

Enumerations

Functions

Macro Definition Documentation

◆ TIVX_TARGET_HOST

◆ TIVX_CONTROL_CMD_SEND_TO_ALL_REPLICATED_NODES

Enumeration Type Documentation

◆ tivx_attribute_extensions_e

◆ tivx_df_image_e

◆ tivx_status_e

◆ tivx_memory_logging_e

Function Documentation

◆ tivxInit()

◆ tivxDeInit()

◆ tivxHostInit()

◆ tivxHostDeInit()

◆ tivxAddKernelTarget()

◆ tivxSetKernelSinkDepth()

◆ tivxRegisterModule()

◆ tivxUnRegisterModule()

◆ tivxGetSelfCpuId()

◆ tivxCreateNodeByKernelEnum()

◆ tivxCreateNodeByKernelRef()

◆ tivxCreateNodeByKernelName()

◆ tivxIsReferenceVirtual()

◆ tivxGetReferenceParent()

◆ tivxIsTargetEnabled()

◆ tivxPlatformGetTimeInUsecs()

◆ tivxSetNodeParameterNumBufByIndex()

◆ tivxGetNodeParameterNumBufByIndex()

◆ tivxSetGraphPipelineDepth()

◆ tivxNodeSendCommand()

◆ tivxNodeSendCommandTimed()

◆ tivxGraphGetNode()

◆ tivxSetUserDataObjectAttribute()

◆ tivxSetNodeTileSize()

◆ tivxSetReferenceAttribute()

◆ tivxIsReferenceMetaFormatEqual()

◆ tivxReferenceImportHandle()

◆ tivxReferenceExportHandle()

◆ tivxCreateReferenceFromExemplar()