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
---------
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
| 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``
-^^^^^^^^^^^^^^^
-
-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
| ``vf`` | VF ID to redirect packets to |
+--------------+--------------------------------+
+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,
.. code-block:: c
int
- rte_flow_isolate(uint8_t port_id, int set, struct rte_flow_error *error);
+ rte_flow_isolate(uint16_t port_id, int set, struct rte_flow_error *error);
Arguments:
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
- "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