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          * Matches a MPLS header.
 288          *
 289          * See struct rte_flow_item_mpls.
 290          */
 291         RTE_FLOW_ITEM_TYPE_MPLS,
 292
 293         /**
 294          * Matches a GRE header.
 295          *
 296          * See struct rte_flow_item_gre.
 297          */
 298         RTE_FLOW_ITEM_TYPE_GRE,
 299 };
 300
 301 /**
 302  * RTE_FLOW_ITEM_TYPE_ANY
 303  *
 304  * Matches any protocol in place of the current layer, a single ANY may also
 305  * stand for several protocol layers.
 306  *
 307  * This is usually specified as the first pattern item when looking for a
 308  * protocol anywhere in a packet.
 309  *
 310  * A zeroed mask stands for any number of layers.
 311  */
 312 struct rte_flow_item_any {
 313         uint32_t num; /**< Number of layers covered. */
 314 };
 315
 316 /** Default mask for RTE_FLOW_ITEM_TYPE_ANY. */
 317 #ifndef __cplusplus
 318 static const struct rte_flow_item_any rte_flow_item_any_mask = {
 319         .num = 0x00000000,
 320 };
 321 #endif
 322
 323 /**
 324  * RTE_FLOW_ITEM_TYPE_VF
 325  *
 326  * Matches packets addressed to a virtual function ID of the device.
 327  *
 328  * If the underlying device function differs from the one that would
 329  * normally receive the matched traffic, specifying this item prevents it
 330  * from reaching that device unless the flow rule contains a VF
 331  * action. Packets are not duplicated between device instances by default.
 332  *
 333  * - Likely to return an error or never match any traffic if this causes a
 334  *   VF device to match traffic addressed to a different VF.
 335  * - Can be specified multiple times to match traffic addressed to several
 336  *   VF IDs.
 337  * - Can be combined with a PF item to match both PF and VF traffic.
 338  *
 339  * A zeroed mask can be used to match any VF ID.
 340  */
 341 struct rte_flow_item_vf {
 342         uint32_t id; /**< Destination VF ID. */
 343 };
 344
 345 /** Default mask for RTE_FLOW_ITEM_TYPE_VF. */
 346 #ifndef __cplusplus
 347 static const struct rte_flow_item_vf rte_flow_item_vf_mask = {
 348         .id = 0x00000000,
 349 };
 350 #endif
 351
 352 /**
 353  * RTE_FLOW_ITEM_TYPE_PORT
 354  *
 355  * Matches packets coming from the specified physical port of the underlying
 356  * device.
 357  *
 358  * The first PORT item overrides the physical port normally associated with
 359  * the specified DPDK input port (port_id). This item can be provided
 360  * several times to match additional physical ports.
 361  *
 362  * Note that physical ports are not necessarily tied to DPDK input ports
 363  * (port_id) when those are not under DPDK control. Possible values are
 364  * specific to each device, they are not necessarily indexed from zero and
 365  * may not be contiguous.
 366  *
 367  * As a device property, the list of allowed values as well as the value
 368  * associated with a port_id should be retrieved by other means.
 369  *
 370  * A zeroed mask can be used to match any port index.
 371  */
 372 struct rte_flow_item_port {
 373         uint32_t index; /**< Physical port index. */
 374 };
 375
 376 /** Default mask for RTE_FLOW_ITEM_TYPE_PORT. */
 377 #ifndef __cplusplus
 378 static const struct rte_flow_item_port rte_flow_item_port_mask = {
 379         .index = 0x00000000,
 380 };
 381 #endif
 382
 383 /**
 384  * RTE_FLOW_ITEM_TYPE_RAW
 385  *
 386  * Matches a byte string of a given length at a given offset.
 387  *
 388  * Offset is either absolute (using the start of the packet) or relative to
 389  * the end of the previous matched item in the stack, in which case negative
 390  * values are allowed.
 391  *
 392  * If search is enabled, offset is used as the starting point. The search
 393  * area can be delimited by setting limit to a nonzero value, which is the
 394  * maximum number of bytes after offset where the pattern may start.
 395  *
 396  * Matching a zero-length pattern is allowed, doing so resets the relative
 397  * offset for subsequent items.
 398  *
 399  * This type does not support ranges (struct rte_flow_item.last).
 400  */
 401 struct rte_flow_item_raw {
 402         uint32_t relative:1; /**< Look for pattern after the previous item. */
 403         uint32_t search:1; /**< Search pattern from offset (see also limit). */
 404         uint32_t reserved:30; /**< Reserved, must be set to zero. */
 405         int32_t offset; /**< Absolute or relative offset for pattern. */
 406         uint16_t limit; /**< Search area limit for start of pattern. */
 407         uint16_t length; /**< Pattern length. */
 408         uint8_t pattern[]; /**< Byte string to look for. */
 409 };
 410
 411 /** Default mask for RTE_FLOW_ITEM_TYPE_RAW. */
 412 #ifndef __cplusplus
 413 static const struct rte_flow_item_raw rte_flow_item_raw_mask = {
 414         .relative = 1,
 415         .search = 1,
 416         .reserved = 0x3fffffff,
 417         .offset = 0xffffffff,
 418         .limit = 0xffff,
 419         .length = 0xffff,
 420 };
 421 #endif
 422
 423 /**
 424  * RTE_FLOW_ITEM_TYPE_ETH
 425  *
 426  * Matches an Ethernet header.
 427  */
 428 struct rte_flow_item_eth {
 429         struct ether_addr dst; /**< Destination MAC. */
 430         struct ether_addr src; /**< Source MAC. */
 431         uint16_t type; /**< EtherType. */
 432 };
 433
 434 /** Default mask for RTE_FLOW_ITEM_TYPE_ETH. */
 435 #ifndef __cplusplus
 436 static const struct rte_flow_item_eth rte_flow_item_eth_mask = {
 437         .dst.addr_bytes = "\xff\xff\xff\xff\xff\xff",
 438         .src.addr_bytes = "\xff\xff\xff\xff\xff\xff",
 439         .type = 0x0000,
 440 };
 441 #endif
 442
 443 /**
 444  * RTE_FLOW_ITEM_TYPE_VLAN
 445  *
 446  * Matches an 802.1Q/ad VLAN tag.
 447  *
 448  * This type normally follows either RTE_FLOW_ITEM_TYPE_ETH or
 449  * RTE_FLOW_ITEM_TYPE_VLAN.
 450  */
 451 struct rte_flow_item_vlan {
 452         uint16_t tpid; /**< Tag protocol identifier. */
 453         uint16_t tci; /**< Tag control information. */
 454 };
 455
 456 /** Default mask for RTE_FLOW_ITEM_TYPE_VLAN. */
 457 #ifndef __cplusplus
 458 static const struct rte_flow_item_vlan rte_flow_item_vlan_mask = {
 459         .tpid = 0x0000,
 460         .tci = 0xffff,
 461 };
 462 #endif
 463
 464 /**
 465  * RTE_FLOW_ITEM_TYPE_IPV4
 466  *
 467  * Matches an IPv4 header.
 468  *
 469  * Note: IPv4 options are handled by dedicated pattern items.
 470  */
 471 struct rte_flow_item_ipv4 {
 472         struct ipv4_hdr hdr; /**< IPv4 header definition. */
 473 };
 474
 475 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV4. */
 476 #ifndef __cplusplus
 477 static const struct rte_flow_item_ipv4 rte_flow_item_ipv4_mask = {
 478         .hdr = {
 479                 .src_addr = 0xffffffff,
 480                 .dst_addr = 0xffffffff,
 481         },
 482 };
 483 #endif
 484
 485 /**
 486  * RTE_FLOW_ITEM_TYPE_IPV6.
 487  *
 488  * Matches an IPv6 header.
 489  *
 490  * Note: IPv6 options are handled by dedicated pattern items.
 491  */
 492 struct rte_flow_item_ipv6 {
 493         struct ipv6_hdr hdr; /**< IPv6 header definition. */
 494 };
 495
 496 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV6. */
 497 #ifndef __cplusplus
 498 static const struct rte_flow_item_ipv6 rte_flow_item_ipv6_mask = {
 499         .hdr = {
 500                 .src_addr =
 501                         "\xff\xff\xff\xff\xff\xff\xff\xff"
 502                         "\xff\xff\xff\xff\xff\xff\xff\xff",
 503                 .dst_addr =
 504                         "\xff\xff\xff\xff\xff\xff\xff\xff"
 505                         "\xff\xff\xff\xff\xff\xff\xff\xff",
 506         },
 507 };
 508 #endif
 509
 510 /**
 511  * RTE_FLOW_ITEM_TYPE_ICMP.
 512  *
 513  * Matches an ICMP header.
 514  */
 515 struct rte_flow_item_icmp {
 516         struct icmp_hdr hdr; /**< ICMP header definition. */
 517 };
 518
 519 /** Default mask for RTE_FLOW_ITEM_TYPE_ICMP. */
 520 #ifndef __cplusplus
 521 static const struct rte_flow_item_icmp rte_flow_item_icmp_mask = {
 522         .hdr = {
 523                 .icmp_type = 0xff,
 524                 .icmp_code = 0xff,
 525         },
 526 };
 527 #endif
 528
 529 /**
 530  * RTE_FLOW_ITEM_TYPE_UDP.
 531  *
 532  * Matches a UDP header.
 533  */
 534 struct rte_flow_item_udp {
 535         struct udp_hdr hdr; /**< UDP header definition. */
 536 };
 537
 538 /** Default mask for RTE_FLOW_ITEM_TYPE_UDP. */
 539 #ifndef __cplusplus
 540 static const struct rte_flow_item_udp rte_flow_item_udp_mask = {
 541         .hdr = {
 542                 .src_port = 0xffff,
 543                 .dst_port = 0xffff,
 544         },
 545 };
 546 #endif
 547
 548 /**
 549  * RTE_FLOW_ITEM_TYPE_TCP.
 550  *
 551  * Matches a TCP header.
 552  */
 553 struct rte_flow_item_tcp {
 554         struct tcp_hdr hdr; /**< TCP header definition. */
 555 };
 556
 557 /** Default mask for RTE_FLOW_ITEM_TYPE_TCP. */
 558 #ifndef __cplusplus
 559 static const struct rte_flow_item_tcp rte_flow_item_tcp_mask = {
 560         .hdr = {
 561                 .src_port = 0xffff,
 562                 .dst_port = 0xffff,
 563         },
 564 };
 565 #endif
 566
 567 /**
 568  * RTE_FLOW_ITEM_TYPE_SCTP.
 569  *
 570  * Matches a SCTP header.
 571  */
 572 struct rte_flow_item_sctp {
 573         struct sctp_hdr hdr; /**< SCTP header definition. */
 574 };
 575
 576 /** Default mask for RTE_FLOW_ITEM_TYPE_SCTP. */
 577 #ifndef __cplusplus
 578 static const struct rte_flow_item_sctp rte_flow_item_sctp_mask = {
 579         .hdr = {
 580                 .src_port = 0xffff,
 581                 .dst_port = 0xffff,
 582         },
 583 };
 584 #endif
 585
 586 /**
 587  * RTE_FLOW_ITEM_TYPE_VXLAN.
 588  *
 589  * Matches a VXLAN header (RFC 7348).
 590  */
 591 struct rte_flow_item_vxlan {
 592         uint8_t flags; /**< Normally 0x08 (I flag). */
 593         uint8_t rsvd0[3]; /**< Reserved, normally 0x000000. */
 594         uint8_t vni[3]; /**< VXLAN identifier. */
 595         uint8_t rsvd1; /**< Reserved, normally 0x00. */
 596 };
 597
 598 /** Default mask for RTE_FLOW_ITEM_TYPE_VXLAN. */
 599 #ifndef __cplusplus
 600 static const struct rte_flow_item_vxlan rte_flow_item_vxlan_mask = {
 601         .vni = "\xff\xff\xff",
 602 };
 603 #endif
 604
 605 /**
 606  * RTE_FLOW_ITEM_TYPE_E_TAG.
 607  *
 608  * Matches a E-tag header.
 609  */
 610 struct rte_flow_item_e_tag {
 611         uint16_t tpid; /**< Tag protocol identifier (0x893F). */
 612         /**
 613          * E-Tag control information (E-TCI).
 614          * E-PCP (3b), E-DEI (1b), ingress E-CID base (12b).
 615          */
 616         uint16_t epcp_edei_in_ecid_b;
 617         /** Reserved (2b), GRP (2b), E-CID base (12b). */
 618         uint16_t rsvd_grp_ecid_b;
 619         uint8_t in_ecid_e; /**< Ingress E-CID ext. */
 620         uint8_t ecid_e; /**< E-CID ext. */
 621 };
 622
 623 /**
 624  * RTE_FLOW_ITEM_TYPE_NVGRE.
 625  *
 626  * Matches a NVGRE header.
 627  */
 628 struct rte_flow_item_nvgre {
 629         /**
 630          * Checksum (1b), undefined (1b), key bit (1b), sequence number (1b),
 631          * reserved 0 (9b), version (3b).
 632          *
 633          * c_k_s_rsvd0_ver must have value 0x2000 according to RFC 7637.
 634          */
 635         uint16_t c_k_s_rsvd0_ver;
 636         uint16_t protocol; /**< Protocol type (0x6558). */
 637         uint8_t tni[3]; /**< Virtual subnet ID. */
 638         uint8_t flow_id; /**< Flow ID. */
 639 };
 640
 641 /**
 642  * RTE_FLOW_ITEM_TYPE_MPLS.
 643  *
 644  * Matches a MPLS header.
 645  */
 646 struct rte_flow_item_mpls {
 647         /**
 648          * Label (20b), TC (3b), Bottom of Stack (1b).
 649          */
 650         uint8_t label_tc_s[3];
 651         uint8_t ttl; /** Time-to-Live. */
 652 };
 653
 654 /** Default mask for RTE_FLOW_ITEM_TYPE_MPLS. */
 655 #ifndef __cplusplus
 656 static const struct rte_flow_item_mpls rte_flow_item_mpls_mask = {
 657         .label_tc_s = "\xff\xff\xf0",
 658 };
 659 #endif
 660
 661 /**
 662  * RTE_FLOW_ITEM_TYPE_GRE.
 663  *
 664  * Matches a GRE header.
 665  */
 666 struct rte_flow_item_gre {
 667         /**
 668          * Checksum (1b), reserved 0 (12b), version (3b).
 669          * Refer to RFC 2784.
 670          */
 671         uint16_t c_rsvd0_ver;
 672         uint16_t protocol; /**< Protocol type. */
 673 };
 674
 675 /** Default mask for RTE_FLOW_ITEM_TYPE_GRE. */
 676 #ifndef __cplusplus
 677 static const struct rte_flow_item_gre rte_flow_item_gre_mask = {
 678         .protocol = 0xffff,
 679 };
 680 #endif
 681
 682 /**
 683  * Matching pattern item definition.
 684  *
 685  * A pattern is formed by stacking items starting from the lowest protocol
 686  * layer to match. This stacking restriction does not apply to meta items
 687  * which can be placed anywhere in the stack without affecting the meaning
 688  * of the resulting pattern.
 689  *
 690  * Patterns are terminated by END items.
 691  *
 692  * The spec field should be a valid pointer to a structure of the related
 693  * item type. It may remain unspecified (NULL) in many cases to request
 694  * broad (nonspecific) matching. In such cases, last and mask must also be
 695  * set to NULL.
 696  *
 697  * Optionally, last can point to a structure of the same type to define an
 698  * inclusive range. This is mostly supported by integer and address fields,
 699  * may cause errors otherwise. Fields that do not support ranges must be set
 700  * to 0 or to the same value as the corresponding fields in spec.
 701  *
 702  * Only the fields defined to nonzero values in the default masks (see
 703  * rte_flow_item_{name}_mask constants) are considered relevant by
 704  * default. This can be overridden by providing a mask structure of the
 705  * same type with applicable bits set to one. It can also be used to
 706  * partially filter out specific fields (e.g. as an alternate mean to match
 707  * ranges of IP addresses).
 708  *
 709  * Mask is a simple bit-mask applied before interpreting the contents of
 710  * spec and last, which may yield unexpected results if not used
 711  * carefully. For example, if for an IPv4 address field, spec provides
 712  * 10.1.2.3, last provides 10.3.4.5 and mask provides 255.255.0.0, the
 713  * effective range becomes 10.1.0.0 to 10.3.255.255.
 714  */
 715 struct rte_flow_item {
 716         enum rte_flow_item_type type; /**< Item type. */
 717         const void *spec; /**< Pointer to item specification structure. */
 718         const void *last; /**< Defines an inclusive range (spec to last). */
 719         const void *mask; /**< Bit-mask applied to spec and last. */
 720 };
 721
 722 /**
 723  * Action types.
 724  *
 725  * Each possible action is represented by a type. Some have associated
 726  * configuration structures. Several actions combined in a list can be
 727  * affected to a flow rule. That list is not ordered.
 728  *
 729  * They fall in three categories:
 730  *
 731  * - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
 732  *   processing matched packets by subsequent flow rules, unless overridden
 733  *   with PASSTHRU.
 734  *
 735  * - Non terminating actions (PASSTHRU, DUP) that leave matched packets up
 736  *   for additional processing by subsequent flow rules.
 737  *
 738  * - Other non terminating meta actions that do not affect the fate of
 739  *   packets (END, VOID, MARK, FLAG, COUNT).
 740  *
 741  * When several actions are combined in a flow rule, they should all have
 742  * different types (e.g. dropping a packet twice is not possible).
 743  *
 744  * Only the last action of a given type is taken into account. PMDs still
 745  * perform error checking on the entire list.
 746  *
 747  * Note that PASSTHRU is the only action able to override a terminating
 748  * rule.
 749  */
 750 enum rte_flow_action_type {
 751         /**
 752          * [META]
 753          *
 754          * End marker for action lists. Prevents further processing of
 755          * actions, thereby ending the list.
 756          *
 757          * No associated configuration structure.
 758          */
 759         RTE_FLOW_ACTION_TYPE_END,
 760
 761         /**
 762          * [META]
 763          *
 764          * Used as a placeholder for convenience. It is ignored and simply
 765          * discarded by PMDs.
 766          *
 767          * No associated configuration structure.
 768          */
 769         RTE_FLOW_ACTION_TYPE_VOID,
 770
 771         /**
 772          * Leaves packets up for additional processing by subsequent flow
 773          * rules. This is the default when a rule does not contain a
 774          * terminating action, but can be specified to force a rule to
 775          * become non-terminating.
 776          *
 777          * No associated configuration structure.
 778          */
 779         RTE_FLOW_ACTION_TYPE_PASSTHRU,
 780
 781         /**
 782          * [META]
 783          *
 784          * Attaches an integer value to packets and sets PKT_RX_FDIR and
 785          * PKT_RX_FDIR_ID mbuf flags.
 786          *
 787          * See struct rte_flow_action_mark.
 788          */
 789         RTE_FLOW_ACTION_TYPE_MARK,
 790
 791         /**
 792          * [META]
 793          *
 794          * Flags packets. Similar to MARK without a specific value; only
 795          * sets the PKT_RX_FDIR mbuf flag.
 796          *
 797          * No associated configuration structure.
 798          */
 799         RTE_FLOW_ACTION_TYPE_FLAG,
 800
 801         /**
 802          * Assigns packets to a given queue index.
 803          *
 804          * See struct rte_flow_action_queue.
 805          */
 806         RTE_FLOW_ACTION_TYPE_QUEUE,
 807
 808         /**
 809          * Drops packets.
 810          *
 811          * PASSTHRU overrides this action if both are specified.
 812          *
 813          * No associated configuration structure.
 814          */
 815         RTE_FLOW_ACTION_TYPE_DROP,
 816
 817         /**
 818          * [META]
 819          *
 820          * Enables counters for this rule.
 821          *
 822          * These counters can be retrieved and reset through rte_flow_query(),
 823          * see struct rte_flow_query_count.
 824          *
 825          * No associated configuration structure.
 826          */
 827         RTE_FLOW_ACTION_TYPE_COUNT,
 828
 829         /**
 830          * Duplicates packets to a given queue index.
 831          *
 832          * This is normally combined with QUEUE, however when used alone, it
 833          * is actually similar to QUEUE + PASSTHRU.
 834          *
 835          * See struct rte_flow_action_dup.
 836          */
 837         RTE_FLOW_ACTION_TYPE_DUP,
 838
 839         /**
 840          * Similar to QUEUE, except RSS is additionally performed on packets
 841          * to spread them among several queues according to the provided
 842          * parameters.
 843          *
 844          * See struct rte_flow_action_rss.
 845          */
 846         RTE_FLOW_ACTION_TYPE_RSS,
 847
 848         /**
 849          * Redirects packets to the physical function (PF) of the current
 850          * device.
 851          *
 852          * No associated configuration structure.
 853          */
 854         RTE_FLOW_ACTION_TYPE_PF,
 855
 856         /**
 857          * Redirects packets to the virtual function (VF) of the current
 858          * device with the specified ID.
 859          *
 860          * See struct rte_flow_action_vf.
 861          */
 862         RTE_FLOW_ACTION_TYPE_VF,
 863 };
 864
 865 /**
 866  * RTE_FLOW_ACTION_TYPE_MARK
 867  *
 868  * Attaches an integer value to packets and sets PKT_RX_FDIR and
 869  * PKT_RX_FDIR_ID mbuf flags.
 870  *
 871  * This value is arbitrary and application-defined. Maximum allowed value
 872  * depends on the underlying implementation. It is returned in the
 873  * hash.fdir.hi mbuf field.
 874  */
 875 struct rte_flow_action_mark {
 876         uint32_t id; /**< Integer value to return with packets. */
 877 };
 878
 879 /**
 880  * RTE_FLOW_ACTION_TYPE_QUEUE
 881  *
 882  * Assign packets to a given queue index.
 883  *
 884  * Terminating by default.
 885  */
 886 struct rte_flow_action_queue {
 887         uint16_t index; /**< Queue index to use. */
 888 };
 889
 890 /**
 891  * RTE_FLOW_ACTION_TYPE_COUNT (query)
 892  *
 893  * Query structure to retrieve and reset flow rule counters.
 894  */
 895 struct rte_flow_query_count {
 896         uint32_t reset:1; /**< Reset counters after query [in]. */
 897         uint32_t hits_set:1; /**< hits field is set [out]. */
 898         uint32_t bytes_set:1; /**< bytes field is set [out]. */
 899         uint32_t reserved:29; /**< Reserved, must be zero [in, out]. */
 900         uint64_t hits; /**< Number of hits for this rule [out]. */
 901         uint64_t bytes; /**< Number of bytes through this rule [out]. */
 902 };
 903
 904 /**
 905  * RTE_FLOW_ACTION_TYPE_DUP
 906  *
 907  * Duplicates packets to a given queue index.
 908  *
 909  * This is normally combined with QUEUE, however when used alone, it is
 910  * actually similar to QUEUE + PASSTHRU.
 911  *
 912  * Non-terminating by default.
 913  */
 914 struct rte_flow_action_dup {
 915         uint16_t index; /**< Queue index to duplicate packets to. */
 916 };
 917
 918 /**
 919  * RTE_FLOW_ACTION_TYPE_RSS
 920  *
 921  * Similar to QUEUE, except RSS is additionally performed on packets to
 922  * spread them among several queues according to the provided parameters.
 923  *
 924  * Note: RSS hash result is stored in the hash.rss mbuf field which overlaps
 925  * hash.fdir.lo. Since the MARK action sets the hash.fdir.hi field only,
 926  * both can be requested simultaneously.
 927  *
 928  * Terminating by default.
 929  */
 930 struct rte_flow_action_rss {
 931         const struct rte_eth_rss_conf *rss_conf; /**< RSS parameters. */
 932         uint16_t num; /**< Number of entries in queue[]. */
 933         uint16_t queue[]; /**< Queues indices to use. */
 934 };
 935
 936 /**
 937  * RTE_FLOW_ACTION_TYPE_VF
 938  *
 939  * Redirects packets to a virtual function (VF) of the current device.
 940  *
 941  * Packets matched by a VF pattern item can be redirected to their original
 942  * VF ID instead of the specified one. This parameter may not be available
 943  * and is not guaranteed to work properly if the VF part is matched by a
 944  * prior flow rule or if packets are not addressed to a VF in the first
 945  * place.
 946  *
 947  * Terminating by default.
 948  */
 949 struct rte_flow_action_vf {
 950         uint32_t original:1; /**< Use original VF ID if possible. */
 951         uint32_t reserved:31; /**< Reserved, must be zero. */
 952         uint32_t id; /**< VF ID to redirect packets to. */
 953 };
 954
 955 /**
 956  * Definition of a single action.
 957  *
 958  * A list of actions is terminated by a END action.
 959  *
 960  * For simple actions without a configuration structure, conf remains NULL.
 961  */
 962 struct rte_flow_action {
 963         enum rte_flow_action_type type; /**< Action type. */
 964         const void *conf; /**< Pointer to action configuration structure. */
 965 };
 966
 967 /**
 968  * Opaque type returned after successfully creating a flow.
 969  *
 970  * This handle can be used to manage and query the related flow (e.g. to
 971  * destroy it or retrieve counters).
 972  */
 973 struct rte_flow;
 974
 975 /**
 976  * Verbose error types.
 977  *
 978  * Most of them provide the type of the object referenced by struct
 979  * rte_flow_error.cause.
 980  */
 981 enum rte_flow_error_type {
 982         RTE_FLOW_ERROR_TYPE_NONE, /**< No error. */
 983         RTE_FLOW_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
 984         RTE_FLOW_ERROR_TYPE_HANDLE, /**< Flow rule (handle). */
 985         RTE_FLOW_ERROR_TYPE_ATTR_GROUP, /**< Group field. */
 986         RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */
 987         RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */
 988         RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */
 989         RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */
 990         RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */
 991         RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */
 992         RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */
 993         RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */
 994 };
 995
 996 /**
 997  * Verbose error structure definition.
 998  *
 999  * This object is normally allocated by applications and set by PMDs, the
1000  * message points to a constant string which does not need to be freed by
1001  * the application, however its pointer can be considered valid only as long
1002  * as its associated DPDK port remains configured. Closing the underlying
1003  * device or unloading the PMD invalidates it.
1004  *
1005  * Both cause and message may be NULL regardless of the error type.
1006  */
1007 struct rte_flow_error {
1008         enum rte_flow_error_type type; /**< Cause field and error types. */
1009         const void *cause; /**< Object responsible for the error. */
1010         const char *message; /**< Human-readable error message. */
1011 };
1012
1013 /**
1014  * Check whether a flow rule can be created on a given port.
1015  *
1016  * The flow rule is validated for correctness and whether it could be accepted
1017  * by the device given sufficient resources. The rule is checked against the
1018  * current device mode and queue configuration. The flow rule may also
1019  * optionally be validated against existing flow rules and device resources.
1020  * This function has no effect on the target device.
1021  *
1022  * The returned value is guaranteed to remain valid only as long as no
1023  * successful calls to rte_flow_create() or rte_flow_destroy() are made in
1024  * the meantime and no device parameter affecting flow rules in any way are
1025  * modified, due to possible collisions or resource limitations (although in
1026  * such cases EINVAL should not be returned).
1027  *
1028  * @param port_id
1029  *   Port identifier of Ethernet device.
1030  * @param[in] attr
1031  *   Flow rule attributes.
1032  * @param[in] pattern
1033  *   Pattern specification (list terminated by the END pattern item).
1034  * @param[in] actions
1035  *   Associated actions (list terminated by the END action).
1036  * @param[out] error
1037  *   Perform verbose error reporting if not NULL. PMDs initialize this
1038  *   structure in case of error only.
1039  *
1040  * @return
1041  *   0 if flow rule is valid and can be created. A negative errno value
1042  *   otherwise (rte_errno is also set), the following errors are defined:
1043  *
1044  *   -ENOSYS: underlying device does not support this functionality.
1045  *
1046  *   -EINVAL: unknown or invalid rule specification.
1047  *
1048  *   -ENOTSUP: valid but unsupported rule specification (e.g. partial
1049  *   bit-masks are unsupported).
1050  *
1051  *   -EEXIST: collision with an existing rule. Only returned if device
1052  *   supports flow rule collision checking and there was a flow rule
1053  *   collision. Not receiving this return code is no guarantee that creating
1054  *   the rule will not fail due to a collision.
1055  *
1056  *   -ENOMEM: not enough memory to execute the function, or if the device
1057  *   supports resource validation, resource limitation on the device.
1058  *
1059  *   -EBUSY: action cannot be performed due to busy device resources, may
1060  *   succeed if the affected queues or even the entire port are in a stopped
1061  *   state (see rte_eth_dev_rx_queue_stop() and rte_eth_dev_stop()).
1062  */
1063 int
1064 rte_flow_validate(uint8_t port_id,
1065                   const struct rte_flow_attr *attr,
1066                   const struct rte_flow_item pattern[],
1067                   const struct rte_flow_action actions[],
1068                   struct rte_flow_error *error);
1069
1070 /**
1071  * Create a flow rule on a given port.
1072  *
1073  * @param port_id
1074  *   Port identifier of Ethernet device.
1075  * @param[in] attr
1076  *   Flow rule attributes.
1077  * @param[in] pattern
1078  *   Pattern specification (list terminated by the END pattern item).
1079  * @param[in] actions
1080  *   Associated actions (list terminated by the END action).
1081  * @param[out] error
1082  *   Perform verbose error reporting if not NULL. PMDs initialize this
1083  *   structure in case of error only.
1084  *
1085  * @return
1086  *   A valid handle in case of success, NULL otherwise and rte_errno is set
1087  *   to the positive version of one of the error codes defined for
1088  *   rte_flow_validate().
1089  */
1090 struct rte_flow *
1091 rte_flow_create(uint8_t port_id,
1092                 const struct rte_flow_attr *attr,
1093                 const struct rte_flow_item pattern[],
1094                 const struct rte_flow_action actions[],
1095                 struct rte_flow_error *error);
1096
1097 /**
1098  * Destroy a flow rule on a given port.
1099  *
1100  * Failure to destroy a flow rule handle may occur when other flow rules
1101  * depend on it, and destroying it would result in an inconsistent state.
1102  *
1103  * This function is only guaranteed to succeed if handles are destroyed in
1104  * reverse order of their creation.
1105  *
1106  * @param port_id
1107  *   Port identifier of Ethernet device.
1108  * @param flow
1109  *   Flow rule handle to destroy.
1110  * @param[out] error
1111  *   Perform verbose error reporting if not NULL. PMDs initialize this
1112  *   structure in case of error only.
1113  *
1114  * @return
1115  *   0 on success, a negative errno value otherwise and rte_errno is set.
1116  */
1117 int
1118 rte_flow_destroy(uint8_t port_id,
1119                  struct rte_flow *flow,
1120                  struct rte_flow_error *error);
1121
1122 /**
1123  * Destroy all flow rules associated with a port.
1124  *
1125  * In the unlikely event of failure, handles are still considered destroyed
1126  * and no longer valid but the port must be assumed to be in an inconsistent
1127  * state.
1128  *
1129  * @param port_id
1130  *   Port identifier of Ethernet device.
1131  * @param[out] error
1132  *   Perform verbose error reporting if not NULL. PMDs initialize this
1133  *   structure in case of error only.
1134  *
1135  * @return
1136  *   0 on success, a negative errno value otherwise and rte_errno is set.
1137  */
1138 int
1139 rte_flow_flush(uint8_t port_id,
1140                struct rte_flow_error *error);
1141
1142 /**
1143  * Query an existing flow rule.
1144  *
1145  * This function allows retrieving flow-specific data such as counters.
1146  * Data is gathered by special actions which must be present in the flow
1147  * rule definition.
1148  *
1149  * \see RTE_FLOW_ACTION_TYPE_COUNT
1150  *
1151  * @param port_id
1152  *   Port identifier of Ethernet device.
1153  * @param flow
1154  *   Flow rule handle to query.
1155  * @param action
1156  *   Action type to query.
1157  * @param[in, out] data
1158  *   Pointer to storage for the associated query data type.
1159  * @param[out] error
1160  *   Perform verbose error reporting if not NULL. PMDs initialize this
1161  *   structure in case of error only.
1162  *
1163  * @return
1164  *   0 on success, a negative errno value otherwise and rte_errno is set.
1165  */
1166 int
1167 rte_flow_query(uint8_t port_id,
1168                struct rte_flow *flow,
1169                enum rte_flow_action_type action,
1170                void *data,
1171                struct rte_flow_error *error);
1172
1173 #ifdef __cplusplus
1174 }
1175 #endif
1176
1177 #endif /* RTE_FLOW_H_ */