doc/guides/sample_app_ug/pipeline.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2020 Intel Corporation.
   3
   4 Pipeline Application
   5 ====================
   6
   7 Application overview
   8 --------------------
   9
  10 This application showcases the features of the Software Switch (SWX) pipeline that is aligned with the P4 language.
  11
  12 Each pipeline is created using a specification file that can either be manually developed or generated using a P4 compiler.
  13
  14 Each pipeline is built through the CLI, either by invoking commands one by one, or through a CLI script.
  15 The CLI can also be used to update the pipeline tables or poll the pipeline statistics.
  16
  17 Each pipeline is mapped to a specific application thread. Multiple pipelines can be mapped to the same thread.
  18
  19 Running the application
  20 -----------------------
  21
  22 The application startup command line is::
  23
  24    dpdk-pipeline [EAL_ARGS] -- [-s SCRIPT_FILE] [-h HOST] [-p PORT]
  25
  26 The application startup arguments are:
  27
  28 ``-s SCRIPT_FILE``
  29
  30  * Optional: Yes
  31
  32  * Default: Not present
  33
  34  * Argument: Path to the CLI script file to be run at application startup.
  35    No CLI script file will run at startup if this argument is not present.
  36
  37 ``-h HOST``
  38
  39  * Optional: Yes
  40
  41  * Default: ``0.0.0.0``
  42
  43  * Argument: IP Address of the host running the application to be used by
  44    remote TCP based client (telnet, netcat, etc.) for connection.
  45
  46 ``-p PORT``
  47
  48  * Optional: Yes
  49
  50  * Default: ``8086``
  51
  52  * Argument: TCP port number at which the application is running.
  53    This port number should be used by remote TCP client (such as telnet, netcat, etc.) to connect to host application.
  54
  55 Refer to *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options.
  56
  57 The following is an example command to run the application configured for the VXLAN encapsulation example:
  58
  59 .. code-block:: console
  60
  61     $ ./<build_dir>/examples/dpdk-pipeline -c 0x3 -- -s examples/vxlan.cli
  62
  63 The application should start successfully and display as follows:
  64
  65 .. code-block:: console
  66
  67     EAL: Detected 40 lcore(s)
  68     EAL: Detected 2 NUMA nodes
  69     EAL: Multi-process socket /var/run/.rte_unix
  70     EAL: Probing VFIO support...
  71     EAL: PCI device 0000:02:00.0 on NUMA socket 0
  72     EAL:   probe driver: 8086:10fb net_ixgbe
  73     ...
  74
  75 To run remote client (e.g. telnet) to communicate with the application:
  76
  77 .. code-block:: console
  78
  79     $ telnet 0.0.0.0 8086
  80
  81 When running a telnet client as above, command prompt is displayed:
  82
  83 .. code-block:: console
  84
  85     Trying 0.0.0.0...
  86     Connected to 0.0.0.0.
  87     Escape character is '^]'.
  88
  89     Welcome!
  90
  91     pipeline>
  92
  93 Once application and telnet client start running, messages can be sent from client to application.
  94
  95
  96 Application stages
  97 ------------------
  98
  99 Initialization
 100 ~~~~~~~~~~~~~~
 101
 102 During this stage, EAL layer is initialised and application specific arguments are parsed. Furthermore, the data structures
 103 for application objects are initialized. In case of any initialization error, an error message is displayed and the application
 104 is terminated.
 105
 106 Run-time
 107 ~~~~~~~~
 108
 109 The main thread is creating and managing all the application objects based on CLI input.
 110
 111 Each data plane thread runs one or several pipelines previously assigned to it in round-robin order. Each data plane thread
 112 executes two tasks in time-sharing mode:
 113
 114 1. *Packet processing task*: Process bursts of input packets read from the pipeline input ports.
 115
 116 2. *Message handling task*: Periodically, the data plane thread pauses the packet processing task and polls for request
 117    messages send by the main thread. Examples: add/remove pipeline to/from current data plane thread, add/delete rules
 118    to/from given table of a specific pipeline owned by the current data plane thread, read statistics, etc.