TIOVX User Guide
TIOVX Usage Recommendations

Table of Contents

vxSetNodeTarget()

  • vxSetNodeTarget() should only be called on nodes of a graph before calling vxVerifyGraph() for that graph.
  • If a kernel that has only one available target is instantiated, the vxSetNodeTarget() API does not have to be called for that instantiated kernel. It will default to the only available target.
  • If multiple targets are available for a given kernel and the vxSetNodeTarget() is not called, the framework will default to the first target added to the kernel via the tivxAddKernelTarget() API, which is called when adding the target kernel to the context.
  • As per a requirement of the conformance tests, the vxSetNodeTarget API accepts string target values of "any", "aNy" and "ANY" then the behaviour is the same as if the VX_TARGET_ANY enum was passed. If a legitimate TI-target is required for a given node, that target value must be provided to the API.

vxGetRemapPoint() and vxSetRemapPoint()

  • The vxGetRemapPoint() and vxSetRemapPoint() API's must always get or set the (0,0) element first prior to any other get or set. Additionally, the element at (remap_width, remap_height) must be set or gotten last. This is because getting or setting the (0,0) element performs a map of the remap object and getting or setting the (remap_width, remap_height) element performs an unmap of the remap object.

Stride Alignment for Images and Raw Images

  • TIOVX automatically aligns the stride of images and raw images to the value of TIVX_DEFAULT_STRIDE_Y_ALIGN. This is a requirement of certain hardware accelerators (such as LDC) and should not be modified.

Graph Performance API's with pipelining

  • The graph performance API's (VX_GRAPH_PERFORMANCE) give the overall time to execute a graph.
  • However, when using the pipelining extension, this may not be as useful in the case that one may need to calculate the frame rate of the graph.
  • In this case, it is recommended to use the API's provided in vision_apps for calculating the frame rate and other performance information here

Enabling a node within the graph to run at lower FPS than rest of graph

  • In some situations, it may be desirable to have a node within the graph run at a lower FPS than the rest of the graph.
  • In these scenarios, the node itself can be customized using the steps below to accomplish this.
    • A thread can be created from the create callback of the custom node.
    • Pass message/control commands from this thread in process callback.
    • Close thread from destroy callback
  • This is done in the tivxHwaVpacVissNode to pass information to the tivxAewbNode and can be referenced for custom node implementations.

Virtual Object Support in TIOVX

  • While the OpenVX standard specification provides a provision for implementations to optimize memory footprint via virtual objects, the TIOVX framework does not provide any added optimization from using virtual objects.
  • Certain nodes, such as the DSS M2M node and the Mosaic node, do not support virtual objects. In these cases, the standard objects should be used instead.

Map and Copy API Usage in TIOVX

  • Each OpenVX data object has an associated vxMap<Data_Object> and vxCopy<Data_Object> API.
  • In general, all memory allocation within TIOVX occurs during the vxVerifyGraph call, in order to provide a single return regarding whether or not a system has sufficient memory to run applications. Therefore, even if the data object is created via the vxCreate<Data_Object> API, the memory will only be allocated at the call to vxVerifyGraph.
  • There are a few exceptions to this rule:
    • The vxMap<Data_Object> and vxCopy<Data_Object> API's are an exception to this rule about memory allocation occurring at a single point. Given that these API's return a pointer to the object data buffer, the memory for these data objects are allocated in the call to vxMap<Data_Object> and vxCopy<Data_Object>. When the call to vxVerifyGraph occurs, it will have already allocated this memory prior to executing the graph verification.
    • An additional exception to this rule is for the vx_user_data_object API vxCreateUserDataObject. This API allows the developer to provide a data structure instance to populate the memory at creation of the vx_user_data_object itself. Therefore, in this case, the memory for the vx_user_data_object will be allocated.
    • Similarly, the memory for a vx_scalar will be allocated when calling vxCreateScalar in the case that a scalar value is passed at create time.

TIOVX Implementation of Image API's

  • The vx_image API's below allow an application to use an allocated handle to create or swap into an OpenVX image object
  • An important note about these API's is that the handles used by these API's must be allocated using tivxMemAlloc rather than by using malloc or other such memory.

TIOVX Implementation of Subimages

  • The OpenVX specification does not define the depth of the number of the subimages which a vx_image may contain
  • Therefore, the TIOVX implementation has added a max value of "2" for the number of subimage levels, as well as a max value of "16" for the number of subimages per level.
  • These are configurable and can be updated in the max value configuration file.

tivxNodeSendCommand()

  • The intention behind the tivxNodeSendCommand() is to send non-real time data to a node and/or to query for information from the node
  • Particularly if using pipelining, this API shall not be used for sending/receiving data from a node for every execution of the node. If that is the requirement of a given use case, the node API should be changed to encapsulate this parameter.

Supplementary Data with Composite Objects from Exemplar

  • For the specific scenario of creating a composite object (i.e., a vx_pyramid or a vx_object_array) from exemplar when the composite object used as the exemplar contains supplementary data, the children objects of the resulting composite object will contain the same supplementary data as the base object (i.e., the vx_pyramid or vx_object_array).
  • As an example, in the case that a vx_object_array "ABC" is created with supplementary data "XYZ", if an exemplar of object ABC is created, then the resulting object array elements will contain supplementary data "XYZ" as well.

TIOVX Task API on MPU Cores

  • When used on MPU cores running an HLOS (i.e., Linux or QNX), the priority parameter of the tivx_task API is ignored. This is left to maintain compatibility with RTOS.
  • If a thread needs to be created with a priority, please instead use the native pthread API

Using TIVX_MEMORY_TYPE_DMA

  • For buffers of type VX_MEMORY_TYPE_HOST, the host core will manage the buffer and perform its corresponding cache operations.
  • However, a buffer with a memory type of TIVX_MEMORY_TYPE_DMA will not necessarily mean a DMA will be accessing the buffer.
    • Rather, it simply means cache operations on buffer will be skipped.
  • This makes buffers of TIVX_MEMORY_TYPE_DMA faster.
    • This comes at the tradeoff of the application ensuring stale data is not created.
    • Additionally, each TI SoC has their own cache implementation and validation policies, which using VX_MEMORY_TYPE_HOST would normally abstract from the application.
  • A performance optimization could occur when, for example, only small pieces of a buffer are accessed, which would make it ineffective to maintain cache operations on the full buffer.
    • In this case the application can use a buffer TIVX_MEMORY_TYPE_DMA which skips the maintenance, and later the developer can perform the maintenance on just the pieces of the buffer accessed.