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
---------
Attribute: Traffic direction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Flow rules can apply to inbound and/or outbound traffic (ingress/egress).
+Flow rule patterns apply to inbound and/or outbound traffic.
+
+In the context of this API, **ingress** and **egress** respectively stand
+for **inbound** and **outbound** based on the standpoint of the application
+creating a flow rule.
+
+There are no exceptions to this definition.
Several pattern items and actions are valid and can be used in both
directions. At least one direction must be specified.
Specifying both directions at once for a given rule is not recommended but
may be valid in a few cases (e.g. shared counters).
+Attribute: Transfer
+^^^^^^^^^^^^^^^^^^^
+
+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 reroute 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 `Item: PHY_PORT`_
+and is meaningless without them.
+
+When transferring flow rules, **ingress** and **egress** attributes
+(`Attribute: Traffic direction`_) keep their original meaning, as if
+processing traffic emitted or received by the application.
+
Pattern item
~~~~~~~~~~~~
Pattern items fall in two categories:
-- Matching protocol headers and packet data (ANY, RAW, ETH, VLAN, IPV4,
- IPV6, ICMP, UDP, TCP, SCTP, VXLAN, MPLS, GRE and so on), usually
- associated with a specification structure.
+- 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 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.
+- 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.
Item specification structures are used to match specific values among
protocol fields (or item properties). Documentation describes for each item
Item: ``PF``
^^^^^^^^^^^^
-Matches packets addressed to the physical function of the device.
+Matches traffic originating from (ingress) or going to (egress) the physical
+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 `Action: PF`_. Packets are not
-duplicated between device instances by default.
+If supported, should work even if the physical function is not managed by
+the application and thus not associated with a DPDK port ID.
-- Likely to return an error or never match any traffic if applied to a VF
- device.
- Can be combined with any number of `Item: VF`_ to match both PF and VF
traffic.
- ``spec``, ``last`` and ``mask`` must not be set.
Item: ``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 `Action: VF`_. 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.
| ``mask`` | ``id`` | zeroed to match any VF ID |
+----------+----------+---------------------------+
-Item: ``PORT``
-^^^^^^^^^^^^^^
+Item: ``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 several times
-to match additional physical ports.
+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
(port_id) when those are not under DPDK control. Possible values are
- Default ``mask`` matches any port index.
-.. _table_rte_flow_item_port:
+.. _table_rte_flow_item_phy_port:
-.. table:: PORT
+.. table:: PHY_PORT
+----------+-----------+--------------------------------+
| Field | Subfield | Value |
Matches an Ethernet header.
+The ``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, ``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.
+
- ``dst``: destination MAC.
- ``src``: source MAC.
-- ``type``: EtherType.
+- ``type``: EtherType or TPID.
- Default ``mask`` matches destination and source addresses only.
Item: ``VLAN``
Matches an 802.1Q/ad VLAN tag.
-- ``tpid``: tag protocol identifier.
+The corresponding standard outer EtherType (TPID) values are
+``ETHER_TYPE_VLAN`` or ``ETHER_TYPE_QINQ``. It can be overridden by the
+preceding pattern item.
+
- ``tci``: tag control information.
-- Default ``mask`` matches TCI only.
+- ``inner_type``: inner EtherType or TPID.
+- Default ``mask`` matches the VID part of TCI only (lower 12 bits).
Item: ``IPV4``
^^^^^^^^^^^^^^
Matches an IEEE 802.1BR E-Tag header.
-- ``tpid``: tag protocol identifier (0x893F)
+The corresponding standard outer EtherType (TPID) value is
+``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).
- ``rsvd_grp_ecid_b``: reserved (2b), GRP (2b), E-CID base (12b).
- ``in_ecid_e``: ingress E-CID ext.
- ``ecid_e``: E-CID ext.
+- ``inner_type``: inner EtherType or TPID.
- Default ``mask`` simultaneously matches GRP and E-CID base.
Item: ``NVGRE``
- Default ``mask`` matches label only.
Item: ``GRE``
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^
Matches a GRE header.
- ``protocol``: protocol type.
- Default ``mask`` matches protocol only.
+Item: ``FUZZY``
+^^^^^^^^^^^^^^^
+
+Fuzzy pattern match, expect faster than default.
+
+This is for device that support fuzzy match option. Usually a fuzzy match is
+fast but the cost is accuracy. i.e. Signature Match only match pattern's hash
+value, but it is possible two different patterns have the same hash value.
+
+Matching accuracy level can be configured by threshold. Driver can divide the
+range of threshold and map to different accuracy levels that device support.
+
+Threshold 0 means perfect match (no fuzziness), while threshold 0xffffffff
+means fuzziest match.
+
+.. _table_rte_flow_item_fuzzy:
+
+.. table:: FUZZY
+
+ +----------+---------------+--------------------------------------------------+
+ | Field | Subfield | Value |
+ +==========+===============+==================================================+
+ | ``spec`` | ``threshold`` | 0 as perfect match, 0xffffffff as fuzziest match |
+ +----------+---------------+--------------------------------------------------+
+ | ``last`` | ``threshold`` | upper range value |
+ +----------+---------------+--------------------------------------------------+
+ | ``mask`` | ``threshold`` | bit-mask apply to "spec" and "last" |
+ +----------+---------------+--------------------------------------------------+
+
+Usage example, fuzzy match a TCPv4 packets:
+
+.. _table_rte_flow_item_fuzzy_example:
+
+.. table:: Fuzzy matching
+
+ +-------+----------+
+ | Index | Item |
+ +=======+==========+
+ | 0 | FUZZY |
+ +-------+----------+
+ | 1 | Ethernet |
+ +-------+----------+
+ | 2 | IPv4 |
+ +-------+----------+
+ | 3 | TCP |
+ +-------+----------+
+ | 4 | END |
+ +-------+----------+
+
+Item: ``GTP``, ``GTPC``, ``GTPU``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Matches a GTPv1 header.
+
+Note: GTP, GTPC and GTPU use the same structure. GTPC and GTPU item
+are defined for a user-friendly API when creating GTP-C and GTP-U
+flow rules.
+
+- ``v_pt_rsv_flags``: version (3b), protocol type (1b), reserved (1b),
+ extension header flag (1b), sequence number flag (1b), N-PDU number
+ flag (1b).
+- ``msg_type``: message type.
+- ``msg_len``: message length.
+- ``teid``: tunnel endpoint identifier.
+- Default ``mask`` matches teid only.
+
+Item: ``ESP``
+^^^^^^^^^^^^^
+
+Matches an ESP header.
+
+- ``hdr``: ESP header definition (``rte_esp.h``).
+- Default ``mask`` matches SPI only.
+
+Item: ``GENEVE``
+^^^^^^^^^^^^^^^^
+
+Matches a GENEVE header.
+
+- ``ver_opt_len_o_c_rsvd0``: version (2b), length of the options fields (6b),
+ OAM packet (1b), critical options present (1b), reserved 0 (6b).
+- ``protocol``: protocol type.
+- ``vni``: virtual network identifier.
+- ``rsvd1``: reserved, normally 0x00.
+- Default ``mask`` matches VNI only.
+
Actions
~~~~~~~
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.
+configuration structures. Several actions combined in a list can be 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.
+- Actions that modify the fate of matching traffic, for instance by dropping
+ or assigning it a specific destination.
-- Non-terminating actions (PASSTHRU, DUP) 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
- (END, VOID, MARK, FLAG, COUNT).
+- 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``
+Action: ``RSS``
^^^^^^^^^^^^^^^
-Duplicates packets to a given queue index.
+Similar to QUEUE, except RSS is additionally performed on packets to spread
+them among several queues according to the provided parameters.
-This is normally combined with QUEUE, however when used alone, it is
-actually similar to QUEUE + PASSTHRU.
+Unlike global RSS settings used by other DPDK APIs, unsetting the ``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.
-- Non-terminating by default.
+Note: RSS hash result is stored in the ``hash.rss`` mbuf field which
+overlaps ``hash.fdir.lo``. Since `Action: MARK`_ sets the ``hash.fdir.hi``
+field only, both can be requested simultaneously.
-.. _table_rte_flow_action_dup:
+Also, regarding packet encapsulation ``level``:
-.. table:: DUP
+- ``0`` requests the default behavior. Depending on the packet type, it can
+ mean outermost, innermost, anything in between or even no RSS.
- +-----------+------------------------------------+
- | Field | Value |
- +===========+====================================+
- | ``index`` | queue index to duplicate packet to |
- +-----------+------------------------------------+
+ It basically stands for the innermost encapsulation level RSS can be
+ performed on according to PMD and device capabilities.
-Action: ``RSS``
-^^^^^^^^^^^^^^^
+- ``1`` requests RSS to be performed on the outermost packet encapsulation
+ level.
-Similar to QUEUE, except RSS is additionally performed on packets to spread
-them among several queues according to the provided parameters.
+- ``2`` and subsequent values request RSS to be performed on the specified
+ inner packet encapsulation level, from outermost to innermost (lower to
+ higher values).
-Note: RSS hash result is stored in the ``hash.rss`` mbuf field which
-overlaps ``hash.fdir.lo``. Since `Action: MARK`_ sets the ``hash.fdir.hi``
-field only, both can be requested simultaneously.
+Values other than ``0`` are not necessarily supported.
-- Terminating by default.
+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.
.. _table_rte_flow_action_rss:
.. table:: RSS
- +--------------+------------------------------+
- | Field | Value |
- +==============+==============================+
- | ``rss_conf`` | RSS parameters |
- +--------------+------------------------------+
- | ``num`` | number of entries in queue[] |
- +--------------+------------------------------+
- | ``queue[]`` | queue indices to use |
- +--------------+------------------------------+
+ +---------------+---------------------------------------------+
+ | Field | Value |
+ +===============+=============================================+
+ | ``func`` | RSS hash function to apply |
+ +---------------+---------------------------------------------+
+ | ``level`` | encapsulation level for ``types`` |
+ +---------------+---------------------------------------------+
+ | ``types`` | specific RSS hash types (see ``ETH_RSS_*``) |
+ +---------------+---------------------------------------------+
+ | ``key_len`` | hash key length in bytes |
+ +---------------+---------------------------------------------+
+ | ``queue_num`` | number of entries in ``queue`` |
+ +---------------+---------------------------------------------+
+ | ``key`` | hash key |
+ +---------------+---------------------------------------------+
+ | ``queue`` | queue indices to use |
+ +---------------+---------------------------------------------+
Action: ``PF``
^^^^^^^^^^^^^^
-Redirects packets to the physical function (PF) of the current device.
+Directs matching traffic to the physical function (PF) of the current
+device.
+
+See `Item: PF`_.
- No configurable properties.
-- Terminating by default.
.. _table_rte_flow_action_pf:
Action: ``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.
+See `Item: VF`_.
.. _table_rte_flow_action_vf:
+==============+================================+
| ``original`` | use original VF ID if possible |
+--------------+--------------------------------+
- | ``vf`` | VF ID to redirect packets to |
+ | ``id`` | VF ID |
+--------------+--------------------------------+
+Action: ``PHY_PORT``
+^^^^^^^^^^^^^^^^^^^^
+
+Directs matching traffic to a given physical port index of the underlying
+device.
+
+See `Item: PHY_PORT`_.
+
+.. _table_rte_flow_action_phy_port:
+
+.. table:: PHY_PORT
+
+ +--------------+-------------------------------------+
+ | Field | Value |
+ +==============+=====================================+
+ | ``original`` | use original port index if possible |
+ +--------------+-------------------------------------+
+ | ``index`` | physical port index |
+ +--------------+-------------------------------------+
+
+Action: ``METER``
+^^^^^^^^^^^^^^^^^
+
+Applies a stage of metering and policing.
+
+The metering and policing (MTR) object has to be first created using the
+rte_mtr_create() API function. The ID of the MTR object is specified as
+action parameter. More than one flow can use the same MTR object through
+the meter action. The MTR object can be further updated or queried using
+the rte_mtr* API.
+
+.. _table_rte_flow_action_meter:
+
+.. table:: METER
+
+ +--------------+---------------+
+ | Field | Value |
+ +==============+===============+
+ | ``mtr_id`` | MTR object ID |
+ +--------------+---------------+
+
+Action: ``SECURITY``
+^^^^^^^^^^^^^^^^^^^^
+
+Perform the security action on flows matched by the pattern items
+according to the configuration of the security session.
+
+This action modifies the payload of matched flows. For INLINE_CRYPTO, the
+security protocol headers and IV are fully provided by the application as
+specified in the flow pattern. The payload of matching packets is
+encrypted on egress, and decrypted and authenticated on ingress.
+For INLINE_PROTOCOL, the security protocol is fully offloaded to HW,
+providing full encapsulation and decapsulation of packets in security
+protocols. The flow pattern specifies both the outer security header fields
+and the inner packet fields. The security session specified in the action
+must match the pattern parameters.
+
+The security session specified in the action must be created on the same
+port as the flow action that is being specified.
+
+The ingress/egress flow attribute should match that specified in the
+security session if the security session supports the definition of the
+direction.
+
+Multiple flows can be configured to use the same security session.
+
+.. _table_rte_flow_action_security:
+
+.. table:: SECURITY
+
+ +----------------------+--------------------------------------+
+ | Field | Value |
+ +======================+======================================+
+ | ``security_session`` | security session to apply |
+ +----------------------+--------------------------------------+
+
+The following is an example of configuring IPsec inline using the
+INLINE_CRYPTO security session:
+
+The encryption algorithm, keys and salt are part of the opaque
+``rte_security_session``. The SA is identified according to the IP and ESP
+fields in the pattern items.
+
+.. _table_rte_flow_item_esp_inline_example:
+
+.. table:: IPsec inline crypto flow pattern items.
+
+ +-------+----------+
+ | Index | Item |
+ +=======+==========+
+ | 0 | Ethernet |
+ +-------+----------+
+ | 1 | IPv4 |
+ +-------+----------+
+ | 2 | ESP |
+ +-------+----------+
+ | 3 | END |
+ +-------+----------+
+
+.. _table_rte_flow_action_esp_inline_example:
+
+.. table:: IPsec inline flow actions.
+
+ +-------+----------+
+ | Index | Action |
+ +=======+==========+
+ | 0 | SECURITY |
+ +-------+----------+
+ | 1 | END |
+ +-------+----------+
+
Negative types
~~~~~~~~~~~~~~
.. code-block:: c
int
- rte_flow_validate(uint8_t port_id,
+ rte_flow_validate(uint16_t port_id,
const struct rte_flow_attr *attr,
const struct rte_flow_item pattern[],
const struct rte_flow_action actions[],
.. code-block:: c
struct rte_flow *
- rte_flow_create(uint8_t port_id,
+ rte_flow_create(uint16_t port_id,
const struct rte_flow_attr *attr,
const struct rte_flow_item pattern[],
const struct rte_flow_action *actions[],
.. code-block:: c
int
- rte_flow_destroy(uint8_t port_id,
+ rte_flow_destroy(uint16_t port_id,
struct rte_flow *flow,
struct rte_flow_error *error);
.. code-block:: c
int
- rte_flow_flush(uint8_t port_id,
+ rte_flow_flush(uint16_t port_id,
struct rte_flow_error *error);
In the unlikely event of failure, handles are still considered destroyed and
.. code-block:: c
int
- rte_flow_query(uint8_t port_id,
+ rte_flow_query(uint16_t port_id,
struct rte_flow *flow,
enum rte_flow_action_type action,
void *data,
- 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
+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
+queue (with or without RSS, locally or in some sub-device instance)
+depending on the global configuration settings of a port.
+
+While fine from a compatibility standpoint, this approach makes drivers more
+complex as they have to check for possible side effects outside of this API
+when creating or destroying flow rules. It results in a more limited set of
+available rule types due to the way device resources are assigned (e.g. no
+support for the RSS action even on capable hardware).
+
+Given that nonspecific traffic can be handled by flow rules as well,
+isolated mode is a means for applications to tell a driver that ingress on
+the underlying port must be injected from the defined flow rules only; that
+no default traffic is expected outside those rules.
+
+This has the following benefits:
+
+- Applications get finer-grained control over the kind of traffic they want
+ to receive (no traffic by default).
+
+- More importantly they control at what point nonspecific traffic is handled
+ relative to other flow rules, by adjusting priority levels.
+
+- Drivers can assign more hardware resources to flow rules and expand the
+ set of supported rule types.
+
+Because toggling isolated mode may cause profound changes to the ingress
+processing path of a driver, it may not be possible to leave it once
+entered. Likewise, existing flow rules or global configuration settings may
+prevent a driver from entering isolated mode.
+
+Applications relying on this mode are therefore encouraged to toggle it as
+soon as possible after device initialization, ideally before the first call
+to ``rte_eth_dev_configure()`` to avoid possible failures due to conflicting
+settings.
+
+Once effective, the following functionality has no effect on the underlying
+port and may return errors such as ``ENOTSUP`` ("not supported"):
+
+- Toggling promiscuous mode.
+- Toggling allmulticast mode.
+- Configuring MAC addresses.
+- Configuring multicast addresses.
+- Configuring VLAN filters.
+- Configuring Rx filters through the legacy API (e.g. FDIR).
+- Configuring global RSS settings.
+
+.. code-block:: c
+
+ int
+ rte_flow_isolate(uint16_t port_id, int set, struct rte_flow_error *error);
+
+Arguments:
+
+- ``port_id``: port identifier of Ethernet device.
+- ``set``: nonzero to enter isolated mode, attempt to leave it otherwise.
+- ``error``: perform verbose error reporting if not NULL. PMDs initialize
+ this structure in case of error only.
+
+Return values:
+
+- 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
+
Verbose error reporting
-----------------------
as long as its associated DPDK port remains configured. Closing the
underlying device or unloading the PMD invalidates it.
+Helpers
+-------
+
+Error initializer
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+ static inline int
+ rte_flow_error_set(struct rte_flow_error *error,
+ int code,
+ enum rte_flow_error_type type,
+ const void *cause,
+ const char *message);
+
+This function initializes ``error`` (if non-NULL) with the provided
+parameters and sets ``rte_errno`` to ``code``. A negative error ``code`` is
+then returned.
+
Caveats
-------
whatsoever). They only make sure these callbacks are non-NULL or return
the ``ENOSYS`` (function not supported) error.
-This interface additionally defines the following helper functions:
+This interface additionally defines the following helper function:
- ``rte_flow_ops_get()``: get generic flow operations structure from a
port.
-- ``rte_flow_error_set()``: initialize generic flow error structure.
-
More will be added over time.
Device compatibility
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 a
- specific item type if needed.
-
-.. _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 (optional) | ``spec`` | any | |
- | | +----------+-----+ |
- | | | ``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