4 * Copyright 2016 6WIND S.A.
5 * Copyright 2016 Mellanox.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
17 * * Neither the name of 6WIND S.A. nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 * RTE generic flow API
41 * This interface provides the ability to program packet matching and
42 * associated actions in hardware through flow rules.
46 #include <rte_ether.h>
52 #include <rte_byteorder.h>
60 * Flow rule attributes.
62 * Priorities are set on two levels: per group and per rule within groups.
64 * Lower values denote higher priority, the highest priority for both levels
65 * is 0, so that a rule with priority 0 in group 8 is always matched after a
66 * rule with priority 8 in group 0.
68 * Although optional, applications are encouraged to group similar rules as
69 * much as possible to fully take advantage of hardware capabilities
70 * (e.g. optimized matching) and work around limitations (e.g. a single
71 * pattern type possibly allowed in a given group).
73 * Group and priority levels are arbitrary and up to the application, they
74 * do not need to be contiguous nor start from 0, however the maximum number
75 * varies between devices and may be affected by existing flow rules.
77 * If a packet is matched by several rules of a given group for a given
78 * priority level, the outcome is undefined. It can take any path, may be
79 * duplicated or even cause unrecoverable errors.
81 * Note that support for more than a single group and priority level is not
84 * Flow rules can apply to inbound and/or outbound traffic (ingress/egress).
86 * Several pattern items and actions are valid and can be used in both
87 * directions. Those valid for only one direction are described as such.
89 * At least one direction must be specified.
91 * Specifying both directions at once for a given rule is not recommended
92 * but may be valid in a few cases (e.g. shared counter).
94 struct rte_flow_attr {
95 uint32_t group; /**< Priority group. */
96 uint32_t priority; /**< Priority level within group. */
97 uint32_t ingress:1; /**< Rule applies to ingress traffic. */
98 uint32_t egress:1; /**< Rule applies to egress traffic. */
99 uint32_t reserved:30; /**< Reserved, must be zero. */
103 * Matching pattern item types.
105 * Pattern items fall in two categories:
107 * - Matching protocol headers and packet data (ANY, RAW, ETH, VLAN, IPV4,
108 * IPV6, ICMP, UDP, TCP, SCTP, VXLAN and so on), usually associated with a
109 * specification structure. These must be stacked in the same order as the
110 * protocol layers to match, starting from the lowest.
112 * - Matching meta-data or affecting pattern processing (END, VOID, INVERT,
113 * PF, VF, PORT and so on), often without a specification structure. Since
114 * they do not match packet contents, these can be specified anywhere
115 * within item lists without affecting others.
117 * See the description of individual types for more information. Those
118 * marked with [META] fall into the second category.
120 enum rte_flow_item_type {
124 * End marker for item lists. Prevents further processing of items,
125 * thereby ending the pattern.
127 * No associated specification structure.
129 RTE_FLOW_ITEM_TYPE_END,
134 * Used as a placeholder for convenience. It is ignored and simply
137 * No associated specification structure.
139 RTE_FLOW_ITEM_TYPE_VOID,
144 * Inverted matching, i.e. process packets that do not match the
147 * No associated specification structure.
149 RTE_FLOW_ITEM_TYPE_INVERT,
152 * Matches any protocol in place of the current layer, a single ANY
153 * may also stand for several protocol layers.
155 * See struct rte_flow_item_any.
157 RTE_FLOW_ITEM_TYPE_ANY,
162 * Matches packets addressed to the physical function of the device.
164 * If the underlying device function differs from the one that would
165 * normally receive the matched traffic, specifying this item
166 * prevents it from reaching that device unless the flow rule
167 * contains a PF action. Packets are not duplicated between device
168 * instances by default.
170 * No associated specification structure.
172 RTE_FLOW_ITEM_TYPE_PF,
177 * Matches packets addressed to a virtual function ID of the device.
179 * If the underlying device function differs from the one that would
180 * normally receive the matched traffic, specifying this item
181 * prevents it from reaching that device unless the flow rule
182 * contains a VF action. Packets are not duplicated between device
183 * instances by default.
185 * See struct rte_flow_item_vf.
187 RTE_FLOW_ITEM_TYPE_VF,
192 * Matches packets coming from the specified physical port of the
195 * The first PORT item overrides the physical port normally
196 * associated with the specified DPDK input port (port_id). This
197 * item can be provided several times to match additional physical
200 * See struct rte_flow_item_port.
202 RTE_FLOW_ITEM_TYPE_PORT,
205 * Matches a byte string of a given length at a given offset.
207 * See struct rte_flow_item_raw.
209 RTE_FLOW_ITEM_TYPE_RAW,
212 * Matches an Ethernet header.
214 * See struct rte_flow_item_eth.
216 RTE_FLOW_ITEM_TYPE_ETH,
219 * Matches an 802.1Q/ad VLAN tag.
221 * See struct rte_flow_item_vlan.
223 RTE_FLOW_ITEM_TYPE_VLAN,
226 * Matches an IPv4 header.
228 * See struct rte_flow_item_ipv4.
230 RTE_FLOW_ITEM_TYPE_IPV4,
233 * Matches an IPv6 header.
235 * See struct rte_flow_item_ipv6.
237 RTE_FLOW_ITEM_TYPE_IPV6,
240 * Matches an ICMP header.
242 * See struct rte_flow_item_icmp.
244 RTE_FLOW_ITEM_TYPE_ICMP,
247 * Matches a UDP header.
249 * See struct rte_flow_item_udp.
251 RTE_FLOW_ITEM_TYPE_UDP,
254 * Matches a TCP header.
256 * See struct rte_flow_item_tcp.
258 RTE_FLOW_ITEM_TYPE_TCP,
261 * Matches a SCTP header.
263 * See struct rte_flow_item_sctp.
265 RTE_FLOW_ITEM_TYPE_SCTP,
268 * Matches a VXLAN header.
270 * See struct rte_flow_item_vxlan.
272 RTE_FLOW_ITEM_TYPE_VXLAN,
275 * Matches a E_TAG header.
277 * See struct rte_flow_item_e_tag.
279 RTE_FLOW_ITEM_TYPE_E_TAG,
282 * Matches a NVGRE header.
284 * See struct rte_flow_item_nvgre.
286 RTE_FLOW_ITEM_TYPE_NVGRE,
289 * Matches a MPLS header.
291 * See struct rte_flow_item_mpls.
293 RTE_FLOW_ITEM_TYPE_MPLS,
296 * Matches a GRE header.
298 * See struct rte_flow_item_gre.
300 RTE_FLOW_ITEM_TYPE_GRE,
305 * Fuzzy pattern match, expect faster than default.
307 * This is for device that support fuzzy matching option.
308 * Usually a fuzzy matching is fast but the cost is accuracy.
310 * See struct rte_flow_item_fuzzy.
312 RTE_FLOW_ITEM_TYPE_FUZZY,
315 * Matches a GTP header.
317 * Configure flow for GTP packets.
319 * See struct rte_flow_item_gtp.
321 RTE_FLOW_ITEM_TYPE_GTP,
324 * Matches a GTP header.
326 * Configure flow for GTP-C packets.
328 * See struct rte_flow_item_gtp.
330 RTE_FLOW_ITEM_TYPE_GTPC,
333 * Matches a GTP header.
335 * Configure flow for GTP-U packets.
337 * See struct rte_flow_item_gtp.
339 RTE_FLOW_ITEM_TYPE_GTPU,
342 * Matches a ESP header.
344 * See struct rte_flow_item_esp.
346 RTE_FLOW_ITEM_TYPE_ESP,
349 * Matches a GENEVE header.
351 * See struct rte_flow_item_geneve.
353 RTE_FLOW_ITEM_TYPE_GENEVE,
357 * RTE_FLOW_ITEM_TYPE_ANY
359 * Matches any protocol in place of the current layer, a single ANY may also
360 * stand for several protocol layers.
362 * This is usually specified as the first pattern item when looking for a
363 * protocol anywhere in a packet.
365 * A zeroed mask stands for any number of layers.
367 struct rte_flow_item_any {
368 uint32_t num; /**< Number of layers covered. */
371 /** Default mask for RTE_FLOW_ITEM_TYPE_ANY. */
373 static const struct rte_flow_item_any rte_flow_item_any_mask = {
379 * RTE_FLOW_ITEM_TYPE_VF
381 * Matches packets addressed to a virtual function ID of the device.
383 * If the underlying device function differs from the one that would
384 * normally receive the matched traffic, specifying this item prevents it
385 * from reaching that device unless the flow rule contains a VF
386 * action. Packets are not duplicated between device instances by default.
388 * - Likely to return an error or never match any traffic if this causes a
389 * VF device to match traffic addressed to a different VF.
390 * - Can be specified multiple times to match traffic addressed to several
392 * - Can be combined with a PF item to match both PF and VF traffic.
394 * A zeroed mask can be used to match any VF ID.
396 struct rte_flow_item_vf {
397 uint32_t id; /**< Destination VF ID. */
400 /** Default mask for RTE_FLOW_ITEM_TYPE_VF. */
402 static const struct rte_flow_item_vf rte_flow_item_vf_mask = {
408 * RTE_FLOW_ITEM_TYPE_PORT
410 * Matches packets coming from the specified physical port of the underlying
413 * The first PORT item overrides the physical port normally associated with
414 * the specified DPDK input port (port_id). This item can be provided
415 * several times to match additional physical ports.
417 * Note that physical ports are not necessarily tied to DPDK input ports
418 * (port_id) when those are not under DPDK control. Possible values are
419 * specific to each device, they are not necessarily indexed from zero and
420 * may not be contiguous.
422 * As a device property, the list of allowed values as well as the value
423 * associated with a port_id should be retrieved by other means.
425 * A zeroed mask can be used to match any port index.
427 struct rte_flow_item_port {
428 uint32_t index; /**< Physical port index. */
431 /** Default mask for RTE_FLOW_ITEM_TYPE_PORT. */
433 static const struct rte_flow_item_port rte_flow_item_port_mask = {
439 * RTE_FLOW_ITEM_TYPE_RAW
441 * Matches a byte string of a given length at a given offset.
443 * Offset is either absolute (using the start of the packet) or relative to
444 * the end of the previous matched item in the stack, in which case negative
445 * values are allowed.
447 * If search is enabled, offset is used as the starting point. The search
448 * area can be delimited by setting limit to a nonzero value, which is the
449 * maximum number of bytes after offset where the pattern may start.
451 * Matching a zero-length pattern is allowed, doing so resets the relative
452 * offset for subsequent items.
454 * This type does not support ranges (struct rte_flow_item.last).
456 struct rte_flow_item_raw {
457 uint32_t relative:1; /**< Look for pattern after the previous item. */
458 uint32_t search:1; /**< Search pattern from offset (see also limit). */
459 uint32_t reserved:30; /**< Reserved, must be set to zero. */
460 int32_t offset; /**< Absolute or relative offset for pattern. */
461 uint16_t limit; /**< Search area limit for start of pattern. */
462 uint16_t length; /**< Pattern length. */
463 uint8_t pattern[]; /**< Byte string to look for. */
466 /** Default mask for RTE_FLOW_ITEM_TYPE_RAW. */
468 static const struct rte_flow_item_raw rte_flow_item_raw_mask = {
471 .reserved = 0x3fffffff,
472 .offset = 0xffffffff,
479 * RTE_FLOW_ITEM_TYPE_ETH
481 * Matches an Ethernet header.
483 struct rte_flow_item_eth {
484 struct ether_addr dst; /**< Destination MAC. */
485 struct ether_addr src; /**< Source MAC. */
486 rte_be16_t type; /**< EtherType. */
489 /** Default mask for RTE_FLOW_ITEM_TYPE_ETH. */
491 static const struct rte_flow_item_eth rte_flow_item_eth_mask = {
492 .dst.addr_bytes = "\xff\xff\xff\xff\xff\xff",
493 .src.addr_bytes = "\xff\xff\xff\xff\xff\xff",
494 .type = RTE_BE16(0x0000),
499 * RTE_FLOW_ITEM_TYPE_VLAN
501 * Matches an 802.1Q/ad VLAN tag.
503 * This type normally follows either RTE_FLOW_ITEM_TYPE_ETH or
504 * RTE_FLOW_ITEM_TYPE_VLAN.
506 struct rte_flow_item_vlan {
507 rte_be16_t tpid; /**< Tag protocol identifier. */
508 rte_be16_t tci; /**< Tag control information. */
511 /** Default mask for RTE_FLOW_ITEM_TYPE_VLAN. */
513 static const struct rte_flow_item_vlan rte_flow_item_vlan_mask = {
514 .tpid = RTE_BE16(0x0000),
515 .tci = RTE_BE16(0xffff),
520 * RTE_FLOW_ITEM_TYPE_IPV4
522 * Matches an IPv4 header.
524 * Note: IPv4 options are handled by dedicated pattern items.
526 struct rte_flow_item_ipv4 {
527 struct ipv4_hdr hdr; /**< IPv4 header definition. */
530 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV4. */
532 static const struct rte_flow_item_ipv4 rte_flow_item_ipv4_mask = {
534 .src_addr = RTE_BE32(0xffffffff),
535 .dst_addr = RTE_BE32(0xffffffff),
541 * RTE_FLOW_ITEM_TYPE_IPV6.
543 * Matches an IPv6 header.
545 * Note: IPv6 options are handled by dedicated pattern items.
547 struct rte_flow_item_ipv6 {
548 struct ipv6_hdr hdr; /**< IPv6 header definition. */
551 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV6. */
553 static const struct rte_flow_item_ipv6 rte_flow_item_ipv6_mask = {
556 "\xff\xff\xff\xff\xff\xff\xff\xff"
557 "\xff\xff\xff\xff\xff\xff\xff\xff",
559 "\xff\xff\xff\xff\xff\xff\xff\xff"
560 "\xff\xff\xff\xff\xff\xff\xff\xff",
566 * RTE_FLOW_ITEM_TYPE_ICMP.
568 * Matches an ICMP header.
570 struct rte_flow_item_icmp {
571 struct icmp_hdr hdr; /**< ICMP header definition. */
574 /** Default mask for RTE_FLOW_ITEM_TYPE_ICMP. */
576 static const struct rte_flow_item_icmp rte_flow_item_icmp_mask = {
585 * RTE_FLOW_ITEM_TYPE_UDP.
587 * Matches a UDP header.
589 struct rte_flow_item_udp {
590 struct udp_hdr hdr; /**< UDP header definition. */
593 /** Default mask for RTE_FLOW_ITEM_TYPE_UDP. */
595 static const struct rte_flow_item_udp rte_flow_item_udp_mask = {
597 .src_port = RTE_BE16(0xffff),
598 .dst_port = RTE_BE16(0xffff),
604 * RTE_FLOW_ITEM_TYPE_TCP.
606 * Matches a TCP header.
608 struct rte_flow_item_tcp {
609 struct tcp_hdr hdr; /**< TCP header definition. */
612 /** Default mask for RTE_FLOW_ITEM_TYPE_TCP. */
614 static const struct rte_flow_item_tcp rte_flow_item_tcp_mask = {
616 .src_port = RTE_BE16(0xffff),
617 .dst_port = RTE_BE16(0xffff),
623 * RTE_FLOW_ITEM_TYPE_SCTP.
625 * Matches a SCTP header.
627 struct rte_flow_item_sctp {
628 struct sctp_hdr hdr; /**< SCTP header definition. */
631 /** Default mask for RTE_FLOW_ITEM_TYPE_SCTP. */
633 static const struct rte_flow_item_sctp rte_flow_item_sctp_mask = {
635 .src_port = RTE_BE16(0xffff),
636 .dst_port = RTE_BE16(0xffff),
642 * RTE_FLOW_ITEM_TYPE_VXLAN.
644 * Matches a VXLAN header (RFC 7348).
646 struct rte_flow_item_vxlan {
647 uint8_t flags; /**< Normally 0x08 (I flag). */
648 uint8_t rsvd0[3]; /**< Reserved, normally 0x000000. */
649 uint8_t vni[3]; /**< VXLAN identifier. */
650 uint8_t rsvd1; /**< Reserved, normally 0x00. */
653 /** Default mask for RTE_FLOW_ITEM_TYPE_VXLAN. */
655 static const struct rte_flow_item_vxlan rte_flow_item_vxlan_mask = {
656 .vni = "\xff\xff\xff",
661 * RTE_FLOW_ITEM_TYPE_E_TAG.
663 * Matches a E-tag header.
665 struct rte_flow_item_e_tag {
666 rte_be16_t tpid; /**< Tag protocol identifier (0x893F). */
668 * E-Tag control information (E-TCI).
669 * E-PCP (3b), E-DEI (1b), ingress E-CID base (12b).
671 rte_be16_t epcp_edei_in_ecid_b;
672 /** Reserved (2b), GRP (2b), E-CID base (12b). */
673 rte_be16_t rsvd_grp_ecid_b;
674 uint8_t in_ecid_e; /**< Ingress E-CID ext. */
675 uint8_t ecid_e; /**< E-CID ext. */
678 /** Default mask for RTE_FLOW_ITEM_TYPE_E_TAG. */
680 static const struct rte_flow_item_e_tag rte_flow_item_e_tag_mask = {
681 .rsvd_grp_ecid_b = RTE_BE16(0x3fff),
686 * RTE_FLOW_ITEM_TYPE_NVGRE.
688 * Matches a NVGRE header.
690 struct rte_flow_item_nvgre {
692 * Checksum (1b), undefined (1b), key bit (1b), sequence number (1b),
693 * reserved 0 (9b), version (3b).
695 * c_k_s_rsvd0_ver must have value 0x2000 according to RFC 7637.
697 rte_be16_t c_k_s_rsvd0_ver;
698 rte_be16_t protocol; /**< Protocol type (0x6558). */
699 uint8_t tni[3]; /**< Virtual subnet ID. */
700 uint8_t flow_id; /**< Flow ID. */
703 /** Default mask for RTE_FLOW_ITEM_TYPE_NVGRE. */
705 static const struct rte_flow_item_nvgre rte_flow_item_nvgre_mask = {
706 .tni = "\xff\xff\xff",
711 * RTE_FLOW_ITEM_TYPE_MPLS.
713 * Matches a MPLS header.
715 struct rte_flow_item_mpls {
717 * Label (20b), TC (3b), Bottom of Stack (1b).
719 uint8_t label_tc_s[3];
720 uint8_t ttl; /** Time-to-Live. */
723 /** Default mask for RTE_FLOW_ITEM_TYPE_MPLS. */
725 static const struct rte_flow_item_mpls rte_flow_item_mpls_mask = {
726 .label_tc_s = "\xff\xff\xf0",
731 * RTE_FLOW_ITEM_TYPE_GRE.
733 * Matches a GRE header.
735 struct rte_flow_item_gre {
737 * Checksum (1b), reserved 0 (12b), version (3b).
740 rte_be16_t c_rsvd0_ver;
741 rte_be16_t protocol; /**< Protocol type. */
744 /** Default mask for RTE_FLOW_ITEM_TYPE_GRE. */
746 static const struct rte_flow_item_gre rte_flow_item_gre_mask = {
747 .protocol = RTE_BE16(0xffff),
752 * RTE_FLOW_ITEM_TYPE_FUZZY
754 * Fuzzy pattern match, expect faster than default.
756 * This is for device that support fuzzy match option.
757 * Usually a fuzzy match is fast but the cost is accuracy.
758 * i.e. Signature Match only match pattern's hash value, but it is
759 * possible two different patterns have the same hash value.
761 * Matching accuracy level can be configure by threshold.
762 * Driver can divide the range of threshold and map to different
763 * accuracy levels that device support.
765 * Threshold 0 means perfect match (no fuzziness), while threshold
766 * 0xffffffff means fuzziest match.
768 struct rte_flow_item_fuzzy {
769 uint32_t thresh; /**< Accuracy threshold. */
772 /** Default mask for RTE_FLOW_ITEM_TYPE_FUZZY. */
774 static const struct rte_flow_item_fuzzy rte_flow_item_fuzzy_mask = {
775 .thresh = 0xffffffff,
780 * RTE_FLOW_ITEM_TYPE_GTP.
782 * Matches a GTPv1 header.
784 struct rte_flow_item_gtp {
786 * Version (3b), protocol type (1b), reserved (1b),
787 * Extension header flag (1b),
788 * Sequence number flag (1b),
789 * N-PDU number flag (1b).
791 uint8_t v_pt_rsv_flags;
792 uint8_t msg_type; /**< Message type. */
793 rte_be16_t msg_len; /**< Message length. */
794 rte_be32_t teid; /**< Tunnel endpoint identifier. */
797 /** Default mask for RTE_FLOW_ITEM_TYPE_GTP. */
799 static const struct rte_flow_item_gtp rte_flow_item_gtp_mask = {
800 .teid = RTE_BE32(0xffffffff),
805 * RTE_FLOW_ITEM_TYPE_ESP
807 * Matches an ESP header.
809 struct rte_flow_item_esp {
810 struct esp_hdr hdr; /**< ESP header definition. */
813 /** Default mask for RTE_FLOW_ITEM_TYPE_ESP. */
815 static const struct rte_flow_item_esp rte_flow_item_esp_mask = {
823 * RTE_FLOW_ITEM_TYPE_GENEVE.
825 * Matches a GENEVE header.
827 struct rte_flow_item_geneve {
829 * Version (2b), length of the options fields (6b), OAM packet (1b),
830 * critical options present (1b), reserved 0 (6b).
832 rte_be16_t ver_opt_len_o_c_rsvd0;
833 rte_be16_t protocol; /**< Protocol type. */
834 uint8_t vni[3]; /**< Virtual Network Identifier. */
835 uint8_t rsvd1; /**< Reserved, normally 0x00. */
838 /** Default mask for RTE_FLOW_ITEM_TYPE_GENEVE. */
840 static const struct rte_flow_item_geneve rte_flow_item_geneve_mask = {
841 .vni = "\xff\xff\xff",
846 * Matching pattern item definition.
848 * A pattern is formed by stacking items starting from the lowest protocol
849 * layer to match. This stacking restriction does not apply to meta items
850 * which can be placed anywhere in the stack without affecting the meaning
851 * of the resulting pattern.
853 * Patterns are terminated by END items.
855 * The spec field should be a valid pointer to a structure of the related
856 * item type. It may remain unspecified (NULL) in many cases to request
857 * broad (nonspecific) matching. In such cases, last and mask must also be
860 * Optionally, last can point to a structure of the same type to define an
861 * inclusive range. This is mostly supported by integer and address fields,
862 * may cause errors otherwise. Fields that do not support ranges must be set
863 * to 0 or to the same value as the corresponding fields in spec.
865 * Only the fields defined to nonzero values in the default masks (see
866 * rte_flow_item_{name}_mask constants) are considered relevant by
867 * default. This can be overridden by providing a mask structure of the
868 * same type with applicable bits set to one. It can also be used to
869 * partially filter out specific fields (e.g. as an alternate mean to match
870 * ranges of IP addresses).
872 * Mask is a simple bit-mask applied before interpreting the contents of
873 * spec and last, which may yield unexpected results if not used
874 * carefully. For example, if for an IPv4 address field, spec provides
875 * 10.1.2.3, last provides 10.3.4.5 and mask provides 255.255.0.0, the
876 * effective range becomes 10.1.0.0 to 10.3.255.255.
878 struct rte_flow_item {
879 enum rte_flow_item_type type; /**< Item type. */
880 const void *spec; /**< Pointer to item specification structure. */
881 const void *last; /**< Defines an inclusive range (spec to last). */
882 const void *mask; /**< Bit-mask applied to spec and last. */
888 * Each possible action is represented by a type. Some have associated
889 * configuration structures. Several actions combined in a list can be
890 * affected to a flow rule. That list is not ordered.
892 * They fall in three categories:
894 * - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
895 * processing matched packets by subsequent flow rules, unless overridden
898 * - Non terminating actions (PASSTHRU, DUP) that leave matched packets up
899 * for additional processing by subsequent flow rules.
901 * - Other non terminating meta actions that do not affect the fate of
902 * packets (END, VOID, MARK, FLAG, COUNT).
904 * When several actions are combined in a flow rule, they should all have
905 * different types (e.g. dropping a packet twice is not possible).
907 * Only the last action of a given type is taken into account. PMDs still
908 * perform error checking on the entire list.
910 * Note that PASSTHRU is the only action able to override a terminating
913 enum rte_flow_action_type {
917 * End marker for action lists. Prevents further processing of
918 * actions, thereby ending the list.
920 * No associated configuration structure.
922 RTE_FLOW_ACTION_TYPE_END,
927 * Used as a placeholder for convenience. It is ignored and simply
930 * No associated configuration structure.
932 RTE_FLOW_ACTION_TYPE_VOID,
935 * Leaves packets up for additional processing by subsequent flow
936 * rules. This is the default when a rule does not contain a
937 * terminating action, but can be specified to force a rule to
938 * become non-terminating.
940 * No associated configuration structure.
942 RTE_FLOW_ACTION_TYPE_PASSTHRU,
947 * Attaches an integer value to packets and sets PKT_RX_FDIR and
948 * PKT_RX_FDIR_ID mbuf flags.
950 * See struct rte_flow_action_mark.
952 RTE_FLOW_ACTION_TYPE_MARK,
957 * Flags packets. Similar to MARK without a specific value; only
958 * sets the PKT_RX_FDIR mbuf flag.
960 * No associated configuration structure.
962 RTE_FLOW_ACTION_TYPE_FLAG,
965 * Assigns packets to a given queue index.
967 * See struct rte_flow_action_queue.
969 RTE_FLOW_ACTION_TYPE_QUEUE,
974 * PASSTHRU overrides this action if both are specified.
976 * No associated configuration structure.
978 RTE_FLOW_ACTION_TYPE_DROP,
983 * Enables counters for this rule.
985 * These counters can be retrieved and reset through rte_flow_query(),
986 * see struct rte_flow_query_count.
988 * No associated configuration structure.
990 RTE_FLOW_ACTION_TYPE_COUNT,
993 * Duplicates packets to a given queue index.
995 * This is normally combined with QUEUE, however when used alone, it
996 * is actually similar to QUEUE + PASSTHRU.
998 * See struct rte_flow_action_dup.
1000 RTE_FLOW_ACTION_TYPE_DUP,
1003 * Similar to QUEUE, except RSS is additionally performed on packets
1004 * to spread them among several queues according to the provided
1007 * See struct rte_flow_action_rss.
1009 RTE_FLOW_ACTION_TYPE_RSS,
1012 * Redirects packets to the physical function (PF) of the current
1015 * No associated configuration structure.
1017 RTE_FLOW_ACTION_TYPE_PF,
1020 * Redirects packets to the virtual function (VF) of the current
1021 * device with the specified ID.
1023 * See struct rte_flow_action_vf.
1025 RTE_FLOW_ACTION_TYPE_VF,
1028 * Traffic metering and policing (MTR).
1030 * See struct rte_flow_action_meter.
1031 * See file rte_mtr.h for MTR object configuration.
1033 RTE_FLOW_ACTION_TYPE_METER,
1036 * Redirects packets to security engine of current device for security
1037 * processing as specified by security session.
1039 * See struct rte_flow_action_security.
1041 RTE_FLOW_ACTION_TYPE_SECURITY
1045 * RTE_FLOW_ACTION_TYPE_MARK
1047 * Attaches an integer value to packets and sets PKT_RX_FDIR and
1048 * PKT_RX_FDIR_ID mbuf flags.
1050 * This value is arbitrary and application-defined. Maximum allowed value
1051 * depends on the underlying implementation. It is returned in the
1052 * hash.fdir.hi mbuf field.
1054 struct rte_flow_action_mark {
1055 uint32_t id; /**< Integer value to return with packets. */
1059 * RTE_FLOW_ACTION_TYPE_QUEUE
1061 * Assign packets to a given queue index.
1063 * Terminating by default.
1065 struct rte_flow_action_queue {
1066 uint16_t index; /**< Queue index to use. */
1070 * RTE_FLOW_ACTION_TYPE_COUNT (query)
1072 * Query structure to retrieve and reset flow rule counters.
1074 struct rte_flow_query_count {
1075 uint32_t reset:1; /**< Reset counters after query [in]. */
1076 uint32_t hits_set:1; /**< hits field is set [out]. */
1077 uint32_t bytes_set:1; /**< bytes field is set [out]. */
1078 uint32_t reserved:29; /**< Reserved, must be zero [in, out]. */
1079 uint64_t hits; /**< Number of hits for this rule [out]. */
1080 uint64_t bytes; /**< Number of bytes through this rule [out]. */
1084 * RTE_FLOW_ACTION_TYPE_DUP
1086 * Duplicates packets to a given queue index.
1088 * This is normally combined with QUEUE, however when used alone, it is
1089 * actually similar to QUEUE + PASSTHRU.
1091 * Non-terminating by default.
1093 struct rte_flow_action_dup {
1094 uint16_t index; /**< Queue index to duplicate packets to. */
1098 * RTE_FLOW_ACTION_TYPE_RSS
1100 * Similar to QUEUE, except RSS is additionally performed on packets to
1101 * spread them among several queues according to the provided parameters.
1103 * Note: RSS hash result is stored in the hash.rss mbuf field which overlaps
1104 * hash.fdir.lo. Since the MARK action sets the hash.fdir.hi field only,
1105 * both can be requested simultaneously.
1107 * Terminating by default.
1109 struct rte_flow_action_rss {
1110 const struct rte_eth_rss_conf *rss_conf; /**< RSS parameters. */
1111 uint16_t num; /**< Number of entries in queue[]. */
1112 uint16_t queue[]; /**< Queues indices to use. */
1116 * RTE_FLOW_ACTION_TYPE_VF
1118 * Redirects packets to a virtual function (VF) of the current device.
1120 * Packets matched by a VF pattern item can be redirected to their original
1121 * VF ID instead of the specified one. This parameter may not be available
1122 * and is not guaranteed to work properly if the VF part is matched by a
1123 * prior flow rule or if packets are not addressed to a VF in the first
1126 * Terminating by default.
1128 struct rte_flow_action_vf {
1129 uint32_t original:1; /**< Use original VF ID if possible. */
1130 uint32_t reserved:31; /**< Reserved, must be zero. */
1131 uint32_t id; /**< VF ID to redirect packets to. */
1135 * RTE_FLOW_ACTION_TYPE_METER
1137 * Traffic metering and policing (MTR).
1139 * Packets matched by items of this type can be either dropped or passed to the
1140 * next item with their color set by the MTR object.
1142 * Non-terminating by default.
1144 struct rte_flow_action_meter {
1145 uint32_t mtr_id; /**< MTR object ID created with rte_mtr_create(). */
1149 * RTE_FLOW_ACTION_TYPE_SECURITY
1151 * Perform the security action on flows matched by the pattern items
1152 * according to the configuration of the security session.
1154 * This action modifies the payload of matched flows. For INLINE_CRYPTO, the
1155 * security protocol headers and IV are fully provided by the application as
1156 * specified in the flow pattern. The payload of matching packets is
1157 * encrypted on egress, and decrypted and authenticated on ingress.
1158 * For INLINE_PROTOCOL, the security protocol is fully offloaded to HW,
1159 * providing full encapsulation and decapsulation of packets in security
1160 * protocols. The flow pattern specifies both the outer security header fields
1161 * and the inner packet fields. The security session specified in the action
1162 * must match the pattern parameters.
1164 * The security session specified in the action must be created on the same
1165 * port as the flow action that is being specified.
1167 * The ingress/egress flow attribute should match that specified in the
1168 * security session if the security session supports the definition of the
1171 * Multiple flows can be configured to use the same security session.
1173 * Non-terminating by default.
1175 struct rte_flow_action_security {
1176 void *security_session; /**< Pointer to security session structure. */
1180 * Definition of a single action.
1182 * A list of actions is terminated by a END action.
1184 * For simple actions without a configuration structure, conf remains NULL.
1186 struct rte_flow_action {
1187 enum rte_flow_action_type type; /**< Action type. */
1188 const void *conf; /**< Pointer to action configuration structure. */
1192 * Opaque type returned after successfully creating a flow.
1194 * This handle can be used to manage and query the related flow (e.g. to
1195 * destroy it or retrieve counters).
1200 * Verbose error types.
1202 * Most of them provide the type of the object referenced by struct
1203 * rte_flow_error.cause.
1205 enum rte_flow_error_type {
1206 RTE_FLOW_ERROR_TYPE_NONE, /**< No error. */
1207 RTE_FLOW_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
1208 RTE_FLOW_ERROR_TYPE_HANDLE, /**< Flow rule (handle). */
1209 RTE_FLOW_ERROR_TYPE_ATTR_GROUP, /**< Group field. */
1210 RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */
1211 RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */
1212 RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */
1213 RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */
1214 RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */
1215 RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */
1216 RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */
1217 RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */
1221 * Verbose error structure definition.
1223 * This object is normally allocated by applications and set by PMDs, the
1224 * message points to a constant string which does not need to be freed by
1225 * the application, however its pointer can be considered valid only as long
1226 * as its associated DPDK port remains configured. Closing the underlying
1227 * device or unloading the PMD invalidates it.
1229 * Both cause and message may be NULL regardless of the error type.
1231 struct rte_flow_error {
1232 enum rte_flow_error_type type; /**< Cause field and error types. */
1233 const void *cause; /**< Object responsible for the error. */
1234 const char *message; /**< Human-readable error message. */
1238 * Check whether a flow rule can be created on a given port.
1240 * The flow rule is validated for correctness and whether it could be accepted
1241 * by the device given sufficient resources. The rule is checked against the
1242 * current device mode and queue configuration. The flow rule may also
1243 * optionally be validated against existing flow rules and device resources.
1244 * This function has no effect on the target device.
1246 * The returned value is guaranteed to remain valid only as long as no
1247 * successful calls to rte_flow_create() or rte_flow_destroy() are made in
1248 * the meantime and no device parameter affecting flow rules in any way are
1249 * modified, due to possible collisions or resource limitations (although in
1250 * such cases EINVAL should not be returned).
1253 * Port identifier of Ethernet device.
1255 * Flow rule attributes.
1256 * @param[in] pattern
1257 * Pattern specification (list terminated by the END pattern item).
1258 * @param[in] actions
1259 * Associated actions (list terminated by the END action).
1261 * Perform verbose error reporting if not NULL. PMDs initialize this
1262 * structure in case of error only.
1265 * 0 if flow rule is valid and can be created. A negative errno value
1266 * otherwise (rte_errno is also set), the following errors are defined:
1268 * -ENOSYS: underlying device does not support this functionality.
1270 * -EIO: underlying device is removed.
1272 * -EINVAL: unknown or invalid rule specification.
1274 * -ENOTSUP: valid but unsupported rule specification (e.g. partial
1275 * bit-masks are unsupported).
1277 * -EEXIST: collision with an existing rule. Only returned if device
1278 * supports flow rule collision checking and there was a flow rule
1279 * collision. Not receiving this return code is no guarantee that creating
1280 * the rule will not fail due to a collision.
1282 * -ENOMEM: not enough memory to execute the function, or if the device
1283 * supports resource validation, resource limitation on the device.
1285 * -EBUSY: action cannot be performed due to busy device resources, may
1286 * succeed if the affected queues or even the entire port are in a stopped
1287 * state (see rte_eth_dev_rx_queue_stop() and rte_eth_dev_stop()).
1290 rte_flow_validate(uint16_t port_id,
1291 const struct rte_flow_attr *attr,
1292 const struct rte_flow_item pattern[],
1293 const struct rte_flow_action actions[],
1294 struct rte_flow_error *error);
1297 * Create a flow rule on a given port.
1300 * Port identifier of Ethernet device.
1302 * Flow rule attributes.
1303 * @param[in] pattern
1304 * Pattern specification (list terminated by the END pattern item).
1305 * @param[in] actions
1306 * Associated actions (list terminated by the END action).
1308 * Perform verbose error reporting if not NULL. PMDs initialize this
1309 * structure in case of error only.
1312 * A valid handle in case of success, NULL otherwise and rte_errno is set
1313 * to the positive version of one of the error codes defined for
1314 * rte_flow_validate().
1317 rte_flow_create(uint16_t port_id,
1318 const struct rte_flow_attr *attr,
1319 const struct rte_flow_item pattern[],
1320 const struct rte_flow_action actions[],
1321 struct rte_flow_error *error);
1324 * Destroy a flow rule on a given port.
1326 * Failure to destroy a flow rule handle may occur when other flow rules
1327 * depend on it, and destroying it would result in an inconsistent state.
1329 * This function is only guaranteed to succeed if handles are destroyed in
1330 * reverse order of their creation.
1333 * Port identifier of Ethernet device.
1335 * Flow rule handle to destroy.
1337 * Perform verbose error reporting if not NULL. PMDs initialize this
1338 * structure in case of error only.
1341 * 0 on success, a negative errno value otherwise and rte_errno is set.
1344 rte_flow_destroy(uint16_t port_id,
1345 struct rte_flow *flow,
1346 struct rte_flow_error *error);
1349 * Destroy all flow rules associated with a port.
1351 * In the unlikely event of failure, handles are still considered destroyed
1352 * and no longer valid but the port must be assumed to be in an inconsistent
1356 * Port identifier of Ethernet device.
1358 * Perform verbose error reporting if not NULL. PMDs initialize this
1359 * structure in case of error only.
1362 * 0 on success, a negative errno value otherwise and rte_errno is set.
1365 rte_flow_flush(uint16_t port_id,
1366 struct rte_flow_error *error);
1369 * Query an existing flow rule.
1371 * This function allows retrieving flow-specific data such as counters.
1372 * Data is gathered by special actions which must be present in the flow
1375 * \see RTE_FLOW_ACTION_TYPE_COUNT
1378 * Port identifier of Ethernet device.
1380 * Flow rule handle to query.
1382 * Action type to query.
1383 * @param[in, out] data
1384 * Pointer to storage for the associated query data type.
1386 * Perform verbose error reporting if not NULL. PMDs initialize this
1387 * structure in case of error only.
1390 * 0 on success, a negative errno value otherwise and rte_errno is set.
1393 rte_flow_query(uint16_t port_id,
1394 struct rte_flow *flow,
1395 enum rte_flow_action_type action,
1397 struct rte_flow_error *error);
1400 * Restrict ingress traffic to the defined flow rules.
1402 * Isolated mode guarantees that all ingress traffic comes from defined flow
1403 * rules only (current and future).
1405 * Besides making ingress more deterministic, it allows PMDs to safely reuse
1406 * resources otherwise assigned to handle the remaining traffic, such as
1407 * global RSS configuration settings, VLAN filters, MAC address entries,
1408 * legacy filter API rules and so on in order to expand the set of possible
1411 * Calling this function as soon as possible after device initialization,
1412 * ideally before the first call to rte_eth_dev_configure(), is recommended
1413 * to avoid possible failures due to conflicting settings.
1415 * Once effective, leaving isolated mode may not be possible depending on
1416 * PMD implementation.
1418 * Additionally, the following functionality has no effect on the underlying
1419 * port and may return errors such as ENOTSUP ("not supported"):
1421 * - Toggling promiscuous mode.
1422 * - Toggling allmulticast mode.
1423 * - Configuring MAC addresses.
1424 * - Configuring multicast addresses.
1425 * - Configuring VLAN filters.
1426 * - Configuring Rx filters through the legacy API (e.g. FDIR).
1427 * - Configuring global RSS settings.
1430 * Port identifier of Ethernet device.
1432 * Nonzero to enter isolated mode, attempt to leave it otherwise.
1434 * Perform verbose error reporting if not NULL. PMDs initialize this
1435 * structure in case of error only.
1438 * 0 on success, a negative errno value otherwise and rte_errno is set.
1441 rte_flow_isolate(uint16_t port_id, int set, struct rte_flow_error *error);
1444 * Initialize flow error structure.
1447 * Pointer to flow error structure (may be NULL).
1449 * Related error code (rte_errno).
1451 * Cause field and error types.
1453 * Object responsible for the error.
1455 * Human-readable error message.
1458 * Negative error code (errno value) and rte_errno is set.
1461 rte_flow_error_set(struct rte_flow_error *error,
1463 enum rte_flow_error_type type,
1465 const char *message);
1468 * Generic flow representation.
1470 * This form is sufficient to describe an rte_flow independently from any
1471 * PMD implementation and allows for replayability and identification.
1473 struct rte_flow_desc {
1474 size_t size; /**< Allocated space including data[]. */
1475 struct rte_flow_attr attr; /**< Attributes. */
1476 struct rte_flow_item *items; /**< Items. */
1477 struct rte_flow_action *actions; /**< Actions. */
1478 uint8_t data[]; /**< Storage for items/actions. */
1482 * Copy an rte_flow rule description.
1485 * Flow rule description.
1487 * Total size of allocated data for the flow description.
1489 * Flow rule attributes.
1491 * Pattern specification (list terminated by the END pattern item).
1492 * @param[in] actions
1493 * Associated actions (list terminated by the END action).
1496 * If len is greater or equal to the size of the flow, the total size of the
1497 * flow description and its data.
1498 * If len is lower than the size of the flow, the number of bytes that would
1499 * have been written to desc had it been sufficient. Nothing is written.
1502 rte_flow_copy(struct rte_flow_desc *fd, size_t len,
1503 const struct rte_flow_attr *attr,
1504 const struct rte_flow_item *items,
1505 const struct rte_flow_action *actions);
1511 #endif /* RTE_FLOW_H_ */