sample_app_ug/test_pipeline.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 Test Pipeline Application
  32 =========================
  33
  34 The Test Pipeline application illustrates the use of the DPDK Packet Framework tool suite.
  35 Its purpose is to demonstrate the performance of single-table DPDK pipelines.
  36
  37 Overview
  38 --------
  39
  40 The application uses three CPU cores:
  41
  42 *   Core A ("RX core") receives traffic from the NIC ports and feeds core B with traffic through SW queues.
  43
  44 *   Core B ("Pipeline core") implements a single-table DPDK pipeline
  45     whose type is selectable through specific command line parameter.
  46     Core B receives traffic from core A through software queues,
  47     processes it according to the actions configured in the table entries that
  48     are hit by the input packets and feeds it to core C through another set of software queues.
  49
  50 *   Core C ("TX core") receives traffic from core B through software queues and sends it to the NIC ports for transmission.
  51
  52 .. _figure_test_pipeline_app:
  53
  54 .. figure:: img/test_pipeline_app.*
  55
  56    Test Pipeline Application
  57
  58
  59 Compiling the Application
  60 -------------------------
  61
  62 #.  Go to the app/test directory:
  63
  64     .. code-block:: console
  65
  66         export RTE_SDK=/path/to/rte_sdk
  67         cd ${RTE_SDK}/app/test/test-pipeline
  68
  69 #.  Set the target (a default target is used if not specified):
  70
  71     .. code-block:: console
  72
  73         export RTE_TARGET=x86_64-native-linuxapp-gcc
  74
  75 #.  Build the application:
  76
  77     .. code-block:: console
  78
  79         make
  80
  81 Running the Application
  82 -----------------------
  83
  84 Application Command Line
  85 ~~~~~~~~~~~~~~~~~~~~~~~~
  86
  87 The application execution command line is:
  88
  89 .. code-block:: console
  90
  91     ./test-pipeline [EAL options] -- -p PORTMASK --TABLE_TYPE
  92
  93 The -c or -l EAL CPU coremask/corelist option has to contain exactly 3 CPU cores.
  94 The first CPU core in the core mask is assigned for core A, the second for core B and the third for core C.
  95
  96 The PORTMASK parameter must contain 2 or 4 ports.
  97
  98 Table Types and Behavior
  99 ~~~~~~~~~~~~~~~~~~~~~~~~
 100
 101 :numref:`table_test_pipeline_1` describes the table types used and how they are populated.
 102
 103 The hash tables are pre-populated with 16 million keys.
 104 For hash tables, the following parameters can be selected:
 105
 106 *   **Configurable key size implementation or fixed (specialized) key size implementation (e.g. hash-8-ext or hash-spec-8-ext).**
 107     The key size specialized implementations are expected to provide better performance for 8-byte and 16-byte key sizes,
 108     while the key-size-non-specialized implementation is expected to provide better performance for larger key sizes;
 109
 110 *   **Key size (e.g. hash-spec-8-ext or hash-spec-16-ext).**
 111     The available options are 8, 16 and 32 bytes;
 112
 113 *   **Table type (e.g. hash-spec-16-ext or hash-spec-16-lru).**
 114     The available options are ext (extendable bucket) or lru (least recently used).
 115
 116 .. _table_test_pipeline_1:
 117
 118 .. table:: Table Types
 119
 120    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 121    | **#** | **TABLE_TYPE**         | **Description of Core B Table**                          | **Pre-added Table Entries**                           |
 122    |       |                        |                                                          |                                                       |
 123    +=======+========================+==========================================================+=======================================================+
 124    | 1     | none                   | Core B is not implementing a DPDK pipeline.              | N/A                                                   |
 125    |       |                        | Core B is implementing a pass-through from its input set |                                                       |
 126    |       |                        | of software queues to its output set of software queues. |                                                       |
 127    |       |                        |                                                          |                                                       |
 128    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 129    | 2     | stub                   | Stub table. Core B is implementing the same pass-through | N/A                                                   |
 130    |       |                        | functionality as described for the "none" option by      |                                                       |
 131    |       |                        | using the DPDK Packet Framework by using one             |                                                       |
 132    |       |                        | stub table for each input NIC port.                      |                                                       |
 133    |       |                        |                                                          |                                                       |
 134    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 135    | 3     | hash-[spec]-8-lru      | LRU hash table with 8-byte key size and 16 million       | 16 million entries are successfully added to the      |
 136    |       |                        | entries.                                                 | hash table with the following key format:             |
 137    |       |                        |                                                          |                                                       |
 138    |       |                        |                                                          | [4-byte index, 4 bytes of 0]                          |
 139    |       |                        |                                                          |                                                       |
 140    |       |                        |                                                          | The action configured for all table entries is        |
 141    |       |                        |                                                          | "Sendto output port", with the output port index      |
 142    |       |                        |                                                          | uniformly distributed for the range of output ports.  |
 143    |       |                        |                                                          |                                                       |
 144    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
 145    |       |                        |                                                          | miss) is to drop the packet.                          |
 146    |       |                        |                                                          |                                                       |
 147    |       |                        |                                                          | At run time, core A is creating the following lookup  |
 148    |       |                        |                                                          | key and storing it into the packet meta data for      |
 149    |       |                        |                                                          | core B to use for table lookup:                       |
 150    |       |                        |                                                          |                                                       |
 151    |       |                        |                                                          | [destination IPv4 address, 4 bytes of 0]              |
 152    |       |                        |                                                          |                                                       |
 153    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 154    | 4     | hash-[spec]-8-ext      | Extendable bucket hash table with 8-byte key size        | Same as hash-[spec]-8-lru table entries, above.       |
 155    |       |                        | and 16 million entries.                                  |                                                       |
 156    |       |                        |                                                          |                                                       |
 157    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 158    | 5     | hash-[spec]-16-lru     | LRU hash table with 16-byte key size and 16 million      | 16 million entries are successfully added to the hash |
 159    |       |                        | entries.                                                 | table with the following key format:                  |
 160    |       |                        |                                                          |                                                       |
 161    |       |                        |                                                          | [4-byte index, 12 bytes of 0]                         |
 162    |       |                        |                                                          |                                                       |
 163    |       |                        |                                                          | The action configured for all table entries is        |
 164    |       |                        |                                                          | "Send to output port", with the output port index     |
 165    |       |                        |                                                          | uniformly distributed for the range of output ports.  |
 166    |       |                        |                                                          |                                                       |
 167    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
 168    |       |                        |                                                          | miss) is to drop the packet.                          |
 169    |       |                        |                                                          |                                                       |
 170    |       |                        |                                                          | At run time, core A is creating the following lookup  |
 171    |       |                        |                                                          | key and storing it into the packet meta data for core |
 172    |       |                        |                                                          | B to use for table lookup:                            |
 173    |       |                        |                                                          |                                                       |
 174    |       |                        |                                                          | [destination IPv4 address, 12 bytes of 0]             |
 175    |       |                        |                                                          |                                                       |
 176    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 177    | 6     | hash-[spec]-16-ext     | Extendable bucket hash table with 16-byte key size       | Same as hash-[spec]-16-lru table entries, above.      |
 178    |       |                        | and 16 million entries.                                  |                                                       |
 179    |       |                        |                                                          |                                                       |
 180    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 181    | 7     | hash-[spec]-32-lru     | LRU hash table with 32-byte key size and 16 million      | 16 million entries are successfully added to the hash |
 182    |       |                        | entries.                                                 | table with the following key format:                  |
 183    |       |                        |                                                          |                                                       |
 184    |       |                        |                                                          | [4-byte index, 28 bytes of 0].                        |
 185    |       |                        |                                                          |                                                       |
 186    |       |                        |                                                          | The action configured for all table entries is        |
 187    |       |                        |                                                          | "Send to output port", with the output port index     |
 188    |       |                        |                                                          | uniformly distributed for the range of output ports.  |
 189    |       |                        |                                                          |                                                       |
 190    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
 191    |       |                        |                                                          | miss) is to drop the packet.                          |
 192    |       |                        |                                                          |                                                       |
 193    |       |                        |                                                          | At run time, core A is creating the following lookup  |
 194    |       |                        |                                                          | key and storing it into the packet meta data for      |
 195    |       |                        |                                                          | Lpmcore B to use for table lookup:                    |
 196    |       |                        |                                                          |                                                       |
 197    |       |                        |                                                          | [destination IPv4 address, 28 bytes of 0]             |
 198    |       |                        |                                                          |                                                       |
 199    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 200    | 8     | hash-[spec]-32-ext     | Extendable bucket hash table with 32-byte key size       | Same as hash-[spec]-32-lru table entries, above.      |
 201    |       |                        | and 16 million entries.                                  |                                                       |
 202    |       |                        |                                                          |                                                       |
 203    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 204    | 9     | lpm                    | Longest Prefix Match (LPM) IPv4 table.                   | In the case of two ports, two routes                  |
 205    |       |                        |                                                          | are added to the table:                               |
 206    |       |                        |                                                          |                                                       |
 207    |       |                        |                                                          | [0.0.0.0/9 => send to output port 0]                  |
 208    |       |                        |                                                          |                                                       |
 209    |       |                        |                                                          | [0.128.0.0/9 => send to output port 1]                |
 210    |       |                        |                                                          |                                                       |
 211    |       |                        |                                                          | In case of four ports, four entries are added to the  |
 212    |       |                        |                                                          | table:                                                |
 213    |       |                        |                                                          |                                                       |
 214    |       |                        |                                                          | [0.0.0.0/10 => send to output port 0]                 |
 215    |       |                        |                                                          |                                                       |
 216    |       |                        |                                                          | [0.64.0.0/10 => send to output port 1]                |
 217    |       |                        |                                                          |                                                       |
 218    |       |                        |                                                          | [0.128.0.0/10 => send to output port 2]               |
 219    |       |                        |                                                          |                                                       |
 220    |       |                        |                                                          | [0.192.0.0/10 => send to output port 3]               |
 221    |       |                        |                                                          |                                                       |
 222    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
 223    |       |                        |                                                          | miss) is to drop the packet.                          |
 224    |       |                        |                                                          |                                                       |
 225    |       |                        |                                                          | At run time, core A is storing the IPv4 destination   |
 226    |       |                        |                                                          | within the packet meta data to be later used by core  |
 227    |       |                        |                                                          | B as the lookup key.                                  |
 228    |       |                        |                                                          |                                                       |
 229    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 230    | 10    | acl                    | Access Control List (ACL) table                          | In the case of two ports, two ACL rules are added to  |
 231    |       |                        |                                                          | the table:                                            |
 232    |       |                        |                                                          |                                                       |
 233    |       |                        |                                                          | [priority = 0 (highest),                              |
 234    |       |                        |                                                          |                                                       |
 235    |       |                        |                                                          | IPv4 source = ANY,                                    |
 236    |       |                        |                                                          |                                                       |
 237    |       |                        |                                                          | IPv4 destination = 0.0.0.0/9,                         |
 238    |       |                        |                                                          |                                                       |
 239    |       |                        |                                                          | L4 protocol = ANY,                                    |
 240    |       |                        |                                                          |                                                       |
 241    |       |                        |                                                          | TCP source port = ANY,                                |
 242    |       |                        |                                                          |                                                       |
 243    |       |                        |                                                          | TCP destination port = ANY                            |
 244    |       |                        |                                                          |                                                       |
 245    |       |                        |                                                          | => send to output port 0]                             |
 246    |       |                        |                                                          |                                                       |
 247    |       |                        |                                                          |                                                       |
 248    |       |                        |                                                          | [priority = 0 (highest),                              |
 249    |       |                        |                                                          |                                                       |
 250    |       |                        |                                                          | IPv4 source = ANY,                                    |
 251    |       |                        |                                                          |                                                       |
 252    |       |                        |                                                          | IPv4 destination = 0.128.0.0/9,                       |
 253    |       |                        |                                                          |                                                       |
 254    |       |                        |                                                          | L4 protocol = ANY,                                    |
 255    |       |                        |                                                          |                                                       |
 256    |       |                        |                                                          | TCP source port = ANY,                                |
 257    |       |                        |                                                          |                                                       |
 258    |       |                        |                                                          | TCP destination port = ANY                            |
 259    |       |                        |                                                          |                                                       |
 260    |       |                        |                                                          | => send to output port 0].                            |
 261    |       |                        |                                                          |                                                       |
 262    |       |                        |                                                          |                                                       |
 263    |       |                        |                                                          | The default table rule (used in the case of a lookup  |
 264    |       |                        |                                                          | miss) is to drop the packet.                          |
 265    |       |                        |                                                          |                                                       |
 266    +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
 267
 268 Input Traffic
 269 ~~~~~~~~~~~~~
 270
 271 Regardless of the table type used for the core B pipeline,
 272 the same input traffic can be used to hit all table entries with uniform distribution,
 273 which results in uniform distribution of packets sent out on the set of output NIC ports.
 274 The profile for input traffic is TCP/IPv4 packets with:
 275
 276 *   destination IP address as A.B.C.D with A fixed to 0 and B, C,D random
 277
 278 *   source IP address fixed to 0.0.0.0
 279
 280 *   destination TCP port fixed to 0
 281
 282 *   source TCP port fixed to 0