---
name: "RTE_EVENT_DMA_ADAPTER_OP_NEW"
section: "3"
platform: "linux"
package: "dpdk-doc"
version: "24.11.4-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rte_event_dma_adapter.h"
---

# RTE\_EVENT\_DMA\_ADAPTER\_OP\_NEW(3)

Part of [rte\_event\_dma\_adapter.h(3)](/rte_event_dma_adapter.h/3.md).

## NAME

rte\_event\_dma\_adapter.h

## SYNOPSIS

`#include <stdint.h>`\
 `#include <rte_common.h>`\
 `#include <rte_dmadev_pmd.h>`\
 `#include <rte_eventdev.h>`\

### Data Structures

struct **rte\_event\_dma\_adapter\_op**\
 struct **rte\_event\_dma\_adapter\_conf**\
 struct **rte\_event\_dma\_adapter\_runtime\_params**\
 struct **rte\_event\_dma\_adapter\_stats**\

### Typedefs

**typedef** int(\* **rte\_event\_dma\_adapter\_conf\_cb**) (uint8\_t id, uint8\_t evdev\_id, struct **rte\_event\_dma\_adapter\_conf** \*conf, void \*arg)\

### Enumerations

enum **rte\_event\_dma\_adapter\_mode** { **RTE\_EVENT\_DMA\_ADAPTER\_OP\_NEW**, **RTE\_EVENT\_DMA\_ADAPTER\_OP\_FORWARD** }\

### Functions

\_\_rte\_experimental int **rte\_event\_dma\_adapter\_create\_ext** (uint8\_t id, uint8\_t evdev\_id, **rte\_event\_dma\_adapter\_conf\_cb** conf\_cb, enum **rte\_event\_dma\_adapter\_mode** mode, void \*conf\_arg)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_create** (uint8\_t id, uint8\_t evdev\_id, struct **rte\_event\_port\_conf** \*port\_config, enum **rte\_event\_dma\_adapter\_mode** mode)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_free** (uint8\_t id)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_event\_port\_get** (uint8\_t id, uint8\_t \*event\_port\_id)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_vchan\_add** (uint8\_t id, int16\_t dmadev\_id, uint16\_t vchan, const struct **rte\_event** \*event)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_vchan\_del** (uint8\_t id, int16\_t dmadev\_id, uint16\_t vchan)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_service\_id\_get** (uint8\_t id, uint32\_t \*service\_id)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_start** (uint8\_t id)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_stop** (uint8\_t id)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_runtime\_params\_init** (struct **rte\_event\_dma\_adapter\_runtime\_params** \*params)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_runtime\_params\_set** (uint8\_t id, struct **rte\_event\_dma\_adapter\_runtime\_params** \*params)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_runtime\_params\_get** (uint8\_t id, struct **rte\_event\_dma\_adapter\_runtime\_params** \*params)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_stats\_get** (uint8\_t id, struct **rte\_event\_dma\_adapter\_stats** \*stats)\
 \_\_rte\_experimental int **rte\_event\_dma\_adapter\_stats\_reset** (uint8\_t id)\
 \_\_rte\_experimental uint16\_t **rte\_event\_dma\_adapter\_enqueue** (uint8\_t evdev\_id, uint8\_t port\_id, struct **rte\_event** ev\[\], uint16\_t nb\_events)\

## Detailed Description

**Warning**

**EXPERIMENTAL:** All functions in this file may be changed or removed without prior notice.

DMA Event Adapter API.

Eventdev library provides adapters to bridge between various components for providing new event source. The event DMA adapter is one of those adapters which is intended to bridge between event devices and DMA devices.

The DMA adapter adds support to enqueue / dequeue DMA operations to / from event device. The packet flow between DMA device and the event device can be accomplished using both SW and HW based transfer mechanisms. The adapter uses an EAL service core function for SW based packet transfer and uses the eventdev PMD functions to configure HW based packet transfer between the DMA device and the event device.

