Collaboration diagram for DOCA Context:

Typedefs
typedef void(*	doca_ctx_state_changed_callback_t) (const union doca_data user_data, struct doca_ctx *ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state)
	Function to execute on context state change. More...

Enumerations
enum	doca_ctx_states { DOCA_CTX_STATE_IDLE = 0 , DOCA_CTX_STATE_STARTING = 1 , DOCA_CTX_STATE_RUNNING = 2 , DOCA_CTX_STATE_STOPPING = 3 }
	This enum defines the states of a context. More...

Functions
DOCA_STABLE doca_error_t	doca_ctx_start (struct doca_ctx *ctx)
	Finalizes all configurations, and starts the DOCA CTX. More...

DOCA_STABLE doca_error_t	doca_ctx_stop (struct doca_ctx *ctx)
	Stops the context allowing reconfiguration. More...

DOCA_STABLE doca_error_t	doca_ctx_get_num_inflight_tasks (const struct doca_ctx ctx, size_t num_inflight_tasks)
	Get number of in flight tasks in a doca context. More...

DOCA_EXPERIMENTAL doca_error_t	doca_ctx_set_datapath_on_gpu (struct doca_ctx ctx, struct doca_gpu gpu_dev)
	This function binds the DOCA context to a gpu device. More...

DOCA_STABLE doca_error_t	doca_ctx_set_user_data (struct doca_ctx *ctx, union doca_data user_data)
	set user data to context More...

DOCA_STABLE doca_error_t	doca_ctx_get_user_data (const struct doca_ctx ctx, union doca_data user_data)
	get user data from context More...

DOCA_STABLE doca_error_t	doca_ctx_set_state_changed_cb (struct doca_ctx *ctx, doca_ctx_state_changed_callback_t cb)
	Set state changed callback. More...

DOCA_STABLE doca_error_t	doca_ctx_get_state (const struct doca_ctx ctx, enum doca_ctx_states state)
	Get context state. More...

DOCA_EXPERIMENTAL void	doca_ctx_flush_tasks (struct doca_ctx *ctx)
	Flushes tasks that were not flushed during submit. More...

DOCA_EXPERIMENTAL doca_error_t	doca_ctx_set_datapath_on_dpa (struct doca_ctx ctx, struct doca_dpa dpa_dev)
	This function binds the DOCA context to a dpa device. More...

DOCA_EXPERIMENTAL doca_error_t	doca_ctx_set_completion_vector (struct doca_ctx *ctx, uint32_t comp_vector)
	Set context completion vector. More...

DOCA_EXPERIMENTAL doca_error_t	doca_ctx_cap_get_num_completion_vectors (const struct doca_devinfo devinfo, uint32_t num_comp_vectors)
	Get number of completion vectors. More...

Detailed Description

DOCA CTX is the base class of every data-path library in DOCA. It is a specific library/SDK instance object providing abstract data processing functionality. The library exposes events and/or tasks that manipulate data.

Typedef Documentation

◆ doca_ctx_state_changed_callback_t

typedef void(* doca_ctx_state_changed_callback_t) (const union doca_data user_data, struct doca_ctx *ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state)

Function to execute on context state change.

This function is called when a context state is changed.

Parameters

[in] user_data user data supplied by the user (

See also: doca_ctx_set_user_data)

Parameters

[in]	ctx	doca_ctx that changed state
[in]	prev_state	Previous context state
[in]	next_state	Next context state (context is already in this state when the callback is called).

Definition at line 123 of file doca_ctx.h.

Enumeration Type Documentation

◆ doca_ctx_states

enum doca_ctx_states

This enum defines the states of a context.

The state machine:
                           +-------+
                           |       |
  +----------------------->| idle  +
  |                        |       |
  |                        +---+---+
  |                            |
  |                            | doca_ctx_start
  |                            | Synchronous: Change state to running and return DOCA_SUCCESS
  |                            | Asynchronous: Change state to started and return DOCA_ERROR_IN_PROGRESS
  | All in flight tasks are    |
  | drained or flushed         +-------------------------------------------+
  |                            |                                           |
  |                            |                                           |
  |                            V                                           V
  |                       +----------+                                +---------+
  |                       |          | Context is connected           |         |
  |                       | Starting |------------------------------->| Running |
  |                       |          |                                |         |
  |                       +----+-----+                                +----+----+
  |                            |                                           |
  |                            | doca_ctx_stop                             | doca_ctx_stop
  |                            |                                           |
  |                            v                                           |
  |                       +----------+                                     |
  |                       |          |                                     |
  |-----------------------+ Stopping |<------------------------------------+
                          |          |
                          +----------+

