Collaboration diagram for DOCA Progress Engine:

Typedefs
typedef void(*	doca_task_completion_cb_t) (struct doca_task *task, union doca_data task_user_data, union doca_data ctx_user_data)
	Function to execute on task completion. More...

Enumerations
enum	doca_task_batch_max_tasks_number { DOCA_TASK_BATCH_MAX_TASKS_NUMBER_16 , DOCA_TASK_BATCH_MAX_TASKS_NUMBER_32 , DOCA_TASK_BATCH_MAX_TASKS_NUMBER_64 , DOCA_TASK_BATCH_MAX_TASKS_NUMBER_128 }

enum	doca_event_batch_events_number { DOCA_EVENT_BATCH_EVENTS_NUMBER_1 , DOCA_EVENT_BATCH_EVENTS_NUMBER_2 , DOCA_EVENT_BATCH_EVENTS_NUMBER_4 , DOCA_EVENT_BATCH_EVENTS_NUMBER_8 , DOCA_EVENT_BATCH_EVENTS_NUMBER_16 , DOCA_EVENT_BATCH_EVENTS_NUMBER_32 , DOCA_EVENT_BATCH_EVENTS_NUMBER_64 , DOCA_EVENT_BATCH_EVENTS_NUMBER_128 }

enum	doca_task_submit_flag { DOCA_TASK_SUBMIT_FLAG_NONE = 0U , DOCA_TASK_SUBMIT_FLAG_FLUSH = (1U << 0) , DOCA_TASK_SUBMIT_FLAG_OPTIMIZE_REPORTS = (1U << 1) }
	Flags used when submitting a doca_task. More...

enum	doca_pe_event_mode { DOCA_PE_EVENT_MODE_PROGRESS_SELECTIVE , DOCA_PE_EVENT_MODE_PROGRESS_ALL }
	Progress engine event modes. More...

Functions
DOCA_STABLE doca_error_t	doca_pe_create (struct doca_pe **pe)
	Creates DOCA progress engine. More...

DOCA_STABLE doca_error_t	doca_pe_destroy (struct doca_pe *pe)
	Destroy doca progress engine. More...

DOCA_STABLE uint8_t	doca_pe_progress (struct doca_pe *pe)
	Run the progress engine. More...

DOCA_STABLE doca_error_t	doca_pe_clear_notification (struct doca_pe *pe, doca_notification_handle_t handle)
	Clear triggered completions after wait. More...

DOCA_STABLE doca_error_t	doca_pe_request_notification (struct doca_pe *pe)
	Arm the progress engine to wait for completion. More...

DOCA_STABLE doca_error_t	doca_pe_get_num_inflight_tasks (const struct doca_pe pe, size_t num_inflight_tasks)
	Get number of in flight tasks. More...

DOCA_STABLE doca_error_t	doca_task_submit (struct doca_task *task)
	Submit a task to a progress engine. More...

DOCA_EXPERIMENTAL doca_error_t	doca_task_submit_ex (struct doca_task *task, uint32_t flags)
	Extended version of doca_task_submit. More...

DOCA_EXPERIMENTAL doca_error_t	doca_task_batch_submit (struct doca_task_batch *task_batch)
	Submit a task_batch to a progress engine. More...

DOCA_STABLE doca_error_t	doca_task_try_submit (struct doca_task *task)
	Try to submit a task to a progress engine. More...

DOCA_EXPERIMENTAL doca_error_t	doca_task_batch_try_submit (struct doca_task_batch *task_batch)
	Try to submit a task_batch to a progress engine. More...

DOCA_STABLE void	doca_task_free (struct doca_task *task)
	Free a task back to where it was allocated from. More...

DOCA_EXPERIMENTAL void	doca_task_batch_free (struct doca_task_batch *task_batch)
	Free a task_batch back to where it was allocated from. More...

DOCA_STABLE doca_error_t	doca_task_get_status (const struct doca_task *task)
	Get task status. More...

DOCA_EXPERIMENTAL doca_error_t	doca_task_batch_get_status (const struct doca_task_batch *task_batch)
	Get task_batch status. More...

DOCA_STABLE void	doca_task_set_user_data (struct doca_task *task, union doca_data user_data)
	Set user data to a task. More...

DOCA_EXPERIMENTAL void	doca_task_batch_set_user_data (struct doca_task_batch *task_batch, union doca_data user_data)
	Set user data to a task_batch. More...

DOCA_STABLE union doca_data	doca_task_get_user_data (const struct doca_task *task)
	Get user data from a task. More...

