Subject: [tsvwg] UDP Options and Checksum Offload

From: "C. M. Heard" <[email-masked]>
Date: Sat, 26 Mar 2022 16:32:45 -0700

TSVWG,

Gorry stated that he asked Tom Herbert for the Checksum Offload
presentation at yesterday's TSVWG session in part because this is an
interesting and useful background particularly for UDP Options. My
conclusion, after attending the presentation and looking at some of the
reference material that Tom has provided in the past, is that the design of
UDP Options as represented by the current draft presents should generally
play well with protocol-agnostic checksum offload because of the of
checksum compensation property of OCS and the fact that it MUST be present
if UDP CS != 0. To make the case, I'll briefly summarize how both TX and RX
checksum offload would work with UDP options.

The interface to the hardware that supports protocol-agnostic TX checksum
offload requires specification of two parameters:

1. The offset within the packet buffer where the checksum calculation
begins; and
2. The offset within the packet buffer where the calculated checksum will
be inserted.

Both of these must be (at least) 16-bit aligned and may be limited to what
will fit in an 8-bit register (thus, 256 or possibly 512 bytes). The
hardware computes the 1's complement sum of all of the 16-bit bit words
starting from the specified beginning offset all the way to the end of the
packet buffer. The 1's complement of that value (with zero values always
represented as 0xFFFF) is then inserted in the specified 16-bit word,
overwriting the previous contents.

In the case where the UDP length is sufficiently large that OCS cannot be
inserted by the offload hardware, the OCS is calculated by the CPU and
placed in the packet before handoff to the hardware. If UDP CS is not used,
it is set to zero and checksum offload is disabled. Otherwise, the UDP
pseudo-header is stored in the UDP checksum field and checksum offload is
enabled. The offset of the UDP header is where the checksum calculation
begins, and the offset of the UDP checksum is where the checksum is
inserted. This works because OCS, by having a pseudo-header equal to the
surplus area length, is designed to ensure that both the UDP checksum
calculated in the standard way and the UDP checksum with the IP Payload
Length substituted for the UDP Length result in a 1's complement zero.

In the case where the UDP length is sufficiently small to allow OCS to be
inserted by the offload hardware and either UDP CS == 0 or the UDP length
is less than the surplus area length, the procedure is reversed: the CPU
computes the UDP checksum (or inserts zero), and OCS (if used) is computed
by the offload hardware. When offload is used to compute OCS, the OCS field
is populated with the surplus area length before the calculation; the
starting offset is the start of the surplus area; and the offset of OCS
(which is also the start of the surplus area) is where the checksum is
inserted. This case applies to UDP fragments.

In both of the above cases, the CPU does have to calculate one of the
checksums if both are enabled, but the one that is more work for the CPU is
handled by the offload hardware. In the usual cases when the surplus area
is small, or when the packet is a UDP fragment, the CPU has only a small
amount of work.

The hardware that supports protocol-agnostic RX checksum offload simply
computes the 1s-complement sum of all 16-bit words in the packet buffer and
reports the value as part of the received packet metadata. The CPU must
then subtract out the Internet checksum of any protocol headers that
precede the UDP header, as shown on Slide #18 of Tom's presentation. The
resulting value is called the adjusted hardware checksum.

In the case where the UDP length is greater than or equal to the surplus
area length, or when UDP CS == 0, the procedure is similar to that shown in
Tom's Slide #18: the surplus area checksum is calculated and checked to see
if it is equal to the 1s-complement of the surplus area length. If not, the
surplus area is ignored; otherwise, it contains options that need to be
processed in subsequent steps. The surplus area checksum is then subtracted
from the adjusted hardware checksum. If that result is equal to the
1s-complement of the UDP pseudo-header, or if UDP CS == 0, then the UDP
data is valid; otherwise, the entire UDP datagram and any options are
discarded.

In the case where the UDP length is less than the surplus area length, the
CPU computes the checksum of the UDP header and data up to the limit
indicated by UDP length. If UDP CS != 0 and the calculated checksum is not
equal to the 1s-complement of the UDP pseudo-header, then the packet is
discarded. Otherwise, the calculated checksum is subtracted from the
adjusted hardware checksum; if the result is equal to the 1s-complement of
the surplus area length, then the surplus area contains options that need
to be processed in subsequent steps, otherwise it is discarded.

As before, the CPU has only a small amount of work in the usual cases when
the surplus area is small or when the packet is a UDP fragment.

Mike Heard