[v3,3/3] doc: update for conntrack
Checks
Commit Message
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 | 113 ++++++++++++++++++++
doc/guides/rel_notes/release_21_05.rst | 4 +
doc/guides/testpmd_app_ug/testpmd_funcs.rst | 35 ++++++
3 files changed, 152 insertions(+)
Comments
Doc should be added with the code.
16/04/2021 19:54, Bing Zhao:
> The updated documentations include:
> 1. Release notes
> 2. rte_flow.rst
1 & 2 can go in ethdev patch
> 3. testpmd user guide
3 can go in testpmd patch.
On Fri, Apr 16, 2021 at 10:54 AM Bing Zhao <bingz@nvidia.com> wrote:
>
> 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 | 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
s/stateful offloading/stateful offload of connections
> +participation. For example, only the control packets like SYN / FIN or packets
> +with invalid state should be handled by the software.
s/invalid state should be handled by the software/invalid state may be
handled by the software while the rest of the control frames may be
handled in hardware.
> +
> +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.
s/context creating/context creation.
s/depending on the HW./This capability will depend on the underlying hardware
> +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 |
s/for flow rule creating/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 |
s/times/limit
> + +--------------------------+-------------------------------------------------------------+
> + | ``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 |
s/value/size
> + +--------------------------+-------------------------------------------------------------+
> + | ``last_seq`` | sequence value of the last passed packet |
s/value/number
> + +--------------------------+-------------------------------------------------------------+
> + | ``last_ack`` | acknowledgement value the last passed packet |
s/value/number
> + +--------------------------+-------------------------------------------------------------+
> + | ``last_end`` | sum acknowledgement and length value the last passed packet |
sum of ack number and length of the last passed packet
or
sum of acknowledgement 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 will be updated |
except what?
direction??
> + +----------------+---------------------------------------+
> + | ``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
s/use/use the
> +rules like above for the peer port.
By peer, do you mean peer system? Or remote/dst port of the TCP connection?
> +
> +::
> +
> + testpmd> flow indirect_action 0 update 0 action conntrack_update dir / end
> +
> BPF Functions
> --------------
>
> --
> 2.19.0.windows.1
>
Hi Ajit,
> -----Original Message-----
> From: Ajit Khaparde <ajit.khaparde@broadcom.com>
> Sent: Saturday, April 17, 2021 2:30 AM
> To: Bing Zhao <bingz@nvidia.com>
> Cc: Ori Kam <orika@nvidia.com>; NBU-Contact-Thomas Monjalon
> <thomas@monjalon.net>; Ferruh Yigit <ferruh.yigit@intel.com>; Andrew
> Rybchenko <andrew.rybchenko@oktetlabs.ru>; dpdk-dev <dev@dpdk.org>;
> Xiaoyun Li <xiaoyun.li@intel.com>
> Subject: Re: [PATCH v3 3/3] doc: update for conntrack
>
> On Fri, Apr 16, 2021 at 10:54 AM Bing Zhao <bingz@nvidia.com> wrote:
> >
> > 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 | 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
> s/stateful offloading/stateful offload of connections
>
> > +participation. For example, only the control packets like SYN /
> FIN or packets
> > +with invalid state should be handled by the software.
> s/invalid state should be handled by the software/invalid state may
> be
> handled by the software while the rest of the control frames may be
> handled in hardware.
>
I updated this part, please take a review.
In general, the control packets could be handled by HW and SW could get
a state change state of the packet. The SW could also handle the control
packet if there is a flow rule for the state change.
> > +
> > +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.
> s/context creating/context creation.
> s/depending on the HW./This capability will depend on the underlying
> hardware
>
> > +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 |
> s/for flow rule creating/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
> |
> s/times/limit
>
> > + +--------------------------+----------------------------------
> ---------------------------+
> > + | ``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 |
> s/value/size
Done
>
> > + +--------------------------+----------------------------------
> ---------------------------+
> > + | ``last_seq`` | sequence value of the last passed
> packet |
> s/value/number
Agree, thanks
>
> > + +--------------------------+----------------------------------
> ---------------------------+
> > + | ``last_ack`` | acknowledgement value the last
> passed packet |
> s/value/number
Thanks
>
> > + +--------------------------+----------------------------------
> ---------------------------+
> > + | ``last_end`` | sum acknowledgement and length
> value the last passed packet |
> sum of ack number and length of the last passed packet
> or
> sum of acknowledgement number and length of the last passed packet
>
Updated, thanks. Also update the typo
> > + +--------------------------+----------------------------------
> ---------------------------+
> > +
> > +.. _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 |
> except what?
> direction??
Yes, missed this word, 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
> s/use/use the
>
> > +rules like above for the peer port.
> By peer, do you mean peer system? Or remote/dst port of the TCP
> connection?
The peer port of the conntrack. One conntrack context should only be used for
a bi-dir traffic from to same ethdev port or between a pair of ethdev ports.
>
> > +
> > +::
> > +
> > + testpmd> flow indirect_action 0 update 0 action conntrack_update
> dir / end
> > +
> > BPF Functions
> > --------------
> >
> > --
> > 2.19.0.windows.1
> >
@@ -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
~~~~~~~~~~~~~~
@@ -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.
@@ -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
--------------