1Segmentation Offloads in the Linux Networking Stack
  2
  3Introduction
  4============
  5
  6This document describes a set of techniques in the Linux networking stack
  7to take advantage of segmentation offload capabilities of various NICs.
  8
  9The following technologies are described:
 10 * TCP Segmentation Offload - TSO
 11 * UDP Fragmentation Offload - UFO
 12 * IPIP, SIT, GRE, and UDP Tunnel Offloads
 13 * Generic Segmentation Offload - GSO
 14 * Generic Receive Offload - GRO
 15 * Partial Generic Segmentation Offload - GSO_PARTIAL
 16
 17TCP Segmentation Offload
 18========================
 19
 20TCP segmentation allows a device to segment a single frame into multiple
 21frames with a data payload size specified in skb_shinfo()->gso_size.
 22When TCP segmentation requested the bit for either SKB_GSO_TCP or
 23SKB_GSO_TCP6 should be set in skb_shinfo()->gso_type and
 24skb_shinfo()->gso_size should be set to a non-zero value.
 25
 26TCP segmentation is dependent on support for the use of partial checksum
 27offload.  For this reason TSO is normally disabled if the Tx checksum
 28offload for a given device is disabled.
 29
 30In order to support TCP segmentation offload it is necessary to populate
 31the network and transport header offsets of the skbuff so that the device
 32drivers will be able determine the offsets of the IP or IPv6 header and the
 33TCP header.  In addition as CHECKSUM_PARTIAL is required csum_start should
 34also point to the TCP header of the packet.
 35
 36For IPv4 segmentation we support one of two types in terms of the IP ID.
 37The default behavior is to increment the IP ID with every segment.  If the
 38GSO type SKB_GSO_TCP_FIXEDID is specified then we will not increment the IP
 39ID and all segments will use the same IP ID.  If a device has
 40NETIF_F_TSO_MANGLEID set then the IP ID can be ignored when performing TSO
 41and we will either increment the IP ID for all frames, or leave it at a
 42static value based on driver preference.
 43
 44UDP Fragmentation Offload
 45=========================
 46
 47UDP fragmentation offload allows a device to fragment an oversized UDP
 48datagram into multiple IPv4 fragments.  Many of the requirements for UDP
 49fragmentation offload are the same as TSO.  However the IPv4 ID for
 50fragments should not increment as a single IPv4 datagram is fragmented.
 51
 52IPIP, SIT, GRE, UDP Tunnel, and Remote Checksum Offloads
 53========================================================
 54
 55In addition to the offloads described above it is possible for a frame to
 56contain additional headers such as an outer tunnel.  In order to account
 57for such instances an additional set of segmentation offload types were
 58introduced including SKB_GSO_IPIP, SKB_GSO_SIT, SKB_GSO_GRE, and
 59SKB_GSO_UDP_TUNNEL.  These extra segmentation types are used to identify
 60cases where there are more than just 1 set of headers.  For example in the
 61case of IPIP and SIT we should have the network and transport headers moved
 62from the standard list of headers to "inner" header offsets.
 63
 64Currently only two levels of headers are supported.  The convention is to
 65refer to the tunnel headers as the outer headers, while the encapsulated
 66data is normally referred to as the inner headers.  Below is the list of
 67calls to access the given headers:
 68
 69IPIP/SIT Tunnel:
 70		Outer			Inner
 71MAC		skb_mac_header
 72Network		skb_network_header	skb_inner_network_header
 73Transport	skb_transport_header
 74
 75UDP/GRE Tunnel:
 76		Outer			Inner
 77MAC		skb_mac_header		skb_inner_mac_header
 78Network		skb_network_header	skb_inner_network_header
 79Transport	skb_transport_header	skb_inner_transport_header
 80
 81In addition to the above tunnel types there are also SKB_GSO_GRE_CSUM and
 82SKB_GSO_UDP_TUNNEL_CSUM.  These two additional tunnel types reflect the
 83fact that the outer header also requests to have a non-zero checksum
 84included in the outer header.
 85
 86Finally there is SKB_GSO_REMCSUM which indicates that a given tunnel header
 87has requested a remote checksum offload.  In this case the inner headers
 88will be left with a partial checksum and only the outer header checksum
 89will be computed.
 90
 91Generic Segmentation Offload
 92============================
 93
 94Generic segmentation offload is a pure software offload that is meant to
 95deal with cases where device drivers cannot perform the offloads described
 96above.  What occurs in GSO is that a given skbuff will have its data broken
 97out over multiple skbuffs that have been resized to match the MSS provided
 98via skb_shinfo()->gso_size.
 99
100Before enabling any hardware segmentation offload a corresponding software
101offload is required in GSO.  Otherwise it becomes possible for a frame to
102be re-routed between devices and end up being unable to be transmitted.
103
104Generic Receive Offload
105=======================
106
107Generic receive offload is the complement to GSO.  Ideally any frame
108assembled by GRO should be segmented to create an identical sequence of
109frames using GSO, and any sequence of frames segmented by GSO should be
110able to be reassembled back to the original by GRO.  The only exception to
111this is IPv4 ID in the case that the DF bit is set for a given IP header.
112If the value of the IPv4 ID is not sequentially incrementing it will be
113altered so that it is when a frame assembled via GRO is segmented via GSO.
114
115Partial Generic Segmentation Offload
116====================================
117
118Partial generic segmentation offload is a hybrid between TSO and GSO.  What
119it effectively does is take advantage of certain traits of TCP and tunnels
120so that instead of having to rewrite the packet headers for each segment
121only the inner-most transport header and possibly the outer-most network
122header need to be updated.  This allows devices that do not support tunnel
123offloads or tunnel offloads with checksum to still make use of segmentation.
124
125With the partial offload what occurs is that all headers excluding the
126inner transport header are updated such that they will contain the correct
127values for if the header was simply duplicated.  The one exception to this
128is the outer IPv4 ID field.  It is up to the device drivers to guarantee
129that the IPv4 ID field is incremented in the case that a given header does
130not have the DF bit set.