phase_rgb_user_kernel.c File Reference

#include <stdio.h>
#include <VX/vx.h>
#include <TI/tivx.h>
#include <ch03_graph/phase_rgb_user_kernel.h>

Go to the source code of this file.

Macros
#define	PHASE_RGB_IN0_IMG_IDX   (0u)
	Index of input image in parameter list.
#define	PHASE_RGB_OUT0_IMG_IDX   (1u)
	Index of output image in parameter list.
#define	PHASE_RGB_MAX_PARAMS   (2u)
	Total number of parameters for this function.

Functions
static vx_status VX_CALLBACK	phase_rgb_user_kernel_init (vx_node node, const vx_reference parameters[], vx_uint32 num)
	User/target kernel init function. More...
static vx_status VX_CALLBACK	phase_rgb_user_kernel_run (vx_node node, const vx_reference parameters[], vx_uint32 num)
	User/target kernel execute or run function. More...
static vx_status VX_CALLBACK	phase_rgb_user_kernel_deinit (vx_node node, const vx_reference parameters[], vx_uint32 num)
	User/target kernel de-init function. More...
static vx_status VX_CALLBACK	phase_rgb_user_kernel_validate (vx_node node, const vx_reference parameters[], vx_uint32 num, vx_meta_format metas[])
	User/target kernel validate function. More...
static vx_kernel	phase_rgb_user_kernel_add_as_user_kernel (vx_context context)
	Add kernel as user kernel. More...
static vx_kernel	phase_rgb_user_kernel_add_as_target_kernel (vx_context context)
	Add kernel as target kernel. More...
vx_status	phase_rgb_user_kernel_add (vx_context context, vx_bool add_as_target_kernel)
	Add user/target kernel to OpenVX context. More...
vx_status	phase_rgb_user_kernel_remove (vx_context context)
	Remove user/target kernel from context. More...
vx_node	phase_rgb_user_kernel_node (vx_graph graph, vx_image in, vx_image out)
	User/target kernel node create function. More...

Variables
static vx_kernel	phase_rgb_user_kernel = NULL
	Handle to the registered user kernel [static global].
static vx_enum	phase_rgb_user_kernel_id = (vx_status)VX_ERROR_INVALID_PARAMETERS
	Kernel ID of the registered user kernel. Used to create a node for the kernel function [static global].

Detailed Description

User Kernel implementation for Phase to RGB conversion function

This file shows a sample implementation of a user kernel function.

To implement a user kernel the below top level interface functions are implemented

• phase_rgb_user_kernel_add() : Registers user kernel to OpenVX context
  • The implementation of this function has slight variation depending on the kernel implemented as as OpenVX user kernel or TIOVX target kernel
• phase_rgb_user_kernel_remove() : Un-Registers user kernel from OpenVX context
  • The implementation of this function is same for both OpenVX user kernel and TIOVX target kernel
• phase_rgb_user_kernel_node(): Using the user kernel ID, creates a OpenVX node within a graph
  • The implementation of this function is same for both OpenVX user kernel and TIOVX target kernel

When registering a user kernel, the following callback function are implemented and registered with the OpenVX context

• phase_rgb_user_kernel_validate() : kernel validate function. Called during graph verify.
  • The implementation of this function is same for both OpenVX user kernel and TIOVX target kernel
• phase_rgb_user_kernel_init() : kernel init function. Called after phase_rgb_user_kernel_validate() during graph verify
  • This function is typically only implemented for user kernel and is NULL for target kernel
• phase_rgb_user_kernel_run() : kernel run or execute function. Called when graph is executed.
  • This function is MUST be non-NULL for user kernel and MUST be NULL for target kernel
• phase_rgb_user_kernel_deinit(): kernel deinit function. Called during graph release.
  • This function is typically only implemented for user kernel and is NULL for target kernel

When working with user kernel or target kernel,

• phase_rgb_user_kernel_add() MUST be called after vxCreateContext() and before phase_rgb_user_kernel_node().
• phase_rgb_user_kernel_remove() MUST be called before vxReleaseContext() and
• phase_rgb_user_kernel_node() is called to insert the user kernel node into a OpenVX graph

When working with target kernel, additional the target side implementation is done in file phase_rgb_target_kernel.c

Follow the comments for the different functions in the file to understand how a user/target kernel is implemented.

Definition in file phase_rgb_user_kernel.c.

Function Documentation

phase_rgb_user_kernel_init()

static vx_status VX_CALLBACK phase_rgb_user_kernel_init ( vx_node  node, const vx_reference  parameters[], vx_uint32  num  )

static

User/target kernel init function.

This function gets called during vxGraphVerify after kernel validate function. Typically any resources the kernel needs during its execution should be allocated during kernel init.

Parameters

