doc: add description of the offload API

Signed-off-by: Olivier Matz <olivier.matz@6wind.com>

diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst
index 43e6f3a..8f546e0 100644 (file)
--- 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 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
 ---------------------------
 
 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 b8b2d1a..8780ba3 100644 (file)
--- 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.
 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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.
 
 
     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
 --------------------
 
 Poll Mode Driver API
 --------------------