lib/librte_ether/rte_flow.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2016 6WIND S.A.
   3  * Copyright 2016 Mellanox Technologies, Ltd
   4  */
   5
   6 #ifndef RTE_FLOW_H_
   7 #define RTE_FLOW_H_
   8
   9 /**
  10  * @file
  11  * RTE generic flow API
  12  *
  13  * This interface provides the ability to program packet matching and
  14  * associated actions in hardware through flow rules.
  15  */
  16
  17 #include <stddef.h>
  18 #include <stdint.h>
  19
  20 #include <rte_arp.h>
  21 #include <rte_ether.h>
  22 #include <rte_eth_ctrl.h>
  23 #include <rte_icmp.h>
  24 #include <rte_ip.h>
  25 #include <rte_sctp.h>
  26 #include <rte_tcp.h>
  27 #include <rte_udp.h>
  28 #include <rte_byteorder.h>
  29 #include <rte_esp.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * Flow rule attributes.
  37  *
  38  * Priorities are set on two levels: per group and per rule within groups.
  39  *
  40  * Lower values denote higher priority, the highest priority for both levels
  41  * is 0, so that a rule with priority 0 in group 8 is always matched after a
  42  * rule with priority 8 in group 0.
  43  *
  44  * Although optional, applications are encouraged to group similar rules as
  45  * much as possible to fully take advantage of hardware capabilities
  46  * (e.g. optimized matching) and work around limitations (e.g. a single
  47  * pattern type possibly allowed in a given group).
  48  *
  49  * Group and priority levels are arbitrary and up to the application, they
  50  * do not need to be contiguous nor start from 0, however the maximum number
  51  * varies between devices and may be affected by existing flow rules.
  52  *
  53  * If a packet is matched by several rules of a given group for a given
  54  * priority level, the outcome is undefined. It can take any path, may be
  55  * duplicated or even cause unrecoverable errors.
  56  *
  57  * Note that support for more than a single group and priority level is not
  58  * guaranteed.
  59  *
  60  * Flow rules can apply to inbound and/or outbound traffic (ingress/egress).
  61  *
  62  * Several pattern items and actions are valid and can be used in both
  63  * directions. Those valid for only one direction are described as such.
  64  *
  65  * At least one direction must be specified.
  66  *
  67  * Specifying both directions at once for a given rule is not recommended
  68  * but may be valid in a few cases (e.g. shared counter).
  69  */
  70 struct rte_flow_attr {
  71         uint32_t group; /**< Priority group. */
  72         uint32_t priority; /**< Priority level within group. */
  73         uint32_t ingress:1; /**< Rule applies to ingress traffic. */
  74         uint32_t egress:1; /**< Rule applies to egress traffic. */
  75         uint32_t reserved:30; /**< Reserved, must be zero. */
  76 };
  77
  78 /**
  79  * Matching pattern item types.
  80  *
  81  * Pattern items fall in two categories:
  82  *
  83  * - Matching protocol headers and packet data, usually associated with a
  84  *   specification structure. These must be stacked in the same order as the
  85  *   protocol layers to match inside packets, starting from the lowest.
  86  *
  87  * - Matching meta-data or affecting pattern processing, often without a
  88  *   specification structure. Since they do not match packet contents, their
  89  *   position in the list is usually not relevant.
  90  *
  91  * See the description of individual types for more information. Those
  92  * marked with [META] fall into the second category.
  93  */
  94 enum rte_flow_item_type {
  95         /**
  96          * [META]
  97          *
  98          * End marker for item lists. Prevents further processing of items,
  99          * thereby ending the pattern.
 100          *
 101          * No associated specification structure.
 102          */
 103         RTE_FLOW_ITEM_TYPE_END,
 104
 105         /**
 106          * [META]
 107          *
 108          * Used as a placeholder for convenience. It is ignored and simply
 109          * discarded by PMDs.
 110          *
 111          * No associated specification structure.
 112          */
 113         RTE_FLOW_ITEM_TYPE_VOID,
 114
 115         /**
 116          * [META]
 117          *
 118          * Inverted matching, i.e. process packets that do not match the
 119          * pattern.
 120          *
 121          * No associated specification structure.
 122          */
 123         RTE_FLOW_ITEM_TYPE_INVERT,
 124
 125         /**
 126          * Matches any protocol in place of the current layer, a single ANY
 127          * may also stand for several protocol layers.
 128          *
 129          * See struct rte_flow_item_any.
 130          */
 131         RTE_FLOW_ITEM_TYPE_ANY,
 132
 133         /**
 134          * [META]
 135          *
 136          * Matches packets addressed to the physical function of the device.
 137          *
 138          * If the underlying device function differs from the one that would
 139          * normally receive the matched traffic, specifying this item
 140          * prevents it from reaching that device unless the flow rule
 141          * contains a PF action. Packets are not duplicated between device
 142          * instances by default.
 143          *
 144          * No associated specification structure.
 145          */
 146         RTE_FLOW_ITEM_TYPE_PF,
 147
 148         /**
 149          * [META]
 150          *
 151          * Matches packets addressed to a virtual function ID of the device.
 152          *
 153          * If the underlying device function differs from the one that would
 154          * normally receive the matched traffic, specifying this item
 155          * prevents it from reaching that device unless the flow rule
 156          * contains a VF action. Packets are not duplicated between device
 157          * instances by default.
 158          *
 159          * See struct rte_flow_item_vf.
 160          */
 161         RTE_FLOW_ITEM_TYPE_VF,
 162
 163         /**
 164          * [META]
 165          *
 166          * Matches packets coming from the specified physical port of the
 167          * underlying device.
 168          *
 169          * The first PORT item overrides the physical port normally
 170          * associated with the specified DPDK input port (port_id). This
 171          * item can be provided several times to match additional physical
 172          * ports.
 173          *
 174          * See struct rte_flow_item_port.
 175          */
 176         RTE_FLOW_ITEM_TYPE_PORT,
 177
 178         /**
 179          * Matches a byte string of a given length at a given offset.
 180          *
 181          * See struct rte_flow_item_raw.
 182          */
 183         RTE_FLOW_ITEM_TYPE_RAW,
 184
 185         /**
 186          * Matches an Ethernet header.
 187          *
 188          * See struct rte_flow_item_eth.
 189          */
 190         RTE_FLOW_ITEM_TYPE_ETH,
 191
 192         /**
 193          * Matches an 802.1Q/ad VLAN tag.
 194          *
 195          * See struct rte_flow_item_vlan.
 196          */
 197         RTE_FLOW_ITEM_TYPE_VLAN,
 198
 199         /**
 200          * Matches an IPv4 header.
 201          *
 202          * See struct rte_flow_item_ipv4.
 203          */
 204         RTE_FLOW_ITEM_TYPE_IPV4,
 205
 206         /**
 207          * Matches an IPv6 header.
 208          *
 209          * See struct rte_flow_item_ipv6.
 210          */
 211         RTE_FLOW_ITEM_TYPE_IPV6,
 212
 213         /**
 214          * Matches an ICMP header.
 215          *
 216          * See struct rte_flow_item_icmp.
 217          */
 218         RTE_FLOW_ITEM_TYPE_ICMP,
 219
 220         /**
 221          * Matches a UDP header.
 222          *
 223          * See struct rte_flow_item_udp.
 224          */
 225         RTE_FLOW_ITEM_TYPE_UDP,
 226
 227         /**
 228          * Matches a TCP header.
 229          *
 230          * See struct rte_flow_item_tcp.
 231          */
 232         RTE_FLOW_ITEM_TYPE_TCP,
 233
 234         /**
 235          * Matches a SCTP header.
 236          *
 237          * See struct rte_flow_item_sctp.
 238          */
 239         RTE_FLOW_ITEM_TYPE_SCTP,
 240
 241         /**
 242          * Matches a VXLAN header.
 243          *
 244          * See struct rte_flow_item_vxlan.
 245          */
 246         RTE_FLOW_ITEM_TYPE_VXLAN,
 247
 248         /**
 249          * Matches a E_TAG header.
 250          *
 251          * See struct rte_flow_item_e_tag.
 252          */
 253         RTE_FLOW_ITEM_TYPE_E_TAG,
 254
 255         /**
 256          * Matches a NVGRE header.
 257          *
 258          * See struct rte_flow_item_nvgre.
 259          */
 260         RTE_FLOW_ITEM_TYPE_NVGRE,
 261
 262         /**
 263          * Matches a MPLS header.
 264          *
 265          * See struct rte_flow_item_mpls.
 266          */
 267         RTE_FLOW_ITEM_TYPE_MPLS,
 268
 269         /**
 270          * Matches a GRE header.
 271          *
 272          * See struct rte_flow_item_gre.
 273          */
 274         RTE_FLOW_ITEM_TYPE_GRE,
 275
 276         /**
 277          * [META]
 278          *
 279          * Fuzzy pattern match, expect faster than default.
 280          *
 281          * This is for device that support fuzzy matching option.
 282          * Usually a fuzzy matching is fast but the cost is accuracy.
 283          *
 284          * See struct rte_flow_item_fuzzy.
 285          */
 286         RTE_FLOW_ITEM_TYPE_FUZZY,
 287
 288         /**
 289          * Matches a GTP header.
 290          *
 291          * Configure flow for GTP packets.
 292          *
 293          * See struct rte_flow_item_gtp.
 294          */
 295         RTE_FLOW_ITEM_TYPE_GTP,
 296
 297         /**
 298          * Matches a GTP header.
 299          *
 300          * Configure flow for GTP-C packets.
 301          *
 302          * See struct rte_flow_item_gtp.
 303          */
 304         RTE_FLOW_ITEM_TYPE_GTPC,
 305
 306         /**
 307          * Matches a GTP header.
 308          *
 309          * Configure flow for GTP-U packets.
 310          *
 311          * See struct rte_flow_item_gtp.
 312          */
 313         RTE_FLOW_ITEM_TYPE_GTPU,
 314
 315         /**
 316          * Matches a ESP header.
 317          *
 318          * See struct rte_flow_item_esp.
 319          */
 320         RTE_FLOW_ITEM_TYPE_ESP,
 321
 322         /**
 323          * Matches a GENEVE header.
 324          *
 325          * See struct rte_flow_item_geneve.
 326          */
 327         RTE_FLOW_ITEM_TYPE_GENEVE,
 328 };
 329
 330 /**
 331  * RTE_FLOW_ITEM_TYPE_ANY
 332  *
 333  * Matches any protocol in place of the current layer, a single ANY may also
 334  * stand for several protocol layers.
 335  *
 336  * This is usually specified as the first pattern item when looking for a
 337  * protocol anywhere in a packet.
 338  *
 339  * A zeroed mask stands for any number of layers.
 340  */
 341 struct rte_flow_item_any {
 342         uint32_t num; /**< Number of layers covered. */
 343 };
 344
 345 /** Default mask for RTE_FLOW_ITEM_TYPE_ANY. */
 346 #ifndef __cplusplus
 347 static const struct rte_flow_item_any rte_flow_item_any_mask = {
 348         .num = 0x00000000,
 349 };
 350 #endif
 351
 352 /**
 353  * RTE_FLOW_ITEM_TYPE_VF
 354  *
 355  * Matches packets addressed to a virtual function ID of the device.
 356  *
 357  * If the underlying device function differs from the one that would
 358  * normally receive the matched traffic, specifying this item prevents it
 359  * from reaching that device unless the flow rule contains a VF
 360  * action. Packets are not duplicated between device instances by default.
 361  *
 362  * - Likely to return an error or never match any traffic if this causes a
 363  *   VF device to match traffic addressed to a different VF.
 364  * - Can be specified multiple times to match traffic addressed to several
 365  *   VF IDs.
 366  * - Can be combined with a PF item to match both PF and VF traffic.
 367  *
 368  * A zeroed mask can be used to match any VF ID.
 369  */
 370 struct rte_flow_item_vf {
 371         uint32_t id; /**< Destination VF ID. */
 372 };
 373
 374 /** Default mask for RTE_FLOW_ITEM_TYPE_VF. */
 375 #ifndef __cplusplus
 376 static const struct rte_flow_item_vf rte_flow_item_vf_mask = {
 377         .id = 0x00000000,
 378 };
 379 #endif
 380
 381 /**
 382  * RTE_FLOW_ITEM_TYPE_PORT
 383  *
 384  * Matches packets coming from the specified physical port of the underlying
 385  * device.
 386  *
 387  * The first PORT item overrides the physical port normally associated with
 388  * the specified DPDK input port (port_id). This item can be provided
 389  * several times to match additional physical ports.
 390  *
 391  * Note that physical ports are not necessarily tied to DPDK input ports
 392  * (port_id) when those are not under DPDK control. Possible values are
 393  * specific to each device, they are not necessarily indexed from zero and
 394  * may not be contiguous.
 395  *
 396  * As a device property, the list of allowed values as well as the value
 397  * associated with a port_id should be retrieved by other means.
 398  *
 399  * A zeroed mask can be used to match any port index.
 400  */
 401 struct rte_flow_item_port {
 402         uint32_t index; /**< Physical port index. */
 403 };
 404
 405 /** Default mask for RTE_FLOW_ITEM_TYPE_PORT. */
 406 #ifndef __cplusplus
 407 static const struct rte_flow_item_port rte_flow_item_port_mask = {
 408         .index = 0x00000000,
 409 };
 410 #endif
 411
 412 /**
 413  * RTE_FLOW_ITEM_TYPE_RAW
 414  *
 415  * Matches a byte string of a given length at a given offset.
 416  *
 417  * Offset is either absolute (using the start of the packet) or relative to
 418  * the end of the previous matched item in the stack, in which case negative
 419  * values are allowed.
 420  *
 421  * If search is enabled, offset is used as the starting point. The search
 422  * area can be delimited by setting limit to a nonzero value, which is the
 423  * maximum number of bytes after offset where the pattern may start.
 424  *
 425  * Matching a zero-length pattern is allowed, doing so resets the relative
 426  * offset for subsequent items.
 427  *
 428  * This type does not support ranges (struct rte_flow_item.last).
 429  */
 430 struct rte_flow_item_raw {
 431         uint32_t relative:1; /**< Look for pattern after the previous item. */
 432         uint32_t search:1; /**< Search pattern from offset (see also limit). */
 433         uint32_t reserved:30; /**< Reserved, must be set to zero. */
 434         int32_t offset; /**< Absolute or relative offset for pattern. */
 435         uint16_t limit; /**< Search area limit for start of pattern. */
 436         uint16_t length; /**< Pattern length. */
 437         const uint8_t *pattern; /**< Byte string to look for. */
 438 };
 439
 440 /** Default mask for RTE_FLOW_ITEM_TYPE_RAW. */
 441 #ifndef __cplusplus
 442 static const struct rte_flow_item_raw rte_flow_item_raw_mask = {
 443         .relative = 1,
 444         .search = 1,
 445         .reserved = 0x3fffffff,
 446         .offset = 0xffffffff,
 447         .limit = 0xffff,
 448         .length = 0xffff,
 449         .pattern = NULL,
 450 };
 451 #endif
 452
 453 /**
 454  * RTE_FLOW_ITEM_TYPE_ETH
 455  *
 456  * Matches an Ethernet header.
 457  */
 458 struct rte_flow_item_eth {
 459         struct ether_addr dst; /**< Destination MAC. */
 460         struct ether_addr src; /**< Source MAC. */
 461         rte_be16_t type; /**< EtherType. */
 462 };
 463
 464 /** Default mask for RTE_FLOW_ITEM_TYPE_ETH. */
 465 #ifndef __cplusplus
 466 static const struct rte_flow_item_eth rte_flow_item_eth_mask = {
 467         .dst.addr_bytes = "\xff\xff\xff\xff\xff\xff",
 468         .src.addr_bytes = "\xff\xff\xff\xff\xff\xff",
 469         .type = RTE_BE16(0x0000),
 470 };
 471 #endif
 472
 473 /**
 474  * RTE_FLOW_ITEM_TYPE_VLAN
 475  *
 476  * Matches an 802.1Q/ad VLAN tag.
 477  *
 478  * This type normally follows either RTE_FLOW_ITEM_TYPE_ETH or
 479  * RTE_FLOW_ITEM_TYPE_VLAN.
 480  */
 481 struct rte_flow_item_vlan {
 482         rte_be16_t tpid; /**< Tag protocol identifier. */
 483         rte_be16_t tci; /**< Tag control information. */
 484 };
 485
 486 /** Default mask for RTE_FLOW_ITEM_TYPE_VLAN. */
 487 #ifndef __cplusplus
 488 static const struct rte_flow_item_vlan rte_flow_item_vlan_mask = {
 489         .tpid = RTE_BE16(0x0000),
 490         .tci = RTE_BE16(0xffff),
 491 };
 492 #endif
 493
 494 /**
 495  * RTE_FLOW_ITEM_TYPE_IPV4
 496  *
 497  * Matches an IPv4 header.
 498  *
 499  * Note: IPv4 options are handled by dedicated pattern items.
 500  */
 501 struct rte_flow_item_ipv4 {
 502         struct ipv4_hdr hdr; /**< IPv4 header definition. */
 503 };
 504
 505 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV4. */
 506 #ifndef __cplusplus
 507 static const struct rte_flow_item_ipv4 rte_flow_item_ipv4_mask = {
 508         .hdr = {
 509                 .src_addr = RTE_BE32(0xffffffff),
 510                 .dst_addr = RTE_BE32(0xffffffff),
 511         },
 512 };
 513 #endif
 514
 515 /**
 516  * RTE_FLOW_ITEM_TYPE_IPV6.
 517  *
 518  * Matches an IPv6 header.
 519  *
 520  * Note: IPv6 options are handled by dedicated pattern items.
 521  */
 522 struct rte_flow_item_ipv6 {
 523         struct ipv6_hdr hdr; /**< IPv6 header definition. */
 524 };
 525
 526 /** Default mask for RTE_FLOW_ITEM_TYPE_IPV6. */
 527 #ifndef __cplusplus
 528 static const struct rte_flow_item_ipv6 rte_flow_item_ipv6_mask = {
 529         .hdr = {
 530                 .src_addr =
 531                         "\xff\xff\xff\xff\xff\xff\xff\xff"
 532                         "\xff\xff\xff\xff\xff\xff\xff\xff",
 533                 .dst_addr =
 534                         "\xff\xff\xff\xff\xff\xff\xff\xff"
 535                         "\xff\xff\xff\xff\xff\xff\xff\xff",
 536         },
 537 };
 538 #endif
 539
 540 /**
 541  * RTE_FLOW_ITEM_TYPE_ICMP.
 542  *
 543  * Matches an ICMP header.
 544  */
 545 struct rte_flow_item_icmp {
 546         struct icmp_hdr hdr; /**< ICMP header definition. */
 547 };
 548
 549 /** Default mask for RTE_FLOW_ITEM_TYPE_ICMP. */
 550 #ifndef __cplusplus
 551 static const struct rte_flow_item_icmp rte_flow_item_icmp_mask = {
 552         .hdr = {
 553                 .icmp_type = 0xff,
 554                 .icmp_code = 0xff,
 555         },
 556 };
 557 #endif
 558
 559 /**
 560  * RTE_FLOW_ITEM_TYPE_UDP.
 561  *
 562  * Matches a UDP header.
 563  */
 564 struct rte_flow_item_udp {
 565         struct udp_hdr hdr; /**< UDP header definition. */
 566 };
 567
 568 /** Default mask for RTE_FLOW_ITEM_TYPE_UDP. */
 569 #ifndef __cplusplus
 570 static const struct rte_flow_item_udp rte_flow_item_udp_mask = {
 571         .hdr = {
 572                 .src_port = RTE_BE16(0xffff),
 573                 .dst_port = RTE_BE16(0xffff),
 574         },
 575 };
 576 #endif
 577
 578 /**
 579  * RTE_FLOW_ITEM_TYPE_TCP.
 580  *
 581  * Matches a TCP header.
 582  */
 583 struct rte_flow_item_tcp {
 584         struct tcp_hdr hdr; /**< TCP header definition. */
 585 };
 586
 587 /** Default mask for RTE_FLOW_ITEM_TYPE_TCP. */
 588 #ifndef __cplusplus
 589 static const struct rte_flow_item_tcp rte_flow_item_tcp_mask = {
 590         .hdr = {
 591                 .src_port = RTE_BE16(0xffff),
 592                 .dst_port = RTE_BE16(0xffff),
 593         },
 594 };
 595 #endif
 596
 597 /**
 598  * RTE_FLOW_ITEM_TYPE_SCTP.
 599  *
 600  * Matches a SCTP header.
 601  */
 602 struct rte_flow_item_sctp {
 603         struct sctp_hdr hdr; /**< SCTP header definition. */
 604 };
 605
 606 /** Default mask for RTE_FLOW_ITEM_TYPE_SCTP. */
 607 #ifndef __cplusplus
 608 static const struct rte_flow_item_sctp rte_flow_item_sctp_mask = {
 609         .hdr = {
 610                 .src_port = RTE_BE16(0xffff),
 611                 .dst_port = RTE_BE16(0xffff),
 612         },
 613 };
 614 #endif
 615
 616 /**
 617  * RTE_FLOW_ITEM_TYPE_VXLAN.
 618  *
 619  * Matches a VXLAN header (RFC 7348).
 620  */
 621 struct rte_flow_item_vxlan {
 622         uint8_t flags; /**< Normally 0x08 (I flag). */
 623         uint8_t rsvd0[3]; /**< Reserved, normally 0x000000. */
 624         uint8_t vni[3]; /**< VXLAN identifier. */
 625         uint8_t rsvd1; /**< Reserved, normally 0x00. */
 626 };
 627
 628 /** Default mask for RTE_FLOW_ITEM_TYPE_VXLAN. */
 629 #ifndef __cplusplus
 630 static const struct rte_flow_item_vxlan rte_flow_item_vxlan_mask = {
 631         .vni = "\xff\xff\xff",
 632 };
 633 #endif
 634
 635 /**
 636  * RTE_FLOW_ITEM_TYPE_E_TAG.
 637  *
 638  * Matches a E-tag header.
 639  */
 640 struct rte_flow_item_e_tag {
 641         rte_be16_t tpid; /**< Tag protocol identifier (0x893F). */
 642         /**
 643          * E-Tag control information (E-TCI).
 644          * E-PCP (3b), E-DEI (1b), ingress E-CID base (12b).
 645          */
 646         rte_be16_t epcp_edei_in_ecid_b;
 647         /** Reserved (2b), GRP (2b), E-CID base (12b). */
 648         rte_be16_t rsvd_grp_ecid_b;
 649         uint8_t in_ecid_e; /**< Ingress E-CID ext. */
 650         uint8_t ecid_e; /**< E-CID ext. */
 651 };
 652
 653 /** Default mask for RTE_FLOW_ITEM_TYPE_E_TAG. */
 654 #ifndef __cplusplus
 655 static const struct rte_flow_item_e_tag rte_flow_item_e_tag_mask = {
 656         .rsvd_grp_ecid_b = RTE_BE16(0x3fff),
 657 };
 658 #endif
 659
 660 /**
 661  * RTE_FLOW_ITEM_TYPE_NVGRE.
 662  *
 663  * Matches a NVGRE header.
 664  */
 665 struct rte_flow_item_nvgre {
 666         /**
 667          * Checksum (1b), undefined (1b), key bit (1b), sequence number (1b),
 668          * reserved 0 (9b), version (3b).
 669          *
 670          * c_k_s_rsvd0_ver must have value 0x2000 according to RFC 7637.
 671          */
 672         rte_be16_t c_k_s_rsvd0_ver;
 673         rte_be16_t protocol; /**< Protocol type (0x6558). */
 674         uint8_t tni[3]; /**< Virtual subnet ID. */
 675         uint8_t flow_id; /**< Flow ID. */
 676 };
 677
 678 /** Default mask for RTE_FLOW_ITEM_TYPE_NVGRE. */
 679 #ifndef __cplusplus
 680 static const struct rte_flow_item_nvgre rte_flow_item_nvgre_mask = {
 681         .tni = "\xff\xff\xff",
 682 };
 683 #endif
 684
 685 /**
 686  * RTE_FLOW_ITEM_TYPE_MPLS.
 687  *
 688  * Matches a MPLS header.
 689  */
 690 struct rte_flow_item_mpls {
 691         /**
 692          * Label (20b), TC (3b), Bottom of Stack (1b).
 693          */
 694         uint8_t label_tc_s[3];
 695         uint8_t ttl; /** Time-to-Live. */
 696 };
 697
 698 /** Default mask for RTE_FLOW_ITEM_TYPE_MPLS. */
 699 #ifndef __cplusplus
 700 static const struct rte_flow_item_mpls rte_flow_item_mpls_mask = {
 701         .label_tc_s = "\xff\xff\xf0",
 702 };
 703 #endif
 704
 705 /**
 706  * RTE_FLOW_ITEM_TYPE_GRE.
 707  *
 708  * Matches a GRE header.
 709  */
 710 struct rte_flow_item_gre {
 711         /**
 712          * Checksum (1b), reserved 0 (12b), version (3b).
 713          * Refer to RFC 2784.
 714          */
 715         rte_be16_t c_rsvd0_ver;
 716         rte_be16_t protocol; /**< Protocol type. */
 717 };
 718
 719 /** Default mask for RTE_FLOW_ITEM_TYPE_GRE. */
 720 #ifndef __cplusplus
 721 static const struct rte_flow_item_gre rte_flow_item_gre_mask = {
 722         .protocol = RTE_BE16(0xffff),
 723 };
 724 #endif
 725
 726 /**
 727  * RTE_FLOW_ITEM_TYPE_FUZZY
 728  *
 729  * Fuzzy pattern match, expect faster than default.
 730  *
 731  * This is for device that support fuzzy match option.
 732  * Usually a fuzzy match is fast but the cost is accuracy.
 733  * i.e. Signature Match only match pattern's hash value, but it is
 734  * possible two different patterns have the same hash value.
 735  *
 736  * Matching accuracy level can be configure by threshold.
 737  * Driver can divide the range of threshold and map to different
 738  * accuracy levels that device support.
 739  *
 740  * Threshold 0 means perfect match (no fuzziness), while threshold
 741  * 0xffffffff means fuzziest match.
 742  */
 743 struct rte_flow_item_fuzzy {
 744         uint32_t thresh; /**< Accuracy threshold. */
 745 };
 746
 747 /** Default mask for RTE_FLOW_ITEM_TYPE_FUZZY. */
 748 #ifndef __cplusplus
 749 static const struct rte_flow_item_fuzzy rte_flow_item_fuzzy_mask = {
 750         .thresh = 0xffffffff,
 751 };
 752 #endif
 753
 754 /**
 755  * RTE_FLOW_ITEM_TYPE_GTP.
 756  *
 757  * Matches a GTPv1 header.
 758  */
 759 struct rte_flow_item_gtp {
 760         /**
 761          * Version (3b), protocol type (1b), reserved (1b),
 762          * Extension header flag (1b),
 763          * Sequence number flag (1b),
 764          * N-PDU number flag (1b).
 765          */
 766         uint8_t v_pt_rsv_flags;
 767         uint8_t msg_type; /**< Message type. */
 768         rte_be16_t msg_len; /**< Message length. */
 769         rte_be32_t teid; /**< Tunnel endpoint identifier. */
 770 };
 771
 772 /** Default mask for RTE_FLOW_ITEM_TYPE_GTP. */
 773 #ifndef __cplusplus
 774 static const struct rte_flow_item_gtp rte_flow_item_gtp_mask = {
 775         .teid = RTE_BE32(0xffffffff),
 776 };
 777 #endif
 778
 779 /**
 780  * RTE_FLOW_ITEM_TYPE_ESP
 781  *
 782  * Matches an ESP header.
 783  */
 784 struct rte_flow_item_esp {
 785         struct esp_hdr hdr; /**< ESP header definition. */
 786 };
 787
 788 /** Default mask for RTE_FLOW_ITEM_TYPE_ESP. */
 789 #ifndef __cplusplus
 790 static const struct rte_flow_item_esp rte_flow_item_esp_mask = {
 791         .hdr = {
 792                 .spi = 0xffffffff,
 793         },
 794 };
 795 #endif
 796
 797 /**
 798  * RTE_FLOW_ITEM_TYPE_GENEVE.
 799  *
 800  * Matches a GENEVE header.
 801  */
 802 struct rte_flow_item_geneve {
 803         /**
 804          * Version (2b), length of the options fields (6b), OAM packet (1b),
 805          * critical options present (1b), reserved 0 (6b).
 806          */
 807         rte_be16_t ver_opt_len_o_c_rsvd0;
 808         rte_be16_t protocol; /**< Protocol type. */
 809         uint8_t vni[3]; /**< Virtual Network Identifier. */
 810         uint8_t rsvd1; /**< Reserved, normally 0x00. */
 811 };
 812
 813 /** Default mask for RTE_FLOW_ITEM_TYPE_GENEVE. */
 814 #ifndef __cplusplus
 815 static const struct rte_flow_item_geneve rte_flow_item_geneve_mask = {
 816         .vni = "\xff\xff\xff",
 817 };
 818 #endif
 819
 820 /**
 821  * Matching pattern item definition.
 822  *
 823  * A pattern is formed by stacking items starting from the lowest protocol
 824  * layer to match. This stacking restriction does not apply to meta items
 825  * which can be placed anywhere in the stack without affecting the meaning
 826  * of the resulting pattern.
 827  *
 828  * Patterns are terminated by END items.
 829  *
 830  * The spec field should be a valid pointer to a structure of the related
 831  * item type. It may remain unspecified (NULL) in many cases to request
 832  * broad (nonspecific) matching. In such cases, last and mask must also be
 833  * set to NULL.
 834  *
 835  * Optionally, last can point to a structure of the same type to define an
 836  * inclusive range. This is mostly supported by integer and address fields,
 837  * may cause errors otherwise. Fields that do not support ranges must be set
 838  * to 0 or to the same value as the corresponding fields in spec.
 839  *
 840  * Only the fields defined to nonzero values in the default masks (see
 841  * rte_flow_item_{name}_mask constants) are considered relevant by
 842  * default. This can be overridden by providing a mask structure of the
 843  * same type with applicable bits set to one. It can also be used to
 844  * partially filter out specific fields (e.g. as an alternate mean to match
 845  * ranges of IP addresses).
 846  *
 847  * Mask is a simple bit-mask applied before interpreting the contents of
 848  * spec and last, which may yield unexpected results if not used
 849  * carefully. For example, if for an IPv4 address field, spec provides
 850  * 10.1.2.3, last provides 10.3.4.5 and mask provides 255.255.0.0, the
 851  * effective range becomes 10.1.0.0 to 10.3.255.255.
 852  */
 853 struct rte_flow_item {
 854         enum rte_flow_item_type type; /**< Item type. */
 855         const void *spec; /**< Pointer to item specification structure. */
 856         const void *last; /**< Defines an inclusive range (spec to last). */
 857         const void *mask; /**< Bit-mask applied to spec and last. */
 858 };
 859
 860 /**
 861  * Action types.
 862  *
 863  * Each possible action is represented by a type. Some have associated
 864  * configuration structures. Several actions combined in a list can be
 865  * assigned to a flow rule and are performed in order.
 866  *
 867  * They fall in three categories:
 868  *
 869  * - Actions that modify the fate of matching traffic, for instance by
 870  *   dropping or assigning it a specific destination.
 871  *
 872  * - Actions that modify matching traffic contents or its properties. This
 873  *   includes adding/removing encapsulation, encryption, compression and
 874  *   marks.
 875  *
 876  * - Actions related to the flow rule itself, such as updating counters or
 877  *   making it non-terminating.
 878  *
 879  * Flow rules being terminating by default, not specifying any action of the
 880  * fate kind results in undefined behavior. This applies to both ingress and
 881  * egress.
 882  *
 883  * PASSTHRU, when supported, makes a flow rule non-terminating.
 884  */
 885 enum rte_flow_action_type {
 886         /**
 887          * End marker for action lists. Prevents further processing of
 888          * actions, thereby ending the list.
 889          *
 890          * No associated configuration structure.
 891          */
 892         RTE_FLOW_ACTION_TYPE_END,
 893
 894         /**
 895          * Used as a placeholder for convenience. It is ignored and simply
 896          * discarded by PMDs.
 897          *
 898          * No associated configuration structure.
 899          */
 900         RTE_FLOW_ACTION_TYPE_VOID,
 901
 902         /**
 903          * Leaves traffic up for additional processing by subsequent flow
 904          * rules; makes a flow rule non-terminating.
 905          *
 906          * No associated configuration structure.
 907          */
 908         RTE_FLOW_ACTION_TYPE_PASSTHRU,
 909
 910         /**
 911          * Attaches an integer value to packets and sets PKT_RX_FDIR and
 912          * PKT_RX_FDIR_ID mbuf flags.
 913          *
 914          * See struct rte_flow_action_mark.
 915          */
 916         RTE_FLOW_ACTION_TYPE_MARK,
 917
 918         /**
 919          * Flags packets. Similar to MARK without a specific value; only
 920          * sets the PKT_RX_FDIR mbuf flag.
 921          *
 922          * No associated configuration structure.
 923          */
 924         RTE_FLOW_ACTION_TYPE_FLAG,
 925
 926         /**
 927          * Assigns packets to a given queue index.
 928          *
 929          * See struct rte_flow_action_queue.
 930          */
 931         RTE_FLOW_ACTION_TYPE_QUEUE,
 932
 933         /**
 934          * Drops packets.
 935          *
 936          * PASSTHRU overrides this action if both are specified.
 937          *
 938          * No associated configuration structure.
 939          */
 940         RTE_FLOW_ACTION_TYPE_DROP,
 941
 942         /**
 943          * Enables counters for this flow rule.
 944          *
 945          * These counters can be retrieved and reset through rte_flow_query(),
 946          * see struct rte_flow_query_count.
 947          *
 948          * No associated configuration structure.
 949          */
 950         RTE_FLOW_ACTION_TYPE_COUNT,
 951
 952         /**
 953          * Similar to QUEUE, except RSS is additionally performed on packets
 954          * to spread them among several queues according to the provided
 955          * parameters.
 956          *
 957          * See struct rte_flow_action_rss.
 958          */
 959         RTE_FLOW_ACTION_TYPE_RSS,
 960
 961         /**
 962          * Redirects packets to the physical function (PF) of the current
 963          * device.
 964          *
 965          * No associated configuration structure.
 966          */
 967         RTE_FLOW_ACTION_TYPE_PF,
 968
 969         /**
 970          * Redirects packets to the virtual function (VF) of the current
 971          * device with the specified ID.
 972          *
 973          * See struct rte_flow_action_vf.
 974          */
 975         RTE_FLOW_ACTION_TYPE_VF,
 976
 977         /**
 978          * Traffic metering and policing (MTR).
 979          *
 980          * See struct rte_flow_action_meter.
 981          * See file rte_mtr.h for MTR object configuration.
 982          */
 983         RTE_FLOW_ACTION_TYPE_METER,
 984
 985         /**
 986          * Redirects packets to security engine of current device for security
 987          * processing as specified by security session.
 988          *
 989          * See struct rte_flow_action_security.
 990          */
 991         RTE_FLOW_ACTION_TYPE_SECURITY
 992 };
 993
 994 /**
 995  * RTE_FLOW_ACTION_TYPE_MARK
 996  *
 997  * Attaches an integer value to packets and sets PKT_RX_FDIR and
 998  * PKT_RX_FDIR_ID mbuf flags.
 999  *
1000  * This value is arbitrary and application-defined. Maximum allowed value
1001  * depends on the underlying implementation. It is returned in the
1002  * hash.fdir.hi mbuf field.
1003  */
1004 struct rte_flow_action_mark {
1005         uint32_t id; /**< Integer value to return with packets. */
1006 };
1007
1008 /**
1009  * RTE_FLOW_ACTION_TYPE_QUEUE
1010  *
1011  * Assign packets to a given queue index.
1012  */
1013 struct rte_flow_action_queue {
1014         uint16_t index; /**< Queue index to use. */
1015 };
1016
1017 /**
1018  * RTE_FLOW_ACTION_TYPE_COUNT (query)
1019  *
1020  * Query structure to retrieve and reset flow rule counters.
1021  */
1022 struct rte_flow_query_count {
1023         uint32_t reset:1; /**< Reset counters after query [in]. */
1024         uint32_t hits_set:1; /**< hits field is set [out]. */
1025         uint32_t bytes_set:1; /**< bytes field is set [out]. */
1026         uint32_t reserved:29; /**< Reserved, must be zero [in, out]. */
1027         uint64_t hits; /**< Number of hits for this rule [out]. */
1028         uint64_t bytes; /**< Number of bytes through this rule [out]. */
1029 };
1030
1031 /**
1032  * RTE_FLOW_ACTION_TYPE_RSS
1033  *
1034  * Similar to QUEUE, except RSS is additionally performed on packets to
1035  * spread them among several queues according to the provided parameters.
1036  *
1037  * Unlike global RSS settings used by other DPDK APIs, unsetting the
1038  * @p types field does not disable RSS in a flow rule. Doing so instead
1039  * requests safe unspecified "best-effort" settings from the underlying PMD,
1040  * which depending on the flow rule, may result in anything ranging from
1041  * empty (single queue) to all-inclusive RSS.
1042  *
1043  * Note: RSS hash result is stored in the hash.rss mbuf field which overlaps
1044  * hash.fdir.lo. Since the MARK action sets the hash.fdir.hi field only,
1045  * both can be requested simultaneously.
1046  */
1047 struct rte_flow_action_rss {
1048         enum rte_eth_hash_function func; /**< RSS hash function to apply. */
1049         /**
1050          * Packet encapsulation level RSS hash @p types apply to.
1051          *
1052          * - @p 0 requests the default behavior. Depending on the packet
1053          *   type, it can mean outermost, innermost, anything in between or
1054          *   even no RSS.
1055          *
1056          *   It basically stands for the innermost encapsulation level RSS
1057          *   can be performed on according to PMD and device capabilities.
1058          *
1059          * - @p 1 requests RSS to be performed on the outermost packet
1060          *   encapsulation level.
1061          *
1062          * - @p 2 and subsequent values request RSS to be performed on the
1063          *   specified inner packet encapsulation level, from outermost to
1064          *   innermost (lower to higher values).
1065          *
1066          * Values other than @p 0 are not necessarily supported.
1067          *
1068          * Requesting a specific RSS level on unrecognized traffic results
1069          * in undefined behavior. For predictable results, it is recommended
1070          * to make the flow rule pattern match packet headers up to the
1071          * requested encapsulation level so that only matching traffic goes
1072          * through.
1073          */
1074         uint32_t level;
1075         uint64_t types; /**< Specific RSS hash types (see ETH_RSS_*). */
1076         uint32_t key_len; /**< Hash key length in bytes. */
1077         uint32_t queue_num; /**< Number of entries in @p queue. */
1078         const uint8_t *key; /**< Hash key. */
1079         const uint16_t *queue; /**< Queue indices to use. */
1080 };
1081
1082 /**
1083  * RTE_FLOW_ACTION_TYPE_VF
1084  *
1085  * Redirects packets to a virtual function (VF) of the current device.
1086  *
1087  * Packets matched by a VF pattern item can be redirected to their original
1088  * VF ID instead of the specified one. This parameter may not be available
1089  * and is not guaranteed to work properly if the VF part is matched by a
1090  * prior flow rule or if packets are not addressed to a VF in the first
1091  * place.
1092  */
1093 struct rte_flow_action_vf {
1094         uint32_t original:1; /**< Use original VF ID if possible. */
1095         uint32_t reserved:31; /**< Reserved, must be zero. */
1096         uint32_t id; /**< VF ID to redirect packets to. */
1097 };
1098
1099 /**
1100  * RTE_FLOW_ACTION_TYPE_METER
1101  *
1102  * Traffic metering and policing (MTR).
1103  *
1104  * Packets matched by items of this type can be either dropped or passed to the
1105  * next item with their color set by the MTR object.
1106  */
1107 struct rte_flow_action_meter {
1108         uint32_t mtr_id; /**< MTR object ID created with rte_mtr_create(). */
1109 };
1110
1111 /**
1112  * RTE_FLOW_ACTION_TYPE_SECURITY
1113  *
1114  * Perform the security action on flows matched by the pattern items
1115  * according to the configuration of the security session.
1116  *
1117  * This action modifies the payload of matched flows. For INLINE_CRYPTO, the
1118  * security protocol headers and IV are fully provided by the application as
1119  * specified in the flow pattern. The payload of matching packets is
1120  * encrypted on egress, and decrypted and authenticated on ingress.
1121  * For INLINE_PROTOCOL, the security protocol is fully offloaded to HW,
1122  * providing full encapsulation and decapsulation of packets in security
1123  * protocols. The flow pattern specifies both the outer security header fields
1124  * and the inner packet fields. The security session specified in the action
1125  * must match the pattern parameters.
1126  *
1127  * The security session specified in the action must be created on the same
1128  * port as the flow action that is being specified.
1129  *
1130  * The ingress/egress flow attribute should match that specified in the
1131  * security session if the security session supports the definition of the
1132  * direction.
1133  *
1134  * Multiple flows can be configured to use the same security session.
1135  */
1136 struct rte_flow_action_security {
1137         void *security_session; /**< Pointer to security session structure. */
1138 };
1139
1140 /**
1141  * Definition of a single action.
1142  *
1143  * A list of actions is terminated by a END action.
1144  *
1145  * For simple actions without a configuration structure, conf remains NULL.
1146  */
1147 struct rte_flow_action {
1148         enum rte_flow_action_type type; /**< Action type. */
1149         const void *conf; /**< Pointer to action configuration structure. */
1150 };
1151
1152 /**
1153  * Opaque type returned after successfully creating a flow.
1154  *
1155  * This handle can be used to manage and query the related flow (e.g. to
1156  * destroy it or retrieve counters).
1157  */
1158 struct rte_flow;
1159
1160 /**
1161  * Verbose error types.
1162  *
1163  * Most of them provide the type of the object referenced by struct
1164  * rte_flow_error.cause.
1165  */
1166 enum rte_flow_error_type {
1167         RTE_FLOW_ERROR_TYPE_NONE, /**< No error. */
1168         RTE_FLOW_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
1169         RTE_FLOW_ERROR_TYPE_HANDLE, /**< Flow rule (handle). */
1170         RTE_FLOW_ERROR_TYPE_ATTR_GROUP, /**< Group field. */
1171         RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */
1172         RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */
1173         RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */
1174         RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */
1175         RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */
1176         RTE_FLOW_ERROR_TYPE_ITEM_SPEC, /**< Item specification. */
1177         RTE_FLOW_ERROR_TYPE_ITEM_LAST, /**< Item specification range. */
1178         RTE_FLOW_ERROR_TYPE_ITEM_MASK, /**< Item specification mask. */
1179         RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */
1180         RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */
1181         RTE_FLOW_ERROR_TYPE_ACTION_CONF, /**< Action configuration. */
1182         RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */
1183 };
1184
1185 /**
1186  * Verbose error structure definition.
1187  *
1188  * This object is normally allocated by applications and set by PMDs, the
1189  * message points to a constant string which does not need to be freed by
1190  * the application, however its pointer can be considered valid only as long
1191  * as its associated DPDK port remains configured. Closing the underlying
1192  * device or unloading the PMD invalidates it.
1193  *
1194  * Both cause and message may be NULL regardless of the error type.
1195  */
1196 struct rte_flow_error {
1197         enum rte_flow_error_type type; /**< Cause field and error types. */
1198         const void *cause; /**< Object responsible for the error. */
1199         const char *message; /**< Human-readable error message. */
1200 };
1201
1202 /**
1203  * Check whether a flow rule can be created on a given port.
1204  *
1205  * The flow rule is validated for correctness and whether it could be accepted
1206  * by the device given sufficient resources. The rule is checked against the
1207  * current device mode and queue configuration. The flow rule may also
1208  * optionally be validated against existing flow rules and device resources.
1209  * This function has no effect on the target device.
1210  *
1211  * The returned value is guaranteed to remain valid only as long as no
1212  * successful calls to rte_flow_create() or rte_flow_destroy() are made in
1213  * the meantime and no device parameter affecting flow rules in any way are
1214  * modified, due to possible collisions or resource limitations (although in
1215  * such cases EINVAL should not be returned).
1216  *
1217  * @param port_id
1218  *   Port identifier of Ethernet device.
1219  * @param[in] attr
1220  *   Flow rule attributes.
1221  * @param[in] pattern
1222  *   Pattern specification (list terminated by the END pattern item).
1223  * @param[in] actions
1224  *   Associated actions (list terminated by the END action).
1225  * @param[out] error
1226  *   Perform verbose error reporting if not NULL. PMDs initialize this
1227  *   structure in case of error only.
1228  *
1229  * @return
1230  *   0 if flow rule is valid and can be created. A negative errno value
1231  *   otherwise (rte_errno is also set), the following errors are defined:
1232  *
1233  *   -ENOSYS: underlying device does not support this functionality.
1234  *
1235  *   -EIO: underlying device is removed.
1236  *
1237  *   -EINVAL: unknown or invalid rule specification.
1238  *
1239  *   -ENOTSUP: valid but unsupported rule specification (e.g. partial
1240  *   bit-masks are unsupported).
1241  *
1242  *   -EEXIST: collision with an existing rule. Only returned if device
1243  *   supports flow rule collision checking and there was a flow rule
1244  *   collision. Not receiving this return code is no guarantee that creating
1245  *   the rule will not fail due to a collision.
1246  *
1247  *   -ENOMEM: not enough memory to execute the function, or if the device
1248  *   supports resource validation, resource limitation on the device.
1249  *
1250  *   -EBUSY: action cannot be performed due to busy device resources, may
1251  *   succeed if the affected queues or even the entire port are in a stopped
1252  *   state (see rte_eth_dev_rx_queue_stop() and rte_eth_dev_stop()).
1253  */
1254 int
1255 rte_flow_validate(uint16_t port_id,
1256                   const struct rte_flow_attr *attr,
1257                   const struct rte_flow_item pattern[],
1258                   const struct rte_flow_action actions[],
1259                   struct rte_flow_error *error);
1260
1261 /**
1262  * Create a flow rule on a given port.
1263  *
1264  * @param port_id
1265  *   Port identifier of Ethernet device.
1266  * @param[in] attr
1267  *   Flow rule attributes.
1268  * @param[in] pattern
1269  *   Pattern specification (list terminated by the END pattern item).
1270  * @param[in] actions
1271  *   Associated actions (list terminated by the END action).
1272  * @param[out] error
1273  *   Perform verbose error reporting if not NULL. PMDs initialize this
1274  *   structure in case of error only.
1275  *
1276  * @return
1277  *   A valid handle in case of success, NULL otherwise and rte_errno is set
1278  *   to the positive version of one of the error codes defined for
1279  *   rte_flow_validate().
1280  */
1281 struct rte_flow *
1282 rte_flow_create(uint16_t port_id,
1283                 const struct rte_flow_attr *attr,
1284                 const struct rte_flow_item pattern[],
1285                 const struct rte_flow_action actions[],
1286                 struct rte_flow_error *error);
1287
1288 /**
1289  * Destroy a flow rule on a given port.
1290  *
1291  * Failure to destroy a flow rule handle may occur when other flow rules
1292  * depend on it, and destroying it would result in an inconsistent state.
1293  *
1294  * This function is only guaranteed to succeed if handles are destroyed in
1295  * reverse order of their creation.
1296  *
1297  * @param port_id
1298  *   Port identifier of Ethernet device.
1299  * @param flow
1300  *   Flow rule handle to destroy.
1301  * @param[out] error
1302  *   Perform verbose error reporting if not NULL. PMDs initialize this
1303  *   structure in case of error only.
1304  *
1305  * @return
1306  *   0 on success, a negative errno value otherwise and rte_errno is set.
1307  */
1308 int
1309 rte_flow_destroy(uint16_t port_id,
1310                  struct rte_flow *flow,
1311                  struct rte_flow_error *error);
1312
1313 /**
1314  * Destroy all flow rules associated with a port.
1315  *
1316  * In the unlikely event of failure, handles are still considered destroyed
1317  * and no longer valid but the port must be assumed to be in an inconsistent
1318  * state.
1319  *
1320  * @param port_id
1321  *   Port identifier of Ethernet device.
1322  * @param[out] error
1323  *   Perform verbose error reporting if not NULL. PMDs initialize this
1324  *   structure in case of error only.
1325  *
1326  * @return
1327  *   0 on success, a negative errno value otherwise and rte_errno is set.
1328  */
1329 int
1330 rte_flow_flush(uint16_t port_id,
1331                struct rte_flow_error *error);
1332
1333 /**
1334  * Query an existing flow rule.
1335  *
1336  * This function allows retrieving flow-specific data such as counters.
1337  * Data is gathered by special actions which must be present in the flow
1338  * rule definition.
1339  *
1340  * \see RTE_FLOW_ACTION_TYPE_COUNT
1341  *
1342  * @param port_id
1343  *   Port identifier of Ethernet device.
1344  * @param flow
1345  *   Flow rule handle to query.
1346  * @param action
1347  *   Action type to query.
1348  * @param[in, out] data
1349  *   Pointer to storage for the associated query data type.
1350  * @param[out] error
1351  *   Perform verbose error reporting if not NULL. PMDs initialize this
1352  *   structure in case of error only.
1353  *
1354  * @return
1355  *   0 on success, a negative errno value otherwise and rte_errno is set.
1356  */
1357 int
1358 rte_flow_query(uint16_t port_id,
1359                struct rte_flow *flow,
1360                enum rte_flow_action_type action,
1361                void *data,
1362                struct rte_flow_error *error);
1363
1364 /**
1365  * Restrict ingress traffic to the defined flow rules.
1366  *
1367  * Isolated mode guarantees that all ingress traffic comes from defined flow
1368  * rules only (current and future).
1369  *
1370  * Besides making ingress more deterministic, it allows PMDs to safely reuse
1371  * resources otherwise assigned to handle the remaining traffic, such as
1372  * global RSS configuration settings, VLAN filters, MAC address entries,
1373  * legacy filter API rules and so on in order to expand the set of possible
1374  * flow rule types.
1375  *
1376  * Calling this function as soon as possible after device initialization,
1377  * ideally before the first call to rte_eth_dev_configure(), is recommended
1378  * to avoid possible failures due to conflicting settings.
1379  *
1380  * Once effective, leaving isolated mode may not be possible depending on
1381  * PMD implementation.
1382  *
1383  * Additionally, the following functionality has no effect on the underlying
1384  * port and may return errors such as ENOTSUP ("not supported"):
1385  *
1386  * - Toggling promiscuous mode.
1387  * - Toggling allmulticast mode.
1388  * - Configuring MAC addresses.
1389  * - Configuring multicast addresses.
1390  * - Configuring VLAN filters.
1391  * - Configuring Rx filters through the legacy API (e.g. FDIR).
1392  * - Configuring global RSS settings.
1393  *
1394  * @param port_id
1395  *   Port identifier of Ethernet device.
1396  * @param set
1397  *   Nonzero to enter isolated mode, attempt to leave it otherwise.
1398  * @param[out] error
1399  *   Perform verbose error reporting if not NULL. PMDs initialize this
1400  *   structure in case of error only.
1401  *
1402  * @return
1403  *   0 on success, a negative errno value otherwise and rte_errno is set.
1404  */
1405 int
1406 rte_flow_isolate(uint16_t port_id, int set, struct rte_flow_error *error);
1407
1408 /**
1409  * Initialize flow error structure.
1410  *
1411  * @param[out] error
1412  *   Pointer to flow error structure (may be NULL).
1413  * @param code
1414  *   Related error code (rte_errno).
1415  * @param type
1416  *   Cause field and error types.
1417  * @param cause
1418  *   Object responsible for the error.
1419  * @param message
1420  *   Human-readable error message.
1421  *
1422  * @return
1423  *   Negative error code (errno value) and rte_errno is set.
1424  */
1425 int
1426 rte_flow_error_set(struct rte_flow_error *error,
1427                    int code,
1428                    enum rte_flow_error_type type,
1429                    const void *cause,
1430                    const char *message);
1431
1432 /**
1433  * Generic flow representation.
1434  *
1435  * This form is sufficient to describe an rte_flow independently from any
1436  * PMD implementation and allows for replayability and identification.
1437  */
1438 struct rte_flow_desc {
1439         size_t size; /**< Allocated space including data[]. */
1440         struct rte_flow_attr attr; /**< Attributes. */
1441         struct rte_flow_item *items; /**< Items. */
1442         struct rte_flow_action *actions; /**< Actions. */
1443         uint8_t data[]; /**< Storage for items/actions. */
1444 };
1445
1446 /**
1447  * Copy an rte_flow rule description.
1448  *
1449  * @param[in] fd
1450  *   Flow rule description.
1451  * @param[in] len
1452  *   Total size of allocated data for the flow description.
1453  * @param[in] attr
1454  *   Flow rule attributes.
1455  * @param[in] items
1456  *   Pattern specification (list terminated by the END pattern item).
1457  * @param[in] actions
1458  *   Associated actions (list terminated by the END action).
1459  *
1460  * @return
1461  *   If len is greater or equal to the size of the flow, the total size of the
1462  *   flow description and its data.
1463  *   If len is lower than the size of the flow, the number of bytes that would
1464  *   have been written to desc had it been sufficient. Nothing is written.
1465  */
1466 size_t
1467 rte_flow_copy(struct rte_flow_desc *fd, size_t len,
1468               const struct rte_flow_attr *attr,
1469               const struct rte_flow_item *items,
1470               const struct rte_flow_action *actions);
1471
1472 #ifdef __cplusplus
1473 }
1474 #endif
1475
1476 #endif /* RTE_FLOW_H_ */