doc/guides/prog_guide/rte_flow.rst

   1 ..  BSD LICENSE
   2     Copyright 2016 6WIND S.A.
   3     Copyright 2016 Mellanox.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of 6WIND S.A. nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 .. _Generic_flow_API:
  32
  33 Generic flow API (rte_flow)
  34 ===========================
  35
  36 Overview
  37 --------
  38
  39 This API provides a generic means to configure hardware to match specific
  40 ingress or egress traffic, alter its fate and query related counters
  41 according to any number of user-defined rules.
  42
  43 It is named *rte_flow* after the prefix used for all its symbols, and is
  44 defined in ``rte_flow.h``.
  45
  46 - Matching can be performed on packet data (protocol headers, payload) and
  47   properties (e.g. associated physical port, virtual device function ID).
  48
  49 - Possible operations include dropping traffic, diverting it to specific
  50   queues, to virtual/physical device functions or ports, performing tunnel
  51   offloads, adding marks and so on.
  52
  53 It is slightly higher-level than the legacy filtering framework which it
  54 encompasses and supersedes (including all functions and filter types) in
  55 order to expose a single interface with an unambiguous behavior that is
  56 common to all poll-mode drivers (PMDs).
  57
  58 Several methods to migrate existing applications are described in `API
  59 migration`_.
  60
  61 Flow rule
  62 ---------
  63
  64 Description
  65 ~~~~~~~~~~~
  66
  67 A flow rule is the combination of attributes with a matching pattern and a
  68 list of actions. Flow rules form the basis of this API.
  69
  70 Flow rules can have several distinct actions (such as counting,
  71 encapsulating, decapsulating before redirecting packets to a particular
  72 queue, etc.), instead of relying on several rules to achieve this and having
  73 applications deal with hardware implementation details regarding their
  74 order.
  75
  76 Support for different priority levels on a rule basis is provided, for
  77 example in order to force a more specific rule to come before a more generic
  78 one for packets matched by both. However hardware support for more than a
  79 single priority level cannot be guaranteed. When supported, the number of
  80 available priority levels is usually low, which is why they can also be
  81 implemented in software by PMDs (e.g. missing priority levels may be
  82 emulated by reordering rules).
  83
  84 In order to remain as hardware-agnostic as possible, by default all rules
  85 are considered to have the same priority, which means that the order between
  86 overlapping rules (when a packet is matched by several filters) is
  87 undefined.
  88
  89 PMDs may refuse to create overlapping rules at a given priority level when
  90 they can be detected (e.g. if a pattern matches an existing filter).
  91
  92 Thus predictable results for a given priority level can only be achieved
  93 with non-overlapping rules, using perfect matching on all protocol layers.
  94
  95 Flow rules can also be grouped, the flow rule priority is specific to the
  96 group they belong to. All flow rules in a given group are thus processed
  97 either before or after another group.
  98
  99 Support for multiple actions per rule may be implemented internally on top
 100 of non-default hardware priorities, as a result both features may not be
 101 simultaneously available to applications.
 102
 103 Considering that allowed pattern/actions combinations cannot be known in
 104 advance and would result in an impractically large number of capabilities to
 105 expose, a method is provided to validate a given rule from the current
 106 device configuration state.
 107
 108 This enables applications to check if the rule types they need is supported
 109 at initialization time, before starting their data path. This method can be
 110 used anytime, its only requirement being that the resources needed by a rule
 111 should exist (e.g. a target RX queue should be configured first).
 112
 113 Each defined rule is associated with an opaque handle managed by the PMD,
 114 applications are responsible for keeping it. These can be used for queries
 115 and rules management, such as retrieving counters or other data and
 116 destroying them.
 117
 118 To avoid resource leaks on the PMD side, handles must be explicitly
 119 destroyed by the application before releasing associated resources such as
 120 queues and ports.
 121
 122 The following sections cover:
 123
 124 - **Attributes** (represented by ``struct rte_flow_attr``): properties of a
 125   flow rule such as its direction (ingress or egress) and priority.
 126
 127 - **Pattern item** (represented by ``struct rte_flow_item``): part of a
 128   matching pattern that either matches specific packet data or traffic
 129   properties. It can also describe properties of the pattern itself, such as
 130   inverted matching.
 131
 132 - **Matching pattern**: traffic properties to look for, a combination of any
 133   number of items.
 134
 135 - **Actions** (represented by ``struct rte_flow_action``): operations to
 136   perform whenever a packet is matched by a pattern.
 137
 138 Attributes
 139 ~~~~~~~~~~
 140
 141 Attribute: Group
 142 ^^^^^^^^^^^^^^^^
 143
 144 Flow rules can be grouped by assigning them a common group number. Lower
 145 values have higher priority. Group 0 has the highest priority.
 146
 147 Although optional, applications are encouraged to group similar rules as
 148 much as possible to fully take advantage of hardware capabilities
 149 (e.g. optimized matching) and work around limitations (e.g. a single pattern
 150 type possibly allowed in a given group).
 151
 152 Note that support for more than a single group is not guaranteed.
 153
 154 Attribute: Priority
 155 ^^^^^^^^^^^^^^^^^^^
 156
 157 A priority level can be assigned to a flow rule. Like groups, lower values
 158 denote higher priority, with 0 as the maximum.
 159
 160 A rule with priority 0 in group 8 is always matched after a rule with
 161 priority 8 in group 0.
 162
 163 Group and priority levels are arbitrary and up to the application, they do
 164 not need to be contiguous nor start from 0, however the maximum number
 165 varies between devices and may be affected by existing flow rules.
 166
 167 If a packet is matched by several rules of a given group for a given
 168 priority level, the outcome is undefined. It can take any path, may be
 169 duplicated or even cause unrecoverable errors.
 170
 171 Note that support for more than a single priority level is not guaranteed.
 172
 173 Attribute: Traffic direction
 174 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 175
 176 Flow rules can apply to inbound and/or outbound traffic (ingress/egress).
 177
 178 Several pattern items and actions are valid and can be used in both
 179 directions. At least one direction must be specified.
 180
 181 Specifying both directions at once for a given rule is not recommended but
 182 may be valid in a few cases (e.g. shared counters).
 183
 184 Pattern item
 185 ~~~~~~~~~~~~
 186
 187 Pattern items fall in two categories:
 188
 189 - Matching protocol headers and packet data (ANY, RAW, ETH, VLAN, IPV4,
 190   IPV6, ICMP, UDP, TCP, SCTP, VXLAN, MPLS, GRE, ESP and so on), usually
 191   associated with a specification structure.
 192
 193 - Matching meta-data or affecting pattern processing (END, VOID, INVERT, PF,
 194   VF, PORT and so on), often without a specification structure.
 195
 196 Item specification structures are used to match specific values among
 197 protocol fields (or item properties). Documentation describes for each item
 198 whether they are associated with one and their type name if so.
 199
 200 Up to three structures of the same type can be set for a given item:
 201
 202 - ``spec``: values to match (e.g. a given IPv4 address).
 203
 204 - ``last``: upper bound for an inclusive range with corresponding fields in
 205   ``spec``.
 206
 207 - ``mask``: bit-mask applied to both ``spec`` and ``last`` whose purpose is
 208   to distinguish the values to take into account and/or partially mask them
 209   out (e.g. in order to match an IPv4 address prefix).
 210
 211 Usage restrictions and expected behavior:
 212
 213 - Setting either ``mask`` or ``last`` without ``spec`` is an error.
 214
 215 - Field values in ``last`` which are either 0 or equal to the corresponding
 216   values in ``spec`` are ignored; they do not generate a range. Nonzero
 217   values lower than those in ``spec`` are not supported.
 218
 219 - Setting ``spec`` and optionally ``last`` without ``mask`` causes the PMD
 220   to use the default mask defined for that item (defined as
 221   ``rte_flow_item_{name}_mask`` constants).
 222
 223 - Not setting any of them (assuming item type allows it) is equivalent to
 224   providing an empty (zeroed) ``mask`` for broad (nonspecific) matching.
 225
 226 - ``mask`` is a simple bit-mask applied before interpreting the contents of
 227   ``spec`` and ``last``, which may yield unexpected results if not used
 228   carefully. For example, if for an IPv4 address field, ``spec`` provides
 229   *10.1.2.3*, ``last`` provides *10.3.4.5* and ``mask`` provides
 230   *255.255.0.0*, the effective range becomes *10.1.0.0* to *10.3.255.255*.
 231
 232 Example of an item specification matching an Ethernet header:
 233
 234 .. _table_rte_flow_pattern_item_example:
 235
 236 .. table:: Ethernet item
 237
 238    +----------+----------+--------------------+
 239    | Field    | Subfield | Value              |
 240    +==========+==========+====================+
 241    | ``spec`` | ``src``  | ``00:01:02:03:04`` |
 242    |          +----------+--------------------+
 243    |          | ``dst``  | ``00:2a:66:00:01`` |
 244    |          +----------+--------------------+
 245    |          | ``type`` | ``0x22aa``         |
 246    +----------+----------+--------------------+
 247    | ``last`` | unspecified                   |
 248    +----------+----------+--------------------+
 249    | ``mask`` | ``src``  | ``00:ff:ff:ff:00`` |
 250    |          +----------+--------------------+
 251    |          | ``dst``  | ``00:00:00:00:ff`` |
 252    |          +----------+--------------------+
 253    |          | ``type`` | ``0x0000``         |
 254    +----------+----------+--------------------+
 255
 256 Non-masked bits stand for any value (shown as ``?`` below), Ethernet headers
 257 with the following properties are thus matched:
 258
 259 - ``src``: ``??:01:02:03:??``
 260 - ``dst``: ``??:??:??:??:01``
 261 - ``type``: ``0x????``
 262
 263 Matching pattern
 264 ~~~~~~~~~~~~~~~~
 265
 266 A pattern is formed by stacking items starting from the lowest protocol
 267 layer to match. This stacking restriction does not apply to meta items which
 268 can be placed anywhere in the stack without affecting the meaning of the
 269 resulting pattern.
 270
 271 Patterns are terminated by END items.
 272
 273 Examples:
 274
 275 .. _table_rte_flow_tcpv4_as_l4:
 276
 277 .. table:: TCPv4 as L4
 278
 279    +-------+----------+
 280    | Index | Item     |
 281    +=======+==========+
 282    | 0     | Ethernet |
 283    +-------+----------+
 284    | 1     | IPv4     |
 285    +-------+----------+
 286    | 2     | TCP      |
 287    +-------+----------+
 288    | 3     | END      |
 289    +-------+----------+
 290
 291 |
 292
 293 .. _table_rte_flow_tcpv6_in_vxlan:
 294
 295 .. table:: TCPv6 in VXLAN
 296
 297    +-------+------------+
 298    | Index | Item       |
 299    +=======+============+
 300    | 0     | Ethernet   |
 301    +-------+------------+
 302    | 1     | IPv4       |
 303    +-------+------------+
 304    | 2     | UDP        |
 305    +-------+------------+
 306    | 3     | VXLAN      |
 307    +-------+------------+
 308    | 4     | Ethernet   |
 309    +-------+------------+
 310    | 5     | IPv6       |
 311    +-------+------------+
 312    | 6     | TCP        |
 313    +-------+------------+
 314    | 7     | END        |
 315    +-------+------------+
 316
 317 |
 318
 319 .. _table_rte_flow_tcpv4_as_l4_meta:
 320
 321 .. table:: TCPv4 as L4 with meta items
 322
 323    +-------+----------+
 324    | Index | Item     |
 325    +=======+==========+
 326    | 0     | VOID     |
 327    +-------+----------+
 328    | 1     | Ethernet |
 329    +-------+----------+
 330    | 2     | VOID     |
 331    +-------+----------+
 332    | 3     | IPv4     |
 333    +-------+----------+
 334    | 4     | TCP      |
 335    +-------+----------+
 336    | 5     | VOID     |
 337    +-------+----------+
 338    | 6     | VOID     |
 339    +-------+----------+
 340    | 7     | END      |
 341    +-------+----------+
 342
 343 The above example shows how meta items do not affect packet data matching
 344 items, as long as those remain stacked properly. The resulting matching
 345 pattern is identical to "TCPv4 as L4".
 346
 347 .. _table_rte_flow_udpv6_anywhere:
 348
 349 .. table:: UDPv6 anywhere
 350
 351    +-------+------+
 352    | Index | Item |
 353    +=======+======+
 354    | 0     | IPv6 |
 355    +-------+------+
 356    | 1     | UDP  |
 357    +-------+------+
 358    | 2     | END  |
 359    +-------+------+
 360
 361 If supported by the PMD, omitting one or several protocol layers at the
 362 bottom of the stack as in the above example (missing an Ethernet
 363 specification) enables looking up anywhere in packets.
 364
 365 It is unspecified whether the payload of supported encapsulations
 366 (e.g. VXLAN payload) is matched by such a pattern, which may apply to inner,
 367 outer or both packets.
 368
 369 .. _table_rte_flow_invalid_l3:
 370
 371 .. table:: Invalid, missing L3
 372
 373    +-------+----------+
 374    | Index | Item     |
 375    +=======+==========+
 376    | 0     | Ethernet |
 377    +-------+----------+
 378    | 1     | UDP      |
 379    +-------+----------+
 380    | 2     | END      |
 381    +-------+----------+
 382
 383 The above pattern is invalid due to a missing L3 specification between L2
 384 (Ethernet) and L4 (UDP). Doing so is only allowed at the bottom and at the
 385 top of the stack.
 386
 387 Meta item types
 388 ~~~~~~~~~~~~~~~
 389
 390 They match meta-data or affect pattern processing instead of matching packet
 391 data directly, most of them do not need a specification structure. This
 392 particularity allows them to be specified anywhere in the stack without
 393 causing any side effect.
 394
 395 Item: ``END``
 396 ^^^^^^^^^^^^^
 397
 398 End marker for item lists. Prevents further processing of items, thereby
 399 ending the pattern.
 400
 401 - Its numeric value is 0 for convenience.
 402 - PMD support is mandatory.
 403 - ``spec``, ``last`` and ``mask`` are ignored.
 404
 405 .. _table_rte_flow_item_end:
 406
 407 .. table:: END
 408
 409    +----------+---------+
 410    | Field    | Value   |
 411    +==========+=========+
 412    | ``spec`` | ignored |
 413    +----------+---------+
 414    | ``last`` | ignored |
 415    +----------+---------+
 416    | ``mask`` | ignored |
 417    +----------+---------+
 418
 419 Item: ``VOID``
 420 ^^^^^^^^^^^^^^
 421
 422 Used as a placeholder for convenience. It is ignored and simply discarded by
 423 PMDs.
 424
 425 - PMD support is mandatory.
 426 - ``spec``, ``last`` and ``mask`` are ignored.
 427
 428 .. _table_rte_flow_item_void:
 429
 430 .. table:: VOID
 431
 432    +----------+---------+
 433    | Field    | Value   |
 434    +==========+=========+
 435    | ``spec`` | ignored |
 436    +----------+---------+
 437    | ``last`` | ignored |
 438    +----------+---------+
 439    | ``mask`` | ignored |
 440    +----------+---------+
 441
 442 One usage example for this type is generating rules that share a common
 443 prefix quickly without reallocating memory, only by updating item types:
 444
 445 .. _table_rte_flow_item_void_example:
 446
 447 .. table:: TCP, UDP or ICMP as L4
 448
 449    +-------+--------------------+
 450    | Index | Item               |
 451    +=======+====================+
 452    | 0     | Ethernet           |
 453    +-------+--------------------+
 454    | 1     | IPv4               |
 455    +-------+------+------+------+
 456    | 2     | UDP  | VOID | VOID |
 457    +-------+------+------+------+
 458    | 3     | VOID | TCP  | VOID |
 459    +-------+------+------+------+
 460    | 4     | VOID | VOID | ICMP |
 461    +-------+------+------+------+
 462    | 5     | END                |
 463    +-------+--------------------+
 464
 465 Item: ``INVERT``
 466 ^^^^^^^^^^^^^^^^
 467
 468 Inverted matching, i.e. process packets that do not match the pattern.
 469
 470 - ``spec``, ``last`` and ``mask`` are ignored.
 471
 472 .. _table_rte_flow_item_invert:
 473
 474 .. table:: INVERT
 475
 476    +----------+---------+
 477    | Field    | Value   |
 478    +==========+=========+
 479    | ``spec`` | ignored |
 480    +----------+---------+
 481    | ``last`` | ignored |
 482    +----------+---------+
 483    | ``mask`` | ignored |
 484    +----------+---------+
 485
 486 Usage example, matching non-TCPv4 packets only:
 487
 488 .. _table_rte_flow_item_invert_example:
 489
 490 .. table:: Anything but TCPv4
 491
 492    +-------+----------+
 493    | Index | Item     |
 494    +=======+==========+
 495    | 0     | INVERT   |
 496    +-------+----------+
 497    | 1     | Ethernet |
 498    +-------+----------+
 499    | 2     | IPv4     |
 500    +-------+----------+
 501    | 3     | TCP      |
 502    +-------+----------+
 503    | 4     | END      |
 504    +-------+----------+
 505
 506 Item: ``PF``
 507 ^^^^^^^^^^^^
 508
 509 Matches packets addressed to the physical function of the device.
 510
 511 If the underlying device function differs from the one that would normally
 512 receive the matched traffic, specifying this item prevents it from reaching
 513 that device unless the flow rule contains a `Action: PF`_. Packets are not
 514 duplicated between device instances by default.
 515
 516 - Likely to return an error or never match any traffic if applied to a VF
 517   device.
 518 - Can be combined with any number of `Item: VF`_ to match both PF and VF
 519   traffic.
 520 - ``spec``, ``last`` and ``mask`` must not be set.
 521
 522 .. _table_rte_flow_item_pf:
 523
 524 .. table:: PF
 525
 526    +----------+-------+
 527    | Field    | Value |
 528    +==========+=======+
 529    | ``spec`` | unset |
 530    +----------+-------+
 531    | ``last`` | unset |
 532    +----------+-------+
 533    | ``mask`` | unset |
 534    +----------+-------+
 535
 536 Item: ``VF``
 537 ^^^^^^^^^^^^
 538
 539 Matches packets addressed to a virtual function ID of the device.
 540
 541 If the underlying device function differs from the one that would normally
 542 receive the matched traffic, specifying this item prevents it from reaching
 543 that device unless the flow rule contains a `Action: VF`_. Packets are not
 544 duplicated between device instances by default.
 545
 546 - Likely to return an error or never match any traffic if this causes a VF
 547   device to match traffic addressed to a different VF.
 548 - Can be specified multiple times to match traffic addressed to several VF
 549   IDs.
 550 - Can be combined with a PF item to match both PF and VF traffic.
 551 - Default ``mask`` matches any VF ID.
 552
 553 .. _table_rte_flow_item_vf:
 554
 555 .. table:: VF
 556
 557    +----------+----------+---------------------------+
 558    | Field    | Subfield | Value                     |
 559    +==========+==========+===========================+
 560    | ``spec`` | ``id``   | destination VF ID         |
 561    +----------+----------+---------------------------+
 562    | ``last`` | ``id``   | upper range value         |
 563    +----------+----------+---------------------------+
 564    | ``mask`` | ``id``   | zeroed to match any VF ID |
 565    +----------+----------+---------------------------+
 566
 567 Item: ``PORT``
 568 ^^^^^^^^^^^^^^
 569
 570 Matches packets coming from the specified physical port of the underlying
 571 device.
 572
 573 The first PORT item overrides the physical port normally associated with the
 574 specified DPDK input port (port_id). This item can be provided several times
 575 to match additional physical ports.
 576
 577 Note that physical ports are not necessarily tied to DPDK input ports
 578 (port_id) when those are not under DPDK control. Possible values are
 579 specific to each device, they are not necessarily indexed from zero and may
 580 not be contiguous.
 581
 582 As a device property, the list of allowed values as well as the value
 583 associated with a port_id should be retrieved by other means.
 584
 585 - Default ``mask`` matches any port index.
 586
 587 .. _table_rte_flow_item_port:
 588
 589 .. table:: PORT
 590
 591    +----------+-----------+--------------------------------+
 592    | Field    | Subfield  | Value                          |
 593    +==========+===========+================================+
 594    | ``spec`` | ``index`` | physical port index            |
 595    +----------+-----------+--------------------------------+
 596    | ``last`` | ``index`` | upper range value              |
 597    +----------+-----------+--------------------------------+
 598    | ``mask`` | ``index`` | zeroed to match any port index |
 599    +----------+-----------+--------------------------------+
 600
 601 Data matching item types
 602 ~~~~~~~~~~~~~~~~~~~~~~~~
 603
 604 Most of these are basically protocol header definitions with associated
 605 bit-masks. They must be specified (stacked) from lowest to highest protocol
 606 layer to form a matching pattern.
 607
 608 The following list is not exhaustive, new protocols will be added in the
 609 future.
 610
 611 Item: ``ANY``
 612 ^^^^^^^^^^^^^
 613
 614 Matches any protocol in place of the current layer, a single ANY may also
 615 stand for several protocol layers.
 616
 617 This is usually specified as the first pattern item when looking for a
 618 protocol anywhere in a packet.
 619
 620 - Default ``mask`` stands for any number of layers.
 621
 622 .. _table_rte_flow_item_any:
 623
 624 .. table:: ANY
 625
 626    +----------+----------+--------------------------------------+
 627    | Field    | Subfield | Value                                |
 628    +==========+==========+======================================+
 629    | ``spec`` | ``num``  | number of layers covered             |
 630    +----------+----------+--------------------------------------+
 631    | ``last`` | ``num``  | upper range value                    |
 632    +----------+----------+--------------------------------------+
 633    | ``mask`` | ``num``  | zeroed to cover any number of layers |
 634    +----------+----------+--------------------------------------+
 635
 636 Example for VXLAN TCP payload matching regardless of outer L3 (IPv4 or IPv6)
 637 and L4 (UDP) both matched by the first ANY specification, and inner L3 (IPv4
 638 or IPv6) matched by the second ANY specification:
 639
 640 .. _table_rte_flow_item_any_example:
 641
 642 .. table:: TCP in VXLAN with wildcards
 643
 644    +-------+------+----------+----------+-------+
 645    | Index | Item | Field    | Subfield | Value |
 646    +=======+======+==========+==========+=======+
 647    | 0     | Ethernet                           |
 648    +-------+------+----------+----------+-------+
 649    | 1     | ANY  | ``spec`` | ``num``  | 2     |
 650    +-------+------+----------+----------+-------+
 651    | 2     | VXLAN                              |
 652    +-------+------------------------------------+
 653    | 3     | Ethernet                           |
 654    +-------+------+----------+----------+-------+
 655    | 4     | ANY  | ``spec`` | ``num``  | 1     |
 656    +-------+------+----------+----------+-------+
 657    | 5     | TCP                                |
 658    +-------+------------------------------------+
 659    | 6     | END                                |
 660    +-------+------------------------------------+
 661
 662 Item: ``RAW``
 663 ^^^^^^^^^^^^^
 664
 665 Matches a byte string of a given length at a given offset.
 666
 667 Offset is either absolute (using the start of the packet) or relative to the
 668 end of the previous matched item in the stack, in which case negative values
 669 are allowed.
 670
 671 If search is enabled, offset is used as the starting point. The search area
 672 can be delimited by setting limit to a nonzero value, which is the maximum
 673 number of bytes after offset where the pattern may start.
 674
 675 Matching a zero-length pattern is allowed, doing so resets the relative
 676 offset for subsequent items.
 677
 678 - This type does not support ranges (``last`` field).
 679 - Default ``mask`` matches all fields exactly.
 680
 681 .. _table_rte_flow_item_raw:
 682
 683 .. table:: RAW
 684
 685    +----------+--------------+-------------------------------------------------+
 686    | Field    | Subfield     | Value                                           |
 687    +==========+==============+=================================================+
 688    | ``spec`` | ``relative`` | look for pattern after the previous item        |
 689    |          +--------------+-------------------------------------------------+
 690    |          | ``search``   | search pattern from offset (see also ``limit``) |
 691    |          +--------------+-------------------------------------------------+
 692    |          | ``reserved`` | reserved, must be set to zero                   |
 693    |          +--------------+-------------------------------------------------+
 694    |          | ``offset``   | absolute or relative offset for ``pattern``     |
 695    |          +--------------+-------------------------------------------------+
 696    |          | ``limit``    | search area limit for start of ``pattern``      |
 697    |          +--------------+-------------------------------------------------+
 698    |          | ``length``   | ``pattern`` length                              |
 699    |          +--------------+-------------------------------------------------+
 700    |          | ``pattern``  | byte string to look for                         |
 701    +----------+--------------+-------------------------------------------------+
 702    | ``last`` | if specified, either all 0 or with the same values as ``spec`` |
 703    +----------+----------------------------------------------------------------+
 704    | ``mask`` | bit-mask applied to ``spec`` values with usual behavior        |
 705    +----------+----------------------------------------------------------------+
 706
 707 Example pattern looking for several strings at various offsets of a UDP
 708 payload, using combined RAW items:
 709
 710 .. _table_rte_flow_item_raw_example:
 711
 712 .. table:: UDP payload matching
 713
 714    +-------+------+----------+--------------+-------+
 715    | Index | Item | Field    | Subfield     | Value |
 716    +=======+======+==========+==============+=======+
 717    | 0     | Ethernet                               |
 718    +-------+----------------------------------------+
 719    | 1     | IPv4                                   |
 720    +-------+----------------------------------------+
 721    | 2     | UDP                                    |
 722    +-------+------+----------+--------------+-------+
 723    | 3     | RAW  | ``spec`` | ``relative`` | 1     |
 724    |       |      |          +--------------+-------+
 725    |       |      |          | ``search``   | 1     |
 726    |       |      |          +--------------+-------+
 727    |       |      |          | ``offset``   | 10    |
 728    |       |      |          +--------------+-------+
 729    |       |      |          | ``limit``    | 0     |
 730    |       |      |          +--------------+-------+
 731    |       |      |          | ``length``   | 3     |
 732    |       |      |          +--------------+-------+
 733    |       |      |          | ``pattern``  | "foo" |
 734    +-------+------+----------+--------------+-------+
 735    | 4     | RAW  | ``spec`` | ``relative`` | 1     |
 736    |       |      |          +--------------+-------+
 737    |       |      |          | ``search``   | 0     |
 738    |       |      |          +--------------+-------+
 739    |       |      |          | ``offset``   | 20    |
 740    |       |      |          +--------------+-------+
 741    |       |      |          | ``limit``    | 0     |
 742    |       |      |          +--------------+-------+
 743    |       |      |          | ``length``   | 3     |
 744    |       |      |          +--------------+-------+
 745    |       |      |          | ``pattern``  | "bar" |
 746    +-------+------+----------+--------------+-------+
 747    | 5     | RAW  | ``spec`` | ``relative`` | 1     |
 748    |       |      |          +--------------+-------+
 749    |       |      |          | ``search``   | 0     |
 750    |       |      |          +--------------+-------+
 751    |       |      |          | ``offset``   | -29   |
 752    |       |      |          +--------------+-------+
 753    |       |      |          | ``limit``    | 0     |
 754    |       |      |          +--------------+-------+
 755    |       |      |          | ``length``   | 3     |
 756    |       |      |          +--------------+-------+
 757    |       |      |          | ``pattern``  | "baz" |
 758    +-------+------+----------+--------------+-------+
 759    | 6     | END                                    |
 760    +-------+----------------------------------------+
 761
 762 This translates to:
 763
 764 - Locate "foo" at least 10 bytes deep inside UDP payload.
 765 - Locate "bar" after "foo" plus 20 bytes.
 766 - Locate "baz" after "bar" minus 29 bytes.
 767
 768 Such a packet may be represented as follows (not to scale)::
 769
 770  0                     >= 10 B           == 20 B
 771  |                  |<--------->|     |<--------->|
 772  |                  |           |     |           |
 773  |-----|------|-----|-----|-----|-----|-----------|-----|------|
 774  | ETH | IPv4 | UDP | ... | baz | foo | ......... | bar | .... |
 775  |-----|------|-----|-----|-----|-----|-----------|-----|------|
 776                           |                             |
 777                           |<--------------------------->|
 778                                       == 29 B
 779
 780 Note that matching subsequent pattern items would resume after "baz", not
 781 "bar" since matching is always performed after the previous item of the
 782 stack.
 783
 784 Item: ``ETH``
 785 ^^^^^^^^^^^^^
 786
 787 Matches an Ethernet header.
 788
 789 - ``dst``: destination MAC.
 790 - ``src``: source MAC.
 791 - ``type``: EtherType.
 792 - Default ``mask`` matches destination and source addresses only.
 793
 794 Item: ``VLAN``
 795 ^^^^^^^^^^^^^^
 796
 797 Matches an 802.1Q/ad VLAN tag.
 798
 799 - ``tpid``: tag protocol identifier.
 800 - ``tci``: tag control information.
 801 - Default ``mask`` matches TCI only.
 802
 803 Item: ``IPV4``
 804 ^^^^^^^^^^^^^^
 805
 806 Matches an IPv4 header.
 807
 808 Note: IPv4 options are handled by dedicated pattern items.
 809
 810 - ``hdr``: IPv4 header definition (``rte_ip.h``).
 811 - Default ``mask`` matches source and destination addresses only.
 812
 813 Item: ``IPV6``
 814 ^^^^^^^^^^^^^^
 815
 816 Matches an IPv6 header.
 817
 818 Note: IPv6 options are handled by dedicated pattern items.
 819
 820 - ``hdr``: IPv6 header definition (``rte_ip.h``).
 821 - Default ``mask`` matches source and destination addresses only.
 822
 823 Item: ``ICMP``
 824 ^^^^^^^^^^^^^^
 825
 826 Matches an ICMP header.
 827
 828 - ``hdr``: ICMP header definition (``rte_icmp.h``).
 829 - Default ``mask`` matches ICMP type and code only.
 830
 831 Item: ``UDP``
 832 ^^^^^^^^^^^^^
 833
 834 Matches a UDP header.
 835
 836 - ``hdr``: UDP header definition (``rte_udp.h``).
 837 - Default ``mask`` matches source and destination ports only.
 838
 839 Item: ``TCP``
 840 ^^^^^^^^^^^^^
 841
 842 Matches a TCP header.
 843
 844 - ``hdr``: TCP header definition (``rte_tcp.h``).
 845 - Default ``mask`` matches source and destination ports only.
 846
 847 Item: ``SCTP``
 848 ^^^^^^^^^^^^^^
 849
 850 Matches a SCTP header.
 851
 852 - ``hdr``: SCTP header definition (``rte_sctp.h``).
 853 - Default ``mask`` matches source and destination ports only.
 854
 855 Item: ``VXLAN``
 856 ^^^^^^^^^^^^^^^
 857
 858 Matches a VXLAN header (RFC 7348).
 859
 860 - ``flags``: normally 0x08 (I flag).
 861 - ``rsvd0``: reserved, normally 0x000000.
 862 - ``vni``: VXLAN network identifier.
 863 - ``rsvd1``: reserved, normally 0x00.
 864 - Default ``mask`` matches VNI only.
 865
 866 Item: ``E_TAG``
 867 ^^^^^^^^^^^^^^^
 868
 869 Matches an IEEE 802.1BR E-Tag header.
 870
 871 - ``tpid``: tag protocol identifier (0x893F)
 872 - ``epcp_edei_in_ecid_b``: E-Tag control information (E-TCI), E-PCP (3b),
 873   E-DEI (1b), ingress E-CID base (12b).
 874 - ``rsvd_grp_ecid_b``: reserved (2b), GRP (2b), E-CID base (12b).
 875 - ``in_ecid_e``: ingress E-CID ext.
 876 - ``ecid_e``: E-CID ext.
 877 - Default ``mask`` simultaneously matches GRP and E-CID base.
 878
 879 Item: ``NVGRE``
 880 ^^^^^^^^^^^^^^^
 881
 882 Matches a NVGRE header (RFC 7637).
 883
 884 - ``c_k_s_rsvd0_ver``: checksum (1b), undefined (1b), key bit (1b),
 885   sequence number (1b), reserved 0 (9b), version (3b). This field must have
 886   value 0x2000 according to RFC 7637.
 887 - ``protocol``: protocol type (0x6558).
 888 - ``tni``: virtual subnet ID.
 889 - ``flow_id``: flow ID.
 890 - Default ``mask`` matches TNI only.
 891
 892 Item: ``MPLS``
 893 ^^^^^^^^^^^^^^
 894
 895 Matches a MPLS header.
 896
 897 - ``label_tc_s_ttl``: label, TC, Bottom of Stack and TTL.
 898 - Default ``mask`` matches label only.
 899
 900 Item: ``GRE``
 901 ^^^^^^^^^^^^^
 902
 903 Matches a GRE header.
 904
 905 - ``c_rsvd0_ver``: checksum, reserved 0 and version.
 906 - ``protocol``: protocol type.
 907 - Default ``mask`` matches protocol only.
 908
 909 Item: ``FUZZY``
 910 ^^^^^^^^^^^^^^^
 911
 912 Fuzzy pattern match, expect faster than default.
 913
 914 This is for device that support fuzzy match option. Usually a fuzzy match is
 915 fast but the cost is accuracy. i.e. Signature Match only match pattern's hash
 916 value, but it is possible two different patterns have the same hash value.
 917
 918 Matching accuracy level can be configured by threshold. Driver can divide the
 919 range of threshold and map to different accuracy levels that device support.
 920
 921 Threshold 0 means perfect match (no fuzziness), while threshold 0xffffffff
 922 means fuzziest match.
 923
 924 .. _table_rte_flow_item_fuzzy:
 925
 926 .. table:: FUZZY
 927
 928    +----------+---------------+--------------------------------------------------+
 929    | Field    |   Subfield    | Value                                            |
 930    +==========+===============+==================================================+
 931    | ``spec`` | ``threshold`` | 0 as perfect match, 0xffffffff as fuzziest match |
 932    +----------+---------------+--------------------------------------------------+
 933    | ``last`` | ``threshold`` | upper range value                                |
 934    +----------+---------------+--------------------------------------------------+
 935    | ``mask`` | ``threshold`` | bit-mask apply to "spec" and "last"              |
 936    +----------+---------------+--------------------------------------------------+
 937
 938 Usage example, fuzzy match a TCPv4 packets:
 939
 940 .. _table_rte_flow_item_fuzzy_example:
 941
 942 .. table:: Fuzzy matching
 943
 944    +-------+----------+
 945    | Index | Item     |
 946    +=======+==========+
 947    | 0     | FUZZY    |
 948    +-------+----------+
 949    | 1     | Ethernet |
 950    +-------+----------+
 951    | 2     | IPv4     |
 952    +-------+----------+
 953    | 3     | TCP      |
 954    +-------+----------+
 955    | 4     | END      |
 956    +-------+----------+
 957
 958 Item: ``GTP``, ``GTPC``, ``GTPU``
 959 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 960
 961 Matches a GTPv1 header.
 962
 963 Note: GTP, GTPC and GTPU use the same structure. GTPC and GTPU item
 964 are defined for a user-friendly API when creating GTP-C and GTP-U
 965 flow rules.
 966
 967 - ``v_pt_rsv_flags``: version (3b), protocol type (1b), reserved (1b),
 968   extension header flag (1b), sequence number flag (1b), N-PDU number
 969   flag (1b).
 970 - ``msg_type``: message type.
 971 - ``msg_len``: message length.
 972 - ``teid``: tunnel endpoint identifier.
 973 - Default ``mask`` matches teid only.
 974
 975 Item: ``ESP``
 976 ^^^^^^^^^^^^^
 977
 978 Matches an ESP header.
 979
 980 - ``hdr``: ESP header definition (``rte_esp.h``).
 981 - Default ``mask`` matches SPI only.
 982
 983 Actions
 984 ~~~~~~~
 985
 986 Each possible action is represented by a type. Some have associated
 987 configuration structures. Several actions combined in a list can be affected
 988 to a flow rule. That list is not ordered.
 989
 990 They fall in three categories:
 991
 992 - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
 993   processing matched packets by subsequent flow rules, unless overridden
 994   with PASSTHRU.
 995
 996 - Non-terminating actions (PASSTHRU, DUP) that leave matched packets up for
 997   additional processing by subsequent flow rules.
 998
 999 - Other non-terminating meta actions that do not affect the fate of packets