Enumerator
DOCA_CTX_STATE_IDLE	ctx is created Resources are not allocated, ctx can not allocate tasks, submit tasks, allocate events or register events.
DOCA_CTX_STATE_STARTING	doca_ctx_start called, context start is asynchronous. Resources are allocated, ctx can not allocate tasks, submit tasks, allocate events or register events.
DOCA_CTX_STATE_RUNNING	doca_ctx_start called (ctx start is synchronous) or ctx connection is completed. Resources are allocated, ctx can allocate tasks, submit tasks, allocate events and register events.
DOCA_CTX_STATE_STOPPING

Definition at line 83 of file doca_ctx.h.

Function Documentation

◆ doca_ctx_cap_get_num_completion_vectors()

DOCA_EXPERIMENTAL doca_error_t doca_ctx_cap_get_num_completion_vectors	(	const struct doca_devinfo *	devinfo,
		uint32_t *	num_comp_vectors
	)

Get number of completion vectors.

Parameters

[in]	devinfo	The device to query.
[out]	num_comp_vectors	Num completion vectors that the device supports. Valid completion vector is [0 - (num_comp_vectors - 1)].

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_ctx_flush_tasks()

DOCA_EXPERIMENTAL void doca_ctx_flush_tasks ( struct doca_ctx * ctx )

Flushes tasks that were not flushed during submit.

In case the DOCA_TASK_SUBMIT_FLAG_FLUSH was not provided during doca_task_submit_ex() this method can be used to flush the inflight tasks without the need to submit an additional task.

Parameters

[in] ctx The DOCA context to flush. MUST NOT BE IDLE

◆ doca_ctx_get_num_inflight_tasks()

DOCA_STABLE doca_error_t doca_ctx_get_num_inflight_tasks	(	const struct doca_ctx *	ctx,
		size_t *	num_inflight_tasks
	)

Get number of in flight tasks in a doca context.

This method retrieves the number of in flight tasks in a doca context

Parameters

[in]	ctx	Context to query
[out]	num_inflight_tasks	Total number of in flight tasks in the context

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_ctx_get_state()

DOCA_STABLE doca_error_t doca_ctx_get_state	(	const struct doca_ctx *	ctx,
		enum doca_ctx_states *	state
	)

Get context state.

This method retrieves the context state

Parameters

[in]	ctx	doca_ctx to get the state from
[out]	state	Current context state

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_ctx_get_user_data()

DOCA_STABLE doca_error_t doca_ctx_get_user_data	(	const struct doca_ctx *	ctx,
		union doca_data *	user_data
	)

get user data from context

This method retrieves user data from a context (previously set using doca_ctx_set_user_data).

Parameters

[in]	ctx	doca_ctx to get the user data from
[out]	user_data	user data to get

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_ctx_set_completion_vector()

DOCA_EXPERIMENTAL doca_error_t doca_ctx_set_completion_vector	(	struct doca_ctx *	ctx,
		uint32_t	comp_vector
	)

Set context completion vector.

A doca device has a set of completion vectors. Setting different completion vectors to different contexts may spread the CPU load more evenly. DOCA recommends to use the same completion vector for all contexts that are connected to a specific PE. However, Different doca devices may not map the same resources for the same completion vector.

Parameters

[in]	ctx	Context to set completion vector to
[in]	comp_vector	Completion vector to set

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - The context is not idle
DOCA_ERROR_NOT_SUPPORTED - The context does not support setting completion vector.

◆ doca_ctx_set_datapath_on_dpa()

DOCA_EXPERIMENTAL doca_error_t doca_ctx_set_datapath_on_dpa	(	struct doca_ctx *	ctx,
		struct doca_dpa *	dpa_dev
	)

This function binds the DOCA context to a dpa device.

The data path will be executed on the device and not on the CPU.

Parameters

