Re: [PATCH 01/11] eventdev: introduce ML event adapter library

[Jerin Jacob <jerinjacobk@gmail.com>]

On Sun, Jan 7, 2024 at 9:05 PM Srikanth Yalavarthi
<syalavarthi@marvell.com> wrote:
>
> Introduce event ML adapter APIs. This patch provides
> information on adapter modes and usage. Application
> can use this event adapter interface to transfer
> packets between ML device and event device.
>
> Signed-off-by: Srikanth Yalavarthi <syalavarthi@marvell.com>

1) Please --thread ---in-reply-to on reply with RFC patch
2) Pleaes add change log
3)In order to merge this series, We need to have UT. it can be based
on SW adapter.
4) Added other event adapter maintainers for review in case if anyone
interested.


> ---
>  MAINTAINERS                                   |    6 +
>  config/rte_config.h                           |    1 +
>  doc/api/doxy-api-index.md                     |    1 +
>  doc/guides/prog_guide/event_ml_adapter.rst    |  268 ++++
>  doc/guides/prog_guide/eventdev.rst            |   10 +-
>  .../img/event_ml_adapter_op_forward.svg       | 1086 +++++++++++++++++
>  .../img/event_ml_adapter_op_new.svg           | 1079 ++++++++++++++++
>  doc/guides/prog_guide/index.rst               |    1 +
>  lib/eventdev/meson.build                      |    4 +-
>  lib/eventdev/rte_event_ml_adapter.c           |    6 +
>  lib/eventdev/rte_event_ml_adapter.h           |  594 +++++++++
>  lib/eventdev/rte_eventdev.h                   |   45 +
>  lib/meson.build                               |    2 +-
>  lib/mldev/rte_mldev.h                         |    6 +

I perfer this change to come via main tree. Is it possible to move
that change as sepereate patch.

> diff --git a/MAINTAINERS b/MAINTAINERS
> index 0d1c8126e3e..a1125e93621 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -554,6 +554,12 @@ F: drivers/raw/skeleton/
>  F: app/test/test_rawdev.c
>  F: doc/guides/prog_guide/rawdev.rst
>
> +Eventdev ML Adapter API


Add after "Eventdev DMA Adapter API" section

