[PATCH 0/2] doc: update offload API

[PATCH 0/2] doc: update offload API

[Olivier Matz]

Document the offload API and the testpmd commands related
to the checksum forward engine.

Olivier Matz (2):
  doc: update testpmd guide about csum forward engine
  doc: add a description of the offload API

 app/test-pmd/cmdline.c                      |  2 +-
 doc/guides/prog_guide/mbuf_lib.rst          | 89 +++++++++++++++++++++++++++++
 doc/guides/prog_guide/poll_mode_drv.rst     | 24 +++++---
 doc/guides/testpmd_app_ug/testpmd_funcs.rst | 53 +++++++++++++----
 4 files changed, 148 insertions(+), 20 deletions(-)

-- 
2.1.4

[PATCH 1/2] doc: update testpmd guide about csum forward engine

[Olivier Matz]

Document the functions introduced by commit 64fc36064d.

Signed-off-by: Olivier Matz <olivier.matz-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
---
 app/test-pmd/cmdline.c                      |  2 +-
 doc/guides/testpmd_app_ug/testpmd_funcs.rst | 53 +++++++++++++++++++++++------
 2 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/app/test-pmd/cmdline.c b/app/test-pmd/cmdline.c
index 604c3ec..e6107a0 100644
--- a/app/test-pmd/cmdline.c
+++ b/app/test-pmd/cmdline.c
@@ -317,7 +317,7 @@ static void cmd_help_long_parsed(void *parsed_result,
 
 			"csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id)\n"
 			"    Select hardware or software calculation of the"
-			" checksum with when transmitting a packet using the"
+			" checksum when transmitting a packet using the"
 			" csum forward engine.\n"
 			"    ip|udp|tcp|sctp always concern the inner layer.\n"
 			"    outer-ip concerns the outer IP layer in"
diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
index 4d430ff..b3abe9c 100644
--- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
+++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
@@ -505,28 +505,60 @@ Disable hardware insertion of a VLAN header in packets sent on a port:
 
 tx_vlan reset (port_id)
 
-tx_checksum set
-~~~~~~~~~~~~~~~
+csum set
+~~~~~~~~
 
 Select hardware or software calculation of the checksum when
 transmitting a packet using the csum forward engine:
 
-tx_cksum set (ip|udp|tcp|sctp|vxlan)
+csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id)
+
+- ip|udp|tcp|sctp always concern the inner layer.
 
-ip|udp|tcp|sctp always concern the inner layer.
-vxlan concerns the outer IP and UDP layer (in case the packet
-is recognized as a vxlan packet by the forward engine)
+- outer-ip concerns the outer IP layer in case the packet is recognized
+  as a tunnel packet by the forward engine (vxlan, gre and ipip are
+  supported). See "csum parse-tunnel" command.
 
 .. note::
 
     Check the NIC Datasheet for hardware limits.
 
-tx_checksum show
-~~~~~~~~~~~~~~~~
+csum parse-tunnel
+~~~~~~~~~~~~~~~~~
+
+Define how tunneled packets should be handled by the csum forward
+engine.
+
+csum parse-tunnel (on|off) (tx_port_id)
+
+If enabled, the csum forward engine will try to recognize supported
+tunnel headers (vxlan, gre, ipip).
+
+If disabled, treat tunnel packets as non-tunneled packets (a inner
+header is handled as a packet payload).
+
+.. note::
+
+   The port argument is the TX port like in the "csum set" command.
+
+Example:
+
+Consider a packet as following:
+"eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in"
+
+- If parse-tunnel is enabled, the ip|udp|tcp|sctp parameters of "csum
+  set" command are about inner headers (here ipv4_in and tcp_in), and the
+  outer-ip parameter is about outer headers (here ipv4_out).
+
+- If parse-tunnel is disabled, the ip|udp|tcp|sctp parameters of "csum
+  set" command are about outer headers, here ipv4_out and udp_out.
+
+csum show
+~~~~~~~~~
 
 Display tx checksum offload configuration:
 
-tx_checksum show (port_id)
+csum show (port_id)
 
 tso set
 ~~~~~~~
@@ -536,7 +568,8 @@ Enable TCP Segmentation Offload in csum forward engine:
 tso set (segsize) (port_id)
 
 .. note::
