From 5c2a5607e52b15b69d0163b8f33b6afbf5d1341b Mon Sep 17 00:00:00 2001 From: JackDoan Date: Tue, 28 Jul 2026 14:56:51 -0500 Subject: [PATCH] unslop a bit --- overlay/tio/tio.go | 115 ++++++++++++++++++--------------------------- 1 file changed, 47 insertions(+), 68 deletions(-) diff --git a/overlay/tio/tio.go b/overlay/tio/tio.go index 5be6df9d..cac45617 100644 --- a/overlay/tio/tio.go +++ b/overlay/tio/tio.go @@ -13,33 +13,28 @@ type QueueSet interface { Add(fd int) error } -// Capabilities advertises which kernel offload features a Queue -// successfully negotiated. Callers consult this to decide which coalescers -// to wire onto the write path — a Queue without TSO can't usefully accept a -// TCPCoalescer, and a Queue without USO can't accept a UDPCoalescer. +// Capabilities advertises which kernel offload features a Queue successfully negotiated. +// Callers consult this to decide which coalescers to wire onto the write path. type Capabilities struct { - // TSO means the FD was opened with IFF_VNET_HDR and the kernel agreed - // to TUN_F_TSO4|TSO6 — i.e. WriteGSO with GSOProtoTCP is safe. + // TSO means the FD was opened with IFF_VNET_HDR and the kernel agreed to TUN_F_TSO4|TSO6, + // and WriteGSO with GSOProtoTCP is safe. TSO bool - // USO means the kernel additionally agreed to TUN_F_USO4|USO6, so - // WriteGSO with GSOProtoUDP is safe. Linux ≥ 6.2. + // USO means the kernel additionally agreed to TUN_F_USO4|USO6, + // so WriteGSO with GSOProtoUDP is safe. Linux ≥ 6.2. USO bool } -// Queue is a readable/writable Poll queue. Concurrency contract: a single -// read goroutine drives Read; plain Write is safe for concurrent callers; +// Queue is a readable/writable Poll queue. +// Concurrency contract: a single read goroutine drives Read; plain Write is safe for concurrent callers; // WriteGSO (on Queues that implement GSOWriter) is single-writer per queue. type Queue interface { io.Closer - // Read returns one or more packets. The returned Packet.Bytes slices - // are borrowed from the Queue's internal buffer and are only valid - // until the next Read or Close on this Queue - callers must encrypt - // or copy each slice before the next call. A Packet may carry a - // GSO/USO superpacket (see GSOInfo); when GSO.IsSuperpacket() is - // true the caller must segment Bytes before treating it as a single - // IP datagram. Single-reader only: not safe for concurrent Reads (it - // reuses per-queue rx scratch each call). + // Read returns one or more packets. + // The returned Packet.Bytes slices are borrowed from the Queue's internal buffer and are only valid + // until the next Read or Close on this Queue. + // A Packet may carry a GSO/USO superpacket (see GSOInfo) + // Single-reader only: not safe for concurrent Reads (it reuses per-queue rx scratch each call). Read() ([]Packet, error) // Write emits a single packet on the plaintext (outside→inside) @@ -47,19 +42,17 @@ type Queue interface { Write(p []byte) (int, error) } -// Packet is the unit Queue.Read returns. Bytes points into the queue's -// internal buffer and is only valid until the next Read or Close on the -// queue that produced it. GSO is the zero value for an already-segmented -// IP datagram; when non-zero it describes a kernel-supplied TSO/USO -// superpacket the caller must segment before consuming. +// Packet is the unit Queue.Read returns. +// Bytes points into the queue's internal buffer and is only valid until the next Read or Close on the queue that produced it. +// GSO is the zero value for an already-segmented IP datagram; +// when non-zero it describes a kernel-supplied TSO/USO superpacket the caller must segment before consuming. type Packet struct { Bytes []byte GSO GSOInfo } // GSOInfo describes a kernel-supplied superpacket sitting in Packet.Bytes. -// The zero value means "not a superpacket" — Bytes is one regular IP -// datagram and no segmentation is required. +// The zero value means Bytes is one regular IP datagram and no segmentation is required. type GSOInfo struct { // Size is the GSO segment size: max payload bytes per segment // (== TCP MSS for TSO, == UDP payload chunk for USO). Zero means @@ -77,15 +70,13 @@ type GSOInfo struct { } // IsSuperpacket reports whether g describes a multi-segment GSO/USO -// superpacket that needs segmentation before its bytes can be encrypted -// and sent on the wire. +// superpacket that needs segmentation before its bytes can be encrypted and sent on the wire. func (g GSOInfo) IsSuperpacket() bool { return g.Size > 0 } // Clone returns a Packet whose Bytes is a freshly allocated copy of p.Bytes, // safe to retain past the next Read or Close on the originating Queue. -// GSO metadata is copied verbatim. Use this only when a caller genuinely -// needs to outlive the borrowed-slice contract — the hot path reads should -// continue to consume the borrow synchronously to avoid the allocation. +// GSO metadata is copied verbatim. +// Use this only when a caller needs the data to outlive the borrowed-slice contract. func (p Packet) Clone() Packet { if p.Bytes == nil { return p @@ -95,26 +86,23 @@ func (p Packet) Clone() Packet { return Packet{Bytes: cp, GSO: p.GSO} } -// CapsProvider is an optional interface implemented by Queues that -// successfully negotiated kernel offload features at open time. Callers -// pick a write-path coalescer based on the result. Queues that don't -// implement it are treated as having no offload capability — callers must -// fall back to plain per-packet writes. +// CapsProvider is an optional interface implemented by Queues that negotiate kernel offload features at open time. +// Callers pick a write-path coalescer based on the result. +// Queues that don't implement it are treated as having no offload capability. type CapsProvider interface { Capabilities() Capabilities } -// QueueCapabilities returns q's negotiated offload capabilities, or the -// zero value when q does not advertise any. -func QueueCapabilities(q Queue) Capabilities { +// QueueCapabilities returns q's negotiated offload capabilities, or the zero value when q does not advertise any. +func QueueCapabilities(q io.Writer) Capabilities { if cp, ok := q.(CapsProvider); ok { return cp.Capabilities() } return Capabilities{} } -// GSOProto selects the L4 protocol for a GSO superpacket. Determines which -// VIRTIO_NET_HDR_GSO_* type the writer stamps and which checksum offset +// GSOProto selects the L4 protocol for a GSO superpacket. +// Determines which VIRTIO_NET_HDR_GSO_* type the writer stamps and which checksum offset // inside the transport header virtio NEEDS_CSUM expects. type GSOProto uint8 @@ -125,49 +113,40 @@ const ( ) // GSOWriter is implemented by Queues that can emit a TCP or UDP superpacket -// assembled from a header prefix plus one or more borrowed payload -// fragments, in a single vectored write (writev with a leading -// virtio_net_hdr). This lets the coalescer avoid copying payload bytes -// between the caller's decrypt buffer and the TUN. Backends without GSO -// support do not implement this interface and coalescing is skipped. +// assembled from a header prefix plus one or more borrowed payload fragments, +// in a single vectored write (writev with a leading virtio_net_hdr). +// This lets the coalescer avoid copying payload bytes between the caller's decrypt buffer and the TUN. +// Backends without GSO support do not implement this interface and coalescing is skipped. // -// hdr contains the IPv4/IPv6 header prefix (mutable - callers will have -// filled in total length and IP csum). transportHdr is the TCP or UDP -// header (mutable - the L4 checksum field must hold the pseudo-header -// partial, single-fold not inverted, per virtio NEEDS_CSUM semantics). -// pays are non-overlapping payload fragments whose concatenation is the -// full superpacket payload; they are read-only from the writer's -// perspective and must remain valid until the call returns. Every segment -// in pays except possibly the last is exactly the same size. proto picks -// the L4 protocol so the writer knows which gsoType / CsumOffset to set. +// hdr contains the IPv4/IPv6 header prefix (mutable: callers will have filled in total length and IP csum). +// transportHdr is the TCP or UDP header +// (mutable: the L4 checksum field must hold the pseudo-header partial, single-fold not inverted, per virtio NEEDS_CSUM semantics). +// pays are non-overlapping payload fragments whose concatenation is the full superpacket payload. +// They are read-only from the writer's perspective and must remain valid until the call returns. +// Every segment in pays except possibly the last is exactly the same size. +// proto picks the L4 protocol so the writer knows which gsoType / CsumOffset to set. // -// Callers should also consult CapsProvider (via SupportsGSO or -// QueueCapabilities) for the per-protocol negotiated capability; an -// implementation of GSOWriter is necessary but not sufficient since USO -// may not have been negotiated even when TSO was. +// Callers should also consult CapsProvider (via SupportsGSO or QueueCapabilities) +// for the per-protocol negotiated capability: USO may not have been negotiated even when TSO was. type GSOWriter interface { + CapsProvider WriteGSO(hdr []byte, transportHdr []byte, pays [][]byte, proto GSOProto) error } // SupportsGSO reports whether w implements GSOWriter and the underlying -// queue advertises the negotiated capability for `want`. A writer that -// implements GSOWriter but not CapsProvider is treated as permissive -// (used by tests and fakes that don't negotiate). -func SupportsGSO(w any, want GSOProto) (GSOWriter, bool) { +// queue advertises the negotiated capability for `want`. +func SupportsGSO(w io.Writer, want GSOProto) (GSOWriter, bool) { gw, ok := w.(GSOWriter) if !ok { return nil, false } - cp, ok := w.(CapsProvider) - if !ok { - return gw, true - } - caps := cp.Capabilities() + caps := gw.Capabilities() switch want { case GSOProtoTCP: return gw, caps.TSO case GSOProtoUDP: return gw, caps.USO + default: + return gw, false } - return gw, false }