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