The updated documentations include:
1. Release notes
2. rte_flow.rst
3. testpmd user guide
Signed-off-by: Bing Zhao <bi...@nvidia.com>
---
doc/guides/prog_guide/rte_flow.rst | 113 ++++++++++++++++++++
doc/guides/rel_notes/release_21_05.rst | 4 +
doc/guides/testpmd_app_ug/testpmd_funcs.rst | 35 ++++++
3 files changed, 152 insertions(+)
diff --git a/doc/guides/prog_guide/rte_flow.rst
b/doc/guides/prog_guide/rte_flow.rst
index 2ecc48cfff..a1333819fc 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -1398,6 +1398,14 @@ Matches a eCPRI header.
- ``hdr``: eCPRI header definition (``rte_ecpri.h``).
- Default ``mask`` matches nothing, for all eCPRI messages.
+Item: ``CONNTRACK``
+^^^^^^^^^^^^^^^^^^^
+
+Matches a conntrack state after conntrack action.
+
+- ``flags``: conntrack packet state flags.
+- Default ``mask`` matches all state bits.
+
Actions
~~~~~~~
@@ -2842,6 +2850,111 @@ for ``RTE_FLOW_FIELD_VALUE`` and
``RTE_FLOW_FIELD_POINTER`` respectively.
| ``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 offloading with little software
+participation. For example, only the control packets like SYN / FIN or packets
+with invalid state should be handled by the software.
+
+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.
+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 flow rule
creating |
+
+--------------------------+-------------------------------------------------------------+
+ | ``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 value of the last passed packet
|
+
+--------------------------+-------------------------------------------------------------+
+ | ``last_seq`` | sequence value of the last passed packet
|
+
+--------------------------+-------------------------------------------------------------+
+ | ``last_ack`` | acknowledgement value the last passed packet
|
+
+--------------------------+-------------------------------------------------------------+
+ | ``last_end`` | sum acknowledgement and length value 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 will be updated |
+ +----------------+---------------------------------------+
+ | ``reserved`` | reserved bits |
+ +----------------+---------------------------------------+
+
Negative types
~~~~~~~~~~~~~~
diff --git a/doc/guides/rel_notes/release_21_05.rst
b/doc/guides/rel_notes/release_21_05.rst
index e6f99350af..824eb72981 100644
--- a/doc/guides/rel_notes/release_21_05.rst
+++ b/doc/guides/rel_notes/release_21_05.rst
@@ -183,6 +183,10 @@ New Features
the events across multiple stages.
* This also reduced the scheduling overhead on a event device.
+* **Added conntrack support for rte_flow.**
+
+ * Added conntrack action and item for stateful offloading.
+
* **Updated testpmd.**
* Added a command line option to configure forced speed for Ethernet port.
diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
index 1fa6e2000e..4c029776aa 100644
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -3791,6 +3791,8 @@ This section lists supported pattern items and their
attributes, if any.
- ``s_field {unsigned}``: S field.
- ``seid {unsigned}``: session endpoint identifier.
+- ``conntrack``: match conntrack state.
+
Actions list
^^^^^^^^^^^^
@@ -4925,6 +4927,39 @@ NVGRE encapsulation header and sent to port id 0.
testpmd> flow create 0 ingress transfer pattern eth / end actions
sample ratio 1 index 0 / port_id id 2 / end
+Sample conntrack rules
+~~~~~~~~~~~~~~~~~~~~~~
+
+Conntrack rules can be set by the following commands
+
+Need to construct the connection context with provided information.
+In the first table, create a flow rule by using conntrack action and jump to
+the next table. In the next table, create a rule to check the state.
+
+::
+
+ testpmd> set conntrack com peer 1 is_orig 1 enable 1 live 1 sack 1 cack 0
+ last_dir 0 liberal 0 state 1 max_ack_win 7 r_lim 5 last_win 510
+ last_seq 2632987379 last_ack 2532480967 last_end 2632987379
+ last_index 0x8
+ testpmd> set conntrack orig scale 7 fin 0 acked 1 unack_data 0
+ sent_end 2632987379 reply_end 2633016339 max_win 28960
+ max_ack 2632987379
+ testpmd> set conntrack rply scale 7 fin 0 acked 1 unack_data 0
+ sent_end 2532480967 reply_end 2532546247 max_win 65280
+ max_ack 2532480967
+ testpmd> flow indirect_action 0 create ingress action conntrack / end
+ testpmd> flow create 0 group 3 ingress pattern eth / ipv4 / tcp / end actions
indirect 0 / jump group 5 / end
+ testpmd> flow create 0 group 5 ingress pattern eth / ipv4 / tcp / conntrack
is 1 / end actions queue index 5 / end
+
+Construct the conntrack again with only "is_orig" set to 0 (other fields are
+ignored), then use "update" interface to update the direction. Create flow
+rules like above for the peer port.
+
+::
+
+ testpmd> flow indirect_action 0 update 0 action conntrack_update dir / end
+
BPF Functions
--------------
--
2.19.0.windows.1
