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