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 130#. *Packet processing task*: Process bursts of input packets read from the pipeline input ports. 131 132#. *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 | Firewall | ACL | Allow/Drop | 1. Mempool create | 168 | | | | 2. Link create | 169 | | * Key = n-tuple | | 3. Pipeline create | 170 | | * Offset = 270 | | 4. Pipeline port in/out | 171 | | * Table size = 4K | | 5. Pipeline table | 172 | | | | 6. Pipeline port in table | 173 | | | | 7. Pipeline enable | 174 | | | | 8. Pipeline table rule add default | 175 | | | | 9. Pipeline table rule add | 176 +-----------------------+----------------------+----------------+------------------------------------+ 177 | IP routing | LPM (IPv4) | Forward | 1. Mempool Create | 178 | | | | 2. Link create | 179 | | * Key = IP dest addr | | 3. Pipeline create | 180 | | * Offset = 286 | | 4. Pipeline port in/out | 181 | | * Table size = 4K | | 5. Pipeline table | 182 | | | | 6. Pipeline port in table | 183 | | | | 7. Pipeline enable | 184 | | | | 8. Pipeline table rule add default | 185 | | | | 9. Pipeline table rule add | 186 +-----------------------+----------------------+----------------+------------------------------------+ 187 | Equal-cost multi-path | LPM (IPv4) | Forward, | 1. Mempool Create | 188 | routing (ECMP) | | load balance, | 2. Link create | 189 | | * Key = IP dest addr | encap ether | 3. Pipeline create | 190 | | * Offset = 286 | | 4. Pipeline port in/out | 191 | | * Table size = 4K | | 5. Pipeline table (LPM) | 192 | | | | 6. Pipeline table (Array) | 193 | | | | 7. Pipeline port in table (LPM) | 194 | | Array | | 8. Pipeline enable | 195 | | | | 9. Pipeline table rule add default | 196 | | * Key = Array index | | 10. Pipeline table rule add(LPM) | 197 | | * Offset = 256 | | 11. Pipeline table rule add(Array) | 198 | | * Size = 64K | | | 199 | | | | | 200 +-----------------------+----------------------+----------------+------------------------------------+ 201 202Command Line Interface (CLI) 203---------------------------- 204 205Link 206~~~~ 207 208 Link configuration :: 209 210 link <link_name> 211 dev <device_name>|port <port_id> 212 rxq <n_queues> <queue_size> <mempool_name> 213 txq <n_queues> <queue_size> promiscuous on | off 214 [rss <qid_0> ... <qid_n>] 215 216 Note: The PCI device name must be specified in the Domain:Bus:Device.Function format. 217 218 219Mempool 220~~~~~~~ 221 222 Mempool create :: 223 224 mempool <mempool_name> buffer <buffer_size> 225 pool <pool_size> cache <cache_size> cpu <cpu_id> 226 227 228Software queue 229~~~~~~~~~~~~~~ 230 231 Create software queue :: 232 233 swq <swq_name> size <size> cpu <cpu_id> 234 235 236Traffic manager 237~~~~~~~~~~~~~~~ 238 239 Add traffic manager subport profile :: 240 241 tmgr subport profile 242 <tb_rate> <tb_size> 243 <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate> <tc4_rate> 244 <tc5_rate> <tc6_rate> <tc7_rate> <tc8_rate> 245 <tc9_rate> <tc10_rate> <tc11_rate> <tc12_rate> 246 <tc_period> 247 248 Add traffic manager pipe profile :: 249 250 tmgr pipe 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 <tc_ov_weight> 257 <wrr_weight0..3> 258 259 Create traffic manager port :: 260 261 tmgr <tmgr_name> 262 rate <rate> 263 spp <n_subports_per_port> 264 pps <n_pipes_per_subport> 265 fo <frame_overhead> 266 mtu <mtu> 267 cpu <cpu_id> 268 269 Configure traffic manager subport :: 270 271 tmgr <tmgr_name> 272 subport <subport_id> 273 profile <subport_profile_id> 274 275 Configure traffic manager pipe :: 276 277 tmgr <tmgr_name> 278 subport <subport_id> 279 pipe from <pipe_id_first> to <pipe_id_last> 280 profile <pipe_profile_id> 281 282 283Tap 284~~~ 285 286 Create tap port :: 287 288 tap <name> 289 290 291Cryptodev 292~~~~~~~~~ 293 294 Create cryptodev port :: 295 296 cryptodev <cryptodev_name> 297 dev <DPDK Cryptodev PMD name> 298 queue <n_queues> <queue_size> 299 300Action profile 301~~~~~~~~~~~~~~ 302 303 Create action profile for pipeline input port :: 304 305 port in action profile <profile_name> 306 [filter match | mismatch offset <key_offset> mask <key_mask> key <key_value> port <port_id>] 307 [balance offset <key_offset> mask <key_mask> port <port_id0> ... <port_id15>] 308 309 Create action profile for the pipeline table :: 310 311 table action profile <profile_name> 312 ipv4 | ipv6 313 offset <ip_offset> 314 fwd 315 [balance offset <key_offset> mask <key_mask> outoffset <out_offset>] 316 [meter srtcm | trtcm 317 tc <n_tc> 318 stats none | pkts | bytes | both] 319 [tm spp <n_subports_per_port> pps <n_pipes_per_subport>] 320 [encap ether | vlan | qinq | mpls | pppoe] 321 [nat src | dst 322 proto udp | tcp] 323 [ttl drop | fwd 324 stats none | pkts] 325 [stats pkts | bytes | both] 326 [sym_crypto cryptodev <cryptodev_name> 327 mempool_create <mempool_name> mempool_init <mempool_name>] 328 [time] 329 330 331Pipeline 332~~~~~~~~ 333 334Create pipeline :: 335 336 pipeline <pipeline_name> 337 period <timer_period_ms> 338 offset_port_id <offset_port_id> 339 cpu <cpu_id> 340 341Create pipeline input port :: 342 343 pipeline <pipeline_name> port in 344 bsz <burst_size> 345 link <link_name> rxq <queue_id> 346 | swq <swq_name> 347 | tmgr <tmgr_name> 348 | tap <tap_name> mempool <mempool_name> mtu <mtu> 349 | source mempool <mempool_name> file <file_name> bpp <n_bytes_per_pkt> 350 [action <port_in_action_profile_name>] 351 [disabled] 352 353Create pipeline output port :: 354 355 pipeline <pipeline_name> port out 356 bsz <burst_size> 357 link <link_name> txq <txq_id> 358 | swq <swq_name> 359 | tmgr <tmgr_name> 360 | tap <tap_name> 361 | sink [file <file_name> pkts <max_n_pkts>] 362 363Create pipeline table :: 364 365 pipeline <pipeline_name> table 366 match 367 acl 368 ipv4 | ipv6 369 offset <ip_header_offset> 370 size <n_rules> 371 | array 372 offset <key_offset> 373 size <n_keys> 374 | hash 375 ext | lru 376 key <key_size> 377 mask <key_mask> 378 offset <key_offset> 379 buckets <n_buckets> 380 size <n_keys> 381 | lpm 382 ipv4 | ipv6 383 offset <ip_header_offset> 384 size <n_rules> 385 | stub 386 [action <table_action_profile_name>] 387 388Connect pipeline input port to table :: 389 390 pipeline <pipeline_name> port in <port_id> table <table_id> 391 392Display statistics for specific pipeline input port, output port 393or table :: 394 395 pipeline <pipeline_name> port in <port_id> stats read [clear] 396 pipeline <pipeline_name> port out <port_id> stats read [clear] 397 pipeline <pipeline_name> table <table_id> stats read [clear] 398 399Enable given input port for specific pipeline instance :: 400 401 pipeline <pipeline_name> port out <port_id> disable 402 403Disable given input port for specific pipeline instance :: 404 405 pipeline <pipeline_name> port out <port_id> disable 406 407Add default rule to table for specific pipeline instance :: 408 409 pipeline <pipeline_name> table <table_id> rule add 410 match 411 default 412 action 413 fwd 414 drop 415 | port <port_id> 416 | meta 417 | table <table_id> 418 419Add rule to table for specific pipeline instance :: 420 421 pipeline <pipeline_name> table <table_id> rule add 422 423 match 424 acl 425 priority <priority> 426 ipv4 | ipv6 <sa> <sa_depth> <da> <da_depth> 427 <sp0> <sp1> <dp0> <dp1> <proto> 428 | array <pos> 429 | hash 430 raw <key> 431 | ipv4_5tuple <sa> <da> <sp> <dp> <proto> 432 | ipv6_5tuple <sa> <da> <sp> <dp> <proto> 433 | ipv4_addr <addr> 434 | ipv6_addr <addr> 435 | qinq <svlan> <cvlan> 436 | lpm 437 ipv4 | ipv6 <addr> <depth> 438 439 action 440 fwd 441 drop 442 | port <port_id> 443 | meta 444 | table <table_id> 445 [balance <out0> ... <out7>] 446 [meter 447 tc0 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 448 [tc1 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 449 tc2 meter <meter_profile_id> policer g <pa> y <pa> r <pa> 450 tc3 meter <meter_profile_id> policer g <pa> y <pa> r <pa>]] 451 [tm subport <subport_id> pipe <pipe_id>] 452 [encap 453 ether <da> <sa> 454 | vlan <da> <sa> <pcp> <dei> <vid> 455 | qinq <da> <sa> <pcp> <dei> <vid> <pcp> <dei> <vid> 456 | mpls unicast | multicast 457 <da> <sa> 458 label0 <label> <tc> <ttl> 459 [label1 <label> <tc> <ttl> 460 [label2 <label> <tc> <ttl> 461 [label3 <label> <tc> <ttl>]]] 462 | pppoe <da> <sa> <session_id>] 463 [nat ipv4 | ipv6 <addr> <port>] 464 [ttl dec | keep] 465 [stats] 466 [time] 467 [sym_crypto 468 encrypt | decrypt 469 type 470 | cipher 471 cipher_algo <algo> cipher_key <key> cipher_iv <iv> 472 | cipher_auth 473 cipher_algo <algo> cipher_key <key> cipher_iv <iv> 474 auth_algo <algo> auth_key <key> digest_size <size> 475 | aead 476 aead_algo <algo> aead_key <key> aead_iv <iv> aead_aad <aad> 477 digest_size <size> 478 data_offset <data_offset>] 479 480 where: 481 <pa> ::= g | y | r | drop 482 483Add bulk rules to table for specific pipeline instance :: 484 485 pipeline <pipeline_name> table <table_id> rule add bulk <file_name> <n_rules> 486 487 Where: 488 - file_name = path to file 489 - File line format = match <match> action <action> 490 491Delete table rule for specific pipeline instance :: 492 493 pipeline <pipeline_name> table <table_id> rule delete 494 match <match> 495 496Delete default table rule for specific pipeline instance :: 497 498 pipeline <pipeline_name> table <table_id> rule delete 499 match 500 default 501 502Add meter profile to the table for specific pipeline instance :: 503 504 pipeline <pipeline_name> table <table_id> meter profile <meter_profile_id> 505 add srtcm cir <cir> cbs <cbs> ebs <ebs> 506 | trtcm cir <cir> pir <pir> cbs <cbs> pbs <pbs> 507 508Delete meter profile from the table for specific pipeline instance :: 509 510 pipeline <pipeline_name> table <table_id> 511 meter profile <meter_profile_id> delete 512 513 514Update the dscp table for meter or traffic manager action for specific 515pipeline instance :: 516 517 pipeline <pipeline_name> table <table_id> dscp <file_name> 518 519 Where: 520 - file_name = path to file 521 - exactly 64 lines 522 - File line format = <tc_id> <tc_queue_id> <color>, with <color> as: g | y | r 523 524 525Pipeline enable/disable 526~~~~~~~~~~~~~~~~~~~~~~~ 527 528 Enable given pipeline instance for specific data plane thread :: 529 530 thread <thread_id> pipeline <pipeline_name> enable 531 532 533 Disable given pipeline instance for specific data plane thread :: 534 535 thread <thread_id> pipeline <pipeline_name> disable 536