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 /**
 274  * RTE_FLOW_ITEM_TYPE_ANY
 275  *
 276  * Matches any protocol in place of the current layer, a single ANY may also
 277  * stand for several protocol layers.
 278  *
 279  * This is usually specified as the first pattern item when looking for a
 280  * protocol anywhere in a packet.
 281  *
 282  * A zeroed mask stands for any number of layers.
 283  */
 284 struct rte_flow_item_any {
 285         uint32_t num; /* Number of layers covered. */
 286 };
 287
 288 /**
 289  * RTE_FLOW_ITEM_TYPE_VF
 290  *
 291  * Matches packets addressed to a virtual function ID of the device.
 292  *
 293  * If the underlying device function differs from the one that would
 294  * normally receive the matched traffic, specifying this item prevents it
 295  * from reaching that device unless the flow rule contains a VF
 296  * action. Packets are not duplicated between device instances by default.
 297  *
 298  * - Likely to return an error or never match any traffic if this causes a
 299  *   VF device to match traffic addressed to a different VF.
 300  * - Can be specified multiple times to match traffic addressed to several
 301  *   VF IDs.
 302  * - Can be combined with a PF item to match both PF and VF traffic.
 303  *
 304  * A zeroed mask can be used to match any VF ID.
 305  */
 306 struct rte_flow_item_vf {
 307         uint32_t id; /**< Destination VF ID. */
 308 };
 309
 310 /**
 311  * RTE_FLOW_ITEM_TYPE_PORT
 312  *
 313  * Matches packets coming from the specified physical port of the underlying
 314  * device.
 315  *
 316  * The first PORT item overrides the physical port normally associated with
 317  * the specified DPDK input port (port_id). This item can be provided
 318  * several times to match additional physical ports.
 319  *
 320  * Note that physical ports are not necessarily tied to DPDK input ports
 321  * (port_id) when those are not under DPDK control. Possible values are
 322  * specific to each device, they are not necessarily indexed from zero and
 323  * may not be contiguous.
 324  *
 325  * As a device property, the list of allowed values as well as the value
 326  * associated with a port_id should be retrieved by other means.
 327  *
 328  * A zeroed mask can be used to match any port index.
 329  */
 330 struct rte_flow_item_port {
 331         uint32_t index; /**< Physical port index. */
 332 };
 333
 334 /**
 335  * RTE_FLOW_ITEM_TYPE_RAW
 336  *
 337  * Matches a byte string of a given length at a given offset.
 338  *
 339  * Offset is either absolute (using the start of the packet) or relative to
 340  * the end of the previous matched item in the stack, in which case negative
 341  * values are allowed.
 342  *
 343  * If search is enabled, offset is used as the starting point. The search
 344  * area can be delimited by setting limit to a nonzero value, which is the
 345  * maximum number of bytes after offset where the pattern may start.
 346  *
 347  * Matching a zero-length pattern is allowed, doing so resets the relative
 348  * offset for subsequent items.
 349  *
 350  * This type does not support ranges (struct rte_flow_item.last).
 351  */
 352 struct rte_flow_item_raw {
 353         uint32_t relative:1; /**< Look for pattern after the previous item. */
 354         uint32_t search:1; /**< Search pattern from offset (see also limit). */
 355         uint32_t reserved:30; /**< Reserved, must be set to zero. */
 356         int32_t offset; /**< Absolute or relative offset for pattern. */
 357         uint16_t limit; /**< Search area limit for start of pattern. */
 358         uint16_t length; /**< Pattern length. */
 359         uint8_t pattern[]; /**< Byte string to look for. */
 360 };
 361
 362 /**
 363  * RTE_FLOW_ITEM_TYPE_ETH
 364  *
 365  * Matches an Ethernet header.
 366  */
 367 struct rte_flow_item_eth {
 368         struct ether_addr dst; /**< Destination MAC. */
 369         struct ether_addr src; /**< Source MAC. */
 370         uint16_t type; /**< EtherType. */
 371 };
 372
 373 /**
 374  * RTE_FLOW_ITEM_TYPE_VLAN
 375  *
 376  * Matches an 802.1Q/ad VLAN tag.
 377  *
 378  * This type normally follows either RTE_FLOW_ITEM_TYPE_ETH or
 379  * RTE_FLOW_ITEM_TYPE_VLAN.
 380  */
 381 struct rte_flow_item_vlan {
 382         uint16_t tpid; /**< Tag protocol identifier. */
 383         uint16_t tci; /**< Tag control information. */
 384 };
 385
 386 /**
 387  * RTE_FLOW_ITEM_TYPE_IPV4
 388  *
 389  * Matches an IPv4 header.
 390  *
 391  * Note: IPv4 options are handled by dedicated pattern items.
 392  */
 393 struct rte_flow_item_ipv4 {
 394         struct ipv4_hdr hdr; /**< IPv4 header definition. */
 395 };
 396
 397 /**
 398  * RTE_FLOW_ITEM_TYPE_IPV6.
 399  *
 400  * Matches an IPv6 header.
 401  *
 402  * Note: IPv6 options are handled by dedicated pattern items.
 403  */
 404 struct rte_flow_item_ipv6 {
 405         struct ipv6_hdr hdr; /**< IPv6 header definition. */
 406 };
 407
 408 /**
 409  * RTE_FLOW_ITEM_TYPE_ICMP.
 410  *
 411  * Matches an ICMP header.
 412  */
 413 struct rte_flow_item_icmp {
 414         struct icmp_hdr hdr; /**< ICMP header definition. */
 415 };
 416
 417 /**
 418  * RTE_FLOW_ITEM_TYPE_UDP.
 419  *
 420  * Matches a UDP header.
 421  */
 422 struct rte_flow_item_udp {
 423         struct udp_hdr hdr; /**< UDP header definition. */
 424 };
 425
 426 /**
 427  * RTE_FLOW_ITEM_TYPE_TCP.
 428  *
 429  * Matches a TCP header.
 430  */
 431 struct rte_flow_item_tcp {
 432         struct tcp_hdr hdr; /**< TCP header definition. */
 433 };
 434
 435 /**
 436  * RTE_FLOW_ITEM_TYPE_SCTP.
 437  *
 438  * Matches a SCTP header.
 439  */
 440 struct rte_flow_item_sctp {
 441         struct sctp_hdr hdr; /**< SCTP header definition. */
 442 };
 443
 444 /**
 445  * RTE_FLOW_ITEM_TYPE_VXLAN.
 446  *
 447  * Matches a VXLAN header (RFC 7348).
 448  */
 449 struct rte_flow_item_vxlan {
 450         uint8_t flags; /**< Normally 0x08 (I flag). */
 451         uint8_t rsvd0[3]; /**< Reserved, normally 0x000000. */
 452         uint8_t vni[3]; /**< VXLAN identifier. */
 453         uint8_t rsvd1; /**< Reserved, normally 0x00. */
 454 };
 455
 456 /**
 457  * Matching pattern item definition.
 458  *
 459  * A pattern is formed by stacking items starting from the lowest protocol
 460  * layer to match. This stacking restriction does not apply to meta items
 461  * which can be placed anywhere in the stack without affecting the meaning
 462  * of the resulting pattern.
 463  *
 464  * Patterns are terminated by END items.
 465  *
 466  * The spec field should be a valid pointer to a structure of the related
 467  * item type. It may be set to NULL in many cases to use default values.
 468  *
 469  * Optionally, last can point to a structure of the same type to define an
 470  * inclusive range. This is mostly supported by integer and address fields,
 471  * may cause errors otherwise. Fields that do not support ranges must be set
 472  * to 0 or to the same value as the corresponding fields in spec.
 473  *
 474  * By default all fields present in spec are considered relevant (see note
 475  * below). This behavior can be altered by providing a mask structure of the
 476  * same type with applicable bits set to one. It can also be used to
 477  * partially filter out specific fields (e.g. as an alternate mean to match
 478  * ranges of IP addresses).
 479  *
 480  * Mask is a simple bit-mask applied before interpreting the contents of
 481  * spec and last, which may yield unexpected results if not used
 482  * carefully. For example, if for an IPv4 address field, spec provides
 483  * 10.1.2.3, last provides 10.3.4.5 and mask provides 255.255.0.0, the
 484  * effective range becomes 10.1.0.0 to 10.3.255.255.
 485  *
 486  * Note: the defaults for data-matching items such as IPv4 when mask is not
 487  * specified actually depend on the underlying implementation since only
 488  * recognized fields can be taken into account.
 489  */
 490 struct rte_flow_item {
 491         enum rte_flow_item_type type; /**< Item type. */
 492         const void *spec; /**< Pointer to item specification structure. */
 493         const void *last; /**< Defines an inclusive range (spec to last). */
 494         const void *mask; /**< Bit-mask applied to spec and last. */
 495 };
 496
 497 /**
 498  * Action types.
 499  *
 500  * Each possible action is represented by a type. Some have associated
 501  * configuration structures. Several actions combined in a list can be
 502  * affected to a flow rule. That list is not ordered.
 503  *
 504  * They fall in three categories:
 505  *
 506  * - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent
 507  *   processing matched packets by subsequent flow rules, unless overridden
 508  *   with PASSTHRU.
 509  *
 510  * - Non terminating actions (PASSTHRU, DUP) that leave matched packets up
 511  *   for additional processing by subsequent flow rules.
 512  *
 513  * - Other non terminating meta actions that do not affect the fate of
 514  *   packets (END, VOID, MARK, FLAG, COUNT).
 515  *
 516  * When several actions are combined in a flow rule, they should all have
 517  * different types (e.g. dropping a packet twice is not possible).
 518  *
 519  * Only the last action of a given type is taken into account. PMDs still
 520  * perform error checking on the entire list.
 521  *
 522  * Note that PASSTHRU is the only action able to override a terminating
 523  * rule.
 524  */
 525 enum rte_flow_action_type {
 526         /**
 527          * [META]
 528          *
 529          * End marker for action lists. Prevents further processing of
 530          * actions, thereby ending the list.
 531          *
 532          * No associated configuration structure.
 533          */
 534         RTE_FLOW_ACTION_TYPE_END,
 535
 536         /**
 537          * [META]
 538          *
 539          * Used as a placeholder for convenience. It is ignored and simply
 540          * discarded by PMDs.
 541          *
 542          * No associated configuration structure.
 543          */
 544         RTE_FLOW_ACTION_TYPE_VOID,
 545
 546         /**
 547          * Leaves packets up for additional processing by subsequent flow
 548          * rules. This is the default when a rule does not contain a
 549          * terminating action, but can be specified to force a rule to
 550          * become non-terminating.
 551          *
 552          * No associated configuration structure.
 553          */
 554         RTE_FLOW_ACTION_TYPE_PASSTHRU,
 555
 556         /**
 557          * [META]
 558          *
 559          * Attaches an integer value to packets and sets PKT_RX_FDIR and
 560          * PKT_RX_FDIR_ID mbuf flags.
 561          *
 562          * See struct rte_flow_action_mark.
 563          */
 564         RTE_FLOW_ACTION_TYPE_MARK,
 565
 566         /**
 567          * [META]
 568          *
 569          * Flags packets. Similar to MARK without a specific value; only
 570          * sets the PKT_RX_FDIR mbuf flag.
 571          *
 572          * No associated configuration structure.
 573          */
 574         RTE_FLOW_ACTION_TYPE_FLAG,
 575
 576         /**
 577          * Assigns packets to a given queue index.
 578          *
 579          * See struct rte_flow_action_queue.
 580          */
 581         RTE_FLOW_ACTION_TYPE_QUEUE,
 582
 583         /**
 584          * Drops packets.
 585          *
 586          * PASSTHRU overrides this action if both are specified.
 587          *
 588          * No associated configuration structure.
 589          */
 590         RTE_FLOW_ACTION_TYPE_DROP,
 591
 592         /**
 593          * [META]
 594          *
 595          * Enables counters for this rule.
 596          *
 597          * These counters can be retrieved and reset through rte_flow_query(),
 598          * see struct rte_flow_query_count.
 599          *
 600          * No associated configuration structure.
 601          */
 602         RTE_FLOW_ACTION_TYPE_COUNT,
 603
 604         /**
 605          * Duplicates packets to a given queue index.
 606          *
 607          * This is normally combined with QUEUE, however when used alone, it
 608          * is actually similar to QUEUE + PASSTHRU.
 609          *
 610          * See struct rte_flow_action_dup.
 611          */
 612         RTE_FLOW_ACTION_TYPE_DUP,
 613
 614         /**
 615          * Similar to QUEUE, except RSS is additionally performed on packets
 616          * to spread them among several queues according to the provided
 617          * parameters.
 618          *
 619          * See struct rte_flow_action_rss.
 620          */
 621         RTE_FLOW_ACTION_TYPE_RSS,
 622
 623         /**
 624          * Redirects packets to the physical function (PF) of the current
 625          * device.
 626          *
 627          * No associated configuration structure.
 628          */
 629         RTE_FLOW_ACTION_TYPE_PF,
 630
 631         /**
 632          * Redirects packets to the virtual function (VF) of the current
 633          * device with the specified ID.
 634          *
 635          * See struct rte_flow_action_vf.
 636          */
 637         RTE_FLOW_ACTION_TYPE_VF,
 638 };
 639
 640 /**
 641  * RTE_FLOW_ACTION_TYPE_MARK
 642  *
 643  * Attaches an integer value to packets and sets PKT_RX_FDIR and
 644  * PKT_RX_FDIR_ID mbuf flags.
 645  *
 646  * This value is arbitrary and application-defined. Maximum allowed value
 647  * depends on the underlying implementation. It is returned in the
 648  * hash.fdir.hi mbuf field.
 649  */
 650 struct rte_flow_action_mark {
 651         uint32_t id; /**< Integer value to return with packets. */
 652 };
 653
 654 /**
 655  * RTE_FLOW_ACTION_TYPE_QUEUE
 656  *
 657  * Assign packets to a given queue index.
 658  *
 659  * Terminating by default.
 660  */
 661 struct rte_flow_action_queue {
 662         uint16_t index; /**< Queue index to use. */
 663 };
 664
 665 /**
 666  * RTE_FLOW_ACTION_TYPE_COUNT (query)
 667  *
 668  * Query structure to retrieve and reset flow rule counters.
 669  */
 670 struct rte_flow_query_count {
 671         uint32_t reset:1; /**< Reset counters after query [in]. */
 672         uint32_t hits_set:1; /**< hits field is set [out]. */
 673         uint32_t bytes_set:1; /**< bytes field is set [out]. */
 674         uint32_t reserved:29; /**< Reserved, must be zero [in, out]. */
 675         uint64_t hits; /**< Number of hits for this rule [out]. */
 676         uint64_t bytes; /**< Number of bytes through this rule [out]. */
 677 };
 678
 679 /**
 680  * RTE_FLOW_ACTION_TYPE_DUP
 681  *
 682  * Duplicates packets to a given queue index.
 683  *
 684  * This is normally combined with QUEUE, however when used alone, it is
 685  * actually similar to QUEUE + PASSTHRU.
 686  *
 687  * Non-terminating by default.
 688  */
 689 struct rte_flow_action_dup {
 690         uint16_t index; /**< Queue index to duplicate packets to. */
 691 };
 692
 693 /**
 694  * RTE_FLOW_ACTION_TYPE_RSS
 695  *
 696  * Similar to QUEUE, except RSS is additionally performed on packets to
 697  * spread them among several queues according to the provided parameters.
 698  *
 699  * Note: RSS hash result is normally stored in the hash.rss mbuf field,
 700  * however it conflicts with the MARK action as they share the same
 701  * space. When both actions are specified, the RSS hash is discarded and
 702  * PKT_RX_RSS_HASH is not set in ol_flags. MARK has priority. The mbuf
 703  * structure should eventually evolve to store both.
 704  *
 705  * Terminating by default.
 706  */
 707 struct rte_flow_action_rss {
 708         const struct rte_eth_rss_conf *rss_conf; /**< RSS parameters. */
 709         uint16_t num; /**< Number of entries in queue[]. */
 710         uint16_t queue[]; /**< Queues indices to use. */
 711 };
 712
 713 /**
 714  * RTE_FLOW_ACTION_TYPE_VF
 715  *
 716  * Redirects packets to a virtual function (VF) of the current device.
 717  *
 718  * Packets matched by a VF pattern item can be redirected to their original
 719  * VF ID instead of the specified one. This parameter may not be available
 720  * and is not guaranteed to work properly if the VF part is matched by a
 721  * prior flow rule or if packets are not addressed to a VF in the first
 722  * place.
 723  *
 724  * Terminating by default.
 725  */
 726 struct rte_flow_action_vf {
 727         uint32_t original:1; /**< Use original VF ID if possible. */
 728         uint32_t reserved:31; /**< Reserved, must be zero. */
 729         uint32_t id; /**< VF ID to redirect packets to. */
 730 };
 731
 732 /**
 733  * Definition of a single action.
 734  *
 735  * A list of actions is terminated by a END action.
 736  *
 737  * For simple actions without a configuration structure, conf remains NULL.
 738  */
 739 struct rte_flow_action {
 740         enum rte_flow_action_type type; /**< Action type. */
 741         const void *conf; /**< Pointer to action configuration structure. */
 742 };
 743
 744 /**
 745  * Opaque type returned after successfully creating a flow.
 746  *
 747  * This handle can be used to manage and query the related flow (e.g. to
 748  * destroy it or retrieve counters).
 749  */
 750 struct rte_flow;
 751
 752 /**
 753  * Verbose error types.
 754  *
 755  * Most of them provide the type of the object referenced by struct
 756  * rte_flow_error.cause.
 757  */
 758 enum rte_flow_error_type {
 759         RTE_FLOW_ERROR_TYPE_NONE, /**< No error. */
 760         RTE_FLOW_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
 761         RTE_FLOW_ERROR_TYPE_HANDLE, /**< Flow rule (handle). */
 762         RTE_FLOW_ERROR_TYPE_ATTR_GROUP, /**< Group field. */
 763         RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */
 764         RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */
 765         RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */
 766         RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */
 767         RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */
 768         RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */
 769         RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */
 770         RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */
 771 };
 772
 773 /**
 774  * Verbose error structure definition.
 775  *
 776  * This object is normally allocated by applications and set by PMDs, the
 777  * message points to a constant string which does not need to be freed by
 778  * the application, however its pointer can be considered valid only as long
 779  * as its associated DPDK port remains configured. Closing the underlying
 780  * device or unloading the PMD invalidates it.
 781  *
 782  * Both cause and message may be NULL regardless of the error type.
 783  */
 784 struct rte_flow_error {
 785         enum rte_flow_error_type type; /**< Cause field and error types. */
 786         const void *cause; /**< Object responsible for the error. */
 787         const char *message; /**< Human-readable error message. */
 788 };
 789
 790 /**
 791  * Check whether a flow rule can be created on a given port.
 792  *
 793  * While this function has no effect on the target device, the flow rule is
 794  * validated against its current configuration state and the returned value
 795  * should be considered valid by the caller for that state only.
 796  *
 797  * The returned value is guaranteed to remain valid only as long as no
 798  * successful calls to rte_flow_create() or rte_flow_destroy() are made in
 799  * the meantime and no device parameter affecting flow rules in any way are
 800  * modified, due to possible collisions or resource limitations (although in
 801  * such cases EINVAL should not be returned).
 802  *
 803  * @param port_id
 804  *   Port identifier of Ethernet device.
 805  * @param[in] attr
 806  *   Flow rule attributes.
 807  * @param[in] pattern
 808  *   Pattern specification (list terminated by the END pattern item).
 809  * @param[in] actions
 810  *   Associated actions (list terminated by the END action).
 811  * @param[out] error
 812  *   Perform verbose error reporting if not NULL. PMDs initialize this
 813  *   structure in case of error only.
 814  *
 815  * @return
 816  *   0 if flow rule is valid and can be created. A negative errno value
 817  *   otherwise (rte_errno is also set), the following errors are defined:
 818  *
 819  *   -ENOSYS: underlying device does not support this functionality.
 820  *
 821  *   -EINVAL: unknown or invalid rule specification.
 822  *
 823  *   -ENOTSUP: valid but unsupported rule specification (e.g. partial
 824  *   bit-masks are unsupported).
 825  *
 826  *   -EEXIST: collision with an existing rule.
 827  *
 828  *   -ENOMEM: not enough resources.
 829  *
 830  *   -EBUSY: action cannot be performed due to busy device resources, may
 831  *   succeed if the affected queues or even the entire port are in a stopped
 832  *   state (see rte_eth_dev_rx_queue_stop() and rte_eth_dev_stop()).
 833  */
 834 int
 835 rte_flow_validate(uint8_t port_id,
 836                   const struct rte_flow_attr *attr,
 837                   const struct rte_flow_item pattern[],
 838                   const struct rte_flow_action actions[],
 839                   struct rte_flow_error *error);
 840
 841 /**
 842  * Create a flow rule on a given port.
 843  *
 844  * @param port_id
 845  *   Port identifier of Ethernet device.
 846  * @param[in] attr
 847  *   Flow rule attributes.
 848  * @param[in] pattern
 849  *   Pattern specification (list terminated by the END pattern item).
 850  * @param[in] actions
 851  *   Associated actions (list terminated by the END action).
 852  * @param[out] error
 853  *   Perform verbose error reporting if not NULL. PMDs initialize this
 854  *   structure in case of error only.
 855  *
 856  * @return
 857  *   A valid handle in case of success, NULL otherwise and rte_errno is set
 858  *   to the positive version of one of the error codes defined for
 859  *   rte_flow_validate().
 860  */
 861 struct rte_flow *
 862 rte_flow_create(uint8_t port_id,
 863                 const struct rte_flow_attr *attr,
 864                 const struct rte_flow_item pattern[],
 865                 const struct rte_flow_action actions[],
 866                 struct rte_flow_error *error);
 867
 868 /**
 869  * Destroy a flow rule on a given port.
 870  *
 871  * Failure to destroy a flow rule handle may occur when other flow rules
 872  * depend on it, and destroying it would result in an inconsistent state.
 873  *
 874  * This function is only guaranteed to succeed if handles are destroyed in
 875  * reverse order of their creation.
 876  *
 877  * @param port_id
 878  *   Port identifier of Ethernet device.
 879  * @param flow
 880  *   Flow rule handle to destroy.
 881  * @param[out] error
 882  *   Perform verbose error reporting if not NULL. PMDs initialize this
 883  *   structure in case of error only.
 884  *
 885  * @return
 886  *   0 on success, a negative errno value otherwise and rte_errno is set.
 887  */
 888 int
 889 rte_flow_destroy(uint8_t port_id,
 890                  struct rte_flow *flow,
 891                  struct rte_flow_error *error);
 892
 893 /**
 894  * Destroy all flow rules associated with a port.
 895  *
 896  * In the unlikely event of failure, handles are still considered destroyed
 897  * and no longer valid but the port must be assumed to be in an inconsistent
 898  * state.
 899  *
 900  * @param port_id
 901  *   Port identifier of Ethernet device.
 902  * @param[out] error
 903  *   Perform verbose error reporting if not NULL. PMDs initialize this
 904  *   structure in case of error only.
 905  *
 906  * @return
 907  *   0 on success, a negative errno value otherwise and rte_errno is set.
 908  */
 909 int
 910 rte_flow_flush(uint8_t port_id,
 911                struct rte_flow_error *error);
 912
 913 /**
 914  * Query an existing flow rule.
 915  *
 916  * This function allows retrieving flow-specific data such as counters.
 917  * Data is gathered by special actions which must be present in the flow
 918  * rule definition.
 919  *
 920  * \see RTE_FLOW_ACTION_TYPE_COUNT
 921  *
 922  * @param port_id
 923  *   Port identifier of Ethernet device.
 924  * @param flow
 925  *   Flow rule handle to query.
 926  * @param action
 927  *   Action type to query.
 928  * @param[in, out] data
 929  *   Pointer to storage for the associated query data type.
 930  * @param[out] error
 931  *   Perform verbose error reporting if not NULL. PMDs initialize this
 932  *   structure in case of error only.
 933  *
 934  * @return
 935  *   0 on success, a negative errno value otherwise and rte_errno is set.
 936  */
 937 int
 938 rte_flow_query(uint8_t port_id,
 939                struct rte_flow *flow,
 940                enum rte_flow_action_type action,
 941                void *data,
 942                struct rte_flow_error *error);
 943
 944 #ifdef __cplusplus
 945 }
 946 #endif
 947
 948 #endif /* RTE_FLOW_H_ */