Pipelining and Batch Processing

Data Structures
struct	vx_graph_parameter_queue_params_t

Macros
#define	VX_LIBRARY_KHR_PIPELINING_EXTENSION   (0x1)

Enumerations
enum	vx_graph_schedule_mode_enum_e
enum	vx_graph_schedule_mode_type_e
enum	vx_graph_attribute_pipelining_e

Functions
vx_status	vxSetGraphScheduleConfig (vx_graph graph, vx_enum graph_schedule_mode, uint32_t graph_parameters_list_size, const vx_graph_parameter_queue_params_t graph_parameters_queue_params_list[])
vx_status	vxGraphParameterEnqueueReadyRef (vx_graph graph, vx_uint32 graph_parameter_index, vx_reference *refs, vx_uint32 num_refs)
vx_status	vxGraphParameterDequeueDoneRef (vx_graph graph, vx_uint32 graph_parameter_index, vx_reference *refs, vx_uint32 max_refs, vx_uint32 *num_refs)
vx_status	vxGraphParameterCheckDoneRef (vx_graph graph, vx_uint32 graph_parameter_index, vx_uint32 *num_refs)

Detailed Description

This section lists the APIs required for graph pipelining and batch processing.

---

Data Structure Documentation

struct vx_graph_parameter_queue_params_t

Queueing parameters for a specific graph parameter.

See vxSetGraphScheduleConfig for additional details.

Definition at line 101 of file vx_khr_pipelining.h.

Collaboration diagram for vx_graph_parameter_queue_params_t:

Data Fields
uint32_t	graph_parameter_index	Index of graph parameter to which these properties apply.
vx_uint32	refs_list_size	Number of elements in array 'refs_list'.
vx_reference *	refs_list	Array of references that could be enqueued at a later point of time at this graph parameter.

Enumeration Type Documentation

enum vx_graph_schedule_mode_enum_e

Extra enums.

Enumerator
VX_ENUM_GRAPH_SCHEDULE_MODE_TYPE	Graph schedule mode type enumeration.

Definition at line 59 of file vx_khr_pipelining.h.

enum vx_graph_schedule_mode_type_e

Type of graph scheduling mode.

See vxSetGraphScheduleConfig and vxGraphParameterEnqueueReadyRef for details about each mode.

Enumerator
VX_GRAPH_SCHEDULE_MODE_NORMAL	Schedule graph in non-queueing mode.
VX_GRAPH_SCHEDULE_MODE_QUEUE_AUTO	Schedule graph in queueing mode with auto scheduling.
VX_GRAPH_SCHEDULE_MODE_QUEUE_MANUAL	Schedule graph in queueing mode with manual scheduling.

Definition at line 70 of file vx_khr_pipelining.h.

enum vx_graph_attribute_pipelining_e

The graph attributes added by this extension.

Enumerator
VX_GRAPH_SCHEDULE_MODE	Returns the schedule mode of a graph. Read-only. Use a vx_enum parameter. See vx_graph_schedule_mode_type_e enum.

Definition at line 88 of file vx_khr_pipelining.h.

Function Documentation

vx_status vxSetGraphScheduleConfig	(	vx_graph	graph,
		vx_enum	graph_schedule_mode,
		uint32_t	graph_parameters_list_size,
		const vx_graph_parameter_queue_params_t	graph_parameters_queue_params_list[]
	)

Sets the graph scheduler config.

This API is used to set the graph scheduler config to allow user to schedule multiple instances of a graph for execution.

For legacy applications that don't need graph pipelining or batch processing, this API need not be used.

Using this API, the application specifies the graph schedule mode, as well as queueing parameters for all graph parameters that need to allow enqueueing of references. A single monolithic API is provided instead of discrete APIs, since this allows the implementation to get all information related to scheduling in one shot and then optimize the subsequent graph scheduling based on this information. This API MUST be called before graph verify since in this case it allows implementations the opportunity to optimize resources based on information provided by the application.

'graph_schedule_mode' selects how input and output references are provided to a graph and how the next graph schedule is triggered by an implementation.

Below scheduling modes are supported:

When graph schedule mode is VX_GRAPH_SCHEDULE_MODE_QUEUE_AUTO:

• Application needs to explicitly call vxVerifyGraph before enqueing data references
• Application should not call vxScheduleGraph or vxProcessGraph
• When enough references are enqueued at various graph parameters, the implementation could trigger the next graph schedule.
• Here, not all graph parameters need to have enqueued references for a graph schedule to begin. An implementation is expected to execute the graph as much as possible until a enqueued reference is not available at which time it will stall the graph until the reference becomes available. This allows application to schedule a graph even when all parameters references are not yet available, i.e do a 'late' enqueue. However, exact behaviour is implementation specific.

When graph schedule mode is VX_GRAPH_SCHEDULE_MODE_QUEUE_MANUAL:

• Application needs to explicitly call vxScheduleGraph
• Application should not call vxProcessGraph
• References for all graph parameters of the graph needs to enqueued before vxScheduleGraph is called on the graph else an error is returned by vxScheduleGraph
• Application can enqueue multiple references at the same graph parameter. When vxScheduleGraph is called, all enqueued references get processed in a 'batch'.
• User can use vxWaitGraph to wait for the previous vxScheduleGraph to complete.

When graph schedule mode is VX_GRAPH_SCHEDULE_MODE_NORMAL:

• 'graph_parameters_list_size' MUST be 0 and
• 'graph_parameters_queue_params_list' MUST be NULL
• This mode is equivalent to non-queueing scheduling mode as defined by OpenVX v1.2 and earlier.

By default all graphs are in VX_GRAPH_SCHEDULE_MODE_NORMAL mode until this API is called.

'graph_parameters_queue_params_list' allows to specify below information:

• For the graph parameter index that is specified, it enables queueing mode of operation
• Further it allows the application to specify the list of references that it could later enqueue at this graph parameter.

For graph parameters listed in 'graph_parameters_queue_params_list', application MUST use vxGraphParameterEnqueueReadyRef to set references at the graph parameter. Using other data access API's on these parameters or corresponding data objects will return an error. For graph parameters not listed in 'graph_parameters_queue_params_list' application MUST use the vxSetGraphParameterByIndex to set the reference at the graph parameter. Using other data access API's on these parameters or corresponding data objects will return an error.

This API also allows application to provide a list of references which could be later enqueued at the graph parameter. This allows implementation to do meta-data checking up front rather than during each reference enqueue.

When this API is called before vxVerifyGraph, the 'refs_list' field can be NULL, if the reference handles are not available yet at the application. However 'refs_list_size' MUST always be specified by the application. Application can call vxSetGraphScheduleConfig again after verify graph with all parameters remaining the same except with 'refs_list' field providing the list of references that can be enqueued at the graph parameter.

Parameters

[in]	graph	Graph reference
[in]	graph_schedule_mode	Graph schedule mode. See vx_graph_schedule_mode_type_e
[in]	graph_parameters_list_size	Number of elements in graph_parameters_queue_params_list
[in]	graph_parameters_queue_params_list	Array containing queuing properties at graph parameters that need to support queueing.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference
VX_ERROR_INVALID_PARAMETERS	Invalid graph parameter queueing parameters
VX_FAILURE	Any other failure.

vx_status vxGraphParameterEnqueueReadyRef	(	vx_graph	graph,
		vx_uint32	graph_parameter_index,
		vx_reference *	refs,
		vx_uint32	num_refs
	)

Enqueues new references into a graph parameter for processing.

This new reference will take effect on the next graph schedule.

In case of a graph parameter which is input to a graph, this function provides a data reference with new input data to the graph. In case of a graph parameter which is not input to a graph, this function provides a 'empty' reference into which a graph execution can write new data into.

This function essentially transfers ownership of the reference from the application to the graph.

User MUST use vxGraphParameterDequeueDoneRef to get back the processed or consumed references.

The references that are enqueued MUST be the references listed during vxSetGraphScheduleConfig. If a reference outside this list is provided then behaviour is undefined.

Parameters

[in]	graph	Graph reference
[in]	graph_parameter_index	Graph parameter index
[in]	refs	The array of references to enqueue into the graph parameter
[in]	num_refs	Number of references to enqueue

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference OR reference is not a valid reference
VX_ERROR_INVALID_PARAMETERS	graph_parameter_index is NOT a valid graph parameter index
VX_FAILURE	Reference could not be enqueued.

vx_status vxGraphParameterDequeueDoneRef	(	vx_graph	graph,
		vx_uint32	graph_parameter_index,
		vx_reference *	refs,
		vx_uint32	max_refs,
		vx_uint32 *	num_refs
	)

Dequeues 'consumed' references from a graph parameter.

This function dequeues references from a graph parameter of a graph. The reference that is dequeued is a reference that had been previously enqueued into a graph, and after subsequent graph execution is considered as processed or consumed by the graph. This function essentially transfers ownership of the reference from the graph to the application.

IMPORTANT : This API will block until at least one reference is dequeued.

In case of a graph parameter which is input to a graph, this function provides a 'consumed' buffer to the application so that new input data can filled and later enqueued to the graph. In case of a graph parameter which is not input to a graph, this function provides a reference filled with new data based on graph execution. User can then use this newly generated data with their application. Typically when this new data is consumed by the application the 'empty' reference is again enqueued to the graph.

This API returns an array of references up to a maximum of 'max_refs'. Application MUST ensure the array pointer ('refs') passed as input can hold 'max_refs'. 'num_refs' is actual number of references returned and will be <= 'max_refs'.

Parameters

[in]	graph	Graph reference
[in]	graph_parameter_index	Graph parameter index
[in]	refs	Pointer to an array of max elements 'max_refs'
[out]	refs	Dequeued references filled in the array
[in]	max_refs	Max number of references to dequeue
[out]	num_refs	Actual number of references dequeued.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference
VX_ERROR_INVALID_PARAMETERS	graph_parameter_index is NOT a valid graph parameter index
VX_FAILURE	Reference could not be dequeued.

vx_status vxGraphParameterCheckDoneRef	(	vx_graph	graph,
		vx_uint32	graph_parameter_index,
		vx_uint32 *	num_refs
	)

Checks and returns the number of references that are ready for dequeue.

This function checks the number of references that can be dequeued and returns the value to the application.

See also vxGraphParameterDequeueDoneRef.

Parameters

[in]	graph	Graph reference
[in]	graph_parameter_index	Graph parameter index
[out]	num_refs	Number of references that can be dequeued using

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	graph is not a valid reference
VX_ERROR_INVALID_PARAMETERS	graph_parameter_index is NOT a valid graph parameter index
VX_FAILURE	Any other failure.