-   Please check the NIC datasheet for HW limits
+
+   Check the NIC datasheet for hardware limits
 
 tso show
 ~~~~~~~~
-- 
2.1.4

Re: [PATCH 1/2] doc: update testpmd guide about csum forward engine

[De Lara Guarch, Pablo]

> -----Original Message-----
> From: dev [mailto:dev-bounces-VfR2kkLFssw@public.gmane.org] On Behalf Of Olivier Matz
> Sent: Thursday, March 19, 2015 4:37 PM
> To: dev-VfR2kkLFssw@public.gmane.org
> Subject: [dpdk-dev] [PATCH 1/2] doc: update testpmd guide about csum
> forward engine
> 
> Document the functions introduced by commit 64fc36064d.
> 
> Signed-off-by: Olivier Matz <olivier.matz-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>

Acked-by: Pablo de Lara <pablo.de.lara.guarch-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

[PATCH 2/2] doc: add a description of the offload API

[Olivier Matz]

Signed-off-by: Olivier Matz <olivier.matz-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
---
 doc/guides/prog_guide/mbuf_lib.rst      | 89 +++++++++++++++++++++++++++++++++
 doc/guides/prog_guide/poll_mode_drv.rst | 24 +++++----
 2 files changed, 104 insertions(+), 9 deletions(-)

diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst
index 3d59e96..6e3b209 100644
--- a/doc/guides/prog_guide/mbuf_lib.rst
+++ b/doc/guides/prog_guide/mbuf_lib.rst
@@ -148,6 +148,95 @@ An mbuf also contains the input port (where it comes from), and the number of se
 
 For chained buffers, only the first mbuf of the chain stores this meta information.
 
+For instance, this is the case on RX side for the IEEE1588 packet
+timestamp mechanism, the VLAN tagging and the IP checksum computation.
+
+On TX side, it is also possible for an application to delegate some
+processing to the hardware if it supports it. For instance, the
+PKT_TX_IP_CKSUM flag allows to offload the computation of the IPv4
+checksum.
+
+The following examples explain how to configure different TX offloads on
+a vxlan-encapsulated tcp packet:
+``out_eth/out_ip/out_udp/vxlan/in_eth/in_ip/in_tcp/payload``
+
+- calculate checksum of out_ip::
+
+    mb->l2_len = len(out_eth)
+    mb->l3_len = len(out_ip)
+    mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM
+    set out_ip checksum to 0 in the packet
+
+  This is supported on hardwares advertising DEV_TX_OFFLOAD_IPV4_CKSUM.
+
+- calculate checksum of out_ip and out_udp::
+
+    mb->l2_len = len(out_eth)
+    mb->l3_len = len(out_ip)
+    mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM | PKT_TX_UDP_CKSUM
+    set out_ip checksum to 0 in the packet
+    set out_udp checksum to pseudo header using rte_ipv4_phdr_cksum()
+
+   This is supported on hardwares advertising DEV_TX_OFFLOAD_IPV4_CKSUM
+   and DEV_TX_OFFLOAD_UDP_CKSUM.
+
+- calculate checksum of in_ip::
+
+    mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
+    mb->l3_len = len(in_ip)
+    mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM
+    set in_ip checksum to 0 in the packet
+
+  This is similar to case 1), but l2_len is different. It is supported
+  on hardwares advertising DEV_TX_OFFLOAD_IPV4_CKSUM.
+  Note that it can only work if outer L4 checksum is 0.
+
+- calculate checksum of in_ip and in_tcp::
+
+    mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
+    mb->l3_len = len(in_ip)
+    mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM | PKT_TX_TCP_CKSUM
+    set in_ip checksum to 0 in the packet
+    set in_tcp checksum to pseudo header using rte_ipv4_phdr_cksum()
+
+  This is similar to case 2), but l2_len is different. It is supported
+  on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM and
+  DEV_TX_OFFLOAD_TCP_CKSUM.
+  Note that it can only work if outer L4 checksum is 0.
+
+- segment inner TCP::
+
+    mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth)
+    mb->l3_len = len(in_ip)
+    mb->l4_len = len(in_tcp)
+    mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CKSUM | PKT_TX_TCP_CKSUM |
+      PKT_TX_TCP_SEG;
+    set in_ip checksum to 0 in the packet
+    set in_tcp checksum to pseudo header without including the IP
+      payload length using rte_ipv4_phdr_cksum()
+
+  This is supported on hardware advertising DEV_TX_OFFLOAD_TCP_TSO.
+  Note that it can only work if outer L4 checksum is 0.
+
+- calculate checksum of out_ip, in_ip, in_tcp::
+
+    mb->outer_l2_len = len(out_eth)
+    mb->outer_l3_len = len(out_ip)
+    mb->l2_len = len(out_udp + vxlan + in_eth)
+    mb->l3_len = len(in_ip)
+    mb->ol_flags |= PKT_TX_OUTER_IPV4 | PKT_TX_OUTER_IP_CKSUM  | \
+      PKT_TX_IP_CKSUM |  PKT_TX_TCP_CKSUM;
+    set out_ip checksum to 0 in the packet
+    set in_ip checksum to 0 in the packet
+    set in_tcp checksum to pseudo header using rte_ipv4_phdr_cksum()
+
+   This is supported on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM,
+   DEV_TX_OFFLOAD_UDP_CKSUM and DEV_TX_OFFLOAD_OUTER_IPV4_CKSUM.
+
+The list of flags and their precise meaning is described in the mbuf API
+documentation (rte_mbuf.h). Also refer to the testpmd source code
+(specifically the csumonly.c file) for details.
+
 Direct and Indirect Buffers
 ---------------------------
 
