Documentation/networking/segmentation-offloads.txt

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