doc/guides/sample_app_ug/test_pipeline.rst


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266

..  BSD LICENSE
    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
    * Neither the name of Intel Corporation nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Test Pipeline Application
=========================

The Test Pipeline application illustrates the use of the DPDK Packet Framework tool suite.
Its purpose is to demonstrate the performance of single-table DPDK pipelines.

Overview
--------

The application uses three CPU cores:

*   Core A ("RX core") receives traffic from the NIC ports and feeds core B with traffic through SW queues.

*   Core B ("Pipeline core") implements a single-table DPDK pipeline
    whose type is selectable through specific command line parameter.
    Core B receives traffic from core A through software queues,
    processes it according to the actions configured in the table entries that
    are hit by the input packets and feeds it to core C through another set of software queues.

*   Core C ("TX core") receives traffic from core B through software queues and sends it to the NIC ports for transmission.

.. _figure_test_pipeline_app:

.. figure:: img/test_pipeline_app.*

   Test Pipeline Application

Compiling the Application
-------------------------
To compile the sample application see :doc:`compiling`

The application is located in the ``$RTE_SDK/test/test-pipline`` directory.


Running the Application
-----------------------

Application Command Line
~~~~~~~~~~~~~~~~~~~~~~~~

The application execution command line is:

.. code-block:: console

    ./test-pipeline [EAL options] -- -p PORTMASK --TABLE_TYPE

The -c or -l EAL CPU coremask/corelist option has to contain exactly 3 CPU cores.
The first CPU core in the core mask is assigned for core A, the second for core B and the third for core C.

The PORTMASK parameter must contain 2 or 4 ports.

Table Types and Behavior
~~~~~~~~~~~~~~~~~~~~~~~~

:numref:`table_test_pipeline_1` describes the table types used and how they are populated.

The hash tables are pre-populated with 16 million keys.
For hash tables, the following parameters can be selected:

*   **Configurable key size implementation or fixed (specialized) key size implementation (e.g. hash-8-ext or hash-spec-8-ext).**
    The key size specialized implementations are expected to provide better performance for 8-byte and 16-byte key sizes,
    while the key-size-non-specialized implementation is expected to provide better performance for larger key sizes;

*   **Key size (e.g. hash-spec-8-ext or hash-spec-16-ext).**
    The available options are 8, 16 and 32 bytes;

*   **Table type (e.g. hash-spec-16-ext or hash-spec-16-lru).**
    The available options are ext (extendable bucket) or lru (least recently used).

.. _table_test_pipeline_1:

