[dpdk-dev,v5,19/20] doc: add event device and software eventdev
Checks
Commit Message
This commit adds a section to the docs listing the event
device PMDs available.
It then adds the software eventdev PMD to the listed event
devices.
Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
---
doc/guides/eventdevs/index.rst | 40 +++++++++++
doc/guides/eventdevs/sw.rst | 148 +++++++++++++++++++++++++++++++++++++++++
doc/guides/index.rst | 1 +
3 files changed, 189 insertions(+)
create mode 100644 doc/guides/eventdevs/index.rst
create mode 100644 doc/guides/eventdevs/sw.rst
Comments
On Fri, Mar 24, 2017 at 04:53:14PM +0000, Harry van Haaren wrote:
> This commit adds a section to the docs listing the event
> device PMDs available.
>
> It then adds the software eventdev PMD to the listed event
> devices.
>
> Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
> ---
> doc/guides/eventdevs/index.rst | 40 +++++++++++
> doc/guides/eventdevs/sw.rst | 148 +++++++++++++++++++++++++++++++++++++++++
> doc/guides/index.rst | 1 +
> 3 files changed, 189 insertions(+)
> create mode 100644 doc/guides/eventdevs/index.rst
> create mode 100644 doc/guides/eventdevs/sw.rst
>
> diff --git a/doc/guides/eventdevs/index.rst b/doc/guides/eventdevs/index.rst
> new file mode 100644
> index 0000000..9b1fcc7
> --- /dev/null
> +++ b/doc/guides/eventdevs/index.rst
> @@ -0,0 +1,40 @@
> +.. BSD LICENSE
> + Copyright(c) 2017 Intel Corporation. All rights reserved.
> +
> + Redistribution and use in source and binary forms, with or without
> + modification, are permitted provided that the following conditions
> + are met:
> +
> + * Redistributions of source code must retain the above copyright
> + notice, this list of conditions and the following disclaimer.
> + * Redistributions in binary form must reproduce the above copyright
> + notice, this list of conditions and the following disclaimer in
> + the documentation and/or other materials provided with the
> + distribution.
> + * Neither the name of Intel Corporation nor the names of its
> + contributors may be used to endorse or promote products derived
> + from this software without specific prior written permission.
> +
> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
> + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
> + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
> + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
> + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
> + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
> + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
> + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
> + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
> + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
> + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
> +
> +Event Device Drivers
> +====================
> +
> +The following are a list of Event device PMDs, which can be used from an
> +application trough the EventDev API.
> +
> +.. toctree::
> + :maxdepth: 2
> + :numbered:
> +
> + sw
> diff --git a/doc/guides/eventdevs/sw.rst b/doc/guides/eventdevs/sw.rst
> new file mode 100644
> index 0000000..79d8023
> --- /dev/null
> +++ b/doc/guides/eventdevs/sw.rst
> @@ -0,0 +1,148 @@
> +.. BSD LICENSE
> + Copyright(c) 2017 Intel Corporation. All rights reserved.
> +
> + Redistribution and use in source and binary forms, with or without
> + modification, are permitted provided that the following conditions
> + are met:
> +
> + * Redistributions of source code must retain the above copyright
> + notice, this list of conditions and the following disclaimer.
> + * Redistributions in binary form must reproduce the above copyright
> + notice, this list of conditions and the following disclaimer in
> + the documentation and/or other materials provided with the
> + distribution.
> + * Neither the name of Intel Corporation nor the names of its
> + contributors may be used to endorse or promote products derived
> + from this software without specific prior written permission.
> +
> + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
> + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
> + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
> + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
> + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
> + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
> + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
> + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
> + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
> + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
> + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
> +
> +Software Eventdev Poll Mode Driver
> +==================================
> +
> +The software eventdev is an implementation of the Eventdev API, that provides a
> +wide range of the Eventdev features. The eventdev relies on a CPU core to
> +perform event scheduling.
> +
> +
> +Features
> +--------
> +
> +The software eventdev implements many features in the eventdev API;
> +
> +Queues
> + * Atomic
> + * Ordered
> + * Parallel
> + * Single-Link
> +
> +Ports
> + * Load balanced (for Atomic, Ordered, Parallel queues)
> + * Single Link (for single-link queues)
> +
> +Event Priorities
> + * Each event has a priority, which can be used to provide basic QOS
s/QOS/QoS
> +
> +
> +Configuration and Options
> +-------------------------
> +
> +The software eventdev is a vdev device, and as such can be created from the
> +application code, or from the EAL command line:
> +
> +* Call ``rte_eal_vdev_init("event_sw0")`` from the application
> +
> +* Use ``--vdev="event_sw0"`` in the EAL options, which will call
> + rte_eal_vdev_init() internally
> +
> +Example:
> +
> +.. code-block:: console
> +
> + ./your_eventdev_application --vdev="event_sw0"
> +
> +
> +Scheduling Quanta
> +~~~~~~~~~~~~~~~~~
> +
> +The scheduling quanta sets the number of events that the device attempts to
> +schedule before returning to the application from the ``rte_event_schedule()``
> +function. Note that is a *hint* only, and that fewer or more events may be
> +scheduled in a given iteration.
> +
> +The scheduling quanta can be set using a string argument to the vdev
> +create call:
> +
> +.. code-block:: console
> +
> + --vdev="event_sw0,sched_quanta=64"
> +
> +
> +Credit Quanta
> +~~~~~~~~~~~~~
> +
> +The credit quanta is the number of credits that a port will fetch at a time from
> +the instance's credit pool. Higher numbers will cause less overhead in the
> +atomic credit fetch code, however it also reduces the overall number of credits
> +in the system faster. A balanced number (eg 32) ensures that only small numbers
> +of credits are pre-allocated at a time, while also mitigating performance impact
> +of the atomics.
> +
> +Experimentation with higher values may provide minor performance improvements,
> +at the cost of the whole system having less credits. On the other hand,
> +reducing the quanta may cause measurable performance impact but provide the
> +system with a higher number of credits at all times.
> +
> +A value of 32 seems a good balance however your specific application may
> +benefit from a higher or reduced quanta size, experimentation is required to
> +verify possible gains.
> +
> +.. code-block:: console
> +
> + --vdev="event_sw0,credit_quanta=64"
> +
> +
> +Limitations
> +-----------
> +
> +The software eventdev implementation has a few limitations. The root cause of
> +these limitations is that the performance impact of supporting the feature
> +would be significant.
> +
> +
> +"All Types" Queues
> +~~~~~~~~~~~~~~~~~~
> +
> +The software eventdev does not support creating queues that handle all types of
> +traffic. An eventdev with this capability allows enqueueing Atomic, Ordered and
> +Parallel traffic to the same queue, but scheduling each of them appropriately.
> +
> +The root cause of not allowing Atomic, Ordered and Parallel event types in the
> +same queue is that it causes excessive branching in the code to enqueue packets
> +to the queue, causing a significant performance impact.
> +
> +The ``RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES`` flag is not set in the
> +``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the software
> +eventdev.
> +
> +Distributed Scheduler
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +The software eventdev is a centralized scheduler, requiring the
> +``rte_event_schedule()`` function to be called by a CPU core to perform the
> +required event distribution. This is not really a limitation but rather a
> +design decision.
> +
> +The ``RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED`` flag is not set in the
> +``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the software
> +eventdev.
How about adding unavilablity of timeout support
rte_event_dequeue_burst?
> diff --git a/doc/guides/index.rst b/doc/guides/index.rst
> index 82b00e9..63716b0 100644
> --- a/doc/guides/index.rst
> +++ b/doc/guides/index.rst
> @@ -43,6 +43,7 @@ DPDK documentation
> testpmd_app_ug/index
> nics/index
> cryptodevs/index
> + eventdevs/index
> xen/index
> contributing/index
> rel_notes/index
> --
> 2.7.4
With suggested changes,
Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>
new file mode 100644
@@ -0,0 +1,40 @@
+.. BSD LICENSE
+ Copyright(c) 2017 Intel Corporation. All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Intel Corporation nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Event Device Drivers
+====================
+
+The following are a list of Event device PMDs, which can be used from an
+application trough the EventDev API.
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ sw
new file mode 100644
@@ -0,0 +1,148 @@
+.. BSD LICENSE
+ Copyright(c) 2017 Intel Corporation. All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Intel Corporation nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Software Eventdev Poll Mode Driver
+==================================
+
+The software eventdev is an implementation of the Eventdev API, that provides a
+wide range of the Eventdev features. The eventdev relies on a CPU core to
+perform event scheduling.
+
+
+Features
+--------
+
+The software eventdev implements many features in the eventdev API;
+
+Queues
+ * Atomic
+ * Ordered
+ * Parallel
+ * Single-Link
+
+Ports
+ * Load balanced (for Atomic, Ordered, Parallel queues)
+ * Single Link (for single-link queues)
+
+Event Priorities
+ * Each event has a priority, which can be used to provide basic QOS
+
+
+Configuration and Options
+-------------------------
+
+The software eventdev is a vdev device, and as such can be created from the
+application code, or from the EAL command line:
+
+* Call ``rte_eal_vdev_init("event_sw0")`` from the application
+
+* Use ``--vdev="event_sw0"`` in the EAL options, which will call
+ rte_eal_vdev_init() internally
+
+Example:
+
+.. code-block:: console
+
+ ./your_eventdev_application --vdev="event_sw0"
+
+
+Scheduling Quanta
+~~~~~~~~~~~~~~~~~
+
+The scheduling quanta sets the number of events that the device attempts to
+schedule before returning to the application from the ``rte_event_schedule()``
+function. Note that is a *hint* only, and that fewer or more events may be
+scheduled in a given iteration.
+
+The scheduling quanta can be set using a string argument to the vdev
+create call:
+
+.. code-block:: console
+
+ --vdev="event_sw0,sched_quanta=64"
+
+
+Credit Quanta
+~~~~~~~~~~~~~
+
+The credit quanta is the number of credits that a port will fetch at a time from
+the instance's credit pool. Higher numbers will cause less overhead in the
+atomic credit fetch code, however it also reduces the overall number of credits
+in the system faster. A balanced number (eg 32) ensures that only small numbers
+of credits are pre-allocated at a time, while also mitigating performance impact
+of the atomics.
+
+Experimentation with higher values may provide minor performance improvements,
+at the cost of the whole system having less credits. On the other hand,
+reducing the quanta may cause measurable performance impact but provide the
+system with a higher number of credits at all times.
+
+A value of 32 seems a good balance however your specific application may
+benefit from a higher or reduced quanta size, experimentation is required to
+verify possible gains.
+
+.. code-block:: console
+
+ --vdev="event_sw0,credit_quanta=64"
+
+
+Limitations
+-----------
+
+The software eventdev implementation has a few limitations. The root cause of
+these limitations is that the performance impact of supporting the feature
+would be significant.
+
+
+"All Types" Queues
+~~~~~~~~~~~~~~~~~~
+
+The software eventdev does not support creating queues that handle all types of
+traffic. An eventdev with this capability allows enqueueing Atomic, Ordered and
+Parallel traffic to the same queue, but scheduling each of them appropriately.
+
+The root cause of not allowing Atomic, Ordered and Parallel event types in the
+same queue is that it causes excessive branching in the code to enqueue packets
+to the queue, causing a significant performance impact.
+
+The ``RTE_EVENT_DEV_CAP_QUEUE_ALL_TYPES`` flag is not set in the
+``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the software
+eventdev.
+
+Distributed Scheduler
+~~~~~~~~~~~~~~~~~~~~~
+
+The software eventdev is a centralized scheduler, requiring the
+``rte_event_schedule()`` function to be called by a CPU core to perform the
+required event distribution. This is not really a limitation but rather a
+design decision.
+
+The ``RTE_EVENT_DEV_CAP_DISTRIBUTED_SCHED`` flag is not set in the
+``event_dev_cap`` field of the ``rte_event_dev_info`` struct for the software
+eventdev.
@@ -43,6 +43,7 @@ DPDK documentation
testpmd_app_ug/index
nics/index
cryptodevs/index
+ eventdevs/index
xen/index
contributing/index
rel_notes/index