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,
350 * RTE_FLOW_ITEM_TYPE_ANY
352 * Matches any protocol in place of the current layer, a single ANY may also
353 * stand for several protocol layers.
355 * This is usually specified as the first pattern item when looking for a
356 * protocol anywhere in a packet.
358 * A zeroed mask stands for any number of layers.
360 struct rte_flow_item_any {
361 uint32_t num; /**< Number of layers covered. */
364 /** Default mask for RTE_FLOW_ITEM_TYPE_ANY. */
366 static const struct rte_flow_item_any rte_flow_item_any_mask = {
372 * RTE_FLOW_ITEM_TYPE_VF
374 * Matches packets addressed to a virtual function ID of the device.
376 * If the underlying device function differs from the one that would
377 * normally receive the matched traffic, specifying this item prevents it
378 * from reaching that device unless the flow rule contains a VF
379 * action. Packets are not duplicated between device instances by default.
381 * - Likely to return an error or never match any traffic if this causes a
382 * VF device to match traffic addressed to a different VF.
383 * - Can be specified multiple times to match traffic addressed to several
385 * - Can be combined with a PF item to match both PF and VF traffic.
387 * A zeroed mask can be used to match any VF ID.
389 struct rte_flow_item_vf {
390 uint32_t id; /**< Destination VF ID. */
393 /** Default mask for RTE_FLOW_ITEM_TYPE_VF. */
395 static const struct rte_flow_item_vf rte_flow_item_vf_mask = {
401 * RTE_FLOW_ITEM_TYPE_PORT
403 * Matches packets coming from the specified physical port of the underlying
406 * The first PORT item overrides the physical port normally associated with
407 * the specified DPDK input port (port_id). This item can be provided
408 * several times to match additional physical ports.
410 * Note that physical ports are not necessarily tied to DPDK input ports
411 * (port_id) when those are not under DPDK control. Possible values are
412 * specific to each device, they are not necessarily indexed from zero and
413 * may not be contiguous.
415 * As a device property, the list of allowed values as well as the value
416 * associated with a port_id should be retrieved by other means.
418 * A zeroed mask can be used to match any port index.
420 struct rte_flow_item_port {
421 uint32_t index; /**< Physical port index. */
424 /** Default mask for RTE_FLOW_ITEM_TYPE_PORT. */
426 static const struct rte_flow_item_port rte_flow_item_port_mask = {
432 * RTE_FLOW_ITEM_TYPE_RAW
434 * Matches a byte string of a given length at a given offset.
436 * Offset is either absolute (using the start of the packet) or relative to
437 * the end of the previous matched item in the stack, in which case negative
438 * values are allowed.
440 * If search is enabled, offset is used as the starting point. The search
441 * area can be delimited by setting limit to a nonzero value, which is the
442 * maximum number of bytes after offset where the pattern may start.
444 * Matching a zero-length pattern is allowed, doing so resets the relative
445 * offset for subsequent items.
447 * This type does not support ranges (struct rte_flow_item.last).
449 struct rte_flow_item_raw {
450 uint32_t relative:1; /**< Look for pattern after the previous item. */
451 uint32_t search:1; /**< Search pattern from offset (see also limit). */
452 uint32_t reserved:30; /**< Reserved, must be set to zero. */
453 int32_t offset; /**< Absolute or relative offset for pattern. */
454 uint16_t limit; /**< Search area limit for start of pattern. */
455 uint16_t length; /**< Pattern length. */
456 uint8_t pattern[]; /**< Byte string to look for. */
459 /** Default mask for RTE_FLOW_ITEM_TYPE_RAW. */
461 static const struct rte_flow_item_raw rte_flow_item_raw_mask = {
464 .reserved = 0x3fffffff,
465 .offset = 0xffffffff,
472 * RTE_FLOW_ITEM_TYPE_ETH
474 * Matches an Ethernet header.
476 struct rte_flow_item_eth {
477 struct ether_addr dst; /**< Destination MAC. */
478 struct ether_addr src; /**< Source MAC. */
479 rte_be16_t type; /**< EtherType. */
482 /** Default mask for RTE_FLOW_ITEM_TYPE_ETH. */
484 static const struct rte_flow_item_eth rte_flow_item_eth_mask = {
485 .dst.addr_bytes = "\xff\xff\xff\xff\xff\xff",
486 .src.addr_bytes = "\xff\xff\xff\xff\xff\xff",
487 .type = RTE_BE16(0x0000),
492 * RTE_FLOW_ITEM_TYPE_VLAN
494 * Matches an 802.1Q/ad VLAN tag.
496 * This type normally follows either RTE_FLOW_ITEM_TYPE_ETH or
497 * RTE_FLOW_ITEM_TYPE_VLAN.
499 struct rte_flow_item_vlan {
500 rte_be16_t tpid; /**< Tag protocol identifier. */
501 rte_be16_t tci; /**< Tag control information. */
504 /** Default mask for RTE_FLOW_ITEM_TYPE_VLAN. */
506 static const struct rte_flow_item_vlan rte_flow_item_vlan_mask = {
507 .tpid = RTE_BE16(0x0000),
508 .tci = RTE_BE16(0xffff),
513 * RTE_FLOW_ITEM_TYPE_IPV4
515 * Matches an IPv4 header.
517 * Note: IPv4 options are handled by dedicated pattern items.
519 struct rte_flow_item_ipv4 {
520 struct ipv4_hdr hdr; /**< IPv4 header definition. */
523 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV4. */
525 static const struct rte_flow_item_ipv4 rte_flow_item_ipv4_mask = {
527 .src_addr = RTE_BE32(0xffffffff),
528 .dst_addr = RTE_BE32(0xffffffff),
534 * RTE_FLOW_ITEM_TYPE_IPV6.
536 * Matches an IPv6 header.
538 * Note: IPv6 options are handled by dedicated pattern items.
540 struct rte_flow_item_ipv6 {
541 struct ipv6_hdr hdr; /**< IPv6 header definition. */
544 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV6. */
546 static const struct rte_flow_item_ipv6 rte_flow_item_ipv6_mask = {
549 "\xff\xff\xff\xff\xff\xff\xff\xff"
550 "\xff\xff\xff\xff\xff\xff\xff\xff",
552 "\xff\xff\xff\xff\xff\xff\xff\xff"
553 "\xff\xff\xff\xff\xff\xff\xff\xff",
559 * RTE_FLOW_ITEM_TYPE_ICMP.
561 * Matches an ICMP header.
563 struct rte_flow_item_icmp {
564 struct icmp_hdr hdr; /**< ICMP header definition. */
567 /** Default mask for RTE_FLOW_ITEM_TYPE_ICMP. */
569 static const struct rte_flow_item_icmp rte_flow_item_icmp_mask = {
578 * RTE_FLOW_ITEM_TYPE_UDP.
580 * Matches a UDP header.
582 struct rte_flow_item_udp {
583 struct udp_hdr hdr; /**< UDP header definition. */
586 /** Default mask for RTE_FLOW_ITEM_TYPE_UDP. */
588 static const struct rte_flow_item_udp rte_flow_item_udp_mask = {
590 .src_port = RTE_BE16(0xffff),
591 .dst_port = RTE_BE16(0xffff),
597 * RTE_FLOW_ITEM_TYPE_TCP.
599 * Matches a TCP header.
601 struct rte_flow_item_tcp {
602 struct tcp_hdr hdr; /**< TCP header definition. */
605 /** Default mask for RTE_FLOW_ITEM_TYPE_TCP. */
607 static const struct rte_flow_item_tcp rte_flow_item_tcp_mask = {
609 .src_port = RTE_BE16(0xffff),
610 .dst_port = RTE_BE16(0xffff),
616 * RTE_FLOW_ITEM_TYPE_SCTP.
618 * Matches a SCTP header.
620 struct rte_flow_item_sctp {
621 struct sctp_hdr hdr; /**< SCTP header definition. */
624 /** Default mask for RTE_FLOW_ITEM_TYPE_SCTP. */
626 static const struct rte_flow_item_sctp rte_flow_item_sctp_mask = {
628 .src_port = RTE_BE16(0xffff),
629 .dst_port = RTE_BE16(0xffff),
635 * RTE_FLOW_ITEM_TYPE_VXLAN.
637 * Matches a VXLAN header (RFC 7348).
639 struct rte_flow_item_vxlan {
640 uint8_t flags; /**< Normally 0x08 (I flag). */
641 uint8_t rsvd0[3]; /**< Reserved, normally 0x000000. */
642 uint8_t vni[3]; /**< VXLAN identifier. */
643 uint8_t rsvd1; /**< Reserved, normally 0x00. */
646 /** Default mask for RTE_FLOW_ITEM_TYPE_VXLAN. */
648 static const struct rte_flow_item_vxlan rte_flow_item_vxlan_mask = {
649 .vni = "\xff\xff\xff",
654 * RTE_FLOW_ITEM_TYPE_E_TAG.
656 * Matches a E-tag header.
658 struct rte_flow_item_e_tag {
659 rte_be16_t tpid; /**< Tag protocol identifier (0x893F). */
661 * E-Tag control information (E-TCI).
662 * E-PCP (3b), E-DEI (1b), ingress E-CID base (12b).
664 rte_be16_t epcp_edei_in_ecid_b;
665 /** Reserved (2b), GRP (2b), E-CID base (12b). */
666 rte_be16_t rsvd_grp_ecid_b;
667 uint8_t in_ecid_e; /**< Ingress E-CID ext. */
668 uint8_t ecid_e; /**< E-CID ext. */
671 /** Default mask for RTE_FLOW_ITEM_TYPE_E_TAG. */
673 static const struct rte_flow_item_e_tag rte_flow_item_e_tag_mask = {
674 .rsvd_grp_ecid_b = RTE_BE16(0x3fff),
679 * RTE_FLOW_ITEM_TYPE_NVGRE.
681 * Matches a NVGRE header.
683 struct rte_flow_item_nvgre {
685 * Checksum (1b), undefined (1b), key bit (1b), sequence number (1b),
686 * reserved 0 (9b), version (3b).
688 * c_k_s_rsvd0_ver must have value 0x2000 according to RFC 7637.
690 rte_be16_t c_k_s_rsvd0_ver;
691 rte_be16_t protocol; /**< Protocol type (0x6558). */
692 uint8_t tni[3]; /**< Virtual subnet ID. */
693 uint8_t flow_id; /**< Flow ID. */
696 /** Default mask for RTE_FLOW_ITEM_TYPE_NVGRE. */
698 static const struct rte_flow_item_nvgre rte_flow_item_nvgre_mask = {
699 .tni = "\xff\xff\xff",
704 * RTE_FLOW_ITEM_TYPE_MPLS.
706 * Matches a MPLS header.
708 struct rte_flow_item_mpls {
710 * Label (20b), TC (3b), Bottom of Stack (1b).
712 uint8_t label_tc_s[3];
713 uint8_t ttl; /** Time-to-Live. */
716 /** Default mask for RTE_FLOW_ITEM_TYPE_MPLS. */
718 static const struct rte_flow_item_mpls rte_flow_item_mpls_mask = {
719 .label_tc_s = "\xff\xff\xf0",
724 * RTE_FLOW_ITEM_TYPE_GRE.
726 * Matches a GRE header.
728 struct rte_flow_item_gre {
730 * Checksum (1b), reserved 0 (12b), version (3b).
733 rte_be16_t c_rsvd0_ver;
734 rte_be16_t protocol; /**< Protocol type. */
737 /** Default mask for RTE_FLOW_ITEM_TYPE_GRE. */
739 static const struct rte_flow_item_gre rte_flow_item_gre_mask = {
740 .protocol = RTE_BE16(0xffff),
745 * RTE_FLOW_ITEM_TYPE_FUZZY
747 * Fuzzy pattern match, expect faster than default.
749 * This is for device that support fuzzy match option.
750 * Usually a fuzzy match is fast but the cost is accuracy.
751 * i.e. Signature Match only match pattern's hash value, but it is
752 * possible two different patterns have the same hash value.
754 * Matching accuracy level can be configure by threshold.
755 * Driver can divide the range of threshold and map to different
756 * accuracy levels that device support.
758 * Threshold 0 means perfect match (no fuzziness), while threshold
759 * 0xffffffff means fuzziest match.
761 struct rte_flow_item_fuzzy {
762 uint32_t thresh; /**< Accuracy threshold. */
765 /** Default mask for RTE_FLOW_ITEM_TYPE_FUZZY. */
767 static const struct rte_flow_item_fuzzy rte_flow_item_fuzzy_mask = {
768 .thresh = 0xffffffff,
773 * RTE_FLOW_ITEM_TYPE_GTP.
775 * Matches a GTPv1 header.
777 struct rte_flow_item_gtp {
779 * Version (3b), protocol type (1b), reserved (1b),
780 * Extension header flag (1b),
781 * Sequence number flag (1b),
782 * N-PDU number flag (1b).
784 uint8_t v_pt_rsv_flags;
785 uint8_t msg_type; /**< Message type. */
786 rte_be16_t msg_len; /**< Message length. */
787 rte_be32_t teid; /**< Tunnel endpoint identifier. */
790 /** Default mask for RTE_FLOW_ITEM_TYPE_GTP. */
792 static const struct rte_flow_item_gtp rte_flow_item_gtp_mask = {
793 .teid = RTE_BE32(0xffffffff),
798 * RTE_FLOW_ITEM_TYPE_ESP
800 * Matches an ESP header.
802 struct rte_flow_item_esp {
803 struct esp_hdr hdr; /**< ESP header definition. */
806 /** Default mask for RTE_FLOW_ITEM_TYPE_ESP. */
808 static const struct rte_flow_item_esp rte_flow_item_esp_mask = {
816 * Matching pattern item definition.
818 * A pattern is formed by stacking items starting from the lowest protocol
819 * layer to match. This stacking restriction does not apply to meta items
820 * which can be placed anywhere in the stack without affecting the meaning
821 * of the resulting pattern.
823 * Patterns are terminated by END items.
825 * The spec field should be a valid pointer to a structure of the related
826 * item type. It may remain unspecified (NULL) in many cases to request
827 * broad (nonspecific) matching. In such cases, last and mask must also be
830 * Optionally, last can point to a structure of the same type to define an
831 * inclusive range. This is mostly supported by integer and address fields,
832 * may cause errors otherwise. Fields that do not support ranges must be set
833 * to 0 or to the same value as the corresponding fields in spec.
835 * Only the fields defined to nonzero values in the default masks (see
836 * rte_flow_item_{name}_mask constants) are considered relevant by
837 * default. This can be overridden by providing a mask structure of the
838 * same type with applicable bits set to one. It can also be used to
839 * partially filter out specific fields (e.g. as an alternate mean to match
840 * ranges of IP addresses).
842 * Mask is a simple bit-mask applied before interpreting the contents of
843 * spec and last, which may yield unexpected results if not used
844 * carefully. For example, if for an IPv4 address field, spec provides
845 * 10.1.2.3, last provides 10.3.4.5 and mask provides 255.255.0.0, the
846 * effective range becomes 10.1.0.0 to 10.3.255.255.
848 struct rte_flow_item {
849 enum rte_flow_item_type type; /**< Item type. */
850 const void *spec; /**< Pointer to item specification structure. */
851 const void *last; /**< Defines an inclusive range (spec to last). */
852 const void *mask; /**< Bit-mask applied to spec and last. */
858 * Each possible action is represented by a type. Some have associated
859 * configuration structures. Several actions combined in a list can be
860 * affected to a flow rule. That list is not ordered.
862 * They fall in three categories:
864 * - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
865 * processing matched packets by subsequent flow rules, unless overridden
868 * - Non terminating actions (PASSTHRU, DUP) that leave matched packets up
869 * for additional processing by subsequent flow rules.
871 * - Other non terminating meta actions that do not affect the fate of
872 * packets (END, VOID, MARK, FLAG, COUNT).
874 * When several actions are combined in a flow rule, they should all have
875 * different types (e.g. dropping a packet twice is not possible).
877 * Only the last action of a given type is taken into account. PMDs still
878 * perform error checking on the entire list.
880 * Note that PASSTHRU is the only action able to override a terminating
883 enum rte_flow_action_type {
887 * End marker for action lists. Prevents further processing of
888 * actions, thereby ending the list.
890 * No associated configuration structure.
892 RTE_FLOW_ACTION_TYPE_END,
897 * Used as a placeholder for convenience. It is ignored and simply
900 * No associated configuration structure.
902 RTE_FLOW_ACTION_TYPE_VOID,
905 * Leaves packets up for additional processing by subsequent flow
906 * rules. This is the default when a rule does not contain a
907 * terminating action, but can be specified to force a rule to
908 * become non-terminating.
910 * No associated configuration structure.
912 RTE_FLOW_ACTION_TYPE_PASSTHRU,
917 * Attaches an integer value to packets and sets PKT_RX_FDIR and
918 * PKT_RX_FDIR_ID mbuf flags.
920 * See struct rte_flow_action_mark.
922 RTE_FLOW_ACTION_TYPE_MARK,
927 * Flags packets. Similar to MARK without a specific value; only
928 * sets the PKT_RX_FDIR mbuf flag.
930 * No associated configuration structure.
932 RTE_FLOW_ACTION_TYPE_FLAG,
935 * Assigns packets to a given queue index.
937 * See struct rte_flow_action_queue.
939 RTE_FLOW_ACTION_TYPE_QUEUE,
944 * PASSTHRU overrides this action if both are specified.
946 * No associated configuration structure.
948 RTE_FLOW_ACTION_TYPE_DROP,
953 * Enables counters for this rule.
955 * These counters can be retrieved and reset through rte_flow_query(),
956 * see struct rte_flow_query_count.
958 * No associated configuration structure.
960 RTE_FLOW_ACTION_TYPE_COUNT,
963 * Duplicates packets to a given queue index.
965 * This is normally combined with QUEUE, however when used alone, it
966 * is actually similar to QUEUE + PASSTHRU.
968 * See struct rte_flow_action_dup.
970 RTE_FLOW_ACTION_TYPE_DUP,
973 * Similar to QUEUE, except RSS is additionally performed on packets
974 * to spread them among several queues according to the provided
977 * See struct rte_flow_action_rss.
979 RTE_FLOW_ACTION_TYPE_RSS,
982 * Redirects packets to the physical function (PF) of the current
985 * No associated configuration structure.
987 RTE_FLOW_ACTION_TYPE_PF,
990 * Redirects packets to the virtual function (VF) of the current
991 * device with the specified ID.
993 * See struct rte_flow_action_vf.
995 RTE_FLOW_ACTION_TYPE_VF,
998 * Traffic metering and policing (MTR).
1000 * See struct rte_flow_action_meter.
1001 * See file rte_mtr.h for MTR object configuration.
1003 RTE_FLOW_ACTION_TYPE_METER,
1006 * Redirects packets to security engine of current device for security
1007 * processing as specified by security session.
1009 * See struct rte_flow_action_security.
1011 RTE_FLOW_ACTION_TYPE_SECURITY
1015 * RTE_FLOW_ACTION_TYPE_MARK
1017 * Attaches an integer value to packets and sets PKT_RX_FDIR and
1018 * PKT_RX_FDIR_ID mbuf flags.
1020 * This value is arbitrary and application-defined. Maximum allowed value
1021 * depends on the underlying implementation. It is returned in the
1022 * hash.fdir.hi mbuf field.
1024 struct rte_flow_action_mark {
1025 uint32_t id; /**< Integer value to return with packets. */
1029 * RTE_FLOW_ACTION_TYPE_QUEUE
1031 * Assign packets to a given queue index.
1033 * Terminating by default.
1035 struct rte_flow_action_queue {
1036 uint16_t index; /**< Queue index to use. */
1040 * RTE_FLOW_ACTION_TYPE_COUNT (query)
1042 * Query structure to retrieve and reset flow rule counters.
1044 struct rte_flow_query_count {
1045 uint32_t reset:1; /**< Reset counters after query [in]. */
1046 uint32_t hits_set:1; /**< hits field is set [out]. */
1047 uint32_t bytes_set:1; /**< bytes field is set [out]. */
1048 uint32_t reserved:29; /**< Reserved, must be zero [in, out]. */
1049 uint64_t hits; /**< Number of hits for this rule [out]. */
1050 uint64_t bytes; /**< Number of bytes through this rule [out]. */
1054 * RTE_FLOW_ACTION_TYPE_DUP
1056 * Duplicates packets to a given queue index.
1058 * This is normally combined with QUEUE, however when used alone, it is
1059 * actually similar to QUEUE + PASSTHRU.
1061 * Non-terminating by default.
1063 struct rte_flow_action_dup {
1064 uint16_t index; /**< Queue index to duplicate packets to. */
1068 * RTE_FLOW_ACTION_TYPE_RSS
1070 * Similar to QUEUE, except RSS is additionally performed on packets to
1071 * spread them among several queues according to the provided parameters.
1073 * Note: RSS hash result is stored in the hash.rss mbuf field which overlaps
1074 * hash.fdir.lo. Since the MARK action sets the hash.fdir.hi field only,
1075 * both can be requested simultaneously.
1077 * Terminating by default.
1079 struct rte_flow_action_rss {
1080 const struct rte_eth_rss_conf *rss_conf; /**< RSS parameters. */
1081 uint16_t num; /**< Number of entries in queue[]. */
1082 uint16_t queue[]; /**< Queues indices to use. */
1086 * RTE_FLOW_ACTION_TYPE_VF
1088 * Redirects packets to a virtual function (VF) of the current device.
1090 * Packets matched by a VF pattern item can be redirected to their original
1091 * VF ID instead of the specified one. This parameter may not be available
1092 * and is not guaranteed to work properly if the VF part is matched by a
1093 * prior flow rule or if packets are not addressed to a VF in the first
1096 * Terminating by default.
1098 struct rte_flow_action_vf {
1099 uint32_t original:1; /**< Use original VF ID if possible. */
1100 uint32_t reserved:31; /**< Reserved, must be zero. */
1101 uint32_t id; /**< VF ID to redirect packets to. */
1105 * RTE_FLOW_ACTION_TYPE_METER
1107 * Traffic metering and policing (MTR).
1109 * Packets matched by items of this type can be either dropped or passed to the
1110 * next item with their color set by the MTR object.
1112 * Non-terminating by default.
1114 struct rte_flow_action_meter {
1115 uint32_t mtr_id; /**< MTR object ID created with rte_mtr_create(). */
1119 * RTE_FLOW_ACTION_TYPE_SECURITY
1121 * Perform the security action on flows matched by the pattern items
1122 * according to the configuration of the security session.
1124 * This action modifies the payload of matched flows. For INLINE_CRYPTO, the
1125 * security protocol headers and IV are fully provided by the application as
1126 * specified in the flow pattern. The payload of matching packets is
1127 * encrypted on egress, and decrypted and authenticated on ingress.
1128 * For INLINE_PROTOCOL, the security protocol is fully offloaded to HW,
1129 * providing full encapsulation and decapsulation of packets in security
1130 * protocols. The flow pattern specifies both the outer security header fields
1131 * and the inner packet fields. The security session specified in the action
1132 * must match the pattern parameters.
1134 * The security session specified in the action must be created on the same
1135 * port as the flow action that is being specified.
1137 * The ingress/egress flow attribute should match that specified in the
1138 * security session if the security session supports the definition of the
1141 * Multiple flows can be configured to use the same security session.
1143 * Non-terminating by default.
1145 struct rte_flow_action_security {
1146 void *security_session; /**< Pointer to security session structure. */
1150 * Definition of a single action.
1152 * A list of actions is terminated by a END action.
1154 * For simple actions without a configuration structure, conf remains NULL.
1156 struct rte_flow_action {
1157 enum rte_flow_action_type type; /**< Action type. */
1158 const void *conf; /**< Pointer to action configuration structure. */
1162 * Opaque type returned after successfully creating a flow.
1164 * This handle can be used to manage and query the related flow (e.g. to
1165 * destroy it or retrieve counters).
1170 * Verbose error types.
1172 * Most of them provide the type of the object referenced by struct
1173 * rte_flow_error.cause.
1175 enum rte_flow_error_type {
1176 RTE_FLOW_ERROR_TYPE_NONE, /**< No error. */
1177 RTE_FLOW_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
1178 RTE_FLOW_ERROR_TYPE_HANDLE, /**< Flow rule (handle). */
1179 RTE_FLOW_ERROR_TYPE_ATTR_GROUP, /**< Group field. */
1180 RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */
1181 RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */
1182 RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */
1183 RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */
1184 RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */
1185 RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */
1186 RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */
1187 RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */
1191 * Verbose error structure definition.
1193 * This object is normally allocated by applications and set by PMDs, the
1194 * message points to a constant string which does not need to be freed by
1195 * the application, however its pointer can be considered valid only as long
1196 * as its associated DPDK port remains configured. Closing the underlying
1197 * device or unloading the PMD invalidates it.
1199 * Both cause and message may be NULL regardless of the error type.
1201 struct rte_flow_error {
1202 enum rte_flow_error_type type; /**< Cause field and error types. */
1203 const void *cause; /**< Object responsible for the error. */
1204 const char *message; /**< Human-readable error message. */
1208 * Check whether a flow rule can be created on a given port.
1210 * The flow rule is validated for correctness and whether it could be accepted
1211 * by the device given sufficient resources. The rule is checked against the
1212 * current device mode and queue configuration. The flow rule may also
1213 * optionally be validated against existing flow rules and device resources.
1214 * This function has no effect on the target device.
1216 * The returned value is guaranteed to remain valid only as long as no
1217 * successful calls to rte_flow_create() or rte_flow_destroy() are made in
1218 * the meantime and no device parameter affecting flow rules in any way are
1219 * modified, due to possible collisions or resource limitations (although in
1220 * such cases EINVAL should not be returned).
1223 * Port identifier of Ethernet device.
1225 * Flow rule attributes.
1226 * @param[in] pattern
1227 * Pattern specification (list terminated by the END pattern item).
1228 * @param[in] actions
1229 * Associated actions (list terminated by the END action).
1231 * Perform verbose error reporting if not NULL. PMDs initialize this
1232 * structure in case of error only.
1235 * 0 if flow rule is valid and can be created. A negative errno value
1236 * otherwise (rte_errno is also set), the following errors are defined:
1238 * -ENOSYS: underlying device does not support this functionality.
1240 * -EINVAL: unknown or invalid rule specification.
1242 * -ENOTSUP: valid but unsupported rule specification (e.g. partial
1243 * bit-masks are unsupported).
1245 * -EEXIST: collision with an existing rule. Only returned if device
1246 * supports flow rule collision checking and there was a flow rule
1247 * collision. Not receiving this return code is no guarantee that creating
1248 * the rule will not fail due to a collision.
1250 * -ENOMEM: not enough memory to execute the function, or if the device
1251 * supports resource validation, resource limitation on the device.
1253 * -EBUSY: action cannot be performed due to busy device resources, may
1254 * succeed if the affected queues or even the entire port are in a stopped
1255 * state (see rte_eth_dev_rx_queue_stop() and rte_eth_dev_stop()).
1258 rte_flow_validate(uint16_t port_id,
1259 const struct rte_flow_attr *attr,
1260 const struct rte_flow_item pattern[],
1261 const struct rte_flow_action actions[],
1262 struct rte_flow_error *error);
1265 * Create a flow rule on a given port.
1268 * Port identifier of Ethernet device.
1270 * Flow rule attributes.
1271 * @param[in] pattern
1272 * Pattern specification (list terminated by the END pattern item).
1273 * @param[in] actions
1274 * Associated actions (list terminated by the END action).
1276 * Perform verbose error reporting if not NULL. PMDs initialize this
1277 * structure in case of error only.
1280 * A valid handle in case of success, NULL otherwise and rte_errno is set
1281 * to the positive version of one of the error codes defined for
1282 * rte_flow_validate().
1285 rte_flow_create(uint16_t port_id,
1286 const struct rte_flow_attr *attr,
1287 const struct rte_flow_item pattern[],
1288 const struct rte_flow_action actions[],
1289 struct rte_flow_error *error);
1292 * Destroy a flow rule on a given port.
1294 * Failure to destroy a flow rule handle may occur when other flow rules
1295 * depend on it, and destroying it would result in an inconsistent state.
1297 * This function is only guaranteed to succeed if handles are destroyed in
1298 * reverse order of their creation.
1301 * Port identifier of Ethernet device.
1303 * Flow rule handle to destroy.
1305 * Perform verbose error reporting if not NULL. PMDs initialize this
1306 * structure in case of error only.
1309 * 0 on success, a negative errno value otherwise and rte_errno is set.
1312 rte_flow_destroy(uint16_t port_id,
1313 struct rte_flow *flow,
1314 struct rte_flow_error *error);
1317 * Destroy all flow rules associated with a port.
1319 * In the unlikely event of failure, handles are still considered destroyed
1320 * and no longer valid but the port must be assumed to be in an inconsistent
1324 * Port identifier of Ethernet device.
1326 * Perform verbose error reporting if not NULL. PMDs initialize this
1327 * structure in case of error only.
1330 * 0 on success, a negative errno value otherwise and rte_errno is set.
1333 rte_flow_flush(uint16_t port_id,
1334 struct rte_flow_error *error);
1337 * Query an existing flow rule.
1339 * This function allows retrieving flow-specific data such as counters.
1340 * Data is gathered by special actions which must be present in the flow
1343 * \see RTE_FLOW_ACTION_TYPE_COUNT
1346 * Port identifier of Ethernet device.
1348 * Flow rule handle to query.
1350 * Action type to query.
1351 * @param[in, out] data
1352 * Pointer to storage for the associated query data type.
1354 * Perform verbose error reporting if not NULL. PMDs initialize this
1355 * structure in case of error only.
1358 * 0 on success, a negative errno value otherwise and rte_errno is set.
1361 rte_flow_query(uint16_t port_id,
1362 struct rte_flow *flow,
1363 enum rte_flow_action_type action,
1365 struct rte_flow_error *error);
1368 * Restrict ingress traffic to the defined flow rules.
1370 * Isolated mode guarantees that all ingress traffic comes from defined flow
1371 * rules only (current and future).
1373 * Besides making ingress more deterministic, it allows PMDs to safely reuse
1374 * resources otherwise assigned to handle the remaining traffic, such as
1375 * global RSS configuration settings, VLAN filters, MAC address entries,
1376 * legacy filter API rules and so on in order to expand the set of possible
1379 * Calling this function as soon as possible after device initialization,
1380 * ideally before the first call to rte_eth_dev_configure(), is recommended
1381 * to avoid possible failures due to conflicting settings.
1383 * Once effective, leaving isolated mode may not be possible depending on
1384 * PMD implementation.
1386 * Additionally, the following functionality has no effect on the underlying
1387 * port and may return errors such as ENOTSUP ("not supported"):
1389 * - Toggling promiscuous mode.
1390 * - Toggling allmulticast mode.
1391 * - Configuring MAC addresses.
1392 * - Configuring multicast addresses.
1393 * - Configuring VLAN filters.
1394 * - Configuring Rx filters through the legacy API (e.g. FDIR).
1395 * - Configuring global RSS settings.
1398 * Port identifier of Ethernet device.
1400 * Nonzero to enter isolated mode, attempt to leave it otherwise.
1402 * Perform verbose error reporting if not NULL. PMDs initialize this
1403 * structure in case of error only.
1406 * 0 on success, a negative errno value otherwise and rte_errno is set.
1409 rte_flow_isolate(uint16_t port_id, int set, struct rte_flow_error *error);
1412 * Initialize flow error structure.
1415 * Pointer to flow error structure (may be NULL).
1417 * Related error code (rte_errno).
1419 * Cause field and error types.
1421 * Object responsible for the error.
1423 * Human-readable error message.
1426 * Negative error code (errno value) and rte_errno is set.
1429 rte_flow_error_set(struct rte_flow_error *error,
1431 enum rte_flow_error_type type,
1433 const char *message);
1436 * Generic flow representation.
1438 * This form is sufficient to describe an rte_flow independently from any
1439 * PMD implementation and allows for replayability and identification.
1441 struct rte_flow_desc {
1442 size_t size; /**< Allocated space including data[]. */
1443 struct rte_flow_attr attr; /**< Attributes. */
1444 struct rte_flow_item *items; /**< Items. */
1445 struct rte_flow_action *actions; /**< Actions. */
1446 uint8_t data[]; /**< Storage for items/actions. */
1450 * Copy an rte_flow rule description.
1453 * Flow rule description.
1455 * Total size of allocated data for the flow description.
1457 * Flow rule attributes.
1459 * Pattern specification (list terminated by the END pattern item).
1460 * @param[in] actions
1461 * Associated actions (list terminated by the END action).
1464 * If len is greater or equal to the size of the flow, the total size of the
1465 * flow description and its data.
1466 * If len is lower than the size of the flow, the number of bytes that would
1467 * have been written to desc had it been sufficient. Nothing is written.
1470 rte_flow_copy(struct rte_flow_desc *fd, size_t len,
1471 const struct rte_flow_attr *attr,
1472 const struct rte_flow_item *items,
1473 const struct rte_flow_action *actions);
1479 #endif /* RTE_FLOW_H_ */