DOCA_EXPERIMENTAL union doca_data	doca_task_batch_get_user_data (const struct doca_task_batch *task_batch)
	Get user data from a task_batch. More...

DOCA_STABLE struct doca_ctx *	doca_task_get_ctx (const struct doca_task *task)
	Get context from a doca task. More...

DOCA_EXPERIMENTAL struct doca_ctx *	doca_task_batch_get_ctx (const struct doca_task_batch *task_batch)
	Get context from a doca task_batch. More...

DOCA_EXPERIMENTAL union doca_data	doca_task_batch_get_ctx_user_data (const struct doca_task_batch *task_batch)
	Get context user data from a doca task_batch. More...

DOCA_EXPERIMENTAL uint16_t	doca_task_batch_get_tasks_num (struct doca_task_batch *task_batch)
	Get actual tasks number from a doca task_batch. More...

DOCA_STABLE doca_error_t	doca_pe_connect_ctx (struct doca_pe pe, struct doca_ctx ctx)
	This method connects a context to a progress engine. More...

DOCA_EXPERIMENTAL doca_error_t	doca_pe_set_event_mode (struct doca_pe *pe, enum doca_pe_event_mode event_mode)
	Set event mode. More...

Detailed Description

Typedef Documentation

◆ doca_task_completion_cb_t

typedef void(* doca_task_completion_cb_t) (struct doca_task *task, union doca_data task_user_data, union doca_data ctx_user_data)

Function to execute on task completion.

This function is called by doca_pe_progress() when related task identified as completed successfully. When this function called the ownership of the task object passed from DOCA back to user. User may decide on the task object inside this callback:

re-submit task with doca_task_submit(); task object ownership passed to DOCA
release task with doca_task_free(); task object ownership passed to DOCA
keep the task object for future re-use; user keeps the ownership on the task object. All tasks MUST be freed before stopping the context (drained tasks should be freed during stop flow). Inside this callback the user shouldn't call doca_pe_progress(). Please see doca_pe_progress for details.

Any failure/error inside this function should be handled internally or differed; due to the mode of nested in doca_pe_progress() execution this callback doesn't return error.

NOTE: this callback type utilizes successful & failed task completions.

Parameters

[in]	task	The successfully completed task. The implementation can assume this value is not NULL.
[in]	task_user_data	task user data
[in]	ctx_user_data	doca_ctx user data

Definition at line 136 of file doca_pe.h.

Enumeration Type Documentation

◆ doca_event_batch_events_number

enum doca_event_batch_events_number

Supported batch sizes for event batches

Enumerator
DOCA_EVENT_BATCH_EVENTS_NUMBER_1
DOCA_EVENT_BATCH_EVENTS_NUMBER_2
DOCA_EVENT_BATCH_EVENTS_NUMBER_4
DOCA_EVENT_BATCH_EVENTS_NUMBER_8
DOCA_EVENT_BATCH_EVENTS_NUMBER_16
DOCA_EVENT_BATCH_EVENTS_NUMBER_32
DOCA_EVENT_BATCH_EVENTS_NUMBER_64
DOCA_EVENT_BATCH_EVENTS_NUMBER_128

Definition at line 58 of file doca_pe.h.

◆ doca_pe_event_mode

enum doca_pe_event_mode

Progress engine event modes.

Enumerator
DOCA_PE_EVENT_MODE_PROGRESS_SELECTIVE
DOCA_PE_EVENT_MODE_PROGRESS_ALL

Definition at line 101 of file doca_pe.h.

◆ doca_task_batch_max_tasks_number

enum doca_task_batch_max_tasks_number

Supported batch sizes for doca_task_batch

Enumerator
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_16
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_32
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_64
DOCA_TASK_BATCH_MAX_TASKS_NUMBER_128

Definition at line 48 of file doca_pe.h.

◆ doca_task_submit_flag

enum doca_task_submit_flag

Flags used when submitting a doca_task.

These flags can be provided during task submission as part of doca_task_submit_ex

Enumerator
DOCA_TASK_SUBMIT_FLAG_NONE
DOCA_TASK_SUBMIT_FLAG_FLUSH
DOCA_TASK_SUBMIT_FLAG_OPTIMIZE_REPORTS	Use flag to inform doca_ctx to flush this task and previous tasks to HW, otherwise doca_ctx may aggregate the task and not flush it immediately. This is the default submit behavior Considerations: submitting without this flag may allow the doca_ctx to optimize submission to HW, by first aggregating a batch of tasks, and then flushing them all at once

