X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fprog_guide%2Frte_flow.rst;h=15c7b804f3cb79ac4c584046191f5ba25b17db7f;hb=44bf3c796be3f747eba5d4904d93614ff300e688;hp=7da446e8a358c4cd04e78f31accfb3d7967a08f7;hpb=3374db185755b1c62c13c0235a6244eec6e0f93f;p=dpdk.git diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index 7da446e8a3..15c7b804f3 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -238,29 +238,29 @@ Example of an item specification matching an Ethernet header: .. table:: Ethernet item - +----------+----------+--------------------+ - | Field | Subfield | Value | - +==========+==========+====================+ - | ``spec`` | ``src`` | ``00:01:02:03:04`` | - | +----------+--------------------+ - | | ``dst`` | ``00:2a:66:00:01`` | - | +----------+--------------------+ - | | ``type`` | ``0x22aa`` | - +----------+----------+--------------------+ - | ``last`` | unspecified | - +----------+----------+--------------------+ - | ``mask`` | ``src`` | ``00:ff:ff:ff:00`` | - | +----------+--------------------+ - | | ``dst`` | ``00:00:00:00:ff`` | - | +----------+--------------------+ - | | ``type`` | ``0x0000`` | - +----------+----------+--------------------+ + +----------+----------+-----------------------+ + | Field | Subfield | Value | + +==========+==========+=======================+ + | ``spec`` | ``src`` | ``00:00:01:02:03:04`` | + | +----------+-----------------------+ + | | ``dst`` | ``00:00:2a:66:00:01`` | + | +----------+-----------------------+ + | | ``type`` | ``0x22aa`` | + +----------+----------+-----------------------+ + | ``last`` | unspecified | + +----------+----------+-----------------------+ + | ``mask`` | ``src`` | ``00:00:ff:ff:ff:00`` | + | +----------+-----------------------+ + | | ``dst`` | ``00:00:00:00:00:ff`` | + | +----------+-----------------------+ + | | ``type`` | ``0x0000`` | + +----------+----------+-----------------------+ Non-masked bits stand for any value (shown as ``?`` below), Ethernet headers with the following properties are thus matched: -- ``src``: ``??:01:02:03:??`` -- ``dst``: ``??:??:??:??:01`` +- ``src``: ``??:??:01:02:03:??`` +- ``dst``: ``??:??:??:??:??:01`` - ``type``: ``0x????`` Matching pattern @@ -658,6 +658,60 @@ the physical device, with virtual groups in the PMD or not at all. | ``mask`` | ``id`` | zeroed to match any value | +----------+----------+---------------------------+ +Item: ``TAG`` +^^^^^^^^^^^^^ + +Matches tag item set by other flows. Multiple tags are supported by specifying +``index``. + +- Default ``mask`` matches the specified tag value and index. + +.. _table_rte_flow_item_tag: + +.. table:: TAG + + +----------+----------+----------------------------------------+ + | Field | Subfield | Value | + +==========+===========+=======================================+ + | ``spec`` | ``data`` | 32 bit flow tag value | + | +-----------+---------------------------------------+ + | | ``index`` | index of flow tag | + +----------+-----------+---------------------------------------+ + | ``last`` | ``data`` | upper range value | + | +-----------+---------------------------------------+ + | | ``index`` | field is ignored | + +----------+-----------+---------------------------------------+ + | ``mask`` | ``data`` | bit-mask applies to "spec" and "last" | + | +-----------+---------------------------------------+ + | | ``index`` | field is ignored | + +----------+-----------+---------------------------------------+ + +Item: ``META`` +^^^^^^^^^^^^^^^^^ + +Matches 32 bit metadata item set. + +On egress, metadata can be set either by mbuf metadata field with +PKT_TX_DYNF_METADATA flag or ``SET_META`` action. On ingress, ``SET_META`` +action sets metadata for a packet and the metadata will be reported via +``metadata`` dynamic field of ``rte_mbuf`` with PKT_RX_DYNF_METADATA flag. + +- Default ``mask`` matches the specified Rx metadata value. + +.. _table_rte_flow_item_meta: + +.. table:: META + + +----------+----------+---------------------------------------+ + | Field | Subfield | Value | + +==========+==========+=======================================+ + | ``spec`` | ``data`` | 32 bit metadata value | + +----------+----------+---------------------------------------+ + | ``last`` | ``data`` | upper range value | + +----------+----------+---------------------------------------+ + | ``mask`` | ``data`` | bit-mask applies to "spec" and "last" | + +----------+----------+---------------------------------------+ + Data matching item types ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1205,19 +1259,101 @@ Matches an application specific 32 bit metadata item. - Default ``mask`` matches the specified metadata value. -.. _table_rte_flow_item_meta: +Item: ``GTP_PSC`` +^^^^^^^^^^^^^^^^^ -.. table:: META +Matches a GTP PDU extension header with type 0x85. - +----------+----------+---------------------------------------+ - | Field | Subfield | Value | - +==========+==========+=======================================+ - | ``spec`` | ``data`` | 32 bit metadata value | - +----------+--------------------------------------------------+ - | ``last`` | ``data`` | upper range value | - +----------+----------+---------------------------------------+ - | ``mask`` | ``data`` | bit-mask applies to "spec" and "last" | - +----------+----------+---------------------------------------+ +- ``pdu_type``: PDU type. +- ``qfi``: QoS flow identifier. +- Default ``mask`` matches QFI only. + +Item: ``PPPOES``, ``PPPOED`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Matches a PPPoE header. + +- ``version_type``: version (4b), type (4b). +- ``code``: message type. +- ``session_id``: session identifier. +- ``length``: payload length. + +Item: ``PPPOE_PROTO_ID`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Matches a PPPoE session protocol identifier. + +- ``proto_id``: PPP protocol identifier. +- Default ``mask`` matches proto_id only. + +Item: ``NSH`` +^^^^^^^^^^^^^ + +Matches a network service header (RFC 8300). + +- ``version``: normally 0x0 (2 bits). +- ``oam_pkt``: indicate oam packet (1 bit). +- ``reserved``: reserved bit (1 bit). +- ``ttl``: maximum SFF hopes (6 bits). +- ``length``: total length in 4 bytes words (6 bits). +- ``reserved1``: reserved1 bits (4 bits). +- ``mdtype``: ndicates format of NSH header (4 bits). +- ``next_proto``: indicates protocol type of encap data (8 bits). +- ``spi``: service path identifier (3 bytes). +- ``sindex``: service index (1 byte). +- Default ``mask`` matches mdtype, next_proto, spi, sindex. + + +Item: ``IGMP`` +^^^^^^^^^^^^^^ + +Matches a Internet Group Management Protocol (RFC 2236). + +- ``type``: IGMP message type (Query/Report). +- ``max_resp_time``: max time allowed before sending report. +- ``checksum``: checksum, 1s complement of whole IGMP message. +- ``group_addr``: group address, for Query value will be 0. +- Default ``mask`` matches group_addr. + + +Item: ``AH`` +^^^^^^^^^^^^ + +Matches a IP Authentication Header (RFC 4302). + +- ``next_hdr``: next payload after AH. +- ``payload_len``: total length of AH in 4B words. +- ``reserved``: reserved bits. +- ``spi``: security parameters index. +- ``seq_num``: counter value increased by 1 on each packet sent. +- Default ``mask`` matches spi. + +Item: ``HIGIG2`` +^^^^^^^^^^^^^^^^^ + +Matches a HIGIG2 header field. It is layer 2.5 protocol and used in +Broadcom switches. + +- Default ``mask`` matches classification and vlan. + +Item: ``L2TPV3OIP`` +^^^^^^^^^^^^^^^^^^^ + +Matches a L2TPv3 over IP header. + +- ``session_id``: L2TPv3 over IP session identifier. +- Default ``mask`` matches session_id only. + +Item: ``PFCP`` +^^^^^^^^^^^^^^ + +Matches a PFCP Header. + +- ``s_field``: S field. +- ``msg_type``: message type. +- ``msg_len``: message length. +- ``seid``: session endpoint identifier. +- Default ``mask`` matches s_field and seid. Actions ~~~~~~~ @@ -1532,7 +1668,7 @@ Counters can be retrieved and reset through ``rte_flow_query()``, see The shared flag indicates whether the counter is unique to the flow rule the action is specified with, or whether it is a shared counter. -For a count action with the shared flag set, then then a global device +For a count action with the shared flag set, then a global device namespace is assumed for the counter id, so that any matched flow rules using a count action with the same counter id on the same port will contribute to that counter. @@ -2387,6 +2523,121 @@ Value to decrease TCP acknowledgment number by is a big-endian 32 bit integer. Using this action on non-matching traffic will result in undefined behavior. +Action: ``SET_TAG`` +^^^^^^^^^^^^^^^^^^^ + +Set Tag. + +Tag is a transient data used during flow matching. This is not delivered to +application. Multiple tags are supported by specifying index. + +.. _table_rte_flow_action_set_tag: + +.. table:: SET_TAG + + +-----------+----------------------------+ + | Field | Value | + +===========+============================+ + | ``data`` | 32 bit tag value | + +-----------+----------------------------+ + | ``mask`` | bit-mask applies to "data" | + +-----------+----------------------------+ + | ``index`` | index of tag to set | + +-----------+----------------------------+ + +Action: ``SET_META`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Set metadata. Item ``META`` matches metadata. + +Metadata set by mbuf metadata field with PKT_TX_DYNF_METADATA flag on egress +will be overridden by this action. On ingress, the metadata will be carried by +``metadata`` dynamic field of ``rte_mbuf`` which can be accessed by +``RTE_FLOW_DYNF_METADATA()``. PKT_RX_DYNF_METADATA flag will be set along +with the data. + +The mbuf dynamic field must be registered by calling +``rte_flow_dynf_metadata_register()`` prior to use ``SET_META`` action. + +Altering partial bits is supported with ``mask``. For bits which have never been +set, unpredictable value will be seen depending on driver implementation. For +loopback/hairpin packet, metadata set on Rx/Tx may or may not be propagated to +the other path depending on HW capability. + +.. _table_rte_flow_action_set_meta: + +.. table:: SET_META + + +----------+----------------------------+ + | Field | Value | + +==========+============================+ + | ``data`` | 32 bit metadata value | + +----------+----------------------------+ + | ``mask`` | bit-mask applies to "data" | + +----------+----------------------------+ + +Action: ``SET_IPV4_DSCP`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set IPv4 DSCP. + +Modify DSCP in IPv4 header. + +It must be used with RTE_FLOW_ITEM_TYPE_IPV4 in pattern. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_ipv4_dscp: + +.. table:: SET_IPV4_DSCP + + +-----------+---------------------------------+ + | Field | Value | + +===========+=================================+ + | ``dscp`` | DSCP in low 6 bits, rest ignore | + +-----------+---------------------------------+ + +Action: ``SET_IPV6_DSCP`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set IPv6 DSCP. + +Modify DSCP in IPv6 header. + +It must be used with RTE_FLOW_ITEM_TYPE_IPV6 in pattern. +Otherwise, RTE_FLOW_ERROR_TYPE_ACTION error will be returned. + +.. _table_rte_flow_action_set_ipv6_dscp: + +.. table:: SET_IPV6_DSCP + + +-----------+---------------------------------+ + | Field | Value | + +===========+=================================+ + | ``dscp`` | DSCP in low 6 bits, rest ignore | + +-----------+---------------------------------+ + +Action: ``AGE`` +^^^^^^^^^^^^^^^ + +Set ageing timeout configuration to a flow. + +Event RTE_ETH_EVENT_FLOW_AGED will be reported if +timeout passed without any matching on the flow. + +.. _table_rte_flow_action_age: + +.. table:: AGE + + +--------------+---------------------------------+ + | Field | Value | + +==============+=================================+ + | ``timeout`` | 24 bits timeout value | + +--------------+---------------------------------+ + | ``reserved`` | 8 bits reserved, must be zero | + +--------------+---------------------------------+ + | ``context`` | user input flow context | + +--------------+---------------------------------+ + Negative types ~~~~~~~~~~~~~~