1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2015-2018 Intel Corporation.
4 Internet Protocol (IP) Pipeline Application
5 ===========================================
10 The *Internet Protocol (IP) Pipeline* application is intended to be a vehicle for rapid development of packet processing
11 applications on multi-core CPUs.
13 Following OpenFlow and P4 design principles, the application can be used to create functional blocks called pipelines out
14 of input/output ports, tables and actions in a modular way. Multiple pipelines can be inter-connected through packet queues
15 to create complete applications (super-pipelines).
17 The pipelines are mapped to application threads, with each pipeline executed by a single thread and each thread able to run
18 one or several pipelines. The possibilities of creating pipelines out of ports, tables and actions, connecting multiple
19 pipelines together and mapping the pipelines to execution threads are endless, therefore this application can be seen as
20 a true application generator.
22 Pipelines are created and managed through Command Line Interface (CLI):
24 * Any standard TCP client (e.g. telnet, netcat, custom script, etc) is typically able to connect to the application, send
25 commands through the network and wait for the response before pushing the next command.
27 * All the application objects are created and managed through CLI commands:
28 * 'Primitive' objects used to create pipeline ports: memory pools, links (i.e. network interfaces), SW queues, traffic managers, etc.
29 * Action profiles: used to define the actions to be executed by pipeline input/output ports and tables.
30 * Pipeline components: input/output ports, tables, pipelines, mapping of pipelines to execution threads.
32 Running the application
33 -----------------------
35 The application startup command line is::
37 ip_pipeline [EAL_ARGS] -- [-s SCRIPT_FILE] [-h HOST] [-p PORT]
39 The application startup arguments are:
45 * Default: Not present
47 * Argument: Path to the CLI script file to be run at application startup.
48 No CLI script file will run at startup if this argument is not present.
54 * Default: ``0.0.0.0``
56 * Argument: IP Address of the host running ip pipeline application to be used by
57 remote TCP based client (telnet, netcat, etc.) for connection.
65 * Argument: TCP port number at which the ip pipeline is running.
66 This port number should be used by remote TCP client (such as telnet, netcat, etc.) to connect to host application.
68 Refer to *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options.
70 The following is an example command to run ip pipeline application configured for layer 2 forwarding:
72 .. code-block:: console
74 $ ./build/ip_pipeline -c 0x3 -- -s examples/route_ecmp.cli
76 The application should start successfully and display as follows:
78 .. code-block:: console
80 EAL: Detected 40 lcore(s)
81 EAL: Detected 2 NUMA nodes
82 EAL: Multi-process socket /var/run/.rte_unix
83 EAL: Probing VFIO support...
84 EAL: PCI device 0000:02:00.0 on NUMA socket 0
85 EAL: probe driver: 8086:10fb net_ixgbe
88 To run remote client (e.g. telnet) to communicate with the ip pipeline application:
90 .. code-block:: console
92 $ telnet 127.0.0.1 8086
94 When running a telnet client as above, command prompt is displayed:
96 .. code-block:: console
99 Connected to 127.0.0.1.
100 Escape character is '^]'.
102 Welcome to IP Pipeline!
106 Once application and telnet client start running, messages can be sent from client to application.
107 At any stage, telnet client can be terminated using the quit command.
116 During this stage, EAL layer is initialised and application specific arguments are parsed. Furthermore, the data structures
117 (i.e. linked lists) for application objects are initialized. In case of any initialization error, an error message
118 is displayed and the application is terminated.
120 .. _ip_pipeline_runtime:
125 The master thread is creating and managing all the application objects based on CLI input.
127 Each data plane thread runs one or several pipelines previously assigned to it in round-robin order. Each data plane thread
128 executes two tasks in time-sharing mode:
130 1. *Packet processing task*: Process bursts of input packets read from the pipeline input ports.
132 2. *Message handling task*: Periodically, the data plane thread pauses the packet processing task and polls for request
133 messages send by the master thread. Examples: add/remove pipeline to/from current data plane thread, add/delete rules
134 to/from given table of a specific pipeline owned by the current data plane thread, read statistics, etc.
141 .. tabularcolumns:: |p{3cm}|p{5cm}|p{4cm}|p{4cm}|
143 .. table:: Pipeline examples provided with the application
145 +-----------------------+----------------------+----------------+------------------------------------+
146 | Name | Table(s) | Actions | Messages |
147 +=======================+======================+================+====================================+
148 | L2fwd | Stub | Forward | 1. Mempool create |
149 | | | | 2. Link create |
150 | Note: Implemented | | | 3. Pipeline create |
151 | using pipeline with | | | 4. Pipeline port in/out |
152 | a simple pass-through | | | 5. Pipeline table |
153 | connection between | | | 6. Pipeline port in table |
154 | input and output | | | 7. Pipeline enable |
155 | ports. | | | 8. Pipeline table rule add |
156 +-----------------------+----------------------+----------------+------------------------------------+
157 | Flow classification | Exact match | Forward | 1. Mempool create |
158 | | | | 2. Link create |
159 | | * Key = byte array | | 3. Pipeline create |
160 | | (16 bytes) | | 4. Pipeline port in/out |
161 | | * Offset = 278 | | 5. Pipeline table |
162 | | * Table size = 64K | | 6. Pipeline port in table |
163 | | | | 7. Pipeline enable |
164 | | | | 8. Pipeline table rule add default |
165 | | | | 9. Pipeline table rule add |
166 +-----------------------+----------------------+----------------+------------------------------------+
167 | KNI | Stub | Forward | 1. Mempool create |
168 | | | | 2. Link create |
169 | | | | 3. Pipeline create |
170 | | | | 4. Pipeline port in/out |
171 | | | | 5. Pipeline table |
172 | | | | 6. Pipeline port in table |
173 | | | | 7. Pipeline enable |
174 | | | | 8. Pipeline table rule add |
175 +-----------------------+----------------------+----------------+------------------------------------+
176 | Firewall | ACL | Allow/Drop | 1. Mempool create |
177 | | | | 2. Link create |
178 | | * Key = n-tuple | | 3. Pipeline create |
179 | | * Offset = 270 | | 4. Pipeline port in/out |
180 | | * Table size = 4K | | 5. Pipeline table |
181 | | | | 6. Pipeline port in table |
182 | | | | 7. Pipeline enable |
183 | | | | 8. Pipeline table rule add default |
184 | | | | 9. Pipeline table rule add |
185 +-----------------------+----------------------+----------------+------------------------------------+
186 | IP routing | LPM (IPv4) | Forward | 1. Mempool Create |
187 | | | | 2. Link create |
188 | | * Key = IP dest addr | | 3. Pipeline create |
189 | | * Offset = 286 | | 4. Pipeline port in/out |
190 | | * Table size = 4K | | 5. Pipeline table |
191 | | | | 6. Pipeline port in table |
192 | | | | 7. Pipeline enable |
193 | | | | 8. Pipeline table rule add default |
194 | | | | 9. Pipeline table rule add |
195 +-----------------------+----------------------+----------------+------------------------------------+
196 | Equal-cost multi-path | LPM (IPv4) | Forward, | 1. Mempool Create |
197 | routing (ECMP) | | load balance, | 2. Link create |
198 | | * Key = IP dest addr | encap ether | 3. Pipeline create |
199 | | * Offset = 286 | | 4. Pipeline port in/out |
200 | | * Table size = 4K | | 5. Pipeline table (LPM) |
201 | | | | 6. Pipeline table (Array) |
202 | | | | 7. Pipeline port in table (LPM) |
203 | | Array | | 8. Pipeline enable |
204 | | | | 9. Pipeline table rule add default |
205 | | * Key = Array index | | 10. Pipeline table rule add(LPM) |
206 | | * Offset = 256 | | 11. Pipeline table rule add(Array) |
207 | | * Size = 64K | | |
209 +-----------------------+----------------------+----------------+------------------------------------+
211 Command Line Interface (CLI)
212 ----------------------------
217 Link configuration ::
220 dev <device_name>|port <port_id>
221 rxq <n_queues> <queue_size> <mempool_name>
222 txq <n_queues> <queue_size> promiscuous on | off
223 [rss <qid_0> ... <qid_n>]
225 Note: The PCI device name must be specified in the Domain:Bus:Device.Function format.
233 mempool <mempool_name> buffer <buffer_size>
234 pool <pool_size> cache <cache_size> cpu <cpu_id>
240 Create software queue ::
242 swq <swq_name> size <size> cpu <cpu_id>
248 Add traffic manager subport profile ::
252 <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate>
256 Add traffic manager pipe profile ::
260 <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate>
262 <tc_ov_weight> <wrr_weight0..15>
264 Create traffic manager port ::
268 spp <n_subports_per_port>
269 pps <n_pipes_per_subport>
271 <qsize_tc1> <qsize_tc2> <qsize_tc3>
272 fo <frame_overhead> mtu <mtu> cpu <cpu_id>
274 Configure traffic manager subport ::
278 profile <subport_profile_id>
280 Configure traffic manager pipe ::
284 pipe from <pipe_id_first> to <pipe_id_last>
285 profile <pipe_profile_id>
303 mempool <mempool_name>
310 Create cryptodev port ::
312 cryptodev <cryptodev_name>
313 dev <DPDK Cryptodev PMD name>
314 queue <n_queues> <queue_size>
319 Create action profile for pipeline input port ::
321 port in action profile <profile_name>
322 [filter match | mismatch offset <key_offset> mask <key_mask> key <key_value> port <port_id>]
323 [balance offset <key_offset> mask <key_mask> port <port_id0> ... <port_id15>]
325 Create action profile for the pipeline table ::
327 table action profile <profile_name>
331 [balance offset <key_offset> mask <key_mask> outoffset <out_offset>]
334 stats none | pkts | bytes | both]
335 [tm spp <n_subports_per_port> pps <n_pipes_per_subport>]
336 [encap ether | vlan | qinq | mpls | pppoe]
341 [stats pkts | bytes | both]
342 [sym_crypto cryptodev <cryptodev_name>
343 mempool_create <mempool_name> mempool_init <mempool_name>]
352 pipeline <pipeline_name>
353 period <timer_period_ms>
354 offset_port_id <offset_port_id>
357 Create pipeline input port ::
359 pipeline <pipeline_name> port in
361 link <link_name> rxq <queue_id>
364 | tap <tap_name> mempool <mempool_name> mtu <mtu>
366 | source mempool <mempool_name> file <file_name> bpp <n_bytes_per_pkt>
367 [action <port_in_action_profile_name>]
370 Create pipeline output port ::
372 pipeline <pipeline_name> port out
374 link <link_name> txq <txq_id>
379 | sink [file <file_name> pkts <max_n_pkts>]
381 Create pipeline table ::
383 pipeline <pipeline_name> table
387 offset <ip_header_offset>
401 offset <ip_header_offset>
404 [action <table_action_profile_name>]
406 Connect pipeline input port to table ::
408 pipeline <pipeline_name> port in <port_id> table <table_id>
410 Display statistics for specific pipeline input port, output port
413 pipeline <pipeline_name> port in <port_id> stats read [clear]
414 pipeline <pipeline_name> port out <port_id> stats read [clear]
415 pipeline <pipeline_name> table <table_id> stats read [clear]
417 Enable given input port for specific pipeline instance ::
419 pipeline <pipeline_name> port out <port_id> disable
421 Disable given input port for specific pipeline instance ::
423 pipeline <pipeline_name> port out <port_id> disable
425 Add default rule to table for specific pipeline instance ::
427 pipeline <pipeline_name> table <table_id> rule add
437 Add rule to table for specific pipeline instance ::
439 pipeline <pipeline_name> table <table_id> rule add
444 ipv4 | ipv6 <sa> <sa_depth> <da> <da_depth>
445 <sp0> <sp1> <dp0> <dp1> <proto>
449 | ipv4_5tuple <sa> <da> <sp> <dp> <proto>
450 | ipv6_5tuple <sa> <da> <sp> <dp> <proto>
453 | qinq <svlan> <cvlan>
455 ipv4 | ipv6 <addr> <depth>
463 [balance <out0> ... <out7>]
465 tc0 meter <meter_profile_id> policer g <pa> y <pa> r <pa>
466 [tc1 meter <meter_profile_id> policer g <pa> y <pa> r <pa>
467 tc2 meter <meter_profile_id> policer g <pa> y <pa> r <pa>
468 tc3 meter <meter_profile_id> policer g <pa> y <pa> r <pa>]]
469 [tm subport <subport_id> pipe <pipe_id>]
472 | vlan <da> <sa> <pcp> <dei> <vid>
473 | qinq <da> <sa> <pcp> <dei> <vid> <pcp> <dei> <vid>
474 | mpls unicast | multicast
476 label0 <label> <tc> <ttl>
477 [label1 <label> <tc> <ttl>
478 [label2 <label> <tc> <ttl>
479 [label3 <label> <tc> <ttl>]]]
480 | pppoe <da> <sa> <session_id>]
481 [nat ipv4 | ipv6 <addr> <port>]
489 cipher_algo <algo> cipher_key <key> cipher_iv <iv>
491 cipher_algo <algo> cipher_key <key> cipher_iv <iv>
492 auth_algo <algo> auth_key <key> digest_size <size>
494 aead_algo <algo> aead_key <key> aead_iv <iv> aead_aad <aad>
496 data_offset <data_offset>]
499 <pa> ::= g | y | r | drop
501 Add bulk rules to table for specific pipeline instance ::
503 pipeline <pipeline_name> table <table_id> rule add bulk <file_name> <n_rules>
506 - file_name = path to file
507 - File line format = match <match> action <action>
509 Delete table rule for specific pipeline instance ::
511 pipeline <pipeline_name> table <table_id> rule delete
514 Delete default table rule for specific pipeline instance ::
516 pipeline <pipeline_name> table <table_id> rule delete
520 Add meter profile to the table for specific pipeline instance ::
522 pipeline <pipeline_name> table <table_id> meter profile <meter_profile_id>
523 add srtcm cir <cir> cbs <cbs> ebs <ebs>
524 | trtcm cir <cir> pir <pir> cbs <cbs> pbs <pbs>
526 Delete meter profile from the table for specific pipeline instance ::
528 pipeline <pipeline_name> table <table_id>
529 meter profile <meter_profile_id> delete
532 Update the dscp table for meter or traffic manager action for specific
535 pipeline <pipeline_name> table <table_id> dscp <file_name>
538 - file_name = path to file
540 - File line format = <tc_id> <tc_queue_id> <color>, with <color> as: g | y | r
543 Pipeline enable/disable
544 ~~~~~~~~~~~~~~~~~~~~~~~
546 Enable given pipeline instance for specific data plane thread ::
548 thread <thread_id> pipeline <pipeline_name> enable
551 Disable given pipeline instance for specific data plane thread ::
553 thread <thread_id> pipeline <pipeline_name> disable