.. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2015-2018 Intel Corporation. Internet Protocol (IP) Pipeline Application =========================================== Application overview -------------------- The *Internet Protocol (IP) Pipeline* application is intended to be a vehicle for rapid development of packet processing applications on multi-core CPUs. Following OpenFlow and P4 design principles, the application can be used to create functional blocks called pipelines out of input/output ports, tables and actions in a modular way. Multiple pipelines can be inter-connected through packet queues to create complete applications (super-pipelines). The pipelines are mapped to application threads, with each pipeline executed by a single thread and each thread able to run one or several pipelines. The possibilities of creating pipelines out of ports, tables and actions, connecting multiple pipelines together and mapping the pipelines to execution threads are endless, therefore this application can be seen as a true application generator. Pipelines are created and managed through Command Line Interface (CLI): * Any standard TCP client (e.g. telnet, netcat, custom script, etc) is typically able to connect to the application, send commands through the network and wait for the response before pushing the next command. * All the application objects are created and managed through CLI commands: * 'Primitive' objects used to create pipeline ports: memory pools, links (i.e. network interfaces), SW queues, traffic managers, etc. * Action profiles: used to define the actions to be executed by pipeline input/output ports and tables. * Pipeline components: input/output ports, tables, pipelines, mapping of pipelines to execution threads. Running the application ----------------------- The application startup command line is:: ip_pipeline [EAL_ARGS] -- [-s SCRIPT_FILE] [-h HOST] [-p PORT] The application startup arguments are: ``-s SCRIPT_FILE`` * Optional: Yes * Default: Not present * Argument: Path to the CLI script file to be run at application startup. No CLI script file will run at startup if this argument is not present. ``-h HOST`` * Optional: Yes * Default: ``0.0.0.0`` * Argument: IP Address of the host running ip pipeline application to be used by remote TCP based client (telnet, netcat, etc.) for connection. ``-p PORT`` * Optional: Yes * Default: ``8086`` * Argument: TCP port number at which the ip pipeline is running. This port number should be used by remote TCP client (such as telnet, netcat, etc.) to connect to host application. Refer to *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. The following is an example command to run ip pipeline application configured for layer 2 forwarding: .. code-block:: console $ ./build/ip_pipeline -c 0x3 -- -s examples/route_ecmp.cli The application should start successfully and display as follows: .. code-block:: console EAL: Detected 40 lcore(s) EAL: Detected 2 NUMA nodes EAL: Multi-process socket /var/run/.rte_unix EAL: Probing VFIO support... EAL: PCI device 0000:02:00.0 on NUMA socket 0 EAL: probe driver: 8086:10fb net_ixgbe ... To run remote client (e.g. telnet) to communicate with the ip pipeline application: .. code-block:: console $ telnet 127.0.0.1 8086 When running a telnet client as above, command prompt is displayed: .. code-block:: console Trying 127.0.0.1... Connected to 127.0.0.1. Escape character is '^]'. Welcome to IP Pipeline! pipeline> Once application and telnet client start running, messages can be sent from client to application. At any stage, telnet client can be terminated using the quit command. Application stages ------------------ Initialization ~~~~~~~~~~~~~~ During this stage, EAL layer is initialised and application specific arguments are parsed. Furthermore, the data structures (i.e. linked lists) for application objects are initialized. In case of any initialization error, an error message is displayed and the application is terminated. .. _ip_pipeline_runtime: Run-time ~~~~~~~~ The master thread is creating and managing all the application objects based on CLI input. Each data plane thread runs one or several pipelines previously assigned to it in round-robin order. Each data plane thread executes two tasks in time-sharing mode: 1. *Packet processing task*: Process bursts of input packets read from the pipeline input ports. 2. *Message handling task*: Periodically, the data plane thread pauses the packet processing task and polls for request messages send by the master thread. Examples: add/remove pipeline to/from current data plane thread, add/delete rules to/from given table of a specific pipeline owned by the current data plane thread, read statistics, etc. Examples -------- .. _table_examples: .. tabularcolumns:: |p{3cm}|p{5cm}|p{4cm}|p{4cm}| .. table:: Pipeline examples provided with the application +-----------------------+----------------------+----------------+------------------------------------+ | Name | Table(s) | Actions | Messages | +=======================+======================+================+====================================+ | L2fwd | Stub | Forward | 1. Mempool create | | | | | 2. Link create | | Note: Implemented | | | 3. Pipeline create | | using pipeline with | | | 4. Pipeline port in/out | | a simple pass-through | | | 5. Pipeline table | | connection between | | | 6. Pipeline port in table | | input and output | | | 7. Pipeline enable | | ports. | | | 8. Pipeline table rule add | +-----------------------+----------------------+----------------+------------------------------------+ | Flow classification | Exact match | Forward | 1. Mempool create | | | | | 2. Link create | | | * Key = byte array | | 3. Pipeline create | | | (16 bytes) | | 4. Pipeline port in/out | | | * Offset = 278 | | 5. Pipeline table | | | * Table size = 64K | | 6. Pipeline port in table | | | | | 7. Pipeline enable | | | | | 8. Pipeline table rule add default | | | | | 9. Pipeline table rule add | +-----------------------+----------------------+----------------+------------------------------------+ | KNI | Stub | Forward | 1. Mempool create | | | | | 2. Link create | | | | | 3. Pipeline create | | | | | 4. Pipeline port in/out | | | | | 5. Pipeline table | | | | | 6. Pipeline port in table | | | | | 7. Pipeline enable | | | | | 8. Pipeline table rule add | +-----------------------+----------------------+----------------+------------------------------------+ | Firewall | ACL | Allow/Drop | 1. Mempool create | | | | | 2. Link create | | | * Key = n-tuple | | 3. Pipeline create | | | * Offset = 270 | | 4. Pipeline port in/out | | | * Table size = 4K | | 5. Pipeline table | | | | | 6. Pipeline port in table | | | | | 7. Pipeline enable | | | | | 8. Pipeline table rule add default | | | | | 9. Pipeline table rule add | +-----------------------+----------------------+----------------+------------------------------------+ | IP routing | LPM (IPv4) | Forward | 1. Mempool Create | | | | | 2. Link create | | | * Key = IP dest addr | | 3. Pipeline create | | | * Offset = 286 | | 4. Pipeline port in/out | | | * Table size = 4K | | 5. Pipeline table | | | | | 6. Pipeline port in table | | | | | 7. Pipeline enable | | | | | 8. Pipeline table rule add default | | | | | 9. Pipeline table rule add | +-----------------------+----------------------+----------------+------------------------------------+ | Equal-cost multi-path | LPM (IPv4) | Forward, | 1. Mempool Create | | routing (ECMP) | | load balance, | 2. Link create | | | * Key = IP dest addr | encap ether | 3. Pipeline create | | | * Offset = 286 | | 4. Pipeline port in/out | | | * Table size = 4K | | 5. Pipeline table (LPM) | | | | | 6. Pipeline table (Array) | | | | | 7. Pipeline port in table (LPM) | | | Array | | 8. Pipeline enable | | | | | 9. Pipeline table rule add default | | | * Key = Array index | | 10. Pipeline table rule add(LPM) | | | * Offset = 256 | | 11. Pipeline table rule add(Array) | | | * Size = 64K | | | | | | | | +-----------------------+----------------------+----------------+------------------------------------+ Command Line Interface (CLI) ---------------------------- Link ~~~~ Link configuration :: link dev |port rxq txq promiscuous on | off [rss ... ] Note: The PCI device name must be specified in the Domain:Bus:Device.Function format. Mempool ~~~~~~~ Mempool create :: mempool buffer pool cache cpu Software queue ~~~~~~~~~~~~~~ Create software queue :: swq size cpu Traffic manager ~~~~~~~~~~~~~~~ Add traffic manager subport profile :: tmgr subport profile pps qsize Add traffic manager pipe profile :: tmgr pipe profile Create traffic manager port :: tmgr rate spp fo mtu cpu Configure traffic manager subport :: tmgr subport profile Configure traffic manager pipe :: tmgr subport pipe from to profile Tap ~~~ Create tap port :: tap Kni ~~~ Create kni port :: kni link mempool [thread ] Cryptodev ~~~~~~~~~ Create cryptodev port :: cryptodev dev queue Action profile ~~~~~~~~~~~~~~ Create action profile for pipeline input port :: port in action profile [filter match | mismatch offset mask key port ] [balance offset mask port ... ] Create action profile for the pipeline table :: table action profile ipv4 | ipv6 offset fwd [balance offset mask outoffset ] [meter srtcm | trtcm tc stats none | pkts | bytes | both] [tm spp pps ] [encap ether | vlan | qinq | mpls | pppoe] [nat src | dst proto udp | tcp] [ttl drop | fwd stats none | pkts] [stats pkts | bytes | both] [sym_crypto cryptodev mempool_create mempool_init ] [time] Pipeline ~~~~~~~~ Create pipeline :: pipeline period offset_port_id cpu Create pipeline input port :: pipeline port in bsz link rxq | swq | tmgr | tap mempool mtu | kni | source mempool file bpp [action ] [disabled] Create pipeline output port :: pipeline port out bsz link txq | swq | tmgr | tap | kni | sink [file pkts ] Create pipeline table :: pipeline table match acl ipv4 | ipv6 offset size | array offset size | hash ext | lru key mask offset buckets size | lpm ipv4 | ipv6 offset size | stub [action ] Connect pipeline input port to table :: pipeline port in table Display statistics for specific pipeline input port, output port or table :: pipeline port in stats read [clear] pipeline port out stats read [clear] pipeline table stats read [clear] Enable given input port for specific pipeline instance :: pipeline port out disable Disable given input port for specific pipeline instance :: pipeline port out disable Add default rule to table for specific pipeline instance :: pipeline table rule add match default action fwd drop | port | meta | table Add rule to table for specific pipeline instance :: pipeline table rule add match acl priority ipv4 | ipv6 | array | hash raw | ipv4_5tuple | ipv6_5tuple | ipv4_addr | ipv6_addr | qinq | lpm ipv4 | ipv6 action fwd drop | port | meta | table [balance ... ] [meter tc0 meter policer g y r [tc1 meter policer g y r tc2 meter policer g y r tc3 meter policer g y r ]] [tm subport pipe ] [encap ether | vlan | qinq | mpls unicast | multicast label0