[in]	ctx	The library instance.
[in]	dpa_dev	A pointer to a doca_dpa device.

Returns

DOCA_SUCCESS - In case of success. Error code - on failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - CTX is started.

◆ doca_ctx_set_datapath_on_gpu()

DOCA_EXPERIMENTAL doca_error_t doca_ctx_set_datapath_on_gpu	(	struct doca_ctx *	ctx,
		struct doca_gpu *	gpu_dev
	)

This function binds the DOCA context to a gpu device.

The data path will be executed on the device and not on the CPU.

Parameters

[in]	ctx	The library instance.
[in]	gpu_dev	A pointer to a doca_gpu device.

Returns

DOCA_SUCCESS - In case of success. Error code - on failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - CTX is started.

◆ doca_ctx_set_state_changed_cb()

DOCA_STABLE doca_error_t doca_ctx_set_state_changed_cb	(	struct doca_ctx *	ctx,
		doca_ctx_state_changed_callback_t	cb
	)

Set state changed callback.

This method sets state changed callback that is invoked every time that a context state is changed

Parameters

[in]	ctx	doca_ctx to set the callback to
[in]	cb	doca_ctx_state_changed_callback_t

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_ctx_set_user_data()

DOCA_STABLE doca_error_t doca_ctx_set_user_data	(	struct doca_ctx *	ctx,
		union doca_data	user_data
	)

set user data to context

This method sets a user data to a context. The user data is used as a parameter in doca_ctx_state_changed_callback_t

Parameters

[in]	ctx	doca_ctx to set the user data to
[in]	user_data	doca_data to set to the context

Returns

DOCA_SUCCESS Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_ctx_start()

DOCA_STABLE doca_error_t doca_ctx_start ( struct doca_ctx * ctx )

Finalizes all configurations, and starts the DOCA CTX.

After starting the CTX, it can't be configured any further. Use doca_ctx_stop in order to reconfigure the CTX.

The following become possible only after start:

Submitting a task using doca_task_submit()

The following are NOT possible after start and become possible again after calling doca_ctx_stop:

Changing CTX properties
Binding gpu device to CTX using doca_ctx_set_datapath_on_gpu()
Binding dpa device to CTX using doca_ctx_set_datapath_on_dpa()

Parameters

[in] ctx The DOCA context to start.

Returns

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

DOCA_ERROR_INVALID_VALUE - either an invalid input was received or no devices were added to the CTX.
DOCA_ERROR_NOT_SUPPORTED - one of the provided devices is not supported by CTX.
DOCA_ERROR_NOT_CONNECTED - ctx is not connected to a PE and data path on gpu or dpa was not set.
DOCA_ERROR_INITIALIZATION - resource initialization failed (could be due to allocation failure), or the device is in a bad state or another reason caused initialization to fail.
DOCA_ERROR_UNEXPECTED - ctx is corrupted.

◆ doca_ctx_stop()

DOCA_STABLE doca_error_t doca_ctx_stop ( struct doca_ctx * ctx )

Stops the context allowing reconfiguration.

Once a context has started, it can't be configured any further. This method should be called in case the context needs to be configured after starting. For more details see doca_ctx_start().

Parameters

[in] ctx The DOCA context to stop.

Returns

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

DOCA_ERROR_IN_PROGRESS - some tasks are still in progress. CTX will move to stopping state and a state changed callback shall be invoked when context is fully stopped.
DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_CONNECTED - ctx is not connected to a PE and data path on gpu or dpa was not set.
DOCA_ERROR_UNEXPECTED - ctx is corrupted.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ doca_ctx_state_changed_callback_t

Enumeration Type Documentation

◆ doca_ctx_states

Function Documentation

◆ doca_ctx_cap_get_num_completion_vectors()

◆ doca_ctx_flush_tasks()

◆ doca_ctx_get_num_inflight_tasks()

◆ doca_ctx_get_state()

◆ doca_ctx_get_user_data()

◆ doca_ctx_set_completion_vector()

◆ doca_ctx_set_datapath_on_dpa()

◆ doca_ctx_set_datapath_on_gpu()

◆ doca_ctx_set_state_changed_cb()

◆ doca_ctx_set_user_data()

◆ doca_ctx_start()

◆ doca_ctx_stop()