.. table:: Table Types

   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | **#** | **TABLE_TYPE**         | **Description of Core B Table**                          | **Pre-added Table Entries**                           |
   |       |                        |                                                          |                                                       |
   +=======+========================+==========================================================+=======================================================+
   | 1     | none                   | Core B is not implementing a DPDK pipeline.              | N/A                                                   |
   |       |                        | Core B is implementing a pass-through from its input set |                                                       |
   |       |                        | of software queues to its output set of software queues. |                                                       |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 2     | stub                   | Stub table. Core B is implementing the same pass-through | N/A                                                   |
   |       |                        | functionality as described for the "none" option by      |                                                       |
   |       |                        | using the DPDK Packet Framework by using one             |                                                       |
   |       |                        | stub table for each input NIC port.                      |                                                       |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 3     | hash-[spec]-8-lru      | LRU hash table with 8-byte key size and 16 million       | 16 million entries are successfully added to the      |
   |       |                        | entries.                                                 | hash table with the following key format:             |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [4-byte index, 4 bytes of 0]                          |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | The action configured for all table entries is        |
   |       |                        |                                                          | "Sendto output port", with the output port index      |
   |       |                        |                                                          | uniformly distributed for the range of output ports.  |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | The default table rule (used in the case of a lookup  |
   |       |                        |                                                          | miss) is to drop the packet.                          |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | At run time, core A is creating the following lookup  |
   |       |                        |                                                          | key and storing it into the packet meta data for      |
   |       |                        |                                                          | core B to use for table lookup:                       |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [destination IPv4 address, 4 bytes of 0]              |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 4     | hash-[spec]-8-ext      | Extendable bucket hash table with 8-byte key size        | Same as hash-[spec]-8-lru table entries, above.       |
   |       |                        | and 16 million entries.                                  |                                                       |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 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 |
   |       |                        | entries.                                                 | table with the following key format:                  |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [4-byte index, 12 bytes of 0]                         |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | The action configured for all table entries is        |
   |       |                        |                                                          | "Send to output port", with the output port index     |
   |       |                        |                                                          | uniformly distributed for the range of output ports.  |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | The default table rule (used in the case of a lookup  |
   |       |                        |                                                          | miss) is to drop the packet.                          |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | At run time, core A is creating the following lookup  |
   |       |                        |                                                          | key and storing it into the packet meta data for core |
   |       |                        |                                                          | B to use for table lookup:                            |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [destination IPv4 address, 12 bytes of 0]             |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 6     | hash-[spec]-16-ext     | Extendable bucket hash table with 16-byte key size       | Same as hash-[spec]-16-lru table entries, above.      |
   |       |                        | and 16 million entries.                                  |                                                       |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 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 |
   |       |                        | entries.                                                 | table with the following key format:                  |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [4-byte index, 28 bytes of 0].                        |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | The action configured for all table entries is        |
   |       |                        |                                                          | "Send to output port", with the output port index     |
   |       |                        |                                                          | uniformly distributed for the range of output ports.  |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | The default table rule (used in the case of a lookup  |
   |       |                        |                                                          | miss) is to drop the packet.                          |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | At run time, core A is creating the following lookup  |
   |       |                        |                                                          | key and storing it into the packet meta data for      |
   |       |                        |                                                          | Lpmcore B to use for table lookup:                    |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [destination IPv4 address, 28 bytes of 0]             |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 8     | hash-[spec]-32-ext     | Extendable bucket hash table with 32-byte key size       | Same as hash-[spec]-32-lru table entries, above.      |
   |       |                        | and 16 million entries.                                  |                                                       |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 9     | lpm                    | Longest Prefix Match (LPM) IPv4 table.                   | In the case of two ports, two routes                  |
   |       |                        |                                                          | are added to the table:                               |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [0.0.0.0/9 => send to output port 0]                  |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [0.128.0.0/9 => send to output port 1]                |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | In case of four ports, four entries are added to the  |
   |       |                        |                                                          | table:                                                |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [0.0.0.0/10 => send to output port 0]                 |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [0.64.0.0/10 => send to output port 1]                |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [0.128.0.0/10 => send to output port 2]               |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [0.192.0.0/10 => send to output port 3]               |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | The default table rule (used in the case of a lookup  |
   |       |                        |                                                          | miss) is to drop the packet.                          |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | At run time, core A is storing the IPv4 destination   |
   |       |                        |                                                          | within the packet meta data to be later used by core  |
   |       |                        |                                                          | B as the lookup key.                                  |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+
   | 10    | acl                    | Access Control List (ACL) table                          | In the case of two ports, two ACL rules are added to  |
   |       |                        |                                                          | the table:                                            |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [priority = 0 (highest),                              |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | IPv4 source = ANY,                                    |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | IPv4 destination = 0.0.0.0/9,                         |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | L4 protocol = ANY,                                    |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | TCP source port = ANY,                                |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | TCP destination port = ANY                            |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | => send to output port 0]                             |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | [priority = 0 (highest),                              |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | IPv4 source = ANY,                                    |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | IPv4 destination = 0.128.0.0/9,                       |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | L4 protocol = ANY,                                    |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | TCP source port = ANY,                                |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | TCP destination port = ANY                            |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | => send to output port 0].                            |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          |                                                       |
   |       |                        |                                                          | The default table rule (used in the case of a lookup  |
   |       |                        |                                                          | miss) is to drop the packet.                          |
   |       |                        |                                                          |                                                       |
   +-------+------------------------+----------------------------------------------------------+-------------------------------------------------------+

Input Traffic
~~~~~~~~~~~~~

Regardless of the table type used for the core B pipeline,
the same input traffic can be used to hit all table entries with uniform distribution,
which results in uniform distribution of packets sent out on the set of output NIC ports.
The profile for input traffic is TCP/IPv4 packets with:

*   destination IP address as A.B.C.D with A fixed to 0 and B, C,D random

*   source IP address fixed to 0.0.0.0

*   destination TCP port fixed to 0

*   source TCP port fixed to 0