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 dpdk-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_dir>/examples/dpdk-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 structures 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 main 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 main 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 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 | | | 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 Note: The PCI device name must be specified in the Domain:Bus:Device.Function format. 226 227 228Mempool 229~~~~~~~ 230 231 Mempool create :: 232 233 mempool <mempool_name> buffer <buffer_size> 234 pool <pool_size> cache <cache_size> cpu <cpu_id> 235 236 237Software queue 238~~~~~~~~~~~~~~ 239 240 Create software queue :: 241 242 swq <swq_name> size <size> cpu <cpu_id> 243 244 245Traffic manager 246~~~~~~~~~~~~~~~ 247 248 Add traffic manager subport profile :: 249 250 tmgr subport profile 251 <tb_rate> <tb_size> 252 <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate> <tc4_rate> 253 <tc5_rate> <tc6_rate> <tc7_rate> <tc8_rate> 254 <tc9_rate> <tc10_rate> <tc11_rate> <tc12_rate> 255 <tc_period> 256 pps <n_pipes_per_subport> 257 qsize <qsize_tc0> <qsize_tc1> <qsize_tc2> 258 <qsize_tc3> <qsize_tc4> <qsize_tc5> <qsize_tc6> 259 <qsize_tc7> <qsize_tc8> <qsize_tc9> <qsize_tc10> 260 <qsize_tc11> <qsize_tc12> 261 262 Add traffic manager pipe profile :: 263 264 tmgr pipe profile 265 <tb_rate> <tb_size> 266 <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate> <tc4_rate> 267 <tc5_rate> <tc6_rate> <tc7_rate> <tc8_rate> 268 <tc9_rate> <tc10_rate> <tc11_rate> <tc12_rate> 269 <tc_period> 270 <tc_ov_weight> 271 <wrr_weight0..3> 272 273 Create traffic manager port :: 274 275 tmgr <tmgr_name> 276 rate <rate> 277 spp <n_subports_per_port> 278 fo <frame_overhead> 279 mtu <mtu> 280 cpu <cpu_id> 281 282 Configure traffic manager subport :: 283 284 tmgr <tmgr_name> 285 subport <subport_id> 286 profile <subport_profile_id> 287 288 Configure traffic manager pipe :: 289 290 tmgr <tmgr_name> 291 subport <subport_id> 292 pipe from <pipe_id_first> to <pipe_id_last> 293 profile <pipe_profile_id> 294 295 296Tap 297~~~ 298 299 Create tap port :: 300 301 tap <name> 302 303 304Kni 305~~~ 306 307 Create kni port :: 308 309 kni <kni_name> 310 link <link_name> 311 mempool <mempool_name> 312 [thread <thread_id>] 313 314 315Cryptodev 316~~~~~~~~~ 317 318 Create cryptodev port :: 319 320 cryptodev <cryptodev_name> 321 dev <DPDK Cryptodev PMD name> 322 queue <n_queues> <queue_size> 323 324Action profile 325~~~~~~~~~~~~~~ 326 327 Create action profile for pipeline input port :: 328 329 port in action profile <profile_name> 330 [filter match | mismatch offset <key_offset> mask <key_mask> key <key_value> port <port_id>] 331 [balance offset <key_offset> mask <key_mask> port <port_id0> ... <port_id15>] 332 333 Create action profile for the pipeline table :: 334 335 table action profile <profile_name> 336 ipv4 | ipv6 337 offset <ip_offset> 338 fwd 339 [balance offset <key_offset> mask <key_mask> outoffset <out_offset>] 340 [meter srtcm | trtcm 341 tc <n_tc> 342 stats none | pkts | bytes | both] 343 [tm spp <n_subports_per_port> pps <n_pipes_per_subport>] 344 [encap ether | vlan | qinq | mpls | pppoe] 345 [nat src | dst 346 proto udp | tcp] 347 [ttl drop | fwd 348 stats none | pkts] 349 [stats pkts | bytes | both] 350 [sym_crypto cryptodev <cryptodev_name> 351 mempool_create <mempool_name> mempool_init <mempool_name>] 352 [time] 353 354 355Pipeline 356~~~~~~~~ 357 358Create pipeline :: 359 360 pipeline <pipeline_name> 361 period <timer_period_ms> 362 offset_port_id <offset_port_id> 363 cpu <cpu_id> 364 365Create pipeline input port :: 366 367 pipeline <pipeline_name> port in 368 bsz <burst_size> 369 link <link_name> rxq <queue_id> 370 | swq <swq_name> 371 | tmgr <tmgr_name> 372 | tap <tap_name> mempool <mempool_name> mtu <mtu> 373 | kni <kni_name> 374 | source mempool <mempool_name> file <file_name> bpp <n_bytes_per_pkt> 375 [action <port_in_action_profile_name>] 376 [disabled] 377 378Create pipeline output port :: 379 380 pipeline <pipeline_name> port out 381 bsz <burst_size> 382 link <link_name> txq <txq_id> 383 | swq <swq_name> 384 | tmgr <tmgr_name> 385 | tap <tap_name> 386 | kni <kni_name> 387 | sink [file <file_name> pkts <max_n_pkts>] 388 389Create pipeline table :: 390 391 pipeline <pipeline_name> table 392 match 393 acl 394 ipv4 | ipv6 395 offset <ip_header_offset> 396 size <n_rules> 397 | array 398 offset <key_offset> 399 size <n_keys> 400 | hash 401 ext | lru 402 key <key_size> 403 mask <key_mask> 404 offset <key_offset> 405 buckets <n_buckets> 406 size <n_keys> 407 | lpm 408 ipv4 | ipv6 409 offset <ip_header_offset> 410 size <n_rules> 411 | stub 412 [action <table_action_profile_name>] 413 414Connect pipeline input port to table :: 415 416 pipeline <pipeline_name> port in <port_id> table <table_id> 417 418Display statistics for specific pipeline input port, output port 419or table :: 420 421 pipeline <pipeline_name> port in <port_id> stats read [clear] 422 pipeline <pipeline_name> port out <port_id> stats read [clear] 423 pipeline <pipeline_name> table <table_id> stats read [clear] 424 425Enable given input port for specific pipeline instance :: 426 427 pipeline <pipeline_name> port out <port_id> disable 428 429Disable given input port for specific pipeline instance :: 430 431 pipeline <pipeline_name> port out <port_id> disable 432 433Add default rule to table for specific pipeline instance :: 434 435 pipeline <pipeline_name> table <table_id> rule add 436 match 437 default 438 action 439 fwd 440 drop 441 | port <port_id> 442 | meta 443 | table <table_id> 444 445Add rule to table for specific pipeline instance :: 446 447 pipeline <pipeline_name> table <table_id> rule add 448 449 match 450 acl 451 priority <priority> 452 ipv4 | ipv6 <sa> <sa_depth> <da> <da_depth> 453 <sp0> <sp1> <dp0> <dp1> <proto> 454 | array <pos> 455 | hash 456 raw <key> 457 | ipv4_5tuple <sa> <da> <sp> <dp> <proto> 458 | ipv6_5tuple <sa> <da> <sp> <dp> <proto> 459 | ipv4_addr <addr> 460 | ipv6_addr <addr> 461 | qinq <svlan> <cvlan> 462 | lpm 463 ipv4 | ipv6 <addr> <depth> 464 465 action 466 fwd 467 drop 468 | port <port_id> 469 | meta 470 | table <table_id> 471 [balance <out0> ... <out7>] 472 [meter 473 tc0 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 474 [tc1 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 475 tc2 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 476 tc3 meter <meter_profile_id> policer g <pa> y <pa> r <pa>]] 477 [tm subport <subport_id> pipe <pipe_id>] 478 [encap 479 ether <da> <sa> 480 | vlan <da> <sa> <pcp> <dei> <vid> 481 | qinq <da> <sa> <pcp> <dei> <vid> <pcp> <dei> <vid> 482 | mpls unicast | multicast 483 <da> <sa> 484 label0 <label> <tc> <ttl> 485 [label1 <label> <tc> <ttl> 486 [label2 <label> <tc> <ttl> 487 [label3 <label> <tc> <ttl>]]] 488 | pppoe <da> <sa> <session_id>] 489 [nat ipv4 | ipv6 <addr> <port>] 490 [ttl dec | keep] 491 [stats] 492 [time] 493 [sym_crypto 494 encrypt | decrypt 495 type 496 | cipher 497 cipher_algo <algo> cipher_key <key> cipher_iv <iv> 498 | cipher_auth 499 cipher_algo <algo> cipher_key <key> cipher_iv <iv> 500 auth_algo <algo> auth_key <key> digest_size <size> 501 | aead 502 aead_algo <algo> aead_key <key> aead_iv <iv> aead_aad <aad> 503 digest_size <size> 504 data_offset <data_offset>] 505 506 where: 507 <pa> ::= g | y | r | drop 508 509Add bulk rules to table for specific pipeline instance :: 510 511 pipeline <pipeline_name> table <table_id> rule add bulk <file_name> <n_rules> 512 513 Where: 514 - file_name = path to file 515 - File line format = match <match> action <action> 516 517Delete table rule for specific pipeline instance :: 518 519 pipeline <pipeline_name> table <table_id> rule delete 520 match <match> 521 522Delete default table rule for specific pipeline instance :: 523 524 pipeline <pipeline_name> table <table_id> rule delete 525 match 526 default 527 528Add meter profile to the table for specific pipeline instance :: 529 530 pipeline <pipeline_name> table <table_id> meter profile <meter_profile_id> 531 add srtcm cir <cir> cbs <cbs> ebs <ebs> 532 | trtcm cir <cir> pir <pir> cbs <cbs> pbs <pbs> 533 534Delete meter profile from the table for specific pipeline instance :: 535 536 pipeline <pipeline_name> table <table_id> 537 meter profile <meter_profile_id> delete 538 539 540Update the dscp table for meter or traffic manager action for specific 541pipeline instance :: 542 543 pipeline <pipeline_name> table <table_id> dscp <file_name> 544 545 Where: 546 - file_name = path to file 547 - exactly 64 lines 548 - File line format = <tc_id> <tc_queue_id> <color>, with <color> as: g | y | r 549 550 551Pipeline enable/disable 552~~~~~~~~~~~~~~~~~~~~~~~ 553 554 Enable given pipeline instance for specific data plane thread :: 555 556 thread <thread_id> pipeline <pipeline_name> enable 557 558 559 Disable given pipeline instance for specific data plane thread :: 560 561 thread <thread_id> pipeline <pipeline_name> disable 562