destroyed by the application before releasing associated resources such as
queues and ports.
+.. warning::
+
+ The following description of rule persistence is an experimental behavior
+ that may change without a prior notice.
+
+When the device is stopped, its rules do not process the traffic.
+In particular, transfer rules created using some device
+stop affecting the traffic even if they refer to different ports.
+
+If ``RTE_ETH_DEV_CAPA_FLOW_RULE_KEEP`` is not advertised,
+rules cannot be created until the device is started for the first time
+and cannot be kept when the device is stopped.
+However, PMD also does not flush them automatically on stop,
+so the application must call ``rte_flow_flush()`` or ``rte_flow_destroy()``
+before stopping the device to ensure no rules remain.
+
+If ``RTE_ETH_DEV_CAPA_FLOW_RULE_KEEP`` is advertised, this means
+the PMD can keep at least some rules across the device stop and start.
+However, ``rte_eth_dev_configure()`` may fail if any rules remain,
+so the application must flush them before attempting a reconfiguration.
+Keeping may be unsupported for some types of rule items and actions,
+as well as depending on the value of flow attributes transfer bit.
+A combination of a single an item or action type
+and a value of the transfer bit is called a rule feature.
+For example: a COUNT action with the transfer bit set.
+To test if rules with a particular feature are kept, the application must try
+to create a valid rule using this feature when the device is not started
+(either before the first start or after a stop).
+If it fails with an error of type ``RTE_FLOW_ERROR_TYPE_STATE``,
+all rules using this feature must be flushed by the application
+before stopping the device.
+If it succeeds, such rules will be kept when the device is stopped,
+provided they do not use other features that are not supported.
+Rules that are created when the device is stopped, including the rules
+created for the test, will be kept after the device is started.
+
The following sections cover:
- **Attributes** (represented by ``struct rte_flow_attr``): properties of a
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``
+RTE_MBUF_DYNFLAG_TX_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.
+``metadata`` dynamic field of ``rte_mbuf`` with RTE_MBUF_DYNFLAG_RX_METADATA flag.
- Default ``mask`` matches the specified Rx metadata value.
as padded with trailing zeroes up to full configured length, both for
value and mask.
+Item: ``L2TPV2``
+^^^^^^^^^^^^^^^^^^^
+
+Matches a L2TPv2 header.
+
+- ``flags_version``: flags(12b), version(4b).
+- ``length``: total length of the message.
+- ``tunnel_id``: identifier for the control connection.
+- ``session_id``: identifier for a session within a tunnel.
+- ``ns``: sequence number for this date or control message.
+- ``nr``: sequence number expected in the next control message to be received.
+- ``offset_size``: offset of payload data.
+- ``offset_padding``: offset padding, variable length.
+- Default ``mask`` matches flags_version only.
+
+Item: ``PPP``
+^^^^^^^^^^^^^^^^^^^
+
+Matches a PPP header.
+
+- ``addr``: PPP address.
+- ``ctrl``: PPP control.
+- ``proto_id``: PPP protocol identifier.
+- Default ``mask`` matches addr, ctrl, proto_id.
+
Actions
~~~~~~~
Action: ``MARK``
^^^^^^^^^^^^^^^^
-Attaches an integer value to packets and sets ``PKT_RX_FDIR`` and
-``PKT_RX_FDIR_ID`` mbuf flags.
+Attaches an integer value to packets and sets ``RTE_MBUF_F_RX_FDIR`` and
+``RTE_MBUF_F_RX_FDIR_ID`` mbuf flags.
This value is arbitrary and application-defined. Maximum allowed value
depends on the underlying implementation. It is returned in the
^^^^^^^^^^^^^^^^
Flags packets. Similar to `Action: MARK`_ without a specific value; only
-sets the ``PKT_RX_FDIR`` mbuf flag.
+sets the ``RTE_MBUF_F_RX_FDIR`` mbuf flag.
- No configurable properties.
.. table:: RSS
- +---------------+---------------------------------------------+
- | 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 |
- +---------------+---------------------------------------------+
+ +---------------+-------------------------------------------------+
+ | Field | Value |
+ +===============+=================================================+
+ | ``func`` | RSS hash function to apply |
+ +---------------+-------------------------------------------------+
+ | ``level`` | encapsulation level for ``types`` |
+ +---------------+-------------------------------------------------+
+ | ``types`` | specific RSS hash types (see ``RTE_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``
^^^^^^^^^^^^^^
Action: ``OF_SET_MPLS_TTL``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This action is deprecated. Consider `Action: MODIFY_FIELD`_.
Implements ``OFPAT_SET_MPLS_TTL`` ("MPLS TTL") as defined by the `OpenFlow
Switch Specification`_.
Action: ``OF_DEC_MPLS_TTL``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This action is deprecated. Consider `Action: MODIFY_FIELD`_.
Implements ``OFPAT_DEC_MPLS_TTL`` ("decrement MPLS TTL") as defined by the
`OpenFlow Switch Specification`_.
Action: ``OF_SET_NW_TTL``
^^^^^^^^^^^^^^^^^^^^^^^^^
+This action is deprecated. Consider `Action: MODIFY_FIELD`_.
Implements ``OFPAT_SET_NW_TTL`` ("IP TTL") as defined by the `OpenFlow
Switch Specification`_.
Action: ``OF_DEC_NW_TTL``
^^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Implements ``OFPAT_DEC_NW_TTL`` ("decrement IP TTL") as defined by the
`OpenFlow Switch Specification`_.
Action: ``OF_COPY_TTL_OUT``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This action is deprecated. Consider `Action: MODIFY_FIELD`_.
Implements ``OFPAT_COPY_TTL_OUT`` ("copy TTL "outwards" -- from
next-to-outermost to outermost") as defined by the `OpenFlow Switch
Action: ``OF_COPY_TTL_IN``
^^^^^^^^^^^^^^^^^^^^^^^^^^
+This action is deprecated. Consider `Action: MODIFY_FIELD`_.
Implements ``OFPAT_COPY_TTL_IN`` ("copy TTL "inwards" -- from outermost to
next-to-outermost") as defined by the `OpenFlow Switch Specification`_.
Action: ``SET_IPV4_SRC``
^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set a new IPv4 source address in the outermost IPv4 header.
Action: ``SET_IPV4_DST``
^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set a new IPv4 destination address in the outermost IPv4 header.
Action: ``SET_IPV6_SRC``
^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set a new IPv6 source address in the outermost IPv6 header.
Action: ``SET_IPV6_DST``
^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set a new IPv6 destination address in the outermost IPv6 header.
Action: ``SET_TP_SRC``
^^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set a new source port number in the outermost TCP/UDP header.
Action: ``SET_TP_DST``
^^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set a new destination port number in the outermost TCP/UDP header.
Action: ``DEC_TTL``
^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Decrease TTL value.
Action: ``SET_TTL``
^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Assigns a new TTL value.
Action: ``SET_MAC_SRC``
^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set source MAC address.
Action: ``SET_MAC_DST``
^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set destination MAC address.
Action: ``INC_TCP_SEQ``
^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Increase sequence number in the outermost TCP header.
Value to increase TCP sequence number by is a big-endian 32 bit integer.
Action: ``DEC_TCP_SEQ``
^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Decrease sequence number in the outermost TCP header.
Value to decrease TCP sequence number by is a big-endian 32 bit integer.
Action: ``INC_TCP_ACK``
^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Increase acknowledgment number in the outermost TCP header.
Value to increase TCP acknowledgment number by is a big-endian 32 bit integer.
Action: ``DEC_TCP_ACK``
^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Decrease acknowledgment number in the outermost TCP header.
Value to decrease TCP acknowledgment number by is a big-endian 32 bit integer.
Action: ``SET_TAG``
^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set Tag.
Action: ``SET_META``
^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set metadata. Item ``META`` matches metadata.
-Metadata set by mbuf metadata field with PKT_TX_DYNF_METADATA flag on egress
+Metadata set by mbuf metadata field with RTE_MBUF_DYNFLAG_TX_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
+``RTE_FLOW_DYNF_METADATA()``. RTE_MBUF_DYNFLAG_RX_METADATA flag will be set along
with the data.
The mbuf dynamic field must be registered by calling
Action: ``SET_IPV4_DSCP``
^^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set IPv4 DSCP.
Action: ``SET_IPV6_DSCP``
^^^^^^^^^^^^^^^^^^^^^^^^^
+This is a legacy action. Consider `Action: MODIFY_FIELD`_ as alternative.
Set IPv6 DSCP.
The indirect action specified data (e.g. counter) can be queried by
``rte_flow_action_handle_query()``.
+.. warning::
+
+ The following description of indirect action persistence
+ is an experimental behavior that may change without a prior notice.
+
+If ``RTE_ETH_DEV_CAPA_FLOW_SHARED_OBJECT_KEEP`` is not advertised,
+indirect actions cannot be created until the device is started for the first time
+and cannot be kept when the device is stopped.
+However, PMD also does not flush them automatically on stop,
+so the application must call ``rte_flow_action_handle_destroy()``
+before stopping the device to ensure no indirect actions remain.
+
+If ``RTE_ETH_DEV_CAPA_FLOW_SHARED_OBJECT_KEEP`` is advertised,
+this means that the PMD can keep at least some indirect actions
+across device stop and start.
+However, ``rte_eth_dev_configure()`` may fail if any indirect actions remain,
+so the application must destroy them before attempting a reconfiguration.
+Keeping may be only supported for certain kinds of indirect actions.
+A kind is a combination of an action type and a value of its transfer bit.
+For example: an indirect counter with the transfer bit reset.
+To test if a particular kind of indirect actions is kept,
+the application must try to create a valid indirect action of that kind
+when the device is not started (either before the first start of after a stop).
+If it fails with an error of type ``RTE_FLOW_ERROR_TYPE_STATE``,
+application must destroy all indirect actions of this kind
+before stopping the device.
+If it succeeds, all indirect actions of the same kind are kept
+when the device is stopped.
+Indirect actions of a kept kind that are created when the device is stopped,
+including the ones created for the test, will be kept after the device start.
+
.. _table_rte_flow_action_handle:
.. table:: INDIRECT
git.droids-corp.org / dpdk.git / blobdiff