[dpdk-dev] [PATCH v5 3/3] doc: add eventdev library to programmers guide

[Jerin Jacob]

-----Original Message-----
> Date: Fri, 30 Jun 2017 14:51:13 +0100
> From: David Hunt <david.hunt at intel.com>
> To: dev at dpdk.org
> CC: jerin.jacob at caviumnetworks.com, harry.van.haaren at intel.com
> Subject: [PATCH v5 3/3] doc: add eventdev library to programmers guide
> X-Mailer: git-send-email 2.7.4
> 
> From: Harry van Haaren <harry.van.haaren at intel.com>
> 
> This commit adds an entry in the programmers guide
> explaining the eventdev library.
> 
> The rte_event struct, queues and ports are explained.
> An API walktrough of a simple two stage atomic pipeline
> provides the reader with a step by step overview of the
> expected usage of the Eventdev API.
> 
> Signed-off-by: Harry van Haaren <harry.van.haaren at intel.com>

Thanks for document. Overall it looks good. A few comments below.

> ---

Snip

> + The eventdev framework is provided as a DPDK library, allowing
> +applications to use it if they wish, but not require its usage.
> +
> +The goal of this library is to enable applications to build processing
> +pipelines where the load balancing and scheduling is handled by the eventdev.

Adding the differences between polling and event driver model will be
useful. I propose to change the above two paragraphs and add more
detailed text for the  use case. Something like below,

----------Start--------------------
The eventdev framework introduces the event driven programming model.

In a polling model, lcores poll ethdev ports and associated Rx queues
directly to look for a packet. By contrast in an event driven model,
lcores call the scheduler that selects packets for them based on
programmer-specified criteria. The Eventdev library adds support for an
event driven programming model, which offers applications automatic
multicore scaling, dynamic load balancing, pipelining, packet ingress
order maintenance and synchronization services to simplify application
packet processing.

By introducing an event driven programming model, DPDK can support both
polling and event driven programming models for packet processing, and
applications are free to choose whatever model (or combination of the
two) best suits their needs.
-----------End--------------------


> +Step-by-step instructions of the eventdev design is available in the `API
> +Walk-through`_ section later in this document.
> +
> +Event struct
> +------------
> +
> +The eventdev API represents each event with a generic struct, which contains a
> +payload and metadata required for scheduling by an eventdev.  The
> +``rte_event`` struct is a 16 byte C structure, defined in
> +``libs/librte_eventdev/rte_eventdev.h``.
> +

Snip

> +Event Payload
> +~~~~~~~~~~~~~
> +
> +The rte_event struct contains a union for payload, allowing flexibility in what
> +the actual event being scheduled is. The payload is a union of the following:
> +
> +* ``uint64_t u64``
> +* ``void *event_ptr``
> +* ``struct rte_mbuf *mbuf``
> +
> +These three items in a union occupy the same 64 bits at the end of the rte_event
> +structure. The application can utilize the 64 bits directly by accessing the
> +u64 variable, while the event_ptr and mbuf are provided as convenience
> +variables.  For example the mbuf pointer in the union can used to schedule a
> +DPDK packet.
> +
> +Queues
> +~~~~~~
> +
> +A queue is a logical "stage" of a packet processing graph, where each stage
> +has a specified scheduling type.  The application configures each queue for a
> +specific type of scheduling, and just enqueues all events to the eventdev.
> +The Eventdev API supports the following scheduling types per queue:

IMO, The above definition fits nicely if the queue is NOT with
RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES.

I think, We can take the queue definition from header file.
http://dpdk.org/browse/next/dpdk-next-eventdev/tree/lib/librte_eventdev/rte_eventdev.h#n113

and tell about the RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES and non
RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES capability queues here.


> +
> +*   Atomic
> +*   Ordered
> +*   Parallel
> +
> +Atomic, Ordered and Parallel are load-balanced scheduling types: the output
> +of the queue can be spread out over multiple CPU cores.
> +
> +Atomic scheduling on a queue ensures that a single flow is not present on two
> +different CPU cores at the same time. Ordered allows sending all flows to any
> +core, but the scheduler must ensure that on egress the packets are returned to

We can emphasize of when reordering happens ie "On downstream queue enqueue"

> +ingress order. Parallel allows sending all flows to all CPU cores, without any
> +re-ordering guarantees.
> +
> +Single Link Flag
> +^^^^^^^^^^^^^^^^
> +
> +There is a SINGLE_LINK flag which allows an application to indicate that only
> +one port will be connected to a queue.  Queues configured with the single-link
> +flag follow a FIFO like structure, maintaining ordering but it is only capable
> +of being linked to a single port (see below for port and queue linking details).
> +
> +
> +Ports
> +~~~~~
> +
> +Ports are the points of contact between worker cores and the eventdev. The
> +general use-case will see one CPU core using one port to enqueue and dequeue
> +events from an eventdev. Ports are linked to queues in order to retrieve events
> +from those queues (more details in `Linking Queues and Ports`_ below).
> +
> +
> +API Walk-through
> +----------------
> +
> +This section will introduce the reader to the eventdev API, showing how to
> +create and configure an eventdev and use it for a two-stage atomic pipeline
> +with a single core for TX. The diagram below shows the final state of the
> +application after this walk-through:
> +
> +.. _figure_eventdev-usage1:
> +
> +.. figure:: img/eventdev_usage.*
> +
> +   Sample eventdev usage, with RX, two atomic stages and a single-link to TX.
> +
> +
> +A high level overview of the setup steps are:
> +
> +* rte_event_dev_configure()
> +* rte_event_queue_setup()
> +* rte_event_port_setup()
> +* rte_event_port_link()
> +* rte_event_dev_start()
> +

