X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=lib%2Flibrte_ether%2Frte_flow.h;h=09a21e5315c9d228211b93ee0a93e0fe20763cfe;hb=fc6bbb3f28f2336ecae64d4c2732c09c05a5ab4a;hp=44ae19d3b2dacce52cbcc991887cd1711e8d477c;hpb=06dbc8de059d7ab491a52a83842d758d4012a338;p=dpdk.git diff --git a/lib/librte_ether/rte_flow.h b/lib/librte_ether/rte_flow.h index 44ae19d3b2..09a21e5315 100644 --- a/lib/librte_ether/rte_flow.h +++ b/lib/librte_ether/rte_flow.h @@ -14,10 +14,12 @@ * associated actions in hardware through flow rules. */ +#include #include #include #include +#include #include #include #include @@ -70,7 +72,26 @@ struct rte_flow_attr { uint32_t priority; /**< Priority level within group. */ uint32_t ingress:1; /**< Rule applies to ingress traffic. */ uint32_t egress:1; /**< Rule applies to egress traffic. */ - uint32_t reserved:30; /**< Reserved, must be zero. */ + /** + * Instead of simply matching the properties of traffic as it would + * appear on a given DPDK port ID, enabling this attribute transfers + * a flow rule to the lowest possible level of any device endpoints + * found in the pattern. + * + * When supported, this effectively enables an application to + * re-route traffic not necessarily intended for it (e.g. coming + * from or addressed to different physical ports, VFs or + * applications) at the device level. + * + * It complements the behavior of some pattern items such as + * RTE_FLOW_ITEM_TYPE_PHY_PORT and is meaningless without them. + * + * When transferring flow rules, ingress and egress attributes keep + * their original meaning, as if processing traffic emitted or + * received by the application. + */ + uint32_t transfer:1; + uint32_t reserved:29; /**< Reserved, must be zero. */ }; /** @@ -78,15 +99,13 @@ struct rte_flow_attr { * * Pattern items fall in two categories: * - * - Matching protocol headers and packet data (ANY, RAW, ETH, VLAN, IPV4, - * IPV6, ICMP, UDP, TCP, SCTP, VXLAN and so on), usually associated with a + * - Matching protocol headers and packet data, usually associated with a * specification structure. These must be stacked in the same order as the - * protocol layers to match, starting from the lowest. + * protocol layers to match inside packets, starting from the lowest. * - * - Matching meta-data or affecting pattern processing (END, VOID, INVERT, - * PF, VF, PORT and so on), often without a specification structure. Since - * they do not match packet contents, these can be specified anywhere - * within item lists without affecting others. + * - Matching meta-data or affecting pattern processing, often without a + * specification structure. Since they do not match packet contents, their + * position in the list is usually not relevant. * * See the description of individual types for more information. Those * marked with [META] fall into the second category. @@ -133,13 +152,8 @@ enum rte_flow_item_type { /** * [META] * - * Matches packets addressed to the physical function of the device. - * - * If the underlying device function differs from the one that would - * normally receive the matched traffic, specifying this item - * prevents it from reaching that device unless the flow rule - * contains a PF action. Packets are not duplicated between device - * instances by default. + * Matches traffic originating from (ingress) or going to (egress) + * the physical function of the current device. * * No associated specification structure. */ @@ -148,13 +162,8 @@ enum rte_flow_item_type { /** * [META] * - * Matches packets addressed to a virtual function ID of the device. - * - * If the underlying device function differs from the one that would - * normally receive the matched traffic, specifying this item - * prevents it from reaching that device unless the flow rule - * contains a VF action. Packets are not duplicated between device - * instances by default. + * Matches traffic originating from (ingress) or going to (egress) a + * given virtual function of the current device. * * See struct rte_flow_item_vf. */ @@ -163,17 +172,22 @@ enum rte_flow_item_type { /** * [META] * - * Matches packets coming from the specified physical port of the - * underlying device. + * Matches traffic originating from (ingress) or going to (egress) a + * physical port of the underlying device. * - * The first PORT item overrides the physical port normally - * associated with the specified DPDK input port (port_id). This - * item can be provided several times to match additional physical - * ports. + * See struct rte_flow_item_phy_port. + */ + RTE_FLOW_ITEM_TYPE_PHY_PORT, + + /** + * [META] + * + * Matches traffic originating from (ingress) or going to (egress) a + * given DPDK port ID. * - * See struct rte_flow_item_port. + * See struct rte_flow_item_port_id. */ - RTE_FLOW_ITEM_TYPE_PORT, + RTE_FLOW_ITEM_TYPE_PORT_ID, /** * Matches a byte string of a given length at a given offset. @@ -352,15 +366,15 @@ static const struct rte_flow_item_any rte_flow_item_any_mask = { /** * RTE_FLOW_ITEM_TYPE_VF * - * Matches packets addressed to a virtual function ID of the device. + * Matches traffic originating from (ingress) or going to (egress) a given + * virtual function of the current device. * - * If the underlying device function differs from the one that would - * normally receive the matched traffic, specifying this item prevents it - * from reaching that device unless the flow rule contains a VF - * action. Packets are not duplicated between device instances by default. + * If supported, should work even if the virtual function is not managed by + * the application and thus not associated with a DPDK port ID. + * + * Note this pattern item does not match VF representors traffic which, as + * separate entities, should be addressed through their own DPDK port IDs. * - * - Likely to return an error or never match any traffic if this causes a - * VF device to match traffic addressed to a different VF. * - Can be specified multiple times to match traffic addressed to several * VF IDs. * - Can be combined with a PF item to match both PF and VF traffic. @@ -368,7 +382,7 @@ static const struct rte_flow_item_any rte_flow_item_any_mask = { * A zeroed mask can be used to match any VF ID. */ struct rte_flow_item_vf { - uint32_t id; /**< Destination VF ID. */ + uint32_t id; /**< VF ID. */ }; /** Default mask for RTE_FLOW_ITEM_TYPE_VF. */ @@ -379,13 +393,13 @@ static const struct rte_flow_item_vf rte_flow_item_vf_mask = { #endif /** - * RTE_FLOW_ITEM_TYPE_PORT + * RTE_FLOW_ITEM_TYPE_PHY_PORT * - * Matches packets coming from the specified physical port of the underlying - * device. + * Matches traffic originating from (ingress) or going to (egress) a + * physical port of the underlying device. * - * The first PORT item overrides the physical port normally associated with - * the specified DPDK input port (port_id). This item can be provided + * The first PHY_PORT item overrides the physical port normally associated + * with the specified DPDK input port (port_id). This item can be provided * several times to match additional physical ports. * * Note that physical ports are not necessarily tied to DPDK input ports @@ -398,17 +412,43 @@ static const struct rte_flow_item_vf rte_flow_item_vf_mask = { * * A zeroed mask can be used to match any port index. */ -struct rte_flow_item_port { +struct rte_flow_item_phy_port { uint32_t index; /**< Physical port index. */ }; -/** Default mask for RTE_FLOW_ITEM_TYPE_PORT. */ +/** Default mask for RTE_FLOW_ITEM_TYPE_PHY_PORT. */ #ifndef __cplusplus -static const struct rte_flow_item_port rte_flow_item_port_mask = { +static const struct rte_flow_item_phy_port rte_flow_item_phy_port_mask = { .index = 0x00000000, }; #endif +/** + * RTE_FLOW_ITEM_TYPE_PORT_ID + * + * Matches traffic originating from (ingress) or going to (egress) a given + * DPDK port ID. + * + * Normally only supported if the port ID in question is known by the + * underlying PMD and related to the device the flow rule is created + * against. + * + * This must not be confused with @p PHY_PORT which refers to the physical + * port of a device, whereas @p PORT_ID refers to a struct rte_eth_dev + * object on the application side (also known as "port representor" + * depending on the kind of underlying device). + */ +struct rte_flow_item_port_id { + uint32_t id; /**< DPDK port ID. */ +}; + +/** Default mask for RTE_FLOW_ITEM_TYPE_PORT_ID. */ +#ifndef __cplusplus +static const struct rte_flow_item_port_id rte_flow_item_port_id_mask = { + .id = 0xffffffff, +}; +#endif + /** * RTE_FLOW_ITEM_TYPE_RAW * @@ -434,7 +474,7 @@ struct rte_flow_item_raw { int32_t offset; /**< Absolute or relative offset for pattern. */ uint16_t limit; /**< Search area limit for start of pattern. */ uint16_t length; /**< Pattern length. */ - uint8_t pattern[]; /**< Byte string to look for. */ + const uint8_t *pattern; /**< Byte string to look for. */ }; /** Default mask for RTE_FLOW_ITEM_TYPE_RAW. */ @@ -446,6 +486,7 @@ static const struct rte_flow_item_raw rte_flow_item_raw_mask = { .offset = 0xffffffff, .limit = 0xffff, .length = 0xffff, + .pattern = NULL, }; #endif @@ -453,11 +494,17 @@ static const struct rte_flow_item_raw rte_flow_item_raw_mask = { * RTE_FLOW_ITEM_TYPE_ETH * * Matches an Ethernet header. + * + * The @p type field either stands for "EtherType" or "TPID" when followed + * by so-called layer 2.5 pattern items such as RTE_FLOW_ITEM_TYPE_VLAN. In + * the latter case, @p type refers to that of the outer header, with the + * inner EtherType/TPID provided by the subsequent pattern item. This is the + * same order as on the wire. */ struct rte_flow_item_eth { struct ether_addr dst; /**< Destination MAC. */ struct ether_addr src; /**< Source MAC. */ - rte_be16_t type; /**< EtherType. */ + rte_be16_t type; /**< EtherType or TPID. */ }; /** Default mask for RTE_FLOW_ITEM_TYPE_ETH. */ @@ -474,19 +521,20 @@ static const struct rte_flow_item_eth rte_flow_item_eth_mask = { * * Matches an 802.1Q/ad VLAN tag. * - * This type normally follows either RTE_FLOW_ITEM_TYPE_ETH or - * RTE_FLOW_ITEM_TYPE_VLAN. + * The corresponding standard outer EtherType (TPID) values are + * ETHER_TYPE_VLAN or ETHER_TYPE_QINQ. It can be overridden by the preceding + * pattern item. */ struct rte_flow_item_vlan { - rte_be16_t tpid; /**< Tag protocol identifier. */ rte_be16_t tci; /**< Tag control information. */ + rte_be16_t inner_type; /**< Inner EtherType or TPID. */ }; /** Default mask for RTE_FLOW_ITEM_TYPE_VLAN. */ #ifndef __cplusplus static const struct rte_flow_item_vlan rte_flow_item_vlan_mask = { - .tpid = RTE_BE16(0x0000), - .tci = RTE_BE16(0xffff), + .tci = RTE_BE16(0x0fff), + .inner_type = RTE_BE16(0x0000), }; #endif @@ -635,9 +683,11 @@ static const struct rte_flow_item_vxlan rte_flow_item_vxlan_mask = { * RTE_FLOW_ITEM_TYPE_E_TAG. * * Matches a E-tag header. + * + * The corresponding standard outer EtherType (TPID) value is + * ETHER_TYPE_ETAG. It can be overridden by the preceding pattern item. */ struct rte_flow_item_e_tag { - rte_be16_t tpid; /**< Tag protocol identifier (0x893F). */ /** * E-Tag control information (E-TCI). * E-PCP (3b), E-DEI (1b), ingress E-CID base (12b). @@ -647,6 +697,7 @@ struct rte_flow_item_e_tag { rte_be16_t rsvd_grp_ecid_b; uint8_t in_ecid_e; /**< Ingress E-CID ext. */ uint8_t ecid_e; /**< E-CID ext. */ + rte_be16_t inner_type; /**< Inner EtherType or TPID. */ }; /** Default mask for RTE_FLOW_ITEM_TYPE_E_TAG. */ @@ -861,33 +912,28 @@ struct rte_flow_item { * * Each possible action is represented by a type. Some have associated * configuration structures. Several actions combined in a list can be - * affected to a flow rule. That list is not ordered. + * assigned to a flow rule and are performed in order. * * They fall in three categories: * - * - Terminating actions (such as QUEUE, DROP, RSS, PF, VF) that prevent - * processing matched packets by subsequent flow rules, unless overridden - * with PASSTHRU. - * - * - Non terminating actions (PASSTHRU, DUP) that leave matched packets up - * for additional processing by subsequent flow rules. + * - Actions that modify the fate of matching traffic, for instance by + * dropping or assigning it a specific destination. * - * - Other non terminating meta actions that do not affect the fate of - * packets (END, VOID, MARK, FLAG, COUNT). + * - Actions that modify matching traffic contents or its properties. This + * includes adding/removing encapsulation, encryption, compression and + * marks. * - * When several actions are combined in a flow rule, they should all have - * different types (e.g. dropping a packet twice is not possible). + * - Actions related to the flow rule itself, such as updating counters or + * making it non-terminating. * - * Only the last action of a given type is taken into account. PMDs still - * perform error checking on the entire list. + * Flow rules being terminating by default, not specifying any action of the + * fate kind results in undefined behavior. This applies to both ingress and + * egress. * - * Note that PASSTHRU is the only action able to override a terminating - * rule. + * PASSTHRU, when supported, makes a flow rule non-terminating. */ enum rte_flow_action_type { /** - * [META] - * * End marker for action lists. Prevents further processing of * actions, thereby ending the list. * @@ -896,8 +942,6 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_END, /** - * [META] - * * Used as a placeholder for convenience. It is ignored and simply * discarded by PMDs. * @@ -906,18 +950,14 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_VOID, /** - * Leaves packets up for additional processing by subsequent flow - * rules. This is the default when a rule does not contain a - * terminating action, but can be specified to force a rule to - * become non-terminating. + * Leaves traffic up for additional processing by subsequent flow + * rules; makes a flow rule non-terminating. * * No associated configuration structure. */ RTE_FLOW_ACTION_TYPE_PASSTHRU, /** - * [META] - * * Attaches an integer value to packets and sets PKT_RX_FDIR and * PKT_RX_FDIR_ID mbuf flags. * @@ -926,8 +966,6 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_MARK, /** - * [META] - * * Flags packets. Similar to MARK without a specific value; only * sets the PKT_RX_FDIR mbuf flag. * @@ -952,9 +990,7 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_DROP, /** - * [META] - * - * Enables counters for this rule. + * Enables counters for this flow rule. * * These counters can be retrieved and reset through rte_flow_query(), * see struct rte_flow_query_count. @@ -963,16 +999,6 @@ enum rte_flow_action_type { */ RTE_FLOW_ACTION_TYPE_COUNT, - /** - * Duplicates packets to a given queue index. - * - * This is normally combined with QUEUE, however when used alone, it - * is actually similar to QUEUE + PASSTHRU. - * - * See struct rte_flow_action_dup. - */ - RTE_FLOW_ACTION_TYPE_DUP, - /** * Similar to QUEUE, except RSS is additionally performed on packets * to spread them among several queues according to the provided @@ -983,21 +1009,36 @@ enum rte_flow_action_type { RTE_FLOW_ACTION_TYPE_RSS, /** - * Redirects packets to the physical function (PF) of the current - * device. + * Directs matching traffic to the physical function (PF) of the + * current device. * * No associated configuration structure. */ RTE_FLOW_ACTION_TYPE_PF, /** - * Redirects packets to the virtual function (VF) of the current - * device with the specified ID. + * Directs matching traffic to a given virtual function of the + * current device. * * See struct rte_flow_action_vf. */ RTE_FLOW_ACTION_TYPE_VF, + /** + * Directs packets to a given physical port index of the underlying + * device. + * + * See struct rte_flow_action_phy_port. + */ + RTE_FLOW_ACTION_TYPE_PHY_PORT, + + /** + * Directs matching traffic to a given DPDK port ID. + * + * See struct rte_flow_action_port_id. + */ + RTE_FLOW_ACTION_TYPE_PORT_ID, + /** * Traffic metering and policing (MTR). * @@ -1033,8 +1074,6 @@ struct rte_flow_action_mark { * RTE_FLOW_ACTION_TYPE_QUEUE * * Assign packets to a given queue index. - * - * Terminating by default. */ struct rte_flow_action_queue { uint16_t index; /**< Queue index to use. */ @@ -1054,55 +1093,100 @@ struct rte_flow_query_count { uint64_t bytes; /**< Number of bytes through this rule [out]. */ }; -/** - * RTE_FLOW_ACTION_TYPE_DUP - * - * Duplicates packets to a given queue index. - * - * This is normally combined with QUEUE, however when used alone, it is - * actually similar to QUEUE + PASSTHRU. - * - * Non-terminating by default. - */ -struct rte_flow_action_dup { - uint16_t index; /**< Queue index to duplicate packets to. */ -}; - /** * RTE_FLOW_ACTION_TYPE_RSS * * Similar to QUEUE, except RSS is additionally performed on packets to * spread them among several queues according to the provided parameters. * + * Unlike global RSS settings used by other DPDK APIs, unsetting the + * @p types field does not disable RSS in a flow rule. Doing so instead + * requests safe unspecified "best-effort" settings from the underlying PMD, + * which depending on the flow rule, may result in anything ranging from + * empty (single queue) to all-inclusive RSS. + * * Note: RSS hash result is stored in the hash.rss mbuf field which overlaps * hash.fdir.lo. Since the MARK action sets the hash.fdir.hi field only, * both can be requested simultaneously. - * - * Terminating by default. */ struct rte_flow_action_rss { - const struct rte_eth_rss_conf *rss_conf; /**< RSS parameters. */ - uint16_t num; /**< Number of entries in queue[]. */ - uint16_t queue[]; /**< Queues indices to use. */ + enum rte_eth_hash_function func; /**< RSS hash function to apply. */ + /** + * Packet encapsulation level RSS hash @p types apply to. + * + * - @p 0 requests the default behavior. Depending on the packet + * type, it can mean outermost, innermost, anything in between or + * even no RSS. + * + * It basically stands for the innermost encapsulation level RSS + * can be performed on according to PMD and device capabilities. + * + * - @p 1 requests RSS to be performed on the outermost packet + * encapsulation level. + * + * - @p 2 and subsequent values request RSS to be performed on the + * specified inner packet encapsulation level, from outermost to + * innermost (lower to higher values). + * + * Values other than @p 0 are not necessarily supported. + * + * Requesting a specific RSS level on unrecognized traffic results + * in undefined behavior. For predictable results, it is recommended + * to make the flow rule pattern match packet headers up to the + * requested encapsulation level so that only matching traffic goes + * through. + */ + uint32_t level; + uint64_t types; /**< Specific RSS hash types (see ETH_RSS_*). */ + uint32_t key_len; /**< Hash key length in bytes. */ + uint32_t queue_num; /**< Number of entries in @p queue. */ + const uint8_t *key; /**< Hash key. */ + const uint16_t *queue; /**< Queue indices to use. */ }; /** * RTE_FLOW_ACTION_TYPE_VF * - * Redirects packets to a virtual function (VF) of the current device. + * Directs matching traffic to a given virtual function of the current + * device. * * Packets matched by a VF pattern item can be redirected to their original * VF ID instead of the specified one. This parameter may not be available * and is not guaranteed to work properly if the VF part is matched by a * prior flow rule or if packets are not addressed to a VF in the first * place. - * - * Terminating by default. */ struct rte_flow_action_vf { uint32_t original:1; /**< Use original VF ID if possible. */ uint32_t reserved:31; /**< Reserved, must be zero. */ - uint32_t id; /**< VF ID to redirect packets to. */ + uint32_t id; /**< VF ID. */ +}; + +/** + * RTE_FLOW_ACTION_TYPE_PHY_PORT + * + * Directs packets to a given physical port index of the underlying + * device. + * + * @see RTE_FLOW_ITEM_TYPE_PHY_PORT + */ +struct rte_flow_action_phy_port { + uint32_t original:1; /**< Use original port index if possible. */ + uint32_t reserved:31; /**< Reserved, must be zero. */ + uint32_t index; /**< Physical port index. */ +}; + +/** + * RTE_FLOW_ACTION_TYPE_PORT_ID + * + * Directs matching traffic to a given DPDK port ID. + * + * @see RTE_FLOW_ITEM_TYPE_PORT_ID + */ +struct rte_flow_action_port_id { + uint32_t original:1; /**< Use original DPDK port ID if possible. */ + uint32_t reserved:31; /**< Reserved, must be zero. */ + uint32_t id; /**< DPDK port ID. */ }; /** @@ -1112,8 +1196,6 @@ struct rte_flow_action_vf { * * Packets matched by items of this type can be either dropped or passed to the * next item with their color set by the MTR object. - * - * Non-terminating by default. */ struct rte_flow_action_meter { uint32_t mtr_id; /**< MTR object ID created with rte_mtr_create(). */ @@ -1143,8 +1225,6 @@ struct rte_flow_action_meter { * direction. * * Multiple flows can be configured to use the same security session. - * - * Non-terminating by default. */ struct rte_flow_action_security { void *security_session; /**< Pointer to security session structure. */ @@ -1184,10 +1264,15 @@ enum rte_flow_error_type { RTE_FLOW_ERROR_TYPE_ATTR_PRIORITY, /**< Priority field. */ RTE_FLOW_ERROR_TYPE_ATTR_INGRESS, /**< Ingress field. */ RTE_FLOW_ERROR_TYPE_ATTR_EGRESS, /**< Egress field. */ + RTE_FLOW_ERROR_TYPE_ATTR_TRANSFER, /**< Transfer field. */ RTE_FLOW_ERROR_TYPE_ATTR, /**< Attributes structure. */ RTE_FLOW_ERROR_TYPE_ITEM_NUM, /**< Pattern length. */ + RTE_FLOW_ERROR_TYPE_ITEM_SPEC, /**< Item specification. */ + RTE_FLOW_ERROR_TYPE_ITEM_LAST, /**< Item specification range. */ + RTE_FLOW_ERROR_TYPE_ITEM_MASK, /**< Item specification mask. */ RTE_FLOW_ERROR_TYPE_ITEM, /**< Specific pattern item. */ RTE_FLOW_ERROR_TYPE_ACTION_NUM, /**< Number of actions. */ + RTE_FLOW_ERROR_TYPE_ACTION_CONF, /**< Action configuration. */ RTE_FLOW_ERROR_TYPE_ACTION, /**< Specific action. */ };