diff --git a/doc/guides/prog_guide/poll_mode_drv.rst b/doc/guides/prog_guide/poll_mode_drv.rst
index e9e1132..7b9e7ca 100755
--- a/doc/guides/prog_guide/poll_mode_drv.rst
+++ b/doc/guides/prog_guide/poll_mode_drv.rst
@@ -198,15 +198,7 @@ the Intel® 82599 10 Gigabit Ethernet Controller controllers in the testpmd appl
 Other features such as the L3/L4 5-Tuple packet filtering feature of a port can be configured in the same way.
 Ethernet* flow control (pause frame) can be configured on the individual port.
 Refer to the testpmd source code for details.
-Also, L4 (UDP/TCP/ SCTP) checksum offload by the NIC can be enabled for an individual packet as long as the packet mbuf is set up correctly.
-In terms of UDP tunneling packet, the PKT_TX_UDP_TUNNEL_PKT flag must be set to enable tunneling packet TX checksum offload for both outer layer and inner layer.
-Refer to the testpmd source code (specifically the csumonly.c file) for details.
-
-That being said, the support of some offload features implies the addition of dedicated status bit(s) and value field(s) into the rte_mbuf
-data structure, along with their appropriate handling by the receive/transmit functions exported by each PMD.
-
-For instance, this is the case for the IEEE1588 packet timestamp mechanism, the VLAN tagging and the IP checksum computation, as described in
-the Section 7.6 "Meta Information".
+Also, L4 (UDP/TCP/ SCTP) checksum offload by the NIC can be enabled for an individual packet as long as the packet mbuf is set up correctly. See `Hardware Offload`_ for details.
 
 Configuration of Transmit and Receive Queues
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -257,6 +249,20 @@ One descriptor in the TX ring is used as a sentinel to avoid a hardware race con
 
     When configuring for DCB operation, at port initialization, both the number of transmit queues and the number of receive queues must be set to 128.
 
+Hardware Offload
+~~~~~~~~~~~~~~~~
+
+Depending on driver capabilities advertised by
+``rte_eth_dev_info_get()``, the PMD may support hardware offloading
+feature like checksumming, TCP segmentation or VLAN insertion.
+
+The support of these offload features implies the addition of dedicated
+status bit(s) and value field(s) into the rte_mbuf data structure, along
+with their appropriate handling by the receive/transmit functions
+exported by each PMD. The list of flags and their precise meaning is
+described in the mbuf API documentation and in the in :ref:`Mbuf Library
+<Mbuf_Library>`, section "Meta Information".
+
 Poll Mode Driver API
 --------------------
 
-- 
2.1.4

Re: [PATCH 0/2] doc: update offload API

[Thomas Monjalon]

> Document the offload API and the testpmd commands related
> to the checksum forward engine.
> 
> Olivier Matz (2):
>   doc: update testpmd guide about csum forward engine
>   doc: add a description of the offload API

Applied, thanks