Definition at line 74 of file doca_pe.h.

Function Documentation

◆ doca_pe_clear_notification()

DOCA_STABLE doca_error_t doca_pe_clear_notification	(	struct doca_pe *	pe,
		doca_notification_handle_t	handle
	)

Clear triggered completions after wait.

Method used for clearing of events, this method should be called after an event has been received using the event handle. After this method is called, the events will no longer be triggered, and the handle can be armed again. See doca_pe_request_notification() for entire flow. Linux only: doca_pe_clear_notification does not have to be invoked when event mode is set to DOCA_PE_EVENT_MODE_PROGRESS_ALL. In such case doca_pe_request_notification will clear previous notifications.

Parameters

[in]	pe	The progress engine object that received the events. MUST NOT BE NULL.
[in]	handle	progress engine event handle.

Returns

DOCA_SUCCESS - on successfully clearing triggered events.
DOCA_ERROR_OPERATING_SYSTEM - a system call has failed.

◆ doca_pe_connect_ctx()

DOCA_STABLE doca_error_t doca_pe_connect_ctx	(	struct doca_pe *	pe,
		struct doca_ctx *	ctx
	)

This method connects a context to a progress engine.

: The connection can only be broken by destroying the context.

Parameters

[in]	pe	Progress engine to connect the context to
[in]	ctx	Context to connect

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - context or pe argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to allocate resources for the context.
DOCA_ERROR_BAD_STATE - context is not idle
DOCA_ERROR_NOT_PERMITTED - context is already connected to a progress engine.

◆ doca_pe_create()

DOCA_STABLE doca_error_t doca_pe_create ( struct doca_pe ** pe )

Creates DOCA progress engine.

The progress engine is used to progress tasks and events. The progress engine is associated with one or more doca contexts. A doca context can only be associated with one progress engine.

Parameters

[out] pe progress engine to create

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_NO_MEMORY - failed to allocate progress engine.

◆ doca_pe_destroy()

DOCA_STABLE doca_error_t doca_pe_destroy ( struct doca_pe * pe )

Destroy doca progress engine.

This function destroys a progress engine. Progress engine can be destroyed only after all connected contexts has been destroyed.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - invalid input received.
DOCA_ERROR_IN_USE - contexts are still connected to the progress engine.

◆ doca_pe_get_num_inflight_tasks()

DOCA_STABLE doca_error_t doca_pe_get_num_inflight_tasks	(	const struct doca_pe *	pe,
		size_t *	num_inflight_tasks
	)

Get number of in flight tasks.

This method retrieves the number of in flight tasks in a progress engine

Parameters

[in]	pe	Progress engine to query
[out]	num_inflight_tasks	Total number of in flight tasks in the progress engine

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_pe_progress()

DOCA_STABLE uint8_t doca_pe_progress ( struct doca_pe * pe )

Run the progress engine.

Polling method for progress of submitted tasks and handling of registered events. The method finds the next context with a completed task and invokes its completion callback.

Parameters

[in] pe The progress engine object to poll for completions. MUST NOT BE NULL.

Returns: 1 if progress was made, 0 otherwise. Examples: A task was completed (fully, partially). Unsolicited event handled. Context state transition (starting -> running or stopping -> idle).

◆ doca_pe_request_notification()

DOCA_STABLE doca_error_t doca_pe_request_notification ( struct doca_pe * pe )

Arm the progress engine to wait for completion.

This method should be used before waiting on the completion handle. The expected flow is as follows:

Get or set event handle using doca_pe_get_notification_handle or doca_pe_set_notification_handle
Arm the progress engine.
Wait for an event using the event handle. E.g., using epoll_wait().
Once the thread wakes up, call doca_pe_clear_notification().
Call doca_pe_progress() until it returns 0 (implies that no more tasks, events or other progress is done)
Repeat 2.

Parameters

[in] pe The progress engine object to arm. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - progress engine has been successfully armed, event handle can be used to wait on events.

◆ doca_pe_set_event_mode()

DOCA_EXPERIMENTAL doca_error_t doca_pe_set_event_mode	(	struct doca_pe *	pe,
		enum doca_pe_event_mode	event_mode
	)

Set event mode.

Setting event mode affects doca_pe_progress behavior.

See also: enum doca_pe_event_mode for more details. Event mode can be set during run time, but not in the context of a task completion callback.

Parameters

[in]	pe	The progress engine to set
[in]	event_mode	The new event mode.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_task_batch_free()

