Collaboration diagram for DOCA UROM Workers:

Macros
#define	DOCA_UROM_WORKER_ID_ANY -1ULL
	DOCA UROM WORKER ID any give the library the responsibility to generate a worker id. More...

Typedefs
typedef void(*	doca_urom_worker_cmd_task_completion_cb_t) (struct doca_urom_worker_cmd_task *task, union doca_data task_user_data, union doca_data ctx_user_data)
	Worker Command task completion callback type. More...

Functions
DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_create (struct doca_urom_worker **worker_ctx)
	This method creates a UROM Worker context. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_destroy (struct doca_urom_worker *worker_ctx)
	This method destroys a UROM Worker context. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_set_service (struct doca_urom_worker worker_ctx, struct doca_urom_service service_ctx)
	This method attaches a UROM Service to the Worker context. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_set_id (struct doca_urom_worker *worker_ctx, uint64_t worker_id)
	This method sets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_set_plugins (struct doca_urom_worker *worker_ctx, uint64_t plugins)
	This method adds plugins mask for the supported plugins by the UROM Worker on the DPU. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_set_cpuset (struct doca_urom_worker *worker_ctx, doca_cpu_set_t cpuset)
	Set the allowed CPUs for the Worker. The cpuset must be a subset of the service's allowed CPUs. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_set_gid (struct doca_urom_worker *worker_ctx, uint32_t gid)
	Set worker group ID, must be set before starting the worker context. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_set_max_inflight_tasks (struct doca_urom_worker *worker_ctx, uint32_t max_tasks)
	Set Worker maximum in-flight tasks. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_set_env (struct doca_urom_worker worker_ctx, char const env[], size_t count)
	Set worker env variables when spawning worker on DPU side. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_get_id (struct doca_urom_worker worker_ctx, uint64_t worker_id)
	This method gets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device. If when creating the worker the user sets worker id equals to DOCA_UROM_WORKER_ID_ANY the library will generate new id for the worker. More...

DOCA_EXPERIMENTAL doca_error_t	doca_urom_worker_get_gid (struct doca_urom_worker worker_ctx, uint32_t worker_gid)
	This method gets the Worker context group ID to be used to identify the Worker group that belongs to. More...

DOCA_EXPERIMENTAL struct doca_ctx *	doca_urom_worker_as_ctx (struct doca_urom_worker *worker_ctx)

Detailed Description

DOCA UROM Worker interfaces and data structures.

The UROM Worker represents a process running on a DOCA device. The process may be used to offload application logic to the device. Application logic is defined in Worker plugins. A Worker may be configured to support one or more plugins concurrently. Users submit DOCA tasks to a Worker in order to initiate an offloaded operation.

Macro Definition Documentation

◆ DOCA_UROM_WORKER_ID_ANY

#define DOCA_UROM_WORKER_ID_ANY -1ULL

DOCA UROM WORKER ID any give the library the responsibility to generate a worker id.

Definition at line 556 of file doca_urom.h.

Typedef Documentation

◆ doca_urom_worker_cmd_task_completion_cb_t

typedef void(* doca_urom_worker_cmd_task_completion_cb_t) (struct doca_urom_worker_cmd_task *task, union doca_data task_user_data, union doca_data ctx_user_data)

Worker Command task completion callback type.

Definition at line 485 of file doca_urom.h.

Function Documentation

◆ doca_urom_worker_as_ctx()

DOCA_EXPERIMENTAL struct doca_ctx* doca_urom_worker_as_ctx ( struct doca_urom_worker * worker_ctx )

Convert worker_ctx instance into a generalized context for use with DOCA core objects.

Parameters

[in] worker_ctx Worker context instance. This must remain valid until after the context is no longer required.

Returns: Non NULL upon success, NULL otherwise.

◆ doca_urom_worker_create()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_create ( struct doca_urom_worker ** worker_ctx )

This method creates a UROM Worker context.

