From mboxrd@z Thu Jan 1 00:00:00 1970 From: John McNamara Subject: =?utf-8?q?=5BPATCH_v2=5D_doc=3A_ip=5Fpipeline_app_user?= =?utf-8?q?_guide?= Date: Tue, 11 Aug 2015 17:47:08 +0100 Message-ID: <1439311628-10210-1-git-send-email-john.mcnamara@intel.com> References: <1438868898-12669-1-git-send-email-cristian.dumitrescu@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable To: dev@dpdk.org Return-path: Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) by dpdk.org (Postfix) with ESMTP id B65DB5A64 for ; Tue, 11 Aug 2015 18:47:19 +0200 (CEST) In-Reply-To: <1438868898-12669-1-git-send-email-cristian.dumitrescu@intel.com> List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" From: "Dumitrescu, Cristian" Added more extensive documentation for ip_pipeline application. Signed-off-by: Cristian Dumitrescu Acked-by: Jasvinder Singh Acked-by: Piotr Azarewicz Acked-by: John McNamara --- doc/guides/index.rst | 1 + doc/guides/ip_pipeline_ug/img/ip_pipelines_1.svg | 738 +++++++++++++ doc/guides/ip_pipeline_ug/img/ip_pipelines_2.svg | 997 ++++++++++++++= +++ doc/guides/ip_pipeline_ug/img/ip_pipelines_3.svg | 826 ++++++++++++++ doc/guides/ip_pipeline_ug/index.rst | 38 + doc/guides/ip_pipeline_ug/ip_pipeline_app.rst | 1129 ++++++++++++++= ++++++ doc/guides/sample_app_ug/index.rst | 1 - .../sample_app_ug/internet_proto_ip_pipeline.rst | 135 --- 8 files changed, 3729 insertions(+), 136 deletions(-) create mode 100644 doc/guides/ip_pipeline_ug/img/ip_pipelines_1.svg create mode 100644 doc/guides/ip_pipeline_ug/img/ip_pipelines_2.svg create mode 100644 doc/guides/ip_pipeline_ug/img/ip_pipelines_3.svg create mode 100644 doc/guides/ip_pipeline_ug/index.rst create mode 100644 doc/guides/ip_pipeline_ug/ip_pipeline_app.rst delete mode 100644 doc/guides/sample_app_ug/internet_proto_ip_pipeline.r= st diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 439c7e3..a916856 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -44,6 +44,7 @@ Contents: nics/index sample_app_ug/index testpmd_app_ug/index + ip_pipeline_ug/index faq/index rel_notes/index contributing/index diff --git a/doc/guides/ip_pipeline_ug/img/ip_pipelines_1.svg b/doc/guide= s/ip_pipeline_ug/img/ip_pipelines_1.svg new file mode 100644 index 0000000..a114ed8 --- /dev/null +++ b/doc/guides/ip_pipeline_ug/img/ip_pipelines_1.svg @@ -0,0 +1,738 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CPU Core 1 + CPU Core 2 + CPU Core 3 + + P1 + P2 + P3 + CPU Core 1 + P1 + P2 + P3 + + diff --git a/doc/guides/ip_pipeline_ug/img/ip_pipelines_2.svg b/doc/guide= s/ip_pipeline_ug/img/ip_pipelines_2.svg new file mode 100644 index 0000000..5252b17 --- /dev/null +++ b/doc/guides/ip_pipeline_ug/img/ip_pipelines_2.svg @@ -0,0 +1,997 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pipeline 1 + Table 1 + Route + Next Hop + Pipeline 2 + Table 2 + Key + MAC Address + Pipeline 1 + Route + Next Hop + Key + MAC Address + Table 1 + Table 2 + + diff --git a/doc/guides/ip_pipeline_ug/img/ip_pipelines_3.svg b/doc/guide= s/ip_pipeline_ug/img/ip_pipelines_3.svg new file mode 100644 index 0000000..1cf5413 --- /dev/null +++ b/doc/guides/ip_pipeline_ug/img/ip_pipelines_3.svg @@ -0,0 +1,826 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pipeline 1 + Pipeline 2 + Flow Table 1 + Flow Table 2 + Flow # + Flow # + Actions 2 + Actions 1 + Pipeline 1 + Flow Table 1 + Flow # + Actions 1 + Actions 2 + + diff --git a/doc/guides/ip_pipeline_ug/index.rst b/doc/guides/ip_pipeline= _ug/index.rst new file mode 100644 index 0000000..3e813cc --- /dev/null +++ b/doc/guides/ip_pipeline_ug/index.rst @@ -0,0 +1,38 @@ +.. BSD LICENSE + Copyright(c) 2015 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 FO= R + 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 AN= Y + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Internet Protocol (IP) Pipeline Application User Guide +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + +.. toctree:: + :maxdepth: 3 + :numbered: + + ip_pipeline_app diff --git a/doc/guides/ip_pipeline_ug/ip_pipeline_app.rst b/doc/guides/i= p_pipeline_ug/ip_pipeline_app.rst new file mode 100644 index 0000000..2e0ce22 --- /dev/null +++ b/doc/guides/ip_pipeline_ug/ip_pipeline_app.rst @@ -0,0 +1,1129 @@ +Internet Protocol (IP) Pipeline Application +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Application overview +-------------------- + +The *Internet Protocol (IP) Pipeline* application is intended to be a ve= hicle for rapid development of packet processing +applications running on multi-core CPUs. + +The application provides a library of reusable functional blocks called = pipelines. +These pipelines can be seen as prefabricated blocks that can be instanti= ated and inter-connected through packet queues +to create complete applications (super-pipelines). + +Pipelines are created and inter-connected through the application config= uration file. +By using different configuration files, different applications are effec= tively created, therefore this application +can be seen as an application generator. +The configuration of each pipeline can be updated at run-time through th= e application Command Line Interface (CLI). + +Main application components are: + +**A Library of reusable pipelines** + + * Each pipeline represents a functional block, e.g. flow classification= , firewall, routing, master, etc. + + * Each pipeline type can be instantiated several times in the same appl= ication, which each instance configured + separately and mapped to a single CPU core. + Each CPU core can run one or several pipeline instances, which can be= of same or different type. + + * Pipeline instances are inter-connected through packet queues (for pac= ket processing) and message queues + (for run-time configuration). + + * Pipelines are implemented using DPDK Packet Framework. + + * More pipeline types can always be built and added to the existing pip= eline types. + +**The Configuration file** + + * The configuration file defines the application structure. + By using different configuration files, different applications are cr= eated. + + * All the application resources are created and configured through the = application configuration file: + pipeline instances, buffer pools, links (i.e. network interfaces), ha= rdware device RX/TX queues, + software queues, traffic manager devices, EAL startup arguments, etc. + + * The configuration file syntax is =E2=80=9Cdefine by reference=E2=80=9D= , meaning that resources are defined as they are referenced. + First time a resource name is detected, it is registered with default= parameters. + Optionally, the resource parameters can be further refined through a = configuration file section dedicated to + that resource. + + * Command Line Interface (CLI) + +**Global CLI commands: link configuration, etc.** + + * Common pipeline CLI commands: ping (keep-alive), statistics, etc. + + * Pipeline type specific CLI commands: used to configure instances of s= pecific pipeline type. + These commands are registered with the application when the pipeline = type is registered. + For example, the commands for routing pipeline instances include: rou= te add, route delete, route list, etc. + + * CLI commands can be grouped into scripts that can be invoked at initi= alization and at runtime. + + +Rapid development +----------------- + +This application enables rapid development through quick connectivity of= standard components called pipelines. +These components are built using DPDK Packet Framework and encapsulate p= acket processing features at different levels: +ports, tables, actions, pipelines and complete applications. + +Pipeline instances are instantiated, configured and inter-connected thro= ugh low complexity configuration files loaded +during application initialization. +Each pipeline instance is mapped to a single CPU core, with each CPU cor= e able to run one or multiple pipeline +instances of same or different types. By loading a different configurati= on file, a different application is +effectively started. + + +Flexibility +----------- + +Each packet processing application is typically represented as a chain o= f functional stages which is often called +the functional pipeline of the application. +These stages are mapped to CPU cores to create chains of CPU cores (pipe= line model), clusters of CPU cores +(run-to-completion model) or chains of clusters of CPU cores (hybrid mod= el). + +This application allows all the above programming models. +By applying changes to the configuration file, the application provides = the flexibility to reshuffle its +building blocks in different ways until the configuration providing the = best performance is identified. + + +.. raw:: latex + + \newpage + + +Move pipelines around +~~~~~~~~~~~~~~~~~~~~~ + +The mapping of pipeline instances to CPU cores can be reshuffled through= the configuration file. +One or several pipeline instances can be mapped to the same CPU core. + +.. _figure_ip_pipelines_1: + +.. figure:: img/ip_pipelines_1.* + + Example of moving pipeline instances across different CPU cores + + +.. raw:: latex + + \newpage + +Move tables around +~~~~~~~~~~~~~~~~~~ + +There is some degree of flexibility for moving tables from one pipeline = instance to another. +Based on the configuration arguments passed to each pipeline instance in= the configuration file, specific tables +can be enabled or disabled. +This way, a specific table can be =E2=80=9Cmoved=E2=80=9D from pipeline = instance A to pipeline instance B by simply disabling its +associated functionality for pipeline instance A while enabling it for p= ipeline instance B. + +Due to requirement to have simple syntax for the configuration file, mov= ing tables across different pipeline +instances is not as flexible as the mapping of pipeline instances to CPU= cores, or mapping actions to pipeline tables. +Complete flexibility in moving tables from one pipeline to another could= be achieved through a complex pipeline +description language that would detail the structural elements of the pi= peline (ports, tables and actions) and +their connectivity, resulting in complex syntax for the configuration fi= le, which is not acceptable. +Good configuration file readability through simple syntax is preferred. + +*Example*: the IP routing pipeline can run the routing function only (wi= th ARP function run by a different +pipeline instance), or it can run both the routing and ARP functions as = part of the same pipeline instance. + + +.. _figure_ip_pipelines_2: + +.. figure:: img/ip_pipelines_2.* + + Example of moving tables across different pipeline instances + + +.. raw:: latex + + \newpage + +Move actions around +~~~~~~~~~~~~~~~~~~~ + +When it makes sense, packet processing actions can be moved from one pip= eline instance to another. +Based on the configuration arguments passed to each pipeline instance in= the configuration file, specific actions +can be enabled or disabled. +This way, a specific action can be "moved" from pipeline instance A to p= ipeline instance B by simply disabling its +associated functionality for pipeline instance A while enabling it for p= ipeline instance B. + +*Example*: The flow actions of accounting, traffic metering, application= identification, NAT, etc can be run as part +of the flow classification pipeline instance or split across several flo= w actions pipeline instances, depending on +the number of flow instances and their compute requirements. + + +.. _figure_ip_pipelines_3: + +.. figure:: img/ip_pipelines_3.* + + Example of moving actions across different tables and pipeline instan= ces + + +Performance +----------- + +Performance of the application is the highest priority requirement. +Flexibility is not provided at the expense of performance. + +The purpose of flexibility is to provide an incremental development meth= odology that allows monitoring the +performance evolution: + +* Apply incremental changes in the configuration (e.g. mapping on pipeli= ne instances to CPU cores) + in order to identify the configuration providing the best performance = for a given application; + +* Add more processing incrementally (e.g. by enabling more actions for s= pecific pipeline instances) until + the application is feature complete while checking the performance imp= act at each step. + + +Debug capabilities +------------------ + +The application provides a significant set of debug capabilities: + +* Command Line Interface (CLI) support for statistics polling: pipeline = instance ping (keep-alive checks), + pipeline instance statistics per input port/output port/table, link st= atistics, etc; + +* Logging: Turn on/off application log messages based on priority level; + +Running the application +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The application startup command line is:: + + ip_pipeline [-f CONFIG_FILE] [-s SCRIPT_FILE] -p PORT_MASK [-l LOG_LE= VEL] + +The application startup arguments are: + +``-f CONFIG_FILE`` + + * Optional: Yes + + * Default: ``./config/ip_pipeline.cfg`` + + * Argument: Path to the configuration file to be loaded by the applicat= ion. + Please refer to the :ref:`ip_pipeline_configuration_file` for details= on how to write the configuration file. + +``-s SCRIPT_FILE`` + + * Optional: Yes + + * Default: Not present + + * Argument: Path to the CLI script file to be run by the master pipelin= e at application startup. + No CLI script file will be run at startup of this argument is not pre= sent. + +``-p PORT_MASK`` + + * Optional: No + + * Default: N/A + + * Argument: Hexadecimal mask of NIC port IDs to be used by the applicat= ion. + First port enabled in this mask will be referenced as LINK0 as part o= f the application configuration file, + next port as LINK1, etc. + +``-l LOG_LEVEL`` + + * Optional: Yes + + * Default: 1 (High priority) + + * Argument: Log level to determine which application messages are to be= printed to standard output. + Available log levels are: 0 (None), 1 (High priority), 2 (Low priorit= y). + Only application messages whose priority is higher than or equal to t= he application log level will be printed. + + +Application stages +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + +Configuration +------------- + +During this stage, the application configuration file is parsed and its = content is loaded into the application data +structures. +In case of any configuration file parse error, an error message is displ= ayed and the application is terminated. +Please refer to the :ref:`ip_pipeline_configuration_file` for a descript= ion of the application configuration file format. + + +Configuration checking +---------------------- + +In the absence of any parse errors, the loaded content of application da= ta structures is checked for overall consistency. +In case of any configuration check error, an error message is displayed = and the application is terminated. + + +Initialization +-------------- + +During this stage, the application resources are initialized and the han= dles to access them are saved into the +application data structures. +In case of any initialization error, an error message is displayed and t= he application is terminated. + +The typical resources to be initialized are: pipeline instances, buffer = pools, links (i.e. network interfaces), +hardware device RX/TX queues, software queues, traffic management device= s, etc. + + +.. _ip_pipeline_runtime: + +Run-time +-------- + +Each CPU core runs the pipeline instances assigned to it in time sharing= mode and in round robin order: + +1. *Packet processing task*: The pipeline run-time code is typically a p= acket *processing* task built on top of + DPDK Packet Framework rte_pipeline library, which reads bursts of pac= kets from the pipeline input ports, + performs table lookups and executes the identified actions for all ta= bles in the pipeline, with packet + eventually written to pipeline output ports or dropped. + +2. *Message handling task*: Each CPU core will also periodically execute= the *message handling* code of each + of the pipelines mapped to it. + The pipeline message handling code is processing the messages that ar= e pending in the pipeline input message + queues, which are typically sent by the master CPU core for the on-th= e-fly pipeline configuration: check + that pipeline is still alive (ping), add/delete entries in the pipeli= ne tables, get statistics, etc. + The frequency of executing the message handling code is usually much = smaller than the frequency of executing + the packet processing work. + +Please refer to the :ref:`ip_pipeline_pipeline_section` for more details= about the application pipeline module encapsulation. + +.. _ip_pipeline_configuration_file: + +Configuration file syntax +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +Syntax overview +--------------- + +The syntax of the configuration file is designed to be simple, which fav= ors readability. +The configuration file is parsed using the DPDK library librte_cfgfile, = which supports simple +`INI file format `__ for configur= ation files. + +As result, the configuration file is split into several sections, with e= ach section containing one or more entries. +The scope of each entry is its section, and each entry specifies a varia= ble that is assigned a specific value. +Any text after the ``;`` character is considered a comment and is theref= ore ignored. + +The following are application specific: number of sections, name of each= section, number of entries of each section, +name of the variables used for each section entry, the value format (e.g= . signed/unsigned integer, string, etc) +and range of each section entry variable. + +Generic example of configuration file section: + +.. code-block:: ini + + [] + + =3D + + ... + + =3D + + +Application resources present in the configuration file +------------------------------------------------------- + +.. _table_ip_pipelines_resource_name: + +.. tabularcolumns:: |p{4cm}|p{6cm}|p{6cm}| + +.. table:: Application resource names in the configuration file + + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Resource type | Format | Examples = | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D+ + | Pipeline | ``PIPELINE`` | ``PIPELINE= 0``, ``PIPELINE1`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Mempool | ``MEMPOOL`` | ``MEMPOOL0= ``, ``MEMPOOL1`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Link (network interface) | ``LINK`` | ``LINK0``,= ``LINK1`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Link RX queue | ``RXQ.`` | ``RXQ0.0``= , ``RXQ1.5`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Link TX queue | ``TXQ.`` | ``TXQ0.0``= , ``TXQ1.5`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Software queue | ``SWQ`` | ``SWQ0``, = ``SWQ1`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Traffic Manager | ``TM`` | ``TM0``, `= `TM1`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Source | ``SOURCE`` | ``SOURCE0`= `, ``SOURCE1`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Sink | ``SINK`` | ``SINK0``,= ``SINK1`` | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + | Message queue | ``MSGQ`` | ``MSGQ0``,= ``MSGQ1``, | + | | ``MSGQ-REQ-PIPELINE`` | ``MSGQ-REQ= -PIPELINE2``, ``MSGQ-RSP-PIPELINE2,`` | + | | ``MSGQ-RSP-PIPELINE`` | ``MSGQ-REQ= -CORE-s0c1``, ``MSGQ-RSP-CORE-s0c1`` | + | | ``MSGQ-REQ-CORE-`` | = | + | | ``MSGQ-RSP-CORE-`` | = | + +--------------------------+-----------------------------+-----------= --------------------------------------+ + +``LINK`` instances are created implicitly based on the ``PORT_MASK`` app= lication startup argument. +``LINK0`` is the first port enabled in the ``PORT_MASK``, port 1 is the = next one, etc. +The LINK ID is different than the DPDK PMD-level NIC port ID, which is t= he actual position in the bitmask mentioned above. +For example, if bit 5 is the first bit set in the bitmask, then ``LINK0`= ` is having the PMD ID of 5. +This mechanism creates a contiguous LINK ID space and isolates the confi= guration file against changes in the board +PCIe slots where NICs are plugged in. + +``RXQ``, ``TXQ`` and ``TM`` instances have the LINK ID as part of their = name. +For example, ``RXQ2.1``, ``TXQ2.1`` and ``TM2`` are all associated with = ``LINK2``. + + +Rules to parse the configuration file +------------------------------------- + +The main rules used to parse the configuration file are: + +1. Application resource name determines the type of resource based on th= e name prefix. + + *Example*: all software queues need to start with ``SWQ`` prefix, so = ``SWQ0`` and ``SWQ5`` are valid software + queue names. + +2. An application resource is defined by creating a configuration file s= ection with its name. + The configuration file section allows fine tuning on any of the resou= rce parameters. + Some resource parameters are mandatory, in which case it is required = to have them specified as part of the + section, while some others are optional, in which case they get assig= ned their default value when not present. + + *Example*: section ``SWQ0`` defines a software queue named SWQ0, whos= e parameters are detailed as part of this section. + +3. An application resource can also be defined by referencing it. + Referencing a resource takes place by simply using its name as part o= f the value assigned to a variable in any + configuration file section. + In this case, the resource is registered with all its parameters havi= ng their default values. + Optionally, a section with the resource name can be added to the conf= iguration file to fine tune some or all + of the resource parameters. + + *Example*: in section ``PIPELINE3``, variable ``pktq_in`` includes ``= SWQ5`` as part of its list, which results + in defining a software queue named ``SWQ5``; when there is no ``SWQ5`= ` section present in the configuration file, + ``SWQ5`` gets registered with default parameters. + + +.. _ip_pipeline_pipeline_section: + +PIPELINE section +---------------- + +.. _table_ip_pipelines_pipeline_section_1: + +.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Configuration file PIPELINE section (1/2) + + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + | Section | Description = | Optional | Range | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D+ + | type | Pipeline type. Defines the functionality to be = | NO | See "List | N/A | + | | executed. = | | of pipeline types" | | + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + | core | CPU core to run the current pipeline. = | YES | See "CPU Core | CPU socket 0, | + | | = | | notation" | core 0, | + | | = | | | hyper-thread 0 | + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + | pktq_in | Packet queues to serve as input ports for the = | YES | List of input | Empty list | + | | current pipeline instance. The acceptable packet = | | packet queue IDs | | + | | queue types are: ``RXQ``, ``SWQ``, ``TM`` and ``SOU= RCE``. | | | | + | | First device in this list is used as pipeline input= port | | | | + | | 0, second as pipeline input port 1, etc. = | | | | + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + | pktq_out | Packet queues to serve as output ports for the = | YES | List of output | Empty list | + | | current pipeline instance. The acceptable packet = | | packet queue IDs. | | + | | queue types are: ``TXQ``, ``SWQ``, ``TM`` and ``SIN= K``. | | | | + | | First device in this list is used as pipeline outpu= t | | | | + | | port 0, second as pipeline output port 1, etc. = | | | | + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + +.. _table_ip_pipelines_pipeline_section_2: + +.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Configuration file PIPELINE section (2/2) + + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + | Section | Description = | Optional | Range | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D+ + | msgq_in | Input message queues. These queues contain = | YES | List of message | Empty list | + | | request messages that need to be handled by the = | | queue IDs | | + | | current pipeline instance. The type and format of = | | | | + | | request messages is defined by the pipeline type. = | | | | + | | For each pipeline instance, there is an input = | | | | + | | message queue defined implicitly, whose name is: = | | | | + | | ``MSGQ-REQ-``. This message queue = | | | | + | | should not be mentioned as part of msgq_in list. = | | | | + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + | msgq_out | Output message queues. These queues are used by = | YES | List of message | Empty list | + | | the current pipeline instance to write response = | | queue IDs | | + | | messages as result of request messages being = | | | | + | | handled. The type and format of response = | | | | + | | messages is defined by the pipeline type. = | | | | + | | For each pipeline instance, there is an output = | | | | + | | message queue defined implicitly, whose name is: = | | | | + | | ``MSGQ-RSP-``. This message queue = | | | | + | | should not be mentioned as part of msgq_out list. = | | | | + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + | timer_period | Time period, measured in milliseconds, = | YES | milliseconds | 1 ms | + | | for handling the input message queues. = | | | | + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + | | Arguments to be passed to the current pipeline = | Depends on | Depends on | Depends on | + | | instance. Format of the arguments, their type, = | pipeline type | pipeline type | pipeline type | + | | whether each argument is optional or mandatory = | | | | + | | and its default value (when optional) are defined = | | | | + | | by the pipeline type. = | | | | + | | The value of the arguments is applicable to the = | | | | + | | current pipeline instance only. = | | | | + +---------------+----------------------------------------------------= -------+---------------+------------------------+----------------+ + + +.. raw:: latex + + \newpage + + +CPU core notation +~~~~~~~~~~~~~~~~~ + +The CPU Core notation is:: + + ::=3D [s|S][c|C][h|H] + +For example:: + + CPU socket 0, core 0, hyper-thread 0: 0, c0, s0c0 + + CPU socket 0, core 0, hyper-thread 1: 0h, c0h, s0c0h + + CPU socket 3, core 9, hyper-thread 1: s3c9h + + +MEMPOOL section +--------------- + +.. _table_ip_pipelines_mempool_section: + +.. tabularcolumns:: |p{2.5cm}|p{6cm}|p{1.5cm}|p{1.5cm}|p{3cm}| + +.. table:: Configuration file MEMPOOL section + + +---------------+-----------------------------------------------+----= ------+----------+---------------------------+ + | Section | Description | Opt= ional | Type | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | buffer_size | Buffer size (in bytes) for the current | YES= | uint32_t | 2048 | + | | buffer pool. | = | | + sizeof(struct rte_mbuf) | + | | | = | | + HEADROOM | + +---------------+-----------------------------------------------+----= ------+----------+---------------------------+ + | pool_size | Number of buffers in the current buffer pool. | YES= | uint32_t | 32K | + +---------------+-----------------------------------------------+----= ------+----------+---------------------------+ + | cache_size | Per CPU thread cache size (in number of | YES= | uint32_t | 256 | + | | buffers) for the current buffer pool. | = | | | + +---------------+-----------------------------------------------+----= ------+----------+---------------------------+ + | cpu | CPU socket ID where to allocate memory for | YES= | uint32_t | 0 | + | | the current buffer pool. | = | | | + +---------------+-----------------------------------------------+----= ------+----------+---------------------------+ + + +LINK section +------------ + +.. _table_ip_pipelines_link_section: + +.. tabularcolumns:: |p{3cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{2cm}| + +.. table:: Configuration file LINK section + + +-----------------+----------------------------------------------+---= -------+----------+-------------------+ + | Section entry | Description | Op= tional | Type | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D+ + | arp_q | NIC RX queue where ARP packets should | YE= S | 0 .. 127 | 0 (default queue) | + | | be filtered. | = | | | + +-----------------+----------------------------------------------+---= -------+----------+-------------------+ + | tcp_syn_local_q | NIC RX queue where TCP packets with SYN | YE= S | 0 .. 127 | 0 (default queue) | + | | flag should be filtered. | = | | | + +-----------------+----------------------------------------------+---= -------+----------+-------------------+ + | ip_local_q | NIC RX queue where IP packets with local | YE= S | 0 .. 127 | 0 (default queue) | + | | destination should be filtered. | = | | | + | | When TCP, UDP and SCTP local queues are | = | | | + | | defined, they take higher priority than this | = | | | + | | queue. | = | | | + +-----------------+----------------------------------------------+---= -------+----------+-------------------+ + | tcp_local_q | NIC RX queue where TCP packets with local | YE= S | 0 .. 127 | 0 (default queue) | + | | destination should be filtered. | = | | | + +-----------------+----------------------------------------------+---= -------+----------+-------------------+ + | udp_local_q | NIC RX queue where TCP packets with local | YE= S | 0 .. 127 | 0 (default queue) | + | | destination should be filtered. | = | | | + +-----------------+----------------------------------------------+---= -------+----------+-------------------+ + | sctp_local_q | NIC RX queue where TCP packets with local | YE= S | 0 .. 127 | 0 (default queue) | + | | destination should be filtered. | = | | | + +-----------------+----------------------------------------------+---= -------+----------+-------------------+ + | promisc | Indicates whether current link should be | YE= S | YES/NO | YES | + | | started in promiscuous mode. | = | | | + +-----------------+----------------------------------------------+---= -------+----------+-------------------+ + + +RXQ section +----------- + +.. _table_ip_pipelines_rxq_section: + +.. tabularcolumns:: |p{3cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{2cm}| + +.. table:: Configuration file RXQ section + + +---------------+--------------------------------------------+-------= ---+----------+---------------+ + | Section | Description | Option= al | Type | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | mempool | Mempool to use for buffer allocation for | YES = | uint32_t | MEMPOOL0 | + | | current NIC RX queue. The mempool ID has | = | | | + | | to be associated with a valid instance | = | | | + | | defined in the mempool entry of the global | = | | | + | | section. | = | | | + +---------------+--------------------------------------------+-------= ---+----------+---------------+ + | Size | NIC RX queue size (number of descriptors) | YES = | uint32_t | 128 | + +---------------+--------------------------------------------+-------= ---+----------+---------------+ + | burst | Read burst size (number of descriptors) | YES = | uint32_t | 32 | + +---------------+--------------------------------------------+-------= ---+----------+---------------+ + + +TXQ section +----------- + +.. _table_ip_pipelines_txq_section: + +.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{2cm}|p{1.5cm}| + +.. table:: Configuration file TXQ section + + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | Section | Description | Opti= onal | Type | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D+ + | size | NIC TX queue size (number of descriptors) | YES = | uint32_t | 512 | + | | | = | power of 2 | | + | | | = | > 0 | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | burst | Write burst size (number of descriptors) | YES = | uint32_t | 32 | + | | | = | power of 2 | | + | | | = | 0 < burst < size | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | dropless | When dropless is set to NO, packets can be | YES = | YES/NO | NO | + | | dropped if not enough free slots are | = | | | + | | currently available in the queue, so the | = | | | + | | write operation to the queue is non- | = | | | + | | blocking. | = | | | + | | When dropless is set to YES, packets cannot | = | | | + | | be dropped if not enough free slots are | = | | | + | | currently available in the queue, so the | = | | | + | | write operation to the queue is blocking, as | = | | | + | | the write operation is retried until enough | = | | | + | | free slots become available and all the | = | | | + | | packets are successfully written to the | = | | | + | | queue. | = | | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | n_retries | Number of retries. Valid only when dropless | YES = | uint32_t | 0 | + | | is set to YES. When set to 0, it indicates | = | | | + | | unlimited number of retries. | = | | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + + +SWQ section +----------- + +.. _table_ip_pipelines_swq_section: + +.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Configuration file SWQ section + + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | Section | Description | Opti= onal | Type | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D+ + | size | Queue size (number of packets) | YES = | uint32_t | 256 | + | | | = | power of 2 | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | burst_read | Read burst size (number of packets) | YES = | uint32_t | 32 | + | | | = | power of 2 | | + | | | = | 0 < burst < size | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | burst_write | Write burst size (number of packets) | YES = | uint32_t | 32 | + | | | = | power of 2 | | + | | | = | 0 < burst < size | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | dropless | When dropless is set to NO, packets can be | YES = | YES/NO | NO | + | | dropped if not enough free slots are | = | | | + | | currently available in the queue, so the | = | | | + | | write operation to the queue is non- | = | | | + | | blocking. | = | | | + | | When dropless is set to YES, packets cannot | = | | | + | | be dropped if not enough free slots are | = | | | + | | currently available in the queue, so the | = | | | + | | write operation to the queue is blocking, as | = | | | + | | the write operation is retried until enough | = | | | + | | free slots become available and all the | = | | | + | | packets are successfully written to the | = | | | + | | queue. | = | | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | n_retries | Number of retries. Valid only when dropless | YES = | uint32_t | 0 | + | | is set to YES. When set to 0, it indicates | = | | | + | | unlimited number of retries. | = | | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + | cpu | CPU socket ID where to allocate memory | YES = | uint32_t | 0 | + | | for this SWQ. | = | | | + +---------------+----------------------------------------------+-----= -----+------------------+---------------+ + + +TM section +---------- + +.. _table_ip_pipelines_tm_section: + +.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Configuration file TM section + + +---------------+---------------------------------------------+------= ----+----------+---------------+ + | Section | Description | Optio= nal | Type | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | Cfg | File name to parse for the TM configuration | YES = | string | tm_profile | + | | to be applied. The syntax of this file is | = | | | + | | described in the examples/qos_sched DPDK | = | | | + | | application documentation. | = | | | + +---------------+---------------------------------------------+------= ----+----------+---------------+ + | burst_read | Read burst size (number of packets) | YES = | uint32_t | 64 | + +---------------+---------------------------------------------+------= ----+----------+---------------+ + | burst_write | Write burst size (number of packets) | YES = | uint32_t | 32 | + +---------------+---------------------------------------------+------= ----+----------+---------------+ + + +SOURCE section +-------------- + +.. _table_ip_pipelines_source_section: + +.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{2cm}| + +.. table:: Configuration file SOURCE section + + +---------------+---------------------------------------+----------+-= ---------+---------------+ + | Section | Description | Optional | = Type | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | Mempool | Mempool to use for buffer allocation. | YES | = uint32_t | MEMPOOL0 | + +---------------+---------------------------------------+----------+-= ---------+---------------+ + | Burst | Read burst size (number of packets) | | = uint32_t | 32 | + +---------------+---------------------------------------+----------+-= ---------+---------------+ + + +SINK section +------------ + +Currently, there are no parameters to be passed to a sink device, so +SINK section is not allowed. + +MSGQ section +------------ + +.. _table_ip_pipelines_msgq_section: + +.. tabularcolumns:: |p{2.5cm}|p{7cm}|p{1.5cm}|p{1.5cm}|p{1.5cm}| + +.. table:: Configuration file MSGQ section + + +---------+--------------------------------------------+----------+--= ----------+---------------+ + | Section | Description | Optional | T= ype | Default value | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | size | Queue size (number of packets) | YES | u= int32_t | 64 | + | | | | != =3D 0 | | + | | | | p= ower of 2 | | + +---------+--------------------------------------------+----------+--= ----------+---------------+ + | cpu | CPU socket ID where to allocate memory for | YES | u= int32_t | 0 | + | | the current queue. | | = | | + +---------+--------------------------------------------+----------+--= ----------+---------------+ + + +EAL section +----------- + +The application generates the EAL parameters rather than reading them fr= om the command line. + +The CPU core mask parameter is generated based on the core entry of all = PIPELINE sections. +All the other EAL parameters can be set from this section of the applica= tion configuration file. + + +Library of pipeline types +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +Pipeline module +--------------- + +A pipeline is a self-contained module that implements a packet processin= g function and is typically implemented on +top of the DPDK Packet Framework *librte_pipeline* library. +The application provides a run-time mechanism to register different pipe= line types. + +Depending on the required configuration, each registered pipeline type (= pipeline class) is instantiated one or +several times, with each pipeline instance (pipeline object) assigned to= one of the available CPU cores. +Each CPU core can run one or more pipeline instances, which might be of = same or different types. +For more information of the CPU core threading model, please refer to th= e :ref:`ip_pipeline_runtime` section. + + +Pipeline type +~~~~~~~~~~~~~ + +Each pipeline type is made up of a back-end and a front-end. The back-en= d represents the packet processing engine +of the pipeline, typically implemented using the DPDK Packet Framework l= ibraries, which reads packets from the +input packet queues, handles them and eventually writes them to the outp= ut packet queues or drops them. +The front-end represents the run-time configuration interface of the pip= eline, which is exposed as CLI commands. +The front-end communicates with the back-end through message queues. + +.. _table_ip_pipelines_back_end: + +.. tabularcolumns:: |p{1cm}|p{2cm}|p{12cm}| + +.. table:: Pipeline back-end + + +------------+------------------+------------------------------------= --------------------------------+ + | Field name | Field type | Description = | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+ + | f_init | Function pointer | Function to initialize the back-end= of the current pipeline | + | | | instance. Typical work implemented = by this function for the | + | | | current pipeline instance: = | + | | | Memory allocation; = | + | | | Parse the pipeline type specific ar= guments; | + | | | Initialize the pipeline input ports= , output ports and tables, | + | | | interconnect input ports to tables;= | + | | | Set the message handlers. = | + +------------+------------------+------------------------------------= --------------------------------+ + | f_free | Function pointer | Function to free the resources allo= cated by the back-end of the | + | | | current pipeline instance. = | + +------------+------------------+------------------------------------= --------------------------------+ + | f_run | Function pointer | Set to NULL for pipelines implement= ed using the DPDK library | + | | | librte_pipeline (typical case), and= to non-NULL otherwise. This | + | | | mechanism is made available to supp= ort quick integration of | + | | | legacy code. = | + | | | This function is expected to provid= e the packet processing | + | | | related code to be called as part o= f the CPU thread dispatch | + | | | loop, so this function is not allow= ed to contain an infinite loop. | + +------------+------------------+------------------------------------= --------------------------------+ + | f_timer | Function pointer | Function to read the pipeline input= message queues, handle | + | | | the request messages, create respon= se messages and write | + | | | the response queues. The format of = request and response | + | | | messages is defined by each pipelin= e type, with the exception | + | | | of some requests which are mandator= y for all pipelines (e.g. | + | | | ping, statistics). = | + +------------+------------------+------------------------------------= --------------------------------+ + | f_track | Function pointer | See section Tracking pipeline outpu= t port to physical link | + +------------+------------------+------------------------------------= --------------------------------+ + + +.. _table_ip_pipelines_front_end: + +.. tabularcolumns:: |p{1cm}|p{2cm}|p{12cm}| + +.. table:: Pipeline front-end + + +------------+-----------------------+-------------------------------= ------------------------------------+ + | Field name | Field type | Description = | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D+ + | f_init | Function pointer | Function to initialize the fro= nt-end of the current pipeline | + | | | instance. = | + +------------+-----------------------+-------------------------------= ------------------------------------+ + | f_free | Function pointer | Function to free the resources= allocated by the front-end of | + | | | the current pipeline instance.= | + +------------+-----------------------+-------------------------------= ------------------------------------+ + | cmds | Array of CLI commands | Array of CLI commands to be re= gistered to the application CLI | + | | | for the current pipeline type.= Even though the CLI is executed | + | | | by a different pipeline (typic= ally, this is the master pipeline), | + | | | from modularity perspective is= more efficient to keep the | + | | | message client side (part of t= he front-end) together with the | + | | | message server side (part of t= he back-end). | + +------------+-----------------------+-------------------------------= ------------------------------------+ + + +Tracking pipeline output port to physical link +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each pipeline instance is a standalone block that does not have visibili= ty into the other pipeline instances or +the application-level pipeline inter-connectivity. +In some cases, it is useful for a pipeline instance to get application l= evel information related to pipeline +connectivity, such as to identify the output link (e.g. physical NIC por= t) where one of its output ports connected, +either directly or indirectly by traversing other pipeline instances. + +Tracking can be successful or unsuccessful. +Typically, tracking for a specific pipeline instance is successful when = each one of its input ports can be mapped +to a single output port, meaning that all packets read from the current = input port can only go out on a single +output port. +Depending on the pipeline type, some exceptions may be allowed: a small = portion of the packets, considered exception +packets, are sent out on an output port that is pre-configured for this = purpose. + +For pass-through pipeline type, the tracking is always successful. +For pipeline types as flow classification, firewall or routing, the trac= king is only successful when the number of +output ports for the current pipeline instance is 1. + +This feature is used by the IP routing pipeline for adding/removing impl= icit routes every time a link is brought +up/down. + + +Table copies +~~~~~~~~~~~~ + +Fast table copy: pipeline table used by pipeline for the packet processi= ng task, updated through messages, table +data structures are optimized for lookup operation. + +Slow table copy: used by the configuration layer, typically updated thro= ugh CLI commands, kept in sync with the fast +copy (its update triggers the fast copy update). +Required for executing advanced table queries without impacting the pack= et processing task, therefore the slow copy +is typically organized using different criteria than the fast copy. + +Examples: + +* Flow classification: Search through current set of flows (e.g. list al= l flows with a specific source IP address); + +* Firewall: List rules in descending order of priority; + +* Routing table: List routes sorted by prefix depth and their type (loca= l, remote, default); + +* ARP: List entries sorted per output interface. + + +Packet meta-data +~~~~~~~~~~~~~~~~ + +Packet meta-data field offsets provided as argument to pipeline instance= s are essentially defining the data structure +for the packet meta-data used by the current application use-case. +It is very useful to put it in the configuration file as a comment in or= der to facilitate the readability of the +configuration file. + +The reason to use field offsets for defining the data structure for the = packet meta-data is due to the C language +limitation of not being able to define data structures at run-time. +Feature to consider: have the configuration file parser automatically ge= nerate and print the data structure defining +the packet meta-data for the current application use-case. + +Packet meta-data typically contains: + +1. Pure meta-data: intermediate data per packet that is computed interna= lly, passed between different tables of + the same pipeline instance (e.g. lookup key for the ARP table is obta= ined from the routing table), or between + different pipeline instances (e.g. flow ID, traffic metering color, e= tc); + +2. Packet fields: typically, packet header fields that are read directly= from the packet, or read from the packet + and saved (duplicated) as a working copy at a different location with= in the packet meta-data (e.g. Diffserv + 5-tuple, IP destination address, etc). + +Several strategies are used to design the packet meta-data, as described= in the next subsections. + + +Store packet meta-data in a different cache line as the packet headers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This approach is able to support protocols with variable header length, = like MPLS, where the offset of IP header +from the start of the packet (and, implicitly, the offset of the IP head= er in the packet buffer) is not fixed. +Since the pipelines typically require the specification of a fixed offse= t to the packet fields (e.g. Diffserv +5-tuple, used by the flow classification pipeline, or the IP destination= address, used by the IP routing pipeline), +the workaround is to have the packet RX pipeline copy these fields at fi= xed offsets within the packet meta-data. + +As this approach duplicates some of the packet fields, it requires acces= sing more cache lines per packet for filling +in selected packet meta-data fields (on RX), as well as flushing selecte= d packet meta-data fields into the +packet (on TX). + +Example: + +.. code-block:: ini + + + ; struct app_pkt_metadata { + ; uint32_t ip_da; + ; uint32_t hash; + ; uint32_t flow_id; + ; uint32_t color; + ; } __attribute__((__packed__)); + ; + + [PIPELINE1] + ; Packet meta-data offsets + ip_da_offset =3D 0; Used by: routing + hash_offset =3D 4; Used by: RX, flow classification + flow_id_offset =3D 8; Used by: flow classification, flow actions + color_offset =3D 12; Used by: flow actions, routing + + +.. raw:: latex + + \newpage + +Overlay the packet meta-data in the same cache line with the packet head= ers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^= ^^^^ + +This approach is minimizing the number of cache line accessed per packet= by storing the packet metadata in the +same cache line with the packet headers. +To enable this strategy, either some headroom is reserved for meta-data = at the beginning of the packet headers +cache line (e.g. if 16 bytes are needed for meta-data, then the packet h= eadroom can be set to 128+16 bytes, so +that NIC writes the first byte of the packet at offset 16 from the start= of the first packet cache line), +or meta-data is reusing the space of some packet headers that are discar= ded from the packet (e.g. input Ethernet +header). + +Example: + +.. code-block:: ini + + ; struct app_pkt_metadata { + ; uint8_t headroom[RTE_PKTMBUF_HEADROOM]; /* 128 bytes (default)= */ + ; union { + ; struct { + ; struct ether_hdr ether; /* 14 bytes */ + ; struct qinq_hdr qinq; /* 8 bytes */ + ; }; + ; struct { + ; uint32_t hash; + ; uint32_t flow_id; + ; uint32_t color; + ; }; + ; }; + ; struct ipv4_hdr ip; /* 20 bytes */ + ; } __attribute__((__packed__)); + ; + [PIPELINE2] + ; Packet meta-data offsets + qinq_offset =3D 142; Used by: RX, flow classification + ip_da_offset =3D 166; Used by: routing + hash_offset =3D 128; Used by: RX, flow classification + flow_id_offset =3D 132; Used by: flow classification, flow actions + color_offset =3D 136; Used by: flow actions, routing + + +List of pipeline types +---------------------- + +.. _table_ip_pipelines_types: + +.. tabularcolumns:: |p{3cm}|p{5cm}|p{4cm}|p{4cm}| + +.. table:: List of pipeline types provided with the application + + +-----------------------+-----------------------------+--------------= ---------+------------------------------------------+ + | Name | Table(s) | Actions = | Messages | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | Pass-through | Passthrough | 1. Pkt metada= ta build | 1. Ping | + | | | 2. Flow hash = | 2. Stats | + | Note: depending on | | 3. Pkt checks= | | + | port type, can be | | 4. Load balan= cing | | + | used for RX, TX, IP | | = | | + | fragmentation, IP | | = | | + | reassembly or Traffic | | = | | + | Management | | = | | + +-----------------------+-----------------------------+--------------= ---------+------------------------------------------+ + | Flow classification | Exact match | 1. Flow ID = | 1. Ping | + | | | = | | + | | * Key =3D byte array | 2. Flow sta= ts | 2. Stats | + | | (source: pkt metadata) | 3. Metering = | 3. Flow stats | + | | * Data =3D action dependent | 4. Network = Address | 4. Action stats | + | | | 5. Translatio= n (NAT) | 5. Flow add/ update/ delete | + | | | = | 6. Default flow add/ update/ delete | + | | | = | 7. Action update | + +-----------------------+-----------------------------+--------------= ---------+------------------------------------------+ + | Flow actions | Array | 1. Flow stats= | 1. Ping | + | | | = | | + | | * Key =3D Flow ID | 2. Metering= | 2. Stats | + | | (source: pkt metadata) | 3. Network Ad= dress | 3. Action stats | + | | * Data =3D action dependent | 4. Translat= ion (NAT) | 4. Action update | + +-----------------------+-----------------------------+--------------= ---------+------------------------------------------+ + | Firewall | ACL | 1. Allow/Drop= | 1. Ping | + | | | = | | + | | * Key =3D n-tuple | = | 2. Stats | + | | (source: pkt headers) | = | 3. Rule add/ update/ delete | + | | * Data =3D none | = | 4. Default rule add/ update/ delete | + +-----------------------+-----------------------------+--------------= ---------+------------------------------------------+ + | IP routing | LPM (IPv4 or IPv6, | 1. TTL decrem= ent and | 1. Ping | + | | depending on pipeline type) | 2. IPv4 check= sum | 2. Stats | + | | | = | | + | | * Key =3D IP destination | 3. update = | 3. Route add/ update/ delete | + | | (source: pkt metadata) | 4. Header = | 4. Default route add/ update/ delete | + | | * Data =3D Dependent on | 5. encapsul= ation | 5. ARP entry add/ update/ delete | + | | actions and next hop | 6. (based on = next hop | 6. Default ARP entry add/ update/ delete | + | | type | 7. type) = | | + | | | = | | + | | Hash table (for ARP, only | = | | + | | | = | | + | | when ARP is enabled) | = | | + | | | = | | + | | * Key =3D (Port ID, | = | | + | | next hop IP address) | = | | + | | (source: pkt meta-data) | = | | + | | * Data: MAC address | = | | + +-----------------------+-----------------------------+--------------= ---------+------------------------------------------+ + + + +Command Line Interface (CLI) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +Global CLI commands +------------------- + +.. _table_ip_pipelines_cli_commands: + +.. tabularcolumns:: |p{3cm}|p{6cm}|p{6cm}| + +.. table:: Global CLI commands + + +---------+---------------------------------------+------------------= --------------------------+ + | Command | Description | Syntax = | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | run | Run CLI commands script file. | run = | + | | | =3D path t= o file with CLI commands to | + | | | execute = | + +---------+---------------------------------------+------------------= --------------------------+ + | quit | Gracefully terminate the application. | quit = | + +---------+---------------------------------------+------------------= --------------------------+ + + +CLI commands for link configuration +----------------------------------- + +.. _table_ip_pipelines_runtime_config: + +.. tabularcolumns:: |p{3cm}|p{6cm}|p{6cm}| + +.. table:: List of run-time configuration commands for link configuratio= n + + +-------------+--------------------+---------------------------------= -----------+ + | Command | Description | Syntax = | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D+ + | link config | Link configuration | link config | + +-------------+--------------------+---------------------------------= -----------+ + | link up | Link up | link up = | + +-------------+--------------------+---------------------------------= -----------+ + | link down | Link down | link down = | + +-------------+--------------------+---------------------------------= -----------+ + | link ls | Link list | link ls = | + +-------------+--------------------+---------------------------------= -----------+ + + +CLI commands common for all pipeline types +------------------------------------------ + +.. _table_ip_pipelines_mandatory: + +.. tabularcolumns:: |p{3cm}|p{6cm}|p{6cm}| + +.. table:: CLI commands mandatory for all pipelines + + +--------------------+-----------------------------------------------= -------+----------------------------------------------+ + | Command | Description = | Syntax | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | ping | Check whether specific pipeline instance is al= ive. | p ping | + | | The master pipeline sends a ping request = | | + | | message to given pipeline instance and waits f= or | | + | | a response message back. = | | + | | Timeout message is displayed when the response= | | + | | message is not received before the timer = | | + | | expires. = | | + +--------------------+-----------------------------------------------= -------+----------------------------------------------+ + | stats | Display statistics for specific pipeline input= port, | p stats port in | + | | output port or table. = | p stats port out | + | | = | p stats table | + +--------------------+-----------------------------------------------= -------+----------------------------------------------+ + | input port enable | Enable given input port for specific pipeline = | p port in enable | + | | instance. = | | + +--------------------+-----------------------------------------------= -------+----------------------------------------------+ + | input port disable | Disable given input port for specific pipeline= | p port in disable | + | | instance. = | | + +--------------------+-----------------------------------------------= -------+----------------------------------------------+ + +Pipeline type specific CLI commands +----------------------------------- + +The pipeline specific CLI commands are part of the pipeline type front-e= nd. diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_u= g/index.rst index 50dac0f..5777480 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -67,7 +67,6 @@ Sample Applications User Guide vmdq_dcb_forwarding vhost netmap_compatibility - internet_proto_ip_pipeline test_pipeline dist_app vm_power_management diff --git a/doc/guides/sample_app_ug/internet_proto_ip_pipeline.rst b/do= c/guides/sample_app_ug/internet_proto_ip_pipeline.rst deleted file mode 100644 index 257ce3f..0000000 --- a/doc/guides/sample_app_ug/internet_proto_ip_pipeline.rst +++ /dev/null @@ -1,135 +0,0 @@ -.. 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 FO= R - 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 AN= Y - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Internet Protocol (IP) Pipeline Sample Application -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D - -The Internet Protocol (IP) Pipeline application illustrates the use of t= he DPDK Packet Framework tool suite. -The DPDK pipeline methodology is used to implement functional blocks suc= h as -packet RX, packet TX, flow classification, firewall, -routing, IP fragmentation, IP reassembly, etc -which are then assigned to different CPU cores and connected together to= create complex multi-core applications. - -Overview --------- - -The pipelines for packet RX, packet TX, flow classification, firewall, r= outing, IP fragmentation, IP reassembly, management, etc -are instantiated and different CPU cores and connected together through = software queues. -One of the CPU cores can be designated as the management core to run a C= ommand Line Interface (CLI) to add entries to each table -(e.g. flow table, firewall rule database, routing table, Address Resolut= ion Protocol (ARP) table, and so on), -bring NIC ports up or down, and so on. - -Compiling the Application -------------------------- - -#. Go to the examples directory: - - .. code-block:: console - - export RTE_SDK=3D/path/to/rte_sdk - cd ${RTE_SDK}/examples/ip_pipeline - -#. Set the target (a default target is used if not specified): - - .. code-block:: console - - export RTE_TARGET=3Dx86_64-native-linuxapp-gcc - -#. Build the application: - - .. code-block:: console - - make - -Running the Sample Code ------------------------ - -The application execution command line is: - -.. code-block:: console - - ./ip_pipeline [EAL options] -- -p PORTMASK [-f CONFIG_FILE] - -The number of ports in the PORTMASK can be either 2 or 4. - -The config file assigns functionality to the CPU core by deciding the pi= peline type to run on each CPU core -(e.g. master, RX, flow classification, firewall, routing, IP fragmentati= on, IP reassembly, TX) and -also allows creating complex topologies made up of CPU cores by intercon= necting the CPU cores through SW queues. - -Once the application is initialized, the CLI is available for populating= the application tables, -bringing NIC ports up or down, and so on. - -The flow classification pipeline implements the flow table by using a la= rge (multi-million entry) hash table with a 16-byte key size. -The lookup key is the IPv4 5-tuple, which is extracted from the input pa= cket by the packet RX pipeline and -saved in the packet meta-data, has the following format: - - [source IP address, destination IP address, L4 protocol, L4 protocol= source port, L4 protocol destination port] - -The firewall pipeline implements the rule database using an ACL table. - -The routing pipeline implements an IP routing table by using an LPM IPv4= table and -an ARP table by using a hash table with an 8-byte key size. -The IP routing table lookup provides the output interface ID and the nex= t hop IP address, -which are stored in the packet meta-data, then used as the lookup key in= to the ARP table. -The ARP table lookup provides the destination MAC address to be used for= the output packet. -The action for the default entry of both the IP routing table and the AR= P table is packet drop. - -The following CLI operations are available: - -* Enable/disable NIC ports (RX pipeline) - -* Add/delete/list flows (flow classification pipeline) - -* Add/delete/list firewall rules (firewall pipeline) - -* Add/delete/list routes (routing pipeline) - -* Add/delete/list ARP entries (routing pipeline) - -In addition, there are two special commands: - -* flow add all: - Populate the flow classification table with 16 million flows - (by iterating through the last three bytes of the destination IP add= ress). - These flows are not displayed when using the flow print command. - When this command is used, the following traffic profile must be use= d to have flow table lookup hits for all input packets. - TCP/IPv4 packets with: - - * destination IP address =3D A.B.C.D with A fixed to 0 and B,C,D r= andom - - * source IP address fixed to 0 - - * source TCP port fixed to 0 - - * destination TCP port fixed to 0 - -* run cmd_file_path: Read CLI commands from an external file and run t= hem one by one. - -The full list of the available CLI commands can be displayed by pressing= the TAB key while the application is running. --=20 1.8.1.4