summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOlivier Matz <olivier.matz@6wind.com>2015-03-19 17:36:38 +0100
committerThomas Monjalon <thomas.monjalon@6wind.com>2015-03-31 02:55:07 +0200
commit2542ad53d8676fdadc14f88ca8bef5bf68a2a606 (patch)
treee0aa69771ea8f9039179a43f72c3fab67263c3b7
parentc22f2fee1677afa05f78513c89480839d9e1dcfb (diff)
downloaddpdk-2542ad53d8676fdadc14f88ca8bef5bf68a2a606.zip
dpdk-2542ad53d8676fdadc14f88ca8bef5bf68a2a606.tar.gz
dpdk-2542ad53d8676fdadc14f88ca8bef5bf68a2a606.tar.xz
doc: add description of the offload API
Signed-off-by: Olivier Matz <olivier.matz@6wind.com>
-rw-r--r--doc/guides/prog_guide/mbuf_lib.rst89
-rw-r--r--doc/guides/prog_guide/poll_mode_drv.rst24
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 43e6f3a..8f546e0 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 b8b2d1a..8780ba3 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
+<Mbuf_Library>`, section "Meta Information".
+
Poll Mode Driver API
--------------------