pe_task_try_submit_sample.c File Reference

#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_task_try_submit_sample.c:

Go to the source code of this file.

Data Structures
struct	pe_task_try_submit_sample_state

Macros
#define	EXIT_ON_FAILURE(_expression_)
#define	NUM_TASKS   (16)
#define	DMA_BUFFER_SIZE   (1024)
#define	BUFFER_SIZE   (DMA_BUFFER_SIZE * 2 * NUM_TASKS)
#define	BUF_INVENTORY_SIZE   (NUM_TASKS * 2)

Functions
	DOCA_LOG_REGISTER (PE_TASK_TRY_SUBMIT::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)
static doca_error_t	create_dma (struct pe_task_try_submit_sample_state *state)
static doca_error_t	try_submit_dma_tasks (uint32_t num_tasks, struct doca_dma_task_memcpy **tasks)
static void	cleanup (struct pe_task_try_submit_sample_state *state)
static doca_error_t	run (struct pe_task_try_submit_sample_state *state)
doca_error_t	run_pe_task_try_submit_sample (void)

Macro Definition Documentation

BUF_INVENTORY_SIZE

#define BUF_INVENTORY_SIZE   (NUM_TASKS * 2)

Definition at line 72 of file pe_task_try_submit_sample.c.

BUFFER_SIZE

#define BUFFER_SIZE   (DMA_BUFFER_SIZE * 2 * NUM_TASKS)

Definition at line 71 of file pe_task_try_submit_sample.c.

DMA_BUFFER_SIZE

#define DMA_BUFFER_SIZE   (1024)

Definition at line 70 of file pe_task_try_submit_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_task_try_submit doca_task_try_submit will validate the submitted tasks before submitting them to the hardware. doca_task_try_submit is expected to be used during program development until the program is stable. doca_task_try_submit shall fail if a task parameters are invalid (e.g. null, invalid or insufficient doca_buf, etc.) doca_task_try_submit may impact performance (mostly because task validation may take CPU cycles). It is recommended to switch to doca_task_submit once the program is stable. 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 16 DMA memcpy tasks. 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 59 of file pe_task_try_submit_sample.c.

NUM_TASKS

#define NUM_TASKS   (16)

Definition at line 69 of file pe_task_try_submit_sample.c.

Function Documentation

cleanup()

static void cleanup ( struct pe_task_try_submit_sample_state *  state )

static

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

Definition at line 209 of file pe_task_try_submit_sample.c.

create_dma()

static doca_error_t create_dma ( struct pe_task_try_submit_sample_state *  state )

static

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.

Definition at line 142 of file pe_task_try_submit_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

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_task_try_submit_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 118 of file pe_task_try_submit_sample.c.

DOCA_LOG_REGISTER()

DOCA_LOG_REGISTER

(

PE_TASK_TRY_SUBMIT::SAMPLE

)

run()

static doca_error_t run ( struct pe_task_try_submit_sample_state *  state )

static

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 230 of file pe_task_try_submit_sample.c.

run_pe_task_try_submit_sample()

doca_error_t run_pe_task_try_submit_sample

(

void

)

Run the PE polling sample

Returns

: DOCA_SUCCESS on success and DOCA_ERROR otherwise

Definition at line 256 of file pe_task_try_submit_sample.c.

try_submit_dma_tasks()

static doca_error_t try_submit_dma_tasks ( uint32_t  num_tasks, struct doca_dma_task_memcpy **  tasks  )

static

This method tries submits all the tasks (

See also

allocate_dma_tasks).

@num_tasks [in]: Number of tasks per group @tasks [in]: tasks to submit

Returns

: DOCA_SUCCESS on success and DOCA_ERROR otherwise

A task that failed to submit is owned by the program. The sample frees it here, but it can also be freed at later stage.

Definition at line 177 of file pe_task_try_submit_sample.c.