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