X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fprog_guide%2Frte_flow.rst;h=6c8162ff4afdb078ebc9ecc55aa6b0c85844de5a;hb=e0e6a7f2154e;hp=5b23778c761a0cb4c2213548409e76f9dd06af70;hpb=e05419b3f05615c2b48169bc27049cda3ae584c6;p=dpdk.git diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index 5b23778c76..6c8162ff4a 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -1,32 +1,6 @@ -.. BSD LICENSE +.. SPDX-License-Identifier: BSD-3-Clause Copyright 2016 6WIND S.A. - Copyright 2016 Mellanox. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of 6WIND S.A. nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + Copyright 2016 Mellanox Technologies, Ltd .. _Generic_flow_API: @@ -1217,6 +1191,27 @@ 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. + +.. _table_rte_flow_item_meta: + +.. table:: META + + +----------+----------+-----------------------+ + | Field | Subfield | Value | + +==========+==========+=======================+ + | ``spec`` | ``data`` | 32 bit metadata value | + +----------+----------------------------------+ + | ``last`` | ``data`` | ignored | + +----------+----------+-----------------------+ + | ``mask`` | ``data`` | ignored | + +----------+----------+-----------------------+ + Actions ~~~~~~~ @@ -1277,17 +1272,19 @@ Actions are performed in list order: .. table:: Mark, count then redirect - +-------+--------+-----------+-------+ - | Index | Action | Field | Value | - +=======+========+===========+=======+ - | 0 | MARK | ``mark`` | 0x2a | - +-------+--------+-----------+-------+ - | 1 | COUNT | - +-------+--------+-----------+-------+ - | 2 | QUEUE | ``queue`` | 10 | - +-------+--------+-----------+-------+ - | 3 | END | - +-------+----------------------------+ + +-------+--------+------------+-------+ + | Index | Action | Field | Value | + +=======+========+============+=======+ + | 0 | MARK | ``mark`` | 0x2a | + +-------+--------+------------+-------+ + | 1 | COUNT | ``shared`` | 0 | + | | +------------+-------+ + | | | ``id`` | 0 | + +-------+--------+------------+-------+ + | 2 | QUEUE | ``queue`` | 10 | + +-------+--------+------------+-------+ + | 3 | END | + +-------+-----------------------------+ | @@ -1516,23 +1513,36 @@ Drop packets. Action: ``COUNT`` ^^^^^^^^^^^^^^^^^ -Enables counters for this rule. +Adds a counter action to a matched flow. + +If more than one count action is specified in a single flow rule, then each +action must specify a unique id. -These counters can be retrieved and reset through ``rte_flow_query()``, see +Counters can be retrieved and reset through ``rte_flow_query()``, see ``struct rte_flow_query_count``. -- Counters can be retrieved with ``rte_flow_query()``. -- No configurable properties. +The shared flag indicates whether the counter is unique to the flow rule the +action is specified with, or whether it is a shared counter. + +For a count action with the shared flag set, then then a global device +namespace is assumed for the counter id, so that any matched flow rules using +a count action with the same counter id on the same port will contribute to +that counter. + +For ports within the same switch domain then the counter id namespace extends +to all ports within that switch domain. .. _table_rte_flow_action_count: .. table:: COUNT - +---------------+ - | Field | - +===============+ - | no properties | - +---------------+ + +------------+---------------------+ + | Field | Value | + +============+=====================+ + | ``shared`` | shared counter flag | + +------------+---------------------+ + | ``id`` | counter id | + +------------+---------------------+ Query structure to retrieve and reset flow rule counters: @@ -2087,6 +2097,250 @@ 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 eincapsulation 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 behaviour 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 behaviour 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 + +.. _table_rte_flow_action_set_mac_src: + +.. table:: SET_MAC_SRC + + +--------------+---------------+ + | Field | Value | + +==============+===============+ + | ``mac_addr`` | MAC address | + +--------------+---------------+ + +Action: ``SET_MAC_DST`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Set source MAC address + +.. _table_rte_flow_action_set_mac_dst: + +.. table:: SET_MAC_DST + + +--------------+---------------+ + | Field | Value | + +==============+===============+ + | ``mac_addr`` | MAC address | + +--------------+---------------+ + Negative types ~~~~~~~~~~~~~~ @@ -2282,7 +2536,7 @@ definition. int rte_flow_query(uint16_t port_id, struct rte_flow *flow, - enum rte_flow_action_type action, + const struct rte_flow_action *action, void *data, struct rte_flow_error *error); @@ -2290,7 +2544,7 @@ Arguments: - ``port_id``: port identifier of Ethernet device. - ``flow``: flow rule handle to query. -- ``action``: action type to query. +- ``action``: action to query, this must match prototype from flow rule. - ``data``: pointer to storage for the associated query data type. - ``error``: perform verbose error reporting if not NULL. PMDs initialize this structure in case of error only. @@ -2430,6 +2684,26 @@ This function initializes ``error`` (if non-NULL) with the provided parameters and sets ``rte_errno`` to ``code``. A negative error ``code`` is then returned. +Object conversion +~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + int + rte_flow_conv(enum rte_flow_conv_op op, + void *dst, + size_t size, + const void *src, + struct rte_flow_error *error); + +Convert ``src`` to ``dst`` according to operation ``op``. Possible +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 -------