> +M: Srikanth Yalavarthi <syalavarthi@marvell.com>
> +T: git://dpdk.org/next/dpdk-next-eventdev
> +F: lib/eventdev/*ml_adapter*
> +F: doc/guides/prog_guide/event_ml_adapter.rst
> +
>

> index 00000000000..71f6c4b5974
> --- /dev/null
> +++ b/doc/guides/prog_guide/event_ml_adapter.rst
> @@ -0,0 +1,268 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright (c) 2024 Marvell.
> +
> +Event ML Adapter Library
> +========================
> +
> +DPDK :doc:`Eventdev library <eventdev>` provides event driven programming model with features
> +to schedule events. :doc:`ML Device library <mldev>` provides an interface to ML poll mode
> +drivers that support Machine Learning inference operations. Event ML Adapter is intended to
> +bridge between the event device and the ML device.
> +
> +Packet flow from ML device to the event device can be accomplished using software and hardware
> +based transfer mechanisms. The adapter queries an eventdev PMD to determine which mechanism to
> +be used. The adapter uses an EAL service core function for software based packet transfer and
> +uses the eventdev PMD functions to configure hardware based packet transfer between ML device
> +and the event device. ML adapter uses a new event type called ``RTE_EVENT_TYPE_MLDEV`` to
> +indicate the source of event.
> +
> +Application can choose to submit an ML operation directly to an ML device or send it to an ML
> +adapter via eventdev based on RTE_EVENT_ML_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability. The

Use ``...`` everywhere accros the this document when using the symbols
like RTE_EVENT_ML_ADAPTER_CAP_INTERNAL_PORT_OP_FWD

> +first mode is known as the event new (RTE_EVENT_ML_ADAPTER_OP_NEW) mode and the second as the

Same as above.. Please follow the same for rest of the file.,

> +event forward (RTE_EVENT_ML_ADAPTER_OP_FORWARD) mode. Choice of mode can be specified while
> +creating the adapter. In the former mode, it is the application's responsibility to enable
> +ingress packet ordering. In the latter mode, it is the adapter's responsibility to enable
> +ingress packet ordering.
> +
> +
> +Adapter Modes
> +-------------
> +
> +RTE_EVENT_ML_ADAPTER_OP_NEW mode
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +In the RTE_EVENT_ML_ADAPTER_OP_NEW mode, application submits ML operations directly to an ML
> +device. The adapter then dequeues ML completions from the ML device and enqueues them as events
> +to the event device. This mode does not ensure ingress ordering as the application directly
> +enqueues to the mldev without going through ML/atomic stage. In this mode, events dequeued

Is this ML/atomic or atomic ?

> +from the adapter are treated as new events. The application has to specify event information
> +(response information) which is needed to enqueue an event after the ML operation is completed.
> +

> +
> +
> +API Overview
> +------------
> +
> +This section has a brief introduction to the event ML adapter APIs. The application is expected
> +to create an adapter which is associated with a single eventdev, then add mldev and queue pair
> +to the adapter instance.
> +
> +
> +Create an adapter instance
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +An adapter instance is created using ``rte_event_ml_adapter_create()``. This function is called
> +with event device to be associated with the adapter and port configuration for the adapter to
> +setup an event port (if the adapter needs to use a service function).
> +
> +Adapter can be started in ``RTE_EVENT_ML_ADAPTER_OP_NEW`` or ``RTE_EVENT_ML_ADAPTER_OP_FORWARD``
> +mode.
> +


> + */
> +
> +#ifndef RTE_EVENT_ML_ADAPTER
> +#define RTE_EVENT_ML_ADAPTER
> +
> +/**
> + * @file rte_event_ml_adapter.h
> + *
> + * @warning
> + * @b EXPERIMENTAL:
> + * All functions in this file may be changed or removed without prior notice.
> + *
> + * ML (Machine Learning) Event Adapter API.
> + *
> + * Eventdev library provides adapters to bridge between various components for providing new
> + * event source. The event ML adapter is one of those adapters which is intended to bridge
> + * between event devices and ML devices.
> + *
> + * The ML adapter adds support to enqueue / dequeue ML operations to / from event device. The packet
> + * flow between ML 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 ML device
> + * and the event device.
> + *
> + * The application can choose to submit a ML operation directly to an ML device or send it to the ML
> + * adapter via eventdev based on RTE_EVENT_ML_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability. The first

Please check genereated doxygen output. Use @ref to get proper link.
Same comment across this file.

> + * mode is known as the event new (RTE_EVENT_ML_ADAPTER_OP_NEW) mode and the second as the event
> + * forward (RTE_EVENT_ML_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_ML_ADAPTER_OP_NEW mode:
> + *
> + *                +--------------+         +--------------+
> + *                |              |         |   ML stage   |
> + *                | Application  |---[2]-->| + enqueue to |
> + *                |              |         |     mldev    |
> + *                +--------------+         +--------------+
> + *                    ^   ^                       |
> + *                    |   |                      [3]
> + *                   [6] [1]                      |
> + *                    |   |                       |
> + *                +--------------+                |
> + *                |              |                |
> + *                | Event device |                |
> + *                |              |                |
> + *                +--------------+                |
> + *                       ^                        |
> + *                       |                        |
> + *                      [5]                       |
> + *                       |                        v
> + *                +--------------+         +--------------+
> + *                |              |         |              |
> + *                |  ML adapter  |<--[4]---|    mldev     |
> + *                |              |         |              |
> + *                +--------------+         +--------------+
> + *
> + *
> + *         [1] Application dequeues events from the previous stage.
> + *         [2] Application prepares the ML operations.
> + *         [3] ML operations are submitted to mldev by application.
> + *         [4] ML adapter dequeues ML completions from mldev.
> + *         [5] ML adapter enqueues events to the eventdev.
> + *         [6] Application dequeues from eventdev for further processing.
> + *
> + * In the RTE_EVENT_ML_ADAPTER_OP_NEW mode, application submits ML operations directly to ML device.
> + * The ML adapter then dequeues ML completions from ML device and enqueues events to the event
> + * device. This mode does not ensure ingress ordering, if the application directly enqueues to mldev
> + * without going through ML / atomic stage i.e. removing item [1] and [2].


ML/atomic or atomic ?


> + *
> + * 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
> + * ML operation is completed.
> + *

> + *
> + */
> +
> +#include <stdint.h>
> +
> +#include "rte_eventdev.h"
> +#include <rte_common.h>
> +
> +#ifdef __cplusplus
> +extern "C" {
> +#endif
> +
> +/**
> + *  ML event adapter mode
> + */
> +enum rte_event_ml_adapter_mode {
> +       RTE_EVENT_ML_ADAPTER_OP_NEW,
> +       /**< Start the ML adapter in event new mode.
> +        * @see RTE_EVENT_OP_NEW.
> +        *
> +        * Application submits ML operations to the mldev. Adapter only dequeues the ML completions
> +        * from mldev and enqueue events to the eventdev.
> +        */
> +
> +       RTE_EVENT_ML_ADAPTER_OP_FORWARD,
> +       /**< Start the ML adapter in event forward mode.
> +        * @see RTE_EVENT_OP_FORWARD.
> +        *
> +        * Application submits ML requests as events to the ML adapter or ML device based on
> +        * RTE_EVENT_ML_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability. ML completions are enqueued
> +        * back to the eventdev by ML adapter.
> +        */
> +};
> +
> +};
> +
> +
> +/**
> + * Free an event ML adapter
> + *
> + * @param id
> + *     Adapter identifier.
> + * @return
> + *     - 0: Success
> + *     - <0: Error code on failure, If the adapter still has queue pairs added to it, the function
> + * returns -EBUSY.
> + */
> +int
> +rte_event_ml_adapter_free(uint8_t id);
> +

> +
> +/**
> + * Enqueue a burst of ML operations as event objects supplied in *rte_event* structure on an event
> + * ML 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_ML_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_ml_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.
> + * @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.

Html rendering of return values are not correct.

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

,
> diff --git a/lib/mldev/rte_mldev.h b/lib/mldev/rte_mldev.h

I perfer this change to come via main tree. Is it possible to move
that change as sepereate patch.

> index 27e372fbcf1..a031592de61 100644
> --- a/lib/mldev/rte_mldev.h
> +++ b/lib/mldev/rte_mldev.h
> @@ -469,6 +469,12 @@ struct rte_ml_op {
>          * dequeue and enqueue operation.
>          * The application should not modify this field.
>          */
> +       uint32_t private_data_offset;
> +       /**< Offset to indicate start of private data (if any).
> +        * The offset is counted from the start of the rte_ml_op.
> +        * The offset provides an offset to locate the request /
> +        * response information in the rte_ml_op.
> +        */
>  } __rte_cache_aligned;
>
>  /* Enqueue/Dequeue operations */
> --
> 2.42.0
>