node	[in] OpenVX node which will execute the kernel
parameters	[in] Parameters references for this kernel function
num	[in] Number of parameter references

Returns

VX_SUCCESS if validate is successful, else appropiate error code

Definition at line 547 of file phase_rgb_user_kernel.c.

phase_rgb_user_kernel_run()

static vx_status VX_CALLBACK phase_rgb_user_kernel_run ( vx_node  node, const vx_reference  parameters[], vx_uint32  num  )

static

User/target kernel execute or run function.

This function gets called during graph execution. This where the actual kernel function which reads the input data and writes the output data is implemented.

Parameters

node	[in] OpenVX node which will execute the kernel
parameters	[in] Parameters references for this kernel function
num	[in] Number of parameter references

Returns

VX_SUCCESS if validate is successful, else appropiate error code

Definition at line 568 of file phase_rgb_user_kernel.c.

phase_rgb_user_kernel_deinit()

static vx_status VX_CALLBACK phase_rgb_user_kernel_deinit ( vx_node  node, const vx_reference  parameters[], vx_uint32  num  )

static

User/target kernel de-init function.

This function gets called during vxReleaseGraph. Typically any resources allcoated during kernel init are released during deinit.

Parameters

node	[in] OpenVX node which will execute the kernel
parameters	[in] Parameters references for this kernel function
num	[in] Number of parameter references

Returns

VX_SUCCESS if validate is successful, else appropiate error code

Definition at line 684 of file phase_rgb_user_kernel.c.

phase_rgb_user_kernel_validate()

static vx_status VX_CALLBACK phase_rgb_user_kernel_validate ( vx_node  node, const vx_reference  parameters[], vx_uint32  num, vx_meta_format  metas[]  )

static

User/target kernel validate function.

This function gets called during vxGraphVerify. The node which will runs the kernel, parameter references are passed as input to this function. This function checks the parameters to make sure all attributes of the parameter are as expected. ex, data format checks, image width, height relations between input and output.

Parameters

node	[in] OpenVX node which will execute the kernel
parameters	[in] Parameters references for this kernel function
num	[in] Number of parameter references
metas	[in/out] Meta references update with attribute values

Returns

VX_SUCCESS if validate is successful, else appropiate error code

Definition at line 417 of file phase_rgb_user_kernel.c.

phase_rgb_user_kernel_add_as_user_kernel()

static vx_kernel phase_rgb_user_kernel_add_as_user_kernel ( vx_context  context )

static

Add kernel as user kernel.

Parameters

context

[in] OpenVX context to which the kernel will be added

Returns

OpenVX kernel object handle

- Dynamically allocate a kernel ID and store it in the global 'phase_rgb_user_kernel_id'

This is used later to create the node with this kernel function

  /
status = vxAllocateUserKernelId(context, &phase_rgb_user_kernel_id);

- Register kernel to OpenVX context

A kernel can be identified with its kernel ID (allocated above).
A kernel can also be identified with its unique kernel name string. "vx_tutorial_graph.phase_rgb" or TIVX_TUTORIAL_KERNEL_PHASE_RGB_NAME defined in file vx_tutorial_kernels.h in this case.

When calling vxAddUserKernel(), additional callbacks are registered including the mandatory phase_rgb_user_kernel_run() function.

  /
kernel = vxAddUserKernel(
            context,
            TIVX_TUTORIAL_KERNEL_PHASE_RGB_NAME,
            phase_rgb_user_kernel_id,
            phase_rgb_user_kernel_run,
            2, /* number of parameters objects for this user function */
            phase_rgb_user_kernel_validate,
            phase_rgb_user_kernel_init,
            phase_rgb_user_kernel_deinit);

Definition at line 252 of file phase_rgb_user_kernel.c.

phase_rgb_user_kernel_add_as_target_kernel()

static vx_kernel phase_rgb_user_kernel_add_as_target_kernel ( vx_context  context )

static

Add kernel as target kernel.

Parameters

context

[in] OpenVX context to which the kernel will be added

Returns

OpenVX kernel object handle

- Dynamically allocate a kernel ID and store it in the global 'phase_rgb_user_kernel_id'

This is used later to create the node with this kernel function

  /
status = vxAllocateUserKernelId(context, &phase_rgb_user_kernel_id);

- Register kernel to OpenVX context

A kernel can be identified with its kernel ID (allocated above).
A kernel can also be identified with its unique kernel name string. "vx_tutorial_graph.phase_rgb" or TIVX_TUTORIAL_KERNEL_PHASE_RGB_NAME defined in file vx_tutorial_kernels.h in this case.

When calling vxAddUserKernel(), additional callbacks are registered. For target kernel, the 'run' callback is set to NULL. Typically 'init' and 'deinit' callbacks are also set to NULL. 'validate' callback is typically set

  /
