summaryrefslogtreecommitdiff
path: root/doc/guides/sample_app_ug/ip_pipeline.rst
blob: 447a544d57292fffe3c03d326f7afecbdde641ad (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
..  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 strcutures
(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 creat                  |
   |                       | * 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 <link_name>
    dev <device_name>|port <port_id>
    rxq <n_queues> <queue_size> <mempool_name>
    txq <n_queues> <queue_size> promiscuous on | off
    [rss <qid_0> ... <qid_n>]

 Note: The PCI device name must be specified in the Domain:Bus:Device.Function format.


Mempool
~~~~~~~

 Mempool create ::

   mempool <mempool_name> buffer <buffer_size>
   pool <pool_size> cache <cache_size> cpu <cpu_id>


Software queue
~~~~~~~~~~~~~~

  Create software queue ::

   swq <swq_name> size <size> cpu <cpu_id>


Traffic manager
~~~~~~~~~~~~~~~

 Add traffic manager subport profile ::

  tmgr subport profile
   <tb_rate> <tb_size>
   <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate>
   <tc_period>


 Add traffic manager pipe profile ::

  tmgr pipe profile
   <tb_rate> <tb_size>
   <tc0_rate> <tc1_rate> <tc2_rate> <tc3_rate>
   <tc_period>
   <tc_ov_weight> <wrr_weight0..15>

 Create traffic manager port ::

  tmgr <tmgr_name>
   rate <rate>
   spp <n_subports_per_port>
   pps <n_pipes_per_subport>
   qsize <qsize_tc0>
   <qsize_tc1> <qsize_tc2> <qsize_tc3>
   fo <frame_overhead> mtu <mtu> cpu <cpu_id>

 Configure traffic manager subport ::

  tmgr <tmgr_name>
   subport <subport_id>
   profile <subport_profile_id>

 Configure traffic manager pipe ::

  tmgr <tmgr_name>
   subport <subport_id>
   pipe from <pipe_id_first> to <pipe_id_last>
   profile <pipe_profile_id>


Tap
~~~

 Create tap port ::

  tap <name>


Kni
~~~

  Create kni port ::

   kni <kni_name>
    link <link_name>
    mempool <mempool_name>
    [thread <thread_id>]


Cryptodev
~~~~~~~~~

  Create cryptodev port ::

   cryptodev <cryptodev_name>
    dev <DPDK Cryptodev PMD name>
    queue <n_queues> <queue_size>

Action profile
~~~~~~~~~~~~~~

 Create action profile for pipeline input port ::

  port in action profile <profile_name>
   [filter match | mismatch offset <key_offset> mask <key_mask> key <key_value> port <port_id>]
   [balance offset <key_offset> mask <key_mask> port <port_id0> ... <port_id15>]

 Create action profile for the pipeline table ::

  table action profile <profile_name>
   ipv4 | ipv6
   offset <ip_offset>
   fwd
   [balance offset <key_offset> mask <key_mask> outoffset <out_offset>]
   [meter srtcm | trtcm
       tc <n_tc>
       stats none | pkts | bytes | both]
   [tm spp <n_subports_per_port> pps <n_pipes_per_subport>]
   [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 <cryptodev_name>
       mempool_create <mempool_name> mempool_init <mempool_name>]
   [time]


Pipeline
~~~~~~~~

Create pipeline ::

  pipeline <pipeline_name>
   period <timer_period_ms>
   offset_port_id <offset_port_id>
   cpu <cpu_id>

Create pipeline input port ::

  pipeline <pipeline_name> port in
   bsz <burst_size>
   link <link_name> rxq <queue_id>
   | swq <swq_name>
   | tmgr <tmgr_name>
   | tap <tap_name> mempool <mempool_name> mtu <mtu>
   | kni <kni_name>
   | source mempool <mempool_name> file <file_name> bpp <n_bytes_per_pkt>
   [action <port_in_action_profile_name>]
   [disabled]

Create pipeline output port ::

  pipeline <pipeline_name> port out
   bsz <burst_size>
   link <link_name> txq <txq_id>
   | swq <swq_name>
   | tmgr <tmgr_name>
   | tap <tap_name>
   | kni <kni_name>
   | sink [file <file_name> pkts <max_n_pkts>]

Create pipeline table ::

  pipeline <pipeline_name> table
       match
       acl
           ipv4 | ipv6
           offset <ip_header_offset>
           size <n_rules>
       | array
           offset <key_offset>
           size <n_keys>
       | hash
           ext | lru
           key <key_size>
           mask <key_mask>
           offset <key_offset>
           buckets <n_buckets>
           size <n_keys>
       | lpm
           ipv4 | ipv6
           offset <ip_header_offset>
           size <n_rules>
       | stub
   [action <table_action_profile_name>]

Connect pipeline input port to table ::

  pipeline <pipeline_name> port in <port_id> table <table_id>

Display statistics for specific pipeline input port, output port
or table ::

  pipeline <pipeline_name> port in <port_id> stats read [clear]
  pipeline <pipeline_name> port out <port_id> stats read [clear]
  pipeline <pipeline_name> table <table_id> stats read [clear]

Enable given input port for specific pipeline instance ::

  pipeline <pipeline_name> port out <port_id> disable

Disable given input port for specific pipeline instance ::

  pipeline <pipeline_name> port out <port_id> disable

Add default rule to table for specific pipeline instance ::

  pipeline <pipeline_name> table <table_id> rule add
     match
        default
     action
        fwd
           drop
           | port <port_id>
           | meta
           | table <table_id>

Add rule to table for specific pipeline instance ::

  pipeline <pipeline_name> table <table_id> rule add

  match
     acl
        priority <priority>
        ipv4 | ipv6 <sa> <sa_depth> <da> <da_depth>
        <sp0> <sp1> <dp0> <dp1> <proto>
     | array <pos>
     | hash
        raw <key>
        | ipv4_5tuple <sa> <da> <sp> <dp> <proto>
        | ipv6_5tuple <sa> <da> <sp> <dp> <proto>
        | ipv4_addr <addr>
        | ipv6_addr <addr>
        | qinq <svlan> <cvlan>
     | lpm
        ipv4 | ipv6 <addr> <depth>

  action
     fwd
        drop
        | port <port_id>
        | meta
        | table <table_id>
     [balance <out0> ... <out7>]
     [meter
        tc0 meter <meter_profile_id> policer g <pa> y <pa> r <pa>
        [tc1 meter <meter_profile_id> policer g <pa> y <pa> r <pa>
        tc2 meter <meter_profile_id> policer g <pa> y <pa> r <pa>
        tc3 meter <meter_profile_id> policer g <pa> y <pa> r <pa>]]
     [tm subport <subport_id> pipe <pipe_id>]
     [encap
        ether <da> <sa>
        | vlan <da> <sa> <pcp> <dei> <vid>
        | qinq <da> <sa> <pcp> <dei> <vid> <pcp> <dei> <vid>
        | mpls unicast | multicast
           <da> <sa>
           label0 <label> <tc> <ttl>
           [label1 <label> <tc> <ttl>
           [label2 <label> <tc> <ttl>
           [label3 <label> <tc> <ttl>]]]
        | pppoe <da> <sa> <session_id>]
     [nat ipv4 | ipv6 <addr> <port>]
     [ttl dec | keep]
     [stats]
     [time]
     [sym_crypto
        encrypt | decrypt
        type
        | cipher
           cipher_algo <algo> cipher_key <key> cipher_iv <iv>
        | cipher_auth
           cipher_algo <algo> cipher_key <key> cipher_iv <iv>
           auth_algo <algo> auth_key <key> digest_size <size>
        | aead
           aead_algo <algo> aead_key <key> aead_iv <iv> aead_aad <aad>
           digest_size <size>
        data_offset <data_offset>]

  where:
     <pa> ::= g | y | r | drop

Add bulk rules to table for specific pipeline instance ::

  pipeline <pipeline_name> table <table_id> rule add bulk <file_name> <n_rules>

  Where:
  - file_name = path to file
  - File line format = match <match> action <action>

Delete table rule for specific pipeline instance ::

  pipeline <pipeline_name> table <table_id> rule delete
     match <match>

Delete default table rule for specific pipeline instance ::

  pipeline <pipeline_name> table <table_id> rule delete
     match
        default

Add meter profile to the table for specific pipeline instance ::

  pipeline <pipeline_name> table <table_id> meter profile <meter_profile_id>
   add srtcm cir <cir> cbs <cbs> ebs <ebs>
   | trtcm cir <cir> pir <pir> cbs <cbs> pbs <pbs>

Delete meter profile from the table for specific pipeline instance ::

  pipeline <pipeline_name> table <table_id>
   meter profile <meter_profile_id> delete


Update the dscp table for meter or traffic manager action for specific
pipeline instance ::

   pipeline <pipeline_name> table <table_id> dscp <file_name>

   Where:
      - file_name = path to file
      - exactly 64 lines
      - File line format = <tc_id> <tc_queue_id> <color>, with <color> as: g | y | r


Pipeline enable/disable
~~~~~~~~~~~~~~~~~~~~~~~

   Enable given pipeline instance for specific data plane thread ::

    thread <thread_id> pipeline <pipeline_name> enable


   Disable given pipeline instance for specific data plane thread ::

    thread <thread_id> pipeline <pipeline_name> disable