The application can choose to submit a DMA operation directly to an DMA device or send it to the DMA adapter via eventdev based on RTE\_EVENT\_DMA\_ADAPTER\_CAP\_INTERNAL\_PORT\_OP\_FWD capability. The first mode is known as the event new (RTE\_EVENT\_DMA\_ADAPTER\_OP\_NEW) mode and the second as the event forward (RTE\_EVENT\_DMA\_ADAPTER\_OP\_FORWARD) mode. The choice of mode can be specified while creating the adapter. In the former mode, it is an application responsibility to enable ingress packet ordering. In the latter mode, it is the adapter responsibility to enable the ingress packet ordering.

Working model of RTE\_EVENT\_DMA\_ADAPTER\_OP\_NEW mode:

```
           +--------------+         +--------------+
           |              |         |   DMA stage  |
           | Application  |---[2]-->| + enqueue to |
           |              |         |     dmadev   |
           +--------------+         +--------------+
               ^   ^                       |
               |   |                      [3]
              [6] [1]                      |
               |   |                       |
           +--------------+                |
           |              |                |
           | Event device |                |
           |              |                |
           +--------------+                |
                  ^                        |
                  |                        |
                 [5]                       |
                  |                        v
           +--------------+         +--------------+
           |              |         |              |
           |  DMA adapter |<--[4]---|    dmadev    |
           |              |         |              |
           +--------------+         +--------------+
    [1] Application dequeues events from the previous stage.
    [2] Application prepares the DMA operations.
    [3] DMA operations are submitted to dmadev by application.
    [4] DMA adapter dequeues DMA completions from dmadev.
    [5] DMA adapter enqueues events to the eventdev.
    [6] Application dequeues from eventdev for further processing.
```

 In the RTE\_EVENT\_DMA\_ADAPTER\_OP\_NEW mode, application submits DMA operations directly to DMA device. The DMA adapter then dequeues DMA completions from DMA device and enqueue events to the event device. This mode does not ensure ingress ordering, if the application directly enqueues to dmadev without going through DMA / atomic stage i.e. removing item \[1\] and \[2\].

Events dequeued from the adapter will be treated as new events. In this mode, application needs to specify event information (response information) which is needed to enqueue an event after the DMA operation is completed.

Working model of RTE\_EVENT\_DMA\_ADAPTER\_OP\_FORWARD mode:

```
           +--------------+         +--------------+
   --[1]-->|              |---[2]-->|  Application |
           | Event device |         |      in      |
   <--[8]--|              |<--[3]---| Ordered stage|
           +--------------+         +--------------+
               ^      |
               |     [4]
              [7]     |
               |      v
          +----------------+       +--------------+
          |                |--[5]->|              |
          |   DMA adapter  |       |     dmadev   |
          |                |<-[6]--|              |
          +----------------+       +--------------+
    [1] Events from the previous stage.
    [2] Application in ordered stage dequeues events from eventdev.
    [3] Application enqueues DMA operations as events to eventdev.
    [4] DMA adapter dequeues event from eventdev.
    [5] DMA adapter submits DMA operations to dmadev (Atomic stage).
    [6] DMA adapter dequeues DMA completions from dmadev
    [7] DMA adapter enqueues events to the eventdev
    [8] Events to the next stage
```

 In the event forward (RTE\_EVENT\_DMA\_ADAPTER\_OP\_FORWARD) mode, if the HW supports the capability RTE\_EVENT\_DMA\_ADAPTER\_CAP\_INTERNAL\_PORT\_OP\_FWD, application can directly submit the DMA operations to the dmadev. If not, application retrieves the event port of the DMA adapter through the API, rte\_event\_DMA\_adapter\_event\_port\_get(). Then, links its event queue to this port and starts enqueuing DMA operations as events to the eventdev. The adapter then dequeues the events and submits the DMA operations to the dmadev. After the DMA completions, the adapter enqueues events to the event device.

Application can use this mode, when ingress packet ordering is needed. Events dequeued from the adapter will be treated as forwarded events. In this mode, the application needs to specify the dmadev ID and queue pair ID (request information) needed to enqueue an DMA operation in addition to the event information (response information) needed to enqueue an event after the DMA operation has completed.

