diff mbox series

[v4,3/3] doc: update for conntrack

Message ID 1618852616-369498-4-git-send-email-bingz@nvidia.com (mailing list archive)
State Superseded
Delegated to: Ferruh Yigit
Headers show
Series ethdev: introduce conntrack flow action and item | expand

Checks

Context Check Description
ci/Intel-compilation fail apply issues
ci/checkpatch success coding style OK

Commit Message

Bing Zhao April 19, 2021, 5:16 p.m. UTC
The updated documentations include:
  1. Release notes
  2. rte_flow.rst
  3. testpmd user guide

Signed-off-by: Bing Zhao <bingz@nvidia.com>
---
 doc/guides/prog_guide/rte_flow.rst          | 118 ++++++++++++++++++++
 doc/guides/rel_notes/release_21_05.rst      |   4 +
 doc/guides/testpmd_app_ug/testpmd_funcs.rst |  35 ++++++
 3 files changed, 157 insertions(+)

Comments

Thomas Monjalon April 19, 2021, 5:32 p.m. UTC | #1
19/04/2021 19:16, Bing Zhao:
> The updated documentations include:
>   1. Release notes
>   2. rte_flow.rst
>   3. testpmd user guide

We need a v5 with doc squashed in previous patches.
Release notes should go with ethdev patch.
> --- a/doc/guides/rel_notes/release_21_05.rst
> +++ b/doc/guides/rel_notes/release_21_05.rst
> @@ -203,6 +203,10 @@ New Features
>      the events across multiple stages.
>    * This also reduced the scheduling overhead on a event device.
>  
> +* **Added conntrack support for rte_flow.**

Suggested headline:
Added TCP connection tracking offload in flow API.

> +
> +  * Added conntrack action and item for stateful offloading.

It should be moved above with other ethdev features.
Ori Kam April 19, 2021, 5:37 p.m. UTC | #2
Hi Bing

I think that this patch should be merged  to the two previous patches.

Except this,
Acked-by: Ori Kam <orika@nvidia.com>
Thanks,
Ori

> -----Original Message-----
> From: Bing Zhao <bingz@nvidia.com>
> Sent: Monday, April 19, 2021 8:17 PM
> Subject: [PATCH v4 3/3] doc: update for conntrack
> 
> The updated documentations include:
>   1. Release notes
>   2. rte_flow.rst
>   3. testpmd user guide
> 
> Signed-off-by: Bing Zhao <bingz@nvidia.com>
> ---
>  doc/guides/prog_guide/rte_flow.rst          | 118 ++++++++++++++++++++
>  doc/guides/rel_notes/release_21_05.rst      |   4 +
>  doc/guides/testpmd_app_ug/testpmd_funcs.rst |  35 ++++++
>  3 files changed, 157 insertions(+)
> 
> diff --git a/doc/guides/prog_guide/rte_flow.rst
> b/doc/guides/prog_guide/rte_flow.rst
> index 4b54588995..caabc49143 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,116 @@ 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 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 value of the last passed packet
> |
> +   +--------------------------+-------------------------------------------------------------+
> +   | ``last_seq``             | sequence value of the last passed packet                    |
> +   +--------------------------+-------------------------------------------------------------+
> +   | ``last_ack``             | acknowledgment value 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
>  ~~~~~~~~~~~~~~
> 
> diff --git a/doc/guides/rel_notes/release_21_05.rst
> b/doc/guides/rel_notes/release_21_05.rst
> index 8913dd4f9c..fb978aebe3 100644
> --- a/doc/guides/rel_notes/release_21_05.rst
> +++ b/doc/guides/rel_notes/release_21_05.rst
> @@ -203,6 +203,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 715e209fd2..efa32bb6ad 100644
> --- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
> +++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
> @@ -3789,6 +3789,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
>  ^^^^^^^^^^^^
> 
> @@ -4927,6 +4929,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
diff mbox series

Patch

diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 4b54588995..caabc49143 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,116 @@  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 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 value of the last passed packet                      |
+   +--------------------------+-------------------------------------------------------------+
+   | ``last_seq``             | sequence value of the last passed packet                    |
+   +--------------------------+-------------------------------------------------------------+
+   | ``last_ack``             | acknowledgment value 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
 ~~~~~~~~~~~~~~
 
diff --git a/doc/guides/rel_notes/release_21_05.rst b/doc/guides/rel_notes/release_21_05.rst
index 8913dd4f9c..fb978aebe3 100644
--- a/doc/guides/rel_notes/release_21_05.rst
+++ b/doc/guides/rel_notes/release_21_05.rst
@@ -203,6 +203,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 715e209fd2..efa32bb6ad 100644
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -3789,6 +3789,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
 ^^^^^^^^^^^^
 
@@ -4927,6 +4929,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
 --------------