- ``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
~~~~~~~
| ``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 |
+ +----------------+-------------------------------------------------+
+
Negative types
~~~~~~~~~~~~~~
#include <rte_esp.h>
#include <rte_higig.h>
#include <rte_ecpri.h>
+#include <rte_bitops.h>
#include <rte_mbuf.h>
#include <rte_mbuf_dyn.h>
* @see struct rte_flow_item_integrity.
*/
RTE_FLOW_ITEM_TYPE_INTEGRITY,
+
+ /**
+ * [META]
+ *
+ * Matches conntrack state.
+ *
+ * @see struct rte_flow_item_conntrack.
+ */
+ RTE_FLOW_ITEM_TYPE_CONNTRACK,
};
/**
};
#endif
+/**
+ * The packet is valid after conntrack checking.
+ */
+#define RTE_FLOW_CONNTRACK_PKT_STATE_VALID RTE_BIT32(0)
+/**
+ * The state of the connection is changed.
+ */
+#define RTE_FLOW_CONNTRACK_PKT_STATE_CHANGED RTE_BIT32(1)
+/**
+ * Error is detected on this packet for this connection and
+ * an invalid state is set.
+ */
+#define RTE_FLOW_CONNTRACK_PKT_STATE_INVALID RTE_BIT32(2)
+/**
+ * The HW connection tracking module is disabled.
+ * It can be due to application command or an invalid state.
+ */
+#define RTE_FLOW_CONNTRACK_PKT_STATE_DISABLED RTE_BIT32(3)
+/**
+ * The packet contains some bad field(s) and cannot continue
+ * with the conntrack module checking.
+ */
+#define RTE_FLOW_CONNTRACK_PKT_STATE_BAD RTE_BIT32(4)
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change without prior notice
+ *
+ * RTE_FLOW_ITEM_TYPE_CONNTRACK
+ *
+ * Matches the state of a packet after it passed the connection tracking
+ * examination. The state is a bitmap of one RTE_FLOW_CONNTRACK_PKT_STATE*
+ * or a reasonable combination of these bits.
+ */
+struct rte_flow_item_conntrack {
+ uint32_t flags;
+};
+
+/** Default mask for RTE_FLOW_ITEM_TYPE_CONNTRACK. */
+#ifndef __cplusplus
+static const struct rte_flow_item_conntrack rte_flow_item_conntrack_mask = {
+ .flags = 0xffffffff,
+};
+#endif
+
/**
* Matching pattern item definition.
*
* or different ethdev ports.
*/
RTE_FLOW_ACTION_TYPE_INDIRECT,
+
+ /**
+ * [META]
+ *
+ * Enable tracking a TCP connection state.
+ *
+ * @see struct rte_flow_action_conntrack.
+ */
+ RTE_FLOW_ACTION_TYPE_CONNTRACK,
};
/**
*/
struct rte_flow_action_handle;
+/**
+ * The state of a TCP connection.
+ */
+enum rte_flow_conntrack_state {
+ /** SYN-ACK packet was seen. */
+ RTE_FLOW_CONNTRACK_STATE_SYN_RECV,
+ /** 3-way handshake was done. */
+ RTE_FLOW_CONNTRACK_STATE_ESTABLISHED,
+ /** First FIN packet was received to close the connection. */
+ RTE_FLOW_CONNTRACK_STATE_FIN_WAIT,
+ /** First FIN was ACKed. */
+ RTE_FLOW_CONNTRACK_STATE_CLOSE_WAIT,
+ /** Second FIN was received, waiting for the last ACK. */
+ RTE_FLOW_CONNTRACK_STATE_LAST_ACK,
+ /** Second FIN was ACKed, connection was closed. */
+ RTE_FLOW_CONNTRACK_STATE_TIME_WAIT,
+};
+
+/**
+ * The last passed TCP packet flags of a connection.
+ */
+enum rte_flow_conntrack_tcp_last_index {
+ RTE_FLOW_CONNTRACK_FLAG_NONE = 0, /**< No Flag. */
+ RTE_FLOW_CONNTRACK_FLAG_SYN = RTE_BIT32(0), /**< With SYN flag. */
+ RTE_FLOW_CONNTRACK_FLAG_SYNACK = RTE_BIT32(1), /**< With SYNACK flag. */
+ RTE_FLOW_CONNTRACK_FLAG_FIN = RTE_BIT32(2), /**< With FIN flag. */
+ RTE_FLOW_CONNTRACK_FLAG_ACK = RTE_BIT32(3), /**< With ACK flag. */
+ RTE_FLOW_CONNTRACK_FLAG_RST = RTE_BIT32(4), /**< With RST flag. */
+};
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change without prior notice
+ *
+ * Configuration parameters for each direction of a TCP connection.
+ * All fields should be in host byte order.
+ * If needed, driver should convert all fields to network byte order
+ * if HW needs them in that way.
+ */
+struct rte_flow_tcp_dir_param {
+ /** TCP window scaling factor, 0xF to disable. */
+ uint32_t scale:4;
+ /** The FIN was sent by this direction. */
+ uint32_t close_initiated:1;
+ /** An ACK packet has been received by this side. */
+ uint32_t last_ack_seen:1;
+ /**
+ * If set, it indicates that there is unacknowledged data for the
+ * packets sent from this direction.
+ */
+ uint32_t data_unacked:1;
+ /**
+ * Maximal value of sequence + payload length in sent
+ * packets (next ACK from the opposite direction).
+ */
+ uint32_t sent_end;
+ /**
+ * Maximal value of (ACK + window size) in received packet + length
+ * over sent packet (maximal sequence could be sent).
+ */
+ uint32_t reply_end;
+ /** Maximal value of actual window size in sent packets. */
+ uint32_t max_win;
+ /** Maximal value of ACK in sent packets. */
+ uint32_t max_ack;
+};
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change without prior notice
+ *
+ * RTE_FLOW_ACTION_TYPE_CONNTRACK
+ *
+ * Configuration and initial state for the connection tracking module.
+ * This structure could be used for both setting and query.
+ * All fields should be in host byte order.
+ */
+struct rte_flow_action_conntrack {
+ /** The peer port number, can be the same port. */
+ uint16_t peer_port;
+ /**
+ * Direction of this connection when creating a flow rule, the
+ * value only affects the creation of subsequent flow rules.
+ */
+ uint32_t is_original_dir:1;
+ /**
+ * Enable / disable the conntrack HW module. When disabled, the
+ * result will always be RTE_FLOW_CONNTRACK_FLAG_DISABLED.
+ * In this state the HW will act as passthrough.
+ * It only affects this conntrack object in the HW without any effect
+ * to the other objects.
+ */
+ uint32_t enable:1;
+ /** At least one ack was seen after the connection was established. */
+ uint32_t live_connection:1;
+ /** Enable selective ACK on this connection. */
+ uint32_t selective_ack:1;
+ /** A challenge ack has passed. */
+ uint32_t challenge_ack_passed:1;
+ /**
+ * 1: The last packet is seen from the original direction.
+ * 0: The last packet is seen from the reply direction.
+ */
+ uint32_t last_direction:1;
+ /** No TCP check will be done except the state change. */
+ uint32_t liberal_mode:1;
+ /**<The current state of this connection. */
+ enum rte_flow_conntrack_state state;
+ /** Scaling factor for maximal allowed ACK window. */
+ uint8_t max_ack_window;
+ /** Maximal allowed number of retransmission times. */
+ uint8_t retransmission_limit;
+ /** TCP parameters of the original direction. */
+ struct rte_flow_tcp_dir_param original_dir;
+ /** TCP parameters of the reply direction. */
+ struct rte_flow_tcp_dir_param reply_dir;
+ /** The window value of the last packet passed this conntrack. */
+ uint16_t last_window;
+ enum rte_flow_conntrack_tcp_last_index last_index;
+ /** The sequence of the last packet passed this conntrack. */
+ uint32_t last_seq;
+ /** The acknowledgment of the last packet passed this conntrack. */
+ uint32_t last_ack;
+ /**
+ * The total value ACK + payload length of the last packet
+ * passed this conntrack.
+ */
+ uint32_t last_end;
+};
+
+/**
+ * RTE_FLOW_ACTION_TYPE_CONNTRACK
+ *
+ * Wrapper structure for the context update interface.
+ * Ports cannot support updating, and the only valid solution is to
+ * destroy the old context and create a new one instead.
+ */
+struct rte_flow_modify_conntrack {
+ /** New connection tracking parameters to be updated. */
+ struct rte_flow_action_conntrack new_ct;
+ /** The direction field will be updated. */
+ uint32_t direction:1;
+ /** All the other fields except direction will be updated. */
+ uint32_t state:1;
+ /** Reserved bits for the future usage. */
+ uint32_t reserved:30;
+};
+
/**
* Field IDs for MODIFY_FIELD action.
*/