On Tue, Sep 19, 2023 at 7:12 PM Amit Prakash Shukla
<amitpraka...@marvell.com> wrote:
>
> Introduce event DMA adapter APIs. The change provides information
> on adapter modes and usage. Application can use this event adapter
> interface to transfer packets between DMA device and event device.
>
> Signed-off-by: Amit Prakash Shukla <amitpraka...@marvell.com>
Please have a cover letter and document changes from RFC for easy review.
The driver changes can be accepted after rc1. So please have two
series better review
First series - Targeting to merge for rc1
-API Header file with programing guide
-SW implementation
-Test cases
Second series: - Targeting to merge for rc2.
-cnxk driver changes
> ---
> 13 files changed, 3336 insertions(+), 5 deletions(-)
> create mode 100644 doc/guides/prog_guide/event_dma_adapter.rst
> create mode 100644 doc/guides/prog_guide/img/event_dma_adapter_op_forward.svg
> create mode 100644 doc/guides/prog_guide/img/event_dma_adapter_op_new.svg
> create mode 100644 lib/eventdev/rte_event_dma_adapter.h
Missing updates to MAINTAINERS and doc/guides/rel_notes/release_23_11.rst
> diff --git a/doc/guides/eventdevs/features/default.ini
> b/doc/guides/eventdevs/features/default.ini
> index 00360f60c6..fda8baf487 100644
> --- a/doc/guides/eventdevs/features/default.ini
> +++ b/doc/guides/eventdevs/features/default.ini
> @@ -44,6 +44,14 @@ internal_port_op_fwd =
> internal_port_qp_ev_bind =
> session_private_data =
>
> +;
> +; Features of a default DMA adapter.
> +;
> +[DMA adapter Features]
> +internal_port_op_new =
> +internal_port_op_fwd =
> +internal_port_qp_ev_bind =
For dmadev there is qp (queue pair) change to vchan.
> diff --git a/doc/guides/prog_guide/event_dma_adapter.rst
> b/doc/guides/prog_guide/event_dma_adapter.rst
Snip
> +Adding vchan queue to the adapter instance
Keep only vchan (remove queue) to align with dmadev.
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +dmadev device id and vchan queue are configured using dmadev APIs. For more
> information
> +see :doc:`here <dmadev>`.
> +
> +.. code-block:: c
> +
> + struct rte_dma_vchan_conf vchan_conf;
> + struct rte_dma_conf dev_conf;
> + uint8_t dev_id = 0;
> + uint16_t vchan = 0;
> +
> + rte_dma_configure(dev_id, &dev_conf);
> + rte_dma_vchan_setup(dev_id, vhcan, &vchan_conf);
> +
> +These dmadev id and vchan are added to the instance using the
> +``rte_event_dma_adapter_vchan_queue_add()`` API. The same is removed using
Keep only vchan (remove queue) to align with dmadev.
> +``rte_event_dma_adapter_vchan_queue_del()`` API. If hardware supports
Keep only vchan (remove queue) to align with dmadev.
> +``RTE_EVENT_DMA_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND`` capability, event
> information must be passed to
QP->VCHAN
> +the add API.
> +
> +.. code-block:: c
> +
> + uint32_t cap;
> + int ret;
> +
> + ret = rte_event_dma_adapter_caps_get(evdev_id, dma_dev_id, &cap);
> + if (cap & RTE_EVENT_DMA_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND) {
> + struct rte_event event;
> +
> + rte_event_dma_adapter_vchan_queue_add(id, dma_dev_id, vchan,
> &conf);
Keep only vchan (remove queue) to align with dmadev.
> + } else
> + rte_event_dma_adapter_vchan_queue_add(id, dma_dev_id, vchan,
> NULL);
Keep only vchan (remove queue) to align with dmadev.
> +
> +
> +
> +Set event request / response information
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +In the RTE_EVENT_DMA_ADAPTER_OP_FORWARD mode, the application specifies the
> dmadev ID and
> +vchan ID (request information) in addition to the event information
> (response information)
> +needed to enqueue an event after the DMA operation has completed. The
> request and response
> +information are specified in the ``struct rte_event_dma_metadata``.
Symbol rte_event_dma_metadata not found in header file. Remove this
section if it is not used.
> +/**
> + * This API may change without prior notice
> + *
> + * Add DMA queue pair to event device. This callback is invoked if
> + * the caps returned from rte_event_dma_adapter_caps_get(, dmadev_id)
> + * has RTE_EVENT_DMA_ADAPTER_CAP_INTERNAL_PORT_* set.
> + *
> + * @param dev
> + * Event device pointer
> + *
> + * @param dmadev
> + * DMADEV pointer
> + *
> + * @param queue_pair_id
> + * DMADEV queue pair identifier.
> + *
> + * @param event
> + * Event information required for binding dmadev queue pair to event queue.
> + * This structure will have a valid value for only those HW PMDs supporting
> + * @see RTE_EVENT_DMA_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND capability.
QP->VCHAN
> + *
> + * @return
> + * - 0: Success, dmadev queue pair added successfully.
> + * - <0: Error code returned by the driver function.
> + *
> + */
> +typedef int (*eventdev_dma_adapter_queue_pair_add_t)(const struct
> rte_eventdev *dev,
queue_pair->vchan
> + const struct rte_dma_dev
> *dmadev,
> + int32_t queue_pair_id,
queue_pair->vchan
> +++ b/lib/eventdev/rte_event_dma_adapter.h
> @@ -0,0 +1,641 @@
> +/* SPDX-License-Identifier: BSD-3-Clause
> + * Copyright (c) 2023 Marvell.
> + */
> +
> +#ifndef RTE_EVENT_DMA_ADAPTER
> +#define RTE_EVENT_DMA_ADAPTER
> +
> +/**
> + * @file rte_event_dma_adapter.h
> + *
> + * @warning
> + * @b 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
Grep queue pair and change to vchan everywhere.
> + * 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_queue_add()
> + * - rte_event_dma_adapter_vchan_queue_del()
Remove queue
> + * - 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_queue_add() /
> + * rte_event_dma_adapter_vchan_queue_del() APIs. If HW supports the
> capability
> + * RTE_EVENT_DMA_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND, event information
> must be passed to the add
> + * API.
> + *
> + */
> +
> +#include <stdint.h>
> +
> +#include "rte_eventdev.h"
use <> and sort in alphanetical orer.
> +#include <rte_common.h>
> +#include <rte_dmadev_pmd.h>
> +
> +#ifdef __cplusplus
> +extern "C" {
> +#endif
> +
> +/**
> + * A structure used to hold event based DMA operation entry.
> + */
> +struct rte_event_dma_adapter_op {
> + struct rte_dma_sge *src_seg;
> + /**< Source segments. */
> + struct rte_dma_sge *dst_seg;
> + /**< Destination segments. */
> + uint16_t nb_src;
> + /**< Number of source segments. */
> + uint16_t nb_dst;
> + /**< Number of destination segments. */
> + uint64_t flags;
> + /**< Flags related to the operation.
> + * @see RTE_DMA_OP_FLAG_*
> + */
> + struct rte_mempool *op_mp;
> + /**< Mempool from which op is allocated. */
> +};
> +
> +/**
> + * DMA event adapter mode
> + */
> +enum rte_event_dma_adapter_mode {
> + RTE_EVENT_DMA_ADAPTER_OP_NEW,
> + /**< Start the DMA adapter in event new mode.
> + * @see 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 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.
> + */
> +};
> +
> +/**
> + * DMA event request structure will be filled by application to provide
> event request information to
> + * the adapter.
> + */
> +struct rte_event_dma_request {
It is got duplicated by rte_event_dma_adapter_op. Right? if so,
please remove it.
> + uint8_t resv[8];
> + /**< Overlaps with first 8 bytes of struct rte_event that encode the
> response event
> + * information. Application is expected to fill in struct rte_event
> response_info.
> + */
> +
> + int16_t dmadev_id;
> + /**< DMA device ID to be used */
> +
> + uint16_t queue_pair_id;
> + /**< DMA queue pair ID to be used */
> +
> + uint32_t rsvd;
> + /**< Reserved bits */
> +};
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
Header file has this banner. No need to duplcate for EVERY functiion.
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Add a vchan queue to an event DMA adapter.
Remove queue
> + *
> + * @param id
> + * Adapter identifier.
> + * @param dmadev_id
> + * dmadev identifier.
> + * @param queue_pair_id
vchan_id
> + * DMA device vchan queue identifier. If queue_pair_id is set -1,
> adapter adds all the
> + * preconfigured queue pairs to the instance.
> + * @param event
> + * If HW supports dmadev queue pair to event queue binding, application
> is expected to fill in
> + * event information, else it will be NULL.
> + * @see RTE_EVENT_DMA_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND
> + *
> + * @return
> + * - 0: Success, vchan queue added correctly.
> + * - <0: Error code on failure.
> + */
> +__rte_experimental
> +int rte_event_dma_adapter_vchan_queue_add(uint8_t id, int16_t dmadev_id,
> int32_t queue_pair_id,
Remove queue
> + const struct rte_event *event);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * Delete a vchan queue from an event DMA adapter.
> + *
> + * @param id
> + * Adapter identifier.
> + * @param dmadev_id
> + * DMA device identifier.
> + * @param queue_pair_id
vchan_id
> + * DMA device vchan queue identifier.
> + *
> + * @return
> + * - 0: Success, vchan queue deleted successfully.
> + * - <0: Error code on failure.
> + */
> +__rte_experimental
> +int rte_event_dma_adapter_vchan_queue_del(uint8_t id, int16_t dmadev_id,
> int32_t queue_pair_id);
Remove queue
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice.
> + *
> + * 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.
> + *
> + * @param evdev_id
> + * The identifier of the device.
> + * @param port_id
> + * The identifier of the event port.
> + * @param ev
> + * Points to an array of *nb_events* objects of type *rte_event*
> structure which contain the
> + * event object enqueue operations to be processed.
Documenent the use of rte_event_dma_adapter_ops
> + * @param 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.
> + *
> + * @return
> + * 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.
> + */
> +__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);
> +
> +#ifdef __cplusplus
> +}
> +#endif
> +
> +
> +#define RTE_EVENT_DMA_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND 0x4
QP->VCHAN
> +/**< Flag indicates HW is capable of mapping DMA queue pair to
queue pair to vhcan
> + * event queue.
> + */
> +
> +/**
> + * Retrieve the event device's DMA adapter capabilities for the
> + * specified dmadev device
> + *
> + * @param dev_id
> + * The identifier of the device.
> + *
> + * @param dmadev_id
> + * The identifier of the dmadev device.
> + *
> + * @param[out] caps
> + * A pointer to memory filled with event adapter capabilities.
> + * It is expected to be pre-allocated & initialized by caller.
> + *
> + * @return
> + * - 0: Success, driver provides event adapter capabilities for the
> + * dmadev device.
> + * - <0: Error code returned by the driver function.
> + *
> + */
> +int
> +rte_event_dma_adapter_caps_get(uint8_t dev_id, int16_t dmadev_id, uint32_t
> *caps);
> +
> extern struct rte_event_fp_ops rte_event_fp_ops[RTE_EVENT_MAX_DEVS];
> diff --git a/lib/eventdev/version.map b/lib/eventdev/version.map
> index 7ce09a87bb..597a5c9cda 100644
> --- a/lib/eventdev/version.map
> +++ b/lib/eventdev/version.map
> @@ -134,6 +134,21 @@ EXPERIMENTAL {
>
> # added in 23.11
> rte_event_eth_rx_adapter_create_ext_with_params;
> + rte_event_dma_adapter_create_ext;
> + rte_event_dma_adapter_create;
> + rte_event_dma_adapter_free;
> + rte_event_dma_adapter_event_port_get;
> + rte_event_dma_adapter_vchan_queue_add;
> + rte_event_dma_adapter_vchan_queue_del;
> + rte_event_dma_adapter_service_id_get;
> + rte_event_dma_adapter_start;
> + rte_event_dma_adapter_stop;
> + rte_event_dma_adapter_runtime_params_init;
> + rte_event_dma_adapter_runtime_params_set;
> + rte_event_dma_adapter_runtime_params_get;
> + rte_event_dma_adapter_stats_get;
> + rte_event_dma_adapter_stats_reset;
> + rte_event_dma_adapter_enqueue;
sort in alphabetical order.
Phew :-)
