app/testpmd: add flow queue pull operation
[dpdk.git] / doc / guides / prog_guide / rte_flow.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright 2016 6WIND S.A.
3     Copyright 2016 Mellanox Technologies, Ltd
4
5 Generic flow API (rte_flow)
6 ===========================
7
8 Overview
9 --------
10
11 This API provides a generic means to configure hardware to match specific
12 traffic, alter its fate and query related counters according to any
13 number of user-defined rules.
14
15 It is named *rte_flow* after the prefix used for all its symbols, and is
16 defined in ``rte_flow.h``.
17
18 - Matching can be performed on packet data (protocol headers, payload) and
19   properties (e.g. associated physical port, virtual device function ID).
20
21 - Possible operations include dropping traffic, diverting it to specific
22   queues, to virtual/physical device functions or ports, performing tunnel
23   offloads, adding marks and so on.
24
25 Flow rule
26 ---------
27
28 Description
29 ~~~~~~~~~~~
30
31 A flow rule is the combination of attributes with a matching pattern and a
32 list of actions. Flow rules form the basis of this API.
33
34 Flow rules can have several distinct actions (such as counting,
35 encapsulating, decapsulating before redirecting packets to a particular
36 queue, etc.), instead of relying on several rules to achieve this and having
37 applications deal with hardware implementation details regarding their
38 order.
39
40 Support for different priority levels on a rule basis is provided, for
41 example in order to force a more specific rule to come before a more generic
42 one for packets matched by both. However hardware support for more than a
43 single priority level cannot be guaranteed. When supported, the number of
44 available priority levels is usually low, which is why they can also be
45 implemented in software by PMDs (e.g. missing priority levels may be
46 emulated by reordering rules).
47
48 In order to remain as hardware-agnostic as possible, by default all rules
49 are considered to have the same priority, which means that the order between
50 overlapping rules (when a packet is matched by several filters) is
51 undefined.
52
53 PMDs may refuse to create overlapping rules at a given priority level when
54 they can be detected (e.g. if a pattern matches an existing filter).
55
56 Thus predictable results for a given priority level can only be achieved
57 with non-overlapping rules, using perfect matching on all protocol layers.
58
59 Flow rules can also be grouped, the flow rule priority is specific to the
60 group they belong to. All flow rules in a given group are thus processed within
61 the context of that group. Groups are not linked by default, so the logical
62 hierarchy of groups must be explicitly defined by flow rules themselves in each
63 group using the JUMP action to define the next group to redirect too. Only flow
64 rules defined in the default group 0 are guarantee to be matched against, this
65 makes group 0 the origin of any group hierarchy defined by an application.
66
67 Support for multiple actions per rule may be implemented internally on top
68 of non-default hardware priorities, as a result both features may not be
69 simultaneously available to applications.
70
71 Considering that allowed pattern/actions combinations cannot be known in
72 advance and would result in an impractically large number of capabilities to
73 expose, a method is provided to validate a given rule from the current
74 device configuration state.
75
76 This enables applications to check if the rule types they need is supported
77 at initialization time, before starting their data path. This method can be
78 used anytime, its only requirement being that the resources needed by a rule
79 should exist (e.g. a target RX queue should be configured first).
80
81 Each defined rule is associated with an opaque handle managed by the PMD,
82 applications are responsible for keeping it. These can be used for queries
83 and rules management, such as retrieving counters or other data and
84 destroying them.
85
86 To avoid resource leaks on the PMD side, handles must be explicitly
87 destroyed by the application before releasing associated resources such as
88 queues and ports.
89
90 .. warning::
91
92    The following description of rule persistence is an experimental behavior
93    that may change without a prior notice.
94
95 When the device is stopped, its rules do not process the traffic.
96 In particular, transfer rules created using some device
97 stop affecting the traffic even if they refer to different ports.
98
99 If ``RTE_ETH_DEV_CAPA_FLOW_RULE_KEEP`` is not advertised,
100 rules cannot be created until the device is started for the first time
101 and cannot be kept when the device is stopped.
102 However, PMD also does not flush them automatically on stop,
103 so the application must call ``rte_flow_flush()`` or ``rte_flow_destroy()``
104 before stopping the device to ensure no rules remain.
105
106 If ``RTE_ETH_DEV_CAPA_FLOW_RULE_KEEP`` is advertised, this means
107 the PMD can keep at least some rules across the device stop and start.
108 However, ``rte_eth_dev_configure()`` may fail if any rules remain,
109 so the application must flush them before attempting a reconfiguration.
110 Keeping may be unsupported for some types of rule items and actions,
111 as well as depending on the value of flow attributes transfer bit.
112 A combination of a single an item or action type
113 and a value of the transfer bit is called a rule feature.
114 For example: a COUNT action with the transfer bit set.
115 To test if rules with a particular feature are kept, the application must try
116 to create a valid rule using this feature when the device is not started
117 (either before the first start or after a stop).
118 If it fails with an error of type ``RTE_FLOW_ERROR_TYPE_STATE``,
119 all rules using this feature must be flushed by the application
120 before stopping the device.
121 If it succeeds, such rules will be kept when the device is stopped,
122 provided they do not use other features that are not supported.
123 Rules that are created when the device is stopped, including the rules
124 created for the test, will be kept after the device is started.
125
126 The following sections cover:
127
128 - **Attributes** (represented by ``struct rte_flow_attr``): properties of a
129   flow rule such as its direction (ingress or egress) and priority.
130
131 - **Pattern item** (represented by ``struct rte_flow_item``): part of a
132   matching pattern that either matches specific packet data or traffic
133   properties. It can also describe properties of the pattern itself, such as
134   inverted matching.
135
136 - **Matching pattern**: traffic properties to look for, a combination of any
137   number of items.
138
139 - **Actions** (represented by ``struct rte_flow_action``): operations to
140   perform whenever a packet is matched by a pattern.
141
142 Attributes
143 ~~~~~~~~~~
144
145 Attribute: Group
146 ^^^^^^^^^^^^^^^^
147
148 Flow rules can be grouped by assigning them a common group number. Groups
149 allow a logical hierarchy of flow rule groups (tables) to be defined. These
150 groups can be supported virtually in the PMD or in the physical device.
151 Group 0 is the default group and this is the only group which flows are
152 guarantee to matched against, all subsequent groups can only be reached by
153 way of the JUMP action from a matched flow rule.
154
155 Although optional, applications are encouraged to group similar rules as
156 much as possible to fully take advantage of hardware capabilities
157 (e.g. optimized matching) and work around limitations (e.g. a single pattern
158 type possibly allowed in a given group), while being aware that the groups
159 hierarchies must be programmed explicitly.
160
161 Note that support for more than a single group is not guaranteed.
162
163 Attribute: Priority
164 ^^^^^^^^^^^^^^^^^^^
165
166 A priority level can be assigned to a flow rule, lower values
167 denote higher priority, with 0 as the maximum.
168
169 Priority levels are arbitrary and up to the application, they do
170 not need to be contiguous nor start from 0, however the maximum number
171 varies between devices and may be affected by existing flow rules.
172
173 A flow which matches multiple rules in the same group will always matched by
174 the rule with the highest priority in that group.
175
176 If a packet is matched by several rules of a given group for a given
177 priority level, the outcome is undefined. It can take any path, may be
178 duplicated or even cause unrecoverable errors.
179
180 Note that support for more than a single priority level is not guaranteed.
181
182 Attribute: Traffic direction
183 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
184
185 Unless `Attribute: Transfer`_ is specified, flow rule patterns apply
186 to inbound and / or outbound traffic. With this respect, ``ingress``
187 and ``egress`` respectively stand for **inbound** and **outbound**
188 based on the standpoint of the application creating a flow rule.
189
190 Several pattern items and actions are valid and can be used in both
191 directions. At least one direction must be specified.
192
193 Specifying both directions at once for a given rule is not recommended but
194 may be valid in a few cases.
195
196 Attribute: Transfer
197 ^^^^^^^^^^^^^^^^^^^
198
199 Instead of simply matching the properties of traffic as it would appear on a
200 given DPDK port ID, enabling this attribute transfers a flow rule to the
201 lowest possible level of any device endpoints found in the pattern.
202
203 When supported, this effectively enables an application to reroute traffic
204 not necessarily intended for it (e.g. coming from or addressed to different
205 physical ports, VFs or applications) at the device level.
206
207 In "transfer" flows, the use of `Attribute: Traffic direction`_ in the sense of
208 implicitly matching packets going to or going from the ethdev used to create
209 flow rules is **deprecated**. `Attribute: Transfer`_ shifts the viewpoint to
210 the embedded switch. In it, `Attribute: Traffic direction`_ is ambiguous as
211 the switch serves many different endpoints. The application should match
212 traffic originating from precise locations. To do so, it should
213 use `Item: PORT_REPRESENTOR`_ and `Item: REPRESENTED_PORT`_.
214
215 Pattern item
216 ~~~~~~~~~~~~
217
218 Pattern items fall in two categories:
219
220 - Matching protocol headers and packet data, usually associated with a
221   specification structure. These must be stacked in the same order as the
222   protocol layers to match inside packets, starting from the lowest.
223
224 - Matching meta-data or affecting pattern processing, often without a
225   specification structure. Since they do not match packet contents, their
226   position in the list is usually not relevant.
227
228 Item specification structures are used to match specific values among
229 protocol fields (or item properties). Documentation describes for each item
230 whether they are associated with one and their type name if so.
231
232 Up to three structures of the same type can be set for a given item:
233
234 - ``spec``: values to match (e.g. a given IPv4 address).
235
236 - ``last``: upper bound for an inclusive range with corresponding fields in
237   ``spec``.
238
239 - ``mask``: bit-mask applied to both ``spec`` and ``last`` whose purpose is
240   to distinguish the values to take into account and/or partially mask them
241   out (e.g. in order to match an IPv4 address prefix).
242
243 Usage restrictions and expected behavior:
244
245 - Setting either ``mask`` or ``last`` without ``spec`` is an error.
246
247 - Field values in ``last`` which are either 0 or equal to the corresponding
248   values in ``spec`` are ignored; they do not generate a range. Nonzero
249   values lower than those in ``spec`` are not supported.
250
251 - Setting ``spec`` and optionally ``last`` without ``mask`` causes the PMD
252   to use the default mask defined for that item (defined as
253   ``rte_flow_item_{name}_mask`` constants).
254
255 - Not setting any of them (assuming item type allows it) is equivalent to
256   providing an empty (zeroed) ``mask`` for broad (nonspecific) matching.
257
258 - ``mask`` is a simple bit-mask applied before interpreting the contents of
259   ``spec`` and ``last``, which may yield unexpected results if not used
260   carefully. For example, if for an IPv4 address field, ``spec`` provides
261   *10.1.2.3*, ``last`` provides *10.3.4.5* and ``mask`` provides
262   *255.255.0.0*, the effective range becomes *10.1.0.0* to *10.3.255.255*.
263
264 Example of an item specification matching an Ethernet header:
265
266 .. _table_rte_flow_pattern_item_example:
267
268 .. table:: Ethernet item
269
270    +----------+----------+-----------------------+
271    | Field    | Subfield | Value                 |
272    +==========+==========+=======================+
273    | ``spec`` | ``src``  | ``00:00:01:02:03:04`` |
274    |          +----------+-----------------------+
275    |          | ``dst``  | ``00:00:2a:66:00:01`` |
276    |          +----------+-----------------------+
277    |          | ``type`` | ``0x22aa``            |
278    +----------+----------+-----------------------+
279    | ``last`` | unspecified                      |
280    +----------+----------+-----------------------+
281    | ``mask`` | ``src``  | ``00:00:ff:ff:ff:00`` |
282    |          +----------+-----------------------+
283    |          | ``dst``  | ``00:00:00:00:00:ff`` |
284    |          +----------+-----------------------+
285    |          | ``type`` | ``0x0000``            |
286    +----------+----------+-----------------------+
287
288 Non-masked bits stand for any value (shown as ``?`` below), Ethernet headers
289 with the following properties are thus matched:
290
291 - ``src``: ``??:??:01:02:03:??``
292 - ``dst``: ``??:??:??:??:??:01``
293 - ``type``: ``0x????``
294
295 Matching pattern
296 ~~~~~~~~~~~~~~~~
297
298 A pattern is formed by stacking items starting from the lowest protocol
299 layer to match. This stacking restriction does not apply to meta items which
300 can be placed anywhere in the stack without affecting the meaning of the
301 resulting pattern.
302
303 Patterns are terminated by END items.
304
305 Examples:
306
307 .. _table_rte_flow_tcpv4_as_l4:
308
309 .. table:: TCPv4 as L4
310
311    +-------+----------+
312    | Index | Item     |
313    +=======+==========+
314    | 0     | Ethernet |
315    +-------+----------+
316    | 1     | IPv4     |
317    +-------+----------+
318    | 2     | TCP      |
319    +-------+----------+
320    | 3     | END      |
321    +-------+----------+
322
323 |
324
325 .. _table_rte_flow_tcpv6_in_vxlan:
326
327 .. table:: TCPv6 in VXLAN
328
329    +-------+------------+
330    | Index | Item       |
331    +=======+============+
332    | 0     | Ethernet   |
333    +-------+------------+
334    | 1     | IPv4       |
335    +-------+------------+
336    | 2     | UDP        |
337    +-------+------------+
338    | 3     | VXLAN      |
339    +-------+------------+
340    | 4     | Ethernet   |
341    +-------+------------+
342    | 5     | IPv6       |
343    +-------+------------+
344    | 6     | TCP        |
345    +-------+------------+
346    | 7     | END        |
347    +-------+------------+
348
349 |
350
351 .. _table_rte_flow_tcpv4_as_l4_meta:
352
353 .. table:: TCPv4 as L4 with meta items
354
355    +-------+----------+
356    | Index | Item     |
357    +=======+==========+
358    | 0     | VOID     |
359    +-------+----------+
360    | 1     | Ethernet |
361    +-------+----------+
362    | 2     | VOID     |
363    +-------+----------+
364    | 3     | IPv4     |
365    +-------+----------+
366    | 4     | TCP      |
367    +-------+----------+
368    | 5     | VOID     |
369    +-------+----------+
370    | 6     | VOID     |
371    +-------+----------+
372    | 7     | END      |
373    +-------+----------+
374
375 The above example shows how meta items do not affect packet data matching
376 items, as long as those remain stacked properly. The resulting matching
377 pattern is identical to "TCPv4 as L4".
378
379 .. _table_rte_flow_udpv6_anywhere:
380
381 .. table:: UDPv6 anywhere
382
383    +-------+------+
384    | Index | Item |
385    +=======+======+
386    | 0     | IPv6 |
387    +-------+------+
388    | 1     | UDP  |
389    +-------+------+
390    | 2     | END  |
391    +-------+------+
392
393 If supported by the PMD, omitting one or several protocol layers at the
394 bottom of the stack as in the above example (missing an Ethernet
395 specification) enables looking up anywhere in packets.
396
397 It is unspecified whether the payload of supported encapsulations
398 (e.g. VXLAN payload) is matched by such a pattern, which may apply to inner,
399 outer or both packets.
400
401 .. _table_rte_flow_invalid_l3:
402
403 .. table:: Invalid, missing L3
404
405    +-------+----------+
406    | Index | Item     |
407    +=======+==========+
408    | 0     | Ethernet |
409    +-------+----------+
410    | 1     | UDP      |
411    +-------+----------+
412    | 2     | END      |
413    +-------+----------+
414
415 The above pattern is invalid due to a missing L3 specification between L2
416 (Ethernet) and L4 (UDP). Doing so is only allowed at the bottom and at the
417 top of the stack.
418
419 Meta item types
420 ~~~~~~~~~~~~~~~
421
422 They match meta-data or affect pattern processing instead of matching packet
423 data directly, most of them do not need a specification structure. This
424 particularity allows them to be specified anywhere in the stack without
425 causing any side effect.
426
427 Item: ``END``
428 ^^^^^^^^^^^^^
429
430 End marker for item lists. Prevents further processing of items, thereby
431 ending the pattern.
432
433 - Its numeric value is 0 for convenience.
434 - PMD support is mandatory.
435 - ``spec``, ``last`` and ``mask`` are ignored.
436
437 .. _table_rte_flow_item_end:
438
439 .. table:: END
440
441    +----------+---------+
442    | Field    | Value   |
443    +==========+=========+
444    | ``spec`` | ignored |
445    +----------+---------+
446    | ``last`` | ignored |
447    +----------+---------+
448    | ``mask`` | ignored |
449    +----------+---------+
450
451 Item: ``VOID``
452 ^^^^^^^^^^^^^^
453
454 Used as a placeholder for convenience. It is ignored and simply discarded by
455 PMDs.
456
457 - PMD support is mandatory.
458 - ``spec``, ``last`` and ``mask`` are ignored.
459
460 .. _table_rte_flow_item_void:
461
462 .. table:: VOID
463
464    +----------+---------+
465    | Field    | Value   |
466    +==========+=========+
467    | ``spec`` | ignored |
468    +----------+---------+
469    | ``last`` | ignored |
470    +----------+---------+
471    | ``mask`` | ignored |
472    +----------+---------+
473
474 One usage example for this type is generating rules that share a common
475 prefix quickly without reallocating memory, only by updating item types:
476
477 .. _table_rte_flow_item_void_example:
478
479 .. table:: TCP, UDP or ICMP as L4
480
481    +-------+--------------------+
482    | Index | Item               |
483    +=======+====================+
484    | 0     | Ethernet           |
485    +-------+--------------------+
486    | 1     | IPv4               |
487    +-------+------+------+------+
488    | 2     | UDP  | VOID | VOID |
489    +-------+------+------+------+
490    | 3     | VOID | TCP  | VOID |
491    +-------+------+------+------+
492    | 4     | VOID | VOID | ICMP |
493    +-------+------+------+------+
494    | 5     | END                |
495    +-------+--------------------+
496
497 Item: ``INVERT``
498 ^^^^^^^^^^^^^^^^
499
500 Inverted matching, i.e. process packets that do not match the pattern.
501
502 - ``spec``, ``last`` and ``mask`` are ignored.
503
504 .. _table_rte_flow_item_invert:
505
506 .. table:: INVERT
507
508    +----------+---------+
509    | Field    | Value   |
510    +==========+=========+
511    | ``spec`` | ignored |
512    +----------+---------+
513    | ``last`` | ignored |
514    +----------+---------+
515    | ``mask`` | ignored |
516    +----------+---------+
517
518 Usage example, matching non-TCPv4 packets only:
519
520 .. _table_rte_flow_item_invert_example:
521
522 .. table:: Anything but TCPv4
523
524    +-------+----------+
525    | Index | Item     |
526    +=======+==========+
527    | 0     | INVERT   |
528    +-------+----------+
529    | 1     | Ethernet |
530    +-------+----------+
531    | 2     | IPv4     |
532    +-------+----------+
533    | 3     | TCP      |
534    +-------+----------+
535    | 4     | END      |
536    +-------+----------+
537
538 Item: ``PF``
539 ^^^^^^^^^^^^
540
541 This item is deprecated. Consider:
542  - `Item: PORT_REPRESENTOR`_
543  - `Item: REPRESENTED_PORT`_
544
545 Matches traffic originating from (ingress) or going to (egress) the physical
546 function of the current device.
547
548 If supported, should work even if the physical function is not managed by
549 the application and thus not associated with a DPDK port ID.
550
551 - Can be combined with any number of `Item: VF`_ to match both PF and VF
552   traffic.
553 - ``spec``, ``last`` and ``mask`` must not be set.
554
555 .. _table_rte_flow_item_pf:
556
557 .. table:: PF
558
559    +----------+-------+
560    | Field    | Value |
561    +==========+=======+
562    | ``spec`` | unset |
563    +----------+-------+
564    | ``last`` | unset |
565    +----------+-------+
566    | ``mask`` | unset |
567    +----------+-------+
568
569 Item: ``VF``
570 ^^^^^^^^^^^^
571
572 This item is deprecated. Consider:
573  - `Item: PORT_REPRESENTOR`_
574  - `Item: REPRESENTED_PORT`_
575
576 Matches traffic originating from (ingress) or going to (egress) a given
577 virtual function of the current device.
578
579 If supported, should work even if the virtual function is not managed by the
580 application and thus not associated with a DPDK port ID.
581
582 Note this pattern item does not match VF representors traffic which, as
583 separate entities, should be addressed through their own DPDK port IDs.
584
585 - Can be specified multiple times to match traffic addressed to several VF
586   IDs.
587 - Can be combined with a PF item to match both PF and VF traffic.
588 - Default ``mask`` matches any VF ID.
589
590 .. _table_rte_flow_item_vf:
591
592 .. table:: VF
593
594    +----------+----------+---------------------------+
595    | Field    | Subfield | Value                     |
596    +==========+==========+===========================+
597    | ``spec`` | ``id``   | destination VF ID         |
598    +----------+----------+---------------------------+
599    | ``last`` | ``id``   | upper range value         |
600    +----------+----------+---------------------------+
601    | ``mask`` | ``id``   | zeroed to match any VF ID |
602    +----------+----------+---------------------------+
603
604 Item: ``PHY_PORT``
605 ^^^^^^^^^^^^^^^^^^
606
607 This item is deprecated. Consider:
608  - `Item: PORT_REPRESENTOR`_
609  - `Item: REPRESENTED_PORT`_
610
611 Matches traffic originating from (ingress) or going to (egress) a physical
612 port of the underlying device.
613
614 The first PHY_PORT item overrides the physical port normally associated with
615 the specified DPDK input port (port_id). This item can be provided several
616 times to match additional physical ports.
617
618 Note that physical ports are not necessarily tied to DPDK input ports
619 (port_id) when those are not under DPDK control. Possible values are
620 specific to each device, they are not necessarily indexed from zero and may
621 not be contiguous.
622
623 As a device property, the list of allowed values as well as the value
624 associated with a port_id should be retrieved by other means.
625
626 - Default ``mask`` matches any port index.
627
628 .. _table_rte_flow_item_phy_port:
629
630 .. table:: PHY_PORT
631
632    +----------+-----------+--------------------------------+
633    | Field    | Subfield  | Value                          |
634    +==========+===========+================================+
635    | ``spec`` | ``index`` | physical port index            |
636    +----------+-----------+--------------------------------+
637    | ``last`` | ``index`` | upper range value              |
638    +----------+-----------+--------------------------------+
639    | ``mask`` | ``index`` | zeroed to match any port index |
640    +----------+-----------+--------------------------------+
641
642 Item: ``PORT_ID``
643 ^^^^^^^^^^^^^^^^^
644
645 This item is deprecated. Consider:
646  - `Item: PORT_REPRESENTOR`_
647  - `Item: REPRESENTED_PORT`_
648
649 Matches traffic originating from (ingress) or going to (egress) a given DPDK
650 port ID.
651
652 Normally only supported if the port ID in question is known by the
653 underlying PMD and related to the device the flow rule is created against.
654
655 This must not be confused with `Item: PHY_PORT`_ which refers to the
656 physical port of a device, whereas `Item: PORT_ID`_ refers to a ``struct
657 rte_eth_dev`` object on the application side (also known as "port
658 representor" depending on the kind of underlying device).
659
660 - Default ``mask`` matches the specified DPDK port ID.
661
662 .. _table_rte_flow_item_port_id:
663
664 .. table:: PORT_ID
665
666    +----------+----------+-----------------------------+
667    | Field    | Subfield | Value                       |
668    +==========+==========+=============================+
669    | ``spec`` | ``id``   | DPDK port ID                |
670    +----------+----------+-----------------------------+
671    | ``last`` | ``id``   | upper range value           |
672    +----------+----------+-----------------------------+
673    | ``mask`` | ``id``   | zeroed to match any port ID |
674    +----------+----------+-----------------------------+
675
676 Item: ``MARK``
677 ^^^^^^^^^^^^^^
678
679 Matches an arbitrary integer value which was set using the ``MARK`` action in
680 a previously matched rule.
681
682 This item can only specified once as a match criteria as the ``MARK`` action can
683 only be specified once in a flow action.
684
685 Note the value of MARK field is arbitrary and application defined.
686
687 Depending on the underlying implementation the MARK item may be supported on
688 the physical device, with virtual groups in the PMD or not at all.
689
690 - Default ``mask`` matches any integer value.
691
692 .. _table_rte_flow_item_mark:
693
694 .. table:: MARK
695
696    +----------+----------+---------------------------+
697    | Field    | Subfield | Value                     |
698    +==========+==========+===========================+
699    | ``spec`` | ``id``   | integer value             |
700    +----------+--------------------------------------+
701    | ``last`` | ``id``   | upper range value         |
702    +----------+----------+---------------------------+
703    | ``mask`` | ``id``   | zeroed to match any value |
704    +----------+----------+---------------------------+
705
706 Item: ``TAG``
707 ^^^^^^^^^^^^^
708
709 Matches tag item set by other flows. Multiple tags are supported by specifying
710 ``index``.
711
712 - Default ``mask`` matches the specified tag value and index.
713
714 .. _table_rte_flow_item_tag:
715
716 .. table:: TAG
717
718    +----------+----------+----------------------------------------+
719    | Field    | Subfield  | Value                                 |
720    +==========+===========+=======================================+
721    | ``spec`` | ``data``  | 32 bit flow tag value                 |
722    |          +-----------+---------------------------------------+
723    |          | ``index`` | index of flow tag                     |
724    +----------+-----------+---------------------------------------+
725    | ``last`` | ``data``  | upper range value                     |
726    |          +-----------+---------------------------------------+
727    |          | ``index`` | field is ignored                      |
728    +----------+-----------+---------------------------------------+
729    | ``mask`` | ``data``  | bit-mask applies to "spec" and "last" |
730    |          +-----------+---------------------------------------+
731    |          | ``index`` | field is ignored                      |
732    +----------+-----------+---------------------------------------+
733
734 Item: ``META``
735 ^^^^^^^^^^^^^^^^^
736
737 Matches 32 bit metadata item set.
738
739 On egress, metadata can be set either by mbuf metadata field with
740 RTE_MBUF_DYNFLAG_TX_METADATA flag or ``SET_META`` action. On ingress, ``SET_META``
741 action sets metadata for a packet and the metadata will be reported via
742 ``metadata`` dynamic field of ``rte_mbuf`` with RTE_MBUF_DYNFLAG_RX_METADATA flag.
743
744 - Default ``mask`` matches the specified Rx metadata value.
745
746 .. _table_rte_flow_item_meta:
747
748 .. table:: META
749
750    +----------+----------+---------------------------------------+
751    | Field    | Subfield | Value                                 |
752    +==========+==========+=======================================+
753    | ``spec`` | ``data`` | 32 bit metadata value                 |
754    +----------+----------+---------------------------------------+
755    | ``last`` | ``data`` | upper range value                     |
756    +----------+----------+---------------------------------------+
757    | ``mask`` | ``data`` | bit-mask applies to "spec" and "last" |
758    +----------+----------+---------------------------------------+
759
760 Data matching item types
761 ~~~~~~~~~~~~~~~~~~~~~~~~
762
763 Most of these are basically protocol header definitions with associated
764 bit-masks. They must be specified (stacked) from lowest to highest protocol
765 layer to form a matching pattern.
766
767 Item: ``ANY``
768 ^^^^^^^^^^^^^
769
770 Matches any protocol in place of the current layer, a single ANY may also
771 stand for several protocol layers.
772
773 This is usually specified as the first pattern item when looking for a
774 protocol anywhere in a packet.
775
776 - Default ``mask`` stands for any number of layers.
777
778 .. _table_rte_flow_item_any:
779
780 .. table:: ANY
781
782    +----------+----------+--------------------------------------+
783    | Field    | Subfield | Value                                |
784    +==========+==========+======================================+
785    | ``spec`` | ``num``  | number of layers covered             |
786    +----------+----------+--------------------------------------+
787    | ``last`` | ``num``  | upper range value                    |
788    +----------+----------+--------------------------------------+
789    | ``mask`` | ``num``  | zeroed to cover any number of layers |
790    +----------+----------+--------------------------------------+
791
792 Example for VXLAN TCP payload matching regardless of outer L3 (IPv4 or IPv6)
793 and L4 (UDP) both matched by the first ANY specification, and inner L3 (IPv4
794 or IPv6) matched by the second ANY specification:
795
796 .. _table_rte_flow_item_any_example:
797
798 .. table:: TCP in VXLAN with wildcards
799
800    +-------+------+----------+----------+-------+
801    | Index | Item | Field    | Subfield | Value |
802    +=======+======+==========+==========+=======+
803    | 0     | Ethernet                           |
804    +-------+------+----------+----------+-------+
805    | 1     | ANY  | ``spec`` | ``num``  | 2     |
806    +-------+------+----------+----------+-------+
807    | 2     | VXLAN                              |
808    +-------+------------------------------------+
809    | 3     | Ethernet                           |
810    +-------+------+----------+----------+-------+
811    | 4     | ANY  | ``spec`` | ``num``  | 1     |
812    +-------+------+----------+----------+-------+
813    | 5     | TCP                                |
814    +-------+------------------------------------+
815    | 6     | END                                |
816    +-------+------------------------------------+
817
818 Item: ``RAW``
819 ^^^^^^^^^^^^^
820
821 Matches a byte string of a given length at a given offset.
822
823 Offset is either absolute (using the start of the packet) or relative to the
824 end of the previous matched item in the stack, in which case negative values
825 are allowed.
826
827 If search is enabled, offset is used as the starting point. The search area
828 can be delimited by setting limit to a nonzero value, which is the maximum
829 number of bytes after offset where the pattern may start.
830
831 Matching a zero-length pattern is allowed, doing so resets the relative
832 offset for subsequent items.
833
834 - This type does not support ranges (``last`` field).
835 - Default ``mask`` matches all fields exactly.
836
837 .. _table_rte_flow_item_raw:
838
839 .. table:: RAW
840
841    +----------+--------------+-------------------------------------------------+
842    | Field    | Subfield     | Value                                           |
843    +==========+==============+=================================================+
844    | ``spec`` | ``relative`` | look for pattern after the previous item        |
845    |          +--------------+-------------------------------------------------+
846    |          | ``search``   | search pattern from offset (see also ``limit``) |
847    |          +--------------+-------------------------------------------------+
848    |          | ``reserved`` | reserved, must be set to zero                   |
849    |          +--------------+-------------------------------------------------+
850    |          | ``offset``   | absolute or relative offset for ``pattern``     |
851    |          +--------------+-------------------------------------------------+
852    |          | ``limit``    | search area limit for start of ``pattern``      |
853    |          +--------------+-------------------------------------------------+
854    |          | ``length``   | ``pattern`` length                              |
855    |          +--------------+-------------------------------------------------+
856    |          | ``pattern``  | byte string to look for                         |
857    +----------+--------------+-------------------------------------------------+
858    | ``last`` | if specified, either all 0 or with the same values as ``spec`` |
859    +----------+----------------------------------------------------------------+
860    | ``mask`` | bit-mask applied to ``spec`` values with usual behavior        |
861    +----------+----------------------------------------------------------------+
862
863 Example pattern looking for several strings at various offsets of a UDP
864 payload, using combined RAW items:
865
866 .. _table_rte_flow_item_raw_example:
867
868 .. table:: UDP payload matching
869
870    +-------+------+----------+--------------+-------+
871    | Index | Item | Field    | Subfield     | Value |
872    +=======+======+==========+==============+=======+
873    | 0     | Ethernet                               |
874    +-------+----------------------------------------+
875    | 1     | IPv4                                   |
876    +-------+----------------------------------------+
877    | 2     | UDP                                    |
878    +-------+------+----------+--------------+-------+
879    | 3     | RAW  | ``spec`` | ``relative`` | 1     |
880    |       |      |          +--------------+-------+
881    |       |      |          | ``search``   | 1     |
882    |       |      |          +--------------+-------+
883    |       |      |          | ``offset``   | 10    |
884    |       |      |          +--------------+-------+
885    |       |      |          | ``limit``    | 0     |
886    |       |      |          +--------------+-------+
887    |       |      |          | ``length``   | 3     |
888    |       |      |          +--------------+-------+
889    |       |      |          | ``pattern``  | "foo" |
890    +-------+------+----------+--------------+-------+
891    | 4     | RAW  | ``spec`` | ``relative`` | 1     |
892    |       |      |          +--------------+-------+
893    |       |      |          | ``search``   | 0     |
894    |       |      |          +--------------+-------+
895    |       |      |          | ``offset``   | 20    |
896    |       |      |          +--------------+-------+
897    |       |      |          | ``limit``    | 0     |
898    |       |      |          +--------------+-------+
899    |       |      |          | ``length``   | 3     |
900    |       |      |          +--------------+-------+
901    |       |      |          | ``pattern``  | "bar" |
902    +-------+------+----------+--------------+-------+
903    | 5     | RAW  | ``spec`` | ``relative`` | 1     |
904    |       |      |          +--------------+-------+
905    |       |      |          | ``search``   | 0     |
906    |       |      |          +--------------+-------+
907    |       |      |          | ``offset``   | -29   |
908    |       |      |          +--------------+-------+
909    |       |      |          | ``limit``    | 0     |
910    |       |      |          +--------------+-------+
911    |       |      |          | ``length``   | 3     |
912    |       |      |          +--------------+-------+
913    |       |      |          | ``pattern``  | "baz" |
914    +-------+------+----------+--------------+-------+
915    | 6     | END                                    |
916    +-------+----------------------------------------+
917
918 This translates to:
919
920 - Locate "foo" at least 10 bytes deep inside UDP payload.
921 - Locate "bar" after "foo" plus 20 bytes.
922 - Locate "baz" after "bar" minus 29 bytes.
923
924 Such a packet may be represented as follows (not to scale)::
925
926  0                     >= 10 B           == 20 B
927  |                  |<--------->|     |<--------->|
928  |                  |           |     |           |
929  |-----|------|-----|-----|-----|-----|-----------|-----|------|
930  | ETH | IPv4 | UDP | ... | baz | foo | ......... | bar | .... |
931  |-----|------|-----|-----|-----|-----|-----------|-----|------|
932                           |                             |
933                           |<--------------------------->|
934                                       == 29 B
935
936 Note that matching subsequent pattern items would resume after "baz", not
937 "bar" since matching is always performed after the previous item of the
938 stack.
939
940 Item: ``ETH``
941 ^^^^^^^^^^^^^
942
943 Matches an Ethernet header.
944
945 The ``type`` field either stands for "EtherType" or "TPID" when followed by
946 so-called layer 2.5 pattern items such as ``RTE_FLOW_ITEM_TYPE_VLAN``. In
947 the latter case, ``type`` refers to that of the outer header, with the inner
948 EtherType/TPID provided by the subsequent pattern item. This is the same
949 order as on the wire.
950 If the ``type`` field contains a TPID value, then only tagged packets with the
951 specified TPID will match the pattern.
952 The field ``has_vlan`` can be used to match any type of tagged packets,
953 instead of using the ``type`` field.
954 If the ``type`` and ``has_vlan`` fields are not specified, then both tagged
955 and untagged packets will match the pattern.
956
957 - ``dst``: destination MAC.
958 - ``src``: source MAC.
959 - ``type``: EtherType or TPID.
960 - ``has_vlan``: packet header contains at least one VLAN.
961 - Default ``mask`` matches destination and source addresses only.
962
963 Item: ``VLAN``
964 ^^^^^^^^^^^^^^
965
966 Matches an 802.1Q/ad VLAN tag.
967
968 The corresponding standard outer EtherType (TPID) values are
969 ``RTE_ETHER_TYPE_VLAN`` or ``RTE_ETHER_TYPE_QINQ``. It can be overridden by the
970 preceding pattern item.
971 If a ``VLAN`` item is present in the pattern, then only tagged packets will
972 match the pattern.
973 The field ``has_more_vlan`` can be used to match any type of tagged packets,
974 instead of using the ``inner_type field``.
975 If the ``inner_type`` and ``has_more_vlan`` fields are not specified,
976 then any tagged packets will match the pattern.
977
978 - ``tci``: tag control information.
979 - ``inner_type``: inner EtherType or TPID.
980 - ``has_more_vlan``: packet header contains at least one more VLAN, after this VLAN.
981 - Default ``mask`` matches the VID part of TCI only (lower 12 bits).
982
983 Item: ``IPV4``
984 ^^^^^^^^^^^^^^
985
986 Matches an IPv4 header.
987
988 Note: IPv4 options are handled by dedicated pattern items.
989
990 - ``hdr``: IPv4 header definition (``rte_ip.h``).
991 - Default ``mask`` matches source and destination addresses only.
992
993 Item: ``IPV6``
994 ^^^^^^^^^^^^^^
995
996 Matches an IPv6 header.
997
998 Dedicated flags indicate if header contains specific extension headers.
999 To match on packets containing a specific extension header, an application
1000 should match on the dedicated flag set to 1.
1001 To match on packets not containing a specific extension header, an application
1002 should match on the dedicated flag clear to 0.
1003 In case application doesn't care about the existence of a specific extension
1004 header, it should not specify the dedicated flag for matching.
1005
1006 - ``hdr``: IPv6 header definition (``rte_ip.h``).
1007 - ``has_hop_ext``: header contains Hop-by-Hop Options extension header.
1008 - ``has_route_ext``: header contains Routing extension header.
1009 - ``has_frag_ext``: header contains Fragment extension header.
1010 - ``has_auth_ext``: header contains Authentication extension header.
1011 - ``has_esp_ext``: header contains Encapsulation Security Payload extension header.
1012 - ``has_dest_ext``: header contains Destination Options extension header.
1013 - ``has_mobil_ext``: header contains Mobility extension header.
1014 - ``has_hip_ext``: header contains Host Identity Protocol extension header.
1015 - ``has_shim6_ext``: header contains Shim6 Protocol extension header.
1016 - Default ``mask`` matches ``hdr`` source and destination addresses only.
1017
1018 Item: ``ICMP``
1019 ^^^^^^^^^^^^^^
1020
1021 Matches an ICMP header.
1022
1023 - ``hdr``: ICMP header definition (``rte_icmp.h``).
1024 - Default ``mask`` matches ICMP type and code only.
1025
1026 Item: ``UDP``
1027 ^^^^^^^^^^^^^
1028
1029 Matches a UDP header.
1030
1031 - ``hdr``: UDP header definition (``rte_udp.h``).
1032 - Default ``mask`` matches source and destination ports only.
1033
1034 Item: ``TCP``
1035 ^^^^^^^^^^^^^
1036
1037 Matches a TCP header.
1038
1039 - ``hdr``: TCP header definition (``rte_tcp.h``).
1040 - Default ``mask`` matches source and destination ports only.
1041
1042 Item: ``SCTP``
1043 ^^^^^^^^^^^^^^
1044
1045 Matches a SCTP header.
1046
1047 - ``hdr``: SCTP header definition (``rte_sctp.h``).
1048 - Default ``mask`` matches source and destination ports only.
1049
1050 Item: ``VXLAN``
1051 ^^^^^^^^^^^^^^^
1052
1053 Matches a VXLAN header (RFC 7348).
1054
1055 - ``flags``: normally 0x08 (I flag).
1056 - ``rsvd0``: reserved, normally 0x000000.
1057 - ``vni``: VXLAN network identifier.
1058 - ``rsvd1``: reserved, normally 0x00.
1059 - Default ``mask`` matches VNI only.
1060
1061 Item: ``E_TAG``
1062 ^^^^^^^^^^^^^^^
1063
1064 Matches an IEEE 802.1BR E-Tag header.
1065
1066 The corresponding standard outer EtherType (TPID) value is
1067 ``RTE_ETHER_TYPE_ETAG``. It can be overridden by the preceding pattern item.
1068
1069 - ``epcp_edei_in_ecid_b``: E-Tag control information (E-TCI), E-PCP (3b),
1070   E-DEI (1b), ingress E-CID base (12b).
1071 - ``rsvd_grp_ecid_b``: reserved (2b), GRP (2b), E-CID base (12b).
1072 - ``in_ecid_e``: ingress E-CID ext.
1073 - ``ecid_e``: E-CID ext.
1074 - ``inner_type``: inner EtherType or TPID.
1075 - Default ``mask`` simultaneously matches GRP and E-CID base.
1076
1077 Item: ``NVGRE``
1078 ^^^^^^^^^^^^^^^
1079
1080 Matches a NVGRE header (RFC 7637).
1081
1082 - ``c_k_s_rsvd0_ver``: checksum (1b), undefined (1b), key bit (1b),
1083   sequence number (1b), reserved 0 (9b), version (3b). This field must have
1084   value 0x2000 according to RFC 7637.
1085 - ``protocol``: protocol type (0x6558).
1086 - ``tni``: virtual subnet ID.
1087 - ``flow_id``: flow ID.
1088 - Default ``mask`` matches TNI only.
1089
1090 Item: ``MPLS``
1091 ^^^^^^^^^^^^^^
1092
1093 Matches a MPLS header.
1094
1095 - ``label_tc_s_ttl``: label, TC, Bottom of Stack and TTL.
1096 - Default ``mask`` matches label only.
1097
1098 Item: ``GRE``
1099 ^^^^^^^^^^^^^
1100
1101 Matches a GRE header.
1102
1103 - ``c_rsvd0_ver``: checksum, reserved 0 and version.
1104 - ``protocol``: protocol type.
1105 - Default ``mask`` matches protocol only.
1106
1107 Item: ``GRE_KEY``
1108 ^^^^^^^^^^^^^^^^^
1109 This action is deprecated. Consider `Item: GRE_OPTION`.
1110
1111 Matches a GRE key field.
1112 This should be preceded by item ``GRE``.
1113
1114 - Value to be matched is a big-endian 32 bit integer.
1115 - When this item present it implicitly match K bit in default mask as "1"
1116
1117 Item: ``GRE_OPTION``
1118 ^^^^^^^^^^^^^^^^^^^^
1119
1120 Matches a GRE optional fields (checksum/key/sequence).
1121 This should be preceded by item ``GRE``.
1122
1123 - ``checksum``: checksum.
1124 - ``key``: key.
1125 - ``sequence``: sequence.
1126 - The items in GRE_OPTION do not change bit flags(c_bit/k_bit/s_bit) in GRE
1127   item. The bit flags need be set with GRE item by application. When the items
1128   present, the corresponding bits in GRE spec and mask should be set "1" by
1129   application, it means to match specified value of the fields. When the items
1130   no present, but the corresponding bits in GRE spec and mask is "1", it means
1131   to match any value of the fields.
1132
1133 Item: ``FUZZY``
1134 ^^^^^^^^^^^^^^^
1135
1136 Fuzzy pattern match, expect faster than default.
1137
1138 This is for device that support fuzzy match option. Usually a fuzzy match is
1139 fast but the cost is accuracy. i.e. Signature Match only match pattern's hash
1140 value, but it is possible two different patterns have the same hash value.
1141
1142 Matching accuracy level can be configured by threshold. Driver can divide the
1143 range of threshold and map to different accuracy levels that device support.
1144
1145 Threshold 0 means perfect match (no fuzziness), while threshold 0xffffffff
1146 means fuzziest match.
1147
1148 .. _table_rte_flow_item_fuzzy:
1149
1150 .. table:: FUZZY
1151
1152    +----------+---------------+--------------------------------------------------+
1153    | Field    |   Subfield    | Value                                            |
1154    +==========+===============+==================================================+
1155    | ``spec`` | ``threshold`` | 0 as perfect match, 0xffffffff as fuzziest match |
1156    +----------+---------------+--------------------------------------------------+
1157    | ``last`` | ``threshold`` | upper range value                                |
1158    +----------+---------------+--------------------------------------------------+
1159    | ``mask`` | ``threshold`` | bit-mask apply to "spec" and "last"              |
1160    +----------+---------------+--------------------------------------------------+
1161
1162 Usage example, fuzzy match a TCPv4 packets:
1163
1164 .. _table_rte_flow_item_fuzzy_example:
1165
1166 .. table:: Fuzzy matching
1167
1168    +-------+----------+
1169    | Index | Item     |
1170    +=======+==========+
1171    | 0     | FUZZY    |
1172    +-------+----------+
1173    | 1     | Ethernet |
1174    +-------+----------+
1175    | 2     | IPv4     |
1176    +-------+----------+
1177    | 3     | TCP      |
1178    +-------+----------+
1179    | 4     | END      |
1180    +-------+----------+
1181
1182 Item: ``GTP``, ``GTPC``, ``GTPU``
1183 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1184
1185 Matches a GTPv1 header.
1186
1187 Note: GTP, GTPC and GTPU use the same structure. GTPC and GTPU item
1188 are defined for a user-friendly API when creating GTP-C and GTP-U
1189 flow rules.
1190
1191 - ``v_pt_rsv_flags``: version (3b), protocol type (1b), reserved (1b),
1192   extension header flag (1b), sequence number flag (1b), N-PDU number
1193   flag (1b).
1194 - ``msg_type``: message type.
1195 - ``msg_len``: message length.
1196 - ``teid``: tunnel endpoint identifier.
1197 - Default ``mask`` matches teid only.
1198
1199 Item: ``ESP``
1200 ^^^^^^^^^^^^^
1201
1202 Matches an ESP header.
1203
1204 - ``hdr``: ESP header definition (``rte_esp.h``).
1205 - Default ``mask`` matches SPI only.
1206
1207 Item: ``GENEVE``
1208 ^^^^^^^^^^^^^^^^
1209
1210 Matches a GENEVE header.
1211
1212 - ``ver_opt_len_o_c_rsvd0``: version (2b), length of the options fields (6b),
1213   OAM packet (1b), critical options present (1b), reserved 0 (6b).
1214 - ``protocol``: protocol type.
1215 - ``vni``: virtual network identifier.
1216 - ``rsvd1``: reserved, normally 0x00.
1217 - Default ``mask`` matches VNI only.
1218
1219 Item: ``VXLAN-GPE``
1220 ^^^^^^^^^^^^^^^^^^^
1221
1222 Matches a VXLAN-GPE header (draft-ietf-nvo3-vxlan-gpe-05).
1223
1224 - ``flags``: normally 0x0C (I and P flags).
1225 - ``rsvd0``: reserved, normally 0x0000.
1226 - ``protocol``: protocol type.
1227 - ``vni``: VXLAN network identifier.
1228 - ``rsvd1``: reserved, normally 0x00.
1229 - Default ``mask`` matches VNI only.
1230
1231 Item: ``ARP_ETH_IPV4``
1232 ^^^^^^^^^^^^^^^^^^^^^^
1233
1234 Matches an ARP header for Ethernet/IPv4.
1235
1236 - ``hdr``: hardware type, normally 1.
1237 - ``pro``: protocol type, normally 0x0800.
1238 - ``hln``: hardware address length, normally 6.
1239 - ``pln``: protocol address length, normally 4.
1240 - ``op``: opcode (1 for request, 2 for reply).
1241 - ``sha``: sender hardware address.
1242 - ``spa``: sender IPv4 address.
1243 - ``tha``: target hardware address.
1244 - ``tpa``: target IPv4 address.
1245 - Default ``mask`` matches SHA, SPA, THA and TPA.
1246
1247 Item: ``IPV6_EXT``
1248 ^^^^^^^^^^^^^^^^^^
1249
1250 Matches the presence of any IPv6 extension header.
1251
1252 - ``next_hdr``: next header.
1253 - Default ``mask`` matches ``next_hdr``.
1254
1255 Normally preceded by any of:
1256
1257 - `Item: IPV6`_
1258 - `Item: IPV6_EXT`_
1259
1260 Item: ``IPV6_FRAG_EXT``
1261 ^^^^^^^^^^^^^^^^^^^^^^^
1262
1263 Matches the presence of IPv6 fragment extension header.
1264
1265 - ``hdr``: IPv6 fragment extension header definition (``rte_ip.h``).
1266
1267 Normally preceded by any of:
1268
1269 - `Item: IPV6`_
1270 - `Item: IPV6_EXT`_
1271
1272 Item: ``ICMP6``
1273 ^^^^^^^^^^^^^^^
1274
1275 Matches any ICMPv6 header.
1276
1277 - ``type``: ICMPv6 type.
1278 - ``code``: ICMPv6 code.
1279 - ``checksum``: ICMPv6 checksum.
1280 - Default ``mask`` matches ``type`` and ``code``.
1281
1282 Item: ``ICMP6_ND_NS``
1283 ^^^^^^^^^^^^^^^^^^^^^
1284
1285 Matches an ICMPv6 neighbor discovery solicitation.
1286
1287 - ``type``: ICMPv6 type, normally 135.
1288 - ``code``: ICMPv6 code, normally 0.
1289 - ``checksum``: ICMPv6 checksum.
1290 - ``reserved``: reserved, normally 0.
1291 - ``target_addr``: target address.
1292 - Default ``mask`` matches target address only.
1293
1294 Item: ``ICMP6_ND_NA``
1295 ^^^^^^^^^^^^^^^^^^^^^
1296
1297 Matches an ICMPv6 neighbor discovery advertisement.
1298
1299 - ``type``: ICMPv6 type, normally 136.
1300 - ``code``: ICMPv6 code, normally 0.
1301 - ``checksum``: ICMPv6 checksum.
1302 - ``rso_reserved``: route flag (1b), solicited flag (1b), override flag
1303   (1b), reserved (29b).
1304 - ``target_addr``: target address.
1305 - Default ``mask`` matches target address only.
1306
1307 Item: ``ICMP6_ND_OPT``
1308 ^^^^^^^^^^^^^^^^^^^^^^
1309
1310 Matches the presence of any ICMPv6 neighbor discovery option.
1311
1312 - ``type``: ND option type.
1313 - ``length``: ND option length.
1314 - Default ``mask`` matches type only.
1315
1316 Normally preceded by any of:
1317
1318 - `Item: ICMP6_ND_NA`_
1319 - `Item: ICMP6_ND_NS`_
1320 - `Item: ICMP6_ND_OPT`_
1321
1322 Item: ``ICMP6_ND_OPT_SLA_ETH``
1323 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1324
1325 Matches an ICMPv6 neighbor discovery source Ethernet link-layer address
1326 option.
1327
1328 - ``type``: ND option type, normally 1.
1329 - ``length``: ND option length, normally 1.
1330 - ``sla``: source Ethernet LLA.
1331 - Default ``mask`` matches source link-layer address only.
1332
1333 Normally preceded by any of:
1334
1335 - `Item: ICMP6_ND_NA`_
1336 - `Item: ICMP6_ND_OPT`_
1337
1338 Item: ``ICMP6_ND_OPT_TLA_ETH``
1339 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1340
1341 Matches an ICMPv6 neighbor discovery target Ethernet link-layer address
1342 option.
1343
1344 - ``type``: ND option type, normally 2.
1345 - ``length``: ND option length, normally 1.
1346 - ``tla``: target Ethernet LLA.
1347 - Default ``mask`` matches target link-layer address only.
1348
1349 Normally preceded by any of:
1350
1351 - `Item: ICMP6_ND_NS`_
1352 - `Item: ICMP6_ND_OPT`_
1353
1354 Item: ``META``
1355 ^^^^^^^^^^^^^^
1356
1357 Matches an application specific 32 bit metadata item.
1358
1359 - Default ``mask`` matches the specified metadata value.
1360
1361 Item: ``GTP_PSC``
1362 ^^^^^^^^^^^^^^^^^
1363
1364 Matches a GTP PDU extension header with type 0x85.
1365
1366 - ``pdu_type``: PDU type.
1367 - ``qfi``: QoS flow identifier.
1368 - Default ``mask`` matches QFI only.
1369
1370 Item: ``PPPOES``, ``PPPOED``
1371 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1372
1373 Matches a PPPoE header.
1374
1375 - ``version_type``: version (4b), type (4b).
1376 - ``code``: message type.
1377 - ``session_id``: session identifier.
1378 - ``length``: payload length.
1379
1380 Item: ``PPPOE_PROTO_ID``
1381 ^^^^^^^^^^^^^^^^^^^^^^^^
1382
1383 Matches a PPPoE session protocol identifier.
1384
1385 - ``proto_id``: PPP protocol identifier.
1386 - Default ``mask`` matches proto_id only.
1387
1388 Item: ``NSH``
1389 ^^^^^^^^^^^^^
1390
1391 Matches a network service header (RFC 8300).
1392
1393 - ``version``: normally 0x0 (2 bits).
1394 - ``oam_pkt``: indicate oam packet (1 bit).
1395 - ``reserved``: reserved bit (1 bit).
1396 - ``ttl``: maximum SFF hopes (6 bits).
1397 - ``length``: total length in 4 bytes words (6 bits).
1398 - ``reserved1``: reserved1 bits (4 bits).
1399 - ``mdtype``: indicates format of NSH header (4 bits).
1400 - ``next_proto``: indicates protocol type of encap data (8 bits).
1401 - ``spi``: service path identifier (3 bytes).
1402 - ``sindex``: service index (1 byte).
1403 - Default ``mask`` matches mdtype, next_proto, spi, sindex.
1404
1405
1406 Item: ``IGMP``
1407 ^^^^^^^^^^^^^^
1408
1409 Matches a Internet Group Management Protocol (RFC 2236).
1410
1411 - ``type``: IGMP message type (Query/Report).
1412 - ``max_resp_time``: max time allowed before sending report.
1413 - ``checksum``: checksum, 1s complement of whole IGMP message.
1414 - ``group_addr``: group address, for Query value will be 0.
1415 - Default ``mask`` matches group_addr.
1416
1417
1418 Item: ``AH``
1419 ^^^^^^^^^^^^
1420
1421 Matches a IP Authentication Header (RFC 4302).
1422
1423 - ``next_hdr``: next payload after AH.
1424 - ``payload_len``: total length of AH in 4B words.
1425 - ``reserved``: reserved bits.
1426 - ``spi``: security parameters index.
1427 - ``seq_num``: counter value increased by 1 on each packet sent.
1428 - Default ``mask`` matches spi.
1429
1430 Item: ``HIGIG2``
1431 ^^^^^^^^^^^^^^^^^
1432
1433 Matches a HIGIG2 header field. It is layer 2.5 protocol and used in
1434 Broadcom switches.
1435
1436 - Default ``mask`` matches classification and vlan.
1437
1438 Item: ``L2TPV3OIP``
1439 ^^^^^^^^^^^^^^^^^^^
1440
1441 Matches a L2TPv3 over IP header.
1442
1443 - ``session_id``: L2TPv3 over IP session identifier.
1444 - Default ``mask`` matches session_id only.
1445
1446 Item: ``PFCP``
1447 ^^^^^^^^^^^^^^
1448
1449 Matches a PFCP Header.
1450
1451 - ``s_field``: S field.
1452 - ``msg_type``: message type.
1453 - ``msg_len``: message length.
1454 - ``seid``: session endpoint identifier.
1455 - Default ``mask`` matches s_field and seid.
1456
1457 Item: ``ECPRI``
1458 ^^^^^^^^^^^^^^^
1459
1460 Matches a eCPRI header.
1461
1462 - ``hdr``: eCPRI header definition (``rte_ecpri.h``).
1463 - Default ``mask`` matches nothing, for all eCPRI messages.
1464
1465 Item: ``PACKET_INTEGRITY_CHECKS``
1466 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1467
1468 Matches packet integrity.
1469 For some devices application needs to enable integration checks in HW
1470 before using this item.
1471
1472 - ``level``: the encapsulation level that should be checked:
1473    - ``level == 0`` means the default PMD mode (can be inner most / outermost).
1474    - ``level == 1`` means outermost header.
1475    - ``level > 1``  means inner header. See also RSS level.
1476 - ``packet_ok``: All HW packet integrity checks have passed based on the
1477   topmost network layer. For example, for ICMP packet the topmost network
1478   layer is L3 and for TCP or UDP packet the topmost network layer is L4.
1479 - ``l2_ok``: all layer 2 HW integrity checks passed.
1480 - ``l3_ok``: all layer 3 HW integrity checks passed.
1481 - ``l4_ok``: all layer 4 HW integrity checks passed.
1482 - ``l2_crc_ok``: layer 2 CRC check passed.
1483 - ``ipv4_csum_ok``: IPv4 checksum check passed.
1484 - ``l4_csum_ok``: layer 4 checksum check passed.
1485 - ``l3_len_ok``: the layer 3 length is smaller than the frame length.
1486
1487 Item: ``CONNTRACK``
1488 ^^^^^^^^^^^^^^^^^^^
1489
1490 Matches a conntrack state after conntrack action.
1491
1492 - ``flags``: conntrack packet state flags.
1493 - Default ``mask`` matches all state bits.
1494
1495 Item: ``PORT_REPRESENTOR``
1496 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1497
1498 Matches traffic entering the embedded switch from the given ethdev.
1499
1500 Term **ethdev** and the concept of **port representor** are synonymous.
1501 The **represented port** is an *entity* plugged to the embedded switch
1502 at the opposite end of the "wire" leading to the ethdev.
1503
1504 ::
1505
1506     .--------------------.
1507     |  PORT_REPRESENTOR  |  Ethdev (Application Port Referred to by its ID)
1508     '--------------------'
1509               ||
1510               \/
1511       .----------------.
1512       |  Logical Port  |
1513       '----------------'
1514               ||
1515               ||
1516               ||
1517               \/
1518          .----------.
1519          |  Switch  |
1520          '----------'
1521               :
1522                :
1523               :
1524                :
1525       .----------------.
1526       |  Logical Port  |
1527       '----------------'
1528               :
1529                :
1530     .--------------------.
1531     |  REPRESENTED_PORT  |  Net / Guest / Another Ethdev (Same Application)
1532     '--------------------'
1533
1534
1535 - Incompatible with `Attribute: Traffic direction`_.
1536 - Requires `Attribute: Transfer`_.
1537
1538 .. _table_rte_flow_item_ethdev:
1539
1540 .. table:: ``struct rte_flow_item_ethdev``
1541
1542    +----------+-------------+---------------------------+
1543    | Field    | Subfield    | Value                     |
1544    +==========+=============+===========================+
1545    | ``spec`` | ``port_id`` | ethdev port ID            |
1546    +----------+-------------+---------------------------+
1547    | ``last`` | ``port_id`` | upper range value         |
1548    +----------+-------------+---------------------------+
1549    | ``mask`` | ``port_id`` | zeroed for wildcard match |
1550    +----------+-------------+---------------------------+
1551
1552 - Default ``mask`` provides exact match behaviour.
1553
1554 See also `Action: PORT_REPRESENTOR`_.
1555
1556 Item: ``REPRESENTED_PORT``
1557 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1558
1559 Matches traffic entering the embedded switch from
1560 the entity represented by the given ethdev.
1561
1562 Term **ethdev** and the concept of **port representor** are synonymous.
1563 The **represented port** is an *entity* plugged to the embedded switch
1564 at the opposite end of the "wire" leading to the ethdev.
1565
1566 ::
1567
1568     .--------------------.
1569     |  PORT_REPRESENTOR  |  Ethdev (Application Port Referred to by its ID)
1570     '--------------------'
1571               :
1572                :
1573       .----------------.
1574       |  Logical Port  |
1575       '----------------'
1576               :
1577                :
1578               :
1579                :
1580          .----------.
1581          |  Switch  |
1582          '----------'
1583               /\
1584               ||
1585               ||
1586               ||
1587       .----------------.
1588       |  Logical Port  |
1589       '----------------'
1590               /\
1591               ||
1592     .--------------------.
1593     |  REPRESENTED_PORT  |  Net / Guest / Another Ethdev (Same Application)
1594     '--------------------'
1595
1596
1597 - Incompatible with `Attribute: Traffic direction`_.
1598 - Requires `Attribute: Transfer`_.
1599
1600 This item is meant to use the same structure as `Item: PORT_REPRESENTOR`_.
1601
1602 See also `Action: REPRESENTED_PORT`_.
1603
1604 Item: ``FLEX``
1605 ^^^^^^^^^^^^^^
1606
1607 Matches with the custom network protocol header that was created
1608 using rte_flow_flex_item_create() API. The application describes
1609 the desired header structure, defines the header fields attributes
1610 and header relations with preceding and following protocols and
1611 configures the ethernet devices accordingly via
1612 rte_flow_flex_item_create() routine.
1613
1614 - ``handle``: the flex item handle returned by the PMD on successful
1615   rte_flow_flex_item_create() call, mask for this field is ignored.
1616 - ``length``: match pattern length in bytes. If the length does not cover
1617   all fields defined in item configuration, the pattern spec and mask are
1618   considered by the driver as padded with trailing zeroes till the full
1619   configured item pattern length.
1620 - ``pattern``: pattern to match. The pattern is concatenation of bit fields
1621   configured at item creation. At configuration the fields are presented
1622   by sample_data array. The order of the bitfields is defined by the order
1623   of sample_data elements. The width of each bitfield is defined by the width
1624   specified in the corresponding sample_data element as well. If pattern
1625   length is smaller than configured fields overall length it is considered
1626   as padded with trailing zeroes up to full configured length, both for
1627   value and mask.
1628
1629 Item: ``L2TPV2``
1630 ^^^^^^^^^^^^^^^^^^^
1631
1632 Matches a L2TPv2 header.
1633
1634 - ``flags_version``: flags(12b), version(4b).
1635 - ``length``: total length of the message.
1636 - ``tunnel_id``: identifier for the control connection.
1637 - ``session_id``: identifier for a session within a tunnel.
1638 - ``ns``: sequence number for this date or control message.
1639 - ``nr``: sequence number expected in the next control message to be received.
1640 - ``offset_size``: offset of payload data.
1641 - ``offset_padding``: offset padding, variable length.
1642 - Default ``mask`` matches flags_version only.
1643
1644 Item: ``PPP``
1645 ^^^^^^^^^^^^^^^^^^^
1646
1647 Matches a PPP header.
1648
1649 - ``addr``: PPP address.
1650 - ``ctrl``: PPP control.
1651 - ``proto_id``: PPP protocol identifier.
1652 - Default ``mask`` matches addr, ctrl, proto_id.
1653
1654 Actions
1655 ~~~~~~~
1656
1657 Each possible action is represented by a type.
1658 An action can have an associated configuration object.
1659 Several actions combined in a list can be assigned
1660 to a flow rule and are performed in order.
1661
1662 They fall in three categories:
1663
1664 - Actions that modify the fate of matching traffic, for instance by dropping
1665   or assigning it a specific destination.
1666
1667 - Actions that modify matching traffic contents or its properties. This
1668   includes adding/removing encapsulation, encryption, compression and marks.
1669
1670 - Actions related to the flow rule itself, such as updating counters or
1671   making it non-terminating.
1672
1673 Flow rules being terminating by default, not specifying any action of the
1674 fate kind results in undefined behavior. This applies to both ingress and
1675 egress.
1676
1677 PASSTHRU, when supported, makes a flow rule non-terminating.
1678
1679 Like matching patterns, action lists are terminated by END items.
1680
1681 Example of action that redirects packets to queue index 10:
1682
1683 .. _table_rte_flow_action_example:
1684
1685 .. table:: Queue action
1686
1687    +-----------+-------+
1688    | Field     | Value |
1689    +===========+=======+
1690    | ``index`` | 10    |
1691    +-----------+-------+
1692
1693 Actions are performed in list order:
1694
1695 .. _table_rte_flow_count_then_drop:
1696
1697 .. table:: Count then drop
1698
1699    +-------+--------+
1700    | Index | Action |
1701    +=======+========+
1702    | 0     | COUNT  |
1703    +-------+--------+
1704    | 1     | DROP   |
1705    +-------+--------+
1706    | 2     | END    |
1707    +-------+--------+
1708
1709 |
1710
1711 .. _table_rte_flow_mark_count_redirect:
1712
1713 .. table:: Mark, count then redirect
1714
1715    +-------+--------+------------+-------+
1716    | Index | Action | Field      | Value |
1717    +=======+========+============+=======+
1718    | 0     | MARK   | ``mark``   | 0x2a  |
1719    +-------+--------+------------+-------+
1720    | 1     | COUNT  | ``id``     | 0     |
1721    +-------+--------+------------+-------+
1722    | 2     | QUEUE  | ``queue``  | 10    |
1723    +-------+--------+------------+-------+
1724    | 3     | END                         |
1725    +-------+-----------------------------+
1726
1727 |
1728
1729 .. _table_rte_flow_redirect_queue_5:
1730
1731 .. table:: Redirect to queue 5
1732
1733    +-------+--------+-----------+-------+
1734    | Index | Action | Field     | Value |
1735    +=======+========+===========+=======+
1736    | 0     | DROP                       |
1737    +-------+--------+-----------+-------+
1738    | 1     | QUEUE  | ``queue`` | 5     |
1739    +-------+--------+-----------+-------+
1740    | 2     | END                        |
1741    +-------+----------------------------+
1742
1743 In the above example, while DROP and QUEUE must be performed in order, both
1744 have to happen before reaching END. Only QUEUE has a visible effect.
1745
1746 Note that such a list may be thought as ambiguous and rejected on that
1747 basis.
1748
1749 .. _table_rte_flow_redirect_queue_5_3:
1750
1751 .. table:: Redirect to queues 5 and 3
1752
1753    +-------+--------+-----------+-------+
1754    | Index | Action | Field     | Value |
1755    +=======+========+===========+=======+
1756    | 0     | QUEUE  | ``queue`` | 5     |
1757    +-------+--------+-----------+-------+
1758    | 1     | VOID                       |
1759    +-------+--------+-----------+-------+
1760    | 2     | QUEUE  | ``queue`` | 3     |
1761    +-------+--------+-----------+-------+
1762    | 3     | END                        |
1763    +-------+----------------------------+
1764
1765 As previously described, all actions must be taken into account. This
1766 effectively duplicates traffic to both queues. The above example also shows
1767 that VOID is ignored.
1768
1769 Action types
1770 ~~~~~~~~~~~~
1771
1772 Common action types are described in this section.
1773
1774 Action: ``END``
1775 ^^^^^^^^^^^^^^^
1776
1777 End marker for action lists. Prevents further processing of actions, thereby
1778 ending the list.
1779
1780 - Its numeric value is 0 for convenience.
1781 - PMD support is mandatory.
1782 - No configurable properties.
1783
1784 .. _table_rte_flow_action_end:
1785
1786 .. table:: END
1787
1788    +---------------+
1789    | Field         |
1790    +===============+
1791    | no properties |
1792    +---------------+
1793
1794 Action: ``VOID``
1795 ^^^^^^^^^^^^^^^^
1796
1797 Used as a placeholder for convenience. It is ignored and simply discarded by
1798 PMDs.
1799
1800 - PMD support is mandatory.
1801 - No configurable properties.
1802
1803 .. _table_rte_flow_action_void:
1804
1805 .. table:: VOID
1806
1807    +---------------+
1808    | Field         |
1809    +===============+
1810    | no properties |
1811    +---------------+
1812
1813 Action: ``PASSTHRU``
1814 ^^^^^^^^^^^^^^^^^^^^
1815
1816 Leaves traffic up for additional processing by subsequent flow rules; makes
1817 a flow rule non-terminating.
1818
1819 - No configurable properties.
1820
1821 .. _table_rte_flow_action_passthru:
1822
1823 .. table:: PASSTHRU
1824
1825    +---------------+
1826    | Field         |
1827    +===============+
1828    | no properties |
1829    +---------------+
1830
1831 Example to copy a packet to a queue and continue processing by subsequent
1832 flow rules:
1833
1834 .. _table_rte_flow_action_passthru_example:
1835
1836 .. table:: Copy to queue 8
1837
1838    +-------+--------+-----------+-------+
1839    | Index | Action | Field     | Value |
1840    +=======+========+===========+=======+
1841    | 0     | PASSTHRU                   |
1842    +-------+--------+-----------+-------+
1843    | 1     | QUEUE  | ``queue`` | 8     |
1844    +-------+--------+-----------+-------+
1845    | 2     | END                        |
1846    +-------+----------------------------+
1847
1848 Action: ``JUMP``
1849 ^^^^^^^^^^^^^^^^
1850
1851 Redirects packets to a group on the current device.
1852
1853 In a hierarchy of groups, which can be used to represent physical or logical
1854 flow group/tables on the device, this action redirects the matched flow to
1855 the specified group on that device.
1856
1857 If a matched flow is redirected to a table which doesn't contain a matching
1858 rule for that flow then the behavior is undefined and the resulting behavior
1859 is up to the specific device. Best practice when using groups would be define
1860 a default flow rule for each group which a defines the default actions in that
1861 group so a consistent behavior is defined.
1862
1863 Defining an action for matched flow in a group to jump to a group which is
1864 higher in the group hierarchy may not be supported by physical devices,
1865 depending on how groups are mapped to the physical devices. In the
1866 definitions of jump actions, applications should be aware that it may be
1867 possible to define flow rules which trigger an undefined behavior causing
1868 flows to loop between groups.
1869
1870 .. _table_rte_flow_action_jump:
1871
1872 .. table:: JUMP
1873
1874    +-----------+------------------------------+
1875    | Field     | Value                        |
1876    +===========+==============================+
1877    | ``group`` | Group to redirect packets to |
1878    +-----------+------------------------------+
1879
1880 Action: ``MARK``
1881 ^^^^^^^^^^^^^^^^
1882
1883 Attaches an integer value to packets and sets ``RTE_MBUF_F_RX_FDIR`` and
1884 ``RTE_MBUF_F_RX_FDIR_ID`` mbuf flags.
1885
1886 This value is arbitrary and application-defined. Maximum allowed value
1887 depends on the underlying implementation. It is returned in the
1888 ``hash.fdir.hi`` mbuf field.
1889
1890 .. _table_rte_flow_action_mark:
1891
1892 .. table:: MARK
1893
1894    +--------+--------------------------------------+
1895    | Field  | Value                                |
1896    +========+======================================+
1897    | ``id`` | integer value to return with packets |
1898    +--------+--------------------------------------+
1899
1900 Action: ``FLAG``
1901 ^^^^^^^^^^^^^^^^
1902
1903 Flags packets. Similar to `Action: MARK`_ without a specific value; only
1904 sets the ``RTE_MBUF_F_RX_FDIR`` mbuf flag.
1905
1906 - No configurable properties.
1907
1908 .. _table_rte_flow_action_flag:
1909
1910 .. table:: FLAG
1911
1912    +---------------+
1913    | Field         |
1914    +===============+
1915    | no properties |
1916    +---------------+
1917
1918 Action: ``QUEUE``
1919 ^^^^^^^^^^^^^^^^^
1920
1921 Assigns packets to a given queue index.
1922
1923 .. _table_rte_flow_action_queue:
1924
1925 .. table:: QUEUE
1926
1927    +-----------+--------------------+
1928    | Field     | Value              |
1929    +===========+====================+
1930    | ``index`` | queue index to use |
1931    +-----------+--------------------+
1932
1933 Action: ``DROP``
1934 ^^^^^^^^^^^^^^^^
1935
1936 Drop packets.
1937
1938 - No configurable properties.
1939
1940 .. _table_rte_flow_action_drop:
1941
1942 .. table:: DROP
1943
1944    +---------------+
1945    | Field         |
1946    +===============+
1947    | no properties |
1948    +---------------+
1949
1950 Action: ``COUNT``
1951 ^^^^^^^^^^^^^^^^^
1952
1953 Adds a counter action to a matched flow.
1954
1955 If more than one count action is specified in a single flow rule, then each
1956 action must specify a unique id.
1957
1958 Counters can be retrieved and reset through ``rte_flow_query()``, see
1959 ``struct rte_flow_query_count``.
1960
1961 For ports within the same switch domain then the counter id namespace extends
1962 to all ports within that switch domain.
1963
1964 .. _table_rte_flow_action_count:
1965
1966 .. table:: COUNT
1967
1968    +------------+---------------------------------+
1969    | Field      | Value                           |
1970    +============+=================================+
1971    | ``id``     | counter id                      |
1972    +------------+---------------------------------+
1973
1974 Query structure to retrieve and reset flow rule counters:
1975
1976 .. _table_rte_flow_query_count:
1977
1978 .. table:: COUNT query
1979
1980    +---------------+-----+-----------------------------------+
1981    | Field         | I/O | Value                             |
1982    +===============+=====+===================================+
1983    | ``reset``     | in  | reset counter after query         |
1984    +---------------+-----+-----------------------------------+
1985    | ``hits_set``  | out | ``hits`` field is set             |
1986    +---------------+-----+-----------------------------------+
1987    | ``bytes_set`` | out | ``bytes`` field is set            |
1988    +---------------+-----+-----------------------------------+
1989    | ``hits``      | out | number of hits for this rule      |
1990    +---------------+-----+-----------------------------------+
1991    | ``bytes``     | out | number of bytes through this rule |
1992    +---------------+-----+-----------------------------------+
1993
1994 Action: ``RSS``
1995 ^^^^^^^^^^^^^^^
1996
1997 Similar to QUEUE, except RSS is additionally performed on packets to spread
1998 them among several queues according to the provided parameters.
1999
2000 Unlike global RSS settings used by other DPDK APIs, unsetting the ``types``
2001 field does not disable RSS in a flow rule. Doing so instead requests safe
2002 unspecified "best-effort" settings from the underlying PMD, which depending
2003 on the flow rule, may result in anything ranging from empty (single queue)
2004 to all-inclusive RSS.
2005
2006 If non-applicable for matching packets RSS types are requested,
2007 these RSS types are simply ignored. For example, it happens if:
2008
2009 - Hashing of both TCP and UDP ports is requested
2010   (only one can be present in a packet).
2011
2012 - Requested RSS types contradict to flow rule pattern
2013   (e.g. pattern has UDP item, but RSS types contain TCP).
2014
2015 If requested RSS hash types are not supported by the Ethernet device at all
2016 (not reported in ``dev_info.flow_type_rss_offloads``),
2017 the flow creation will fail.
2018
2019 Note: RSS hash result is stored in the ``hash.rss`` mbuf field which
2020 overlaps ``hash.fdir.lo``. Since `Action: MARK`_ sets the ``hash.fdir.hi``
2021 field only, both can be requested simultaneously.
2022
2023 Also, regarding packet encapsulation ``level``:
2024
2025 - ``0`` requests the default behavior. Depending on the packet type, it can
2026   mean outermost, innermost, anything in between or even no RSS.
2027
2028   It basically stands for the innermost encapsulation level RSS can be
2029   performed on according to PMD and device capabilities.
2030
2031 - ``1`` requests RSS to be performed on the outermost packet encapsulation
2032   level.
2033
2034 - ``2`` and subsequent values request RSS to be performed on the specified
2035    inner packet encapsulation level, from outermost to innermost (lower to
2036    higher values).
2037
2038 Values other than ``0`` are not necessarily supported.
2039
2040 Requesting a specific RSS level on unrecognized traffic results in undefined
2041 behavior. For predictable results, it is recommended to make the flow rule
2042 pattern match packet headers up to the requested encapsulation level so that
2043 only matching traffic goes through.
2044
2045 .. _table_rte_flow_action_rss:
2046
2047 .. table:: RSS
2048
2049    +---------------+-------------------------------------------------+
2050    | Field         | Value                                           |
2051    +===============+=================================================+
2052    | ``func``      | RSS hash function to apply                      |
2053    +---------------+-------------------------------------------------+
2054    | ``level``     | encapsulation level for ``types``               |
2055    +---------------+-------------------------------------------------+
2056    | ``types``     | specific RSS hash types (see ``RTE_ETH_RSS_*``) |
2057    +---------------+-------------------------------------------------+
2058    | ``key_len``   | hash key length in bytes                        |
2059    +---------------+-------------------------------------------------+
2060    | ``queue_num`` | number of entries in ``queue``                  |
2061    +---------------+-------------------------------------------------+
2062    | ``key``       | hash key                                        |
2063    +---------------+-------------------------------------------------+
2064    | ``queue``     | queue indices to use                            |
2065    +---------------+-------------------------------------------------+
2066
2067 Action: ``PF``
2068 ^^^^^^^^^^^^^^
2069
2070 This action is deprecated. Consider:
2071  - `Action: PORT_REPRESENTOR`_
2072  - `Action: REPRESENTED_PORT`_
2073
2074 Directs matching traffic to the physical function (PF) of the current
2075 device.
2076
2077 See `Item: PF`_.
2078
2079 - No configurable properties.
2080
2081 .. _table_rte_flow_action_pf:
2082
2083 .. table:: PF
2084
2085    +---------------+
2086    | Field         |
2087    +===============+
2088    | no properties |
2089    +---------------+
2090
2091 Action: ``VF``
2092 ^^^^^^^^^^^^^^
2093
2094 This action is deprecated. Consider:
2095  - `Action: PORT_REPRESENTOR`_
2096  - `Action: REPRESENTED_PORT`_
2097
2098 Directs matching traffic to a given virtual function of the current device.
2099
2100 Packets matched by a VF pattern item can be redirected to their original VF
2101 ID instead of the specified one. This parameter may not be available and is
2102 not guaranteed to work properly if the VF part is matched by a prior flow
2103 rule or if packets are not addressed to a VF in the first place.
2104
2105 See `Item: VF`_.
2106
2107 .. _table_rte_flow_action_vf:
2108
2109 .. table:: VF
2110
2111    +--------------+--------------------------------+
2112    | Field        | Value                          |
2113    +==============+================================+
2114    | ``original`` | use original VF ID if possible |
2115    +--------------+--------------------------------+
2116    | ``id``       | VF ID                          |
2117    +--------------+--------------------------------+
2118
2119 Action: ``PHY_PORT``
2120 ^^^^^^^^^^^^^^^^^^^^
2121
2122 This action is deprecated. Consider:
2123  - `Action: PORT_REPRESENTOR`_
2124  - `Action: REPRESENTED_PORT`_
2125
2126 Directs matching traffic to a given physical port index of the underlying
2127 device.
2128
2129 See `Item: PHY_PORT`_.
2130
2131 .. _table_rte_flow_action_phy_port:
2132
2133 .. table:: PHY_PORT
2134
2135    +--------------+-------------------------------------+
2136    | Field        | Value                               |
2137    +==============+=====================================+
2138    | ``original`` | use original port index if possible |
2139    +--------------+-------------------------------------+
2140    | ``index``    | physical port index                 |
2141    +--------------+-------------------------------------+
2142
2143 Action: ``PORT_ID``
2144 ^^^^^^^^^^^^^^^^^^^
2145 This action is deprecated. Consider:
2146  - `Action: PORT_REPRESENTOR`_
2147  - `Action: REPRESENTED_PORT`_
2148
2149 Directs matching traffic to a given DPDK port ID.
2150
2151 See `Item: PORT_ID`_.
2152
2153 .. _table_rte_flow_action_port_id:
2154
2155 .. table:: PORT_ID
2156
2157    +--------------+---------------------------------------+
2158    | Field        | Value                                 |
2159    +==============+=======================================+
2160    | ``original`` | use original DPDK port ID if possible |
2161    +--------------+---------------------------------------+
2162    | ``id``       | DPDK port ID                          |
2163    +--------------+---------------------------------------+
2164
2165 Action: ``METER``
2166 ^^^^^^^^^^^^^^^^^
2167
2168 Applies a stage of metering and policing.
2169
2170 The metering and policing (MTR) object has to be first created using the
2171 rte_mtr_create() API function. The ID of the MTR object is specified as
2172 action parameter. More than one flow can use the same MTR object through
2173 the meter action. The MTR object can be further updated or queried using
2174 the rte_mtr* API.
2175
2176 .. _table_rte_flow_action_meter:
2177
2178 .. table:: METER
2179
2180    +--------------+---------------+
2181    | Field        | Value         |
2182    +==============+===============+
2183    | ``mtr_id``   | MTR object ID |
2184    +--------------+---------------+
2185
2186 Action: ``SECURITY``
2187 ^^^^^^^^^^^^^^^^^^^^
2188
2189 Perform the security action on flows matched by the pattern items
2190 according to the configuration of the security session.
2191
2192 This action modifies the payload of matched flows. For INLINE_CRYPTO, the
2193 security protocol headers and IV are fully provided by the application as
2194 specified in the flow pattern. The payload of matching packets is
2195 encrypted on egress, and decrypted and authenticated on ingress.
2196 For INLINE_PROTOCOL, the security protocol is fully offloaded to HW,
2197 providing full encapsulation and decapsulation of packets in security
2198 protocols. The flow pattern specifies both the outer security header fields
2199 and the inner packet fields. The security session specified in the action
2200 must match the pattern parameters.
2201
2202 The security session specified in the action must be created on the same
2203 port as the flow action that is being specified.
2204
2205 The ingress/egress flow attribute should match that specified in the
2206 security session if the security session supports the definition of the
2207 direction.
2208
2209 Multiple flows can be configured to use the same security session.
2210
2211 .. _table_rte_flow_action_security:
2212
2213 .. table:: SECURITY
2214
2215    +----------------------+--------------------------------------+
2216    | Field                | Value                                |
2217    +======================+======================================+
2218    | ``security_session`` | security session to apply            |
2219    +----------------------+--------------------------------------+
2220
2221 The following is an example of configuring IPsec inline using the
2222 INLINE_CRYPTO security session:
2223
2224 The encryption algorithm, keys and salt are part of the opaque
2225 ``rte_security_session``. The SA is identified according to the IP and ESP
2226 fields in the pattern items.
2227
2228 .. _table_rte_flow_item_esp_inline_example:
2229
2230 .. table:: IPsec inline crypto flow pattern items.
2231
2232    +-------+----------+
2233    | Index | Item     |
2234    +=======+==========+
2235    | 0     | Ethernet |
2236    +-------+----------+
2237    | 1     | IPv4     |
2238    +-------+----------+
2239    | 2     | ESP      |
2240    +-------+----------+
2241    | 3     | END      |
2242    +-------+----------+
2243
2244 .. _table_rte_flow_action_esp_inline_example:
2245
2246 .. table:: IPsec inline flow actions.
2247
2248    +-------+----------+
2249    | Index | Action   |
2250    +=======+==========+
2251    | 0     | SECURITY |
2252    +-------+----------+
2253    | 1     | END      |
2254    +-------+----------+
2255
2256 Action: ``OF_SET_MPLS_TTL``
2257 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
2258 This action is deprecated. Consider `Action: MODIFY_FIELD`_.
2259
2260 Implements ``OFPAT_SET_MPLS_TTL`` ("MPLS TTL") as defined by the `OpenFlow
2261 Switch Specification`_.
2262
2263 .. _table_rte_flow_action_of_set_mpls_ttl:
2264
2265 .. table:: OF_SET_MPLS_TTL
2266
2267    +--------------+----------+
2268    | Field        | Value    |
2269    +==============+==========+
2270    | ``mpls_ttl`` | MPLS TTL |
2271    +--------------+----------+
2272
2273 Action: ``OF_DEC_MPLS_TTL``
2274 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
2275 This action is deprecated. Consider `Action: MODIFY_FIELD`_.
2276
2277 Implements ``OFPAT_DEC_MPLS_TTL`` ("decrement MPLS TTL") as defined by the
2278 `OpenFlow Switch Specification`_.
2279
2280 .. _table_rte_flow_action_of_dec_mpls_ttl:
2281
2282 .. table:: OF_DEC_MPLS_TTL
2283
2284    +---------------+
2285    | Field         |
2286    +===============+
2287    | no properties |
2288    +---------------+
2289
2290 Action: ``OF_SET_NW_TTL``
2291 ^^^^^^^^^^^^^^^^^^^^^^^^^
2292 This action is deprecated. Consider `Action: MODIFY_FIELD`_.
2293
2294 Implements ``OFPAT_SET_NW_TTL`` ("IP TTL") as defined by the `OpenFlow
2295 Switch Specification`_.
2296
2297 .. _table_rte_flow_action_of_set_nw_ttl:
2298
2299 .. table:: OF_SET_NW_TTL
2300
2301    +------------+--------+
2302    | Field      | Value  |
2303    +============+========+
2304    | ``nw_ttl`` | IP TTL |
2305    +------------+--------+
2306
2307 Action: ``OF_DEC_NW_TTL``
2308 ^^^^^^^^^^^^^^^^^^^^^^^^^
2309 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2310
2311 Implements ``OFPAT_DEC_NW_TTL`` ("decrement IP TTL") as defined by the
2312 `OpenFlow Switch Specification`_.
2313
2314 .. _table_rte_flow_action_of_dec_nw_ttl:
2315
2316 .. table:: OF_DEC_NW_TTL
2317
2318    +---------------+
2319    | Field         |
2320    +===============+
2321    | no properties |
2322    +---------------+
2323
2324 Action: ``OF_COPY_TTL_OUT``
2325 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
2326 This action is deprecated. Consider `Action: MODIFY_FIELD`_.
2327
2328 Implements ``OFPAT_COPY_TTL_OUT`` ("copy TTL "outwards" -- from
2329 next-to-outermost to outermost") as defined by the `OpenFlow Switch
2330 Specification`_.
2331
2332 .. _table_rte_flow_action_of_copy_ttl_out:
2333
2334 .. table:: OF_COPY_TTL_OUT
2335
2336    +---------------+
2337    | Field         |
2338    +===============+
2339    | no properties |
2340    +---------------+
2341
2342 Action: ``OF_COPY_TTL_IN``
2343 ^^^^^^^^^^^^^^^^^^^^^^^^^^
2344 This action is deprecated. Consider `Action: MODIFY_FIELD`_.
2345
2346 Implements ``OFPAT_COPY_TTL_IN`` ("copy TTL "inwards" -- from outermost to
2347 next-to-outermost") as defined by the `OpenFlow Switch Specification`_.
2348
2349 .. _table_rte_flow_action_of_copy_ttl_in:
2350
2351 .. table:: OF_COPY_TTL_IN
2352
2353    +---------------+
2354    | Field         |
2355    +===============+
2356    | no properties |
2357    +---------------+
2358
2359 Action: ``OF_POP_VLAN``
2360 ^^^^^^^^^^^^^^^^^^^^^^^
2361
2362 Implements ``OFPAT_POP_VLAN`` ("pop the outer VLAN tag") as defined
2363 by the `OpenFlow Switch Specification`_.
2364
2365 .. _table_rte_flow_action_of_pop_vlan:
2366
2367 .. table:: OF_POP_VLAN
2368
2369    +---------------+
2370    | Field         |
2371    +===============+
2372    | no properties |
2373    +---------------+
2374
2375 Action: ``OF_PUSH_VLAN``
2376 ^^^^^^^^^^^^^^^^^^^^^^^^
2377
2378 Implements ``OFPAT_PUSH_VLAN`` ("push a new VLAN tag") as defined by the
2379 `OpenFlow Switch Specification`_.
2380
2381 .. _table_rte_flow_action_of_push_vlan:
2382
2383 .. table:: OF_PUSH_VLAN
2384
2385    +---------------+-----------+
2386    | Field         | Value     |
2387    +===============+===========+
2388    | ``ethertype`` | EtherType |
2389    +---------------+-----------+
2390
2391 Action: ``OF_SET_VLAN_VID``
2392 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
2393
2394 Implements ``OFPAT_SET_VLAN_VID`` ("set the 802.1q VLAN id") as defined by
2395 the `OpenFlow Switch Specification`_.
2396
2397 .. _table_rte_flow_action_of_set_vlan_vid:
2398
2399 .. table:: OF_SET_VLAN_VID
2400
2401    +--------------+---------+
2402    | Field        | Value   |
2403    +==============+=========+
2404    | ``vlan_vid`` | VLAN id |
2405    +--------------+---------+
2406
2407 Action: ``OF_SET_VLAN_PCP``
2408 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
2409
2410 Implements ``OFPAT_SET_LAN_PCP`` ("set the 802.1q priority") as defined by
2411 the `OpenFlow Switch Specification`_.
2412
2413 .. _table_rte_flow_action_of_set_vlan_pcp:
2414
2415 .. table:: OF_SET_VLAN_PCP
2416
2417    +--------------+---------------+
2418    | Field        | Value         |
2419    +==============+===============+
2420    | ``vlan_pcp`` | VLAN priority |
2421    +--------------+---------------+
2422
2423 Action: ``OF_POP_MPLS``
2424 ^^^^^^^^^^^^^^^^^^^^^^^
2425
2426 Implements ``OFPAT_POP_MPLS`` ("pop the outer MPLS tag") as defined by the
2427 `OpenFlow Switch Specification`_.
2428
2429 .. _table_rte_flow_action_of_pop_mpls:
2430
2431 .. table:: OF_POP_MPLS
2432
2433    +---------------+-----------+
2434    | Field         | Value     |
2435    +===============+===========+
2436    | ``ethertype`` | EtherType |
2437    +---------------+-----------+
2438
2439 Action: ``OF_PUSH_MPLS``
2440 ^^^^^^^^^^^^^^^^^^^^^^^^
2441
2442 Implements ``OFPAT_PUSH_MPLS`` ("push a new MPLS tag") as defined by the
2443 `OpenFlow Switch Specification`_.
2444
2445 .. _table_rte_flow_action_of_push_mpls:
2446
2447 .. table:: OF_PUSH_MPLS
2448
2449    +---------------+-----------+
2450    | Field         | Value     |
2451    +===============+===========+
2452    | ``ethertype`` | EtherType |
2453    +---------------+-----------+
2454
2455 Action: ``VXLAN_ENCAP``
2456 ^^^^^^^^^^^^^^^^^^^^^^^
2457
2458 Performs a VXLAN encapsulation action by encapsulating the matched flow in the
2459 VXLAN tunnel as defined in the``rte_flow_action_vxlan_encap`` flow items
2460 definition.
2461
2462 This action modifies the payload of matched flows. The flow definition specified
2463 in the ``rte_flow_action_tunnel_encap`` action structure must define a valid
2464 VLXAN network overlay which conforms with RFC 7348 (Virtual eXtensible Local
2465 Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks
2466 over Layer 3 Networks). The pattern must be terminated with the
2467 RTE_FLOW_ITEM_TYPE_END item type.
2468
2469 .. _table_rte_flow_action_vxlan_encap:
2470
2471 .. table:: VXLAN_ENCAP
2472
2473    +----------------+-------------------------------------+
2474    | Field          | Value                               |
2475    +================+=====================================+
2476    | ``definition`` | Tunnel end-point overlay definition |
2477    +----------------+-------------------------------------+
2478
2479 .. _table_rte_flow_action_vxlan_encap_example:
2480
2481 .. table:: IPv4 VxLAN flow pattern example.
2482
2483    +-------+----------+
2484    | Index | Item     |
2485    +=======+==========+
2486    | 0     | Ethernet |
2487    +-------+----------+
2488    | 1     | IPv4     |
2489    +-------+----------+
2490    | 2     | UDP      |
2491    +-------+----------+
2492    | 3     | VXLAN    |
2493    +-------+----------+
2494    | 4     | END      |
2495    +-------+----------+
2496
2497 Action: ``VXLAN_DECAP``
2498 ^^^^^^^^^^^^^^^^^^^^^^^
2499
2500 Performs a decapsulation action by stripping all headers of the VXLAN tunnel
2501 network overlay from the matched flow.
2502
2503 The flow items pattern defined for the flow rule with which a ``VXLAN_DECAP``
2504 action is specified, must define a valid VXLAN tunnel as per RFC7348. If the
2505 flow pattern does not specify a valid VXLAN tunnel then a
2506 RTE_FLOW_ERROR_TYPE_ACTION error should be returned.
2507
2508 This action modifies the payload of matched flows.
2509
2510 Action: ``NVGRE_ENCAP``
2511 ^^^^^^^^^^^^^^^^^^^^^^^
2512
2513 Performs a NVGRE encapsulation action by encapsulating the matched flow in the
2514 NVGRE tunnel as defined in the``rte_flow_action_tunnel_encap`` flow item
2515 definition.
2516
2517 This action modifies the payload of matched flows. The flow definition specified
2518 in the ``rte_flow_action_tunnel_encap`` action structure must defined a valid
2519 NVGRE network overlay which conforms with RFC 7637 (NVGRE: Network
2520 Virtualization Using Generic Routing Encapsulation). The pattern must be
2521 terminated with the RTE_FLOW_ITEM_TYPE_END item type.
2522
2523 .. _table_rte_flow_action_nvgre_encap:
2524
2525 .. table:: NVGRE_ENCAP
2526
2527    +----------------+-------------------------------------+
2528    | Field          | Value                               |
2529    +================+=====================================+
2530    | ``definition`` | NVGRE end-point overlay definition  |
2531    +----------------+-------------------------------------+
2532
2533 .. _table_rte_flow_action_nvgre_encap_example:
2534
2535 .. table:: IPv4 NVGRE flow pattern example.
2536
2537    +-------+----------+
2538    | Index | Item     |
2539    +=======+==========+
2540    | 0     | Ethernet |
2541    +-------+----------+
2542    | 1     | IPv4     |
2543    +-------+----------+
2544    | 2     | NVGRE    |
2545    +-------+----------+
2546    | 3     | END      |
2547    +-------+----------+
2548
2549 Action: ``NVGRE_DECAP``
2550 ^^^^^^^^^^^^^^^^^^^^^^^
2551
2552 Performs a decapsulation action by stripping all headers of the NVGRE tunnel
2553 network overlay from the matched flow.
2554
2555 The flow items pattern defined for the flow rule with which a ``NVGRE_DECAP``
2556 action is specified, must define a valid NVGRE tunnel as per RFC7637. If the
2557 flow pattern does not specify a valid NVGRE tunnel then a
2558 RTE_FLOW_ERROR_TYPE_ACTION error should be returned.
2559
2560 This action modifies the payload of matched flows.
2561
2562 Action: ``RAW_ENCAP``
2563 ^^^^^^^^^^^^^^^^^^^^^
2564
2565 Adds outer header whose template is provided in its data buffer,
2566 as defined in the ``rte_flow_action_raw_encap`` definition.
2567
2568 This action modifies the payload of matched flows. The data supplied must
2569 be a valid header, either holding layer 2 data in case of adding layer 2 after
2570 decap layer 3 tunnel (for example MPLSoGRE) or complete tunnel definition
2571 starting from layer 2 and moving to the tunnel item itself. When applied to
2572 the original packet the resulting packet must be a valid packet.
2573
2574 .. _table_rte_flow_action_raw_encap:
2575
2576 .. table:: RAW_ENCAP
2577
2578    +----------------+----------------------------------------+
2579    | Field          | Value                                  |
2580    +================+========================================+
2581    | ``data``       | Encapsulation data                     |
2582    +----------------+----------------------------------------+
2583    | ``preserve``   | Bit-mask of data to preserve on output |
2584    +----------------+----------------------------------------+
2585    | ``size``       | Size of data and preserve              |
2586    +----------------+----------------------------------------+
2587
2588 Action: ``RAW_DECAP``
2589 ^^^^^^^^^^^^^^^^^^^^^^^
2590
2591 Remove outer header whose template is provided in its data buffer,
2592 as defined in the ``rte_flow_action_raw_decap``
2593
2594 This action modifies the payload of matched flows. The data supplied must
2595 be a valid header, either holding layer 2 data in case of removing layer 2
2596 before encapsulation of layer 3 tunnel (for example MPLSoGRE) or complete
2597 tunnel definition starting from layer 2 and moving to the tunnel item itself.
2598 When applied to the original packet the resulting packet must be a
2599 valid packet.
2600
2601 .. _table_rte_flow_action_raw_decap:
2602
2603 .. table:: RAW_DECAP
2604
2605    +----------------+----------------------------------------+
2606    | Field          | Value                                  |
2607    +================+========================================+
2608    | ``data``       | Decapsulation data                     |
2609    +----------------+----------------------------------------+
2610    | ``size``       | Size of data                           |
2611    +----------------+----------------------------------------+
2612
2613 Action: ``SET_IPV4_SRC``
2614 ^^^^^^^^^^^^^^^^^^^^^^^^
2615 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2616
2617 Set a new IPv4 source address in the outermost IPv4 header.
2618
2619 It must be used with a valid RTE_FLOW_ITEM_TYPE_IPV4 flow pattern item.
2620 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2621
2622 .. _table_rte_flow_action_set_ipv4_src:
2623
2624 .. table:: SET_IPV4_SRC
2625
2626    +-----------------------------------------+
2627    | Field         | Value                   |
2628    +===============+=========================+
2629    | ``ipv4_addr`` | new IPv4 source address |
2630    +---------------+-------------------------+
2631
2632 Action: ``SET_IPV4_DST``
2633 ^^^^^^^^^^^^^^^^^^^^^^^^
2634 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2635
2636 Set a new IPv4 destination address in the outermost IPv4 header.
2637
2638 It must be used with a valid RTE_FLOW_ITEM_TYPE_IPV4 flow pattern item.
2639 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2640
2641 .. _table_rte_flow_action_set_ipv4_dst:
2642
2643 .. table:: SET_IPV4_DST
2644
2645    +---------------+------------------------------+
2646    | Field         | Value                        |
2647    +===============+==============================+
2648    | ``ipv4_addr`` | new IPv4 destination address |
2649    +---------------+------------------------------+
2650
2651 Action: ``SET_IPV6_SRC``
2652 ^^^^^^^^^^^^^^^^^^^^^^^^
2653 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2654
2655 Set a new IPv6 source address in the outermost IPv6 header.
2656
2657 It must be used with a valid RTE_FLOW_ITEM_TYPE_IPV6 flow pattern item.
2658 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2659
2660 .. _table_rte_flow_action_set_ipv6_src:
2661
2662 .. table:: SET_IPV6_SRC
2663
2664    +---------------+-------------------------+
2665    | Field         | Value                   |
2666    +===============+=========================+
2667    | ``ipv6_addr`` | new IPv6 source address |
2668    +---------------+-------------------------+
2669
2670 Action: ``SET_IPV6_DST``
2671 ^^^^^^^^^^^^^^^^^^^^^^^^
2672 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2673
2674 Set a new IPv6 destination address in the outermost IPv6 header.
2675
2676 It must be used with a valid RTE_FLOW_ITEM_TYPE_IPV6 flow pattern item.
2677 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2678
2679 .. _table_rte_flow_action_set_ipv6_dst:
2680
2681 .. table:: SET_IPV6_DST
2682
2683    +---------------+------------------------------+
2684    | Field         | Value                        |
2685    +===============+==============================+
2686    | ``ipv6_addr`` | new IPv6 destination address |
2687    +---------------+------------------------------+
2688
2689 Action: ``SET_TP_SRC``
2690 ^^^^^^^^^^^^^^^^^^^^^^^^^
2691 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2692
2693 Set a new source port number in the outermost TCP/UDP header.
2694
2695 It must be used with a valid RTE_FLOW_ITEM_TYPE_TCP or RTE_FLOW_ITEM_TYPE_UDP
2696 flow pattern item. Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2697
2698 .. _table_rte_flow_action_set_tp_src:
2699
2700 .. table:: SET_TP_SRC
2701
2702    +----------+-------------------------+
2703    | Field    | Value                   |
2704    +==========+=========================+
2705    | ``port`` | new TCP/UDP source port |
2706    +---------------+--------------------+
2707
2708 Action: ``SET_TP_DST``
2709 ^^^^^^^^^^^^^^^^^^^^^^^^^
2710 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2711
2712 Set a new destination port number in the outermost TCP/UDP header.
2713
2714 It must be used with a valid RTE_FLOW_ITEM_TYPE_TCP or RTE_FLOW_ITEM_TYPE_UDP
2715 flow pattern item. Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2716
2717 .. _table_rte_flow_action_set_tp_dst:
2718
2719 .. table:: SET_TP_DST
2720
2721    +----------+------------------------------+
2722    | Field    | Value                        |
2723    +==========+==============================+
2724    | ``port`` | new TCP/UDP destination port |
2725    +---------------+-------------------------+
2726
2727 Action: ``MAC_SWAP``
2728 ^^^^^^^^^^^^^^^^^^^^^^^^^
2729
2730 Swap the source and destination MAC addresses in the outermost Ethernet
2731 header.
2732
2733 It must be used with a valid RTE_FLOW_ITEM_TYPE_ETH flow pattern item.
2734 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2735
2736 .. _table_rte_flow_action_mac_swap:
2737
2738 .. table:: MAC_SWAP
2739
2740    +---------------+
2741    | Field         |
2742    +===============+
2743    | no properties |
2744    +---------------+
2745
2746 Action: ``DEC_TTL``
2747 ^^^^^^^^^^^^^^^^^^^
2748 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2749
2750 Decrease TTL value.
2751
2752 If there is no valid RTE_FLOW_ITEM_TYPE_IPV4 or RTE_FLOW_ITEM_TYPE_IPV6
2753 in pattern, Some PMDs will reject rule because behavior will be undefined.
2754
2755 .. _table_rte_flow_action_dec_ttl:
2756
2757 .. table:: DEC_TTL
2758
2759    +---------------+
2760    | Field         |
2761    +===============+
2762    | no properties |
2763    +---------------+
2764
2765 Action: ``SET_TTL``
2766 ^^^^^^^^^^^^^^^^^^^
2767 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2768
2769 Assigns a new TTL value.
2770
2771 If there is no valid RTE_FLOW_ITEM_TYPE_IPV4 or RTE_FLOW_ITEM_TYPE_IPV6
2772 in pattern, Some PMDs will reject rule because behavior will be undefined.
2773
2774 .. _table_rte_flow_action_set_ttl:
2775
2776 .. table:: SET_TTL
2777
2778    +---------------+--------------------+
2779    | Field         | Value              |
2780    +===============+====================+
2781    | ``ttl_value`` | new TTL value      |
2782    +---------------+--------------------+
2783
2784 Action: ``SET_MAC_SRC``
2785 ^^^^^^^^^^^^^^^^^^^^^^^
2786 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2787
2788 Set source MAC address.
2789
2790 It must be used with a valid RTE_FLOW_ITEM_TYPE_ETH flow pattern item.
2791 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2792
2793 .. _table_rte_flow_action_set_mac_src:
2794
2795 .. table:: SET_MAC_SRC
2796
2797    +--------------+---------------+
2798    | Field        | Value         |
2799    +==============+===============+
2800    | ``mac_addr`` | MAC address   |
2801    +--------------+---------------+
2802
2803 Action: ``SET_MAC_DST``
2804 ^^^^^^^^^^^^^^^^^^^^^^^
2805 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2806
2807 Set destination MAC address.
2808
2809 It must be used with a valid RTE_FLOW_ITEM_TYPE_ETH flow pattern item.
2810 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2811
2812 .. _table_rte_flow_action_set_mac_dst:
2813
2814 .. table:: SET_MAC_DST
2815
2816    +--------------+---------------+
2817    | Field        | Value         |
2818    +==============+===============+
2819    | ``mac_addr`` | MAC address   |
2820    +--------------+---------------+
2821
2822 Action: ``INC_TCP_SEQ``
2823 ^^^^^^^^^^^^^^^^^^^^^^^
2824 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2825
2826 Increase sequence number in the outermost TCP header.
2827 Value to increase TCP sequence number by is a big-endian 32 bit integer.
2828
2829 Using this action on non-matching traffic will result in undefined behavior.
2830
2831 Action: ``DEC_TCP_SEQ``
2832 ^^^^^^^^^^^^^^^^^^^^^^^
2833 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2834
2835 Decrease sequence number in the outermost TCP header.
2836 Value to decrease TCP sequence number by is a big-endian 32 bit integer.
2837
2838 Using this action on non-matching traffic will result in undefined behavior.
2839
2840 Action: ``INC_TCP_ACK``
2841 ^^^^^^^^^^^^^^^^^^^^^^^
2842 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2843
2844 Increase acknowledgment number in the outermost TCP header.
2845 Value to increase TCP acknowledgment number by is a big-endian 32 bit integer.
2846
2847 Using this action on non-matching traffic will result in undefined behavior.
2848
2849 Action: ``DEC_TCP_ACK``
2850 ^^^^^^^^^^^^^^^^^^^^^^^
2851 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2852
2853 Decrease acknowledgment number in the outermost TCP header.
2854 Value to decrease TCP acknowledgment number by is a big-endian 32 bit integer.
2855
2856 Using this action on non-matching traffic will result in undefined behavior.
2857
2858 Action: ``SET_TAG``
2859 ^^^^^^^^^^^^^^^^^^^
2860 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2861
2862 Set Tag.
2863
2864 Tag is a transient data used during flow matching. This is not delivered to
2865 application. Multiple tags are supported by specifying index.
2866
2867 .. _table_rte_flow_action_set_tag:
2868
2869 .. table:: SET_TAG
2870
2871    +-----------+----------------------------+
2872    | Field     | Value                      |
2873    +===========+============================+
2874    | ``data``  | 32 bit tag value           |
2875    +-----------+----------------------------+
2876    | ``mask``  | bit-mask applies to "data" |
2877    +-----------+----------------------------+
2878    | ``index`` | index of tag to set        |
2879    +-----------+----------------------------+
2880
2881 Action: ``SET_META``
2882 ^^^^^^^^^^^^^^^^^^^^^^^
2883 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2884
2885 Set metadata. Item ``META`` matches metadata.
2886
2887 Metadata set by mbuf metadata field with RTE_MBUF_DYNFLAG_TX_METADATA flag on egress
2888 will be overridden by this action. On ingress, the metadata will be carried by
2889 ``metadata`` dynamic field of ``rte_mbuf`` which can be accessed by
2890 ``RTE_FLOW_DYNF_METADATA()``. RTE_MBUF_DYNFLAG_RX_METADATA flag will be set along
2891 with the data.
2892
2893 The mbuf dynamic field must be registered by calling
2894 ``rte_flow_dynf_metadata_register()`` prior to use ``SET_META`` action.
2895
2896 Altering partial bits is supported with ``mask``. For bits which have never been
2897 set, unpredictable value will be seen depending on driver implementation. For
2898 loopback/hairpin packet, metadata set on Rx/Tx may or may not be propagated to
2899 the other path depending on HW capability.
2900
2901 In hairpin case with Tx explicit flow mode, metadata could (not mandatory) be
2902 used to connect the Rx and Tx flows if it can be propagated from Rx to Tx path.
2903
2904 .. _table_rte_flow_action_set_meta:
2905
2906 .. table:: SET_META
2907
2908    +----------+----------------------------+
2909    | Field    | Value                      |
2910    +==========+============================+
2911    | ``data`` | 32 bit metadata value      |
2912    +----------+----------------------------+
2913    | ``mask`` | bit-mask applies to "data" |
2914    +----------+----------------------------+
2915
2916 Action: ``SET_IPV4_DSCP``
2917 ^^^^^^^^^^^^^^^^^^^^^^^^^
2918 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2919
2920 Set IPv4 DSCP.
2921
2922 Modify DSCP in IPv4 header.
2923
2924 It must be used with RTE_FLOW_ITEM_TYPE_IPV4 in pattern.
2925 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2926
2927 .. _table_rte_flow_action_set_ipv4_dscp:
2928
2929 .. table:: SET_IPV4_DSCP
2930
2931    +-----------+---------------------------------+
2932    | Field     | Value                           |
2933    +===========+=================================+
2934    | ``dscp``  | DSCP in low 6 bits, rest ignore |
2935    +-----------+---------------------------------+
2936
2937 Action: ``SET_IPV6_DSCP``
2938 ^^^^^^^^^^^^^^^^^^^^^^^^^
2939 This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
2940
2941 Set IPv6 DSCP.
2942
2943 Modify DSCP in IPv6 header.
2944
2945 It must be used with RTE_FLOW_ITEM_TYPE_IPV6 in pattern.
2946 Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned.
2947
2948 .. _table_rte_flow_action_set_ipv6_dscp:
2949
2950 .. table:: SET_IPV6_DSCP
2951
2952    +-----------+---------------------------------+
2953    | Field     | Value                           |
2954    +===========+=================================+
2955    | ``dscp``  | DSCP in low 6 bits, rest ignore |
2956    +-----------+---------------------------------+
2957
2958 Action: ``AGE``
2959 ^^^^^^^^^^^^^^^
2960
2961 Set ageing timeout configuration to a flow.
2962
2963 Event RTE_ETH_EVENT_FLOW_AGED will be reported if
2964 timeout passed without any matching on the flow.
2965
2966 .. _table_rte_flow_action_age:
2967
2968 .. table:: AGE
2969
2970    +--------------+---------------------------------+
2971    | Field        | Value                           |
2972    +==============+=================================+
2973    | ``timeout``  | 24 bits timeout value           |
2974    +--------------+---------------------------------+
2975    | ``reserved`` | 8 bits reserved, must be zero   |
2976    +--------------+---------------------------------+
2977    | ``context``  | user input flow context         |
2978    +--------------+---------------------------------+
2979
2980 Query structure to retrieve ageing status information of a
2981 shared AGE action, or a flow rule using the AGE action:
2982
2983 .. _table_rte_flow_query_age:
2984
2985 .. table:: AGE query
2986
2987    +------------------------------+-----+----------------------------------------+
2988    | Field                        | I/O | Value                                  |
2989    +==============================+=====+========================================+
2990    | ``aged``                     | out | Aging timeout expired                  |
2991    +------------------------------+-----+----------------------------------------+
2992    | ``sec_since_last_hit_valid`` | out | ``sec_since_last_hit`` value is valid  |
2993    +------------------------------+-----+----------------------------------------+
2994    | ``sec_since_last_hit``       | out | Seconds since last traffic hit         |
2995    +------------------------------+-----+----------------------------------------+
2996
2997 Action: ``SAMPLE``
2998 ^^^^^^^^^^^^^^^^^^
2999
3000 Adds a sample action to a matched flow.
3001
3002 The matching packets will be duplicated with the specified ``ratio`` and
3003 applied with own set of actions with a fate action, the packets sampled
3004 equals is '1/ratio'. All the packets continue to the target destination.
3005
3006 When the ``ratio`` is set to 1 then the packets will be 100% mirrored.
3007 ``actions`` represent the different set of actions for the sampled or mirrored
3008 packets, and must have a fate action.
3009
3010 .. _table_rte_flow_action_sample:
3011
3012 .. table:: SAMPLE
3013
3014    +--------------+---------------------------------+
3015    | Field        | Value                           |
3016    +==============+=================================+
3017    | ``ratio``    | 32 bits sample ratio value      |
3018    +--------------+---------------------------------+
3019    | ``actions``  | sub-action list for sampling    |
3020    +--------------+---------------------------------+
3021
3022 Action: ``INDIRECT``
3023 ^^^^^^^^^^^^^^^^^^^^
3024
3025 Flow utilize indirect action by handle as returned from
3026 ``rte_flow_action_handle_create()``.
3027
3028 The behaviour of the indirect action defined by ``action`` argument of type
3029 ``struct rte_flow_action`` passed to ``rte_flow_action_handle_create()``.
3030
3031 The indirect action can be used by a single flow or shared among multiple flows.
3032 The indirect action can be in-place updated by ``rte_flow_action_handle_update()``
3033 without destroying flow and creating flow again. The fields that could be
3034 updated depend on the type of the ``action`` and different for every type.
3035
3036 The indirect action specified data (e.g. counter) can be queried by
3037 ``rte_flow_action_handle_query()``.
3038
3039 .. warning::
3040
3041    The following description of indirect action persistence
3042    is an experimental behavior that may change without a prior notice.
3043
3044 If ``RTE_ETH_DEV_CAPA_FLOW_SHARED_OBJECT_KEEP`` is not advertised,
3045 indirect actions cannot be created until the device is started for the first time
3046 and cannot be kept when the device is stopped.
3047 However, PMD also does not flush them automatically on stop,
3048 so the application must call ``rte_flow_action_handle_destroy()``
3049 before stopping the device to ensure no indirect actions remain.
3050
3051 If ``RTE_ETH_DEV_CAPA_FLOW_SHARED_OBJECT_KEEP`` is advertised,
3052 this means that the PMD can keep at least some indirect actions
3053 across device stop and start.
3054 However, ``rte_eth_dev_configure()`` may fail if any indirect actions remain,
3055 so the application must destroy them before attempting a reconfiguration.
3056 Keeping may be only supported for certain kinds of indirect actions.
3057 A kind is a combination of an action type and a value of its transfer bit.
3058 For example: an indirect counter with the transfer bit reset.
3059 To test if a particular kind of indirect actions is kept,
3060 the application must try to create a valid indirect action of that kind
3061 when the device is not started (either before the first start of after a stop).
3062 If it fails with an error of type ``RTE_FLOW_ERROR_TYPE_STATE``,
3063 application must destroy all indirect actions of this kind
3064 before stopping the device.
3065 If it succeeds, all indirect actions of the same kind are kept
3066 when the device is stopped.
3067 Indirect actions of a kept kind that are created when the device is stopped,
3068 including the ones created for the test, will be kept after the device start.
3069
3070 .. _table_rte_flow_action_handle:
3071
3072 .. table:: INDIRECT
3073
3074    +---------------+
3075    | Field         |
3076    +===============+
3077    | no properties |
3078    +---------------+
3079
3080 Action: ``MODIFY_FIELD``
3081 ^^^^^^^^^^^^^^^^^^^^^^^^
3082
3083 Modify ``dst`` field according to ``op`` selected (set, addition,
3084 subtraction) with ``width`` bits of data from ``src`` field.
3085
3086 Any arbitrary header field (as well as mark, metadata or tag values)
3087 can be used as both source and destination fields as set by ``field``.
3088 The immediate value ``RTE_FLOW_FIELD_VALUE`` (or a pointer to it
3089 ``RTE_FLOW_FIELD_POINTER``) is allowed as a source only.
3090 ``RTE_FLOW_FIELD_START`` is used to point to the beginning of a packet.
3091 See ``enum rte_flow_field_id`` for the list of supported fields.
3092
3093 ``op`` selects the operation to perform on a destination field.
3094 - ``set`` copies the data from ``src`` field to ``dst`` field.
3095 - ``add`` adds together ``dst`` and ``src`` and stores the result into ``dst``.
3096 - ``sub`` subtracts ``src`` from ``dst`` and stores the result into ``dst``
3097
3098 ``width`` defines a number of bits to use from ``src`` field.
3099
3100 ``level`` is used to access any packet field on any encapsulation level
3101 as well as any tag element in the tag array.
3102 - ``0`` means the default behaviour. Depending on the packet type, it can
3103 mean outermost, innermost or anything in between.
3104 - ``1`` requests access to the outermost packet encapsulation level.
3105 - ``2`` and subsequent values requests access to the specified packet
3106 encapsulation level, from outermost to innermost (lower to higher values).
3107 For the tag array (in case of multiple tags are supported and present)
3108 ``level`` translates directly into the array index.
3109
3110 ``offset`` specifies the number of bits to skip from a field's start.
3111 That allows performing a partial copy of the needed part or to divide a big
3112 packet field into multiple smaller fields. Alternatively, ``offset`` allows
3113 going past the specified packet field boundary to copy a field to an
3114 arbitrary place in a packet, essentially providing a way to copy any part of
3115 a packet to any other part of it.
3116
3117 ``value`` sets an immediate value to be used as a source or points to a
3118 location of the value in memory. It is used instead of ``level`` and ``offset``
3119 for ``RTE_FLOW_FIELD_VALUE`` and ``RTE_FLOW_FIELD_POINTER`` respectively.
3120 The data in memory should be presented exactly in the same byte order and
3121 length as in the relevant flow item, i.e. data for field with type
3122 ``RTE_FLOW_FIELD_MAC_DST`` should follow the conventions of ``dst`` field
3123 in ``rte_flow_item_eth`` structure, with type ``RTE_FLOW_FIELD_IPV6_SRC`` -
3124 ``rte_flow_item_ipv6`` conventions, and so on. If the field size is larger than
3125 16 bytes the pattern can be provided as pointer only.
3126
3127 The bitfield extracted from the memory being applied as second operation
3128 parameter is defined by action width and by the destination field offset.
3129 Application should provide the data in immediate value memory (either as
3130 buffer or by pointer) exactly as item field without any applied explicit offset,
3131 and destination packet field (with specified width and bit offset) will be
3132 replaced by immediate source bits from the same bit offset. For example,
3133 to replace the third byte of MAC address with value 0x85, application should
3134 specify destination width as 8, destination offset as 16, and provide immediate
3135 value as sequence of bytes {xxx, xxx, 0x85, xxx, xxx, xxx}.
3136
3137 .. _table_rte_flow_action_modify_field:
3138
3139 .. table:: MODIFY_FIELD
3140
3141    +---------------+-------------------------+
3142    | Field         | Value                   |
3143    +===============+=========================+
3144    | ``op``        | operation to perform    |
3145    +---------------+-------------------------+
3146    | ``dst``       | destination field       |
3147    +---------------+-------------------------+
3148    | ``src``       | source field            |
3149    +---------------+-------------------------+
3150    | ``width``     | number of bits to use   |
3151    +---------------+-------------------------+
3152
3153 .. _table_rte_flow_action_modify_data:
3154
3155 .. table:: destination/source field definition
3156
3157    +---------------+----------------------------------------------------------+
3158    | Field         | Value                                                    |
3159    +===============+==========================================================+
3160    | ``field``     | ID: packet field, mark, meta, tag, immediate, pointer    |
3161    +---------------+----------------------------------------------------------+
3162    | ``level``     | encapsulation level of a packet field or tag array index |
3163    +---------------+----------------------------------------------------------+
3164    | ``offset``    | number of bits to skip at the beginning                  |
3165    +---------------+----------------------------------------------------------+
3166    | ``value``     | immediate value buffer (source field only, not           |
3167    |               | applicable to destination) for RTE_FLOW_FIELD_VALUE      |
3168    |               | field type                                               |
3169    +---------------+----------------------------------------------------------+
3170    | ``pvalue``    | pointer to immediate value data (source field only, not  |
3171    |               | applicable to destination) for RTE_FLOW_FIELD_POINTER    |
3172    |               | field type                                               |
3173    +---------------+----------------------------------------------------------+
3174
3175 Action: ``CONNTRACK``
3176 ^^^^^^^^^^^^^^^^^^^^^
3177
3178 Create a conntrack (connection tracking) context with the provided information.
3179
3180 In stateful session like TCP, the conntrack action provides the ability to
3181 examine every packet of this connection and associate the state to every
3182 packet. It will help to realize the stateful offload of connections with little
3183 software participation. For example, the packets with invalid state may be
3184 handled by the software. The control packets could be handled in the hardware.
3185 The software just need to query the state of a connection when needed, and then
3186 decide how to handle the flow rules and conntrack context.
3187
3188 A conntrack context should be created via ``rte_flow_action_handle_create()``
3189 before using. Then the handle with ``INDIRECT`` type is used for a flow rule
3190 creation. If a flow rule with an opposite direction needs to be created, the
3191 ``rte_flow_action_handle_update()`` should be used to modify the direction.
3192
3193 Not all the fields of the ``struct rte_flow_action_conntrack`` will be used
3194 for a conntrack context creating, depending on the HW, and they should be
3195 in host byte order. PMD should convert them into network byte order when
3196 needed by the HW.
3197
3198 The ``struct rte_flow_modify_conntrack`` should be used for an updating.
3199
3200 The current conntrack context information could be queried via the
3201 ``rte_flow_action_handle_query()`` interface.
3202
3203 .. _table_rte_flow_action_conntrack:
3204
3205 .. table:: CONNTRACK
3206
3207    +--------------------------+-------------------------------------------------------------+
3208    | Field                    | Value                                                       |
3209    +==========================+=============================================================+
3210    | ``peer_port``            | peer port number                                            |
3211    +--------------------------+-------------------------------------------------------------+
3212    | ``is_original_dir``      | direction of this connection for creating flow rule         |
3213    +--------------------------+-------------------------------------------------------------+
3214    | ``enable``               | enable the conntrack context                                |
3215    +--------------------------+-------------------------------------------------------------+
3216    | ``live_connection``      | one ack was seen for this connection                        |
3217    +--------------------------+-------------------------------------------------------------+
3218    | ``selective_ack``        | SACK enabled                                                |
3219    +--------------------------+-------------------------------------------------------------+
3220    | ``challenge_ack_passed`` | a challenge ack has passed                                  |
3221    +--------------------------+-------------------------------------------------------------+
3222    | ``last_direction``       | direction of the last passed packet                         |
3223    +--------------------------+-------------------------------------------------------------+
3224    | ``liberal_mode``         | only report state change                                    |
3225    +--------------------------+-------------------------------------------------------------+
3226    | ``state``                | current state                                               |
3227    +--------------------------+-------------------------------------------------------------+
3228    | ``max_ack_window``       | maximal window scaling factor                               |
3229    +--------------------------+-------------------------------------------------------------+
3230    | ``retransmission_limit`` | maximal retransmission times                                |
3231    +--------------------------+-------------------------------------------------------------+
3232    | ``original_dir``         | TCP parameters of the original direction                    |
3233    +--------------------------+-------------------------------------------------------------+
3234    | ``reply_dir``            | TCP parameters of the reply direction                       |
3235    +--------------------------+-------------------------------------------------------------+
3236    | ``last_window``          | window size of the last passed packet                       |
3237    +--------------------------+-------------------------------------------------------------+
3238    | ``last_seq``             | sequence number of the last passed packet                   |
3239    +--------------------------+-------------------------------------------------------------+
3240    | ``last_ack``             | acknowledgment number the last passed packet                |
3241    +--------------------------+-------------------------------------------------------------+
3242    | ``last_end``             | sum of ack number and length of the last passed packet      |
3243    +--------------------------+-------------------------------------------------------------+
3244
3245 .. _table_rte_flow_tcp_dir_param:
3246
3247 .. table:: configuration parameters for each direction
3248
3249    +---------------------+---------------------------------------------------------+
3250    | Field               | Value                                                   |
3251    +=====================+=========================================================+
3252    | ``scale``           | TCP window scaling factor                               |
3253    +---------------------+---------------------------------------------------------+
3254    | ``close_initiated`` | FIN sent from this direction                            |
3255    +---------------------+---------------------------------------------------------+
3256    | ``last_ack_seen``   | an ACK packet received                                  |
3257    +---------------------+---------------------------------------------------------+
3258    | ``data_unacked``    | unacknowledged data for packets from this direction     |
3259    +---------------------+---------------------------------------------------------+
3260    | ``sent_end``        | max{seq + len} seen in sent packets                     |
3261    +---------------------+---------------------------------------------------------+
3262    | ``reply_end``       | max{sack + max{win, 1}} seen in reply packets           |
3263    +---------------------+---------------------------------------------------------+
3264    | ``max_win``         | max{max{win, 1}} + {sack - ack} seen in sent packets    |
3265    +---------------------+---------------------------------------------------------+
3266    | ``max_ack``         | max{ack} + seen in sent packets                         |
3267    +---------------------+---------------------------------------------------------+
3268
3269 .. _table_rte_flow_modify_conntrack:
3270
3271 .. table:: update a conntrack context
3272
3273    +----------------+-------------------------------------------------+
3274    | Field          | Value                                           |
3275    +================+=================================================+
3276    | ``new_ct``     | new conntrack information                       |
3277    +----------------+-------------------------------------------------+
3278    | ``direction``  | direction will be updated                       |
3279    +----------------+-------------------------------------------------+
3280    | ``state``      | other fields except direction will be updated   |
3281    +----------------+-------------------------------------------------+
3282    | ``reserved``   | reserved bits                                   |
3283    +----------------+-------------------------------------------------+
3284
3285 Action: ``METER_COLOR``
3286 ^^^^^^^^^^^^^^^^^^^^^^^
3287
3288 Color the packet to reflect the meter color result.
3289
3290 The meter action must be configured before meter color action.
3291 Meter color action is set to a color to reflect the meter color result.
3292 Set the meter color in the mbuf to the selected color.
3293 The meter color action output color is the output color of the packet,
3294 which is set in the packet meta-data (i.e. struct ``rte_mbuf::sched::color``)
3295
3296 .. _table_rte_flow_action_meter_color:
3297
3298 .. table:: METER_COLOR
3299
3300    +-----------------+--------------+
3301    | Field           | Value        |
3302    +=================+==============+
3303    | ``meter_color`` | Packet color |
3304    +-----------------+--------------+
3305
3306 Action: ``PORT_REPRESENTOR``
3307 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3308
3309 At embedded switch level, send matching traffic to the given ethdev.
3310
3311 Term **ethdev** and the concept of **port representor** are synonymous.
3312 The **represented port** is an *entity* plugged to the embedded switch
3313 at the opposite end of the "wire" leading to the ethdev.
3314
3315 ::
3316
3317     .--------------------.
3318     |  PORT_REPRESENTOR  |  Ethdev (Application Port Referred to by its ID)
3319     '--------------------'
3320               /\
3321               ||
3322       .----------------.
3323       |  Logical Port  |
3324       '----------------'
3325               /\
3326               ||
3327               ||
3328               ||
3329          .----------.       .--------------------.
3330          |  Switch  |  <==  |  Matching Traffic  |
3331          '----------'       '--------------------'
3332               :
3333                :
3334               :
3335                :
3336       .----------------.
3337       |  Logical Port  |
3338       '----------------'
3339               :
3340                :
3341     .--------------------.
3342     |  REPRESENTED_PORT  |  Net / Guest / Another Ethdev (Same Application)
3343     '--------------------'
3344
3345
3346 - Requires `Attribute: Transfer`_.
3347
3348 .. _table_rte_flow_action_ethdev:
3349
3350 .. table:: ``struct rte_flow_action_ethdev``
3351
3352    +-------------+----------------+
3353    | Field       | Value          |
3354    +=============+================+
3355    | ``port_id`` | ethdev port ID |
3356    +-------------+----------------+
3357
3358 See also `Item: PORT_REPRESENTOR`_.
3359
3360 Action: ``REPRESENTED_PORT``
3361 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3362
3363 At embedded switch level, send matching traffic to
3364 the entity represented by the given ethdev.
3365
3366 Term **ethdev** and the concept of **port representor** are synonymous.
3367 The **represented port** is an *entity* plugged to the embedded switch
3368 at the opposite end of the "wire" leading to the ethdev.
3369
3370 ::
3371
3372     .--------------------.
3373     |  PORT_REPRESENTOR  |  Ethdev (Application Port Referred to by its ID)
3374     '--------------------'
3375               :
3376                :
3377       .----------------.
3378       |  Logical Port  |
3379       '----------------'
3380               :
3381                :
3382               :
3383                :
3384          .----------.       .--------------------.
3385          |  Switch  |  <==  |  Matching Traffic  |
3386          '----------'       '--------------------'
3387               ||
3388               ||
3389               ||
3390               \/
3391       .----------------.
3392       |  Logical Port  |
3393       '----------------'
3394               ||
3395               \/
3396     .--------------------.
3397     |  REPRESENTED_PORT  |  Net / Guest / Another Ethdev (Same Application)
3398     '--------------------'
3399
3400
3401 - Requires `Attribute: Transfer`_.
3402
3403 This action is meant to use the same structure as `Action: PORT_REPRESENTOR`_.
3404
3405 See also `Item: REPRESENTED_PORT`_.
3406
3407 Negative types
3408 ~~~~~~~~~~~~~~
3409
3410 All specified pattern items (``enum rte_flow_item_type``) and actions
3411 (``enum rte_flow_action_type``) use positive identifiers.
3412
3413 The negative space is reserved for dynamic types generated by PMDs during
3414 run-time. PMDs may encounter them as a result but must not accept negative
3415 identifiers they are not aware of.
3416
3417 A method to generate them remains to be defined.
3418
3419 Application may use PMD dynamic items or actions in flow rules. In that case
3420 size of configuration object in dynamic element must be a pointer size.
3421
3422 Rules management
3423 ----------------
3424
3425 A rather simple API with few functions is provided to fully manage flow
3426 rules.
3427
3428 Each created flow rule is associated with an opaque, PMD-specific handle
3429 pointer. The application is responsible for keeping it until the rule is
3430 destroyed.
3431
3432 Flows rules are represented by ``struct rte_flow`` objects.
3433
3434 Validation
3435 ~~~~~~~~~~
3436
3437 Given that expressing a definite set of device capabilities is not
3438 practical, a dedicated function is provided to check if a flow rule is
3439 supported and can be created.
3440
3441 .. code-block:: c
3442
3443    int
3444    rte_flow_validate(uint16_t port_id,
3445                      const struct rte_flow_attr *attr,
3446                      const struct rte_flow_item pattern[],
3447                      const struct rte_flow_action actions[],
3448                      struct rte_flow_error *error);
3449
3450 The flow rule is validated for correctness and whether it could be accepted
3451 by the device given sufficient resources. The rule is checked against the
3452 current device mode and queue configuration. The flow rule may also
3453 optionally be validated against existing flow rules and device resources.
3454 This function has no effect on the target device.
3455
3456 The returned value is guaranteed to remain valid only as long as no
3457 successful calls to ``rte_flow_create()`` or ``rte_flow_destroy()`` are made
3458 in the meantime and no device parameter affecting flow rules in any way are
3459 modified, due to possible collisions or resource limitations (although in
3460 such cases ``EINVAL`` should not be returned).
3461
3462 Arguments:
3463
3464 - ``port_id``: port identifier of Ethernet device.
3465 - ``attr``: flow rule attributes.
3466 - ``pattern``: pattern specification (list terminated by the END pattern
3467   item).
3468 - ``actions``: associated actions (list terminated by the END action).
3469 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
3470   this structure in case of error only.
3471
3472 Return values:
3473
3474 - 0 if flow rule is valid and can be created. A negative errno value
3475   otherwise (``rte_errno`` is also set), the following errors are defined.
3476 - ``-ENOSYS``: underlying device does not support this functionality.
3477 - ``-EINVAL``: unknown or invalid rule specification.
3478 - ``-ENOTSUP``: valid but unsupported rule specification (e.g. partial
3479   bit-masks are unsupported).
3480 - ``EEXIST``: collision with an existing rule. Only returned if device
3481   supports flow rule collision checking and there was a flow rule
3482   collision. Not receiving this return code is no guarantee that creating
3483   the rule will not fail due to a collision.
3484 - ``ENOMEM``: not enough memory to execute the function, or if the device
3485   supports resource validation, resource limitation on the device.
3486 - ``-EBUSY``: action cannot be performed due to busy device resources, may
3487   succeed if the affected queues or even the entire port are in a stopped
3488   state (see ``rte_eth_dev_rx_queue_stop()`` and ``rte_eth_dev_stop()``).
3489
3490 Creation
3491 ~~~~~~~~
3492
3493 Creating a flow rule is similar to validating one, except the rule is
3494 actually created and a handle returned.
3495
3496 .. code-block:: c
3497
3498    struct rte_flow *
3499    rte_flow_create(uint16_t port_id,
3500                    const struct rte_flow_attr *attr,
3501                    const struct rte_flow_item pattern[],
3502                    const struct rte_flow_action *actions[],
3503                    struct rte_flow_error *error);
3504
3505 Arguments:
3506
3507 - ``port_id``: port identifier of Ethernet device.
3508 - ``attr``: flow rule attributes.
3509 - ``pattern``: pattern specification (list terminated by the END pattern
3510   item).
3511 - ``actions``: associated actions (list terminated by the END action).
3512 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
3513   this structure in case of error only.
3514
3515 Return values:
3516
3517 A valid handle in case of success, NULL otherwise and ``rte_errno`` is set
3518 to the positive version of one of the error codes defined for
3519 ``rte_flow_validate()``.
3520
3521 Destruction
3522 ~~~~~~~~~~~
3523
3524 Flow rules destruction is not automatic, and a queue or a port should not be
3525 released if any are still attached to them. Applications must take care of
3526 performing this step before releasing resources.
3527
3528 .. code-block:: c
3529
3530    int
3531    rte_flow_destroy(uint16_t port_id,
3532                     struct rte_flow *flow,
3533                     struct rte_flow_error *error);
3534
3535
3536 Failure to destroy a flow rule handle may occur when other flow rules depend
3537 on it, and destroying it would result in an inconsistent state.
3538
3539 This function is only guaranteed to succeed if handles are destroyed in
3540 reverse order of their creation.
3541
3542 Arguments:
3543
3544 - ``port_id``: port identifier of Ethernet device.
3545 - ``flow``: flow rule handle to destroy.
3546 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
3547   this structure in case of error only.
3548
3549 Return values:
3550
3551 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
3552
3553 Flush
3554 ~~~~~
3555
3556 Convenience function to destroy all flow rule handles associated with a
3557 port. They are released as with successive calls to ``rte_flow_destroy()``.
3558
3559 .. code-block:: c
3560
3561    int
3562    rte_flow_flush(uint16_t port_id,
3563                   struct rte_flow_error *error);
3564
3565 In the unlikely event of failure, handles are still considered destroyed and
3566 no longer valid but the port must be assumed to be in an inconsistent state.
3567
3568 Arguments:
3569
3570 - ``port_id``: port identifier of Ethernet device.
3571 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
3572   this structure in case of error only.
3573
3574 Return values:
3575
3576 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
3577
3578 Query
3579 ~~~~~
3580
3581 Query an existing flow rule.
3582
3583 This function allows retrieving flow-specific data such as counters. Data
3584 is gathered by special actions which must be present in the flow rule
3585 definition.
3586
3587 .. code-block:: c
3588
3589    int
3590    rte_flow_query(uint16_t port_id,
3591                   struct rte_flow *flow,
3592                   const struct rte_flow_action *action,
3593                   void *data,
3594                   struct rte_flow_error *error);
3595
3596 Arguments:
3597
3598 - ``port_id``: port identifier of Ethernet device.
3599 - ``flow``: flow rule handle to query.
3600 - ``action``: action to query, this must match prototype from flow rule.
3601 - ``data``: pointer to storage for the associated query data type.
3602 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
3603   this structure in case of error only.
3604
3605 Return values:
3606
3607 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
3608
3609 Flow engine configuration
3610 -------------------------
3611
3612 Configure flow API management.
3613
3614 An application may provide some parameters at the initialization phase about
3615 rules engine configuration and/or expected flow rules characteristics.
3616 These parameters may be used by PMD to preallocate resources and configure NIC.
3617
3618 Configuration
3619 ~~~~~~~~~~~~~
3620
3621 This function performs the flow API engine configuration and allocates
3622 requested resources beforehand to avoid costly allocations later.
3623 Expected number of resources in an application allows PMD to prepare
3624 and optimize NIC hardware configuration and memory layout in advance.
3625 ``rte_flow_configure()`` must be called before any flow rule is created,
3626 but after an Ethernet device is configured.
3627 It also creates flow queues for asynchronous flow rules operations via
3628 queue-based API, see `Asynchronous operations`_ section.
3629
3630 .. code-block:: c
3631
3632    int
3633    rte_flow_configure(uint16_t port_id,
3634                       const struct rte_flow_port_attr *port_attr,
3635                       uint16_t nb_queue,
3636                       const struct rte_flow_queue_attr *queue_attr[],
3637                       struct rte_flow_error *error);
3638
3639 Information about the number of available resources can be retrieved via
3640 ``rte_flow_info_get()`` API.
3641
3642 .. code-block:: c
3643
3644    int
3645    rte_flow_info_get(uint16_t port_id,
3646                      struct rte_flow_port_info *port_info,
3647                      struct rte_flow_queue_info *queue_info,
3648                      struct rte_flow_error *error);
3649
3650 Flow templates
3651 ~~~~~~~~~~~~~~
3652
3653 Oftentimes in an application, many flow rules share a common structure
3654 (the same pattern and/or action list) so they can be grouped and classified
3655 together. This knowledge may be used as a source of optimization by a PMD/HW.
3656 The flow rule creation is done by selecting a table, a pattern template
3657 and an actions template (which are bound to the table), and setting unique
3658 values for the items and actions. This API is not thread-safe.
3659
3660 Pattern templates
3661 ^^^^^^^^^^^^^^^^^
3662
3663 The pattern template defines a common pattern (the item mask) without values.
3664 The mask value is used to select a field to match on, spec/last are ignored.
3665 The pattern template may be used by multiple tables and must not be destroyed
3666 until all these tables are destroyed first.
3667
3668 .. code-block:: c
3669
3670    struct rte_flow_pattern_template *
3671    rte_flow_pattern_template_create(uint16_t port_id,
3672        const struct rte_flow_pattern_template_attr *template_attr,
3673        const struct rte_flow_item pattern[],
3674        struct rte_flow_error *error);
3675
3676 For example, to create a pattern template to match on the destination MAC:
3677
3678 .. code-block:: c
3679
3680    const struct rte_flow_pattern_template_attr attr = {.ingress = 1};
3681    struct rte_flow_item_eth eth_m = {
3682        .dst.addr_bytes = "\xff\xff\xff\xff\xff\xff";
3683    };
3684    struct rte_flow_item pattern[] = {
3685        [0] = {.type = RTE_FLOW_ITEM_TYPE_ETH,
3686               .mask = &eth_m},
3687        [1] = {.type = RTE_FLOW_ITEM_TYPE_END,},
3688    };
3689    struct rte_flow_error err;
3690
3691    struct rte_flow_pattern_template *pattern_template =
3692            rte_flow_pattern_template_create(port, &attr, &pattern, &err);
3693
3694 The concrete value to match on will be provided at the rule creation.
3695
3696 Actions templates
3697 ^^^^^^^^^^^^^^^^^
3698
3699 The actions template holds a list of action types to be used in flow rules.
3700 The mask parameter allows specifying a shared constant value for every rule.
3701 The actions template may be used by multiple tables and must not be destroyed
3702 until all these tables are destroyed first.
3703
3704 .. code-block:: c
3705
3706    struct rte_flow_actions_template *
3707    rte_flow_actions_template_create(uint16_t port_id,
3708        const struct rte_flow_actions_template_attr *template_attr,
3709        const struct rte_flow_action actions[],
3710        const struct rte_flow_action masks[],
3711        struct rte_flow_error *error);
3712
3713 For example, to create an actions template with the same Mark ID
3714 but different Queue Index for every rule:
3715
3716 .. code-block:: c
3717
3718    rte_flow_actions_template_attr attr = {.ingress = 1};
3719    struct rte_flow_action act[] = {
3720    /* Mark ID is 4 for every rule, Queue Index is unique */
3721        [0] = {.type = RTE_FLOW_ACTION_TYPE_MARK,
3722               .conf = &(struct rte_flow_action_mark){.id = 4}},
3723        [1] = {.type = RTE_FLOW_ACTION_TYPE_QUEUE},
3724        [2] = {.type = RTE_FLOW_ACTION_TYPE_END,},
3725    };
3726    struct rte_flow_action msk[] = {
3727    /* Assign to MARK mask any non-zero value to make it constant */
3728        [0] = {.type = RTE_FLOW_ACTION_TYPE_MARK,
3729               .conf = &(struct rte_flow_action_mark){.id = 1}},
3730        [1] = {.type = RTE_FLOW_ACTION_TYPE_QUEUE},
3731        [2] = {.type = RTE_FLOW_ACTION_TYPE_END,},
3732    };
3733    struct rte_flow_error err;
3734
3735    struct rte_flow_actions_template *actions_template =
3736            rte_flow_actions_template_create(port, &attr, &act, &msk, &err);
3737
3738 The concrete value for Queue Index will be provided at the rule creation.
3739
3740 Template table
3741 ^^^^^^^^^^^^^^
3742
3743 A template table combines a number of pattern and actions templates along with
3744 shared flow rule attributes (group ID, priority and traffic direction).
3745 This way a PMD/HW can prepare all the resources needed for efficient flow rules
3746 creation in the datapath. To avoid any hiccups due to memory reallocation,
3747 the maximum number of flow rules is defined at table creation time.
3748 Any flow rule creation beyond the maximum table size is rejected.
3749 Application may create another table to accommodate more rules in this case.
3750
3751 .. code-block:: c
3752
3753    struct rte_flow_template_table *
3754    rte_flow_template_table_create(uint16_t port_id,
3755        const struct rte_flow_template_table_attr *table_attr,
3756        struct rte_flow_pattern_template *pattern_templates[],
3757        uint8_t nb_pattern_templates,
3758        struct rte_flow_actions_template *actions_templates[],
3759        uint8_t nb_actions_templates,
3760        struct rte_flow_error *error);
3761
3762 A table can be created only after the Flow Rules management is configured
3763 and pattern and actions templates are created.
3764
3765 .. code-block:: c
3766
3767    rte_flow_template_table_attr table_attr = {
3768        .flow_attr.ingress = 1,
3769        .nb_flows = 10000;
3770    };
3771    uint8_t nb_pattern_templ = 1;
3772    struct rte_flow_pattern_template *pattern_templates[nb_pattern_templ];
3773    pattern_templates[0] = pattern_template;
3774    uint8_t nb_actions_templ = 1;
3775    struct rte_flow_actions_template *actions_templates[nb_actions_templ];
3776    actions_templates[0] = actions_template;
3777    struct rte_flow_error error;
3778
3779    struct rte_flow_template_table *table =
3780            rte_flow_template_table_create(port, &table_attr,
3781                    &pattern_templates, nb_pattern_templ,
3782                    &actions_templates, nb_actions_templ,
3783                    &error);
3784
3785 Asynchronous operations
3786 -----------------------
3787
3788 Flow rules management can be done via special lockless flow management queues.
3789 - Queue operations are asynchronous and not thread-safe.
3790
3791 - Operations can thus be invoked by the app's datapath,
3792   packet processing can continue while queue operations are processed by NIC.
3793
3794 - Number of flow queues is configured at initialization stage.
3795
3796 - Available operation types: rule creation, rule destruction,
3797   indirect rule creation, indirect rule destruction, indirect rule update.
3798
3799 - Operations may be reordered within a queue.
3800
3801 - Operations can be postponed and pushed to NIC in batches.
3802
3803 - Results pulling must be done on time to avoid queue overflows.
3804
3805 - User data is returned as part of the result to identify an operation.
3806
3807 - Flow handle is valid once the creation operation is enqueued and must be
3808   destroyed even if the operation is not successful and the rule is not inserted.
3809
3810 - Application must wait for the creation operation result before enqueueing
3811   the deletion operation to make sure the creation is processed by NIC.
3812
3813 The asynchronous flow rule insertion logic can be broken into two phases.
3814
3815 1. Initialization stage as shown here:
3816
3817 .. _figure_rte_flow_async_init:
3818
3819 .. figure:: img/rte_flow_async_init.*
3820
3821 2. Main loop as presented on a datapath application example:
3822
3823 .. _figure_rte_flow_async_usage:
3824
3825 .. figure:: img/rte_flow_async_usage.*
3826
3827 Enqueue creation operation
3828 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3829
3830 Enqueueing a flow rule creation operation is similar to simple creation.
3831
3832 .. code-block:: c
3833
3834    struct rte_flow *
3835    rte_flow_async_create(uint16_t port_id,
3836                          uint32_t queue_id,
3837                          const struct rte_flow_op_attr *op_attr,
3838                          struct rte_flow_template_table *template_table,
3839                          const struct rte_flow_item pattern[],
3840                          uint8_t pattern_template_index,
3841                          const struct rte_flow_action actions[],
3842                          uint8_t actions_template_index,
3843                          void *user_data,
3844                          struct rte_flow_error *error);
3845
3846 A valid handle in case of success is returned. It must be destroyed later
3847 by calling ``rte_flow_async_destroy()`` even if the rule is rejected by HW.
3848
3849 Enqueue destruction operation
3850 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3851
3852 Enqueueing a flow rule destruction operation is similar to simple destruction.
3853
3854 .. code-block:: c
3855
3856    int
3857    rte_flow_async_destroy(uint16_t port_id,
3858                           uint32_t queue_id,
3859                           const struct rte_flow_op_attr *op_attr,
3860                           struct rte_flow *flow,
3861                           void *user_data,
3862                           struct rte_flow_error *error);
3863
3864 Enqueue indirect action creation operation
3865 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3866
3867 Asynchronous version of indirect action creation API.
3868
3869 .. code-block:: c
3870
3871    struct rte_flow_action_handle *
3872    rte_flow_async_action_handle_create(uint16_t port_id,
3873            uint32_t queue_id,
3874            const struct rte_flow_op_attr *q_ops_attr,
3875            const struct rte_flow_indir_action_conf *indir_action_conf,
3876            const struct rte_flow_action *action,
3877            void *user_data,
3878            struct rte_flow_error *error);
3879
3880 A valid handle in case of success is returned. It must be destroyed later by
3881 ``rte_flow_async_action_handle_destroy()`` even if the rule was rejected.
3882
3883 Enqueue indirect action destruction operation
3884 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3885
3886 Asynchronous version of indirect action destruction API.
3887
3888 .. code-block:: c
3889
3890    int
3891    rte_flow_async_action_handle_destroy(uint16_t port_id,
3892            uint32_t queue_id,
3893            const struct rte_flow_op_attr *q_ops_attr,
3894            struct rte_flow_action_handle *action_handle,
3895            void *user_data,
3896            struct rte_flow_error *error);
3897
3898 Enqueue indirect action update operation
3899 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3900
3901 Asynchronous version of indirect action update API.
3902
3903 .. code-block:: c
3904
3905    int
3906    rte_flow_async_action_handle_update(uint16_t port_id,
3907            uint32_t queue_id,
3908            const struct rte_flow_op_attr *q_ops_attr,
3909            struct rte_flow_action_handle *action_handle,
3910            const void *update,
3911            void *user_data,
3912            struct rte_flow_error *error);
3913
3914 Push enqueued operations
3915 ~~~~~~~~~~~~~~~~~~~~~~~~
3916
3917 Pushing all internally stored rules from a queue to the NIC.
3918
3919 .. code-block:: c
3920
3921    int
3922    rte_flow_push(uint16_t port_id,
3923                  uint32_t queue_id,
3924                  struct rte_flow_error *error);
3925
3926 There is the postpone attribute in the queue operation attributes.
3927 When it is set, multiple operations can be bulked together and not sent to HW
3928 right away to save SW/HW interactions and prioritize throughput over latency.
3929 The application must invoke this function to actually push all outstanding
3930 operations to HW in this case.
3931
3932 Pull enqueued operations
3933 ~~~~~~~~~~~~~~~~~~~~~~~~
3934
3935 Pulling asynchronous operations results.
3936
3937 The application must invoke this function in order to complete asynchronous
3938 flow rule operations and to receive flow rule operations statuses.
3939
3940 .. code-block:: c
3941
3942    int
3943    rte_flow_pull(uint16_t port_id,
3944                  uint32_t queue_id,
3945                  struct rte_flow_op_result res[],
3946                  uint16_t n_res,
3947                  struct rte_flow_error *error);
3948
3949 Multiple outstanding operation results can be pulled simultaneously.
3950 User data may be provided during a flow creation/destruction in order
3951 to distinguish between multiple operations. User data is returned as part
3952 of the result to provide a method to detect which operation is completed.
3953
3954 .. _flow_isolated_mode:
3955
3956 Flow isolated mode
3957 ------------------
3958
3959 The general expectation for ingress traffic is that flow rules process it
3960 first; the remaining unmatched or pass-through traffic usually ends up in a
3961 queue (with or without RSS, locally or in some sub-device instance)
3962 depending on the global configuration settings of a port.
3963
3964 While fine from a compatibility standpoint, this approach makes drivers more
3965 complex as they have to check for possible side effects outside of this API
3966 when creating or destroying flow rules. It results in a more limited set of
3967 available rule types due to the way device resources are assigned (e.g. no
3968 support for the RSS action even on capable hardware).
3969
3970 Given that nonspecific traffic can be handled by flow rules as well,
3971 isolated mode is a means for applications to tell a driver that ingress on
3972 the underlying port must be injected from the defined flow rules only; that
3973 no default traffic is expected outside those rules.
3974
3975 This has the following benefits:
3976
3977 - Applications get finer-grained control over the kind of traffic they want
3978   to receive (no traffic by default).
3979
3980 - More importantly they control at what point nonspecific traffic is handled
3981   relative to other flow rules, by adjusting priority levels.
3982
3983 - Drivers can assign more hardware resources to flow rules and expand the
3984   set of supported rule types.
3985
3986 Because toggling isolated mode may cause profound changes to the ingress
3987 processing path of a driver, it may not be possible to leave it once
3988 entered. Likewise, existing flow rules or global configuration settings may
3989 prevent a driver from entering isolated mode.
3990
3991 Applications relying on this mode are therefore encouraged to toggle it as
3992 soon as possible after device initialization, ideally before the first call
3993 to ``rte_eth_dev_configure()`` to avoid possible failures due to conflicting
3994 settings.
3995
3996 Once effective, the following functionality has no effect on the underlying
3997 port and may return errors such as ``ENOTSUP`` ("not supported"):
3998
3999 - Toggling promiscuous mode.
4000 - Toggling allmulticast mode.
4001 - Configuring MAC addresses.
4002 - Configuring multicast addresses.
4003 - Configuring VLAN filters.
4004 - Configuring global RSS settings.
4005
4006 .. code-block:: c
4007
4008    int
4009    rte_flow_isolate(uint16_t port_id, int set, struct rte_flow_error *error);
4010
4011 Arguments:
4012
4013 - ``port_id``: port identifier of Ethernet device.
4014 - ``set``: nonzero to enter isolated mode, attempt to leave it otherwise.
4015 - ``error``: perform verbose error reporting if not NULL. PMDs initialize
4016   this structure in case of error only.
4017
4018 Return values:
4019
4020 - 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
4021
4022 Verbose error reporting
4023 -----------------------
4024
4025 The defined *errno* values may not be accurate enough for users or
4026 application developers who want to investigate issues related to flow rules
4027 management. A dedicated error object is defined for this purpose:
4028
4029 .. code-block:: c
4030
4031    enum rte_flow_error_type {
4032        RTE_FLOW_ERROR_TYPE_NONE, /**< No error. */
4033        RTE_FLOW_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
4034        RTE_FLOW_ERROR_TYPE_HANDLE, /**< Flow rule (handle). */
4035        RTE_FLOW_ERROR_TYPE_ATTR_GROUP, /**< Group field. */
4036        RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */
4037        RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */
4038        RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */
4039        RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */
4040        RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */
4041        RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */
4042        RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */
4043        RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */
4044    };
4045
4046    struct rte_flow_error {
4047        enum rte_flow_error_type type; /**< Cause field and error types. */
4048        const void *cause; /**< Object responsible for the error. */
4049        const char *message; /**< Human-readable error message. */
4050    };
4051
4052 Error type ``RTE_FLOW_ERROR_TYPE_NONE`` stands for no error, in which case
4053 remaining fields can be ignored. Other error types describe the type of the
4054 object pointed by ``cause``.
4055
4056 If non-NULL, ``cause`` points to the object responsible for the error. For a
4057 flow rule, this may be a pattern item or an individual action.
4058
4059 If non-NULL, ``message`` provides a human-readable error message.
4060
4061 This object is normally allocated by applications and set by PMDs in case of
4062 error, the message points to a constant string which does not need to be
4063 freed by the application, however its pointer can be considered valid only
4064 as long as its associated DPDK port remains configured. Closing the
4065 underlying device or unloading the PMD invalidates it.
4066
4067 Helpers
4068 -------
4069
4070 Error initializer
4071 ~~~~~~~~~~~~~~~~~
4072
4073 .. code-block:: c
4074
4075    static inline int
4076    rte_flow_error_set(struct rte_flow_error *error,
4077                       int code,
4078                       enum rte_flow_error_type type,
4079                       const void *cause,
4080                       const char *message);
4081
4082 This function initializes ``error`` (if non-NULL) with the provided
4083 parameters and sets ``rte_errno`` to ``code``. A negative error ``code`` is
4084 then returned.
4085
4086 Object conversion
4087 ~~~~~~~~~~~~~~~~~
4088
4089 .. code-block:: c
4090
4091    int
4092    rte_flow_conv(enum rte_flow_conv_op op,
4093                  void *dst,
4094                  size_t size,
4095                  const void *src,
4096                  struct rte_flow_error *error);
4097
4098 Convert ``src`` to ``dst`` according to operation ``op``. Possible
4099 operations include:
4100
4101 - Attributes, pattern item or action duplication.
4102 - Duplication of an entire pattern or list of actions.
4103 - Duplication of a complete flow rule description.
4104 - Pattern item or action name retrieval.
4105
4106 Tunneled traffic offload
4107 ~~~~~~~~~~~~~~~~~~~~~~~~
4108
4109 rte_flow API provides the building blocks for vendor-agnostic flow
4110 classification offloads. The rte_flow "patterns" and "actions"
4111 primitives are fine-grained, thus enabling DPDK applications the
4112 flexibility to offload network stacks and complex pipelines.
4113 Applications wishing to offload tunneled traffic are required to use
4114 the rte_flow primitives, such as group, meta, mark, tag, and others to
4115 model their high-level objects.  The hardware model design for
4116 high-level software objects is not trivial.  Furthermore, an optimal
4117 design is often vendor-specific.
4118
4119 When hardware offloads tunneled traffic in multi-group logic,
4120 partially offloaded packets may arrive to the application after they
4121 were modified in hardware. In this case, the application may need to
4122 restore the original packet headers. Consider the following sequence:
4123 The application decaps a packet in one group and jumps to a second
4124 group where it tries to match on a 5-tuple, that will miss and send
4125 the packet to the application. In this case, the application does not
4126 receive the original packet but a modified one. Also, in this case,
4127 the application cannot match on the outer header fields, such as VXLAN
4128 vni and 5-tuple.
4129
4130 There are several possible ways to use rte_flow "patterns" and
4131 "actions" to resolve the issues above. For example:
4132
4133 1 Mapping headers to a hardware registers using the
4134 rte_flow_action_mark/rte_flow_action_tag/rte_flow_set_meta objects.
4135
4136 2 Apply the decap only at the last offload stage after all the
4137 "patterns" were matched and the packet will be fully offloaded.
4138
4139 Every approach has its pros and cons and is highly dependent on the
4140 hardware vendor.  For example, some hardware may have a limited number
4141 of registers while other hardware could not support inner actions and
4142 must decap before accessing inner headers.
4143
4144 The tunnel offload model resolves these issues. The model goals are:
4145
4146 1 Provide a unified application API to offload tunneled traffic that
4147 is capable to match on outer headers after decap.
4148
4149 2 Allow the application to restore the outer header of partially
4150 offloaded packets.
4151
4152 The tunnel offload model does not introduce new elements to the
4153 existing RTE flow model and is implemented as a set of helper
4154 functions.
4155
4156 For the application to work with the tunnel offload API it
4157 has to adjust flow rules in multi-table tunnel offload in the
4158 following way:
4159
4160 1 Remove explicit call to decap action and replace it with PMD actions
4161 obtained from rte_flow_tunnel_decap_and_set() helper.
4162
4163 2 Add PMD items obtained from rte_flow_tunnel_match() helper to all
4164 other rules in the tunnel offload sequence.
4165
4166 The model requirements:
4167
4168 Software application must initialize
4169 rte_tunnel object with tunnel parameters before calling
4170 rte_flow_tunnel_decap_set() & rte_flow_tunnel_match().
4171
4172 PMD actions array obtained in rte_flow_tunnel_decap_set() must be
4173 released by application with rte_flow_action_release() call.
4174
4175 PMD items array obtained with rte_flow_tunnel_match() must be released
4176 by application with rte_flow_item_release() call.  Application can
4177 release PMD items and actions after rule was created. However, if the
4178 application needs to create additional rule for the same tunnel it
4179 will need to obtain PMD items again.
4180
4181 Application cannot destroy rte_tunnel object before it releases all
4182 PMD actions & PMD items referencing that tunnel.
4183
4184 Caveats
4185 -------
4186
4187 - DPDK does not keep track of flow rules definitions or flow rule objects
4188   automatically. Applications may keep track of the former and must keep
4189   track of the latter. PMDs may also do it for internal needs, however this
4190   must not be relied on by applications.
4191
4192 - Flow rules are not maintained between successive port initializations. An
4193   application exiting without releasing them and restarting must re-create
4194   them from scratch.
4195
4196 - API operations are synchronous and blocking (``EAGAIN`` cannot be
4197   returned).
4198
4199 - Stopping the data path (TX/RX) should not be necessary when managing flow
4200   rules. If this cannot be achieved naturally or with workarounds (such as
4201   temporarily replacing the burst function pointers), an appropriate error
4202   code must be returned (``EBUSY``).
4203
4204 - Applications, not PMDs, are responsible for maintaining flow rules
4205   configuration when closing, stopping or restarting a port or performing other
4206   actions which may affect them.
4207   Applications must assume that after port close, stop or restart all flows
4208   related to that port are not valid, hardware rules are destroyed and relevant
4209   PMD resources are released.
4210
4211 For devices exposing multiple ports sharing global settings affected by flow
4212 rules:
4213
4214 - All ports under DPDK control must behave consistently, PMDs are
4215   responsible for making sure that existing flow rules on a port are not
4216   affected by other ports.
4217
4218 - Ports not under DPDK control (unaffected or handled by other applications)
4219   are user's responsibility. They may affect existing flow rules and cause
4220   undefined behavior. PMDs aware of this may prevent flow rules creation
4221   altogether in such cases.
4222
4223 PMD interface
4224 -------------
4225
4226 The PMD interface is defined in ``rte_flow_driver.h``. It is not subject to
4227 API/ABI versioning constraints as it is not exposed to applications and may
4228 evolve independently.
4229
4230 The PMD interface is based on callbacks pointed by the ``struct rte_flow_ops``.
4231
4232 - PMD callbacks implement exactly the interface described in `Rules
4233   management`_, except for the port ID argument which has already been
4234   converted to a pointer to the underlying ``struct rte_eth_dev``.
4235
4236 - Public API functions do not process flow rules definitions at all before
4237   calling PMD functions (no basic error checking, no validation
4238   whatsoever). They only make sure these callbacks are non-NULL or return
4239   the ``ENOSYS`` (function not supported) error.
4240
4241 This interface additionally defines the following helper function:
4242
4243 - ``rte_flow_ops_get()``: get generic flow operations structure from a
4244   port.
4245
4246 If PMD interfaces don't support re-entrancy/multi-thread safety,
4247 the rte_flow API functions will protect threads by mutex per port.
4248 The application can check whether ``RTE_ETH_DEV_FLOW_OPS_THREAD_SAFE``
4249 is set in ``dev_flags``, meaning the PMD is thread-safe regarding rte_flow,
4250 so the API level protection is disabled.
4251 Please note that this API-level mutex protects only rte_flow functions,
4252 other control path functions are not in scope.
4253
4254 Device compatibility
4255 --------------------
4256
4257 No known implementation supports all the described features.
4258
4259 Unsupported features or combinations are not expected to be fully emulated
4260 in software by PMDs for performance reasons. Partially supported features
4261 may be completed in software as long as hardware performs most of the work
4262 (such as queue redirection and packet recognition).
4263
4264 However PMDs are expected to do their best to satisfy application requests
4265 by working around hardware limitations as long as doing so does not affect
4266 the behavior of existing flow rules.
4267
4268 The following sections provide a few examples of such cases and describe how
4269 PMDs should handle them, they are based on limitations built into the
4270 previous APIs.
4271
4272 Global bit-masks
4273 ~~~~~~~~~~~~~~~~
4274
4275 Each flow rule comes with its own, per-layer bit-masks, while hardware may
4276 support only a single, device-wide bit-mask for a given layer type, so that
4277 two IPv4 rules cannot use different bit-masks.
4278
4279 The expected behavior in this case is that PMDs automatically configure
4280 global bit-masks according to the needs of the first flow rule created.
4281
4282 Subsequent rules are allowed only if their bit-masks match those, the
4283 ``EEXIST`` error code should be returned otherwise.
4284
4285 Unsupported layer types
4286 ~~~~~~~~~~~~~~~~~~~~~~~
4287
4288 Many protocols can be simulated by crafting patterns with the `Item: RAW`_
4289 type.
4290
4291 PMDs can rely on this capability to simulate support for protocols with
4292 headers not directly recognized by hardware.
4293
4294 ``ANY`` pattern item
4295 ~~~~~~~~~~~~~~~~~~~~
4296
4297 This pattern item stands for anything, which can be difficult to translate
4298 to something hardware would understand, particularly if followed by more
4299 specific types.
4300
4301 Consider the following pattern:
4302
4303 .. _table_rte_flow_unsupported_any:
4304
4305 .. table:: Pattern with ANY as L3
4306
4307    +-------+-----------------------+
4308    | Index | Item                  |
4309    +=======+=======================+
4310    | 0     | ETHER                 |
4311    +-------+-----+---------+-------+
4312    | 1     | ANY | ``num`` | ``1`` |
4313    +-------+-----+---------+-------+
4314    | 2     | TCP                   |
4315    +-------+-----------------------+
4316    | 3     | END                   |
4317    +-------+-----------------------+
4318
4319 Knowing that TCP does not make sense with something other than IPv4 and IPv6
4320 as L3, such a pattern may be translated to two flow rules instead:
4321
4322 .. _table_rte_flow_unsupported_any_ipv4:
4323
4324 .. table:: ANY replaced with IPV4
4325
4326    +-------+--------------------+
4327    | Index | Item               |
4328    +=======+====================+
4329    | 0     | ETHER              |
4330    +-------+--------------------+
4331    | 1     | IPV4 (zeroed mask) |
4332    +-------+--------------------+
4333    | 2     | TCP                |
4334    +-------+--------------------+
4335    | 3     | END                |
4336    +-------+--------------------+
4337
4338 |
4339
4340 .. _table_rte_flow_unsupported_any_ipv6:
4341
4342 .. table:: ANY replaced with IPV6
4343
4344    +-------+--------------------+
4345    | Index | Item               |
4346    +=======+====================+
4347    | 0     | ETHER              |
4348    +-------+--------------------+
4349    | 1     | IPV6 (zeroed mask) |
4350    +-------+--------------------+
4351    | 2     | TCP                |
4352    +-------+--------------------+
4353    | 3     | END                |
4354    +-------+--------------------+
4355
4356 Note that as soon as a ANY rule covers several layers, this approach may
4357 yield a large number of hidden flow rules. It is thus suggested to only
4358 support the most common scenarios (anything as L2 and/or L3).
4359
4360 Unsupported actions
4361 ~~~~~~~~~~~~~~~~~~~
4362
4363 - When combined with `Action: QUEUE`_, packet counting (`Action: COUNT`_)
4364   and tagging (`Action: MARK`_ or `Action: FLAG`_) may be implemented in
4365   software as long as the target queue is used by a single rule.
4366
4367 - When a single target queue is provided, `Action: RSS`_ can also be
4368   implemented through `Action: QUEUE`_.
4369
4370 Flow rules priority
4371 ~~~~~~~~~~~~~~~~~~~
4372
4373 While it would naturally make sense, flow rules cannot be assumed to be
4374 processed by hardware in the same order as their creation for several
4375 reasons:
4376
4377 - They may be managed internally as a tree or a hash table instead of a
4378   list.
4379 - Removing a flow rule before adding another one can either put the new rule
4380   at the end of the list or reuse a freed entry.
4381 - Duplication may occur when packets are matched by several rules.
4382
4383 For overlapping rules (particularly in order to use `Action: PASSTHRU`_)
4384 predictable behavior is only guaranteed by using different priority levels.
4385
4386 Priority levels are not necessarily implemented in hardware, or may be
4387 severely limited (e.g. a single priority bit).
4388
4389 For these reasons, priority levels may be implemented purely in software by
4390 PMDs.
4391
4392 - For devices expecting flow rules to be added in the correct order, PMDs
4393   may destroy and re-create existing rules after adding a new one with
4394   a higher priority.
4395
4396 - A configurable number of dummy or empty rules can be created at
4397   initialization time to save high priority slots for later.
4398
4399 - In order to save priority levels, PMDs may evaluate whether rules are
4400   likely to collide and adjust their priority accordingly.
4401
4402
4403 .. _OpenFlow Switch Specification: https://www.opennetworking.org/software-defined-standards/specifications/