[V2] doc: add pipeline example to user guide
diff mbox series

Message ID 20201123174925.12046-1-cristian.dumitrescu@intel.com
State Accepted, archived
Delegated to: David Marchand
Headers show
Series
  • [V2] doc: add pipeline example to user guide
Related show

Checks

Context Check Description
ci/travis-robot success Travis build: passed
ci/Intel-compilation success Compilation OK
ci/checkpatch success coding style OK

Commit Message

Dumitrescu, Cristian Nov. 23, 2020, 5:49 p.m. UTC
Document the pipeline example in the Sample Application User Guide.

Signed-off-by: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
---
 doc/guides/sample_app_ug/index.rst    |   1 +
 doc/guides/sample_app_ug/pipeline.rst | 118 ++++++++++++++++++++++++++
 2 files changed, 119 insertions(+)
 create mode 100644 doc/guides/sample_app_ug/pipeline.rst

Comments

David Marchand Nov. 25, 2020, 1 p.m. UTC | #1
On Mon, Nov 23, 2020 at 6:49 PM Cristian Dumitrescu
<cristian.dumitrescu@intel.com> wrote:
> diff --git a/doc/guides/sample_app_ug/pipeline.rst b/doc/guides/sample_app_ug/pipeline.rst
> new file mode 100644
> index 000000000..9b52d8a22
> --- /dev/null
> +++ b/doc/guides/sample_app_ug/pipeline.rst
> @@ -0,0 +1,118 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2015-2018 Intel Corporation.

Should it be 2020?
I can fix while applying.


Thanks.
Dumitrescu, Cristian Nov. 25, 2020, 2:12 p.m. UTC | #2
> -----Original Message-----
> From: David Marchand <david.marchand@redhat.com>
> Sent: Wednesday, November 25, 2020 1:00 PM
> To: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>
> Cc: dev <dev@dpdk.org>
> Subject: Re: [PATCH V2] doc: add pipeline example to user guide
> 
> On Mon, Nov 23, 2020 at 6:49 PM Cristian Dumitrescu
> <cristian.dumitrescu@intel.com> wrote:
> > diff --git a/doc/guides/sample_app_ug/pipeline.rst
> b/doc/guides/sample_app_ug/pipeline.rst
> > new file mode 100644
> > index 000000000..9b52d8a22
> > --- /dev/null
> > +++ b/doc/guides/sample_app_ug/pipeline.rst
> > @@ -0,0 +1,118 @@
> > +..  SPDX-License-Identifier: BSD-3-Clause
> > +    Copyright(c) 2015-2018 Intel Corporation.
> 
> Should it be 2020?
> I can fix while applying.
> 
> 
> Thanks.
> 
> --
> David Marchand

Yes, thanks David!
David Marchand Nov. 25, 2020, 2:22 p.m. UTC | #3
On Mon, Nov 23, 2020 at 6:49 PM Cristian Dumitrescu
<cristian.dumitrescu@intel.com> wrote:
>
> Document the pipeline example in the Sample Application User Guide.
>
> Signed-off-by: Cristian Dumitrescu <cristian.dumitrescu@intel.com>

Applied, thanks.

Patch
diff mbox series

diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index ef66e23bb..e8db83d3a 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -48,6 +48,7 @@  Sample Applications User Guides
     vdpa
     ip_pipeline
     test_pipeline
+    pipeline
     eventdev_pipeline
     dist_app
     vm_power_management
diff --git a/doc/guides/sample_app_ug/pipeline.rst b/doc/guides/sample_app_ug/pipeline.rst
new file mode 100644
index 000000000..9b52d8a22
--- /dev/null
+++ b/doc/guides/sample_app_ug/pipeline.rst
@@ -0,0 +1,118 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2015-2018 Intel Corporation.
+
+Pipeline Application
+====================
+
+Application overview
+--------------------
+
+This application showcases the features of the Software Switch (SWX) pipeline that is aligned with the P4 language.
+
+Each pipeline is created using a specification file that can either be manually developed or generated using a P4 compiler.
+
+Each pipeline is built through the CLI, either by invoking commands one by one, or through a CLI script.
+The CLI can also be used to update the pipeline tables or poll the pipeline statistics.
+
+Each pipeline is mapped to a specific application thread. Multiple pipelines can be mapped to the same thread.
+
+Running the application
+-----------------------
+
+The application startup command line is::
+
+   dpdk-pipeline [EAL_ARGS] -- [-s SCRIPT_FILE] [-h HOST] [-p PORT]
+
+The application startup arguments are:
+
+``-s SCRIPT_FILE``
+
+ * Optional: Yes
+
+ * Default: Not present
+
+ * Argument: Path to the CLI script file to be run at application startup.
+   No CLI script file will run at startup if this argument is not present.
+
+``-h HOST``
+
+ * Optional: Yes
+
+ * Default: ``0.0.0.0``
+
+ * Argument: IP Address of the host running the application to be used by
+   remote TCP based client (telnet, netcat, etc.) for connection.
+
+``-p PORT``
+
+ * Optional: Yes
+
+ * Default: ``8086``
+
+ * Argument: TCP port number at which the application is running.
+   This port number should be used by remote TCP client (such as telnet, netcat, etc.) to connect to host application.
+
+Refer to *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options.
+
+The following is an example command to run the application configured for the VXLAN encapsulation example:
+
+.. code-block:: console
+
+    $ ./<build_dir>/examples/dpdk-pipeline -c 0x3 -- -s examples/vxlan.cli
+
+The application should start successfully and display as follows:
+
+.. code-block:: console
+
+    EAL: Detected 40 lcore(s)
+    EAL: Detected 2 NUMA nodes
+    EAL: Multi-process socket /var/run/.rte_unix
+    EAL: Probing VFIO support...
+    EAL: PCI device 0000:02:00.0 on NUMA socket 0
+    EAL:   probe driver: 8086:10fb net_ixgbe
+    ...
+
+To run remote client (e.g. telnet) to communicate with the application:
+
+.. code-block:: console
+
+    $ telnet 0.0.0.0 8086
+
+When running a telnet client as above, command prompt is displayed:
+
+.. code-block:: console
+
+    Trying 0.0.0.0...
+    Connected to 0.0.0.0.
+    Escape character is '^]'.
+
+    Welcome!
+
+    pipeline>
+
+Once application and telnet client start running, messages can be sent from client to application.
+
+
+Application stages
+------------------
+
+Initialization
+~~~~~~~~~~~~~~
+
+During this stage, EAL layer is initialised and application specific arguments are parsed. Furthermore, the data structures
+for application objects are initialized. In case of any initialization error, an error message is displayed and the application
+is terminated.
+
+Run-time
+~~~~~~~~
+
+The main thread is creating and managing all the application objects based on CLI input.
+
+Each data plane thread runs one or several pipelines previously assigned to it in round-robin order. Each data plane thread
+executes two tasks in time-sharing mode:
+
+1. *Packet processing task*: Process bursts of input packets read from the pipeline input ports.
+
+2. *Message handling task*: Periodically, the data plane thread pauses the packet processing task and polls for request
+   messages send by the main thread. Examples: add/remove pipeline to/from current data plane thread, add/delete rules
+   to/from given table of a specific pipeline owned by the current data plane thread, read statistics, etc.