The event DMA adapter provides common APIs to configure the packet flow from the DMA device to event devices for both SW and HW based transfers. The DMA event adapter's functions are:

- •

  **rte\_event\_dma\_adapter\_create\_ext()**

- •

  **rte\_event\_dma\_adapter\_create()**

- •

  **rte\_event\_dma\_adapter\_free()**

- •

  **rte\_event\_dma\_adapter\_vchan\_add()**

- •

  **rte\_event\_dma\_adapter\_vchan\_del()**

- •

  **rte\_event\_dma\_adapter\_start()**

- •

  **rte\_event\_dma\_adapter\_stop()**

- •

  **rte\_event\_dma\_adapter\_stats\_get()**

- •

  **rte\_event\_dma\_adapter\_stats\_reset()**

The application creates an instance using **rte\_event\_dma\_adapter\_create()** or **rte\_event\_dma\_adapter\_create\_ext()**.

dmadev queue pair addition / deletion is done using the **rte\_event\_dma\_adapter\_vchan\_add()** / **rte\_event\_dma\_adapter\_vchan\_del()** APIs. If HW supports the capability RTE\_EVENT\_DMA\_ADAPTER\_CAP\_INTERNAL\_PORT\_VCHAN\_EV\_BIND, event information must be passed to the add API.

Definition in file **rte\_event\_dma\_adapter.h**.

## Typedef Documentation

### typedef int(\* rte\_event\_dma\_adapter\_conf\_cb) (uint8\_t id, uint8\_t evdev\_id, struct rte\_event\_dma\_adapter\_conf \*conf, void \*arg)

Function type used for adapter configuration callback. The callback is used to fill in members of the struct **rte\_event\_dma\_adapter\_conf**, this callback is invoked when creating a SW service for packet transfer from dmadev vchan to the event device. The SW service is created within the function, **rte\_event\_dma\_adapter\_vchan\_add()**, if SW based packet transfers from dmadev vchan to the event device are required.

**Parameters**

*id* Adapter identifier. \
 *evdev\_id* Event device identifier. \
 *conf* Structure that needs to be populated by this callback. \
 *arg* Argument to the callback. This is the same as the conf\_arg passed to the **rte\_event\_dma\_adapter\_create\_ext()**.

Definition at line **291** of file **rte\_event\_dma\_adapter.h**.

## Enumeration Type Documentation

### enum rte\_event\_dma\_adapter\_mode

DMA event adapter mode

**Enumerator**

- *RTE\_EVENT\_DMA\_ADAPTER\_OP\_NEW*

  *Start the DMA adapter in event new mode.*

**See also**

**RTE\_EVENT\_OP\_NEW***.*

*Application submits DMA operations to the dmadev. Adapter only dequeues the DMA completions from dmadev and enqueue events to the eventdev.*

- *RTE\_EVENT\_DMA\_ADAPTER\_OP\_FORWARD*

  *Start the DMA adapter in event forward mode.*

**See also**

**RTE\_EVENT\_OP\_FORWARD***.*

*Application submits DMA requests as events to the DMA adapter or DMA device based on RTE\_EVENT\_DMA\_ADAPTER\_CAP\_INTERNAL\_PORT\_OP\_FWD capability. DMA completions are enqueued back to the eventdev by DMA adapter.*

*Definition at line* **214** *of file* **rte\_event\_dma\_adapter.h***.*

## Function Documentation

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_create\_ext (uint8\_t id, uint8\_t evdev\_id, rte\_event\_dma\_adapter\_conf\_cb conf\_cb, enum rte\_event\_dma\_adapter\_mode mode, void \* conf\_arg)

*Create a new event DMA adapter with the specified identifier.*

**Parameters**

*id Adapter identifier.* \
 *evdev\_id Event device identifier.* \
 *conf\_cb Callback function that fills in members of a struct* **rte\_event\_dma\_adapter\_conf** *struct passed into it.* \
 *mode Flag to indicate the mode of the adapter.*

**See also**

**rte\_event\_dma\_adapter\_mode**

**Parameters**

*conf\_arg Argument that is passed to the conf\_cb function.*

**Returns**

- •

  *0: Success*

