ip_pipeline.rst revision 97f17497
1..  BSD LICENSE
2    Copyright(c) 2015 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
31Internet Protocol (IP) Pipeline Application
32===========================================
33
34Application overview
35--------------------
36
37The *Internet Protocol (IP) Pipeline* application is intended to be a vehicle for rapid development of packet processing
38applications running on multi-core CPUs.
39
40The application provides a library of reusable functional blocks called pipelines.
41These pipelines can be seen as prefabricated blocks that can be instantiated and inter-connected through packet queues
42to create complete applications (super-pipelines).
43
44Pipelines are created and inter-connected through the application configuration file.
45By using different configuration files, different applications are effectively created, therefore this application
46can be seen as an application generator.
47The configuration of each pipeline can be updated at run-time through the application Command Line Interface (CLI).
48
49Main application components are:
50
51**A Library of reusable pipelines**
52
53 * Each pipeline represents a functional block, e.g. flow classification, firewall, routing, master, etc.
54
55 * Each pipeline type can be instantiated several times in the same application, which each instance configured
56   separately and mapped to a single CPU core.
57   Each CPU core can run one or several pipeline instances, which can be of same or different type.
58
59 * Pipeline instances are inter-connected through packet queues (for packet processing) and message queues
60   (for run-time configuration).
61
62 * Pipelines are implemented using DPDK Packet Framework.
63
64 * More pipeline types can always be built and added to the existing pipeline types.
65
66**The Configuration file**
67
68 * The configuration file defines the application structure.
69   By using different configuration files, different applications are created.
70
71 * All the application resources are created and configured through the application configuration file:
72   pipeline instances, buffer pools, links (i.e. network interfaces), hardware device RX/TX queues,
73   software queues, traffic manager devices, EAL startup arguments, etc.
74
75 * The configuration file syntax is “define by reference”, meaning that resources are defined as they are referenced.
76   First time a resource name is detected, it is registered with default parameters.
77   Optionally, the resource parameters can be further refined through a configuration file section dedicated to
78   that resource.
79
80 * Command Line Interface (CLI)
81
82**Global CLI commands: link configuration, etc.**
83
84 * Common pipeline CLI commands: ping (keep-alive), statistics, etc.
85
86 * Pipeline type specific CLI commands: used to configure instances of specific pipeline type.
87   These commands are registered with the application when the pipeline type is registered.
88   For example, the commands for routing pipeline instances include: route add, route delete, route list, etc.
89
90 * CLI commands can be grouped into scripts that can be invoked at initialization and at runtime.
91
92
93Design goals
94------------
95
96
97Rapid development
98~~~~~~~~~~~~~~~~~
99
100This application enables rapid development through quick connectivity of standard components called pipelines.
101These components are built using DPDK Packet Framework and encapsulate packet processing features at different levels:
102ports, tables, actions, pipelines and complete applications.
103
104Pipeline instances are instantiated, configured and inter-connected through low complexity configuration files loaded
105during application initialization.
106Each pipeline instance is mapped to a single CPU core, with each CPU core able to run one or multiple pipeline
107instances of same or different types. By loading a different configuration file, a different application is
108effectively started.
109
110
111Flexibility
112~~~~~~~~~~~
113
114Each packet processing application is typically represented as a chain of functional stages which is often called
115the functional pipeline of the application.
116These stages are mapped to CPU cores to create chains of CPU cores (pipeline model), clusters of CPU cores
117(run-to-completion model) or chains of clusters of CPU cores (hybrid model).
118
119This application allows all the above programming models.
120By applying changes to the configuration file, the application provides the flexibility to reshuffle its
121building blocks in different ways until the configuration providing the best performance is identified.
122
123
124Move pipelines around
125^^^^^^^^^^^^^^^^^^^^^
126
127The mapping of pipeline instances to CPU cores can be reshuffled through the configuration file.
128One or several pipeline instances can be mapped to the same CPU core.
129
130.. _figure_ip_pipelines_1:
131
132.. figure:: img/ip_pipelines_1.*
133
134   Example of moving pipeline instances across different CPU cores
135
136
137Move tables around
138^^^^^^^^^^^^^^^^^^
139
140There is some degree of flexibility for moving tables from one pipeline instance to another.
141Based on the configuration arguments passed to each pipeline instance in the configuration file, specific tables
142can be enabled or disabled.
143This way, a specific table can be “moved” from pipeline instance A to pipeline instance B by simply disabling its
144associated functionality for pipeline instance A while enabling it for pipeline instance B.
145
146Due to requirement to have simple syntax for the configuration file, moving tables across different pipeline
147instances is not as flexible as the mapping of pipeline instances to CPU cores, or mapping actions to pipeline tables.
148Complete flexibility in moving tables from one pipeline to another could be achieved through a complex pipeline
149description language that would detail the structural elements of the pipeline (ports, tables and actions) and
150their connectivity, resulting in complex syntax for the configuration file, which is not acceptable.
151Good configuration file readability through simple syntax is preferred.
152
153*Example*: the IP routing pipeline can run the routing function only (with ARP function run by a different
154pipeline instance), or it can run both the routing and ARP functions as part of the same pipeline instance.
155
156
157.. _figure_ip_pipelines_2:
158
159.. figure:: img/ip_pipelines_2.*
160
161   Example of moving tables across different pipeline instances
162
163
164Move actions around
165^^^^^^^^^^^^^^^^^^^
166
167When it makes sense, packet processing actions can be moved from one pipeline instance to another.
168Based on the configuration arguments passed to each pipeline instance in the configuration file, specific actions
169can be enabled or disabled.
170This way, a specific action can be "moved" from pipeline instance A to pipeline instance B by simply disabling its
171associated functionality for pipeline instance A while enabling it for pipeline instance B.
172
173*Example*: The flow actions of accounting, traffic metering, application identification, NAT, etc can be run as part
174of the flow classification pipeline instance or split across several flow actions pipeline instances, depending on
175the number of flow instances and their compute requirements.
176
177
178.. _figure_ip_pipelines_3:
179
180.. figure:: img/ip_pipelines_3.*
181
182   Example of moving actions across different tables and pipeline instances
183
184
185Performance
186~~~~~~~~~~~
187
188Performance of the application is the highest priority requirement.
189Flexibility is not provided at the expense of performance.
190
191The purpose of flexibility is to provide an incremental development methodology that allows monitoring the
192performance evolution:
193
194* Apply incremental changes in the configuration (e.g. mapping on pipeline instances to CPU cores)
195  in order to identify the configuration providing the best performance for a given application;
196
197* Add more processing incrementally (e.g. by enabling more actions for specific pipeline instances) until
198  the application is feature complete while checking the performance impact at each step.
199
200
201Debug capabilities
202~~~~~~~~~~~~~~~~~~
203
204The application provides a significant set of debug capabilities:
205
206* Command Line Interface (CLI) support for statistics polling: pipeline instance ping (keep-alive checks),
207  pipeline instance statistics per input port/output port/table, link statistics, etc;
208
209* Logging: Turn on/off application log messages based on priority level;
210
211Running the application
212-----------------------
213
214The application startup command line is::
215
216   ip_pipeline [-f CONFIG_FILE] [-s SCRIPT_FILE] -p PORT_MASK [-l LOG_LEVEL]
217
218The application startup arguments are:
219
220``-f CONFIG_FILE``
221
222 * Optional: Yes
223
224 * Default: ``./config/ip_pipeline.cfg``
225
226 * Argument: Path to the configuration file to be loaded by the application.
227   Please refer to the :ref:`ip_pipeline_configuration_file` for details on how to write the configuration file.
228
229``-s SCRIPT_FILE``
230
231 * Optional: Yes
232
233 * Default: Not present
234
235 * Argument: Path to the CLI script file to be run by the master pipeline at application startup.
236   No CLI script file will be run at startup of this argument is not present.
237
238``-p PORT_MASK``
239
240 * Optional: No
241
242 * Default: N/A
243
244 * Argument: Hexadecimal mask of NIC port IDs to be used by the application.
245   First port enabled in this mask will be referenced as LINK0 as part of the application configuration file,
246   next port as LINK1, etc.
247
248``-l LOG_LEVEL``
249
250 * Optional: Yes
251
252 * Default: 1 (High priority)
253
254 * Argument: Log level to determine which application messages are to be printed to standard output.
255   Available log levels are: 0 (None), 1 (High priority), 2 (Low priority).
256   Only application messages whose priority is higher than or equal to the application log level will be printed.
257
258
259Application stages
260------------------
261
262
263Configuration
264~~~~~~~~~~~~~
265
266During this stage, the application configuration file is parsed and its content is loaded into the application data
267structures.
268In case of any configuration file parse error, an error message is displayed and the application is terminated.
269Please refer to the :ref:`ip_pipeline_configuration_file` for a description of the application configuration file format.
270
271
272Configuration checking
273~~~~~~~~~~~~~~~~~~~~~~
274
275In the absence of any parse errors, the loaded content of application data structures is checked for overall consistency.
276In case of any configuration check error, an error message is displayed and the application is terminated.
277
278
279Initialization
280~~~~~~~~~~~~~~
281
282During this stage, the application resources are initialized and the handles to access them are saved into the
283application data structures.
284In case of any initialization error, an error message is displayed and the application is terminated.
285
286The typical resources to be initialized are: pipeline instances, buffer pools, links (i.e. network interfaces),
287hardware device RX/TX queues, software queues, traffic management devices, etc.
288
289
290.. _ip_pipeline_runtime:
291
292Run-time
293~~~~~~~~
294
295Each CPU core runs the pipeline instances assigned to it in time sharing mode and in round robin order:
296
2971. *Packet processing task*: The pipeline run-time code is typically a packet *processing* task built on top of
298   DPDK Packet Framework rte_pipeline library, which reads bursts of packets from the pipeline input ports,
299   performs table lookups and executes the identified actions for all tables in the pipeline, with packet
300   eventually written to pipeline output ports or dropped.
301
3022. *Message handling task*: Each CPU core will also periodically execute the *message handling* code of each
303   of the pipelines mapped to it.
304   The pipeline message handling code is processing the messages that are pending in the pipeline input message
305   queues, which are typically sent by the master CPU core for the on-the-fly pipeline configuration: check
306   that pipeline is still alive (ping), add/delete entries in the pipeline tables, get statistics, etc.
307   The frequency of executing the message handling code is usually much smaller than the frequency of executing
308   the packet processing work.
309
310Please refer to the :ref:`ip_pipeline_pipeline_section` for more details about the application pipeline module encapsulation.
311
312.. _ip_pipeline_configuration_file:
313
314Configuration file syntax
315-------------------------
316
317Syntax overview
318~~~~~~~~~~~~~~~
319
320The syntax of the configuration file is designed to be simple, which favors readability.
321The configuration file is parsed using the DPDK library librte_cfgfile, which supports simple
322`INI file format <http://en.wikipedia.org/wiki/INI_file>`__ for configuration files.
323
324As result, the configuration file is split into several sections, with each section containing one or more entries.
325The scope of each entry is its section, and each entry specifies a variable that is assigned a specific value.
326Any text after the ``;`` character is considered a comment and is therefore ignored.
327
328The following are application specific: number of sections, name of each section, number of entries of each section,
329name of the variables used for each section entry, the value format (e.g. signed/unsigned integer, string, etc)
330and range of each section entry variable.
331
332Generic example of configuration file section:
333
334.. code-block:: ini
335
336    [<section_name>]
337
338    <variable_name_1> = <value_1>
339
340    ...
341
342    <variable_name_N> = <value_N>
343
344
345Application resources present in the configuration file
346~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
347
348.. _table_ip_pipelines_resource_name:
349
350.. tabularcolumns:: |p{4cm}|p{6cm}|p{6cm}|
351
352.. table:: Application resource names in the configuration file
353
354   +--------------------------+-----------------------------+-------------------------------------------------+
355   | Resource type            | Format                      | Examples                                        |
356   +==========================+=============================+=================================================+
357   | Pipeline                 | ``PIPELINE<ID>``            | ``PIPELINE0``, ``PIPELINE1``                    |
358   +--------------------------+-----------------------------+-------------------------------------------------+
359   | Mempool                  | ``MEMPOOL<ID>``             | ``MEMPOOL0``, ``MEMPOOL1``                      |
360   +--------------------------+-----------------------------+-------------------------------------------------+
361   | Link (network interface) | ``LINK<ID>``                | ``LINK0``, ``LINK1``                            |
362   +--------------------------+-----------------------------+-------------------------------------------------+
363   | Link RX queue            | ``RXQ<LINK_ID>.<QUEUE_ID>`` | ``RXQ0.0``, ``RXQ1.5``                          |
364   +--------------------------+-----------------------------+-------------------------------------------------+
365   | Link TX queue            | ``TXQ<LINK_ID>.<QUEUE_ID>`` | ``TXQ0.0``, ``TXQ1.5``                          |
366   +--------------------------+-----------------------------+-------------------------------------------------+
367   | Software queue           | ``SWQ<ID>``                 | ``SWQ0``, ``SWQ1``                              |
368   +--------------------------+-----------------------------+-------------------------------------------------+
369   | Traffic Manager          | ``TM<LINK_ID>``             | ``TM0``, ``TM1``                                |
370   +--------------------------+-----------------------------+-------------------------------------------------+
371   | Source                   | ``SOURCE<ID>``              | ``SOURCE0``, ``SOURCE1``                        |
372   +--------------------------+-----------------------------+-------------------------------------------------+
373   | Sink                     | ``SINK<ID>``                | ``SINK0``, ``SINK1``                            |
374   +--------------------------+-----------------------------+-------------------------------------------------+
375   | Message queue            | ``MSGQ<ID>``                | ``MSGQ0``, ``MSGQ1``,                           |
376   |                          | ``MSGQ-REQ-PIPELINE<ID>``   | ``MSGQ-REQ-PIPELINE2``, ``MSGQ-RSP-PIPELINE2,`` |
377   |                          | ``MSGQ-RSP-PIPELINE<ID>``   | ``MSGQ-REQ-CORE-s0c1``, ``MSGQ-RSP-CORE-s0c1``  |
378   |                          | ``MSGQ-REQ-CORE-<CORE_ID>`` |                                                 |
379   |                          | ``MSGQ-RSP-CORE-<CORE_ID>`` |                                                 |
380   +--------------------------+-----------------------------+-------------------------------------------------+
381
382``LINK`` instances are created implicitly based on the ``PORT_MASK`` application startup argument.
383``LINK0`` is the first port enabled in the ``PORT_MASK``, port 1 is the next one, etc.
384The LINK ID is different than the DPDK PMD-level NIC port ID, which is the actual position in the bitmask mentioned above.
385For example, if bit 5 is the first bit set in the bitmask, then ``LINK0`` is having the PMD ID of 5.
386This mechanism creates a contiguous LINK ID space and isolates the configuration file against changes in the board
387PCIe slots where NICs are plugged in.
388
389``RXQ``, ``TXQ`` and ``TM`` instances have the LINK ID as part of their name.
390For example, ``RXQ2.1``, ``TXQ2.1`` and ``TM2`` are all associated with ``LINK2``.
391
392
393Rules to parse the configuration file
394~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
395
396The main rules used to parse the configuration file are:
397
3981. Application resource name determines the type of resource based on the name prefix.
399
400   *Example*: all software queues need to start with ``SWQ`` prefix, so ``SWQ0`` and ``SWQ5`` are valid software
401   queue names.
402
4032. An application resource is defined by creating a configuration file section with its name.
404   The configuration file section allows fine tuning on any of the resource parameters.
405   Some resource parameters are mandatory, in which case it is required to have them specified as part of the
406   section, while some others are optional, in which case they get assigned their default value when not present.
407
408   *Example*: section ``SWQ0`` defines a software queue named SWQ0, whose parameters are detailed as part of this section.
409
4103. An application resource can also be defined by referencing it.
411   Referencing a resource takes place by simply using its name as part of the value assigned to a variable in any
412   configuration file section.
413   In this case, the resource is registered with all its parameters having their default values.
414   Optionally, a section with the resource name can be added to the configuration file to fine tune some or all
415   of the resource parameters.
416
417   *Example*: in section ``PIPELINE3``, variable ``pktq_in`` includes ``SWQ5`` as part of its list, which results
418   in defining a software queue named ``SWQ5``; when there is no ``SWQ5`` section present in the configuration file,
419   ``SWQ5`` gets registered with default parameters.
420
421
422.. _ip_pipeline_pipeline_section:
423
424PIPELINE section
425~~~~~~~~~~~~~~~~
426
427.. _table_ip_pipelines_pipeline_section_1:
428
429.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}|
430
431.. table:: Configuration file PIPELINE section (1/2)
432
433   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
434   | Section       | Description                                               | Optional      | Range                  | Default value  |
435   +===============+===========================================================+===============+========================+================+
436   | type          | Pipeline type. Defines the functionality to be            | NO            | See "List              | N/A            |
437   |               | executed.                                                 |               | of pipeline types"     |                |
438   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
439   | core          | CPU core to run the current pipeline.                     | YES           | See "CPU Core          | CPU socket 0,  |
440   |               |                                                           |               | notation"              | core 0,        |
441   |               |                                                           |               |                        | hyper-thread 0 |
442   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
443   | pktq_in       | Packet queues to serve as input ports for the             | YES           | List of input          | Empty list     |
444   |               | current pipeline instance. The acceptable packet          |               | packet queue IDs       |                |
445   |               | queue types are: ``RXQ``, ``SWQ``, ``TM`` and ``SOURCE``. |               |                        |                |
446   |               | First device in this list is used as pipeline input port  |               |                        |                |
447   |               | 0, second as pipeline input port 1, etc.                  |               |                        |                |
448   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
449   | pktq_out      | Packet queues to serve as output ports for the            | YES           | List of output         | Empty list     |
450   |               | current pipeline instance. The acceptable packet          |               | packet queue IDs.      |                |
451   |               | queue types are: ``TXQ``, ``SWQ``, ``TM`` and ``SINK``.   |               |                        |                |
452   |               | First device in this list is used as pipeline output      |               |                        |                |
453   |               | port 0, second as pipeline output port 1, etc.            |               |                        |                |
454   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
455
456.. _table_ip_pipelines_pipeline_section_2:
457
458.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}|
459
460.. table:: Configuration file PIPELINE section (2/2)
461
462   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
463   | Section       | Description                                               | Optional      | Range                  | Default value  |
464   +===============+===========================================================+===============+========================+================+
465   | msgq_in       | Input message queues. These queues contain                | YES           | List of message        | Empty list     |
466   |               | request messages that need to be handled by the           |               | queue IDs              |                |
467   |               | current pipeline instance. The type and format of         |               |                        |                |
468   |               | request messages is defined by the pipeline type.         |               |                        |                |
469   |               | For each pipeline instance, there is an input             |               |                        |                |
470   |               | message queue defined implicitly, whose name is:          |               |                        |                |
471   |               | ``MSGQ-REQ-<PIPELINE_ID>``. This message queue            |               |                        |                |
472   |               | should not be mentioned as part of msgq_in list.          |               |                        |                |
473   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
474   | msgq_out      | Output message queues. These queues are used by           | YES           | List of message        | Empty list     |
475   |               | the current pipeline instance to write response           |               | queue IDs              |                |
476   |               | messages as result of request messages being              |               |                        |                |
477   |               | handled. The type and format of response                  |               |                        |                |
478   |               | messages is defined by the pipeline type.                 |               |                        |                |
479   |               | For each pipeline instance, there is an output            |               |                        |                |
480   |               | message queue defined implicitly, whose name is:          |               |                        |                |
481   |               | ``MSGQ-RSP-<PIPELINE_ID>``. This message queue            |               |                        |                |
482   |               | should not be mentioned as part of msgq_out list.         |               |                        |                |
483   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
484   | timer_period  | Time period, measured in milliseconds,                    | YES           | milliseconds           | 1 ms           |
485   |               | for handling the input message queues.                    |               |                        |                |
486   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
487   | <any other>   | Arguments to be passed to the current pipeline            | Depends on    | Depends on             | Depends on     |
488   |               | instance. Format of the arguments, their type,            | pipeline type | pipeline type          | pipeline type  |
489   |               | whether each argument is optional or mandatory            |               |                        |                |
490   |               | and its default value (when optional) are defined         |               |                        |                |
491   |               | by the pipeline type.                                     |               |                        |                |
492   |               | The value of the arguments is applicable to the           |               |                        |                |
493   |               | current pipeline instance only.                           |               |                        |                |
494   +---------------+-----------------------------------------------------------+---------------+------------------------+----------------+
495
496
497CPU core notation
498^^^^^^^^^^^^^^^^^
499
500The CPU Core notation is::
501
502    <CPU core> ::= [s|S<CPU socket ID>][c|C]<CPU core ID>[h|H]
503
504For example::
505
506    CPU socket 0, core 0, hyper-thread 0: 0, c0, s0c0
507
508    CPU socket 0, core 0, hyper-thread 1: 0h, c0h, s0c0h
509
510    CPU socket 3, core 9, hyper-thread 1: s3c9h
511
512
513MEMPOOL section
514~~~~~~~~~~~~~~~
515
516.. _table_ip_pipelines_mempool_section:
517
518.. tabularcolumns:: |p{2.5cm}|p{6cm}|p{1.5cm}|p{1.5cm}|p{3cm}|
519
520.. table:: Configuration file MEMPOOL section
521
522   +---------------+-----------------------------------------------+----------+----------+---------------------------+
523   | Section       | Description                                   | Optional | Type     | Default value             |
524   +===============+===============================================+==========+==========+===========================+
525   | buffer_size   | Buffer size (in bytes) for the current        | YES      | uint32_t | 2048                      |
526   |               | buffer pool.                                  |          |          | + sizeof(struct rte_mbuf) |
527   |               |                                               |          |          | + HEADROOM                |
528   +---------------+-----------------------------------------------+----------+----------+---------------------------+
529   | pool_size     | Number of buffers in the current buffer pool. | YES      | uint32_t | 32K                       |
530   +---------------+-----------------------------------------------+----------+----------+---------------------------+
531   | cache_size    | Per CPU thread cache size (in number of       | YES      | uint32_t | 256                       |
532   |               | buffers) for the current buffer pool.         |          |          |                           |
533   +---------------+-----------------------------------------------+----------+----------+---------------------------+
534   | cpu           | CPU socket ID where to allocate memory for    | YES      | uint32_t | 0                         |
535   |               | the current buffer pool.                      |          |          |                           |
536   +---------------+-----------------------------------------------+----------+----------+---------------------------+
537
538
539LINK section
540~~~~~~~~~~~~
541
542.. _table_ip_pipelines_link_section:
543
544.. tabularcolumns:: |p{3cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{2cm}|
545
546.. table:: Configuration file LINK section
547
548   +-----------------+----------------------------------------------+----------+----------+-------------------+
549   | Section entry   | Description                                  | Optional | Type     | Default value     |
550   +=================+==============================================+==========+==========+===================+
551   | arp_q           | NIC RX queue where ARP packets should        | YES      | 0 .. 127 | 0 (default queue) |
552   |                 | be filtered.                                 |          |          |                   |
553   +-----------------+----------------------------------------------+----------+----------+-------------------+
554   | tcp_syn_local_q | NIC RX queue where TCP packets with SYN      | YES      | 0 .. 127 | 0 (default queue) |
555   |                 | flag should be filtered.                     |          |          |                   |
556   +-----------------+----------------------------------------------+----------+----------+-------------------+
557   | ip_local_q      | NIC RX queue where IP packets with local     | YES      | 0 .. 127 | 0 (default queue) |
558   |                 | destination should be filtered.              |          |          |                   |
559   |                 | When TCP, UDP and SCTP local queues are      |          |          |                   |
560   |                 | defined, they take higher priority than this |          |          |                   |
561   |                 | queue.                                       |          |          |                   |
562   +-----------------+----------------------------------------------+----------+----------+-------------------+
563   | tcp_local_q     | NIC RX queue where TCP packets with local    | YES      | 0 .. 127 | 0 (default queue) |
564   |                 | destination should be filtered.              |          |          |                   |
565   +-----------------+----------------------------------------------+----------+----------+-------------------+
566   | udp_local_q     | NIC RX queue where TCP packets with local    | YES      | 0 .. 127 | 0 (default queue) |
567   |                 | destination should be filtered.              |          |          |                   |
568   +-----------------+----------------------------------------------+----------+----------+-------------------+
569   | sctp_local_q    | NIC RX queue where TCP packets with local    | YES      | 0 .. 127 | 0 (default queue) |
570   |                 | destination should be filtered.              |          |          |                   |
571   +-----------------+----------------------------------------------+----------+----------+-------------------+
572   | promisc         | Indicates whether current link should be     | YES      | YES/NO   | YES               |
573   |                 | started in promiscuous mode.                 |          |          |                   |
574   +-----------------+----------------------------------------------+----------+----------+-------------------+
575
576
577RXQ section
578~~~~~~~~~~~
579
580.. _table_ip_pipelines_rxq_section:
581
582.. tabularcolumns:: |p{3cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{2cm}|
583
584.. table:: Configuration file RXQ section
585
586   +---------------+--------------------------------------------+----------+----------+---------------+
587   | Section       | Description                                | Optional | Type     | Default value |
588   +===============+============================================+==========+==========+===============+
589   | mempool       | Mempool to use for buffer allocation for   | YES      | uint32_t | MEMPOOL0      |
590   |               | current NIC RX queue. The mempool ID has   |          |          |               |
591   |               | to be associated with a valid instance     |          |          |               |
592   |               | defined in the mempool entry of the global |          |          |               |
593   |               | section.                                   |          |          |               |
594   +---------------+--------------------------------------------+----------+----------+---------------+
595   | Size          | NIC RX queue size (number of descriptors)  | YES      | uint32_t | 128           |
596   +---------------+--------------------------------------------+----------+----------+---------------+
597   | burst         | Read burst size (number of descriptors)    | YES      | uint32_t | 32            |
598   +---------------+--------------------------------------------+----------+----------+---------------+
599
600
601TXQ section
602~~~~~~~~~~~
603
604.. _table_ip_pipelines_txq_section:
605
606.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{2cm}|p{1.5cm}|
607
608.. table:: Configuration file TXQ section
609
610   +---------------+----------------------------------------------+----------+------------------+---------------+
611   | Section       | Description                                  | Optional | Type             | Default value |
612   +===============+==============================================+==========+==================+===============+
613   | size          | NIC TX queue size (number of descriptors)    | YES      | uint32_t         | 512           |
614   |               |                                              |          | power of 2       |               |
615   |               |                                              |          | > 0              |               |
616   +---------------+----------------------------------------------+----------+------------------+---------------+
617   | burst         | Write burst size (number of descriptors)     | YES      | uint32_t         | 32            |
618   |               |                                              |          | power of 2       |               |
619   |               |                                              |          | 0 < burst < size |               |
620   +---------------+----------------------------------------------+----------+------------------+---------------+
621   | dropless      | When dropless is set to NO, packets can be   | YES      | YES/NO           | NO            |
622   |               | dropped if not enough free slots are         |          |                  |               |
623   |               | currently available in the queue, so the     |          |                  |               |
624   |               | write operation to the queue is non-         |          |                  |               |
625   |               | blocking.                                    |          |                  |               |
626   |               | When dropless is set to YES, packets cannot  |          |                  |               |
627   |               | be dropped if not enough free slots are      |          |                  |               |
628   |               | currently available in the queue, so the     |          |                  |               |
629   |               | write operation to the queue is blocking, as |          |                  |               |
630   |               | the write operation is retried until enough  |          |                  |               |
631   |               | free slots become available and all the      |          |                  |               |
632   |               | packets are successfully written to the      |          |                  |               |
633   |               | queue.                                       |          |                  |               |
634   +---------------+----------------------------------------------+----------+------------------+---------------+
635   | n_retries     | Number of retries. Valid only when dropless  | YES      | uint32_t         | 0             |
636   |               | is set to YES. When set to 0, it indicates   |          |                  |               |
637   |               | unlimited number of retries.                 |          |                  |               |
638   +---------------+----------------------------------------------+----------+------------------+---------------+
639
640
641SWQ section
642~~~~~~~~~~~
643
644.. _table_ip_pipelines_swq_section:
645
646.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}|
647
648.. table:: Configuration file SWQ section
649
650   +---------------+----------------------------------------------+----------+------------------+---------------+
651   | Section       | Description                                  | Optional | Type             | Default value |
652   +===============+==============================================+==========+==================+===============+
653   | size          | Queue size (number of packets)               | YES      | uint32_t         | 256           |
654   |               |                                              |          | power of 2       |               |
655   +---------------+----------------------------------------------+----------+------------------+---------------+
656   | burst_read    | Read burst size (number of packets)          | YES      | uint32_t         | 32            |
657   |               |                                              |          | power of 2       |               |
658   |               |                                              |          | 0 < burst < size |               |
659   +---------------+----------------------------------------------+----------+------------------+---------------+
660   | burst_write   | Write burst size (number of packets)         | YES      | uint32_t         | 32            |
661   |               |                                              |          | power of 2       |               |
662   |               |                                              |          | 0 < burst < size |               |
663   +---------------+----------------------------------------------+----------+------------------+---------------+
664   | dropless      | When dropless is set to NO, packets can be   | YES      | YES/NO           | NO            |
665   |               | dropped if not enough free slots are         |          |                  |               |
666   |               | currently available in the queue, so the     |          |                  |               |
667   |               | write operation to the queue is non-         |          |                  |               |
668   |               | blocking.                                    |          |                  |               |
669   |               | When dropless is set to YES, packets cannot  |          |                  |               |
670   |               | be dropped if not enough free slots are      |          |                  |               |
671   |               | currently available in the queue, so the     |          |                  |               |
672   |               | write operation to the queue is blocking, as |          |                  |               |
673   |               | the write operation is retried until enough  |          |                  |               |
674   |               | free slots become available and all the      |          |                  |               |
675   |               | packets are successfully written to the      |          |                  |               |
676   |               | queue.                                       |          |                  |               |
677   +---------------+----------------------------------------------+----------+------------------+---------------+
678   | n_retries     | Number of retries. Valid only when dropless  | YES      | uint32_t         | 0             |
679   |               | is set to YES. When set to 0, it indicates   |          |                  |               |
680   |               | unlimited number of retries.                 |          |                  |               |
681   +---------------+----------------------------------------------+----------+------------------+---------------+
682   | cpu           | CPU socket ID where to allocate memory       | YES      | uint32_t         | 0             |
683   |               | for this SWQ.                                |          |                  |               |
684   +---------------+----------------------------------------------+----------+------------------+---------------+
685
686
687TM section
688~~~~~~~~~~
689
690.. _table_ip_pipelines_tm_section:
691
692.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}|
693
694.. table:: Configuration file TM section
695
696   +---------------+---------------------------------------------+----------+----------+---------------+
697   | Section       | Description                                 | Optional | Type     | Default value |
698   +===============+=============================================+==========+==========+===============+
699   | Cfg           | File name to parse for the TM configuration | YES      | string   | tm_profile    |
700   |               | to be applied. The syntax of this file is   |          |          |               |
701   |               | described in the examples/qos_sched DPDK    |          |          |               |
702   |               | application documentation.                  |          |          |               |
703   +---------------+---------------------------------------------+----------+----------+---------------+
704   | burst_read    | Read burst size (number of packets)         | YES      | uint32_t | 64            |
705   +---------------+---------------------------------------------+----------+----------+---------------+
706   | burst_write   | Write burst size (number of packets)        | YES      | uint32_t | 32            |
707   +---------------+---------------------------------------------+----------+----------+---------------+
708
709
710SOURCE section
711~~~~~~~~~~~~~~
712
713.. _table_ip_pipelines_source_section:
714
715.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{2cm}|
716
717.. table:: Configuration file SOURCE section
718
719   +---------------+---------------------------------------+----------+----------+---------------+
720   | Section       | Description                           | Optional | Type     | Default value |
721   +===============+=======================================+==========+==========+===============+
722   | Mempool       | Mempool to use for buffer allocation. | YES      | uint32_t | MEMPOOL0      |
723   +---------------+---------------------------------------+----------+----------+---------------+
724   | Burst         | Read burst size (number of packets)   |          | uint32_t | 32            |
725   +---------------+---------------------------------------+----------+----------+---------------+
726
727
728SINK section
729~~~~~~~~~~~~
730
731Currently, there are no parameters to be passed to a sink device, so
732SINK section is not allowed.
733
734MSGQ section
735~~~~~~~~~~~~
736
737.. _table_ip_pipelines_msgq_section:
738
739.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}|
740
741.. table:: Configuration file MSGQ section
742
743   +---------+--------------------------------------------+----------+------------+---------------+
744   | Section | Description                                | Optional | Type       | Default value |
745   +=========+============================================+==========+============+===============+
746   | size    | Queue size (number of packets)             | YES      | uint32_t   | 64            |
747   |         |                                            |          | != 0       |               |
748   |         |                                            |          | power of 2 |               |
749   +---------+--------------------------------------------+----------+------------+---------------+
750   | cpu     | CPU socket ID where to allocate memory for | YES      | uint32_t   | 0             |
751   |         | the current queue.                         |          |            |               |
752   +---------+--------------------------------------------+----------+------------+---------------+
753
754
755EAL section
756~~~~~~~~~~~
757
758The application generates the EAL parameters rather than reading them from the command line.
759
760The CPU core mask parameter is generated based on the core entry of all PIPELINE sections.
761All the other EAL parameters can be set from this section of the application configuration file.
762
763
764Library of pipeline types
765-------------------------
766
767Pipeline module
768~~~~~~~~~~~~~~~
769
770A pipeline is a self-contained module that implements a packet processing function and is typically implemented on
771top of the DPDK Packet Framework *librte_pipeline* library.
772The application provides a run-time mechanism to register different pipeline types.
773
774Depending on the required configuration, each registered pipeline type (pipeline class) is instantiated one or
775several times, with each pipeline instance (pipeline object) assigned to one of the available CPU cores.
776Each CPU core can run one or more pipeline instances, which might be of same or different types.
777For more information of the CPU core threading model, please refer to the :ref:`ip_pipeline_runtime` section.
778
779
780Pipeline type
781^^^^^^^^^^^^^
782
783Each pipeline type is made up of a back-end and a front-end. The back-end represents the packet processing engine
784of the pipeline, typically implemented using the DPDK Packet Framework libraries, which reads packets from the
785input packet queues, handles them and eventually writes them to the output packet queues or drops them.
786The front-end represents the run-time configuration interface of the pipeline, which is exposed as CLI commands.
787The front-end communicates with the back-end through message queues.
788
789.. _table_ip_pipelines_back_end:
790
791.. tabularcolumns:: |p{1cm}|p{2cm}|p{12cm}|
792
793.. table:: Pipeline back-end
794
795   +------------+------------------+--------------------------------------------------------------------+
796   | Field name | Field type       | Description                                                        |
797   +============+==================+====================================================================+
798   | f_init     | Function pointer | Function to initialize the back-end of the current pipeline        |
799   |            |                  | instance. Typical work implemented by this function for the        |
800   |            |                  | current pipeline instance:                                         |
801   |            |                  | Memory allocation;                                                 |
802   |            |                  | Parse the pipeline type specific arguments;                        |
803   |            |                  | Initialize the pipeline input ports, output ports and tables,      |
804   |            |                  | interconnect input ports to tables;                                |
805   |            |                  | Set the message handlers.                                          |
806   +------------+------------------+--------------------------------------------------------------------+
807   | f_free     | Function pointer | Function to free the resources allocated by the back-end of the    |
808   |            |                  | current pipeline instance.                                         |
809   +------------+------------------+--------------------------------------------------------------------+
810   | f_run      | Function pointer | Set to NULL for pipelines implemented using the DPDK library       |
811   |            |                  | librte_pipeline (typical case), and to non-NULL otherwise. This    |
812   |            |                  | mechanism is made available to support quick integration of        |
813   |            |                  | legacy code.                                                       |
814   |            |                  | This function is expected to provide the packet processing         |
815   |            |                  | related code to be called as part of the CPU thread dispatch       |
816   |            |                  | loop, so this function is not allowed to contain an infinite loop. |
817   +------------+------------------+--------------------------------------------------------------------+
818   | f_timer    | Function pointer | Function to read the pipeline input message queues, handle         |
819   |            |                  | the request messages, create response messages and write           |
820   |            |                  | the response queues. The format of request and response            |
821   |            |                  | messages is defined by each pipeline type, with the exception      |
822   |            |                  | of some requests which are mandatory for all pipelines (e.g.       |
823   |            |                  | ping, statistics).                                                 |
824   +------------+------------------+--------------------------------------------------------------------+
825   | f_track    | Function pointer | See section Tracking pipeline output port to physical link         |
826   +------------+------------------+--------------------------------------------------------------------+
827
828
829.. _table_ip_pipelines_front_end:
830
831.. tabularcolumns:: |p{1cm}|p{2cm}|p{12cm}|
832
833.. table:: Pipeline front-end
834
835   +------------+-----------------------+-------------------------------------------------------------------+
836   | Field name | Field type            | Description                                                       |
837   +============+=======================+===================================================================+
838   | f_init     | Function pointer      | Function to initialize the front-end of the current pipeline      |
839   |            |                       | instance.                                                         |
840   +------------+-----------------------+-------------------------------------------------------------------+
841   | f_free     | Function pointer      | Function to free the resources allocated by the front-end of      |
842   |            |                       | the current pipeline instance.                                    |
843   +------------+-----------------------+-------------------------------------------------------------------+
844   | cmds       | Array of CLI commands | Array of CLI commands to be registered to the application CLI     |
845   |            |                       | for the current pipeline type. Even though the CLI is executed    |
846   |            |                       | by a different pipeline (typically, this is the master pipeline), |
847   |            |                       | from modularity perspective is more efficient to keep the         |
848   |            |                       | message client side (part of the front-end) together with the     |
849   |            |                       | message server side (part of the back-end).                       |
850   +------------+-----------------------+-------------------------------------------------------------------+
851
852
853Tracking pipeline output port to physical link
854^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
855
856Each pipeline instance is a standalone block that does not have visibility into the other pipeline instances or
857the application-level pipeline inter-connectivity.
858In some cases, it is useful for a pipeline instance to get application level information related to pipeline
859connectivity, such as to identify the output link (e.g. physical NIC port) where one of its output ports connected,
860either directly or indirectly by traversing other pipeline instances.
861
862Tracking can be successful or unsuccessful.
863Typically, tracking for a specific pipeline instance is successful when each one of its input ports can be mapped
864to a single output port, meaning that all packets read from the current input port can only go out on a single
865output port.
866Depending on the pipeline type, some exceptions may be allowed: a small portion of the packets, considered exception
867packets, are sent out on an output port that is pre-configured for this purpose.
868
869For pass-through pipeline type, the tracking is always successful.
870For pipeline types as flow classification, firewall or routing, the tracking is only successful when the number of
871output ports for the current pipeline instance is 1.
872
873This feature is used by the IP routing pipeline for adding/removing implicit routes every time a link is brought
874up/down.
875
876
877Table copies
878^^^^^^^^^^^^
879
880Fast table copy: pipeline table used by pipeline for the packet processing task, updated through messages, table
881data structures are optimized for lookup operation.
882
883Slow table copy: used by the configuration layer, typically updated through CLI commands, kept in sync with the fast
884copy (its update triggers the fast copy update).
885Required for executing advanced table queries without impacting the packet processing task, therefore the slow copy
886is typically organized using different criteria than the fast copy.
887
888Examples:
889
890* Flow classification: Search through current set of flows (e.g. list all flows with a specific source IP address);
891
892* Firewall: List rules in descending order of priority;
893
894* Routing table: List routes sorted by prefix depth and their type (local, remote, default);
895
896* ARP: List entries sorted per output interface.
897
898
899Packet meta-data
900^^^^^^^^^^^^^^^^
901
902Packet meta-data field offsets provided as argument to pipeline instances are essentially defining the data structure
903for the packet meta-data used by the current application use-case.
904It is very useful to put it in the configuration file as a comment in order to facilitate the readability of the
905configuration file.
906
907The reason to use field offsets for defining the data structure for the packet meta-data is due to the C language
908limitation of not being able to define data structures at run-time.
909Feature to consider: have the configuration file parser automatically generate and print the data structure defining
910the packet meta-data for the current application use-case.
911
912Packet meta-data typically contains:
913
9141. Pure meta-data: intermediate data per packet that is computed internally, passed between different tables of
915   the same pipeline instance (e.g. lookup key for the ARP table is obtained from the routing table), or between
916   different pipeline instances (e.g. flow ID, traffic metering color, etc);
917
9182. Packet fields: typically, packet header fields that are read directly from the packet, or read from the packet
919   and saved (duplicated) as a working copy at a different location within the packet meta-data (e.g. Diffserv
920   5-tuple, IP destination address, etc).
921
922Several strategies are used to design the packet meta-data, as described in the next subsections.
923
924
925Store packet meta-data in a different cache line as the packet headers
926""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
927
928This approach is able to support protocols with variable header length, like MPLS, where the offset of IP header
929from the start of the packet (and, implicitly, the offset of the IP header in the packet buffer) is not fixed.
930Since the pipelines typically require the specification of a fixed offset to the packet fields (e.g. Diffserv
9315-tuple, used by the flow classification pipeline, or the IP destination address, used by the IP routing pipeline),
932the workaround is to have the packet RX pipeline copy these fields at fixed offsets within the packet meta-data.
933
934As this approach duplicates some of the packet fields, it requires accessing more cache lines per packet for filling
935in selected packet meta-data fields (on RX), as well as flushing selected packet meta-data fields into the
936packet (on TX).
937
938Example:
939
940.. code-block:: ini
941
942
943    ; struct app_pkt_metadata {
944    ;	uint32_t ip_da;
945    ;      uint32_t hash;
946    ;      uint32_t flow_id;
947    ;      uint32_t color;
948    ; } __attribute__((__packed__));
949    ;
950
951    [PIPELINE1]
952    ; Packet meta-data offsets
953    ip_da_offset = 0;   Used by: routing
954    hash_offset = 4;    Used by: RX, flow classification
955    flow_id_offset = 8; Used by: flow classification, flow actions
956    color_offset = 12;  Used by: flow actions, routing
957
958
959Overlay the packet meta-data in the same cache line with the packet headers
960"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
961
962This approach is minimizing the number of cache line accessed per packet by storing the packet metadata in the
963same cache line with the packet headers.
964To enable this strategy, either some headroom is reserved for meta-data at the beginning of the packet headers
965cache line (e.g. if 16 bytes are needed for meta-data, then the packet headroom can be set to 128+16 bytes, so
966that NIC writes the first byte of the packet at offset 16 from the start of the first packet cache line),
967or meta-data is reusing the space of some packet headers that are discarded from the packet (e.g. input Ethernet
968header).
969
970Example:
971
972.. code-block:: ini
973
974    ; struct app_pkt_metadata {
975    ;     uint8_t headroom[RTE_PKTMBUF_HEADROOM]; /* 128 bytes (default) */
976    ;     union {
977    ;         struct {
978    ;             struct ether_hdr ether; /* 14 bytes */
979    ;             struct qinq_hdr qinq; /* 8 bytes */
980    ;         };
981    ;         struct {
982    ;             uint32_t hash;
983    ;             uint32_t flow_id;
984    ;             uint32_t color;
985    ;         };
986    ;     };
987    ;     struct ipv4_hdr ip; /* 20 bytes */
988    ; } __attribute__((__packed__));
989    ;
990    [PIPELINE2]
991    ; Packet meta-data offsets
992    qinq_offset = 142;    Used by: RX, flow classification
993    ip_da_offset = 166;   Used by: routing
994    hash_offset = 128;    Used by: RX, flow classification
995    flow_id_offset = 132; Used by: flow classification, flow actions
996    color_offset = 136;   Used by: flow actions, routing
997
998
999List of pipeline types
1000~~~~~~~~~~~~~~~~~~~~~~
1001
1002.. _table_ip_pipelines_types:
1003
1004.. tabularcolumns:: |p{3cm}|p{5cm}|p{4cm}|p{4cm}|
1005
1006.. table:: List of pipeline types provided with the application
1007
1008   +-----------------------+-----------------------------+-----------------------+------------------------------------------+
1009   | Name                  | Table(s)                    | Actions               | Messages                                 |
1010   +=======================+=============================+=======================+==========================================+
1011   | Pass-through          | Passthrough                 | 1. Pkt metadata build | 1. Ping                                  |
1012   |                       |                             | 2. Flow hash          | 2. Stats                                 |
1013   | Note: depending on    |                             | 3. Pkt checks         |                                          |
1014   | port type, can be     |                             | 4. Load balancing     |                                          |
1015   | used for RX, TX, IP   |                             |                       |                                          |
1016   | fragmentation, IP     |                             |                       |                                          |
1017   | reassembly or Traffic |                             |                       |                                          |
1018   | Management            |                             |                       |                                          |
1019   +-----------------------+-----------------------------+-----------------------+------------------------------------------+
1020   | Flow classification   | Exact match                 | 1. Flow ID            | 1. Ping                                  |
1021   |                       |                             |                       |                                          |
1022   |                       | * Key = byte array          | 2. Flow stats         | 2. Stats                                 |
1023   |                       |   (source: pkt metadata)    | 3. Metering           | 3. Flow stats                            |
1024   |                       | * Data = action dependent   | 4. Network Address    | 4. Action stats                          |
1025   |                       |                             | 5. Translation (NAT)  | 5. Flow add/ update/ delete              |
1026   |                       |                             |                       | 6. Default flow add/ update/ delete      |
1027   |                       |                             |                       | 7. Action update                         |
1028   +-----------------------+-----------------------------+-----------------------+------------------------------------------+
1029   | Flow actions          | Array                       | 1. Flow stats         | 1. Ping                                  |
1030   |                       |                             |                       |                                          |
1031   |                       | * Key = Flow ID             | 2. Metering           | 2. Stats                                 |
1032   |                       |   (source: pkt metadata)    | 3. Network Address    | 3. Action stats                          |
1033   |                       | * Data = action dependent   | 4. Translation (NAT)  | 4. Action update                         |
1034   +-----------------------+-----------------------------+-----------------------+------------------------------------------+
1035   | Firewall              | ACL                         | 1. Allow/Drop         | 1. Ping                                  |
1036   |                       |                             |                       |                                          |
1037   |                       | * Key = n-tuple             |                       | 2. Stats                                 |
1038   |                       |   (source: pkt headers)     |                       | 3. Rule add/ update/ delete              |
1039   |                       | * Data = none               |                       | 4. Default rule add/ update/ delete      |
1040   +-----------------------+-----------------------------+-----------------------+------------------------------------------+
1041   | IP routing            | LPM (IPv4 or IPv6,          | 1. TTL decrement and  | 1. Ping                                  |
1042   |                       | depending on pipeline type) | 2. IPv4 checksum      | 2. Stats                                 |
1043   |                       |                             |                       |                                          |
1044   |                       | * Key = IP destination      | 3. update             | 3. Route add/ update/ delete             |
1045   |                       |   (source: pkt metadata)    | 4. Header             | 4. Default route add/ update/ delete     |
1046   |                       | * Data = Dependent on       | 5. encapsulation      | 5. ARP entry add/ update/ delete         |
1047   |                       |   actions and next hop      | 6. (based on next hop | 6. Default ARP entry add/ update/ delete |
1048   |                       |   type                      | 7. type)              |                                          |
1049   |                       |                             |                       |                                          |
1050   |                       | Hash table (for ARP, only   |                       |                                          |
1051   |                       |                             |                       |                                          |
1052   |                       | when ARP is enabled)        |                       |                                          |
1053   |                       |                             |                       |                                          |
1054   |                       | * Key = (Port ID,           |                       |                                          |
1055   |                       |   next hop IP address)      |                       |                                          |
1056   |                       |   (source: pkt meta-data)   |                       |                                          |
1057   |                       | * Data: MAC address         |                       |                                          |
1058   +-----------------------+-----------------------------+-----------------------+------------------------------------------+
1059
1060
1061
1062Command Line Interface (CLI)
1063----------------------------
1064
1065Global CLI commands
1066~~~~~~~~~~~~~~~~~~~
1067
1068.. _table_ip_pipelines_cli_commands:
1069
1070.. tabularcolumns:: |p{3cm}|p{6cm}|p{6cm}|
1071
1072.. table:: Global CLI commands
1073
1074   +---------+---------------------------------------+--------------------------------------------+
1075   | Command | Description                           | Syntax                                     |
1076   +=========+=======================================+============================================+
1077   | run     | Run CLI commands script file.         | run <file>                                 |
1078   |         |                                       | <file> = path to file with CLI commands to |
1079   |         |                                       | execute                                    |
1080   +---------+---------------------------------------+--------------------------------------------+
1081   | quit    | Gracefully terminate the application. | quit                                       |
1082   +---------+---------------------------------------+--------------------------------------------+
1083
1084
1085CLI commands for link configuration
1086~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1087
1088.. _table_ip_pipelines_runtime_config:
1089
1090.. tabularcolumns:: |p{3cm}|p{6cm}|p{6cm}|
1091
1092.. table:: List of run-time configuration commands for link configuration
1093
1094   +-------------+--------------------+--------------------------------------------+
1095   | Command     | Description        | Syntax                                     |
1096   +=============+====================+============================================+
1097   | link config | Link configuration | link <link ID> config <IP address> <depth> |
1098   +-------------+--------------------+--------------------------------------------+
1099   | link up     | Link up            | link <link ID> up                          |
1100   +-------------+--------------------+--------------------------------------------+
1101   | link down   | Link down          | link <link ID> down                        |
1102   +-------------+--------------------+--------------------------------------------+
1103   | link ls     | Link list          | link ls                                    |
1104   +-------------+--------------------+--------------------------------------------+
1105
1106
1107CLI commands common for all pipeline types
1108~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1109
1110.. _table_ip_pipelines_mandatory:
1111
1112.. tabularcolumns:: |p{3cm}|p{6cm}|p{6cm}|
1113
1114.. table:: CLI commands mandatory for all pipelines
1115
1116   +--------------------+------------------------------------------------------+----------------------------------------------+
1117   | Command            | Description                                          | Syntax                                       |
1118   +====================+======================================================+==============================================+
1119   | ping               | Check whether specific pipeline instance is alive.   | p <pipeline ID> ping                         |
1120   |                    | The master pipeline sends a ping request             |                                              |
1121   |                    | message to given pipeline instance and waits for     |                                              |
1122   |                    | a response message back.                             |                                              |
1123   |                    | Timeout message is displayed when the response       |                                              |
1124   |                    | message is not received before the timer             |                                              |
1125   |                    | expires.                                             |                                              |
1126   +--------------------+------------------------------------------------------+----------------------------------------------+
1127   | stats              | Display statistics for specific pipeline input port, | p <pipeline ID> stats port in <port in ID>   |
1128   |                    | output port or table.                                | p <pipeline ID> stats port out <port out ID> |
1129   |                    |                                                      | p <pipeline ID> stats table <table ID>       |
1130   +--------------------+------------------------------------------------------+----------------------------------------------+
1131   | input port enable  | Enable given input port for specific pipeline        | p <pipeline ID> port in <port ID> enable     |
1132   |                    | instance.                                            |                                              |
1133   +--------------------+------------------------------------------------------+----------------------------------------------+
1134   | input port disable | Disable given input port for specific pipeline       | p <pipeline ID> port in <port ID> disable    |
1135   |                    | instance.                                            |                                              |
1136   +--------------------+------------------------------------------------------+----------------------------------------------+
1137
1138Pipeline type specific CLI commands
1139~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1140
1141The pipeline specific CLI commands are part of the pipeline type front-end.
1142