order to expose a single interface with an unambiguous behavior that is
common to all poll-mode drivers (PMDs).
-Several methods to migrate existing applications are described in `API
-migration`_.
-
Flow rule
---------
Each possible action is represented by a type. Some have associated
configuration structures. Several actions combined in a list can be assigned
-to a flow rule. That list is not ordered.
+to a flow rule and are performed in order.
They fall in three categories:
-- Terminating actions that prevent processing matched packets by subsequent
- flow rules, unless overridden with PASSTHRU.
+- Actions that modify the fate of matching traffic, for instance by dropping
+ or assigning it a specific destination.
-- Non-terminating actions that leave matched packets up for additional
- processing by subsequent flow rules.
+- Actions that modify matching traffic contents or its properties. This
+ includes adding/removing encapsulation, encryption, compression and marks.
-- Other non-terminating meta actions that do not affect the fate of packets.
+- Actions related to the flow rule itself, such as updating counters or
+ making it non-terminating.
-When several actions are combined in a flow rule, they should all have
-different types (e.g. dropping a packet twice is not possible).
+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.
-Only the last action of a given type is taken into account. PMDs still
-perform error checking on the entire list.
+PASSTHRU, when supported, makes a flow rule non-terminating.
Like matching patterns, action lists are terminated by END items.
-*Note that PASSTHRU is the only action able to override a terminating rule.*
-
Example of action that redirects packets to queue index 10:
.. _table_rte_flow_action_example:
| ``index`` | 10 |
+-----------+-------+
-Action lists examples, their order is not significant, applications must
-consider all actions to be performed simultaneously:
+Actions are performed in list order:
-.. _table_rte_flow_count_and_drop:
+.. _table_rte_flow_count_then_drop:
-.. table:: Count and drop
+.. table:: Count then drop
+-------+--------+
| Index | Action |
.. _table_rte_flow_mark_count_redirect:
-.. table:: Mark, count and redirect
+.. table:: Mark, count then redirect
+-------+--------+-----------+-------+
| Index | Action | Field | Value |
| 2 | END |
+-------+----------------------------+
-In the above example, considering both actions are performed simultaneously,
-the end result is that only QUEUE has any effect.
+In the above example, while DROP and QUEUE must be performed in order, both
+have to happen before reaching END. Only QUEUE has a visible effect.
+
+Note that such a list may be thought as ambiguous and rejected on that
+basis.
-.. _table_rte_flow_redirect_queue_3:
+.. _table_rte_flow_redirect_queue_5_3:
-.. table:: Redirect to queue 3
+.. table:: Redirect to queues 5 and 3
+-------+--------+-----------+-------+
| Index | Action | Field | Value |
| 3 | END |
+-------+----------------------------+
-As previously described, only the last action of a given type found in the
-list is taken into account. The above example also shows that VOID is
-ignored.
+As previously described, all actions must be taken into account. This
+effectively duplicates traffic to both queues. The above example also shows
+that VOID is ignored.
Action types
~~~~~~~~~~~~
Action: ``PASSTHRU``
^^^^^^^^^^^^^^^^^^^^
-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 configurable properties.
Assigns packets to a given queue index.
-- Terminating by default.
-
.. _table_rte_flow_action_queue:
.. table:: QUEUE
Drop packets.
- No configurable properties.
-- Terminating by default.
-- PASSTHRU overrides this action if both are specified.
.. _table_rte_flow_action_drop:
| ``bytes`` | out | number of bytes through this rule |
+---------------+-----+-----------------------------------+
-Action: ``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.
-
-.. _table_rte_flow_action_dup:
-
-.. table:: DUP
-
- +-----------+------------------------------------+
- | Field | Value |
- +===========+====================================+
- | ``index`` | queue index to duplicate packet to |
- +-----------+------------------------------------+
-
Action: ``RSS``
^^^^^^^^^^^^^^^
overlaps ``hash.fdir.lo``. Since `Action: MARK`_ sets the ``hash.fdir.hi``
field only, both can be requested simultaneously.
-- Terminating by default.
-
.. _table_rte_flow_action_rss:
.. table:: RSS
Redirects packets to the physical function (PF) of the current device.
- No configurable properties.
-- Terminating by default.
.. _table_rte_flow_action_pf:
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.
-
.. _table_rte_flow_action_vf:
.. table:: VF
the meter action. The MTR object can be further updated or queried using
the rte_mtr* API.
-- Non-terminating by default.
-
.. _table_rte_flow_action_meter:
.. table:: METER
Multiple flows can be configured to use the same security session.
-- Non-terminating by default.
-
.. _table_rte_flow_action_security:
.. table:: SECURITY
and tagging (`Action: MARK`_ or `Action: FLAG`_) may be implemented in
software as long as the target queue is used by a single rule.
-- A rule specifying both `Action: DUP`_ + `Action: QUEUE`_ may be translated
- to two hidden rules combining `Action: QUEUE`_ and `Action: PASSTHRU`_.
-
- When a single target queue is provided, `Action: RSS`_ can also be
implemented through `Action: QUEUE`_.
- Optional software fallback when PMDs are unable to handle requested flow
rules so applications do not have to implement their own.
-
-API migration
--------------
-
-Exhaustive list of deprecated filter types (normally prefixed with
-*RTE_ETH_FILTER_*) found in ``rte_eth_ctrl.h`` and methods to convert them
-to *rte_flow* rules.
-
-``MACVLAN`` to ``ETH`` → ``VF``, ``PF``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*MACVLAN* can be translated to a basic `Item: ETH`_ flow rule with a
-terminating `Action: VF`_ or `Action: PF`_.
-
-.. _table_rte_flow_migration_macvlan:
-
-.. table:: MACVLAN conversion
-
- +--------------------------+---------+
- | Pattern | Actions |
- +===+=====+==========+=====+=========+
- | 0 | ETH | ``spec`` | any | VF, |
- | | +----------+-----+ PF |
- | | | ``last`` | N/A | |
- | | +----------+-----+ |
- | | | ``mask`` | any | |
- +---+-----+----------+-----+---------+
- | 1 | END | END |
- +---+----------------------+---------+
-
-``ETHERTYPE`` to ``ETH`` → ``QUEUE``, ``DROP``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*ETHERTYPE* is basically an `Item: ETH`_ flow rule with a terminating
-`Action: QUEUE`_ or `Action: DROP`_.
-
-.. _table_rte_flow_migration_ethertype:
-
-.. table:: ETHERTYPE conversion
-
- +--------------------------+---------+
- | Pattern | Actions |
- +===+=====+==========+=====+=========+
- | 0 | ETH | ``spec`` | any | QUEUE, |
- | | +----------+-----+ DROP |
- | | | ``last`` | N/A | |
- | | +----------+-----+ |
- | | | ``mask`` | any | |
- +---+-----+----------+-----+---------+
- | 1 | END | END |
- +---+----------------------+---------+
-
-``FLEXIBLE`` to ``RAW`` → ``QUEUE``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*FLEXIBLE* can be translated to one `Item: RAW`_ pattern with a terminating
-`Action: QUEUE`_ and a defined priority level.
-
-.. _table_rte_flow_migration_flexible:
-
-.. table:: FLEXIBLE conversion
-
- +--------------------------+---------+
- | Pattern | Actions |
- +===+=====+==========+=====+=========+
- | 0 | RAW | ``spec`` | any | QUEUE |
- | | +----------+-----+ |
- | | | ``last`` | N/A | |
- | | +----------+-----+ |
- | | | ``mask`` | any | |
- +---+-----+----------+-----+---------+
- | 1 | END | END |
- +---+----------------------+---------+
-
-``SYN`` to ``TCP`` → ``QUEUE``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*SYN* is a `Item: TCP`_ rule with only the ``syn`` bit enabled and masked,
-and a terminating `Action: QUEUE`_.
-
-Priority level can be set to simulate the high priority bit.
-
-.. _table_rte_flow_migration_syn:
-
-.. table:: SYN conversion
-
- +-----------------------------------+---------+
- | Pattern | Actions |
- +===+======+==========+=============+=========+
- | 0 | ETH | ``spec`` | unset | QUEUE |
- | | +----------+-------------+ |
- | | | ``last`` | unset | |
- | | +----------+-------------+ |
- | | | ``mask`` | unset | |
- +---+------+----------+-------------+---------+
- | 1 | IPV4 | ``spec`` | unset | END |
- | | +----------+-------------+ |
- | | | ``mask`` | unset | |
- | | +----------+-------------+ |
- | | | ``mask`` | unset | |
- +---+------+----------+---------+---+ |
- | 2 | TCP | ``spec`` | ``syn`` | 1 | |
- | | +----------+---------+---+ |
- | | | ``mask`` | ``syn`` | 1 | |
- +---+------+----------+---------+---+ |
- | 3 | END | |
- +---+-------------------------------+---------+
-
-``NTUPLE`` to ``IPV4``, ``TCP``, ``UDP`` → ``QUEUE``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*NTUPLE* is similar to specifying an empty L2, `Item: IPV4`_ as L3 with
-`Item: TCP`_ or `Item: UDP`_ as L4 and a terminating `Action: QUEUE`_.
-
-A priority level can be specified as well.
-
-.. _table_rte_flow_migration_ntuple:
-
-.. table:: NTUPLE conversion
-
- +-----------------------------+---------+
- | Pattern | Actions |
- +===+======+==========+=======+=========+
- | 0 | ETH | ``spec`` | unset | QUEUE |
- | | +----------+-------+ |
- | | | ``last`` | unset | |
- | | +----------+-------+ |
- | | | ``mask`` | unset | |
- +---+------+----------+-------+---------+
- | 1 | IPV4 | ``spec`` | any | END |
- | | +----------+-------+ |
- | | | ``last`` | unset | |
- | | +----------+-------+ |
- | | | ``mask`` | any | |
- +---+------+----------+-------+ |
- | 2 | TCP, | ``spec`` | any | |
- | | UDP +----------+-------+ |
- | | | ``last`` | unset | |
- | | +----------+-------+ |
- | | | ``mask`` | any | |
- +---+------+----------+-------+ |
- | 3 | END | |
- +---+-------------------------+---------+
-
-``TUNNEL`` to ``ETH``, ``IPV4``, ``IPV6``, ``VXLAN`` (or other) → ``QUEUE``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*TUNNEL* matches common IPv4 and IPv6 L3/L4-based tunnel types.
-
-In the following table, `Item: ANY`_ is used to cover the optional L4.
-
-.. _table_rte_flow_migration_tunnel:
-
-.. table:: TUNNEL conversion
-
- +-------------------------------------------------------+---------+
- | Pattern | Actions |
- +===+==========================+==========+=============+=========+
- | 0 | ETH | ``spec`` | any | QUEUE |
- | | +----------+-------------+ |
- | | | ``last`` | unset | |
- | | +----------+-------------+ |
- | | | ``mask`` | any | |
- +---+--------------------------+----------+-------------+---------+
- | 1 | IPV4, IPV6 | ``spec`` | any | END |
- | | +----------+-------------+ |
- | | | ``last`` | unset | |
- | | +----------+-------------+ |
- | | | ``mask`` | any | |
- +---+--------------------------+----------+-------------+ |
- | 2 | ANY | ``spec`` | any | |
- | | +----------+-------------+ |
- | | | ``last`` | unset | |
- | | +----------+---------+---+ |
- | | | ``mask`` | ``num`` | 0 | |
- +---+--------------------------+----------+---------+---+ |
- | 3 | VXLAN, GENEVE, TEREDO, | ``spec`` | any | |
- | | NVGRE, GRE, ... +----------+-------------+ |
- | | | ``last`` | unset | |
- | | +----------+-------------+ |
- | | | ``mask`` | any | |
- +---+--------------------------+----------+-------------+ |
- | 4 | END | |
- +---+---------------------------------------------------+---------+
-
-``FDIR`` to most item types → ``QUEUE``, ``DROP``, ``PASSTHRU``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*FDIR* is more complex than any other type, there are several methods to
-emulate its functionality. It is summarized for the most part in the table
-below.
-
-A few features are intentionally not supported:
-
-- The ability to configure the matching input set and masks for the entire
- device, PMDs should take care of it automatically according to the
- requested flow rules.
-
- For example if a device supports only one bit-mask per protocol type,
- source/address IPv4 bit-masks can be made immutable by the first created
- rule. Subsequent IPv4 or TCPv4 rules can only be created if they are
- compatible.
-
- Note that only protocol bit-masks affected by existing flow rules are
- immutable, others can be changed later. They become mutable again after
- the related flow rules are destroyed.
-
-- Returning four or eight bytes of matched data when using flex bytes
- filtering. Although a specific action could implement it, it conflicts
- with the much more useful 32 bits tagging on devices that support it.
-
-- Side effects on RSS processing of the entire device. Flow rules that
- conflict with the current device configuration should not be
- allowed. Similarly, device configuration should not be allowed when it
- affects existing flow rules.
-
-- Device modes of operation. "none" is unsupported since filtering cannot be
- disabled as long as a flow rule is present.
-
-- "MAC VLAN" or "tunnel" perfect matching modes should be automatically set
- according to the created flow rules.
-
-- Signature mode of operation is not defined but could be handled through
- "FUZZY" item.
-
-.. _table_rte_flow_migration_fdir:
-
-.. table:: FDIR conversion
-
- +----------------------------------------+-----------------------+
- | Pattern | Actions |
- +===+===================+==========+=====+=======================+
- | 0 | ETH, RAW | ``spec`` | any | QUEUE, DROP, PASSTHRU |
- | | +----------+-----+ |
- | | | ``last`` | N/A | |
- | | +----------+-----+ |
- | | | ``mask`` | any | |
- +---+-------------------+----------+-----+-----------------------+
- | 1 | IPV4, IPv6 | ``spec`` | any | MARK |
- | | +----------+-----+ |
- | | | ``last`` | N/A | |
- | | +----------+-----+ |
- | | | ``mask`` | any | |
- +---+-------------------+----------+-----+-----------------------+
- | 2 | TCP, UDP, SCTP | ``spec`` | any | END |
- | | +----------+-----+ |
- | | | ``last`` | N/A | |
- | | +----------+-----+ |
- | | | ``mask`` | any | |
- +---+-------------------+----------+-----+ |
- | 3 | VF, PF, FUZZY | ``spec`` | any | |
- | | (optional) +----------+-----+ |
- | | | ``last`` | N/A | |
- | | +----------+-----+ |
- | | | ``mask`` | any | |
- +---+-------------------+----------+-----+ |
- | 4 | END | |
- +---+------------------------------------+-----------------------+
-
-``HASH``
-~~~~~~~~
-
-There is no counterpart to this filter type because it translates to a
-global device setting instead of a pattern item. Device settings are
-automatically set according to the created flow rules.
-
-``L2_TUNNEL`` to ``VOID`` → ``VXLAN`` (or others)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-All packets are matched. This type alters incoming packets to encapsulate
-them in a chosen tunnel type, optionally redirect them to a VF as well.
-
-The destination pool for tag based forwarding can be emulated with other
-flow rules using `Action: DUP`_.
-
-.. _table_rte_flow_migration_l2tunnel:
-
-.. table:: L2_TUNNEL conversion
-
- +---------------------------+--------------------+
- | Pattern | Actions |
- +===+======+==========+=====+====================+
- | 0 | VOID | ``spec`` | N/A | VXLAN, GENEVE, ... |
- | | | | | |
- | | | | | |
- | | +----------+-----+ |
- | | | ``last`` | N/A | |
- | | +----------+-----+ |
- | | | ``mask`` | N/A | |
- | | | | | |
- +---+------+----------+-----+--------------------+
- | 1 | END | VF (optional) |
- +---+ +--------------------+
- | 2 | | END |
- +---+-----------------------+--------------------+
git.droids-corp.org / dpdk.git / blobdiff