- •

  *\<0: Error code on failure*

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_create (uint8\_t id, uint8\_t evdev\_id, struct rte\_event\_port\_conf \* port\_config, enum rte\_event\_dma\_adapter\_mode mode)

*Create a new event DMA adapter with the specified identifier. This function uses an internal configuration function that creates an event port. This default function reconfigures the event device with an additional event port and set up the event port using the port\_config parameter passed into this function. In case the application needs more control in configuration of the service, it should use the* **rte\_event\_dma\_adapter\_create\_ext()** *version.*

**Parameters**

*id Adapter identifier.* \
 *evdev\_id Event device identifier.* \
 *port\_config Argument of type* **rte\_event\_port\_conf that is passed to the conf\_cb function.** \
 *mode* **Flag to indicate the mode of the adapter.**

**See also**

**rte\_event\_dma\_adapter\_mode**

**Returns**

- •

  **0: Success**

- •

  **\<0: Error code on failure**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_free (uint8\_t id)

**Free an event DMA adapter**

**Parameters**

*id* **Adapter identifier.**

**Returns**

- •

  **0: Success**

- •

  **\<0: Error code on failure, If the adapter still has queue pairs added to it, the function returns -EBUSY.**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_event\_port\_get (uint8\_t id, uint8\_t \* event\_port\_id)

**Retrieve the event port of an adapter.**

**Parameters**

*id* **Adapter identifier.**\
 *event\_port\_id* **Application links its event queue to this adapter port which is used in RTE\_EVENT\_DMA\_ADAPTER\_OP\_FORWARD mode.**

**Returns**

- •

  **0: Success**

- •

  **\<0: Error code on failure.**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_vchan\_add (uint8\_t id, int16\_t dmadev\_id, uint16\_t vchan, const struct rte\_event \* event)

**Add a vchan to an event DMA adapter.**

**Parameters**

*id* **Adapter identifier.** \
 *dmadev\_id* **dmadev identifier.** \
 *vchan* **DMA device vchan identifier. If vchan is set -1, adapter adds all the preconfigured vchan to the instance.** \
 *event* **If HW supports dmadev vchan to event queue binding, application is expected to fill in event information, else it will be NULL.**

**See also**

**RTE\_EVENT\_DMA\_ADAPTER\_CAP\_INTERNAL\_PORT\_VCHAN\_EV\_BIND**

**Returns**

- •

  **0: Success, vchan added correctly.**

- •

  **\<0: Error code on failure.**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_vchan\_del (uint8\_t id, int16\_t dmadev\_id, uint16\_t vchan)

**Delete a vchan from an event DMA adapter.**

**Parameters**

*id* **Adapter identifier.** \
 *dmadev\_id* **DMA device identifier.** \
 *vchan* **DMA device vchan identifier.**

**Returns**

- •

  **0: Success, vchan deleted successfully.**

- •

  **\<0: Error code on failure.**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_service\_id\_get (uint8\_t id, uint32\_t \* service\_id)

**Retrieve the service ID of an adapter. If the adapter doesn't use a rte\_service function, this function returns -ESRCH.**

**Parameters**

*id* **Adapter identifier.** \
 *service\_id* **A pointer to a uint32\_t, to be filled in with the service id.**

**Returns**

- •

  **0: Success**

- •

  **\<0: Error code on failure, if the adapter doesn't use a rte\_service function, this function returns -ESRCH.**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_start (uint8\_t id)

**Start event DMA adapter**

**Parameters**

*id* **Adapter identifier.**

**Returns**

- •

  **0: Success, adapter started successfully.**

- •

  **\<0: Error code on failure.**

**Note**

**The eventdev and dmadev to which the event\_dma\_adapter is connected should be started before calling rte\_event\_dma\_adapter\_start().**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_stop (uint8\_t id)

**Stop event DMA adapter**

**Parameters**

*id* **Adapter identifier.**

**Returns**

- •

  **0: Success, adapter stopped successfully.**

- •

  **\<0: Error code on failure.**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_runtime\_params\_init (struct rte\_event\_dma\_adapter\_runtime\_params \* params)

**Initialize the adapter runtime configuration parameters**

