From: Olivier Matz Date: Thu, 19 Mar 2015 16:36:38 +0000 (+0100) Subject: doc: add description of the offload API X-Git-Tag: spdx-start~9357 X-Git-Url: http://git.droids-corp.org/?a=commitdiff_plain;h=2542ad53d8676fdadc14f88ca8bef5bf68a2a606;p=dpdk.git doc: add description of the offload API Signed-off-by: Olivier Matz --- diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst index 43e6f3a90e..8f546e0fac 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 b8b2d1aafa..8780ba30b6 100644 --- 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 +`, section "Meta Information". + Poll Mode Driver API --------------------