From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 20E04A04B1; Mon, 23 Nov 2020 18:42:36 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id A426EC8F2; Mon, 23 Nov 2020 18:42:33 +0100 (CET) Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id 36A66C8C6 for ; Mon, 23 Nov 2020 18:42:31 +0100 (CET) IronPort-SDR: gbky0pXxHcTVbqX4HUtTY+lkRDv8m1+4bH99AbExSmekBI3nrq0lEqTIXaQu+Gcm8lPBGeH7go 830eQwLAO2QA== X-IronPort-AV: E=McAfee;i="6000,8403,9814"; a="169244306" X-IronPort-AV: E=Sophos;i="5.78,364,1599548400"; d="scan'208";a="169244306" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga007.jf.intel.com ([10.7.209.58]) by fmsmga104.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 23 Nov 2020 09:42:29 -0800 IronPort-SDR: a+APl5NhGyi/Iu/Qain1T3d1cqorXc/Fu0xY98okJoWM2up5GRviTEPqQuKHstm43iqnvbsKh8 +px7dIN2+SBg== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.78,364,1599548400"; d="scan'208";a="370097855" Received: from silpixa00400573.ir.intel.com (HELO silpixa00400573.ger.corp.intel.com) ([10.237.223.107]) by orsmga007.jf.intel.com with ESMTP; 23 Nov 2020 09:42:27 -0800 From: Cristian Dumitrescu To: dev@dpdk.org Cc: david.marchand@redhat.com Date: Mon, 23 Nov 2020 17:42:26 +0000 Message-Id: <20201123174227.11920-1-cristian.dumitrescu@intel.com> X-Mailer: git-send-email 2.17.1 Subject: [dpdk-dev] [PATCH] doc: add pipeline example to user guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Document the pipeline example in the Sample Application User Guide. Signed-off-by: Cristian Dumitrescu --- doc/guides/sample_app_ug/index.rst | 1 + doc/guides/sample_app_ug/pipeline.rst | 118 ++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100755 doc/guides/sample_app_ug/pipeline.rst 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 100755 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 + + $ .//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. -- 2.17.1