X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fguides%2Fprog_guide%2Frte_flow.rst;h=7521a1ec49c534456b69d2ebdc9e070fff278e6b;hb=346553db5bd1e2d0c25d017d590cd5225a704b22;hp=964cf9ceb12bf2b2fe66c8452da82231e54d13fd;hpb=063911ee1df4950bc6af387b89ee9fdb39aa0650;p=dpdk.git diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index 964cf9ceb1..7521a1ec49 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -2,8 +2,6 @@ Copyright 2016 6WIND S.A. Copyright 2016 Mellanox Technologies, Ltd -.. _Generic_flow_API: - Generic flow API (rte_flow) =========================== @@ -240,29 +238,29 @@ Example of an item specification matching an Ethernet header: .. table:: Ethernet item - +----------+----------+--------------------+ - | Field | Subfield | Value | - +==========+==========+====================+ - | ``spec`` | ``src`` | ``00:01:02:03:04`` | - | +----------+--------------------+ - | | ``dst`` | ``00:2a:66:00:01`` | - | +----------+--------------------+ - | | ``type`` | ``0x22aa`` | - +----------+----------+--------------------+ - | ``last`` | unspecified | - +----------+----------+--------------------+ - | ``mask`` | ``src`` | ``00:ff:ff:ff:00`` | - | +----------+--------------------+ - | | ``dst`` | ``00:00:00:00:ff`` | - | +----------+--------------------+ - | | ``type`` | ``0x0000`` | - +----------+----------+--------------------+ + +----------+----------+-----------------------+ + | Field | Subfield | Value | + +==========+==========+=======================+ + | ``spec`` | ``src`` | ``00:00:01:02:03:04`` | + | +----------+-----------------------+ + | | ``dst`` | ``00:00:2a:66:00:01`` | + | +----------+-----------------------+ + | | ``type`` | ``0x22aa`` | + +----------+----------+-----------------------+ + | ``last`` | unspecified | + +----------+----------+-----------------------+ + | ``mask`` | ``src`` | ``00:00:ff:ff:ff:00`` | + | +----------+-----------------------+ + | | ``dst`` | ``00:00:00:00:00:ff`` | + | +----------+-----------------------+ + | | ``type`` | ``0x0000`` | + +----------+----------+-----------------------+ Non-masked bits stand for any value (shown as ``?`` below), Ethernet headers with the following properties are thus matched: -- ``src``: ``??:01:02:03:??`` -- ``dst``: ``??:??:??:??:01`` +- ``src``: ``??:??:01:02:03:??`` +- ``dst``: ``??:??:??:??:??:01`` - ``type``: ``0x????`` Matching pattern @@ -865,7 +863,7 @@ Item: ``VLAN`` Matches an 802.1Q/ad VLAN tag. The corresponding standard outer EtherType (TPID) values are -``ETHER_TYPE_VLAN`` or ``ETHER_TYPE_QINQ``. It can be overridden by the +``RTE_ETHER_TYPE_VLAN`` or ``RTE_ETHER_TYPE_QINQ``. It can be overridden by the preceding pattern item. - ``tci``: tag control information. @@ -942,7 +940,7 @@ Item: ``E_TAG`` Matches an IEEE 802.1BR E-Tag header. The corresponding standard outer EtherType (TPID) value is -``ETHER_TYPE_ETAG``. It can be overridden by the preceding pattern item. +``RTE_ETHER_TYPE_ETAG``. It can be overridden by the preceding pattern item. - ``epcp_edei_in_ecid_b``: E-Tag control information (E-TCI), E-PCP (3b), E-DEI (1b), ingress E-CID base (12b). @@ -982,6 +980,15 @@ Matches a GRE header. - ``protocol``: protocol type. - Default ``mask`` matches protocol only. +Item: ``GRE_KEY`` +^^^^^^^^^^^^^^^^^ + +Matches a GRE key field. +This should be preceded by item ``GRE``. + +- Value to be matched is a big-endian 32 bit integer. +- When this item present it implicitly match K bit in default mask as "1" + Item: ``FUZZY`` ^^^^^^^^^^^^^^^ @@ -1191,11 +1198,42 @@ Normally preceded by any of: - `Item: ICMP6_ND_NS`_ - `Item: ICMP6_ND_OPT`_ +Item: ``META`` +^^^^^^^^^^^^^^ + +Matches an application specific 32 bit metadata item. + +- Default ``mask`` matches the specified metadata value. + +Item: ``GTP_PSC`` +^^^^^^^^^^^^^^^^^ + +Matches a GTP PDU extension header with type 0x85. + +- ``pdu_type``: PDU type. +- ``qfi``: QoS flow identifier. +- Default ``mask`` matches QFI only. + +.. _table_rte_flow_item_meta: + +.. table:: META + + +----------+----------+---------------------------------------+ + | Field | Subfield | Value | + +==========+==========+=======================================+ + | ``spec`` | ``data`` | 32 bit metadata value | + +----------+--------------------------------------------------+ + | ``last`` | ``data`` | upper range value | + +----------+----------+---------------------------------------+ + | ``mask`` | ``data`` | bit-mask applies to "spec" and "last" | + +----------+----------+---------------------------------------+ + Actions ~~~~~~~ -Each possible action is represented by a type. Some have associated -configuration structures. Several actions combined in a list can be assigned +Each possible action is represented by a type. +An action can have an associated configuration object. +Several actions combined in a list can be assigned to a flow rule and are performed in order. They fall in three categories: @@ -2076,6 +2114,288 @@ RTE_FLOW_ERROR_TYPE_ACTION error should be returned. This action modifies the payload of matched flows. +Action: ``RAW_ENCAP`` +^^^^^^^^^^^^^^^^^^^^^ + +Adds outer header whose template is provided in its data buffer, +as defined in the ``rte_flow_action_raw_encap`` definition. + +This action modifies the payload of matched flows. The data supplied must +be a valid header, either holding layer 2 data in case of adding layer 2 after +decap layer 3 tunnel (for example MPLSoGRE) or complete tunnel definition +starting from layer 2 and moving to the tunnel item itself. When applied to +the original packet the resulting packet must be a valid packet. + +.. _table_rte_flow_action_raw_encap: + +.. table:: RAW_ENCAP + + +----------------+----------------------------------------+ + | Field | Value | + +================+========================================+ + | ``data`` | Encapsulation data | + +----------------+----------------------------------------+ + | ``preserve`` | Bit-mask of data to preserve on output | + +----------------+----------------------------------------+ + | ``size`` | Size of data and preserve | + +----------------+----------------------------------------+ + +Action: ``RAW_DECAP`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Remove outer header whose template is provided in its data buffer, +as defined in the ``rte_flow_action_raw_decap`` + +This action modifies the payload of matched flows. The data supplied must +be a valid header, either holding layer 2 data in case of removing layer 2 +before encapsulation of layer 3 tunnel (for example MPLSoGRE) or complete +tunnel definition starting from layer 2 and moving to the tunnel item itself. +When applied to the original packet the resulting packet must be a +valid packet. + +.. _table_rte_flow_action_raw_decap: + +.. table:: RAW_DECAP + + +----------------+----------------------------------------+ + | Field | Value | + +================+========================================+ + | ``data`` | Decapsulation data | + +----------------+----------------------------------------+ + | ``size`` | Size of data | + +----------------+----------------------------------------+ + +Action: ``SET_IPV4_SRC`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Set a new IPv4 source address in the outermost IPv4 header. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_IPV4 flow pattern item. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_ipv4_src: + +.. table:: SET_IPV4_SRC + + +-----------------------------------------+ + | Field | Value | + +===============+=========================+ + | ``ipv4_addr`` | new IPv4 source address | + +---------------+-------------------------+ + +Action: ``SET_IPV4_DST`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Set a new IPv4 destination address in the outermost IPv4 header. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_IPV4 flow pattern item. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_ipv4_dst: + +.. table:: SET_IPV4_DST + + +---------------+------------------------------+ + | Field | Value | + +===============+==============================+ + | ``ipv4_addr`` | new IPv4 destination address | + +---------------+------------------------------+ + +Action: ``SET_IPV6_SRC`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Set a new IPv6 source address in the outermost IPv6 header. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_IPV6 flow pattern item. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_ipv6_src: + +.. table:: SET_IPV6_SRC + + +---------------+-------------------------+ + | Field | Value | + +===============+=========================+ + | ``ipv6_addr`` | new IPv6 source address | + +---------------+-------------------------+ + +Action: ``SET_IPV6_DST`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Set a new IPv6 destination address in the outermost IPv6 header. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_IPV6 flow pattern item. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_ipv6_dst: + +.. table:: SET_IPV6_DST + + +---------------+------------------------------+ + | Field | Value | + +===============+==============================+ + | ``ipv6_addr`` | new IPv6 destination address | + +---------------+------------------------------+ + +Action: ``SET_TP_SRC`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set a new source port number in the outermost TCP/UDP header. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_TCP or RTE_FLOW_ITEM_TYPE_UDP +flow pattern item. Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_tp_src: + +.. table:: SET_TP_SRC + + +----------+-------------------------+ + | Field | Value | + +==========+=========================+ + | ``port`` | new TCP/UDP source port | + +---------------+--------------------+ + +Action: ``SET_TP_DST`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set a new destination port number in the outermost TCP/UDP header. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_TCP or RTE_FLOW_ITEM_TYPE_UDP +flow pattern item. Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_tp_dst: + +.. table:: SET_TP_DST + + +----------+------------------------------+ + | Field | Value | + +==========+==============================+ + | ``port`` | new TCP/UDP destination port | + +---------------+-------------------------+ + +Action: ``MAC_SWAP`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Swap the source and destination MAC addresses in the outermost Ethernet +header. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_ETH flow pattern item. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_mac_swap: + +.. table:: MAC_SWAP + + +---------------+ + | Field | + +===============+ + | no properties | + +---------------+ + +Action: ``DEC_TTL`` +^^^^^^^^^^^^^^^^^^^ + +Decrease TTL value. + +If there is no valid RTE_FLOW_ITEM_TYPE_IPV4 or RTE_FLOW_ITEM_TYPE_IPV6 +in pattern, Some PMDs will reject rule because behavior will be undefined. + +.. _table_rte_flow_action_dec_ttl: + +.. table:: DEC_TTL + + +---------------+ + | Field | + +===============+ + | no properties | + +---------------+ + +Action: ``SET_TTL`` +^^^^^^^^^^^^^^^^^^^ + +Assigns a new TTL value. + +If there is no valid RTE_FLOW_ITEM_TYPE_IPV4 or RTE_FLOW_ITEM_TYPE_IPV6 +in pattern, Some PMDs will reject rule because behavior will be undefined. + +.. _table_rte_flow_action_set_ttl: + +.. table:: SET_TTL + + +---------------+--------------------+ + | Field | Value | + +===============+====================+ + | ``ttl_value`` | new TTL value | + +---------------+--------------------+ + +Action: ``SET_MAC_SRC`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Set source MAC address. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_ETH flow pattern item. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_mac_src: + +.. table:: SET_MAC_SRC + + +--------------+---------------+ + | Field | Value | + +==============+===============+ + | ``mac_addr`` | MAC address | + +--------------+---------------+ + +Action: ``SET_MAC_DST`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Set destination MAC address. + +It must be used with a valid RTE_FLOW_ITEM_TYPE_ETH flow pattern item. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_mac_dst: + +.. table:: SET_MAC_DST + + +--------------+---------------+ + | Field | Value | + +==============+===============+ + | ``mac_addr`` | MAC address | + +--------------+---------------+ + +Action: ``INC_TCP_SEQ`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Increase sequence number in the outermost TCP header. +Value to increase TCP sequence number by is a big-endian 32 bit integer. + +Using this action on non-matching traffic will result in undefined behavior. + +Action: ``DEC_TCP_SEQ`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Decrease sequence number in the outermost TCP header. +Value to decrease TCP sequence number by is a big-endian 32 bit integer. + +Using this action on non-matching traffic will result in undefined behavior. + +Action: ``INC_TCP_ACK`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Increase acknowledgment number in the outermost TCP header. +Value to increase TCP acknowledgment number by is a big-endian 32 bit integer. + +Using this action on non-matching traffic will result in undefined behavior. + +Action: ``DEC_TCP_ACK`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Decrease acknowledgment number in the outermost TCP header. +Value to decrease TCP acknowledgment number by is a big-endian 32 bit integer. + +Using this action on non-matching traffic will result in undefined behavior. + Negative types ~~~~~~~~~~~~~~ @@ -2288,8 +2608,10 @@ Return values: - 0 on success, a negative errno value otherwise and ``rte_errno`` is set. -Isolated mode -------------- +.. _flow_isolated_mode: + +Flow isolated mode +------------------ The general expectation for ingress traffic is that flow rules process it first; the remaining unmatched or pass-through traffic usually ends up in a @@ -2437,6 +2759,7 @@ operations include: - Attributes, pattern item or action duplication. - Duplication of an entire pattern or list of actions. - Duplication of a complete flow rule description. +- Pattern item or action name retrieval. Caveats ------- @@ -2453,7 +2776,7 @@ Caveats - API operations are synchronous and blocking (``EAGAIN`` cannot be returned). -- There is no provision for reentrancy/multi-thread safety, although nothing +- There is no provision for re-entrancy/multi-thread safety, although nothing should prevent different devices from being configured at the same time. PMDs may protect their control path functions accordingly.