1000   (END, VOID, MARK, FLAG, COUNT, SECURITY).
1001
1002 When several actions are combined in a flow rule, they should all have
1003 different types (e.g. dropping a packet twice is not possible).
1004
1005 Only the last action of a given type is taken into account. PMDs still
1006 perform error checking on the entire list.
1007
1008 Like matching patterns, action lists are terminated by END items.
1009
1010 *Note that PASSTHRU is the only action able to override a terminating rule.*
1011
1012 Example of action that redirects packets to queue index 10:
1013
1014 .. _table_rte_flow_action_example:
1015
1016 .. table:: Queue action
1017
1018    +-----------+-------+
1019    | Field     | Value |
1020    +===========+=======+
1021    | ``index`` | 10    |
1022    +-----------+-------+
1023
1024 Action lists examples, their order is not significant, applications must
1025 consider all actions to be performed simultaneously:
1026
1027 .. _table_rte_flow_count_and_drop:
1028
1029 .. table:: Count and drop
1030
1031    +-------+--------+
1032    | Index | Action |
1033    +=======+========+
1034    | 0     | COUNT  |
1035    +-------+--------+
1036    | 1     | DROP   |
1037    +-------+--------+
1038    | 2     | END    |
1039    +-------+--------+
1040
1041 |
1042
1043 .. _table_rte_flow_mark_count_redirect:
1044
1045 .. table:: Mark, count and redirect
1046
1047    +-------+--------+-----------+-------+
1048    | Index | Action | Field     | Value |
1049    +=======+========+===========+=======+
1050    | 0     | MARK   | ``mark``  | 0x2a  |
1051    +-------+--------+-----------+-------+
1052    | 1     | COUNT                      |
1053    +-------+--------+-----------+-------+
1054    | 2     | QUEUE  | ``queue`` | 10    |
1055    +-------+--------+-----------+-------+
1056    | 3     | END                        |
1057    +-------+----------------------------+
1058
1059 |
1060
1061 .. _table_rte_flow_redirect_queue_5:
1062
1063 .. table:: Redirect to queue 5
1064
1065    +-------+--------+-----------+-------+
1066    | Index | Action | Field     | Value |
1067    +=======+========+===========+=======+
1068    | 0     | DROP                       |
1069    +-------+--------+-----------+-------+
1070    | 1     | QUEUE  | ``queue`` | 5     |
1071    +-------+--------+-----------+-------+
1072    | 2     | END                        |
1073    +-------+----------------------------+
1074
1075 In the above example, considering both actions are performed simultaneously,
1076 the end result is that only QUEUE has any effect.
1077
1078 .. _table_rte_flow_redirect_queue_3:
1079
1080 .. table:: Redirect to queue 3
1081
1082    +-------+--------+-----------+-------+
1083    | Index | Action | Field     | Value |
1084    +=======+========+===========+=======+
1085    | 0     | QUEUE  | ``queue`` | 5     |
1086    +-------+--------+-----------+-------+
1087    | 1     | VOID                       |
1088    +-------+--------+-----------+-------+
1089    | 2     | QUEUE  | ``queue`` | 3     |
1090    +-------+--------+-----------+-------+
1091    | 3     | END                        |
1092    +-------+----------------------------+
1093
1094 As previously described, only the last action of a given type found in the
1095 list is taken into account. The above example also shows that VOID is
1096 ignored.
1097
1098 Action types
1099 ~~~~~~~~~~~~
1100
1101 Common action types are described in this section. Like pattern item types,
1102 this list is not exhaustive as new actions will be added in the future.
1103
1104 Action: ``END``
1105 ^^^^^^^^^^^^^^^
1106
1107 End marker for action lists. Prevents further processing of actions, thereby
1108 ending the list.
1109
1110 - Its numeric value is 0 for convenience.
1111 - PMD support is mandatory.
1112 - No configurable properties.
1113
1114 .. _table_rte_flow_action_end:
1115
1116 .. table:: END
1117
1118    +---------------+
1119    | Field         |
1120    +===============+
1121    | no properties |
1122    +---------------+
1123
1124 Action: ``VOID``
1125 ^^^^^^^^^^^^^^^^
1126
1127 Used as a placeholder for convenience. It is ignored and simply discarded by
1128 PMDs.
1129
1130 - PMD support is mandatory.
1131 - No configurable properties.
1132
1133 .. _table_rte_flow_action_void:
1134
1135 .. table:: VOID
1136
1137    +---------------+
1138    | Field         |
1139    +===============+
1140    | no properties |
1141    +---------------+
1142
1143 Action: ``PASSTHRU``
1144 ^^^^^^^^^^^^^^^^^^^^
1145
1146 Leaves packets up for additional processing by subsequent flow rules. This
1147 is the default when a rule does not contain a terminating action, but can be
1148 specified to force a rule to become non-terminating.
1149
1150 - No configurable properties.
1151
1152 .. _table_rte_flow_action_passthru:
1153
1154 .. table:: PASSTHRU
1155
1156    +---------------+
1157    | Field         |
1158    +===============+
1159    | no properties |
1160    +---------------+
1161
1162 Example to copy a packet to a queue and continue processing by subsequent
1163 flow rules:
1164
1165 .. _table_rte_flow_action_passthru_example:
1166
1167 .. table:: Copy to queue 8
1168
1169    +-------+--------+-----------+-------+
1170    | Index | Action | Field     | Value |
1171    +=======+========+===========+=======+
1172    | 0     | PASSTHRU                   |
1173    +-------+--------+-----------+-------+
1174    | 1     | QUEUE  | ``queue`` | 8     |
1175    +-------+--------+-----------+-------+
1176    | 2     | END                        |
1177    +-------+----------------------------+
1178
1179 Action: ``MARK``
1180 ^^^^^^^^^^^^^^^^
1181
1182 Attaches an integer value to packets and sets ``PKT_RX_FDIR`` and
1183 ``PKT_RX_FDIR_ID`` mbuf flags.
1184
1185 This value is arbitrary and application-defined. Maximum allowed value
1186 depends on the underlying implementation. It is returned in the
1187 ``hash.fdir.hi`` mbuf field.
1188
1189 .. _table_rte_flow_action_mark:
1190
1191 .. table:: MARK
1192
1193    +--------+--------------------------------------+
1194    | Field  | Value                                |
1195    +========+======================================+
1196    | ``id`` | integer value to return with packets |
1197    +--------+--------------------------------------+
1198
1199 Action: ``FLAG``
1200 ^^^^^^^^^^^^^^^^
1201
1202 Flags packets. Similar to `Action: MARK`_ without a specific value; only
1203 sets the ``PKT_RX_FDIR`` mbuf flag.
1204
1205 - No configurable properties.
1206
1207 .. _table_rte_flow_action_flag:
1208
1209 .. table:: FLAG
1210
1211    +---------------+
1212    | Field         |
1213    +===============+
1214    | no properties |
1215    +---------------+
1216
1217 Action: ``QUEUE``
1218 ^^^^^^^^^^^^^^^^^
1219
1220 Assigns packets to a given queue index.
1221
1222 - Terminating by default.
1223
1224 .. _table_rte_flow_action_queue:
1225
1226 .. table:: QUEUE
1227
1228    +-----------+--------------------+
1229    | Field     | Value              |
1230    +===========+====================+
1231    | ``index`` | queue index to use |
1232    +-----------+--------------------+
1233
1234 Action: ``DROP``
1235 ^^^^^^^^^^^^^^^^
1236
1237 Drop packets.
1238
1239 - No configurable properties.
1240 - Terminating by default.
1241 - PASSTHRU overrides this action if both are specified.
1242
1243 .. _table_rte_flow_action_drop:
1244
1245 .. table:: DROP
1246
1247    +---------------+
1248    | Field         |
1249    +===============+
1250    | no properties |
1251    +---------------+
1252
1253 Action: ``COUNT``
1254 ^^^^^^^^^^^^^^^^^
1255
1256 Enables counters for this rule.
1257
1258 These counters can be retrieved and reset through ``rte_flow_query()``, see
1259 ``struct rte_flow_query_count``.
1260
1261 - Counters can be retrieved with ``rte_flow_query()``.
1262 - No configurable properties.
1263
1264 .. _table_rte_flow_action_count:
1265
1266 .. table:: COUNT
1267
1268    +---------------+
1269    | Field         |
1270    +===============+
1271    | no properties |
1272    +---------------+
1273
1274 Query structure to retrieve and reset flow rule counters:
1275
1276 .. _table_rte_flow_query_count:
1277
1278 .. table:: COUNT query
1279
1280    +---------------+-----+-----------------------------------+
1281    | Field         | I/O | Value                             |
1282    +===============+=====+===================================+
1283    | ``reset``     | in  | reset counter after query         |
1284    +---------------+-----+-----------------------------------+
1285    | ``hits_set``  | out | ``hits`` field is set             |
1286    +---------------+-----+-----------------------------------+
1287    | ``bytes_set`` | out | ``bytes`` field is set            |
1288    +---------------+-----+-----------------------------------+
1289    | ``hits``      | out | number of hits for this rule      |
1290    +---------------+-----+-----------------------------------+
1291    | ``bytes``     | out | number of bytes through this rule |
1292    +---------------+-----+-----------------------------------+
1293
1294 Action: ``DUP``
1295 ^^^^^^^^^^^^^^^
1296
1297 Duplicates packets to a given queue index.
1298
1299 This is normally combined with QUEUE, however when used alone, it is
1300 actually similar to QUEUE + PASSTHRU.
1301
1302 - Non-terminating by default.
1303
1304 .. _table_rte_flow_action_dup:
1305
1306 .. table:: DUP
1307
1308    +-----------+------------------------------------+
1309    | Field     | Value                              |
1310    +===========+====================================+
1311    | ``index`` | queue index to duplicate packet to |
1312    +-----------+------------------------------------+
1313
1314 Action: ``RSS``
1315 ^^^^^^^^^^^^^^^
1316
1317 Similar to QUEUE, except RSS is additionally performed on packets to spread
1318 them among several queues according to the provided parameters.
1319
1320 Note: RSS hash result is stored in the ``hash.rss`` mbuf field which
1321 overlaps ``hash.fdir.lo``. Since `Action: MARK`_ sets the ``hash.fdir.hi``
1322 field only, both can be requested simultaneously.
1323
1324 - Terminating by default.
1325
1326 .. _table_rte_flow_action_rss:
1327
1328 .. table:: RSS
1329
1330    +--------------+------------------------------+
1331    | Field        | Value                        |
1332    +==============+==============================+
1333    | ``rss_conf`` | RSS parameters               |
1334    +--------------+------------------------------+
1335    | ``num``      | number of entries in queue[] |
1336    +--------------+------------------------------+
1337    | ``queue[]``  | queue indices to use         |
1338    +--------------+------------------------------+
1339
1340 Action: ``PF``
1341 ^^^^^^^^^^^^^^
1342
1343 Redirects packets to the physical function (PF) of the current device.
1344
1345 - No configurable properties.
1346 - Terminating by default.
1347
1348 .. _table_rte_flow_action_pf:
1349
1350 .. table:: PF
1351
1352    +---------------+
1353    | Field         |
1354    +===============+
1355    | no properties |
1356    +---------------+
1357
1358 Action: ``VF``
1359 ^^^^^^^^^^^^^^
1360
1361 Redirects packets to a virtual function (VF) of the current device.
1362
1363 Packets matched by a VF pattern item can be redirected to their original VF
1364 ID instead of the specified one. This parameter may not be available and is
1365 not guaranteed to work properly if the VF part is matched by a prior flow
1366 rule or if packets are not addressed to a VF in the first place.
1367
1368 - Terminating by default.
1369
1370 .. _table_rte_flow_action_vf:
1371
1372 .. table:: VF
1373
1374    +--------------+--------------------------------+
1375    | Field        | Value                          |
1376    +==============+================================+
1377    | ``original`` | use original VF ID if possible |
1378    +--------------+--------------------------------+
1379    | ``vf``       | VF ID to redirect packets to   |
1380    +--------------+--------------------------------+
1381
1382 Action: ``METER``
1383 ^^^^^^^^^^^^^^^^^
1384
1385 Applies a stage of metering and policing.
1386
1387 The metering and policing (MTR) object has to be first created using the
1388 rte_mtr_create() API function. The ID of the MTR object is specified as
1389 action parameter. More than one flow can use the same MTR object through
1390 the meter action. The MTR object can be further updated or queried using
1391 the rte_mtr* API.
1392
1393 - Non-terminating by default.
1394
1395 .. _table_rte_flow_action_meter:
1396
1397 .. table:: METER
1398
1399    +--------------+---------------+
1400    | Field        | Value         |
1401    +==============+===============+
1402    | ``mtr_id``   | MTR object ID |
1403    +--------------+---------------+
1404
1405 Action: ``SECURITY``
1406 ^^^^^^^^^^^^^^^^^^^^
1407
1408 Perform the security action on flows matched by the pattern items
1409 according to the configuration of the security session.
1410
1411 This action modifies the payload of matched flows. For INLINE_CRYPTO, the
1412 security protocol headers and IV are fully provided by the application as
1413 specified in the flow pattern. The payload of matching packets is
1414 encrypted on egress, and decrypted and authenticated on ingress.
1415 For INLINE_PROTOCOL, the security protocol is fully offloaded to HW,
1416 providing full encapsulation and decapsulation of packets in security
1417 protocols. The flow pattern specifies both the outer security header fields
1418 and the inner packet fields. The security session specified in the action
1419 must match the pattern parameters.
1420
1421 The security session specified in the action must be created on the same
1422 port as the flow action that is being specified.
1423
1424 The ingress/egress flow attribute should match that specified in the
1425 security session if the security session supports the definition of the
1426 direction.
1427
1428 Multiple flows can be configured to use the same security session.
1429
1430 - Non-terminating by default.
1431
1432 .. _table_rte_flow_action_security:
1433
1434 .. table:: SECURITY
1435
1436    +----------------------+--------------------------------------+
1437    | Field                | Value                                |
1438    +======================+======================================+
1439    | ``security_session`` | security session to apply            |
1440    +----------------------+--------------------------------------+
1441
1442 The following is an example of configuring IPsec inline using the
1443 INLINE_CRYPTO security session:
1444
1445 The encryption algorithm, keys and salt are part of the opaque
1446 ``rte_security_session``. The SA is identified according to the IP and ESP
1447 fields in the pattern items.
1448
1449 .. _table_rte_flow_item_esp_inline_example:
1450
1451 .. table:: IPsec inline crypto flow pattern items.
1452
1453    +-------+----------+
1454    | Index | Item     |
1455    +=======+==========+
1456    | 0     | Ethernet |
1457    +-------+----------+
1458    | 1     | IPv4     |
1459    +-------+----------+
1460    | 2     | ESP      |
1461    +-------+----------+
1462    | 3     | END      |
1463    +-------+----------+
1464
1465 .. _table_rte_flow_action_esp_inline_example:
1466
1467 .. table:: IPsec inline flow actions.
1468
1469    +-------+----------+
1470    | Index | Action   |
1471    +=======+==========+
1472    | 0     | SECURITY |
1473    +-------+----------+
1474    | 1     | END      |
1475    +-------+----------+
1476
1477 Negative types
1478 ~~~~~~~~~~~~~~
1479
1480 All specified pattern items (``enum rte_flow_item_type``) and actions
1481 (``enum rte_flow_action_type``) use positive identifiers.
1482
1483 The negative space is reserved for dynamic types generated by PMDs during
1484 run-time. PMDs may encounter them as a result but must not accept negative
1485 identifiers they are not aware of.
1486
1487 A method to generate them remains to be defined.
1488
1489 Planned types
1490 ~~~~~~~~~~~~~
1491
1492 Pattern item types will be added as new protocols are implemented.
1493
1494 Variable headers support through dedicated pattern items, for example in
1495 order to match specific IPv4 options and IPv6 extension headers would be
1496 stacked after IPv4/IPv6 items.
1497
1498 Other action types are planned but are not defined yet. These include the
1499 ability to alter packet data in several ways, such as performing
1500 encapsulation/decapsulation of tunnel headers.
1501
1502 Rules management
1503 ----------------
1504
1505 A rather simple API with few functions is provided to fully manage flow
1506 rules.
1507
1508 Each created flow rule is associated with an opaque, PMD-specific handle
1509 pointer. The application is responsible for keeping it until the rule is
1510 destroyed.
1511
1512 Flows rules are represented by ``struct rte_flow`` objects.
1513
1514 Validation
1515 ~~~~~~~~~~
1516
1517 Given that expressing a definite set of device capabilities is not
1518 practical, a dedicated function is provided to check if a flow rule is
1519 supported and can be created.
1520
1521 .. code-block:: c
1522
1523    int
1524    rte_flow_validate(uint16_t port_id,
1525                      const struct rte_flow_attr *attr,
1526                      const struct rte_flow_item pattern[],
1527                      const struct rte_flow_action actions[],
1528                      struct rte_flow_error *error);
1529
1530 The flow rule is validated for correctness and whether it could be accepted
1531 by the device given sufficient resources. The rule is checked against the
1532 current device mode and queue configuration. The flow rule may also
1533 optionally be validated against existing flow rules and device resources.
1534 This function has no effect on the target device.
1535
1536 The returned value is guaranteed to remain valid only as long as no
1537 successful calls to ``rte_flow_create()`` or ``rte_flow_destroy()`` are made
1538 in the meantime and no device parameter affecting flow rules in any way are
1539 modified, due to possible collisions or resource limitations (although in
1540 such cases ``EINVAL`` should not be returned).
1541
1542 Arguments:
1543
1544 - ``port_id``: port identifier of Ethernet device.
1545 - ``attr``: flow rule attributes.
1546 - ``pattern``: pattern specification (list terminated by the END pattern
1547   item).
1548 - ``actions``: associated actions (list terminated by the END action).
1549 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
1550   this structure in case of error only.
1551
1552 Return values:
1553
1554 - 0 if flow rule is valid and can be created. A negative errno value
1555   otherwise (``rte_errno`` is also set), the following errors are defined.
1556 - ``-ENOSYS``: underlying device does not support this functionality.
1557 - ``-EINVAL``: unknown or invalid rule specification.
1558 - ``-ENOTSUP``: valid but unsupported rule specification (e.g. partial
1559   bit-masks are unsupported).
1560 - ``EEXIST``: collision with an existing rule. Only returned if device
1561   supports flow rule collision checking and there was a flow rule
1562   collision. Not receiving this return code is no guarantee that creating
1563   the rule will not fail due to a collision.
1564 - ``ENOMEM``: not enough memory to execute the function, or if the device
1565   supports resource validation, resource limitation on the device.
1566 - ``-EBUSY``: action cannot be performed due to busy device resources, may
1567   succeed if the affected queues or even the entire port are in a stopped
1568   state (see ``rte_eth_dev_rx_queue_stop()`` and ``rte_eth_dev_stop()``).
1569
1570 Creation
1571 ~~~~~~~~
1572
1573 Creating a flow rule is similar to validating one, except the rule is
1574 actually created and a handle returned.
1575
1576 .. code-block:: c
1577
1578    struct rte_flow *
1579    rte_flow_create(uint16_t port_id,
1580                    const struct rte_flow_attr *attr,
1581                    const struct rte_flow_item pattern[],
1582                    const struct rte_flow_action *actions[],
1583                    struct rte_flow_error *error);
1584
1585 Arguments:
1586
1587 - ``port_id``: port identifier of Ethernet device.
1588 - ``attr``: flow rule attributes.
1589 - ``pattern``: pattern specification (list terminated by the END pattern
1590   item).
1591 - ``actions``: associated actions (list terminated by the END action).
1592 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
1593   this structure in case of error only.
1594
1595 Return values:
1596
1597 A valid handle in case of success, NULL otherwise and ``rte_errno`` is set
1598 to the positive version of one of the error codes defined for
1599 ``rte_flow_validate()``.
1600
1601 Destruction
1602 ~~~~~~~~~~~
1603
1604 Flow rules destruction is not automatic, and a queue or a port should not be
1605 released if any are still attached to them. Applications must take care of
1606 performing this step before releasing resources.
1607
1608 .. code-block:: c
1609
1610    int
1611    rte_flow_destroy(uint16_t port_id,
1612                     struct rte_flow *flow,
1613                     struct rte_flow_error *error);
1614
1615
1616 Failure to destroy a flow rule handle may occur when other flow rules depend
1617 on it, and destroying it would result in an inconsistent state.
1618
1619 This function is only guaranteed to succeed if handles are destroyed in
1620 reverse order of their creation.
1621
1622 Arguments:
1623
1624 - ``port_id``: port identifier of Ethernet device.
1625 - ``flow``: flow rule handle to destroy.
1626 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
1627   this structure in case of error only.
1628
1629 Return values:
1630
1631 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
1632
1633 Flush
1634 ~~~~~
1635
1636 Convenience function to destroy all flow rule handles associated with a
1637 port. They are released as with successive calls to ``rte_flow_destroy()``.
1638
1639 .. code-block:: c
1640
1641    int
1642    rte_flow_flush(uint16_t port_id,
1643                   struct rte_flow_error *error);
1644
1645 In the unlikely event of failure, handles are still considered destroyed and
1646 no longer valid but the port must be assumed to be in an inconsistent state.
1647
1648 Arguments:
1649
1650 - ``port_id``: port identifier of Ethernet device.
1651 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
1652   this structure in case of error only.
1653
1654 Return values:
1655
1656 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
1657
1658 Query
1659 ~~~~~
1660
1661 Query an existing flow rule.
1662
1663 This function allows retrieving flow-specific data such as counters. Data
1664 is gathered by special actions which must be present in the flow rule
1665 definition.
1666
1667 .. code-block:: c
1668
1669    int
1670    rte_flow_query(uint16_t port_id,
1671                   struct rte_flow *flow,
1672                   enum rte_flow_action_type action,
1673                   void *data,
1674                   struct rte_flow_error *error);
1675
1676 Arguments:
1677
1678 - ``port_id``: port identifier of Ethernet device.
1679 - ``flow``: flow rule handle to query.
1680 - ``action``: action type to query.
1681 - ``data``: pointer to storage for the associated query data type.
1682 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
1683   this structure in case of error only.
1684
1685 Return values:
1686
1687 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
1688
1689 Isolated mode
1690 -------------
1691
1692 The general expectation for ingress traffic is that flow rules process it
1693 first; the remaining unmatched or pass-through traffic usually ends up in a
1694 queue (with or without RSS, locally or in some sub-device instance)
1695 depending on the global configuration settings of a port.
1696
1697 While fine from a compatibility standpoint, this approach makes drivers more
1698 complex as they have to check for possible side effects outside of this API
1699 when creating or destroying flow rules. It results in a more limited set of
1700 available rule types due to the way device resources are assigned (e.g. no
1701 support for the RSS action even on capable hardware).
1702
1703 Given that nonspecific traffic can be handled by flow rules as well,
1704 isolated mode is a means for applications to tell a driver that ingress on
1705 the underlying port must be injected from the defined flow rules only; that
1706 no default traffic is expected outside those rules.
1707
1708 This has the following benefits:
1709
1710 - Applications get finer-grained control over the kind of traffic they want
1711   to receive (no traffic by default).
1712
1713 - More importantly they control at what point nonspecific traffic is handled
1714   relative to other flow rules, by adjusting priority levels.
1715
1716 - Drivers can assign more hardware resources to flow rules and expand the
1717   set of supported rule types.
1718
1719 Because toggling isolated mode may cause profound changes to the ingress
1720 processing path of a driver, it may not be possible to leave it once
1721 entered. Likewise, existing flow rules or global configuration settings may
1722 prevent a driver from entering isolated mode.
1723
1724 Applications relying on this mode are therefore encouraged to toggle it as
1725 soon as possible after device initialization, ideally before the first call
1726 to ``rte_eth_dev_configure()`` to avoid possible failures due to conflicting
1727 settings.
1728
1729 Once effective, the following functionality has no effect on the underlying
1730 port and may return errors such as ``ENOTSUP`` ("not supported"):
1731
1732 - Toggling promiscuous mode.
1733 - Toggling allmulticast mode.
1734 - Configuring MAC addresses.
1735 - Configuring multicast addresses.
1736 - Configuring VLAN filters.
1737 - Configuring Rx filters through the legacy API (e.g. FDIR).
1738 - Configuring global RSS settings.
1739
1740 .. code-block:: c
1741
1742    int
1743    rte_flow_isolate(uint16_t port_id, int set, struct rte_flow_error *error);
1744
1745 Arguments:
1746
1747 - ``port_id``: port identifier of Ethernet device.
1748 - ``set``: nonzero to enter isolated mode, attempt to leave it otherwise.
1749 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
1750   this structure in case of error only.
1751
1752 Return values:
1753
1754 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
1755
1756 Verbose error reporting
1757 -----------------------
1758
1759 The defined *errno* values may not be accurate enough for users or
1760 application developers who want to investigate issues related to flow rules
1761 management. A dedicated error object is defined for this purpose:
1762
1763 .. code-block:: c
1764
1765    enum rte_flow_error_type {
1766        RTE_FLOW_ERROR_TYPE_NONE, /**< No error. */
1767        RTE_FLOW_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
1768        RTE_FLOW_ERROR_TYPE_HANDLE, /**< Flow rule (handle). */
1769        RTE_FLOW_ERROR_TYPE_ATTR_GROUP, /**< Group field. */
1770        RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */
1771        RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */
1772        RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */
1773        RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */
1774        RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */
1775        RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */
1776        RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */
1777        RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */
1778    };
1779
1780    struct rte_flow_error {
1781        enum rte_flow_error_type type; /**< Cause field and error types. */
1782        const void *cause; /**< Object responsible for the error. */
1783        const char *message; /**< Human-readable error message. */
1784    };
1785
1786 Error type ``RTE_FLOW_ERROR_TYPE_NONE`` stands for no error, in which case
1787 remaining fields can be ignored. Other error types describe the type of the
1788 object pointed by ``cause``.
1789
1790 If non-NULL, ``cause`` points to the object responsible for the error. For a
1791 flow rule, this may be a pattern item or an individual action.
1792
1793 If non-NULL, ``message`` provides a human-readable error message.
1794
1795 This object is normally allocated by applications and set by PMDs in case of
1796 error, the message points to a constant string which does not need to be
1797 freed by the application, however its pointer can be considered valid only
1798 as long as its associated DPDK port remains configured. Closing the
1799 underlying device or unloading the PMD invalidates it.
1800
1801 Helpers
1802 -------
1803
1804 Error initializer
1805 ~~~~~~~~~~~~~~~~~
1806
1807 .. code-block:: c
1808
1809    static inline int
1810    rte_flow_error_set(struct rte_flow_error *error,
1811                       int code,
1812                       enum rte_flow_error_type type,
1813                       const void *cause,
1814                       const char *message);
1815
1816 This function initializes ``error`` (if non-NULL) with the provided
1817 parameters and sets ``rte_errno`` to ``code``. A negative error ``code`` is
1818 then returned.
1819
1820 Caveats
1821 -------
1822
1823 - DPDK does not keep track of flow rules definitions or flow rule objects
1824   automatically. Applications may keep track of the former and must keep
1825   track of the latter. PMDs may also do it for internal needs, however this
1826   must not be relied on by applications.
1827
1828 - Flow rules are not maintained between successive port initializations. An
1829   application exiting without releasing them and restarting must re-create
1830   them from scratch.
1831
1832 - API operations are synchronous and blocking (``EAGAIN`` cannot be
1833   returned).
1834
1835 - There is no provision for reentrancy/multi-thread safety, although nothing
1836   should prevent different devices from being configured at the same
1837   time. PMDs may protect their control path functions accordingly.
1838
1839 - Stopping the data path (TX/RX) should not be necessary when managing flow
1840   rules. If this cannot be achieved naturally or with workarounds (such as
1841   temporarily replacing the burst function pointers), an appropriate error
1842   code must be returned (``EBUSY``).
1843
1844 - PMDs, not applications, are responsible for maintaining flow rules
1845   configuration when stopping and restarting a port or performing other
1846   actions which may affect them. They can only be destroyed explicitly by
1847   applications.
1848
1849 For devices exposing multiple ports sharing global settings affected by flow
1850 rules:
1851
1852 - All ports under DPDK control must behave consistently, PMDs are
1853   responsible for making sure that existing flow rules on a port are not
1854   affected by other ports.
1855
1856 - Ports not under DPDK control (unaffected or handled by other applications)
1857   are user's responsibility. They may affect existing flow rules and cause
1858   undefined behavior. PMDs aware of this may prevent flow rules creation
1859   altogether in such cases.
1860
1861 PMD interface
1862 -------------
1863
1864 The PMD interface is defined in ``rte_flow_driver.h``. It is not subject to
1865 API/ABI versioning constraints as it is not exposed to applications and may
1866 evolve independently.
1867
1868 It is currently implemented on top of the legacy filtering framework through
1869 filter type *RTE_ETH_FILTER_GENERIC* that accepts the single operation
1870 *RTE_ETH_FILTER_GET* to return PMD-specific *rte_flow* callbacks wrapped
1871 inside ``struct rte_flow_ops``.
1872
1873 This overhead is temporarily necessary in order to keep compatibility with
1874 the legacy filtering framework, which should eventually disappear.
1875
1876 - PMD callbacks implement exactly the interface described in `Rules
1877   management`_, except for the port ID argument which has already been
1878   converted to a pointer to the underlying ``struct rte_eth_dev``.
1879
1880 - Public API functions do not process flow rules definitions at all before
1881   calling PMD functions (no basic error checking, no validation
1882   whatsoever). They only make sure these callbacks are non-NULL or return
1883   the ``ENOSYS`` (function not supported) error.
1884
1885 This interface additionally defines the following helper function:
1886
1887 - ``rte_flow_ops_get()``: get generic flow operations structure from a
1888   port.
1889
1890 More will be added over time.
1891
1892 Device compatibility
1893 --------------------
1894
1895 No known implementation supports all the described features.
1896
1897 Unsupported features or combinations are not expected to be fully emulated
1898 in software by PMDs for performance reasons. Partially supported features
1899 may be completed in software as long as hardware performs most of the work
1900 (such as queue redirection and packet recognition).
1901
1902 However PMDs are expected to do their best to satisfy application requests
1903 by working around hardware limitations as long as doing so does not affect
1904 the behavior of existing flow rules.
1905
1906 The following sections provide a few examples of such cases and describe how
1907 PMDs should handle them, they are based on limitations built into the
1908 previous APIs.
1909
1910 Global bit-masks
1911 ~~~~~~~~~~~~~~~~
1912
1913 Each flow rule comes with its own, per-layer bit-masks, while hardware may
1914 support only a single, device-wide bit-mask for a given layer type, so that
1915 two IPv4 rules cannot use different bit-masks.
1916
1917 The expected behavior in this case is that PMDs automatically configure
1918 global bit-masks according to the needs of the first flow rule created.
1919
1920 Subsequent rules are allowed only if their bit-masks match those, the
1921 ``EEXIST`` error code should be returned otherwise.
1922
1923 Unsupported layer types
1924 ~~~~~~~~~~~~~~~~~~~~~~~
1925
1926 Many protocols can be simulated by crafting patterns with the `Item: RAW`_
1927 type.
1928
1929 PMDs can rely on this capability to simulate support for protocols with
1930 headers not directly recognized by hardware.
1931
1932 ``ANY`` pattern item
1933 ~~~~~~~~~~~~~~~~~~~~
1934
1935 This pattern item stands for anything, which can be difficult to translate
1936 to something hardware would understand, particularly if followed by more
1937 specific types.
1938
1939 Consider the following pattern:
1940
1941 .. _table_rte_flow_unsupported_any:
1942
1943 .. table:: Pattern with ANY as L3
1944
1945    +-------+-----------------------+
1946    | Index | Item                  |
1947    +=======+=======================+
1948    | 0     | ETHER                 |
1949    +-------+-----+---------+-------+
1950    | 1     | ANY | ``num`` | ``1`` |
1951    +-------+-----+---------+-------+
1952    | 2     | TCP                   |
1953    +-------+-----------------------+
1954    | 3     | END                   |
1955    +-------+-----------------------+
1956
1957 Knowing that TCP does not make sense with something other than IPv4 and IPv6
1958 as L3, such a pattern may be translated to two flow rules instead:
1959
1960 .. _table_rte_flow_unsupported_any_ipv4:
1961
1962 .. table:: ANY replaced with IPV4
1963
1964    +-------+--------------------+
1965    | Index | Item               |
1966    +=======+====================+
1967    | 0     | ETHER              |
1968    +-------+--------------------+
1969    | 1     | IPV4 (zeroed mask) |
1970    +-------+--------------------+
1971    | 2     | TCP                |
1972    +-------+--------------------+
1973    | 3     | END                |
1974    +-------+--------------------+
1975
1976 |
1977
1978 .. _table_rte_flow_unsupported_any_ipv6:
1979
1980 .. table:: ANY replaced with IPV6
1981
1982    +-------+--------------------+
1983    | Index | Item               |
1984    +=======+====================+
1985    | 0     | ETHER              |
1986    +-------+--------------------+
1987    | 1     | IPV6 (zeroed mask) |
1988    +-------+--------------------+
1989    | 2     | TCP                |
1990    +-------+--------------------+
1991    | 3     | END                |
1992    +-------+--------------------+
1993
1994 Note that as soon as a ANY rule covers several layers, this approach may
1995 yield a large number of hidden flow rules. It is thus suggested to only
1996 support the most common scenarios (anything as L2 and/or L3).
1997
1998 Unsupported actions
1999 ~~~~~~~~~~~~~~~~~~~
2000
2001 - When combined with `Action: QUEUE`_, packet counting (`Action: COUNT`_)
2002   and tagging (`Action: MARK`_ or `Action: FLAG`_) may be implemented in
2003   software as long as the target queue is used by a single rule.
2004
2005 - A rule specifying both `Action: DUP`_ + `Action: QUEUE`_ may be translated
2006   to two hidden rules combining `Action: QUEUE`_ and `Action: PASSTHRU`_.
2007
2008 - When a single target queue is provided, `Action: RSS`_ can also be
2009   implemented through `Action: QUEUE`_.
2010
2011 Flow rules priority
2012 ~~~~~~~~~~~~~~~~~~~
2013
2014 While it would naturally make sense, flow rules cannot be assumed to be
2015 processed by hardware in the same order as their creation for several
2016 reasons:
2017
2018 - They may be managed internally as a tree or a hash table instead of a
2019   list.
2020 - Removing a flow rule before adding another one can either put the new rule
2021   at the end of the list or reuse a freed entry.
2022 - Duplication may occur when packets are matched by several rules.
2023
2024 For overlapping rules (particularly in order to use `Action: PASSTHRU`_)
2025 predictable behavior is only guaranteed by using different priority levels.
2026
2027 Priority levels are not necessarily implemented in hardware, or may be
2028 severely limited (e.g. a single priority bit).
2029
2030 For these reasons, priority levels may be implemented purely in software by
2031 PMDs.
2032
2033 - For devices expecting flow rules to be added in the correct order, PMDs
2034   may destroy and re-create existing rules after adding a new one with
2035   a higher priority.
2036
2037 - A configurable number of dummy or empty rules can be created at
2038   initialization time to save high priority slots for later.
2039
2040 - In order to save priority levels, PMDs may evaluate whether rules are
2041   likely to collide and adjust their priority accordingly.
2042
2043 Future evolutions
2044 -----------------
2045
2046 - A device profile selection function which could be used to force a
2047   permanent profile instead of relying on its automatic configuration based
2048   on existing flow rules.
2049
2050 - A method to optimize *rte_flow* rules with specific pattern items and
2051   action types generated on the fly by PMDs. DPDK should assign negative
2052   numbers to these in order to not collide with the existing types. See
2053   `Negative types`_.
2054
2055 - Adding specific egress pattern items and actions as described in
2056   `Attribute: Traffic direction`_.
2057
2058 - Optional software fallback when PMDs are unable to handle requested flow
2059   rules so applications do not have to implement their own.
2060
2061 API migration
2062 -------------
2063
2064 Exhaustive list of deprecated filter types (normally prefixed with
2065 *RTE_ETH_FILTER_*) found in ``rte_eth_ctrl.h`` and methods to convert them
2066 to *rte_flow* rules.
2067
2068 ``MACVLAN`` to ``ETH`` → ``VF``, ``PF``
2069 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2070
2071 *MACVLAN* can be translated to a basic `Item: ETH`_ flow rule with a
2072 terminating `Action: VF`_ or `Action: PF`_.
2073
2074 .. _table_rte_flow_migration_macvlan:
2075
2076 .. table:: MACVLAN conversion
2077
2078    +--------------------------+---------+
2079    | Pattern                  | Actions |
2080    +===+=====+==========+=====+=========+
2081    | 0 | ETH | ``spec`` | any | VF,     |
2082    |   |     +----------+-----+ PF      |
2083    |   |     | ``last`` | N/A |         |
2084    |   |     +----------+-----+         |
2085    |   |     | ``mask`` | any |         |
2086    +---+-----+----------+-----+---------+
2087    | 1 | END                  | END     |
2088    +---+----------------------+---------+
2089
2090 ``ETHERTYPE`` to ``ETH`` → ``QUEUE``, ``DROP``
2091 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2092
2093 *ETHERTYPE* is basically an `Item: ETH`_ flow rule with a terminating
2094 `Action: QUEUE`_ or `Action: DROP`_.
2095
2096 .. _table_rte_flow_migration_ethertype:
2097
2098 .. table:: ETHERTYPE conversion
2099
2100    +--------------------------+---------+
2101    | Pattern                  | Actions |
2102    +===+=====+==========+=====+=========+
2103    | 0 | ETH | ``spec`` | any | QUEUE,  |
2104    |   |     +----------+-----+ DROP    |
2105    |   |     | ``last`` | N/A |         |
2106    |   |     +----------+-----+         |
2107    |   |     | ``mask`` | any |         |
2108    +---+-----+----------+-----+---------+
2109    | 1 | END                  | END     |
2110    +---+----------------------+---------+
2111
2112 ``FLEXIBLE`` to ``RAW`` → ``QUEUE``
2113 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2114
2115 *FLEXIBLE* can be translated to one `Item: RAW`_ pattern with a terminating
2116 `Action: QUEUE`_ and a defined priority level.
2117
2118 .. _table_rte_flow_migration_flexible:
2119
2120 .. table:: FLEXIBLE conversion
2121
2122    +--------------------------+---------+
2123    | Pattern                  | Actions |
2124    +===+=====+==========+=====+=========+
2125    | 0 | RAW | ``spec`` | any | QUEUE   |
2126    |   |     +----------+-----+         |
2127    |   |     | ``last`` | N/A |         |
2128    |   |     +----------+-----+         |
2129    |   |     | ``mask`` | any |         |
2130    +---+-----+----------+-----+---------+
2131    | 1 | END                  | END     |
2132    +---+----------------------+---------+
2133
2134 ``SYN`` to ``TCP`` → ``QUEUE``
2135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2136
2137 *SYN* is a `Item: TCP`_ rule with only the ``syn`` bit enabled and masked,
2138 and a terminating `Action: QUEUE`_.
2139
2140 Priority level can be set to simulate the high priority bit.
2141
2142 .. _table_rte_flow_migration_syn:
2143
2144 .. table:: SYN conversion
2145
2146    +-----------------------------------+---------+
2147    | Pattern                           | Actions |
2148    +===+======+==========+=============+=========+
2149    | 0 | ETH  | ``spec`` | unset       | QUEUE   |
2150    |   |      +----------+-------------+         |
2151    |   |      | ``last`` | unset       |         |
2152    |   |      +----------+-------------+         |
2153    |   |      | ``mask`` | unset       |         |
2154    +---+------+----------+-------------+---------+
2155    | 1 | IPV4 | ``spec`` | unset       | END     |
2156    |   |      +----------+-------------+         |
2157    |   |      | ``mask`` | unset       |         |
2158    |   |      +----------+-------------+         |
2159    |   |      | ``mask`` | unset       |         |
2160    +---+------+----------+---------+---+         |
2161    | 2 | TCP  | ``spec`` | ``syn`` | 1 |         |
2162    |   |      +----------+---------+---+         |
2163    |   |      | ``mask`` | ``syn`` | 1 |         |
2164    +---+------+----------+---------+---+         |
2165    | 3 | END                           |         |
2166    +---+-------------------------------+---------+
2167
2168 ``NTUPLE`` to ``IPV4``, ``TCP``, ``UDP`` → ``QUEUE``
2169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2170
2171 *NTUPLE* is similar to specifying an empty L2, `Item: IPV4`_ as L3 with
2172 `Item: TCP`_ or `Item: UDP`_ as L4 and a terminating `Action: QUEUE`_.
2173
2174 A priority level can be specified as well.
2175
2176 .. _table_rte_flow_migration_ntuple:
2177
2178 .. table:: NTUPLE conversion
2179
2180    +-----------------------------+---------+
2181    | Pattern                     | Actions |
2182    +===+======+==========+=======+=========+
2183    | 0 | ETH  | ``spec`` | unset | QUEUE   |
2184    |   |      +----------+-------+         |
2185    |   |      | ``last`` | unset |         |
2186    |   |      +----------+-------+         |
2187    |   |      | ``mask`` | unset |         |
2188    +---+------+----------+-------+---------+
2189    | 1 | IPV4 | ``spec`` | any   | END     |
2190    |   |      +----------+-------+         |
2191    |   |      | ``last`` | unset |         |
2192    |   |      +----------+-------+         |
2193    |   |      | ``mask`` | any   |         |
2194    +---+------+----------+-------+         |
2195    | 2 | TCP, | ``spec`` | any   |         |
2196    |   | UDP  +----------+-------+         |
2197    |   |      | ``last`` | unset |         |
2198    |   |      +----------+-------+         |
2199    |   |      | ``mask`` | any   |         |
2200    +---+------+----------+-------+         |
2201    | 3 | END                     |         |
2202    +---+-------------------------+---------+
2203
2204 ``TUNNEL`` to ``ETH``, ``IPV4``, ``IPV6``, ``VXLAN`` (or other) → ``QUEUE``
2205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2206
2207 *TUNNEL* matches common IPv4 and IPv6 L3/L4-based tunnel types.
2208
2209 In the following table, `Item: ANY`_ is used to cover the optional L4.
2210
2211 .. _table_rte_flow_migration_tunnel:
2212
2213 .. table:: TUNNEL conversion
2214
2215    +-------------------------------------------------------+---------+
2216    | Pattern                                               | Actions |
2217    +===+==========================+==========+=============+=========+
2218    | 0 | ETH                      | ``spec`` | any         | QUEUE   |
2219    |   |                          +----------+-------------+         |
2220    |   |                          | ``last`` | unset       |         |
2221    |   |                          +----------+-------------+         |
2222    |   |                          | ``mask`` | any         |         |
2223    +---+--------------------------+----------+-------------+---------+
2224    | 1 | IPV4, IPV6               | ``spec`` | any         | END     |
2225    |   |                          +----------+-------------+         |
2226    |   |                          | ``last`` | unset       |         |
2227    |   |                          +----------+-------------+         |
2228    |   |                          | ``mask`` | any         |         |
2229    +---+--------------------------+----------+-------------+         |
2230    | 2 | ANY                      | ``spec`` | any         |         |
2231    |   |                          +----------+-------------+         |
2232    |   |                          | ``last`` | unset       |         |
2233    |   |                          +----------+---------+---+         |
2234    |   |                          | ``mask`` | ``num`` | 0 |         |
2235    +---+--------------------------+----------+---------+---+         |
2236    | 3 | VXLAN, GENEVE, TEREDO,   | ``spec`` | any         |         |
2237    |   | NVGRE, GRE, ...          +----------+-------------+         |
2238    |   |                          | ``last`` | unset       |         |
2239    |   |                          +----------+-------------+         |
2240    |   |                          | ``mask`` | any         |         |
2241    +---+--------------------------+----------+-------------+         |
2242    | 4 | END                                               |         |
2243    +---+---------------------------------------------------+---------+
2244
2245 ``FDIR`` to most item types → ``QUEUE``, ``DROP``, ``PASSTHRU``
2246 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2247
2248 *FDIR* is more complex than any other type, there are several methods to
2249 emulate its functionality. It is summarized for the most part in the table
2250 below.
2251
2252 A few features are intentionally not supported:
2253
2254 - The ability to configure the matching input set and masks for the entire
2255   device, PMDs should take care of it automatically according to the
2256   requested flow rules.
2257
2258   For example if a device supports only one bit-mask per protocol type,
2259   source/address IPv4 bit-masks can be made immutable by the first created
2260   rule. Subsequent IPv4 or TCPv4 rules can only be created if they are
2261   compatible.
2262
2263   Note that only protocol bit-masks affected by existing flow rules are
2264   immutable, others can be changed later. They become mutable again after
2265   the related flow rules are destroyed.
2266
2267 - Returning four or eight bytes of matched data when using flex bytes
2268   filtering. Although a specific action could implement it, it conflicts
2269   with the much more useful 32 bits tagging on devices that support it.
2270
2271 - Side effects on RSS processing of the entire device. Flow rules that
2272   conflict with the current device configuration should not be
2273   allowed. Similarly, device configuration should not be allowed when it
2274   affects existing flow rules.
2275
2276 - Device modes of operation. "none" is unsupported since filtering cannot be
2277   disabled as long as a flow rule is present.
2278
2279 - "MAC VLAN" or "tunnel" perfect matching modes should be automatically set
2280   according to the created flow rules.
2281
2282 - Signature mode of operation is not defined but could be handled through
2283   "FUZZY" item.
2284
2285 .. _table_rte_flow_migration_fdir:
2286
2287 .. table:: FDIR conversion
2288
2289    +----------------------------------------+-----------------------+
2290    | Pattern                                | Actions               |
2291    +===+===================+==========+=====+=======================+
2292    | 0 | ETH, RAW          | ``spec`` | any | QUEUE, DROP, PASSTHRU |
2293    |   |                   +----------+-----+                       |
2294    |   |                   | ``last`` | N/A |                       |
2295    |   |                   +----------+-----+                       |
2296    |   |                   | ``mask`` | any |                       |
2297    +---+-------------------+----------+-----+-----------------------+
2298    | 1 | IPV4, IPv6        | ``spec`` | any | MARK                  |
2299    |   |                   +----------+-----+                       |
2300    |   |                   | ``last`` | N/A |                       |
2301    |   |                   +----------+-----+                       |
2302    |   |                   | ``mask`` | any |                       |
2303    +---+-------------------+----------+-----+-----------------------+
2304    | 2 | TCP, UDP, SCTP    | ``spec`` | any | END                   |
2305    |   |                   +----------+-----+                       |
2306    |   |                   | ``last`` | N/A |                       |
2307    |   |                   +----------+-----+                       |
2308    |   |                   | ``mask`` | any |                       |
2309    +---+-------------------+----------+-----+                       |
2310    | 3 | VF, PF, FUZZY     | ``spec`` | any |                       |
2311    |   | (optional)        +----------+-----+                       |
2312    |   |                   | ``last`` | N/A |                       |
2313    |   |                   +----------+-----+                       |
2314    |   |                   | ``mask`` | any |                       |
2315    +---+-------------------+----------+-----+                       |
2316    | 4 | END                                |                       |
2317    +---+------------------------------------+-----------------------+
2318
2319 ``HASH``
2320 ~~~~~~~~
2321
2322 There is no counterpart to this filter type because it translates to a
2323 global device setting instead of a pattern item. Device settings are
2324 automatically set according to the created flow rules.
2325
2326 ``L2_TUNNEL`` to ``VOID`` → ``VXLAN`` (or others)
2327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2328
2329 All packets are matched. This type alters incoming packets to encapsulate
2330 them in a chosen tunnel type, optionally redirect them to a VF as well.
2331
2332 The destination pool for tag based forwarding can be emulated with other
2333 flow rules using `Action: DUP`_.
2334
2335 .. _table_rte_flow_migration_l2tunnel:
2336
2337 .. table:: L2_TUNNEL conversion
2338
2339    +---------------------------+--------------------+
2340    | Pattern                   | Actions            |
2341    +===+======+==========+=====+====================+
2342    | 0 | VOID | ``spec`` | N/A | VXLAN, GENEVE, ... |
2343    |   |      |          |     |                    |
2344    |   |      |          |     |                    |
2345    |   |      +----------+-----+                    |
2346    |   |      | ``last`` | N/A |                    |
2347    |   |      +----------+-----+                    |
2348    |   |      | ``mask`` | N/A |                    |
2349    |   |      |          |     |                    |
2350    +---+------+----------+-----+--------------------+
2351    | 1 | END                   | VF (optional)      |
2352    +---+                       +--------------------+
2353    | 2 |                       | END                |
2354    +---+-----------------------+--------------------+