Detailed Description

APIs for adding BAM support to DSP target kernel plugins.

Modules
	BAM Supernode Support APIs
	APIs for adding BAM supernode support to DSP target kernel plugins.

Data Structures
struct	tivx_bam_kernel_details_t
	Kernel Details structure. More...

struct	tivx_bam_plugin_def
	BAM plugin definition. More...

Defines
#define	TIVX_BAM_MAX_NODES (16u)
	Max number of nodes in a BAM graph.

#define	TIVX_BAM_MAX_EDGES (32u)
	Max number of edges in a BAM graph.

#define	TIVX_MAX_BUF_PARAMS (32u)
	Max number of buf params in a BAM graph.

#define	TIVX_IMAGE_NULL_PLANE (255)
	indicates if a plane is not connected

Typedefs
typedef void *	tivx_bam_graph_handle
	Graph handle. More...

Functions
vx_status	tivxBamRegisterPlugin (tivx_bam_plugin_def plugin, BAM_KernelId kernelId)
	Register BAM plugin with OpenVX framework on DSP. More...

vx_status	tivxBamGetKernelIdFromName (const char name, BAM_KernelId kernelId)
	Returns the kernelID associated with a plugin name. More...

vx_status	tivxBamMemInit (void ibuf_mem, uint32_t ibuf_size, void wbuf_mem, uint32_t wbuf_size)
	Initialize memory block for BAM usage. More...

vx_status	tivxBamCreateHandleSingleNode (BAM_TI_KernelID kernel_id, VXLIB_bufParams2D_t buf_params[], tivx_bam_kernel_details_t kernel_details, tivx_bam_graph_handle *graph_handle)
	BAM Create Graph Handle for Single Node. More...

vx_status	tivxBamCreateHandleMultiNode (BAM_NodeParams node_list[], uint32_t max_nodes, BAM_EdgeParams edge_list[], uint32_t max_edges, VXLIB_bufParams2D_t buf_params[], tivx_bam_kernel_details_t kernel_details[], tivx_bam_graph_handle g_handle)
	BAM Create Graph Handle for Multiple Nodes. More...

vx_status	tivxBamUpdatePointers (tivx_bam_graph_handle graph_handle, uint32_t num_inputs, uint32_t num_outputs, void *ptrs[])
	BAM Update Pointers. More...

vx_status	tivxBamControlNode (tivx_bam_graph_handle graph_handle, uint32_t node_id, uint32_t cmd, void *payload)
	BAM Node Control. More...

vx_status	tivxBamProcessGraph (tivx_bam_graph_handle graph_handle)
	BAM Process Graph. More...

void	tivxBamDestroyHandle (tivx_bam_graph_handle graph_handle)
	BAM Destroy Handle. More...

vx_status	tivxBamInitKernelDetails (tivx_bam_kernel_details_t *kernel_details, uint32_t num_bam_nodes, tivx_target_kernel_instance kernel)
	BAM Initialize kernel details structure array. More...

Typedef Documentation

◆ tivx_bam_graph_handle

typedef void* tivx_bam_graph_handle

Graph handle.

Handle associated with an instance of a BAM graph.

The structure this handle represents is internally defined and not needed by the user.

The user is given this handle when calling tivxBamCreateHandleSingleNode, or tivxBamCreateHandleMultiNode, and can destroy it by calling tivxBamDestroyHandle.

Definition at line 123 of file tivx_bam_kernel_wrapper.h.

Function Documentation

◆ tivxBamRegisterPlugin()

vx_status tivxBamRegisterPlugin	(	tivx_bam_plugin_def *	plugin,
		BAM_KernelId *	kernelId
	)

Register BAM plugin with OpenVX framework on DSP.

This function is used to register a BAM plugin with the DSP target framework so that the kernel can be included in BAM graphs.

The plugin is expected to have a unique "name" string. If a plugin with the same name has already been registered, then the kernelId of the previously registered plugin will be returned without registering the kernel again.

This function should be called before any calls to tivxBamCreateHandleSingleNode or tivxBamCreateHandleMultiNode, and is recommended to be called during the kernel registration function where tivxAddTargetKernel() is called, or as part of a kernel library registration function.

Parameters

[in]	plugin	Pointer to a plugin definition
[out]	kernelId	The kernel id given to the passed plugin.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_PARAMETERS	If one of the parameters are NULL.
VX_ERROR_NO_MEMORY	If there is not enough memory to register new plugins. The total number of user plugins can be incremented by changing the TIVX_MAX_DSP_BAM_USER_PLUGINS define in the TI/tivx_config.h file.

◆ tivxBamGetKernelIdFromName()

vx_status tivxBamGetKernelIdFromName	(	const char *	name,
		BAM_KernelId *	kernelId
	)

Returns the kernelID associated with a plugin name.

This function is used to return the kernelID of a BAM plugin which has already been registered on the DSP target framework.

If the name is not found in the BAM kernel database, the BAM_TI_KERNELID_UNDEFINED will be returned as the kernelId.

Parameters

[in]	name	Name of the BAM plugin
[out]	kernelId	The kernel id given to the passed plugin.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_PARAMETERS	If one of the parameters are NULL.

◆ tivxBamMemInit()

vx_status tivxBamMemInit	(	void *	ibuf_mem,
		uint32_t	ibuf_size,
		void *	wbuf_mem,
		uint32_t	wbuf_size
	)

Initialize memory block for BAM usage.

This function is used by the application to assign blocks of internal memory for use by BAM. This memory is typically on-chip RAM (L2SRAM, L1DRAM, or OCM RAM).

BAM uses the ibuf memory to temporarily store the input block buffers from the DMA source nodes, the intermediate block buffers within kernels of the graph, and the output block buffers to the DMA sink nodes.