kernel = vxAddUserKernel(
            context,
            TIVX_TUTORIAL_KERNEL_PHASE_RGB_NAME,
            phase_rgb_user_kernel_id,
            NULL,
            2, /* number of parameters objects for this user function */
            phase_rgb_user_kernel_validate,
            NULL,
            NULL);

status = vxGetStatus((vx_reference)kernel);

- Add supported target's on which this target kernel can be run

  /
tivxAddKernelTarget(kernel, TIVX_TARGET_DSP1);
#ifndef SOC_AM62A
tivxAddKernelTarget(kernel, TIVX_TARGET_DSP2);
#endif

Definition at line 306 of file phase_rgb_user_kernel.c.

phase_rgb_user_kernel_add()

vx_status phase_rgb_user_kernel_add	(	vx_context	context,
		vx_bool	add_as_target_kernel
	)

Add user/target kernel to OpenVX context.

Parameters

context	[in] OpenVX context into with the user kernel is added
add_as_target_kernel	[in] 'vx_false_e', add this kernel as user kernel 'vx_true_e', add this kernel as target kernel

- Depending on 'add_as_target_kernel' invoke user kernel or target kernel specific registration logic

phase_rgb_user_kernel_id is set as part of this function invocation.

  /
if(add_as_target_kernel==(vx_bool)vx_false_e)
{
    kernel = phase_rgb_user_kernel_add_as_user_kernel(context);
}
if(add_as_target_kernel==(vx_bool)vx_true_e)
{
    kernel = phase_rgb_user_kernel_add_as_target_kernel(context);
}

- Checking is kernel was added successfully to OpenVX context

  /
status = vxGetStatus((vx_reference)kernel);

- Now define parameters for the kernel

 When specifying the parameters, the below attributes of each parameter are specified,
 - parameter index in the function parameter list
 - the parameter direction: VX_INPUT or VX_OUTPUT
 - parameter data object type
 - paramater state: VX_PARAMETER_STATE_REQUIRED or VX_PARAMETER_STATE_OPTIONAL

  /
index = 0;

if ( status == (vx_status)VX_SUCCESS)
{
    status = vxAddParameterToKernel(kernel,
        index,
        (vx_enum)VX_INPUT,
        (vx_enum)VX_TYPE_IMAGE,
        (vx_enum)VX_PARAMETER_STATE_REQUIRED
        );
    index++;
}
if ( status == (vx_status)VX_SUCCESS)
{
    status = vxAddParameterToKernel(kernel,
        index,
        (vx_enum)VX_OUTPUT,
        (vx_enum)VX_TYPE_IMAGE,
        (vx_enum)VX_PARAMETER_STATE_REQUIRED
        );
    index++;
}

- After all parameters are defined, now the kernel is finalized, i.e it is ready for use.

  /
if ( status == (vx_status)VX_SUCCESS)
{
    status = vxFinalizeKernel(kernel);
}

- Set kernel handle to the global user kernel handle

This global handle is used later to release the kernel when done with it

  /
phase_rgb_user_kernel = kernel;

Definition at line 144 of file phase_rgb_user_kernel.c.

phase_rgb_user_kernel_remove()

vx_status phase_rgb_user_kernel_remove

(

vx_context

context

)

Remove user/target kernel from context.

Parameters

context

[in] OpenVX context from which the kernel will be removed

- Remove user kernel from context and set the global 'phase_rgb_user_kernel' to NULL

  /
status = vxRemoveKernel(phase_rgb_user_kernel);
phase_rgb_user_kernel = NULL;

Definition at line 375 of file phase_rgb_user_kernel.c.

phase_rgb_user_kernel_node()

vx_node phase_rgb_user_kernel_node	(	vx_graph	graph,
		vx_image	in,
		vx_image	out
	)

User/target kernel node create function.

Given a graph reference, this function creates a OpenVX node and inserts it into the graph. The list of parameter references is also provided as input. Exact data type are used instead of base class references to allow some level of compile time type checking. In this example, there is one input image and one output image that are passed as parameters.

Parameters

graph	[in] OpenVX graph
in	[in] Input image reference
out	[in] Output image reference

Returns

OpenVX node that is created and inserted into the graph

- Put parameters into a array of references

  /
vx_reference refs[] = {(vx_reference)in, (vx_reference)out};

- Use TIOVX API to make a node using the graph, kernel ID, and parameter reference array as input

  /
node = tivxCreateNodeByKernelEnum(graph,
            phase_rgb_user_kernel_id,
            refs, sizeof(refs)/sizeof(refs[0])
            );
vxSetReferenceName((vx_reference)node, "PHASE_RGB");

Definition at line 707 of file phase_rgb_user_kernel.c.