From: Cristian Dumitrescu Date: Mon, 23 Nov 2020 17:49:24 +0000 (+0000) Subject: doc: add pipeline example user guide X-Git-Url: http://git.droids-corp.org/?p=dpdk.git;a=commitdiff_plain;h=29485dd07bc3f6d6094cbe96f5d9126e52d744aa doc: add pipeline example user guide Document the pipeline example in the Sample Application User Guide. Signed-off-by: Cristian Dumitrescu --- diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index ef66e23bba..e8db83d3a7 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 0000000000..49d50136bc --- /dev/null +++ b/doc/guides/sample_app_ug/pipeline.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2020 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 + + $ .//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.