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
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 /**
  58  * Flow rule attributes.
  59  *
  60  * Priorities are set on two levels: per group and per rule within groups.
  61  *
  62  * Lower values denote higher priority, the highest priority for both levels
  63  * is 0, so that a rule with priority 0 in group 8 is always matched after a
  64  * rule with priority 8 in group 0.
  65  *
  66  * Although optional, applications are encouraged to group similar rules as
  67  * much as possible to fully take advantage of hardware capabilities
  68  * (e.g. optimized matching) and work around limitations (e.g. a single
  69  * pattern type possibly allowed in a given group).
  70  *
  71  * Group and priority levels are arbitrary and up to the application, they
  72  * do not need to be contiguous nor start from 0, however the maximum number
  73  * varies between devices and may be affected by existing flow rules.
  74  *
  75  * If a packet is matched by several rules of a given group for a given
  76  * priority level, the outcome is undefined. It can take any path, may be
  77  * duplicated or even cause unrecoverable errors.
  78  *
  79  * Note that support for more than a single group and priority level is not
  80  * guaranteed.
  81  *
  82  * Flow rules can apply to inbound and/or outbound traffic (ingress/egress).
  83  *
  84  * Several pattern items and actions are valid and can be used in both
  85  * directions. Those valid for only one direction are described as such.
  86  *
  87  * At least one direction must be specified.
  88  *
  89  * Specifying both directions at once for a given rule is not recommended
  90  * but may be valid in a few cases (e.g. shared counter).
  91  */
  92 struct rte_flow_attr {
  93         uint32_t group; /**< Priority group. */
  94         uint32_t priority; /**< Priority level within group. */
  95         uint32_t ingress:1; /**< Rule applies to ingress traffic. */
  96         uint32_t egress:1; /**< Rule applies to egress traffic. */
  97         uint32_t reserved:30; /**< Reserved, must be zero. */
  98 };
  99
 100 /**
 101  * Matching pattern item types.
 102  *
 103  * Pattern items fall in two categories:
 104  *
 105  * - Matching protocol headers and packet data (ANY, RAW, ETH, VLAN, IPV4,
 106  *   IPV6, ICMP, UDP, TCP, SCTP, VXLAN and so on), usually associated with a
 107  *   specification structure. These must be stacked in the same order as the
 108  *   protocol layers to match, starting from the lowest.
 109  *
 110  * - Matching meta-data or affecting pattern processing (END, VOID, INVERT,
 111  *   PF, VF, PORT and so on), often without a specification structure. Since
 112  *   they do not match packet contents, these can be specified anywhere
 113  *   within item lists without affecting others.
 114  *
 115  * See the description of individual types for more information. Those
 116  * marked with [META] fall into the second category.
 117  */
 118 enum rte_flow_item_type {
 119         /**
 120          * [META]
 121          *
 122          * End marker for item lists. Prevents further processing of items,
 123          * thereby ending the pattern.
 124          *
 125          * No associated specification structure.
 126          */
 127         RTE_FLOW_ITEM_TYPE_END,
 128
 129         /**
 130          * [META]
 131          *
 132          * Used as a placeholder for convenience. It is ignored and simply
 133          * discarded by PMDs.
 134          *
 135          * No associated specification structure.
 136          */
 137         RTE_FLOW_ITEM_TYPE_VOID,
 138
 139         /**
 140          * [META]
 141          *
 142          * Inverted matching, i.e. process packets that do not match the
 143          * pattern.
 144          *
 145          * No associated specification structure.
 146          */
 147         RTE_FLOW_ITEM_TYPE_INVERT,
 148
 149         /**
 150          * Matches any protocol in place of the current layer, a single ANY
 151          * may also stand for several protocol layers.
 152          *
 153          * See struct rte_flow_item_any.
 154          */
 155         RTE_FLOW_ITEM_TYPE_ANY,
 156
 157         /**
 158          * [META]
 159          *
 160          * Matches packets addressed to the physical function of the device.
 161          *
 162          * If the underlying device function differs from the one that would
 163          * normally receive the matched traffic, specifying this item
 164          * prevents it from reaching that device unless the flow rule
 165          * contains a PF action. Packets are not duplicated between device
 166          * instances by default.
 167          *
 168          * No associated specification structure.
 169          */
 170         RTE_FLOW_ITEM_TYPE_PF,
 171
 172         /**
 173          * [META]
 174          *
 175          * Matches packets addressed to a virtual function ID of the device.
 176          *
 177          * If the underlying device function differs from the one that would
 178          * normally receive the matched traffic, specifying this item
 179          * prevents it from reaching that device unless the flow rule
 180          * contains a VF action. Packets are not duplicated between device
 181          * instances by default.
 182          *
 183          * See struct rte_flow_item_vf.
 184          */
 185         RTE_FLOW_ITEM_TYPE_VF,
 186
 187         /**
 188          * [META]
 189          *
 190          * Matches packets coming from the specified physical port of the
 191          * underlying device.
 192          *
 193          * The first PORT item overrides the physical port normally
 194          * associated with the specified DPDK input port (port_id). This
 195          * item can be provided several times to match additional physical
 196          * ports.
 197          *
 198          * See struct rte_flow_item_port.
 199          */
 200         RTE_FLOW_ITEM_TYPE_PORT,
 201
 202         /**
 203          * Matches a byte string of a given length at a given offset.
 204          *
 205          * See struct rte_flow_item_raw.
 206          */
 207         RTE_FLOW_ITEM_TYPE_RAW,
 208
 209         /**
 210          * Matches an Ethernet header.
 211          *
 212          * See struct rte_flow_item_eth.
 213          */
 214         RTE_FLOW_ITEM_TYPE_ETH,
 215
 216         /**
 217          * Matches an 802.1Q/ad VLAN tag.
 218          *
 219          * See struct rte_flow_item_vlan.
 220          */
 221         RTE_FLOW_ITEM_TYPE_VLAN,
 222
 223         /**
 224          * Matches an IPv4 header.
 225          *
 226          * See struct rte_flow_item_ipv4.
 227          */
 228         RTE_FLOW_ITEM_TYPE_IPV4,
 229
 230         /**
 231          * Matches an IPv6 header.
 232          *
 233          * See struct rte_flow_item_ipv6.
 234          */
 235         RTE_FLOW_ITEM_TYPE_IPV6,
 236
 237         /**
 238          * Matches an ICMP header.
 239          *
 240          * See struct rte_flow_item_icmp.
 241          */
 242         RTE_FLOW_ITEM_TYPE_ICMP,
 243
 244         /**
 245          * Matches a UDP header.
 246          *
 247          * See struct rte_flow_item_udp.
 248          */
 249         RTE_FLOW_ITEM_TYPE_UDP,
 250
 251         /**
 252          * Matches a TCP header.
 253          *
 254          * See struct rte_flow_item_tcp.
 255          */
 256         RTE_FLOW_ITEM_TYPE_TCP,
 257
 258         /**
 259          * Matches a SCTP header.
 260          *
 261          * See struct rte_flow_item_sctp.
 262          */
 263         RTE_FLOW_ITEM_TYPE_SCTP,
 264
 265         /**
 266          * Matches a VXLAN header.
 267          *
 268          * See struct rte_flow_item_vxlan.
 269          */
 270         RTE_FLOW_ITEM_TYPE_VXLAN,
 271
 272         /**
 273          * Matches a E_TAG header.
 274          *
 275          * See struct rte_flow_item_e_tag.
 276          */
 277         RTE_FLOW_ITEM_TYPE_E_TAG,
 278
 279         /**
 280          * Matches a NVGRE header.
 281          *
 282          * See struct rte_flow_item_nvgre.
 283          */
 284         RTE_FLOW_ITEM_TYPE_NVGRE,
 285 };
 286
 287 /**
 288  * RTE_FLOW_ITEM_TYPE_ANY
 289  *
 290  * Matches any protocol in place of the current layer, a single ANY may also
 291  * stand for several protocol layers.
 292  *
 293  * This is usually specified as the first pattern item when looking for a
 294  * protocol anywhere in a packet.
 295  *
 296  * A zeroed mask stands for any number of layers.
 297  */
 298 struct rte_flow_item_any {
 299         uint32_t num; /**< Number of layers covered. */
 300 };
 301
 302 /** Default mask for RTE_FLOW_ITEM_TYPE_ANY. */
 303 static const struct rte_flow_item_any rte_flow_item_any_mask = {
 304         .num = 0x00000000,
 305 };
 306
 307 /**
 308  * RTE_FLOW_ITEM_TYPE_VF
 309  *
 310  * Matches packets addressed to a virtual function ID of the device.
 311  *
 312  * If the underlying device function differs from the one that would
 313  * normally receive the matched traffic, specifying this item prevents it
 314  * from reaching that device unless the flow rule contains a VF
 315  * action. Packets are not duplicated between device instances by default.
 316  *
 317  * - Likely to return an error or never match any traffic if this causes a
 318  *   VF device to match traffic addressed to a different VF.
 319  * - Can be specified multiple times to match traffic addressed to several
 320  *   VF IDs.
 321  * - Can be combined with a PF item to match both PF and VF traffic.
 322  *
 323  * A zeroed mask can be used to match any VF ID.
 324  */
 325 struct rte_flow_item_vf {
 326         uint32_t id; /**< Destination VF ID. */
 327 };
 328
 329 /** Default mask for RTE_FLOW_ITEM_TYPE_VF. */
 330 static const struct rte_flow_item_vf rte_flow_item_vf_mask = {
 331         .id = 0x00000000,
 332 };
 333
 334 /**
 335  * RTE_FLOW_ITEM_TYPE_PORT
 336  *
 337  * Matches packets coming from the specified physical port of the underlying
 338  * device.
 339  *
 340  * The first PORT item overrides the physical port normally associated with
 341  * the specified DPDK input port (port_id). This item can be provided
 342  * several times to match additional physical ports.
 343  *
 344  * Note that physical ports are not necessarily tied to DPDK input ports
 345  * (port_id) when those are not under DPDK control. Possible values are
 346  * specific to each device, they are not necessarily indexed from zero and
 347  * may not be contiguous.
 348  *
 349  * As a device property, the list of allowed values as well as the value
 350  * associated with a port_id should be retrieved by other means.
 351  *
 352  * A zeroed mask can be used to match any port index.
 353  */
 354 struct rte_flow_item_port {
 355         uint32_t index; /**< Physical port index. */
 356 };
 357
 358 /** Default mask for RTE_FLOW_ITEM_TYPE_PORT. */
 359 static const struct rte_flow_item_port rte_flow_item_port_mask = {
 360         .index = 0x00000000,
 361 };
 362
 363 /**
 364  * RTE_FLOW_ITEM_TYPE_RAW
 365  *
 366  * Matches a byte string of a given length at a given offset.
 367  *
 368  * Offset is either absolute (using the start of the packet) or relative to
 369  * the end of the previous matched item in the stack, in which case negative
 370  * values are allowed.
 371  *
 372  * If search is enabled, offset is used as the starting point. The search
 373  * area can be delimited by setting limit to a nonzero value, which is the
 374  * maximum number of bytes after offset where the pattern may start.
 375  *
 376  * Matching a zero-length pattern is allowed, doing so resets the relative
 377  * offset for subsequent items.
 378  *
 379  * This type does not support ranges (struct rte_flow_item.last).
 380  */
 381 struct rte_flow_item_raw {
 382         uint32_t relative:1; /**< Look for pattern after the previous item. */
 383         uint32_t search:1; /**< Search pattern from offset (see also limit). */
 384         uint32_t reserved:30; /**< Reserved, must be set to zero. */
 385         int32_t offset; /**< Absolute or relative offset for pattern. */
 386         uint16_t limit; /**< Search area limit for start of pattern. */
 387         uint16_t length; /**< Pattern length. */
 388         uint8_t pattern[]; /**< Byte string to look for. */
 389 };
 390
 391 /** Default mask for RTE_FLOW_ITEM_TYPE_RAW. */
 392 static const struct rte_flow_item_raw rte_flow_item_raw_mask = {
 393         .relative = 1,
 394         .search = 1,
 395         .reserved = 0x3fffffff,
 396         .offset = 0xffffffff,
 397         .limit = 0xffff,
 398         .length = 0xffff,
 399 };
 400
 401 /**
 402  * RTE_FLOW_ITEM_TYPE_ETH
 403  *
 404  * Matches an Ethernet header.
 405  */
 406 struct rte_flow_item_eth {
 407         struct ether_addr dst; /**< Destination MAC. */
 408         struct ether_addr src; /**< Source MAC. */
 409         uint16_t type; /**< EtherType. */
 410 };
 411
 412 /** Default mask for RTE_FLOW_ITEM_TYPE_ETH. */
 413 static const struct rte_flow_item_eth rte_flow_item_eth_mask = {
 414         .dst.addr_bytes = "\xff\xff\xff\xff\xff\xff",
 415         .src.addr_bytes = "\xff\xff\xff\xff\xff\xff",
 416         .type = 0x0000,
 417 };
 418
 419 /**
 420  * RTE_FLOW_ITEM_TYPE_VLAN
 421  *
 422  * Matches an 802.1Q/ad VLAN tag.
 423  *
 424  * This type normally follows either RTE_FLOW_ITEM_TYPE_ETH or
 425  * RTE_FLOW_ITEM_TYPE_VLAN.
 426  */
 427 struct rte_flow_item_vlan {
 428         uint16_t tpid; /**< Tag protocol identifier. */
 429         uint16_t tci; /**< Tag control information. */
 430 };
 431
 432 /** Default mask for RTE_FLOW_ITEM_TYPE_VLAN. */
 433 static const struct rte_flow_item_vlan rte_flow_item_vlan_mask = {
 434         .tpid = 0x0000,
 435         .tci = 0xffff,
 436 };
 437
 438 /**
 439  * RTE_FLOW_ITEM_TYPE_IPV4
 440  *
 441  * Matches an IPv4 header.
 442  *
 443  * Note: IPv4 options are handled by dedicated pattern items.
 444  */
 445 struct rte_flow_item_ipv4 {
 446         struct ipv4_hdr hdr; /**< IPv4 header definition. */
 447 };
 448
 449 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV4. */
 450 static const struct rte_flow_item_ipv4 rte_flow_item_ipv4_mask = {
 451         .hdr = {
 452                 .src_addr = 0xffffffff,
 453                 .dst_addr = 0xffffffff,
 454         },
 455 };
 456
 457 /**
 458  * RTE_FLOW_ITEM_TYPE_IPV6.
 459  *
 460  * Matches an IPv6 header.
 461  *
 462  * Note: IPv6 options are handled by dedicated pattern items.
 463  */
 464 struct rte_flow_item_ipv6 {
 465         struct ipv6_hdr hdr; /**< IPv6 header definition. */
 466 };
 467
 468 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV6. */
 469 static const struct rte_flow_item_ipv6 rte_flow_item_ipv6_mask = {
 470         .hdr = {
 471                 .src_addr =
 472                         "\xff\xff\xff\xff\xff\xff\xff\xff"
 473                         "\xff\xff\xff\xff\xff\xff\xff\xff",
 474                 .dst_addr =
 475                         "\xff\xff\xff\xff\xff\xff\xff\xff"
 476                         "\xff\xff\xff\xff\xff\xff\xff\xff",
 477         },
 478 };
 479
 480 /**
 481  * RTE_FLOW_ITEM_TYPE_ICMP.
 482  *
 483  * Matches an ICMP header.
 484  */
 485 struct rte_flow_item_icmp {
 486         struct icmp_hdr hdr; /**< ICMP header definition. */
 487 };
 488
 489 /** Default mask for RTE_FLOW_ITEM_TYPE_ICMP. */
 490 static const struct rte_flow_item_icmp rte_flow_item_icmp_mask = {
 491         .hdr = {
 492                 .icmp_type = 0xff,
 493                 .icmp_code = 0xff,
 494         },
 495 };
 496
 497 /**
 498  * RTE_FLOW_ITEM_TYPE_UDP.
 499  *
 500  * Matches a UDP header.
 501  */
 502 struct rte_flow_item_udp {
 503         struct udp_hdr hdr; /**< UDP header definition. */
 504 };
 505
 506 /** Default mask for RTE_FLOW_ITEM_TYPE_UDP. */
 507 static const struct rte_flow_item_udp rte_flow_item_udp_mask = {
 508         .hdr = {
 509                 .src_port = 0xffff,
 510                 .dst_port = 0xffff,
 511         },
 512 };
 513
 514 /**
 515  * RTE_FLOW_ITEM_TYPE_TCP.
 516  *
 517  * Matches a TCP header.
 518  */
 519 struct rte_flow_item_tcp {
 520         struct tcp_hdr hdr; /**< TCP header definition. */
 521 };
 522
 523 /** Default mask for RTE_FLOW_ITEM_TYPE_TCP. */
 524 static const struct rte_flow_item_tcp rte_flow_item_tcp_mask = {
 525         .hdr = {
 526                 .src_port = 0xffff,
 527                 .dst_port = 0xffff,
 528         },
 529 };
 530
 531 /**
 532  * RTE_FLOW_ITEM_TYPE_SCTP.
 533  *
 534  * Matches a SCTP header.
 535  */
 536 struct rte_flow_item_sctp {
 537         struct sctp_hdr hdr; /**< SCTP header definition. */
 538 };
 539
 540 /** Default mask for RTE_FLOW_ITEM_TYPE_SCTP. */
 541 static const struct rte_flow_item_sctp rte_flow_item_sctp_mask = {
 542         .hdr = {
 543                 .src_port = 0xffff,
 544                 .dst_port = 0xffff,
 545         },
 546 };
 547
 548 /**
 549  * RTE_FLOW_ITEM_TYPE_VXLAN.
 550  *
 551  * Matches a VXLAN header (RFC 7348).
 552  */
 553 struct rte_flow_item_vxlan {
 554         uint8_t flags; /**< Normally 0x08 (I flag). */
 555         uint8_t rsvd0[3]; /**< Reserved, normally 0x000000. */
 556         uint8_t vni[3]; /**< VXLAN identifier. */
 557         uint8_t rsvd1; /**< Reserved, normally 0x00. */
 558 };
 559
 560 /** Default mask for RTE_FLOW_ITEM_TYPE_VXLAN. */
 561 static const struct rte_flow_item_vxlan rte_flow_item_vxlan_mask = {
 562         .vni = "\xff\xff\xff",
 563 };
 564
 565 /**
 566  * RTE_FLOW_ITEM_TYPE_E_TAG.
 567  *
 568  * Matches a E-tag header.
 569  */
 570 struct rte_flow_item_e_tag {
 571         uint16_t tpid; /**< Tag protocol identifier (0x893F). */
 572         /**
 573          * E-Tag control information (E-TCI).
 574          * E-PCP (3b), E-DEI (1b), ingress E-CID base (12b).
 575          */
 576         uint16_t epcp_edei_in_ecid_b;
 577         /** Reserved (2b), GRP (2b), E-CID base (12b). */
 578         uint16_t rsvd_grp_ecid_b;
 579         uint8_t in_ecid_e; /**< Ingress E-CID ext. */
 580         uint8_t ecid_e; /**< E-CID ext. */
 581 };
 582
 583 /**
 584  * RTE_FLOW_ITEM_TYPE_NVGRE.
 585  *
 586  * Matches a NVGRE header.
 587  */
 588 struct rte_flow_item_nvgre {
 589         /**
 590          * Checksum (1b), undefined (1b), key bit (1b), sequence number (1b),
 591          * reserved 0 (9b), version (3b).
 592          *
 593          * c_k_s_rsvd0_ver must have value 0x2000 according to RFC 7637.
 594          */
 595         uint16_t c_k_s_rsvd0_ver;
 596         uint16_t protocol; /**< Protocol type (0x6558). */
 597         uint8_t tni[3]; /**< Virtual subnet ID. */
 598         uint8_t flow_id; /**< Flow ID. */
 599 };
 600
 601 /**
 602  * Matching pattern item definition.
 603  *
 604  * A pattern is formed by stacking items starting from the lowest protocol
 605  * layer to match. This stacking restriction does not apply to meta items
 606  * which can be placed anywhere in the stack without affecting the meaning
 607  * of the resulting pattern.
 608  *
 609  * Patterns are terminated by END items.
 610  *
 611  * The spec field should be a valid pointer to a structure of the related
 612  * item type. It may remain unspecified (NULL) in many cases to request
 613  * broad (nonspecific) matching. In such cases, last and mask must also be
 614  * set to NULL.
 615  *
 616  * Optionally, last can point to a structure of the same type to define an
 617  * inclusive range. This is mostly supported by integer and address fields,
 618  * may cause errors otherwise. Fields that do not support ranges must be set
 619  * to 0 or to the same value as the corresponding fields in spec.
 620  *
 621  * Only the fields defined to nonzero values in the default masks (see
 622  * rte_flow_item_{name}_mask constants) are considered relevant by
 623  * default. This can be overridden by providing a mask structure of the
 624  * same type with applicable bits set to one. It can also be used to
 625  * partially filter out specific fields (e.g. as an alternate mean to match
 626  * ranges of IP addresses).
 627  *
 628  * Mask is a simple bit-mask applied before interpreting the contents of
 629  * spec and last, which may yield unexpected results if not used
 630  * carefully. For example, if for an IPv4 address field, spec provides
 631  * 10.1.2.3, last provides 10.3.4.5 and mask provides 255.255.0.0, the
 632  * effective range becomes 10.1.0.0 to 10.3.255.255.
 633  */
 634 struct rte_flow_item {
 635         enum rte_flow_item_type type; /**< Item type. */
 636         const void *spec; /**< Pointer to item specification structure. */
 637         const void *last; /**< Defines an inclusive range (spec to last). */
 638         const void *mask; /**< Bit-mask applied to spec and last. */
 639 };
 640
 641 /**
 642  * Action types.
 643  *
 644  * Each possible action is represented by a type. Some have associated
 645  * configuration structures. Several actions combined in a list can be
 646  * affected to a flow rule. That list is not ordered.
 647  *
 648  * They fall in three categories:
 649  *
 650  * - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
 651  *   processing matched packets by subsequent flow rules, unless overridden
 652  *   with PASSTHRU.
 653  *
 654  * - Non terminating actions (PASSTHRU, DUP) that leave matched packets up
 655  *   for additional processing by subsequent flow rules.
 656  *
 657  * - Other non terminating meta actions that do not affect the fate of
 658  *   packets (END, VOID, MARK, FLAG, COUNT).
 659  *
 660  * When several actions are combined in a flow rule, they should all have
 661  * different types (e.g. dropping a packet twice is not possible).
 662  *
 663  * Only the last action of a given type is taken into account. PMDs still
 664  * perform error checking on the entire list.
 665  *
 666  * Note that PASSTHRU is the only action able to override a terminating
 667  * rule.
 668  */
 669 enum rte_flow_action_type {
 670         /**
 671          * [META]
 672          *
 673          * End marker for action lists. Prevents further processing of
 674          * actions, thereby ending the list.
 675          *
 676          * No associated configuration structure.
 677          */
 678         RTE_FLOW_ACTION_TYPE_END,
 679
 680         /**
 681          * [META]
 682          *
 683          * Used as a placeholder for convenience. It is ignored and simply
 684          * discarded by PMDs.
 685          *
 686          * No associated configuration structure.
 687          */
 688         RTE_FLOW_ACTION_TYPE_VOID,
 689
 690         /**
 691          * Leaves packets up for additional processing by subsequent flow
 692          * rules. This is the default when a rule does not contain a
 693          * terminating action, but can be specified to force a rule to
 694          * become non-terminating.
 695          *
 696          * No associated configuration structure.
 697          */
 698         RTE_FLOW_ACTION_TYPE_PASSTHRU,
 699
 700         /**
 701          * [META]
 702          *
 703          * Attaches an integer value to packets and sets PKT_RX_FDIR and
 704          * PKT_RX_FDIR_ID mbuf flags.
 705          *
 706          * See struct rte_flow_action_mark.
 707          */
 708         RTE_FLOW_ACTION_TYPE_MARK,
 709
 710         /**
 711          * [META]
 712          *
 713          * Flags packets. Similar to MARK without a specific value; only
 714          * sets the PKT_RX_FDIR mbuf flag.
 715          *
 716          * No associated configuration structure.
 717          */
 718         RTE_FLOW_ACTION_TYPE_FLAG,
 719
 720         /**
 721          * Assigns packets to a given queue index.
 722          *
 723          * See struct rte_flow_action_queue.
 724          */
 725         RTE_FLOW_ACTION_TYPE_QUEUE,
 726
 727         /**
 728          * Drops packets.
 729          *
 730          * PASSTHRU overrides this action if both are specified.
 731          *
 732          * No associated configuration structure.
 733          */
 734         RTE_FLOW_ACTION_TYPE_DROP,
 735
 736         /**
 737          * [META]
 738          *
 739          * Enables counters for this rule.
 740          *
 741          * These counters can be retrieved and reset through rte_flow_query(),
 742          * see struct rte_flow_query_count.
 743          *
 744          * No associated configuration structure.
 745          */
 746         RTE_FLOW_ACTION_TYPE_COUNT,
 747
 748         /**
 749          * Duplicates packets to a given queue index.
 750          *
 751          * This is normally combined with QUEUE, however when used alone, it
 752          * is actually similar to QUEUE + PASSTHRU.
 753          *
 754          * See struct rte_flow_action_dup.
 755          */
 756         RTE_FLOW_ACTION_TYPE_DUP,
 757
 758         /**
 759          * Similar to QUEUE, except RSS is additionally performed on packets
 760          * to spread them among several queues according to the provided
 761          * parameters.
 762          *
 763          * See struct rte_flow_action_rss.
 764          */
 765         RTE_FLOW_ACTION_TYPE_RSS,
 766
 767         /**
 768          * Redirects packets to the physical function (PF) of the current
 769          * device.
 770          *
 771          * No associated configuration structure.
 772          */
 773         RTE_FLOW_ACTION_TYPE_PF,
 774
 775         /**
 776          * Redirects packets to the virtual function (VF) of the current
 777          * device with the specified ID.
 778          *
 779          * See struct rte_flow_action_vf.
 780          */
 781         RTE_FLOW_ACTION_TYPE_VF,
 782 };
 783
 784 /**
 785  * RTE_FLOW_ACTION_TYPE_MARK
 786  *
 787  * Attaches an integer value to packets and sets PKT_RX_FDIR and
 788  * PKT_RX_FDIR_ID mbuf flags.
 789  *
 790  * This value is arbitrary and application-defined. Maximum allowed value
 791  * depends on the underlying implementation. It is returned in the
 792  * hash.fdir.hi mbuf field.
 793  */
 794 struct rte_flow_action_mark {
 795         uint32_t id; /**< Integer value to return with packets. */
 796 };
 797
 798 /**
 799  * RTE_FLOW_ACTION_TYPE_QUEUE
 800  *
 801  * Assign packets to a given queue index.
 802  *
 803  * Terminating by default.
 804  */
 805 struct rte_flow_action_queue {
 806         uint16_t index; /**< Queue index to use. */
 807 };
 808
 809 /**
 810  * RTE_FLOW_ACTION_TYPE_COUNT (query)
 811  *
 812  * Query structure to retrieve and reset flow rule counters.
 813  */
 814 struct rte_flow_query_count {
 815         uint32_t reset:1; /**< Reset counters after query [in]. */
 816         uint32_t hits_set:1; /**< hits field is set [out]. */
 817         uint32_t bytes_set:1; /**< bytes field is set [out]. */
 818         uint32_t reserved:29; /**< Reserved, must be zero [in, out]. */
 819         uint64_t hits; /**< Number of hits for this rule [out]. */
 820         uint64_t bytes; /**< Number of bytes through this rule [out]. */
 821 };
 822
 823 /**
 824  * RTE_FLOW_ACTION_TYPE_DUP
 825  *
 826  * Duplicates packets to a given queue index.
 827  *
 828  * This is normally combined with QUEUE, however when used alone, it is
 829  * actually similar to QUEUE + PASSTHRU.
 830  *
 831  * Non-terminating by default.
 832  */
 833 struct rte_flow_action_dup {
 834         uint16_t index; /**< Queue index to duplicate packets to. */
 835 };
 836
 837 /**
 838  * RTE_FLOW_ACTION_TYPE_RSS
 839  *
 840  * Similar to QUEUE, except RSS is additionally performed on packets to
 841  * spread them among several queues according to the provided parameters.
 842  *
 843  * Note: RSS hash result is stored in the hash.rss mbuf field which overlaps
 844  * hash.fdir.lo. Since the MARK action sets the hash.fdir.hi field only,
 845  * both can be requested simultaneously.
 846  *
 847  * Terminating by default.
 848  */
 849 struct rte_flow_action_rss {
 850         const struct rte_eth_rss_conf *rss_conf; /**< RSS parameters. */
 851         uint16_t num; /**< Number of entries in queue[]. */
 852         uint16_t queue[]; /**< Queues indices to use. */
 853 };
 854
 855 /**
 856  * RTE_FLOW_ACTION_TYPE_VF
 857  *
 858  * Redirects packets to a virtual function (VF) of the current device.
 859  *
 860  * Packets matched by a VF pattern item can be redirected to their original
 861  * VF ID instead of the specified one. This parameter may not be available
 862  * and is not guaranteed to work properly if the VF part is matched by a
 863  * prior flow rule or if packets are not addressed to a VF in the first
 864  * place.
 865  *
 866  * Terminating by default.
 867  */
 868 struct rte_flow_action_vf {
 869         uint32_t original:1; /**< Use original VF ID if possible. */
 870         uint32_t reserved:31; /**< Reserved, must be zero. */
 871         uint32_t id; /**< VF ID to redirect packets to. */
 872 };
 873
 874 /**
 875  * Definition of a single action.
 876  *
 877  * A list of actions is terminated by a END action.
 878  *
 879  * For simple actions without a configuration structure, conf remains NULL.
 880  */
 881 struct rte_flow_action {
 882         enum rte_flow_action_type type; /**< Action type. */
 883         const void *conf; /**< Pointer to action configuration structure. */
 884 };
 885
 886 /**
 887  * Opaque type returned after successfully creating a flow.
 888  *
 889  * This handle can be used to manage and query the related flow (e.g. to
 890  * destroy it or retrieve counters).
 891  */
 892 struct rte_flow;
 893
 894 /**
 895  * Verbose error types.
 896  *
 897  * Most of them provide the type of the object referenced by struct
 898  * rte_flow_error.cause.
 899  */
 900 enum rte_flow_error_type {
 901         RTE_FLOW_ERROR_TYPE_NONE, /**< No error. */
 902         RTE_FLOW_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
 903         RTE_FLOW_ERROR_TYPE_HANDLE, /**< Flow rule (handle). */
 904         RTE_FLOW_ERROR_TYPE_ATTR_GROUP, /**< Group field. */
 905         RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */
 906         RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */
 907         RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */
 908         RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */
 909         RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */
 910         RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */
 911         RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */
 912         RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */
 913 };
 914
 915 /**
 916  * Verbose error structure definition.
 917  *
 918  * This object is normally allocated by applications and set by PMDs, the
 919  * message points to a constant string which does not need to be freed by
 920  * the application, however its pointer can be considered valid only as long
 921  * as its associated DPDK port remains configured. Closing the underlying
 922  * device or unloading the PMD invalidates it.
 923  *
 924  * Both cause and message may be NULL regardless of the error type.
 925  */
 926 struct rte_flow_error {
 927         enum rte_flow_error_type type; /**< Cause field and error types. */
 928         const void *cause; /**< Object responsible for the error. */
 929         const char *message; /**< Human-readable error message. */
 930 };
 931
 932 /**
 933  * Check whether a flow rule can be created on a given port.
 934  *
 935  * While this function has no effect on the target device, the flow rule is
 936  * validated against its current configuration state and the returned value
 937  * should be considered valid by the caller for that state only.
 938  *
 939  * The returned value is guaranteed to remain valid only as long as no
 940  * successful calls to rte_flow_create() or rte_flow_destroy() are made in
 941  * the meantime and no device parameter affecting flow rules in any way are
 942  * modified, due to possible collisions or resource limitations (although in
 943  * such cases EINVAL should not be returned).
 944  *
 945  * @param port_id
 946  *   Port identifier of Ethernet device.
 947  * @param[in] attr
 948  *   Flow rule attributes.
 949  * @param[in] pattern
 950  *   Pattern specification (list terminated by the END pattern item).
 951  * @param[in] actions
 952  *   Associated actions (list terminated by the END action).
 953  * @param[out] error
 954  *   Perform verbose error reporting if not NULL. PMDs initialize this
 955  *   structure in case of error only.
 956  *
 957  * @return
 958  *   0 if flow rule is valid and can be created. A negative errno value
 959  *   otherwise (rte_errno is also set), the following errors are defined:
 960  *
 961  *   -ENOSYS: underlying device does not support this functionality.
 962  *
 963  *   -EINVAL: unknown or invalid rule specification.
 964  *
 965  *   -ENOTSUP: valid but unsupported rule specification (e.g. partial
 966  *   bit-masks are unsupported).
 967  *
 968  *   -EEXIST: collision with an existing rule.
 969  *
 970  *   -ENOMEM: not enough resources.
 971  *
 972  *   -EBUSY: action cannot be performed due to busy device resources, may
 973  *   succeed if the affected queues or even the entire port are in a stopped
 974  *   state (see rte_eth_dev_rx_queue_stop() and rte_eth_dev_stop()).
 975  */
 976 int
 977 rte_flow_validate(uint8_t port_id,
 978                   const struct rte_flow_attr *attr,
 979                   const struct rte_flow_item pattern[],
 980                   const struct rte_flow_action actions[],
 981                   struct rte_flow_error *error);
 982
 983 /**
 984  * Create a flow rule on a given port.
 985  *
 986  * @param port_id
 987  *   Port identifier of Ethernet device.
 988  * @param[in] attr
 989  *   Flow rule attributes.
 990  * @param[in] pattern
 991  *   Pattern specification (list terminated by the END pattern item).
 992  * @param[in] actions
 993  *   Associated actions (list terminated by the END action).
 994  * @param[out] error
 995  *   Perform verbose error reporting if not NULL. PMDs initialize this
 996  *   structure in case of error only.
 997  *
 998  * @return
 999  *   A valid handle in case of success, NULL otherwise and rte_errno is set
1000  *   to the positive version of one of the error codes defined for
1001  *   rte_flow_validate().
1002  */
1003 struct rte_flow *
1004 rte_flow_create(uint8_t port_id,
1005                 const struct rte_flow_attr *attr,
1006                 const struct rte_flow_item pattern[],
1007                 const struct rte_flow_action actions[],
1008                 struct rte_flow_error *error);
1009
1010 /**
1011  * Destroy a flow rule on a given port.
1012  *
1013  * Failure to destroy a flow rule handle may occur when other flow rules
1014  * depend on it, and destroying it would result in an inconsistent state.
1015  *
1016  * This function is only guaranteed to succeed if handles are destroyed in
1017  * reverse order of their creation.
1018  *
1019  * @param port_id
1020  *   Port identifier of Ethernet device.
1021  * @param flow
1022  *   Flow rule handle to destroy.
1023  * @param[out] error
1024  *   Perform verbose error reporting if not NULL. PMDs initialize this
1025  *   structure in case of error only.
1026  *
1027  * @return
1028  *   0 on success, a negative errno value otherwise and rte_errno is set.
1029  */
1030 int
1031 rte_flow_destroy(uint8_t port_id,
1032                  struct rte_flow *flow,
1033                  struct rte_flow_error *error);
1034
1035 /**
1036  * Destroy all flow rules associated with a port.
1037  *
1038  * In the unlikely event of failure, handles are still considered destroyed
1039  * and no longer valid but the port must be assumed to be in an inconsistent
1040  * state.
1041  *
1042  * @param port_id
1043  *   Port identifier of Ethernet device.
1044  * @param[out] error
1045  *   Perform verbose error reporting if not NULL. PMDs initialize this
1046  *   structure in case of error only.
1047  *
1048  * @return
1049  *   0 on success, a negative errno value otherwise and rte_errno is set.
1050  */
1051 int
1052 rte_flow_flush(uint8_t port_id,
1053                struct rte_flow_error *error);
1054
1055 /**
1056  * Query an existing flow rule.
1057  *
1058  * This function allows retrieving flow-specific data such as counters.
1059  * Data is gathered by special actions which must be present in the flow
1060  * rule definition.
1061  *
1062  * \see RTE_FLOW_ACTION_TYPE_COUNT
1063  *
1064  * @param port_id
1065  *   Port identifier of Ethernet device.
1066  * @param flow
1067  *   Flow rule handle to query.
1068  * @param action
1069  *   Action type to query.
1070  * @param[in, out] data
1071  *   Pointer to storage for the associated query data type.
1072  * @param[out] error
1073  *   Perform verbose error reporting if not NULL. PMDs initialize this
1074  *   structure in case of error only.
1075  *
1076  * @return
1077  *   0 on success, a negative errno value otherwise and rte_errno is set.
1078  */
1079 int
1080 rte_flow_query(uint8_t port_id,
1081                struct rte_flow *flow,
1082                enum rte_flow_action_type action,
1083                void *data,
1084                struct rte_flow_error *error);
1085
1086 #ifdef __cplusplus
1087 }
1088 #endif
1089
1090 #endif /* RTE_FLOW_H_ */