**Parameters**

*params* **A pointer to structure of type struct rte\_event\_dma\_adapter\_runtime\_params**

**Returns**

- •

  **0: Success**

- •

  **\<0: Error code on failure**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_runtime\_params\_set (uint8\_t id, struct rte\_event\_dma\_adapter\_runtime\_params \* params)

**Set the adapter runtime configuration parameters**

**Parameters**

*id* **Adapter identifier**\
 *params* **A pointer to structure of type struct rte\_event\_dma\_adapter\_runtime\_params with configuration parameter values. The reserved fields of this structure must be initialized to zero and the valid fields need to be set appropriately. This struct can be initialized using rte\_event\_dma\_adapter\_runtime\_params\_init() API to default values or application may reset this struct and update required fields.**

**Returns**

- •

  **0: Success**

- •

  **\<0: Error code on failure**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_runtime\_params\_get (uint8\_t id, struct rte\_event\_dma\_adapter\_runtime\_params \* params)

**Get the adapter runtime configuration parameters**

**Parameters**

*id* **Adapter identifier**\
 *params* **A pointer to structure of type struct rte\_event\_dma\_adapter\_runtime\_params containing valid adapter parameters when return value is 0.**

**Returns**

- •

  **0: Success**

- •

  **\<0: Error code on failure**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_stats\_get (uint8\_t id, struct rte\_event\_dma\_adapter\_stats \* stats)

**Retrieve statistics for an adapter**

**Parameters**

*id* **Adapter identifier.** \
 *stats* **A pointer to structure used to retrieve statistics for an adapter.**

**Returns**

- •

  **0: Success, retrieved successfully.**

- •

  **\<0: Error code on failure.**

### \_\_rte\_experimental int rte\_event\_dma\_adapter\_stats\_reset (uint8\_t id)

**Reset statistics for an adapter.**

**Parameters**

*id* **Adapter identifier.**

**Returns**

- •

  **0: Success, statistics reset successfully.**

- •

  **\<0: Error code on failure.**

### \_\_rte\_experimental uint16\_t rte\_event\_dma\_adapter\_enqueue (uint8\_t evdev\_id, uint8\_t port\_id, struct rte\_event ev\[\], uint16\_t nb\_events)

**Enqueue a burst of DMA operations as event objects supplied in rte\_event structure on an event DMA adapter designated by its event** *evdev\_id* **through the event port specified by** *port\_id***. This function is supported if the eventdev PMD has the RTE\_EVENT\_DMA\_ADAPTER\_CAP\_INTERNAL\_PORT\_OP\_FWD capability flag set.**

**The** *nb\_events* **parameter is the number of event objects to enqueue that are supplied in the** *ev* **array of rte\_event structure.**

**The rte\_event\_dma\_adapter\_enqueue() function returns the number of event objects it actually enqueued. A return value equal to** *nb\_events* **means that all event objects have been enqueued.**

**Parameters**

*evdev\_id* **The identifier of the device.** \
 *port\_id* **The identifier of the event port.** \
 *ev* **Points to an array of** *nb\_events* **objects of type rte\_event structure which contain the event object enqueue operations to be processed.** \
 *nb\_events* **The number of event objects to enqueue, typically number of rte\_event\_port\_attr\_get(...RTE\_EVENT\_PORT\_ATTR\_ENQ\_DEPTH...) available for this port.**

**Returns**

**The number of event objects actually enqueued on the event device. The return value can be less than the value of the** *nb\_events* **parameter when the event devices queue is full or if invalid parameters are specified in a rte\_event. If the return value is less than** *nb\_events***, the remaining events at the end of ev\[\] are not consumed and the caller has to take care of them, and rte\_errno is set accordingly. Possible errno values include:**

- •

  **EINVAL: The port ID is invalid, device ID is invalid, an event's queue ID is invalid, or an event's sched type doesn't match the capabilities of the destination queue.**

- •

  **ENOSPC: The event port was backpressured and unable to enqueue one or more events. This error code is only applicable to closed systems.**

## Author

**Generated automatically by Doxygen for DPDK from the source code.**