#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <doca_mmap.h>
#include <doca_buf.h>
#include <doca_buf_inventory.h>
#include <doca_ctx.h>
#include <doca_dma.h>
#include <doca_types.h>
#include <doca_log.h>
#include <doca_pe.h>
#include <samples/common.h>
#include "pe_common.h"

Include dependency graph for pe_multi_context_sample.c:

Data Structures
struct	pe_multi_ctx_sample_state

Macros
#define	EXIT_ON_FAILURE(_expression_)

#define	NUM_CTX (4)

#define	NUM_TASKS (16)

#define	DMA_BUFFER_SIZE (1024)

#define	BUFFER_SIZE (DMA_BUFFER_SIZE * 2 * NUM_TASKS * NUM_CTX)

#define	BUF_INVENTORY_SIZE (NUM_TASKS * 2 * NUM_CTX)

Functions
	DOCA_LOG_REGISTER (PE_POLLING::SAMPLE)

static void	dma_memcpy_completed_callback (struct doca_dma_task_memcpy *dma_task, union doca_data task_user_data, union doca_data ctx_user_data)

static void	dma_memcpy_error_callback (struct doca_dma_task_memcpy *dma_task, union doca_data task_user_data, union doca_data ctx_user_data)

doca_error_t	create_dmas (struct pe_multi_ctx_sample_state *state)

doca_error_t	start_dmas (struct pe_multi_ctx_sample_state *state)

doca_error_t	allocate_tasks_for_multi_context (struct pe_multi_ctx_sample_state *state)

doca_error_t	submit_tasks_for_multi_context (struct pe_multi_ctx_sample_state *state)

void	cleanup (struct pe_multi_ctx_sample_state *state)

doca_error_t	run (struct pe_multi_ctx_sample_state *state)

doca_error_t	run_pe_multi_ctx_sample (void)

Macro Definition Documentation

◆ BUF_INVENTORY_SIZE

#define BUF_INVENTORY_SIZE (NUM_TASKS * 2 * NUM_CTX)

Definition at line 72 of file pe_multi_context_sample.c.

◆ BUFFER_SIZE

#define BUFFER_SIZE (DMA_BUFFER_SIZE * 2 * NUM_TASKS * NUM_CTX)

Definition at line 71 of file pe_multi_context_sample.c.

◆ DMA_BUFFER_SIZE

#define DMA_BUFFER_SIZE (1024)

Definition at line 70 of file pe_multi_context_sample.c.

◆ EXIT_ON_FAILURE

#define EXIT_ON_FAILURE ( _expression_ )

Value:

    { \
        doca_error_t _status_ = _expression_; \
\
		if (_status_ != DOCA_SUCCESS) { \
            DOCA_LOG_ERR("%s failed with status %s", __func__, doca_error_get_descr(_status_)); \
            return _status_; \
        } \
    }

This sample demonstrates how to use DOCA PE (progress engine) with multiple contexts. The sample uses polling because it is the most simple way (see pe_polling sample) and allows to focus on multiple contexts. The sample uses DOCA_DMA context as an example (DOCA PE can run any library that abides to the PE context API). The sample runs 4 instances of DOCA DMA context. All contexts are created on the same device for simplicity. PE can support contexts that use multiple devices. Diff between this sample and pe_polling sample to see the differences for using multiple contexts. This macro is used to minimize code size. The macro runs an expression and returns error if the expression status is not DOCA_SUCCESS

Definition at line 58 of file pe_multi_context_sample.c.

◆ NUM_CTX

#define NUM_CTX (4)

Definition at line 68 of file pe_multi_context_sample.c.

◆ NUM_TASKS

#define NUM_TASKS (16)

Definition at line 69 of file pe_multi_context_sample.c.

Function Documentation

◆ allocate_tasks_for_multi_context()

doca_error_t allocate_tasks_for_multi_context ( struct pe_multi_ctx_sample_state * state )

This method allocate the DMA tasks but does not submit them. This is a sample choice. A task can be submitted immediately after it is allocated.

@state [in]: sample state

Returns: : DOCA_SUCCESS on success and DOCA_ERROR otherwise

Definition at line 212 of file pe_multi_context_sample.c.

◆ cleanup()

void cleanup ( struct pe_multi_ctx_sample_state * state )

