pe_async_stop_sample.c File Reference

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <stdbool.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_async_stop_sample.c:

Go to the source code of this file.

Data Structures
struct	pe_async_stop_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_ASYNC_STOP::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 const char *	ctx_state_to_string (enum doca_ctx_states state)
static void	dma_state_changed_cb (const union doca_data ctx_user_data, struct doca_ctx *ctx, enum doca_ctx_states prev_state, enum doca_ctx_states next_state)
doca_error_t	create_dma (struct pe_async_stop_sample_state *state)
void	poll_for_dma_stop (struct pe_async_stop_sample_state *state)
void	cleanup (struct pe_async_stop_sample_state *state)
doca_error_t	run (struct pe_async_stop_sample_state *state)
doca_error_t	run_pe_async_stop_sample (void)

Macro Definition Documentation

BUF_INVENTORY_SIZE

#define BUF_INVENTORY_SIZE   (NUM_TASKS * 2)

Definition at line 70 of file pe_async_stop_sample.c.

BUFFER_SIZE

#define BUFFER_SIZE   (DMA_BUFFER_SIZE * 2 * NUM_TASKS)

Definition at line 69 of file pe_async_stop_sample.c.

DMA_BUFFER_SIZE

#define DMA_BUFFER_SIZE   (1024)

Definition at line 68 of file pe_async_stop_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 stop a context in the middle of a run while tasks are still submitted. 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 and stops the DMA ctx after half of them were completed. The sample registers to a state changed callback (doca_ctx_set_state_changed_cb) and prints state transitions. Diff between this sample and pe_polling sample to see the differences for mitigating asynchronous stop. 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 57 of file pe_async_stop_sample.c.

NUM_TASKS

#define NUM_TASKS   (16)

Definition at line 67 of file pe_async_stop_sample.c.

Function Documentation

cleanup()

void cleanup

(

struct pe_async_stop_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

Definition at line 274 of file pe_async_stop_sample.c.

create_dma()

doca_error_t create_dma

(

struct pe_async_stop_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.

Definition at line 223 of file pe_async_stop_sample.c.

ctx_state_to_string()

static const char* ctx_state_to_string ( enum doca_ctx_states  state )

static

Convert doca_ctx_states to string

@state [in]: context state

Returns

: string representation of the state

Definition at line 169 of file pe_async_stop_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.

The sample stops the context after half of the tasks are completed to simulate asynchronous stop. The return value is expected to be DOCA_ERROR_IN_PROGRESS which implies that the stopping process has begun but it can't be completed synchronously because one or more tasks are still submitted. dma_state_changed_cb shall be invoked (state changed from stopping to idle) when the context is fully stopped.

Definition at line 91 of file pe_async_stop_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

DMA shall stop in case of error so no need to stop if (state->base.num_completed_tasks == (NUM_TASKS / 2)). Other libraries may define different behavior on error so keep that in mind when implementing the stop callback.

Definition at line 135 of file pe_async_stop_sample.c.

dma_state_changed_cb()

static void dma_state_changed_cb ( const union doca_data  ctx_user_data, struct doca_ctx *  ctx, enum doca_ctx_states  prev_state, enum doca_ctx_states  next_state  )

static

DMA state changed callback

@ctx_user_data [in]: ctx user data @ctx [in]: ctx @prev_state [in]: previous ctx state @next_state [in]: next ctx state

idle -> starting state is irrelevant because DMA start is synchronous. idle -> running is obvious so this callback shall ignore it. running -> stopping is expected because the sample shall request to stop after half of the tasks are done. stopping -> stopped is expected (implies that all in-flight tasks are flushed). The program can use this callback to raise a flag that breaks the progress loop or any other action that depends on state transition

Definition at line 193 of file pe_async_stop_sample.c.

DOCA_LOG_REGISTER()

DOCA_LOG_REGISTER

(

PE_ASYNC_STOP::SAMPLE

)

poll_for_dma_stop()

void poll_for_dma_stop

(

struct pe_async_stop_sample_state *

state

)

This method polls the PE until DMA is stopped. The DMA stop is asynchronous in this sample so after all tasks are completed the PE must be called once again to move the DMA from stopping to idle.

@state [in]: sample state

Definition at line 260 of file pe_async_stop_sample.c.

run()

doca_error_t run

(

struct pe_async_stop_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 295 of file pe_async_stop_sample.c.

run_pe_async_stop_sample()

doca_error_t run_pe_async_stop_sample

(

void

)

Run the PE polling sample

Returns

: DOCA_SUCCESS on success and DOCA_ERROR otherwise

Definition at line 322 of file pe_async_stop_sample.c.