lib/librte_ether/rte_flow.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright 2016 6WIND S.A.
   5  *   Copyright 2016 Mellanox.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  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
  16  *       distribution.
  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.
  20  *
  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.
  32  */
  33
  34 #ifndef RTE_FLOW_H_
  35 #define RTE_FLOW_H_
  36
  37 /**
  38  * @file
  39  * RTE generic flow API
  40  *
  41  * This interface provides the ability to program packet matching and
  42  * associated actions in hardware through flow rules.
  43  */
  44
  45 #include <rte_arp.h>
  46 #include <rte_ether.h>
  47 #include <rte_icmp.h>
  48 #include <rte_ip.h>
  49 #include <rte_sctp.h>
  50 #include <rte_tcp.h>
  51 #include <rte_udp.h>
  52 #include <rte_byteorder.h>
  53 #include <rte_esp.h>
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 /**
  60  * Flow rule attributes.
  61  *
  62  * Priorities are set on two levels: per group and per rule within groups.
  63  *
  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.
  67  *
  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).
  72  *
  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.
  76  *
  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.
  80  *
  81  * Note that support for more than a single group and priority level is not
  82  * guaranteed.
  83  *
  84  * Flow rules can apply to inbound and/or outbound traffic (ingress/egress).
  85  *
  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.
  88  *
  89  * At least one direction must be specified.
  90  *
  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).
  93  */
  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. */
 100 };
 101
 102 /**
 103  * Matching pattern item types.
 104  *
 105  * Pattern items fall in two categories:
 106  *
 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.
 111  *
 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.
 116  *
 117  * See the description of individual types for more information. Those
 118  * marked with [META] fall into the second category.
 119  */
 120 enum rte_flow_item_type {
 121         /**
 122          * [META]
 123          *
 124          * End marker for item lists. Prevents further processing of items,
 125          * thereby ending the pattern.
 126          *
 127          * No associated specification structure.
 128          */
 129         RTE_FLOW_ITEM_TYPE_END,
 130
 131         /**
 132          * [META]
 133          *
 134          * Used as a placeholder for convenience. It is ignored and simply
 135          * discarded by PMDs.
 136          *
 137          * No associated specification structure.
 138          */
 139         RTE_FLOW_ITEM_TYPE_VOID,
 140
 141         /**
 142          * [META]
 143          *
 144          * Inverted matching, i.e. process packets that do not match the
 145          * pattern.
 146          *
 147          * No associated specification structure.
 148          */
 149         RTE_FLOW_ITEM_TYPE_INVERT,
 150
 151         /**
 152          * Matches any protocol in place of the current layer, a single ANY
 153          * may also stand for several protocol layers.
 154          *
 155          * See struct rte_flow_item_any.
 156          */
 157         RTE_FLOW_ITEM_TYPE_ANY,
 158
 159         /**
 160          * [META]
 161          *
 162          * Matches packets addressed to the physical function of the device.
 163          *
 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.
 169          *
 170          * No associated specification structure.
 171          */
 172         RTE_FLOW_ITEM_TYPE_PF,
 173
 174         /**
 175          * [META]
 176          *
 177          * Matches packets addressed to a virtual function ID of the device.
 178          *
 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.
 184          *
 185          * See struct rte_flow_item_vf.
 186          */
 187         RTE_FLOW_ITEM_TYPE_VF,
 188
 189         /**
 190          * [META]
 191          *
 192          * Matches packets coming from the specified physical port of the
 193          * underlying device.
 194          *
 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
 198          * ports.
 199          *
 200          * See struct rte_flow_item_port.
 201          */
 202         RTE_FLOW_ITEM_TYPE_PORT,
 203
 204         /**
 205          * Matches a byte string of a given length at a given offset.
 206          *
 207          * See struct rte_flow_item_raw.
 208          */
 209         RTE_FLOW_ITEM_TYPE_RAW,
 210
 211         /**
 212          * Matches an Ethernet header.
 213          *
 214          * See struct rte_flow_item_eth.
 215          */
 216         RTE_FLOW_ITEM_TYPE_ETH,
 217
 218         /**
 219          * Matches an 802.1Q/ad VLAN tag.
 220          *
 221          * See struct rte_flow_item_vlan.
 222          */
 223         RTE_FLOW_ITEM_TYPE_VLAN,
 224
 225         /**
 226          * Matches an IPv4 header.
 227          *
 228          * See struct rte_flow_item_ipv4.
 229          */
 230         RTE_FLOW_ITEM_TYPE_IPV4,
 231
 232         /**
 233          * Matches an IPv6 header.
 234          *
 235          * See struct rte_flow_item_ipv6.
 236          */
 237         RTE_FLOW_ITEM_TYPE_IPV6,
 238
 239         /**
 240          * Matches an ICMP header.
 241          *
 242          * See struct rte_flow_item_icmp.
 243          */
 244         RTE_FLOW_ITEM_TYPE_ICMP,
 245
 246         /**
 247          * Matches a UDP header.
 248          *
 249          * See struct rte_flow_item_udp.
 250          */
 251         RTE_FLOW_ITEM_TYPE_UDP,
 252
 253         /**
 254          * Matches a TCP header.
 255          *
 256          * See struct rte_flow_item_tcp.
 257          */
 258         RTE_FLOW_ITEM_TYPE_TCP,
 259
 260         /**
 261          * Matches a SCTP header.
 262          *
 263          * See struct rte_flow_item_sctp.
 264          */
 265         RTE_FLOW_ITEM_TYPE_SCTP,
 266
 267         /**
 268          * Matches a VXLAN header.
 269          *
 270          * See struct rte_flow_item_vxlan.
 271          */
 272         RTE_FLOW_ITEM_TYPE_VXLAN,
 273
 274         /**
 275          * Matches a E_TAG header.
 276          *
 277          * See struct rte_flow_item_e_tag.
 278          */
 279         RTE_FLOW_ITEM_TYPE_E_TAG,
 280
 281         /**
 282          * Matches a NVGRE header.
 283          *
 284          * See struct rte_flow_item_nvgre.
 285          */
 286         RTE_FLOW_ITEM_TYPE_NVGRE,
 287
 288         /**
 289          * Matches a MPLS header.
 290          *
 291          * See struct rte_flow_item_mpls.
 292          */
 293         RTE_FLOW_ITEM_TYPE_MPLS,
 294
 295         /**
 296          * Matches a GRE header.
 297          *
 298          * See struct rte_flow_item_gre.
 299          */
 300         RTE_FLOW_ITEM_TYPE_GRE,
 301
 302         /**
 303          * [META]
 304          *
 305          * Fuzzy pattern match, expect faster than default.
 306          *
 307          * This is for device that support fuzzy matching option.
 308          * Usually a fuzzy matching is fast but the cost is accuracy.
 309          *
 310          * See struct rte_flow_item_fuzzy.
 311          */
 312         RTE_FLOW_ITEM_TYPE_FUZZY,
 313
 314         /**
 315          * Matches a GTP header.
 316          *
 317          * Configure flow for GTP packets.
 318          *
 319          * See struct rte_flow_item_gtp.
 320          */
 321         RTE_FLOW_ITEM_TYPE_GTP,
 322
 323         /**
 324          * Matches a GTP header.
 325          *
 326          * Configure flow for GTP-C packets.
 327          *
 328          * See struct rte_flow_item_gtp.
 329          */
 330         RTE_FLOW_ITEM_TYPE_GTPC,
 331
 332         /**
 333          * Matches a GTP header.
 334          *
 335          * Configure flow for GTP-U packets.
 336          *
 337          * See struct rte_flow_item_gtp.
 338          */
 339         RTE_FLOW_ITEM_TYPE_GTPU,
 340
 341         /**
 342          * Matches a ESP header.
 343          *
 344          * See struct rte_flow_item_esp.
 345          */
 346         RTE_FLOW_ITEM_TYPE_ESP,
 347 };
 348
 349 /**
 350  * RTE_FLOW_ITEM_TYPE_ANY
 351  *
 352  * Matches any protocol in place of the current layer, a single ANY may also
 353  * stand for several protocol layers.
 354  *
 355  * This is usually specified as the first pattern item when looking for a
 356  * protocol anywhere in a packet.
 357  *
 358  * A zeroed mask stands for any number of layers.
 359  */
 360 struct rte_flow_item_any {
 361         uint32_t num; /**< Number of layers covered. */
 362 };
 363
 364 /** Default mask for RTE_FLOW_ITEM_TYPE_ANY. */
 365 #ifndef __cplusplus
 366 static const struct rte_flow_item_any rte_flow_item_any_mask = {
 367         .num = 0x00000000,
 368 };
 369 #endif
 370
 371 /**
 372  * RTE_FLOW_ITEM_TYPE_VF
 373  *
 374  * Matches packets addressed to a virtual function ID of the device.
 375  *
 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.
 380  *
 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
 384  *   VF IDs.
 385  * - Can be combined with a PF item to match both PF and VF traffic.
 386  *
 387  * A zeroed mask can be used to match any VF ID.
 388  */
 389 struct rte_flow_item_vf {
 390         uint32_t id; /**< Destination VF ID. */
 391 };
 392
 393 /** Default mask for RTE_FLOW_ITEM_TYPE_VF. */
 394 #ifndef __cplusplus
 395 static const struct rte_flow_item_vf rte_flow_item_vf_mask = {
 396         .id = 0x00000000,
 397 };
 398 #endif
 399
 400 /**
 401  * RTE_FLOW_ITEM_TYPE_PORT
 402  *
 403  * Matches packets coming from the specified physical port of the underlying
 404  * device.
 405  *
 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.
 409  *
 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.
 414  *
 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.
 417  *
 418  * A zeroed mask can be used to match any port index.
 419  */
 420 struct rte_flow_item_port {
 421         uint32_t index; /**< Physical port index. */
 422 };
 423
 424 /** Default mask for RTE_FLOW_ITEM_TYPE_PORT. */
 425 #ifndef __cplusplus
 426 static const struct rte_flow_item_port rte_flow_item_port_mask = {
 427         .index = 0x00000000,
 428 };
 429 #endif
 430
 431 /**
 432  * RTE_FLOW_ITEM_TYPE_RAW
 433  *
 434  * Matches a byte string of a given length at a given offset.
 435  *
 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.
 439  *
 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.
 443  *
 444  * Matching a zero-length pattern is allowed, doing so resets the relative
 445  * offset for subsequent items.
 446  *
 447  * This type does not support ranges (struct rte_flow_item.last).
 448  */
 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. */
 457 };
 458
 459 /** Default mask for RTE_FLOW_ITEM_TYPE_RAW. */
 460 #ifndef __cplusplus
 461 static const struct rte_flow_item_raw rte_flow_item_raw_mask = {
 462         .relative = 1,
 463         .search = 1,
 464         .reserved = 0x3fffffff,
 465         .offset = 0xffffffff,
 466         .limit = 0xffff,
 467         .length = 0xffff,
 468 };
 469 #endif
 470
 471 /**
 472  * RTE_FLOW_ITEM_TYPE_ETH
 473  *
 474  * Matches an Ethernet header.
 475  */
 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. */
 480 };
 481
 482 /** Default mask for RTE_FLOW_ITEM_TYPE_ETH. */
 483 #ifndef __cplusplus
 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),
 488 };
 489 #endif
 490
 491 /**
 492  * RTE_FLOW_ITEM_TYPE_VLAN
 493  *
 494  * Matches an 802.1Q/ad VLAN tag.
 495  *
 496  * This type normally follows either RTE_FLOW_ITEM_TYPE_ETH or
 497  * RTE_FLOW_ITEM_TYPE_VLAN.
 498  */
 499 struct rte_flow_item_vlan {
 500         rte_be16_t tpid; /**< Tag protocol identifier. */
 501         rte_be16_t tci; /**< Tag control information. */
 502 };
 503
 504 /** Default mask for RTE_FLOW_ITEM_TYPE_VLAN. */
 505 #ifndef __cplusplus
 506 static const struct rte_flow_item_vlan rte_flow_item_vlan_mask = {
 507         .tpid = RTE_BE16(0x0000),
 508         .tci = RTE_BE16(0xffff),
 509 };
 510 #endif
 511
 512 /**
 513  * RTE_FLOW_ITEM_TYPE_IPV4
 514  *
 515  * Matches an IPv4 header.
 516  *
 517  * Note: IPv4 options are handled by dedicated pattern items.
 518  */
 519 struct rte_flow_item_ipv4 {
 520         struct ipv4_hdr hdr; /**< IPv4 header definition. */
 521 };
 522
 523 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV4. */
 524 #ifndef __cplusplus
 525 static const struct rte_flow_item_ipv4 rte_flow_item_ipv4_mask = {
 526         .hdr = {
 527                 .src_addr = RTE_BE32(0xffffffff),
 528                 .dst_addr = RTE_BE32(0xffffffff),
 529         },
 530 };
 531 #endif
 532
 533 /**
 534  * RTE_FLOW_ITEM_TYPE_IPV6.
 535  *
 536  * Matches an IPv6 header.
 537  *
 538  * Note: IPv6 options are handled by dedicated pattern items.
 539  */
 540 struct rte_flow_item_ipv6 {
 541         struct ipv6_hdr hdr; /**< IPv6 header definition. */
 542 };
 543
 544 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV6. */
 545 #ifndef __cplusplus
 546 static const struct rte_flow_item_ipv6 rte_flow_item_ipv6_mask = {
 547         .hdr = {
 548                 .src_addr =
 549                         "\xff\xff\xff\xff\xff\xff\xff\xff"
 550                         "\xff\xff\xff\xff\xff\xff\xff\xff",
 551                 .dst_addr =
 552                         "\xff\xff\xff\xff\xff\xff\xff\xff"
 553                         "\xff\xff\xff\xff\xff\xff\xff\xff",
 554         },
 555 };
 556 #endif
 557
 558 /**
 559  * RTE_FLOW_ITEM_TYPE_ICMP.
 560  *
 561  * Matches an ICMP header.
 562  */
 563 struct rte_flow_item_icmp {
 564         struct icmp_hdr hdr; /**< ICMP header definition. */
 565 };
 566
 567 /** Default mask for RTE_FLOW_ITEM_TYPE_ICMP. */
 568 #ifndef __cplusplus
 569 static const struct rte_flow_item_icmp rte_flow_item_icmp_mask = {
 570         .hdr = {
 571                 .icmp_type = 0xff,
 572                 .icmp_code = 0xff,
 573         },
 574 };
 575 #endif
 576
 577 /**
 578  * RTE_FLOW_ITEM_TYPE_UDP.
 579  *
 580  * Matches a UDP header.
 581  */
 582 struct rte_flow_item_udp {
 583         struct udp_hdr hdr; /**< UDP header definition. */
 584 };
 585
 586 /** Default mask for RTE_FLOW_ITEM_TYPE_UDP. */
 587 #ifndef __cplusplus
 588 static const struct rte_flow_item_udp rte_flow_item_udp_mask = {
 589         .hdr = {
 590                 .src_port = RTE_BE16(0xffff),
 591                 .dst_port = RTE_BE16(0xffff),
 592         },
 593 };
 594 #endif
 595
 596 /**
 597  * RTE_FLOW_ITEM_TYPE_TCP.
 598  *
 599  * Matches a TCP header.
 600  */
 601 struct rte_flow_item_tcp {
 602         struct tcp_hdr hdr; /**< TCP header definition. */
 603 };
 604
 605 /** Default mask for RTE_FLOW_ITEM_TYPE_TCP. */
 606 #ifndef __cplusplus
 607 static const struct rte_flow_item_tcp rte_flow_item_tcp_mask = {
 608         .hdr = {
 609                 .src_port = RTE_BE16(0xffff),
 610                 .dst_port = RTE_BE16(0xffff),
 611         },
 612 };
 613 #endif
 614
 615 /**
 616  * RTE_FLOW_ITEM_TYPE_SCTP.
 617  *
 618  * Matches a SCTP header.
 619  */
 620 struct rte_flow_item_sctp {
 621         struct sctp_hdr hdr; /**< SCTP header definition. */
 622 };
 623
 624 /** Default mask for RTE_FLOW_ITEM_TYPE_SCTP. */
 625 #ifndef __cplusplus
 626 static const struct rte_flow_item_sctp rte_flow_item_sctp_mask = {
 627         .hdr = {
 628                 .src_port = RTE_BE16(0xffff),
 629                 .dst_port = RTE_BE16(0xffff),
 630         },
 631 };
 632 #endif
 633
 634 /**
 635  * RTE_FLOW_ITEM_TYPE_VXLAN.
 636  *
 637  * Matches a VXLAN header (RFC 7348).
 638  */
 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. */
 644 };
 645
 646 /** Default mask for RTE_FLOW_ITEM_TYPE_VXLAN. */
 647 #ifndef __cplusplus
 648 static const struct rte_flow_item_vxlan rte_flow_item_vxlan_mask = {
 649         .vni = "\xff\xff\xff",
 650 };
 651 #endif
 652
 653 /**
 654  * RTE_FLOW_ITEM_TYPE_E_TAG.
 655  *
 656  * Matches a E-tag header.
 657  */
 658 struct rte_flow_item_e_tag {
 659         rte_be16_t tpid; /**< Tag protocol identifier (0x893F). */
 660         /**
 661          * E-Tag control information (E-TCI).
 662          * E-PCP (3b), E-DEI (1b), ingress E-CID base (12b).
 663          */
 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. */
 669 };
 670
 671 /** Default mask for RTE_FLOW_ITEM_TYPE_E_TAG. */
 672 #ifndef __cplusplus
 673 static const struct rte_flow_item_e_tag rte_flow_item_e_tag_mask = {
 674         .rsvd_grp_ecid_b = RTE_BE16(0x3fff),
 675 };
 676 #endif
 677
 678 /**
 679  * RTE_FLOW_ITEM_TYPE_NVGRE.
 680  *
 681  * Matches a NVGRE header.
 682  */
 683 struct rte_flow_item_nvgre {
 684         /**
 685          * Checksum (1b), undefined (1b), key bit (1b), sequence number (1b),
 686          * reserved 0 (9b), version (3b).
 687          *
 688          * c_k_s_rsvd0_ver must have value 0x2000 according to RFC 7637.
 689          */
 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. */
 694 };
 695
 696 /** Default mask for RTE_FLOW_ITEM_TYPE_NVGRE. */
 697 #ifndef __cplusplus
 698 static const struct rte_flow_item_nvgre rte_flow_item_nvgre_mask = {
 699         .tni = "\xff\xff\xff",
 700 };
 701 #endif
 702
 703 /**
 704  * RTE_FLOW_ITEM_TYPE_MPLS.
 705  *
 706  * Matches a MPLS header.
 707  */
 708 struct rte_flow_item_mpls {
 709         /**
 710          * Label (20b), TC (3b), Bottom of Stack (1b).
 711          */
 712         uint8_t label_tc_s[3];
 713         uint8_t ttl; /** Time-to-Live. */
 714 };
 715
 716 /** Default mask for RTE_FLOW_ITEM_TYPE_MPLS. */
 717 #ifndef __cplusplus
 718 static const struct rte_flow_item_mpls rte_flow_item_mpls_mask = {
 719         .label_tc_s = "\xff\xff\xf0",
 720 };
 721 #endif
 722
 723 /**
 724  * RTE_FLOW_ITEM_TYPE_GRE.
 725  *
 726  * Matches a GRE header.
 727  */
 728 struct rte_flow_item_gre {
 729         /**
 730          * Checksum (1b), reserved 0 (12b), version (3b).
 731          * Refer to RFC 2784.
 732          */
 733         rte_be16_t c_rsvd0_ver;
 734         rte_be16_t protocol; /**< Protocol type. */
 735 };
 736
 737 /** Default mask for RTE_FLOW_ITEM_TYPE_GRE. */
 738 #ifndef __cplusplus
 739 static const struct rte_flow_item_gre rte_flow_item_gre_mask = {
 740         .protocol = RTE_BE16(0xffff),
 741 };
 742 #endif
 743
 744 /**
 745  * RTE_FLOW_ITEM_TYPE_FUZZY
 746  *
 747  * Fuzzy pattern match, expect faster than default.
 748  *
 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.
 753  *
 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.
 757  *
 758  * Threshold 0 means perfect match (no fuzziness), while threshold
 759  * 0xffffffff means fuzziest match.
 760  */
 761 struct rte_flow_item_fuzzy {
 762         uint32_t thresh; /**< Accuracy threshold. */
 763 };
 764
 765 /** Default mask for RTE_FLOW_ITEM_TYPE_FUZZY. */
 766 #ifndef __cplusplus
 767 static const struct rte_flow_item_fuzzy rte_flow_item_fuzzy_mask = {
 768         .thresh = 0xffffffff,
 769 };
 770 #endif
 771
 772 /**
 773  * RTE_FLOW_ITEM_TYPE_GTP.
 774  *
 775  * Matches a GTPv1 header.
 776  */
 777 struct rte_flow_item_gtp {
 778         /**
 779          * Version (3b), protocol type (1b), reserved (1b),
 780          * Extension header flag (1b),
 781          * Sequence number flag (1b),
 782          * N-PDU number flag (1b).
 783          */
 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. */
 788 };
 789
 790 /** Default mask for RTE_FLOW_ITEM_TYPE_GTP. */
 791 #ifndef __cplusplus
 792 static const struct rte_flow_item_gtp rte_flow_item_gtp_mask = {
 793         .teid = RTE_BE32(0xffffffff),
 794 };
 795 #endif
 796
 797 /**
 798  * RTE_FLOW_ITEM_TYPE_ESP
 799  *
 800  * Matches an ESP header.
 801  */
 802 struct rte_flow_item_esp {
 803         struct esp_hdr hdr; /**< ESP header definition. */
 804 };
 805
 806 /** Default mask for RTE_FLOW_ITEM_TYPE_ESP. */
 807 #ifndef __cplusplus
 808 static const struct rte_flow_item_esp rte_flow_item_esp_mask = {
 809         .hdr = {
 810                 .spi = 0xffffffff,
 811         },
 812 };
 813 #endif
 814
 815 /**
 816  * Matching pattern item definition.
 817  *
 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.
 822  *
 823  * Patterns are terminated by END items.
 824  *
 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
 828  * set to NULL.
 829  *
 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.
 834  *
 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).
 841  *
 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.
 847  */
 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. */
 853 };
 854
 855 /**
 856  * Action types.
 857  *
 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.
 861  *
 862  * They fall in three categories:
 863  *
 864  * - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
 865  *   processing matched packets by subsequent flow rules, unless overridden
 866  *   with PASSTHRU.
 867  *
 868  * - Non terminating actions (PASSTHRU, DUP) that leave matched packets up
 869  *   for additional processing by subsequent flow rules.
 870  *
 871  * - Other non terminating meta actions that do not affect the fate of
 872  *   packets (END, VOID, MARK, FLAG, COUNT).
 873  *
 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).
 876  *
 877  * Only the last action of a given type is taken into account. PMDs still
 878  * perform error checking on the entire list.
 879  *
 880  * Note that PASSTHRU is the only action able to override a terminating
 881  * rule.
 882  */
 883 enum rte_flow_action_type {
 884         /**
 885          * [META]
 886          *
 887          * End marker for action lists. Prevents further processing of
 888          * actions, thereby ending the list.
 889          *
 890          * No associated configuration structure.
 891          */
 892         RTE_FLOW_ACTION_TYPE_END,
 893
 894         /**
 895          * [META]
 896          *
 897          * Used as a placeholder for convenience. It is ignored and simply
 898          * discarded by PMDs.
 899          *
 900          * No associated configuration structure.
 901          */
 902         RTE_FLOW_ACTION_TYPE_VOID,
 903
 904         /**
 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.
 909          *
 910          * No associated configuration structure.
 911          */
 912         RTE_FLOW_ACTION_TYPE_PASSTHRU,
 913
 914         /**
 915          * [META]
 916          *
 917          * Attaches an integer value to packets and sets PKT_RX_FDIR and
 918          * PKT_RX_FDIR_ID mbuf flags.
 919          *
 920          * See struct rte_flow_action_mark.
 921          */
 922         RTE_FLOW_ACTION_TYPE_MARK,
 923
 924         /**
 925          * [META]
 926          *
 927          * Flags packets. Similar to MARK without a specific value; only
 928          * sets the PKT_RX_FDIR mbuf flag.
 929          *
 930          * No associated configuration structure.
 931          */
 932         RTE_FLOW_ACTION_TYPE_FLAG,
 933
 934         /**
 935          * Assigns packets to a given queue index.
 936          *
 937          * See struct rte_flow_action_queue.
 938          */
 939         RTE_FLOW_ACTION_TYPE_QUEUE,
 940
 941         /**
 942          * Drops packets.
 943          *
 944          * PASSTHRU overrides this action if both are specified.
 945          *
 946          * No associated configuration structure.
 947          */
 948         RTE_FLOW_ACTION_TYPE_DROP,
 949
 950         /**
 951          * [META]
 952          *
 953          * Enables counters for this rule.
 954          *
 955          * These counters can be retrieved and reset through rte_flow_query(),
 956          * see struct rte_flow_query_count.
 957          *
 958          * No associated configuration structure.
 959          */
 960         RTE_FLOW_ACTION_TYPE_COUNT,
 961
 962         /**
 963          * Duplicates packets to a given queue index.
 964          *
 965          * This is normally combined with QUEUE, however when used alone, it
 966          * is actually similar to QUEUE + PASSTHRU.
 967          *
 968          * See struct rte_flow_action_dup.
 969          */
 970         RTE_FLOW_ACTION_TYPE_DUP,
 971
 972         /**
 973          * Similar to QUEUE, except RSS is additionally performed on packets
 974          * to spread them among several queues according to the provided
 975          * parameters.
 976          *
 977          * See struct rte_flow_action_rss.
 978          */
 979         RTE_FLOW_ACTION_TYPE_RSS,
 980
 981         /**
 982          * Redirects packets to the physical function (PF) of the current
 983          * device.
 984          *
 985          * No associated configuration structure.
 986          */
 987         RTE_FLOW_ACTION_TYPE_PF,
 988
 989         /**
 990          * Redirects packets to the virtual function (VF) of the current
 991          * device with the specified ID.
 992          *
 993          * See struct rte_flow_action_vf.
 994          */
 995         RTE_FLOW_ACTION_TYPE_VF,
 996
 997         /**
 998          * Traffic metering and policing (MTR).
 999          *
1000          * See struct rte_flow_action_meter.
1001          * See file rte_mtr.h for MTR object configuration.
1002          */
1003         RTE_FLOW_ACTION_TYPE_METER,
1004
1005         /**
1006          * Redirects packets to security engine of current device for security
1007          * processing as specified by security session.
1008          *
1009          * See struct rte_flow_action_security.
1010          */
1011         RTE_FLOW_ACTION_TYPE_SECURITY
1012 };
1013
1014 /**
1015  * RTE_FLOW_ACTION_TYPE_MARK
1016  *
1017  * Attaches an integer value to packets and sets PKT_RX_FDIR and
1018  * PKT_RX_FDIR_ID mbuf flags.
1019  *
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.
1023  */
1024 struct rte_flow_action_mark {
1025         uint32_t id; /**< Integer value to return with packets. */
1026 };
1027
1028 /**
1029  * RTE_FLOW_ACTION_TYPE_QUEUE
1030  *
1031  * Assign packets to a given queue index.
1032  *
1033  * Terminating by default.
1034  */
1035 struct rte_flow_action_queue {
1036         uint16_t index; /**< Queue index to use. */
1037 };
1038
1039 /**
1040  * RTE_FLOW_ACTION_TYPE_COUNT (query)
1041  *
1042  * Query structure to retrieve and reset flow rule counters.
1043  */
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]. */
1051 };
1052
1053 /**
1054  * RTE_FLOW_ACTION_TYPE_DUP
1055  *
1056  * Duplicates packets to a given queue index.
1057  *
1058  * This is normally combined with QUEUE, however when used alone, it is
1059  * actually similar to QUEUE + PASSTHRU.
1060  *
1061  * Non-terminating by default.
1062  */
1063 struct rte_flow_action_dup {
1064         uint16_t index; /**< Queue index to duplicate packets to. */
1065 };
1066
1067 /**
1068  * RTE_FLOW_ACTION_TYPE_RSS
1069  *
1070  * Similar to QUEUE, except RSS is additionally performed on packets to
1071  * spread them among several queues according to the provided parameters.
1072  *
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.
1076  *
1077  * Terminating by default.
1078  */
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. */
1083 };
1084
1085 /**
1086  * RTE_FLOW_ACTION_TYPE_VF
1087  *
1088  * Redirects packets to a virtual function (VF) of the current device.
1089  *
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
1094  * place.
1095  *
1096  * Terminating by default.
1097  */
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. */
1102 };
1103
1104 /**
1105  * RTE_FLOW_ACTION_TYPE_METER
1106  *
1107  * Traffic metering and policing (MTR).
1108  *
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.
1111  *
1112  * Non-terminating by default.
1113  */
1114 struct rte_flow_action_meter {
1115         uint32_t mtr_id; /**< MTR object ID created with rte_mtr_create(). */
1116 };
1117
1118 /**
1119  * RTE_FLOW_ACTION_TYPE_SECURITY
1120  *
1121  * Perform the security action on flows matched by the pattern items
1122  * according to the configuration of the security session.
1123  *
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.
1133  *
1134  * The security session specified in the action must be created on the same
1135  * port as the flow action that is being specified.
1136  *
1137  * The ingress/egress flow attribute should match that specified in the
1138  * security session if the security session supports the definition of the
1139  * direction.
1140  *
1141  * Multiple flows can be configured to use the same security session.
1142  *
1143  * Non-terminating by default.
1144  */
1145 struct rte_flow_action_security {
1146         void *security_session; /**< Pointer to security session structure. */
1147 };
1148
1149 /**
1150  * Definition of a single action.
1151  *
1152  * A list of actions is terminated by a END action.
1153  *
1154  * For simple actions without a configuration structure, conf remains NULL.
1155  */
1156 struct rte_flow_action {
1157         enum rte_flow_action_type type; /**< Action type. */
1158         const void *conf; /**< Pointer to action configuration structure. */
1159 };
1160
1161 /**
1162  * Opaque type returned after successfully creating a flow.
1163  *
1164  * This handle can be used to manage and query the related flow (e.g. to
1165  * destroy it or retrieve counters).
1166  */
1167 struct rte_flow;
1168
1169 /**
1170  * Verbose error types.
1171  *
1172  * Most of them provide the type of the object referenced by struct
1173  * rte_flow_error.cause.
1174  */
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. */
1188 };
1189
1190 /**
1191  * Verbose error structure definition.
1192  *
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.
1198  *
1199  * Both cause and message may be NULL regardless of the error type.
1200  */
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. */
1205 };
1206
1207 /**
1208  * Check whether a flow rule can be created on a given port.
1209  *
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.
1215  *
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).
1221  *
1222  * @param port_id
1223  *   Port identifier of Ethernet device.
1224  * @param[in] attr
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).
1230  * @param[out] error
1231  *   Perform verbose error reporting if not NULL. PMDs initialize this
1232  *   structure in case of error only.
1233  *
1234  * @return
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:
1237  *
1238  *   -ENOSYS: underlying device does not support this functionality.
1239  *
1240  *   -EINVAL: unknown or invalid rule specification.
1241  *
1242  *   -ENOTSUP: valid but unsupported rule specification (e.g. partial
1243  *   bit-masks are unsupported).
1244  *
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.
1249  *
1250  *   -ENOMEM: not enough memory to execute the function, or if the device
1251  *   supports resource validation, resource limitation on the device.
1252  *
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()).
1256  */
1257 int
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);
1263
1264 /**
1265  * Create a flow rule on a given port.
1266  *
1267  * @param port_id
1268  *   Port identifier of Ethernet device.
1269  * @param[in] attr
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).
1275  * @param[out] error
1276  *   Perform verbose error reporting if not NULL. PMDs initialize this
1277  *   structure in case of error only.
1278  *
1279  * @return
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().
1283  */
1284 struct rte_flow *
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);
1290
1291 /**
1292  * Destroy a flow rule on a given port.
1293  *
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.
1296  *
1297  * This function is only guaranteed to succeed if handles are destroyed in
1298  * reverse order of their creation.
1299  *
1300  * @param port_id
1301  *   Port identifier of Ethernet device.
1302  * @param flow
1303  *   Flow rule handle to destroy.
1304  * @param[out] error
1305  *   Perform verbose error reporting if not NULL. PMDs initialize this
1306  *   structure in case of error only.
1307  *
1308  * @return
1309  *   0 on success, a negative errno value otherwise and rte_errno is set.
1310  */
1311 int
1312 rte_flow_destroy(uint16_t port_id,
1313                  struct rte_flow *flow,
1314                  struct rte_flow_error *error);
1315
1316 /**
1317  * Destroy all flow rules associated with a port.
1318  *
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
1321  * state.
1322  *
1323  * @param port_id
1324  *   Port identifier of Ethernet device.
1325  * @param[out] error
1326  *   Perform verbose error reporting if not NULL. PMDs initialize this
1327  *   structure in case of error only.
1328  *
1329  * @return
1330  *   0 on success, a negative errno value otherwise and rte_errno is set.
1331  */
1332 int
1333 rte_flow_flush(uint16_t port_id,
1334                struct rte_flow_error *error);
1335
1336 /**
1337  * Query an existing flow rule.
1338  *
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
1341  * rule definition.
1342  *
1343  * \see RTE_FLOW_ACTION_TYPE_COUNT
1344  *
1345  * @param port_id
1346  *   Port identifier of Ethernet device.
1347  * @param flow
1348  *   Flow rule handle to query.
1349  * @param action
1350  *   Action type to query.
1351  * @param[in, out] data
1352  *   Pointer to storage for the associated query data type.
1353  * @param[out] error
1354  *   Perform verbose error reporting if not NULL. PMDs initialize this
1355  *   structure in case of error only.
1356  *
1357  * @return
1358  *   0 on success, a negative errno value otherwise and rte_errno is set.
1359  */
1360 int
1361 rte_flow_query(uint16_t port_id,
1362                struct rte_flow *flow,
1363                enum rte_flow_action_type action,
1364                void *data,
1365                struct rte_flow_error *error);
1366
1367 /**
1368  * Restrict ingress traffic to the defined flow rules.
1369  *
1370  * Isolated mode guarantees that all ingress traffic comes from defined flow
1371  * rules only (current and future).
1372  *
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
1377  * flow rule types.
1378  *
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.
1382  *
1383  * Once effective, leaving isolated mode may not be possible depending on
1384  * PMD implementation.
1385  *
1386  * Additionally, the following functionality has no effect on the underlying
1387  * port and may return errors such as ENOTSUP ("not supported"):
1388  *
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.
1396  *
1397  * @param port_id
1398  *   Port identifier of Ethernet device.
1399  * @param set
1400  *   Nonzero to enter isolated mode, attempt to leave it otherwise.
1401  * @param[out] error
1402  *   Perform verbose error reporting if not NULL. PMDs initialize this
1403  *   structure in case of error only.
1404  *
1405  * @return
1406  *   0 on success, a negative errno value otherwise and rte_errno is set.
1407  */
1408 int
1409 rte_flow_isolate(uint16_t port_id, int set, struct rte_flow_error *error);
1410
1411 /**
1412  * Initialize flow error structure.
1413  *
1414  * @param[out] error
1415  *   Pointer to flow error structure (may be NULL).
1416  * @param code
1417  *   Related error code (rte_errno).
1418  * @param type
1419  *   Cause field and error types.
1420  * @param cause
1421  *   Object responsible for the error.
1422  * @param message
1423  *   Human-readable error message.
1424  *
1425  * @return
1426  *   Negative error code (errno value) and rte_errno is set.
1427  */
1428 int
1429 rte_flow_error_set(struct rte_flow_error *error,
1430                    int code,
1431                    enum rte_flow_error_type type,
1432                    const void *cause,
1433                    const char *message);
1434
1435 /**
1436  * Generic flow representation.
1437  *
1438  * This form is sufficient to describe an rte_flow independently from any
1439  * PMD implementation and allows for replayability and identification.
1440  */
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. */
1447 };
1448
1449 /**
1450  * Copy an rte_flow rule description.
1451  *
1452  * @param[in] fd
1453  *   Flow rule description.
1454  * @param[in] len
1455  *   Total size of allocated data for the flow description.
1456  * @param[in] attr
1457  *   Flow rule attributes.
1458  * @param[in] items
1459  *   Pattern specification (list terminated by the END pattern item).
1460  * @param[in] actions
1461  *   Associated actions (list terminated by the END action).
1462  *
1463  * @return
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.
1468  */
1469 size_t
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);
1474
1475 #ifdef __cplusplus
1476 }
1477 #endif
1478
1479 #endif /* RTE_FLOW_H_ */