`

A Worker is created in state DOCA_CTX_STATE_IDLE. After creation, a user may configure the Worker using setter methods (e.g. doca_urom_worker_set_service()). Before use, a Worker must be transitioned to state DOCA_CTX_STATE_RUNNING using the doca_ctx_start() interface. A typical invocation looks like:

doca_ctx_start(doca_urom_worker_as_ctx(worker_ctx))

Parameters

[out] worker_ctx The new Worker context.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.
DOCA_ERROR_NO_MEMORY - failed to alloc worker_ctx.

◆ doca_urom_worker_destroy()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_destroy ( struct doca_urom_worker * worker_ctx )

This method destroys a UROM Worker context.

Parameters

[in] worker_ctx Pointer to instance to be destroyed.

Returns

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

DOCA_ERROR_INVALID_VALUE - Unable to gain exclusive access to the worker_ctx instance.
DOCA_ERROR_IN_USE - One or more work queues are still attached. These must be detached first.

◆ doca_urom_worker_get_gid()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_get_gid	(	struct doca_urom_worker *	worker_ctx,
		uint32_t *	worker_gid
	)

This method gets the Worker context group ID to be used to identify the Worker group that belongs to.

Parameters

[in]	worker_ctx	The UROM Worker context.
[out]	worker_gid	The UROM Worker group ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.

◆ doca_urom_worker_get_id()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_get_id	(	struct doca_urom_worker *	worker_ctx,
		uint64_t *	worker_id
	)

This method gets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device. If when creating the worker the user sets worker id equals to DOCA_UROM_WORKER_ID_ANY the library will generate new id for the worker.

Parameters

[in]	worker_ctx	The UROM Worker context.
[out]	worker_id	The UROM Worker ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.

◆ doca_urom_worker_set_cpuset()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_set_cpuset	(	struct doca_urom_worker *	worker_ctx,
		doca_cpu_set_t	cpuset
	)

Set the allowed CPUs for the Worker. The cpuset must be a subset of the service's allowed CPUs.

Parameters

[in]	worker_ctx	The UROM Worker context.
[in]	cpuset	The set of allowed CPUs.

Returns: DOCA_SUCCESS - in case of success. doca_error code - in case of failure: DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer, or, the the cpuset is invalid. DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

◆ doca_urom_worker_set_env()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_set_env	(	struct doca_urom_worker *	worker_ctx,
		char *const	env[],
		size_t	count
	)

Set worker env variables when spawning worker on DPU side.

Must be set before starting the worker context, will fail spawn command if worker already spawned on the DPU. The env variable value shouldn't contain spaces.

Parameters

[in]	worker_ctx	The UROM Worker context.
[in]	env	A string array containing name=value tuples.
[in]	count	String array size.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer, or, count in invalid.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

◆ doca_urom_worker_set_gid()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_set_gid	(	struct doca_urom_worker *	worker_ctx,
		uint32_t	gid
	)

Set worker group ID, must be set before starting the worker context.

Parameters

[in]	worker_ctx	The UROM Worker context.
[in]	gid	group id

Returns: DOCA_SUCCESS - in case of success. doca_error code - in case of failure: DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer, or, the cpuset is invalid. DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

◆ doca_urom_worker_set_id()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_set_id	(	struct doca_urom_worker *	worker_ctx,
		uint64_t	worker_id
	)

This method sets the Worker context ID to be used to identify the Worker. Worker IDs enable an application to establish multiple connections to the same Worker process running on a DOCA Device.

Worker ID must be unique to a UROM Service. If DOCA_UROM_WORKER_ID_ANY is specified, the Service will assign a unique ID for the newly created worker.

If a specific ID is used, the Service will look for an existing Worker with matching ID. If one exists, the Service will establish a new connection to the existing Worker. If a matching Worker does not exist, a new Worker will be created with the specified Worker ID.

Parallel tasks can coordinate by using a convention for worker_id which includes task ID and worker index. task ID should come from a launcher. Worker index can be derived using a local process rank (also from a launcher) and the desired number of workers. The number of workers should be based on the number of available cores for offload, which can be queried through DOCA UROM. The process for setting up workers is then:

Query DOCA UROM for available cores on the Service
Query launcher for task_id and local_rank
Derive ID: worker_id = task_id << 32 | (local_rank % cores)
Create a new Worker context with the derived worker_id

Parameters

[in]	worker_ctx	The UROM Worker context.
[in]	worker_id	The UROM Worker ID.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

◆ doca_urom_worker_set_max_inflight_tasks()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_set_max_inflight_tasks	(	struct doca_urom_worker *	worker_ctx,
		uint32_t	max_tasks
	)

Set Worker maximum in-flight tasks.

Parameters

[in]	worker_ctx	The UROM Worker context.
[in]	max_tasks	The maximum number of tasks to set, should be power of two.

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

◆ doca_urom_worker_set_plugins()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_set_plugins	(	struct doca_urom_worker *	worker_ctx,
		uint64_t	plugins
	)

This method adds plugins mask for the supported plugins by the UROM Worker on the DPU.

Parameters

[in]	worker_ctx	The UROM Worker context
[in]	plugins	The plugin types (Expected as a bit mask on the plugin index's).

Returns

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

DOCA_ERROR_INVALID_VALUE - worker_ctx argument is a NULL pointer or plugin is an unreasonable value.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

◆ doca_urom_worker_set_service()

DOCA_EXPERIMENTAL doca_error_t doca_urom_worker_set_service	(	struct doca_urom_worker *	worker_ctx,
		struct doca_urom_service *	service_ctx
	)

This method attaches a UROM Service to the Worker context.

The Worker will be launched on the DOCA Device managed by the provided Service.

Parameters

[in]	worker_ctx	The UROM Worker context.
[in]	service_ctx	The UROM Service context that will serve this worker.

Returns

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

DOCA_ERROR_INVALID_VALUE - Any argument is a NULL pointer.
DOCA_ERROR_BAD_STATE - worker_ctx is not idle.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ DOCA_UROM_WORKER_ID_ANY

Typedef Documentation

◆ doca_urom_worker_cmd_task_completion_cb_t

Function Documentation

◆ doca_urom_worker_as_ctx()

◆ doca_urom_worker_create()

◆ doca_urom_worker_destroy()

◆ doca_urom_worker_get_gid()

◆ doca_urom_worker_get_id()

◆ doca_urom_worker_set_cpuset()

◆ doca_urom_worker_set_env()

◆ doca_urom_worker_set_gid()

◆ doca_urom_worker_set_id()

◆ doca_urom_worker_set_max_inflight_tasks()

◆ doca_urom_worker_set_plugins()

◆ doca_urom_worker_set_service()