[dpdk-dev,v5,2/3] doc: add sw eventdev pipeline to sample app ug
Checks
Commit Message
From: Harry van Haaren <harry.van.haaren@intel.com>
Add a new entry in the sample app user-guides,
which details the working of the eventdev_pipeline_sw.
Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
Signed-off-by: David Hunt <david.hunt@intel.com>
---
doc/guides/sample_app_ug/eventdev_pipeline_sw.rst | 190 ++++++++++++++++++++++
doc/guides/sample_app_ug/index.rst | 1 +
2 files changed, 191 insertions(+)
create mode 100644 doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
Comments
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of David Hunt
> Sent: Friday, June 30, 2017 2:51 PM
> To: dev@dpdk.org
> Cc: jerin.jacob@caviumnetworks.com; Van Haaren, Harry
> <harry.van.haaren@intel.com>; Hunt, David <david.hunt@intel.com>
> Subject: [dpdk-dev] [PATCH v5 2/3] doc: add sw eventdev pipeline to sample
> app ug
>
> From: Harry van Haaren <harry.van.haaren@intel.com>
>
> Add a new entry in the sample app user-guides, which details the working
> of the eventdev_pipeline_sw.
>
> Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
> Signed-off-by: David Hunt <david.hunt@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
-----Original Message-----
>
> From: Harry van Haaren <harry.van.haaren@intel.com>
> > Adi a new entry in the sample app user-guides,
> which details the working of the eventdev_pipeline_sw.
>
> Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
> Signed-off-by: David Hunt <david.hunt@intel.com>
> ---
> doc/guides/sample_app_ug/eventdev_pipeline_sw.rst | 190 ++++++++++++++++++++++
> doc/guides/sample_app_ug/index.rst | 1 +
> 2 files changed, 191 insertions(+)
> create mode 100644 doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
>
> diff --git a/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst b/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
> new file mode 100644
> index 0000000..65c33a8
> --- /dev/null
> +++ b/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
> @@ -0,0 +1,190 @@
> +
> +
> +Eventdev Pipeline SW Sample Application
Eventdev Pipeline SW PMD Sample Application
> +=======================================
> +
> +The eventdev pipeline sample application is a sample app that demonstrates
> +the usage of the eventdev API using the software PMD. It shows how an
> +application can configure a pipeline and assign a set of worker cores to
> +perform the processing required.
> +
> +The application has a range of command line arguments allowing it to be
> +configured for various numbers worker cores, stages,queue depths and cycles per
> +stage of work. This is useful for performance testing as well as quickly testing
> +a particular pipeline configuration.
> +
> +
> +statistics that the PMD provides. The statistics provided depend on the PMD
> +used, see the Event Device Drivers section for a list of eventdev PMDs.
> diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
> index 02611ef..90be36a 100644
> --- a/doc/guides/sample_app_ug/index.rst
> +++ b/doc/guides/sample_app_ug/index.rst
> @@ -69,6 +69,7 @@ Sample Applications User Guides
> netmap_compatibility
> ip_pipeline
> test_pipeline
> + eventdev_pipeline_sw
eventdev_pipeline_sw_pmd
> dist_app
> vm_power_management
> tep_termination
With above changes:
Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
Hi Jerin,
On 3/7/2017 6:37 AM, Jerin Jacob wrote:
> -----Original Message-----
>> From: Harry van Haaren <harry.van.haaren@intel.com>
>>> Adi a new entry in the sample app user-guides,
>> which details the working of the eventdev_pipeline_sw.
>>
>> Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
>> Signed-off-by: David Hunt <david.hunt@intel.com>
>> ---
>> doc/guides/sample_app_ug/eventdev_pipeline_sw.rst | 190 ++++++++++++++++++++++
>> doc/guides/sample_app_ug/index.rst | 1 +
>> 2 files changed, 191 insertions(+)
>> create mode 100644 doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
>>
>> diff --git a/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst b/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
>> new file mode 100644
>> index 0000000..65c33a8
>> --- /dev/null
>> +++ b/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
>> @@ -0,0 +1,190 @@
>> +
>> +
>> +Eventdev Pipeline SW Sample Application
> Eventdev Pipeline SW PMD Sample Application
Sure.
>> +=======================================
>> +
>> +The eventdev pipeline sample application is a sample app that demonstrates
>> +the usage of the eventdev API using the software PMD. It shows how an
>> +application can configure a pipeline and assign a set of worker cores to
>> +perform the processing required.
>> +
>> +The application has a range of command line arguments allowing it to be
>> +configured for various numbers worker cores, stages,queue depths and cycles per
>> +stage of work. This is useful for performance testing as well as quickly testing
>> +a particular pipeline configuration.
>> +
>> +
>> +statistics that the PMD provides. The statistics provided depend on the PMD
>> +used, see the Event Device Drivers section for a list of eventdev PMDs.
>> diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
>> index 02611ef..90be36a 100644
>> --- a/doc/guides/sample_app_ug/index.rst
>> +++ b/doc/guides/sample_app_ug/index.rst
>> @@ -69,6 +69,7 @@ Sample Applications User Guides
>> netmap_compatibility
>> ip_pipeline
>> test_pipeline
>> + eventdev_pipeline_sw
> eventdev_pipeline_sw_pmd
There's no need to change this, it would break 'make doc'
The filename of the .rst is
"./doc/guides/sample_app_ug/eventdev_pipeline_sw.rst"
The app called eventdev_pipeline_sw.
>> dist_app
>> vm_power_management
>> tep_termination
> With above changes:
>
> Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
>
-----Original Message-----
> Date: Mon, 3 Jul 2017 10:25:17 +0100
> From: "Hunt, David" <david.hunt@intel.com>
> To: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> CC: dev@dpdk.org, harry.van.haaren@intel.com
> Subject: Re: [PATCH v5 2/3] doc: add sw eventdev pipeline to sample app ug
> User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:45.0) Gecko/20100101
> Thunderbird/45.8.0
>
> Hi Jerin,
>
>
> On 3/7/2017 6:37 AM, Jerin Jacob wrote:
> > -----Original Message-----
> > > From: Harry van Haaren <harry.van.haaren@intel.com>
> > > > Adi a new entry in the sample app user-guides,
> > > which details the working of the eventdev_pipeline_sw.
> > >
> > > Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
> > > Signed-off-by: David Hunt <david.hunt@intel.com>
> > > ---
> > > doc/guides/sample_app_ug/eventdev_pipeline_sw.rst | 190 ++++++++++++++++++++++
> > > doc/guides/sample_app_ug/index.rst | 1 +
> > > 2 files changed, 191 insertions(+)
> > > create mode 100644 doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
> > >
> > > diff --git a/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst b/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
> > > new file mode 100644
> > > index 0000000..65c33a8
> > > --- /dev/null
> > > +++ b/doc/guides/sample_app_ug/eventdev_pipeline_sw.rst
> > > @@ -0,0 +1,190 @@
> > > +
> > > +
> > > +Eventdev Pipeline SW Sample Application
> > Eventdev Pipeline SW PMD Sample Application
>
> Sure.
>
> > > +=======================================
> > > +
> > > +The eventdev pipeline sample application is a sample app that demonstrates
> > > +the usage of the eventdev API using the software PMD. It shows how an
> > > +application can configure a pipeline and assign a set of worker cores to
> > > +perform the processing required.
> > > +
> > > +The application has a range of command line arguments allowing it to be
> > > +configured for various numbers worker cores, stages,queue depths and cycles per
> > > +stage of work. This is useful for performance testing as well as quickly testing
> > > +a particular pipeline configuration.
> > > +
> > > +
> > > +statistics that the PMD provides. The statistics provided depend on the PMD
> > > +used, see the Event Device Drivers section for a list of eventdev PMDs.
> > > diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
> > > index 02611ef..90be36a 100644
> > > --- a/doc/guides/sample_app_ug/index.rst
> > > +++ b/doc/guides/sample_app_ug/index.rst
> > > @@ -69,6 +69,7 @@ Sample Applications User Guides
> > > netmap_compatibility
> > > ip_pipeline
> > > test_pipeline
> > > + eventdev_pipeline_sw
> > eventdev_pipeline_sw_pmd
>
> There's no need to change this, it would break 'make doc'
> The filename of the .rst is
> "./doc/guides/sample_app_ug/eventdev_pipeline_sw.rst"
> The app called eventdev_pipeline_sw.
OK
>
> > > dist_app
> > > vm_power_management
> > > tep_termination
> > With above changes:
> >
> > Acked-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
> >
>
On 3/7/2017 10:32 AM, Jerin Jacob wrote:
> -----Original Message-----
>>
--snip--
>>>> @@ -69,6 +69,7 @@ Sample Applications User Guides
>>>> netmap_compatibility
>>>> ip_pipeline
>>>> test_pipeline
>>>> + eventdev_pipeline_sw
>>> eventdev_pipeline_sw_pmd
>> There's no need to change this, it would break 'make doc'
>> The filename of the .rst is
>> "./doc/guides/sample_app_ug/eventdev_pipeline_sw.rst"
>> The app called eventdev_pipeline_sw.
> OK
Jerin,
I've now changed the app name to eventdev_pipeline_sw_pmd,
including directory name, rst name, etc. So now it's all consistent.
Rgds,
Dave.
new file mode 100644
@@ -0,0 +1,190 @@
+
+.. BSD LICENSE
+ Copyright(c) 2017 Intel Corporation. All rights reserved.
+ 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.
+
+Eventdev Pipeline SW Sample Application
+=======================================
+
+The eventdev pipeline sample application is a sample app that demonstrates
+the usage of the eventdev API using the software PMD. It shows how an
+application can configure a pipeline and assign a set of worker cores to
+perform the processing required.
+
+The application has a range of command line arguments allowing it to be
+configured for various numbers worker cores, stages,queue depths and cycles per
+stage of work. This is useful for performance testing as well as quickly testing
+a particular pipeline configuration.
+
+
+Compiling the Application
+-------------------------
+
+To compile the application:
+
+#. Go to the sample application directory:
+
+ .. code-block:: console
+
+ export RTE_SDK=/path/to/rte_sdk
+ cd ${RTE_SDK}/examples/eventdev_pipeline
+
+#. Set the target (a default target is used if not specified). For example:
+
+ .. code-block:: console
+
+ export RTE_TARGET=x86_64-native-linuxapp-gcc
+
+ See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
+
+#. Build the application:
+
+ .. code-block:: console
+
+ make
+
+Running the Application
+-----------------------
+
+The application has a lot of command line options. This allows specification of
+the eventdev PMD to use, and a number of attributes of the processing pipeline
+options.
+
+An example eventdev pipeline running with the software eventdev PMD using
+these settings is shown below:
+
+ * ``-r1``: core mask 0x1 for RX
+ * ``-t1``: core mask 0x1 for TX
+ * ``-e4``: core mask 0x4 for the software scheduler
+ * ``-w FF00``: core mask for worker cores, 8 cores from 8th to 16th
+ * ``-s4``: 4 atomic stages
+ * ``-n0``: process infinite packets (run forever)
+ * ``-c32``: worker dequeue depth of 32
+ * ``-W1000``: do 1000 cycles of work per packet in each stage
+ * ``-D``: dump statistics on exit
+
+.. code-block:: console
+
+ ./build/eventdev_pipeline_sw --vdev event_sw0 -- -r1 -t1 -e4 -w FF00 -s4 -n0 -c32 -W1000 -D
+
+The application has some sanity checking built-in, so if there is a function
+(eg; the RX core) which doesn't have a cpu core mask assigned, the application
+will print an error message:
+
+.. code-block:: console
+
+ Core part of pipeline was not assigned any cores. This will stall the
+ pipeline, please check core masks (use -h for details on setting core masks):
+ rx: 0
+ tx: 1
+
+Configuration of the eventdev is covered in detail in the programmers guide,
+see the Event Device Library section.
+
+
+Observing the Application
+-------------------------
+
+At runtime the eventdev pipeline application prints out a summary of the
+configuration, and some runtime statistics like packets per second. On exit the
+worker statistics are printed, along with a full dump of the PMD statistics if
+required. The following sections show sample output for each of the output
+types.
+
+Configuration
+~~~~~~~~~~~~~
+
+This provides an overview of the pipeline,
+scheduling type at each stage, and parameters to options such as how many
+flows to use and what eventdev PMD is in use. See the following sample output
+for details:
+
+.. code-block:: console
+
+ Config:
+ ports: 2
+ workers: 8
+ packets: 0
+ priorities: 1
+ Queue-prio: 0
+ qid0 type: atomic
+ Cores available: 44
+ Cores used: 10
+ Eventdev 0: event_sw
+ Stages:
+ Stage 0, Type Atomic Priority = 128
+ Stage 1, Type Atomic Priority = 128
+ Stage 2, Type Atomic Priority = 128
+ Stage 3, Type Atomic Priority = 128
+
+Runtime
+~~~~~~~
+
+At runtime, the statistics of the consumer are printed, stating the number of
+packets received, runtime in milliseconds, average mpps, and current mpps.
+
+.. code-block:: console
+
+ # consumer RX= xxxxxxx, time yyyy ms, avg z.zzz mpps [current w.www mpps]
+
+Shutdown
+~~~~~~~~
+
+At shutdown, the application prints the number of packets received and
+transmitted, and an overview of the distribution of work across worker cores.
+
+.. code-block:: console
+
+ Signal 2 received, preparing to exit...
+ worker 12 thread done. RX=4966581 TX=4966581
+ worker 13 thread done. RX=4963329 TX=4963329
+ worker 14 thread done. RX=4953614 TX=4953614
+ worker 0 thread done. RX=0 TX=0
+ worker 11 thread done. RX=4970549 TX=4970549
+ worker 10 thread done. RX=4986391 TX=4986391
+ worker 9 thread done. RX=4970528 TX=4970528
+ worker 15 thread done. RX=4974087 TX=4974087
+ worker 8 thread done. RX=4979908 TX=4979908
+ worker 2 thread done. RX=0 TX=0
+
+ Port Workload distribution:
+ worker 0 : 12.5 % (4979876 pkts)
+ worker 1 : 12.5 % (4970497 pkts)
+ worker 2 : 12.5 % (4986359 pkts)
+ worker 3 : 12.5 % (4970517 pkts)
+ worker 4 : 12.5 % (4966566 pkts)
+ worker 5 : 12.5 % (4963297 pkts)
+ worker 6 : 12.5 % (4953598 pkts)
+ worker 7 : 12.5 % (4974055 pkts)
+
+To get a full dump of the state of the eventdev PMD, pass the ``-D`` flag to
+this application. When the app is terminated using ``Ctrl+C``, the
+``rte_event_dev_dump()`` function is called, resulting in a dump of the
+statistics that the PMD provides. The statistics provided depend on the PMD
+used, see the Event Device Drivers section for a list of eventdev PMDs.
@@ -69,6 +69,7 @@ Sample Applications User Guides
netmap_compatibility
ip_pipeline
test_pipeline
+ eventdev_pipeline_sw
dist_app
vm_power_management
tep_termination