diff options
Diffstat (limited to 'doc/guides/prog_guide/rte_flow.rst')
| -rw-r--r-- | doc/guides/prog_guide/rte_flow.rst | 159 |
1 files changed, 148 insertions, 11 deletions
diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index 662a9123..d158be5e 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -187,7 +187,7 @@ 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 + 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, @@ -955,6 +955,31 @@ 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. + Actions ~~~~~~~ @@ -972,7 +997,7 @@ 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). @@ -1354,6 +1379,101 @@ rule or if packets are not addressed to a VF in the first place. | ``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 ~~~~~~~~~~~~~~ @@ -1401,7 +1521,7 @@ supported and can be created. .. 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[], @@ -1456,7 +1576,7 @@ actually created and a handle returned. .. 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[], @@ -1488,7 +1608,7 @@ performing this step before releasing resources. .. 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); @@ -1519,7 +1639,7 @@ port. They are released as with successive calls to ``rte_flow_destroy()``. .. 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 @@ -1547,7 +1667,7 @@ definition. .. 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, @@ -1620,7 +1740,7 @@ port and may return errors such as ``ENOTSUP`` ("not supported"): .. 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: @@ -1678,6 +1798,25 @@ freed by the application, however its pointer can be considered valid only 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 ------- @@ -1743,13 +1882,11 @@ the legacy filtering framework, which should eventually disappear. 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 |