Good.

> +Ingress of New Events
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Now that the eventdev is set up, and ready to receive events, the RX core must
> +enqueue some events into the system for it to schedule. The events to be
> +scheduled are ordinary DPDK packets, received from an eth_rx_burst() as normal.
> +The following code shows how those packets can be enqueued into the eventdev:
> +
> +.. code-block:: c
> +
> +        const uint16_t nb_rx = rte_eth_rx_burst(eth_port, 0, mbufs, BATCH_SIZE);
> +
> +        for (i = 0; i < nb_rx; i++) {
> +                ev[i].flow_id = mbufs[i]->hash.rss;
> +                ev[i].op = RTE_EVENT_OP_NEW;
> +                ev[i].sched_type = RTE_EVENT_QUEUE_CFG_ATOMIC_ONLY;
> +                ev[i].queue_id = 0;
> +                ev[i].event_type = RTE_EVENT_TYPE_CPU;

ev[i].event_type = RTE_EVENT_TYPE_ETHDEV;

> +                ev[i].sub_event_type = 0;
> +                ev[i].priority = RTE_EVENT_DEV_PRIORITY_NORMAL;
> +                ev[i].mbuf = mbufs[i];
> +        }
> +
> +        const int nb_tx = rte_event_enqueue_burst(dev_id, port_id, ev, nb_rx);
> +        if (nb_tx != nb_rx) {
> +                for(i = nb_tx; i < nb_rx; i++)
> +                        rte_pktmbuf_free(mbufs[i]);
> +        }
> +
> +Forwarding of Events
> +~~~~~~~~~~~~~~~~~~~~
> +
> +Now that the RX core has injected events, there is work to be done by the
> +workers. Note that each worker will dequeue as many events as it can in a burst,
> +process each one individually, and then burst the packets back into the
> +eventdev.
> +
> +The worker can lookup the events source from ``event.queue_id``, which should
> +indicate to the worker what workload needs to be performed on the event.
> +Once done, the worker can update the ``event.queue_id`` to a new value, to send
> +the event to the next stage in the pipeline.
> +
> +.. code-block:: c
> +
> +        int timeout = 0;
> +        struct rte_event events[BATCH_SIZE];
> +        uint16_t nb_rx = rte_event_dequeue_burst(dev_id, worker_port_id, events, BATCH_SIZE, timeout);
> +
> +        for (i = 0; i < nb_rx; i++) {
> +                /* process mbuf using events[i].queue_id as pipeline stage */
> +                struct rte_mbuf *mbuf = events[i].mbuf;
> +                /* Send event to next stage in pipeline */
> +                events[i].queue_id++;
> +        }
> +
> +        uint16_t nb_tx = rte_event_enqueue_burst(dev_id, port_id, events, nb_rx);
> +
> +
> +Egress of Events
> +~~~~~~~~~~~~~~~~
> +
> +Finally, when the packet is ready for egress or needs to be dropped, we need
> +to inform the eventdev that the packet is no longer being handled by the
> +application. This can be done by calling dequeue() or dequeue_burst(), which
> +indicates that the previous burst of packets is no longer in use by the
> +application.

Perfect.

> +
> +.. code-block:: c
> +
> +        struct rte_event events[BATCH_SIZE];
> +        uint16_t n = rte_event_dequeue_burst(dev_id, port_id, events, BATCH_SIZE, 0);
> +        /* burst #1 : now tx or use the packets */
> +        n = rte_event_dequeue_burst(dev_id, port_id, events, BATCH_SIZE, 0);
> +        /* burst #1 is now no longer valid to use in the application, as
> +           the eventdev has dropped any locks or released re-ordered packets */

This above code snippet is bit confusing(dequeue followed by dequeue).
How about changing it in following theme
http://dpdk.org/browse/next/dpdk-next-eventdev/tree/lib/librte_eventdev/rte_eventdev.h#n226


> +
> +Summary
> +-------
> +
> +The eventdev library allows an application to easily schedule events as it
> +requires, either using a run-to-completion or pipeline processing model.  The
> +queues and ports abstract the logical functionality of an eventdev, providing
> +the application with a generic method to schedule events.  With the flexible
> +PMD infrastructure applications benefit of improvements in existing eventdevs
> +and additions of new ones without modification.


With above changes:
Acked-by: Jerin Jacob <jerin.jacob at caviumnetworks.com>