Documentation/networking/checksum-offloads.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/checksum-offloads.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/checksum-offloads.rst
Extension
.rst
Size
6805 bytes
Lines
159
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

=================
Checksum Offloads
=================


Introduction
============

This document describes a set of techniques in the Linux networking stack to
take advantage of checksum offload capabilities of various NICs.

The following technologies are described:

* TX Checksum Offload
* LCO: Local Checksum Offload
* RCO: Remote Checksum Offload

Things that should be documented here but aren't yet:

* CHECKSUM_UNNECESSARY conversion


TX Checksum Offload
===================

In brief, Tx checksum offload allows to request the device fill in a single
ones-complement
checksum defined by the sk_buff fields skb->csum_start and skb->csum_offset.
The device should compute the 16-bit ones-complement checksum (i.e. the
'IP-style' checksum) from csum_start to the end of the packet, and fill in the
result at (csum_start + csum_offset).

Because csum_offset cannot be negative, this ensures that the previous value of
the checksum field is included in the checksum computation, thus it can be used
to supply any needed corrections to the checksum (such as the sum of the
pseudo-header for UDP or TCP).

This interface only allows a single checksum to be offloaded.  Where
encapsulation is used, the packet may have multiple checksum fields in
different header layers, and the rest will have to be handled by another
mechanism such as LCO or RCO.

SCTP CRC32c can also be offloaded using this interface, by means of filling
skb->csum_start and skb->csum_offset as described above, setting
skb->csum_not_inet, and advertising NETIF_F_SCTP_CRC. Drivers must not treat
ordinary IP checksum offload as SCTP CRC32c support.

No offloading of the IP header checksum is performed; it is always done in
software.  This is OK because when we build the IP header, we obviously have it
in cache, so summing it isn't expensive.  It's also rather short.

The requirements for GSO are more complicated, because when segmenting an
encapsulated packet both the inner and outer checksums may need to be edited or
recomputed for each resulting segment.

A driver declares its offload capabilities in netdev->hw_features; see
Documentation/networking/netdev-features.rst for more. NETIF_F_IP_CSUM and
NETIF_F_IPV6_CSUM are restricted legacy features and are being deprecated in
favor of NETIF_F_HW_CSUM. New devices should use NETIF_F_HW_CSUM to advertise
generic checksum offload. The skb_csum_hwoffload_help() helper can resolve
CHECKSUM_PARTIAL according to the device's advertised checksum capabilities,
falling back to software when needed.

The stack should, for the most part, assume that checksum offload is supported
by the underlying device.  The only place that should check is
validate_xmit_skb(), and the functions it calls directly or indirectly.  That
function compares the offload features requested by the SKB (which may include
other offloads besides TX Checksum Offload) and, if they are not supported or

Annotation

Implementation Notes