This method cleans up the sample resources in reverse order of their creation. This method does not check for destroy return values for simplify. Real code should check the return value and act accordingly (e.g. if doca_ctx_stop failed with DOCA_ERROR_IN_PROGRESS it means that some contexts are still added or even that there are still in flight tasks in the progress engine).

@state [in]: sample state

All contexts must be stopped and destroyed before PE is destroyed. Context destroy disconnects it from the PE.

Definition at line 257 of file pe_multi_context_sample.c.

◆ create_dmas()

doca_error_t create_dmas ( struct pe_multi_ctx_sample_state * state )

Create DMA

@state [in]: sample state

Returns: : DOCA_SUCCESS on success and DOCA_ERROR otherwise

The ctx user data is received in the task completion callback. Setting the state to the user data binds the program to the callback. See dma_memcpy_completed_callback for usage.

A context can only be connected to one PE (PE can run multiple contexts). It is recommended to first connect all contexts to the PE and only then start them. Doing so facilitates HW and memory optimizations in the PE

Definition at line 149 of file pe_multi_context_sample.c.

◆ dma_memcpy_completed_callback()

static void dma_memcpy_completed_callback	(	struct doca_dma_task_memcpy *	dma_task,
		union doca_data	task_user_data,
		union doca_data	ctx_user_data
	)

static

Program can get the context using doca_task_get_ctx doca_task_get_ctx(doca_dma_task_memcpy_as_task(dma_task)); Getting the context can be useful when the same callback serves multiple context instances.

See also: doca_pe.h for more task APIs.

process_completed_dma_memcpy_task returns doca_error_t to be able to use EXIT_ON_FAILURE, but there is nothing to do with the return value.

Definition at line 92 of file pe_multi_context_sample.c.

◆ dma_memcpy_error_callback()

static void dma_memcpy_error_callback	(	struct doca_dma_task_memcpy *	dma_task,
		union doca_data	task_user_data,
		union doca_data	ctx_user_data
	)

static

Definition at line 125 of file pe_multi_context_sample.c.

◆ DOCA_LOG_REGISTER()

DOCA_LOG_REGISTER ( PE_POLLING::SAMPLE )

◆ run()

doca_error_t run ( struct pe_multi_ctx_sample_state * state )

Run the sample The method (and the method it calls) does not cleanup anything in case of failures. It assumes that cleanup is called after it at any case.

@state [in]: sample state

Returns: : DOCA_SUCCESS on success and DOCA_ERROR otherwise

Definition at line 283 of file pe_multi_context_sample.c.

◆ run_pe_multi_ctx_sample()

doca_error_t run_pe_multi_ctx_sample ( void )

Run the PE multi context polling sample

Returns: : DOCA_SUCCESS on success and DOCA_ERROR otherwise

Definition at line 309 of file pe_multi_context_sample.c.

◆ start_dmas()

doca_error_t start_dmas ( struct pe_multi_ctx_sample_state * state )

This method starts the DMAS

@state [in]: sample state

Returns: : DOCA_SUCCESS on success and DOCA_ERROR otherwise

It is recommended to first connect all contexts to the PE and only then start them. Doing so facilitates HW and memory optimizations in the PE.

Definition at line 191 of file pe_multi_context_sample.c.

◆ submit_tasks_for_multi_context()

doca_error_t submit_tasks_for_multi_context ( struct pe_multi_ctx_sample_state * state )

This method submits the DMA tasks

@state [in]: sample state

Returns: : DOCA_SUCCESS on success and DOCA_ERROR otherwise

Tasks submission defines the order that they will start processing, but does not define the order of completion. Firstly iterating over contexts and then tasks is arbitrary and can be the other way around.

Definition at line 231 of file pe_multi_context_sample.c.

Data Structures

Macros

Functions

Macro Definition Documentation

◆ BUF_INVENTORY_SIZE

◆ BUFFER_SIZE

◆ DMA_BUFFER_SIZE

◆ EXIT_ON_FAILURE

◆ NUM_CTX

◆ NUM_TASKS

Function Documentation

◆ allocate_tasks_for_multi_context()

◆ cleanup()

◆ create_dmas()

◆ dma_memcpy_completed_callback()

◆ dma_memcpy_error_callback()

◆ DOCA_LOG_REGISTER()

◆ run()

◆ run_pe_multi_ctx_sample()

◆ start_dmas()

◆ submit_tasks_for_multi_context()