bit-masks. They must be specified (stacked) from lowest to highest protocol
layer to form a matching pattern.
-The following list is not exhaustive, new protocols will be added in the
-future.
-
Item: ``ANY``
^^^^^^^^^^^^^
- ``l4_csum_ok``: layer 4 checksum check passed.
- ``l3_len_ok``: the layer 3 length is smaller than the frame length.
+Item: ``CONNTRACK``
+^^^^^^^^^^^^^^^^^^^
+
+Matches a conntrack state after conntrack action.
+
+- ``flags``: conntrack packet state flags.
+- Default ``mask`` matches all state bits.
+
Actions
~~~~~~~
Action types
~~~~~~~~~~~~
-Common action types are described in this section. Like pattern item types,
-this list is not exhaustive as new actions will be added in the future.
+Common action types are described in this section.
Action: ``END``
^^^^^^^^^^^^^^^
| ``value`` | immediate value or a pointer to this value |
+---------------+----------------------------------------------------------+
+Action: ``CONNTRACK``
+^^^^^^^^^^^^^^^^^^^^^
+
+Create a conntrack (connection tracking) context with the provided information.
+
+In stateful session like TCP, the conntrack action provides the ability to
+examine every packet of this connection and associate the state to every
+packet. It will help to realize the stateful offload of connections with little
+software participation. For example, the packets with invalid state may be
+handled by the software. The control packets could be handled in the hardware.
+The software just need to query the state of a connection when needed, and then
+decide how to handle the flow rules and conntrack context.
+
+A conntrack context should be created via ``rte_flow_action_handle_create()``
+before using. Then the handle with ``INDIRECT`` type is used for a flow rule
+creation. If a flow rule with an opposite direction needs to be created, the
+``rte_flow_action_handle_update()`` should be used to modify the direction.
+
+Not all the fields of the ``struct rte_flow_action_conntrack`` will be used
+for a conntrack context creating, depending on the HW, and they should be
+in host byte order. PMD should convert them into network byte order when
+needed by the HW.
+
+The ``struct rte_flow_modify_conntrack`` should be used for an updating.
+
+The current conntrack context information could be queried via the
+``rte_flow_action_handle_query()`` interface.
+
+.. _table_rte_flow_action_conntrack:
+
+.. table:: CONNTRACK
+
+ +--------------------------+-------------------------------------------------------------+
+ | Field | Value |
+ +==========================+=============================================================+
+ | ``peer_port`` | peer port number |
+ +--------------------------+-------------------------------------------------------------+
+ | ``is_original_dir`` | direction of this connection for creating flow rule |
+ +--------------------------+-------------------------------------------------------------+
+ | ``enable`` | enable the conntrack context |
+ +--------------------------+-------------------------------------------------------------+
+ | ``live_connection`` | one ack was seen for this connection |
+ +--------------------------+-------------------------------------------------------------+
+ | ``selective_ack`` | SACK enabled |
+ +--------------------------+-------------------------------------------------------------+
+ | ``challenge_ack_passed`` | a challenge ack has passed |
+ +--------------------------+-------------------------------------------------------------+
+ | ``last_direction`` | direction of the last passed packet |
+ +--------------------------+-------------------------------------------------------------+
+ | ``liberal_mode`` | only report state change |
+ +--------------------------+-------------------------------------------------------------+
+ | ``state`` | current state |
+ +--------------------------+-------------------------------------------------------------+
+ | ``max_ack_window`` | maximal window scaling factor |
+ +--------------------------+-------------------------------------------------------------+
+ | ``retransmission_limit`` | maximal retransmission times |
+ +--------------------------+-------------------------------------------------------------+
+ | ``original_dir`` | TCP parameters of the original direction |
+ +--------------------------+-------------------------------------------------------------+
+ | ``reply_dir`` | TCP parameters of the reply direction |
+ +--------------------------+-------------------------------------------------------------+
+ | ``last_window`` | window size of the last passed packet |
+ +--------------------------+-------------------------------------------------------------+
+ | ``last_seq`` | sequence number of the last passed packet |
+ +--------------------------+-------------------------------------------------------------+
+ | ``last_ack`` | acknowledgment number the last passed packet |
+ +--------------------------+-------------------------------------------------------------+
+ | ``last_end`` | sum of ack number and length of the last passed packet |
+ +--------------------------+-------------------------------------------------------------+
+
+.. _table_rte_flow_tcp_dir_param:
+
+.. table:: configuration parameters for each direction
+
+ +---------------------+---------------------------------------------------------+
+ | Field | Value |
+ +=====================+=========================================================+
+ | ``scale`` | TCP window scaling factor |
+ +---------------------+---------------------------------------------------------+
+ | ``close_initiated`` | FIN sent from this direction |
+ +---------------------+---------------------------------------------------------+
+ | ``last_ack_seen`` | an ACK packet received |
+ +---------------------+---------------------------------------------------------+
+ | ``data_unacked`` | unacknowledged data for packets from this direction |
+ +---------------------+---------------------------------------------------------+
+ | ``sent_end`` | max{seq + len} seen in sent packets |
+ +---------------------+---------------------------------------------------------+
+ | ``reply_end`` | max{sack + max{win, 1}} seen in reply packets |
+ +---------------------+---------------------------------------------------------+
+ | ``max_win`` | max{max{win, 1}} + {sack - ack} seen in sent packets |
+ +---------------------+---------------------------------------------------------+
+ | ``max_ack`` | max{ack} + seen in sent packets |
+ +---------------------+---------------------------------------------------------+
+
+.. _table_rte_flow_modify_conntrack:
+
+.. table:: update a conntrack context
+
+ +----------------+-------------------------------------------------+
+ | Field | Value |
+ +================+=================================================+
+ | ``new_ct`` | new conntrack information |
+ +----------------+-------------------------------------------------+
+ | ``direction`` | direction will be updated |
+ +----------------+-------------------------------------------------+
+ | ``state`` | other fields except direction will be updated |
+ +----------------+-------------------------------------------------+
+ | ``reserved`` | reserved bits |
+ +----------------+-------------------------------------------------+
+
+Action: ``METER_COLOR``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Color the packet to reflect the meter color result.
+
+The meter action must be configured before meter color action.
+Meter color action is set to a color to reflect the meter color result.
+Set the meter color in the mbuf to the selected color.
+The meter color action output color is the output color of the packet,
+which is set in the packet meta-data (i.e. struct ``rte_mbuf::sched::color``)
+
+.. _table_rte_flow_action_meter_color:
+
+.. table:: METER_COLOR
+
+ +-----------------+--------------+
+ | Field | Value |
+ +=================+==============+
+ | ``meter_color`` | Packet color |
+ +-----------------+--------------+
+
Negative types
~~~~~~~~~~~~~~
Application may use PMD dynamic items or actions in flow rules. In that case
size of configuration object in dynamic element must be a pointer size.
-Planned types
-~~~~~~~~~~~~~
-
-Pattern item types will be added as new protocols are implemented.
-
-Variable headers support through dedicated pattern items, for example in
-order to match specific IPv4 options and IPv6 extension headers would be
-stacked after IPv4/IPv6 items.
-
-Other action types are planned but are not defined yet. These include the
-ability to alter packet data in several ways, such as performing
-encapsulation/decapsulation of tunnel headers.
-
Rules management
----------------
Please note that this API-level mutex protects only rte_flow functions,
other control path functions are not in scope.
-More will be added over time.
-
Device compatibility
--------------------
- In order to save priority levels, PMDs may evaluate whether rules are
likely to collide and adjust their priority accordingly.
-Future evolutions
------------------
-
-- A device profile selection function which could be used to force a
- permanent profile instead of relying on its automatic configuration based
- on existing flow rules.
-
-- A method to optimize *rte_flow* rules with specific pattern items and
- action types generated on the fly by PMDs. DPDK should assign negative
- numbers to these in order to not collide with the existing types. See
- `Negative types`_.
-
-- Adding specific egress pattern items and actions as described in
- `Attribute: Traffic direction`_.
-
-- Optional software fallback when PMDs are unable to handle requested flow
- rules so applications do not have to implement their own.
.. _OpenFlow Switch Specification: https://www.opennetworking.org/software-defined-standards/specifications/