1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2015-2018 Intel Corporation. 3 4Internet Protocol (IP) Pipeline Application 5=========================================== 6 7Application overview 8-------------------- 9 10The *Internet Protocol (IP) Pipeline* application is intended to be a vehicle for rapid development of packet processing 11applications on multi-core CPUs. 12 13Following OpenFlow and P4 design principles, the application can be used to create functional blocks called pipelines out 14of input/output ports, tables and actions in a modular way. Multiple pipelines can be inter-connected through packet queues 15to create complete applications (super-pipelines). 16 17The pipelines are mapped to application threads, with each pipeline executed by a single thread and each thread able to run 18one or several pipelines. The possibilities of creating pipelines out of ports, tables and actions, connecting multiple 19pipelines together and mapping the pipelines to execution threads are endless, therefore this application can be seen as 20a true application generator. 21 22Pipelines are created and managed through Command Line Interface (CLI): 23 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. 26 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. 31 32Running the application 33----------------------- 34 35The application startup command line is:: 36 37 ip_pipeline [EAL_ARGS] -- [-s SCRIPT_FILE] [-h HOST] [-p PORT] 38 39The application startup arguments are: 40 41``-s SCRIPT_FILE`` 42 43 * Optional: Yes 44 45 * Default: Not present 46 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. 49 50``-h HOST`` 51 52 * Optional: Yes 53 54 * Default: ``0.0.0.0`` 55 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. 58 59``-p PORT`` 60 61 * Optional: Yes 62 63 * Default: ``8086`` 64 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. 67 68Refer to *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. 69 70The following is an example command to run ip pipeline application configured for layer 2 forwarding: 71 72.. code-block:: console 73 74 $ ./build/ip_pipeline -c 0x3 -- -s examples/route_ecmp.cli 75 76The application should start successfully and display as follows: 77 78.. code-block:: console 79 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 86 ... 87 88To run remote client (e.g. telnet) to communicate with the ip pipeline application: 89 90.. code-block:: console 91 92 $ telnet 127.0.0.1 8086 93 94When running a telnet client as above, command prompt is displayed: 95 96.. code-block:: console 97 98 Trying 127.0.0.1... 99 Connected to 127.0.0.1. 100 Escape character is '^]'. 101 102 Welcome to IP Pipeline! 103 104 pipeline> 105 106Once application and telnet client start running, messages can be sent from client to application. 107At any stage, telnet client can be terminated using the quit command. 108 109 110Application stages 111------------------ 112 113Initialization 114~~~~~~~~~~~~~~ 115 116During this stage, EAL layer is initialised and application specific arguments are parsed. Furthermore, the data strcutures 117(i.e. linked lists) for application objects are initialized. In case of any initialization error, an error message 118is displayed and the application is terminated. 119 120.. _ip_pipeline_runtime: 121 122Run-time 123~~~~~~~~ 124 125The master thread is creating and managing all the application objects based on CLI input. 126 127Each data plane thread runs one or several pipelines previously assigned to it in round-robin order. Each data plane thread 128executes two tasks in time-sharing mode: 129 1301. *Packet processing task*: Process bursts of input packets read from the pipeline input ports. 131 1322. *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. 135 136Examples 137-------- 138 139.. _table_examples: 140 141.. tabularcolumns:: |p{3cm}|p{5cm}|p{4cm}|p{4cm}| 142 143.. table:: Pipeline examples provided with the application 144 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 creat | 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 | | | 208 | | | | | 209 +-----------------------+----------------------+----------------+------------------------------------+ 210 211Command Line Interface (CLI) 212---------------------------- 213 214Link 215~~~~ 216 217 Link configuration :: 218 219 link <link_name> 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>] 224 225 226Mempool 227~~~~~~~ 228 229 Mempool create :: 230 231 mempool <mempool_name> buffer <buffer_size> 232 pool <pool_size> cache <cache_size> cpu <cpu_id> 233 234 235Software queue 236~~~~~~~~~~~~~~ 237 238 Create software queue :: 239 240 swq <swq_name> size <size> cpu <cpu_id> 241 242 243Traffic manager 244~~~~~~~~~~~~~~~ 245 246 Add traffic manager subport profile :: 247 248 tmgr subport profile 249 <tb_rate> <tb_size> 250 <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate> 251 <tc_period> 252 253 254 Add traffic manager pipe profile :: 255 256 tmgr pipe profile 257 <tb_rate> <tb_size> 258 <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate> 259 <tc_period> 260 <tc_ov_weight> <wrr_weight0..15> 261 262 Create traffic manager port :: 263 264 tmgr <tmgr_name> 265 rate <rate> 266 spp <n_subports_per_port> 267 pps <n_pipes_per_subport> 268 qsize <qsize_tc0> 269 <qsize_tc1> <qsize_tc2> <qsize_tc3> 270 fo <frame_overhead> mtu <mtu> cpu <cpu_id> 271 272 Configure traffic manager subport :: 273 274 tmgr <tmgr_name> 275 subport <subport_id> 276 profile <subport_profile_id> 277 278 Configure traffic manager pipe :: 279 280 tmgr <tmgr_name> 281 subport <subport_id> 282 pipe from <pipe_id_first> to <pipe_id_last> 283 profile <pipe_profile_id> 284 285 286Tap 287~~~ 288 289 Create tap port :: 290 291 tap <name> 292 293 294Kni 295~~~ 296 297 Create kni port :: 298 299 kni <kni_name> 300 link <link_name> 301 mempool <mempool_name> 302 [thread <thread_id>] 303 304 305Action profile 306~~~~~~~~~~~~~~ 307 308 Create action profile for pipeline input port :: 309 310 port in action profile <profile_name> 311 [filter match | mismatch offset <key_offset> mask <key_mask> key <key_value> port <port_id>] 312 [balance offset <key_offset> mask <key_mask> port <port_id0> ... <port_id15>] 313 314 Create action profile for the pipeline table :: 315 316 table action profile <profile_name> 317 ipv4 | ipv6 318 offset <ip_offset> 319 fwd 320 [balance offset <key_offset> mask <key_mask> outoffset <out_offset>] 321 [meter srtcm | trtcm 322 tc <n_tc> 323 stats none | pkts | bytes | both] 324 [tm spp <n_subports_per_port> pps <n_pipes_per_subport>] 325 [encap ether | vlan | qinq | mpls | pppoe] 326 [nat src | dst 327 proto udp | tcp] 328 [ttl drop | fwd 329 stats none | pkts] 330 [stats pkts | bytes | both] 331 [time] 332 333 334Pipeline 335~~~~~~~~ 336 337Create pipeline :: 338 339 pipeline <pipeline_name> 340 period <timer_period_ms> 341 offset_port_id <offset_port_id> 342 cpu <cpu_id> 343 344Create pipeline input port :: 345 346 pipeline <pipeline_name> port in 347 bsz <burst_size> 348 link <link_name> rxq <queue_id> 349 | swq <swq_name> 350 | tmgr <tmgr_name> 351 | tap <tap_name> mempool <mempool_name> mtu <mtu> 352 | kni <kni_name> 353 | source mempool <mempool_name> file <file_name> bpp <n_bytes_per_pkt> 354 [action <port_in_action_profile_name>] 355 [disabled] 356 357Create pipeline output port :: 358 359 pipeline <pipeline_name> port out 360 bsz <burst_size> 361 link <link_name> txq <txq_id> 362 | swq <swq_name> 363 | tmgr <tmgr_name> 364 | tap <tap_name> 365 | kni <kni_name> 366 | sink [file <file_name> pkts <max_n_pkts>] 367 368Create pipeline table :: 369 370 pipeline <pipeline_name> table 371 match 372 acl 373 ipv4 | ipv6 374 offset <ip_header_offset> 375 size <n_rules> 376 | array 377 offset <key_offset> 378 size <n_keys> 379 | hash 380 ext | lru 381 key <key_size> 382 mask <key_mask> 383 offset <key_offset> 384 buckets <n_buckets> 385 size <n_keys> 386 | lpm 387 ipv4 | ipv6 388 offset <ip_header_offset> 389 size <n_rules> 390 | stub 391 [action <table_action_profile_name>] 392 393Connect pipeline input port to table :: 394 395 pipeline <pipeline_name> port in <port_id> table <table_id> 396 397Display statistics for specific pipeline input port, output port 398or table :: 399 400 pipeline <pipeline_name> port in <port_id> stats read [clear] 401 pipeline <pipeline_name> port out <port_id> stats read [clear] 402 pipeline <pipeline_name> table <table_id> stats read [clear] 403 404Enable given input port for specific pipeline instance :: 405 406 pipeline <pipeline_name> port out <port_id> disable 407 408Disable given input port for specific pipeline instance :: 409 410 pipeline <pipeline_name> port out <port_id> disable 411 412Add default rule to table for specific pipeline instance :: 413 414 pipeline <pipeline_name> table <table_id> rule add 415 match 416 default 417 action 418 fwd 419 drop 420 | port <port_id> 421 | meta 422 | table <table_id> 423 424Add rule to table for specific pipeline instance :: 425 426 pipeline <pipeline_name> table <table_id> rule add 427 428 match 429 acl 430 priority <priority> 431 ipv4 | ipv6 <sa> <sa_depth> <da> <da_depth> 432 <sp0> <sp1> <dp0> <dp1> <proto> 433 | array <pos> 434 | hash 435 raw <key> 436 | ipv4_5tuple <sa> <da> <sp> <dp> <proto> 437 | ipv6_5tuple <sa> <da> <sp> <dp> <proto> 438 | ipv4_addr <addr> 439 | ipv6_addr <addr> 440 | qinq <svlan> <cvlan> 441 | lpm 442 ipv4 | ipv6 <addr> <depth> 443 444 action 445 fwd 446 drop 447 | port <port_id> 448 | meta 449 | table <table_id> 450 [balance <out0> ... <out7>] 451 [meter 452 tc0 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 453 [tc1 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 454 tc2 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 455 tc3 meter <meter_profile_id> policer g <pa> y <pa> r <pa>]] 456 [tm subport <subport_id> pipe <pipe_id>] 457 [encap 458 ether <da> <sa> 459 | vlan <da> <sa> <pcp> <dei> <vid> 460 | qinq <da> <sa> <pcp> <dei> <vid> <pcp> <dei> <vid> 461 | mpls unicast | multicast 462 <da> <sa> 463 label0 <label> <tc> <ttl> 464 [label1 <label> <tc> <ttl> 465 [label2 <label> <tc> <ttl> 466 [label3 <label> <tc> <ttl>]]] 467 | pppoe <da> <sa> <session_id>] 468 [nat ipv4 | ipv6 <addr> <port>] 469 [ttl dec | keep] 470 [stats] 471 [time] 472 473 where: 474 <pa> ::= g | y | r | drop 475 476Add bulk rules to table for specific pipeline instance :: 477 478 pipeline <pipeline_name> table <table_id> rule add bulk <file_name> <n_rules> 479 480 Where: 481 - file_name = path to file 482 - File line format = match <match> action <action> 483 484Delete table rule for specific pipeline instance :: 485 486 pipeline <pipeline_name> table <table_id> rule delete 487 match <match> 488 489Delete default table rule for specific pipeline instance :: 490 491 pipeline <pipeline_name> table <table_id> rule delete 492 match 493 default 494 495Add meter profile to the table for specific pipeline instance :: 496 497 pipeline <pipeline_name> table <table_id> meter profile <meter_profile_id> 498 add srtcm cir <cir> cbs <cbs> ebs <ebs> 499 | trtcm cir <cir> pir <pir> cbs <cbs> pbs <pbs> 500 501Delete meter profile from the table for specific pipeline instance :: 502 503 pipeline <pipeline_name> table <table_id> 504 meter profile <meter_profile_id> delete 505 506 507Update the dscp table for meter or traffic manager action for specific 508pipeline instance :: 509 510 pipeline <pipeline_name> table <table_id> dscp <file_name> 511 512 Where: 513 - file_name = path to file 514 - exactly 64 lines 515 - File line format = <tc_id> <tc_queue_id> <color>, with <color> as: g | y | r 516 517 518Pipeline enable/disable 519~~~~~~~~~~~~~~~~~~~~~~~ 520 521 Enable given pipeline instance for specific data plane thread :: 522 523 thread <thread_id> pipeline <pipeline_name> enable 524 525 526 Disable given pipeline instance for specific data plane thread :: 527 528 thread <thread_id> pipeline <pipeline_name> disable 529