DOCA_EXPERIMENTAL void doca_task_batch_free ( struct doca_task_batch * task_batch )

Free a task_batch back to where it was allocated from.

This function frees a task_batch back to the where it was allocated from (usually a doca_ctx) Task Batch allocation is a per context API. All task_batches MUST be freed in order for a context to be stopped. A task_batch can be freed during completion / error callback or at any other place in the program as long as it is not submitted.

Parameters

[in] task_batch The task_batch to free

◆ doca_task_batch_get_ctx()

DOCA_EXPERIMENTAL struct doca_ctx* doca_task_batch_get_ctx ( const struct doca_task_batch * task_batch )

Get context from a doca task_batch.

This method retrieves the context from a doca task_batch

Parameters

[in] task_batch The task_batch to get the context from

Returns: doca_ctx - the context that allocated the task_batch.

◆ doca_task_batch_get_ctx_user_data()

DOCA_EXPERIMENTAL union doca_data doca_task_batch_get_ctx_user_data ( const struct doca_task_batch * task_batch )

Get context user data from a doca task_batch.

This method retrieves the context user data from a doca task_batch

Parameters

[in] task_batch The task_batch to get the context user data from

Returns: doca_ctx - the context user data that allocated the task_batch.

◆ doca_task_batch_get_status()

DOCA_EXPERIMENTAL doca_error_t doca_task_batch_get_status ( const struct doca_task_batch * task_batch )

Get task_batch status.

This method retrieves the status of a doca_task_batch

Parameters

[in] task_batch The task_batch to retrieve the status from

Returns: DOCA_SUCCESS - task_batch execution was successful Any other doca_error_t indicates that the task_batch failed (task_batch type dependent)

◆ doca_task_batch_get_tasks_num()

DOCA_EXPERIMENTAL uint16_t doca_task_batch_get_tasks_num ( struct doca_task_batch * task_batch )

Get actual tasks number from a doca task_batch.

This method retrieves the actual tasks number from a doca task_batch

Parameters

[in] task_batch The task_batch to get the tasks number from

Returns: uint16_t - the actual tasks number in the task_batch.

◆ doca_task_batch_get_user_data()

DOCA_EXPERIMENTAL union doca_data doca_task_batch_get_user_data ( const struct doca_task_batch * task_batch )

Get user data from a task_batch.

This method retrieves user data from a doca_task_batch

Parameters

[in] task_batch doca_task_batch to get the user data from

Returns: doca_data - user data that was stored in the task_batch

◆ doca_task_batch_set_user_data()

DOCA_EXPERIMENTAL void doca_task_batch_set_user_data	(	struct doca_task_batch *	task_batch,
		union doca_data	user_data
	)

Set user data to a task_batch.

This method sets a user data to a task_batch

Parameters

[in]	task_batch	doca_task_batch to set the user data to
[in]	user_data	doca_data to set

◆ doca_task_batch_submit()

DOCA_EXPERIMENTAL doca_error_t doca_task_batch_submit ( struct doca_task_batch * task_batch )

Submit a task_batch to a progress engine.

This function submits a task_batch to a progress engine. The function DOES NOT validate the task_batch. The task batch is routed to the relevant context and will be executed asynchronously. See doca_pe_progress for task_batch completion details. The task_batch will be owned by DOCA upon a successful submission.

Parameters

[in] task_batch The task_batch to submit

Returns

DOCA_SUCCESS - on successfully submitting the task_batch.
Any other doca_error_t implies task_batch submission failure. In that case the user owns the task_batch.

◆ doca_task_batch_try_submit()

DOCA_EXPERIMENTAL doca_error_t doca_task_batch_try_submit ( struct doca_task_batch * task_batch )

Try to submit a task_batch to a progress engine.

This function submits a task_batch to a progress engine. The function validates the task_batch (task_batch validation is different per task_batch type). If the task_batch is invalid it will not be submitted. The task_batch is routed to the relevant context and will be executed asynchronously. See doca_pe_progress for task_batch completion details. The task_batch will be owned by DOCA upon a successful submission.

Parameters

[in] task_batch The task_batch to submit

Returns

DOCA_SUCCESS - on successfully submitting the task_batch.
DOCA_ERROR_INVALID_VALUE - The task_batch is invalid (e.g., one of the fields is incorrect or null).
Any other doca_error_t implies task_batch submission failure. In that case the user owns the task_batch.

◆ doca_task_free()

DOCA_STABLE void doca_task_free ( struct doca_task * task )

Free a task back to where it was allocated from.

