1.. SPDX-License-Identifier: GPL-2.0 2 3===================== 4Segmentation Offloads 5===================== 6 7 8Introduction 9============ 10 11This document describes a set of techniques in the Linux networking stack 12to take advantage of segmentation offload capabilities of various NICs. 13 14The following technologies are described: 15 * TCP Segmentation Offload - TSO 16 * UDP Fragmentation Offload - UFO 17 * IPIP, SIT, GRE, and UDP Tunnel Offloads 18 * Generic Segmentation Offload - GSO 19 * Generic Receive Offload - GRO 20 * Partial Generic Segmentation Offload - GSO_PARTIAL 21 * SCTP acceleration with GSO - GSO_BY_FRAGS 22 23 24TCP Segmentation Offload 25======================== 26 27TCP segmentation allows a device to segment a single frame into multiple 28frames with a data payload size specified in skb_shinfo()->gso_size. 29When TCP segmentation requested the bit for either SKB_GSO_TCPV4 or 30SKB_GSO_TCPV6 should be set in skb_shinfo()->gso_type and 31skb_shinfo()->gso_size should be set to a non-zero value. 32 33TCP segmentation is dependent on support for the use of partial checksum 34offload. For this reason TSO is normally disabled if the Tx checksum 35offload for a given device is disabled. 36 37In order to support TCP segmentation offload it is necessary to populate 38the network and transport header offsets of the skbuff so that the device 39drivers will be able determine the offsets of the IP or IPv6 header and the 40TCP header. In addition as CHECKSUM_PARTIAL is required csum_start should 41also point to the TCP header of the packet. 42 43For IPv4 segmentation we support one of two types in terms of the IP ID. 44The default behavior is to increment the IP ID with every segment. If the 45GSO type SKB_GSO_TCP_FIXEDID is specified then we will not increment the IP 46ID and all segments will use the same IP ID. 47 48For encapsulated packets, SKB_GSO_TCP_FIXEDID refers only to the outer header. 49SKB_GSO_TCP_FIXEDID_INNER can be used to specify the same for the inner header. 50Any combination of these two GSO types is allowed. 51 52If a device has NETIF_F_TSO_MANGLEID set then the IP ID can be ignored when 53performing TSO and we will either increment the IP ID for all frames, or leave 54it at a static value based on driver preference. For encapsulated packets, 55NETIF_F_TSO_MANGLEID is relevant for both outer and inner headers, unless the 56DF bit is not set on the outer header, in which case the device driver must 57guarantee that the IP ID field is incremented in the outer header with every 58segment. 59 60 61UDP Fragmentation Offload 62========================= 63 64UDP fragmentation offload allows a device to fragment an oversized UDP 65datagram into multiple IPv4 fragments. Many of the requirements for UDP 66fragmentation offload are the same as TSO. However the IPv4 ID for 67fragments should not increment as a single IPv4 datagram is fragmented. 68 69UFO is deprecated: modern kernels will no longer generate UFO skbs, but can 70still receive them from tuntap and similar devices. Offload of UDP-based 71tunnel protocols is still supported. 72 73 74IPIP, SIT, GRE, UDP Tunnel, and Remote Checksum Offloads 75======================================================== 76 77In addition to the offloads described above it is possible for a frame to 78contain additional headers such as an outer tunnel. In order to account 79for such instances an additional set of segmentation offload types were 80introduced including SKB_GSO_IPXIP4, SKB_GSO_IPXIP6, SKB_GSO_GRE, and 81SKB_GSO_UDP_TUNNEL. These extra segmentation types are used to identify 82cases where there are more than just 1 set of headers. For example in the 83case of IPIP and SIT we should have the network and transport headers moved 84from the standard list of headers to "inner" header offsets. 85 86Currently only two levels of headers are supported. The convention is to 87refer to the tunnel headers as the outer headers, while the encapsulated 88data is normally referred to as the inner headers. Below is the list of 89calls to access the given headers: 90 91IPIP/SIT Tunnel:: 92 93 Outer Inner 94 MAC skb_mac_header 95 Network skb_network_header skb_inner_network_header 96 Transport skb_transport_header 97 98UDP/GRE Tunnel:: 99 100 Outer Inner 101 MAC skb_mac_header skb_inner_mac_header 102 Network skb_network_header skb_inner_network_header 103 Transport skb_transport_header skb_inner_transport_header 104 105In addition to the above tunnel types there are also SKB_GSO_GRE_CSUM and 106SKB_GSO_UDP_TUNNEL_CSUM. These two additional tunnel types reflect the 107fact that the outer header also requests to have a non-zero checksum 108included in the outer header. 109 110Finally there is SKB_GSO_TUNNEL_REMCSUM which indicates that a given tunnel 111header has requested a remote checksum offload. In this case the inner 112headers will be left with a partial checksum and only the outer header 113checksum will be computed. 114 115 116Generic Segmentation Offload 117============================ 118 119Generic segmentation offload is a pure software offload that is meant to 120deal with cases where device drivers cannot perform the offloads described 121above. What occurs in GSO is that a given skbuff will have its data broken 122out over multiple skbuffs that have been resized to match the MSS provided 123via skb_shinfo()->gso_size. 124 125Before enabling any hardware segmentation offload a corresponding software 126offload is required in GSO. Otherwise it becomes possible for a frame to 127be re-routed between devices and end up being unable to be transmitted. 128 129 130Generic Receive Offload 131======================= 132 133Generic receive offload is the complement to GSO. Ideally any frame 134assembled by GRO should be segmented to create an identical sequence of 135frames using GSO, and any sequence of frames segmented by GSO should be 136able to be reassembled back to the original by GRO. 137 138 139Partial Generic Segmentation Offload 140==================================== 141 142Partial generic segmentation offload is a hybrid between TSO and GSO. What 143it effectively does is take advantage of certain traits of TCP and tunnels 144so that instead of having to rewrite the packet headers for each segment 145only the inner-most transport header and possibly the outer-most network 146header need to be updated. This allows devices that do not support tunnel 147offloads or tunnel offloads with checksum to still make use of segmentation. 148 149With the partial offload what occurs is that all headers excluding the 150inner transport header are updated such that they will contain the correct 151values for if the header was simply duplicated. The one exception to this 152is the outer IPv4 ID field. It is up to the device drivers to guarantee 153that the IPv4 ID field is incremented in the case that a given header does 154not have the DF bit set. 155 156 157SCTP acceleration with GSO 158=========================== 159 160SCTP - despite the lack of hardware support - can still take advantage of 161GSO to pass one large packet through the network stack, rather than 162multiple small packets. 163 164This requires a different approach to other offloads, as SCTP packets 165cannot be just segmented to (P)MTU. Rather, the chunks must be contained in 166IP segments, padding respected. So unlike regular GSO, SCTP can't just 167generate a big skb, set gso_size to the fragmentation point and deliver it 168to IP layer. 169 170Instead, the SCTP protocol layer builds an skb with the segments correctly 171padded and stored as chained skbs, and skb_segment() splits based on those. 172To signal this, gso_size is set to the special value GSO_BY_FRAGS. 173 174Therefore, any code in the core networking stack must be aware of the 175possibility that gso_size will be GSO_BY_FRAGS and handle that case 176appropriately. 177 178There are some helpers to make this easier: 179 180- skb_is_gso(skb) && skb_is_gso_sctp(skb) is the best way to see if 181 an skb is an SCTP GSO skb. 182 183- For size checks, the skb_gso_validate_*_len family of helpers correctly 184 considers GSO_BY_FRAGS. 185 186- For manipulating packets, skb_increase_gso_size and skb_decrease_gso_size 187 will check for GSO_BY_FRAGS and WARN if asked to manipulate these skbs. 188 189This also affects drivers with the NETIF_F_FRAGLIST & NETIF_F_GSO_SCTP bits 190set. Note also that NETIF_F_GSO_SCTP is included in NETIF_F_GSO_SOFTWARE. 191