doc: add description of the offload API

[dpdk.git] / doc / guides / prog_guide / mbuf_lib.rst

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
 ---------------------------