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
+ IPV6, ICMP, UDP, TCP, SCTP, VXLAN, MPLS, GRE, ESP and so on), usually
associated with a specification structure.
- Matching meta-data or affecting pattern processing (END, VOID, INVERT, PF,
- Default ``mask`` matches label only.
Item: ``GRE``
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^
Matches a GRE header.
- Default ``mask`` matches protocol only.
Item: ``FUZZY``
-^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^
Fuzzy pattern match, expect faster than default.
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:
| 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
+configuration structures. Several actions combined in a list can be assigned
to a flow rule. That list is not ordered.
They fall in three categories:
additional processing by subsequent flow rules.
- Other non-terminating meta actions that do not affect the fate of packets
- (END, VOID, MARK, FLAG, COUNT).
+ (END, VOID, MARK, FLAG, COUNT, SECURITY).
When several actions are combined in a flow rule, they should all have
different types (e.g. dropping a packet twice is not possible).
| ``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.
+
+- Non-terminating by default.
+
+.. _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.
+
+- Non-terminating by default.
+
+.. _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