This function frees a task back to the where it was allocated from (usually a doca_ctx) Task allocation is a per context API. All tasks MUST be freed in order for a context to be stopped. A task can be freed during completion / error callback or at any other place in the program as long as it is not submitted.

Parameters

[in] task to free

◆ doca_task_get_ctx()

DOCA_STABLE struct doca_ctx* doca_task_get_ctx ( const struct doca_task * task )

Get context from a doca task.

This method retrieves the context from a doca task

Parameters

[in] task The task to get the context from

Returns: doca_ctx - the context that allocated the task.

◆ doca_task_get_status()

DOCA_STABLE doca_error_t doca_task_get_status ( const struct doca_task * task )

Get task status.

This method retrieves the status of a doca_task

Parameters

[in] task The task to retrieve the status from

Returns: DOCA_SUCCESS - task execution was successful Any other doca_error_t indicates that the task failed (task depended)

◆ doca_task_get_user_data()

DOCA_STABLE union doca_data doca_task_get_user_data ( const struct doca_task * task )

Get user data from a task.

This method retrieves user data from a doca_task

Parameters

[in] task doca_task to get the user data from

Returns: doca_data - user data that was stored in the task

◆ doca_task_set_user_data()

DOCA_STABLE void doca_task_set_user_data	(	struct doca_task *	task,
		union doca_data	user_data
	)

Set user data to a task.

This method sets a user data to a task

Parameters

[in]	task	doca_task to set the user data to
[in]	user_data	doca_data to set

◆ doca_task_submit()

DOCA_STABLE doca_error_t doca_task_submit ( struct doca_task * task )

Submit a task to a progress engine.

This function submits a task to a progress engine. The function DOES NOT validate the task. The task is routed to the relevant context and will be executed asynchronously. See doca_pe_progress for task completion details. The task will be owned by DOCA upon a successful submission.

Parameters

[in] task The task to submit

Returns

DOCA_SUCCESS - on successfully submitting the task.
Any other doca_error_t implies task submission failure. In that case the user owns the task.

◆ doca_task_submit_ex()

DOCA_EXPERIMENTAL doca_error_t doca_task_submit_ex	(	struct doca_task *	task,
		uint32_t	flags
	)

Extended version of doca_task_submit.

Same as doca_task_submit, but with ability to provide flags, see enum doca_task_submit_flag

Parameters

[in]	task	The task to submit
[in]	flags	Additional submit flags, bitwise or of enum doca_task_submit_flag

Returns

DOCA_SUCCESS - on successfully submitting the task.
Any other doca_error_t implies task submission failure. In that case the user owns the task.

◆ doca_task_try_submit()

DOCA_STABLE doca_error_t doca_task_try_submit ( struct doca_task * task )

Try to submit a task to a progress engine.

This function submits a task to a progress engine. The function validates the task (task validation is different per task). If the task is invalid it will not be submitted. The task is routed to the relevant context and will be executed asynchronously. See doca_pe_progress for task completion details. The task will be owned by DOCA upon a successful submission.

Parameters

[in] task The task to submit

Returns

DOCA_SUCCESS - on successfully submitting the task.
DOCA_ERROR_INVALID_VALUE - The task is invalid (e.g., one of the fields is incorrect or null).
Any other doca_error_t implies task submission failure. In that case the user owns the task.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ doca_task_completion_cb_t

Enumeration Type Documentation

◆ doca_event_batch_events_number

◆ doca_pe_event_mode

◆ doca_task_batch_max_tasks_number

◆ doca_task_submit_flag

Function Documentation

◆ doca_pe_clear_notification()

◆ doca_pe_connect_ctx()

◆ doca_pe_create()

◆ doca_pe_destroy()

◆ doca_pe_get_num_inflight_tasks()

◆ doca_pe_progress()

◆ doca_pe_request_notification()

◆ doca_pe_set_event_mode()

◆ doca_task_batch_free()

◆ doca_task_batch_get_ctx()

◆ doca_task_batch_get_ctx_user_data()

◆ doca_task_batch_get_status()

◆ doca_task_batch_get_tasks_num()

◆ doca_task_batch_get_user_data()

◆ doca_task_batch_set_user_data()

◆ doca_task_batch_submit()

◆ doca_task_batch_try_submit()

◆ doca_task_free()

◆ doca_task_get_ctx()

◆ doca_task_get_status()

◆ doca_task_get_user_data()

◆ doca_task_set_user_data()

◆ doca_task_submit()

◆ doca_task_submit_ex()

◆ doca_task_try_submit()