BAM uses the wbuf memory to temporarily store internal scratch memory requested by the kernels of the graph.

All of this memory is considered scratch memory, meaning that the BAM does not use it for persistent memory, and it can be overwritten by the application when in between calls to tivxBamProcessGraph.

This function should be called before any calls to tivxBamCreateHandleSingleNode or tivxBamCreateHandleMultiNode.

◆ tivxBamCreateHandleSingleNode()

vx_status tivxBamCreateHandleSingleNode	(	BAM_TI_KernelID	kernel_id,
		VXLIB_bufParams2D_t *	buf_params[],
		tivx_bam_kernel_details_t *	kernel_details,
		tivx_bam_graph_handle *	graph_handle
	)

BAM Create Graph Handle for Single Node.

This function will create a BAM graph of 1 node, given the kernel_id, array of pointers to buf_params, and computation kernel_details, containing kernel info and parameters.

Upon success, a non-NULL graph_handle will be returned and vx_status will be VX_SUCCESS.

If there is not enough memory to allocate the handle for the given kernel and block size, then the VX_ERROR_NO_MEMORY error will be returned and the graph_handle will be set to NULL.

Any other failure will return a VX_FAILURE and the graph_handle will be set to NULL.

The user should pass the graph_handle to other functions in this wrapper related to BAM graph wrappers.

◆ tivxBamCreateHandleMultiNode()

vx_status tivxBamCreateHandleMultiNode	(	BAM_NodeParams	node_list[],
		uint32_t	max_nodes,
		BAM_EdgeParams	edge_list[],
		uint32_t	max_edges,
		VXLIB_bufParams2D_t *	buf_params[],
		tivx_bam_kernel_details_t	kernel_details[],
		tivx_bam_graph_handle *	g_handle
	)

BAM Create Graph Handle for Multiple Nodes.

This function will create a BAM graph of multiple nodes, given the node list, edge list, array of pointers to buf_params, and array of the computation kernel_details, containing kernel info and parameters. This function expects the array size of kernel_details to be equal to the full number of nodes in the node_list, including SOURCE and SINK nodes.

Upon success, a non-NULL graph_handle will be returned and vx_status will be VX_SUCCESS.

If there is not enough memory to allocate the handle for the given kernel and block size, then the VX_ERROR_NO_MEMORY error will be returned and the graph_handle will be set to NULL.

Any other failure will return a VX_FAILURE and the graph_handle will be set to NULL.

The user should pass the graph_handle to other functions in this wrapper related to BAM graph wrappers.

◆ tivxBamUpdatePointers()

vx_status tivxBamUpdatePointers	(	tivx_bam_graph_handle	graph_handle,
		uint32_t	num_inputs,
		uint32_t	num_outputs,
		void *	ptrs[]
	)

BAM Update Pointers.

This function will update the external memory pointers for the associated graph_handle. This is typically called before processing each frame in case the pointer values have changed.

If the pointer values have not changed since the previous time they were set, there is no reason to call this function.

Upon success, vx_status will be VX_SUCCESS. Upon failure, vx_status will be VX_FAILURE.

◆ tivxBamControlNode()

vx_status tivxBamControlNode	(	tivx_bam_graph_handle	graph_handle,
		uint32_t	node_id,
		uint32_t	cmd,
		void *	payload
	)

BAM Node Control.

Some kernel have a control interface to set information or get information back from the kernel context.

This API allows the application to send control commands to a specific node. The commands and control interface is defined in the bam_plugin for each kernel.

In the case of single node handle, node_id is ignored.

Upon success, vx_status will be VX_SUCCESS. Upon failure, vx_status will be VX_FAILURE.

◆ tivxBamProcessGraph()

vx_status tivxBamProcessGraph ( tivx_bam_graph_handle graph_handle )

BAM Process Graph.

This function will execute the kernel within the BAM graph.

This is called once per frame. The BAM wrapper internally will manage the sequencing of DMA fetches and DSP processing for each block during this call.

Upon success, vx_status will be VX_SUCCESS. Upon failure, vx_status will be VX_FAILURE.

◆ tivxBamDestroyHandle()

void tivxBamDestroyHandle ( tivx_bam_graph_handle graph_handle )

BAM Destroy Handle.

This function will destroy the BAM graph handle, effectivly releasing the memory to the system.

This is typically called if the user releases a graph or makes changes to the graph that require a reverification of the graph.

◆ tivxBamInitKernelDetails()

vx_status tivxBamInitKernelDetails	(	tivx_bam_kernel_details_t *	kernel_details,
		uint32_t	num_bam_nodes,
		tivx_target_kernel_instance	kernel
	)

BAM Initialize kernel details structure array.

This function should be called before setting any parameters within the kernel_details structure since it sets all parameters to default values.

This is typically called in the "create" target kernel callback for bam enabled kernels.

Parameters

[out]	kernel_details	Pointer to array of kernel_details to be initialized
[in]	num_bam_nodes	Number of bam nodes in the kernel_details array
[in]	kernel	Kernel instance input

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_PARAMETERS	If kernel_details is NULL or if num_bam_nodes is 0.

Detailed Description

Modules

Data Structures

Defines

Typedefs

Functions

Typedef Documentation

◆ tivx_bam_graph_handle

Function Documentation

◆ tivxBamRegisterPlugin()

◆ tivxBamGetKernelIdFromName()

◆ tivxBamMemInit()

◆ tivxBamCreateHandleSingleNode()

◆ tivxBamCreateHandleMultiNode()

◆ tivxBamUpdatePointers()

◆ tivxBamControlNode()

◆ tivxBamProcessGraph()

◆ tivxBamDestroyHandle()

◆ tivxBamInitKernelDetails()