comments pass and helpers

Signed-off-by: Alex Valiushko <alexvaliushko@tailscale.com>
Change-Id: I99d814cf413752d481920f71d2430be56a6a6964

Author: illotum

buffer/buffer.go

@@ -1,31 +1,32 @@
 /* SPDX-License-Identifier: MIT
  *
  * Copyright (C) 2017-2023 WireGuard LLC. All Rights Reserved.
- *
- * Package buffer implements a reusable buffer abstraction.
- *
- * Wireguard-go's data processing is constrained by both the hosts API,
- * and the transformations performed during encapsulation:
- *
- *  1. Encryption requires tail- and headroom for extra headers and padding.
- *     Available via winrio, and pread(2).
- *  2. Systems are moving towards coalesced reads for both TCP and UDP.
- *     The read data has no gaps for individual slices.
- *  3. crypto.AEAD interface requires a contiguous dst []byte for Sealing.
- *     So we can't use scatter-gather to inject the gaps.
- *
- * Until one of these three conditions is changed, the encryption strategy
- * is to copy on read into buffers with the required gaps.
- * The buffers are right-sized for the packet to avoid memory inflation.
- * To recycle said allocations, each buffer carries a recycle function
- * that routes it back to its originating pool.
- *
- * Decryption shrinks each fragment instead of growing, so buffers can pass
- * through the pipeline without copying till the egress coalescion.
- * Depending on the chosen head of the coalescion, there may or may be no room
- * and reallocation is a necessary fallback until we start passing
- * buffers in batches.
  */
+
+// Package buffer implements a reusable buffer abstraction.
+//
+// Wireguard-go's data processing is constrained by both the hosts API,
+// and the transformations performed during encapsulation:
+//
+//  1. Encryption requires tail- and headroom for extra headers and padding.
+//     Available via winrio, and pread(2).
+//  2. Systems are moving towards coalesced reads for both TCP and UDP.
+//     The read data has no gaps for individual slices.
+//  3. crypto.AEAD interface requires a contiguous dst []byte for Sealing.
+//     So we can't use scatter-gather to inject the gaps.
+//
+// Until one of these three conditions is changed, the encryption strategy
+// is to copy on read into buffers with the required gaps.
+// The buffers are right-sized for the packet to avoid memory inflation.
+// To recycle said allocations, each buffer carries a recycle function
+// that routes it back to its originating pool.
+//
+// Decryption shrinks each fragment instead of growing, so buffers can pass
+// through the pipeline without copying till the egress coalescion.
+// Depending on the chosen head of the coalescion, there may or may be no room
+// and reallocation is a necessary fallback until we start passing
+// buffers in batches.
+
 package buffer
 
 const (
@@ -34,9 +35,13 @@ const (
 
 // Source produces new Buffers.
 type Source interface {
+
+	// Get returns a Buffer of at least the requested size.
+	// Implementations may chose to return error if the request can not be fulfilled.
 	Get(size int) (*Buffer, error)
 }
 
+// Recycler holds state necessary for a correct Buffer return to its originating Source
 type Recycler interface {
 	Recycle(*Buffer)
 }
@@ -47,29 +52,41 @@ type Buffer struct {
 	data     []byte
 	recycler Recycler
 
-	Size int // size of the read, excluding offset
+	// Size is the length of the valid data within the buffer. It does not account for any head- or tailroom.
+	// Typically implementations set it to the number of bytes read into the buffer.
+	Size int
 }
 
 // New creates a standalone Buffer.
 func New(b []byte, recycler Recycler) *Buffer {
 	return &Buffer{data: b, recycler: recycler}
 }
 
+// Make creates a standalone Buffer with a new byte slice of the requested size.
+func Make(size int) *Buffer {
+	return &Buffer{data: make([]byte, size), recycler: nil}
+}
+
+// Data returns the full underlying byte slice of the Buffer.
 func (b *Buffer) Data() []byte {
 	return b.data
 }
 
-func (b *Buffer) Len() int {
-	return len(b.data)
+// Packet returns a slice starting at the given offset and ending at the end of the valid data in the buffer.
+func (b *Buffer) Packet(offset int) []byte {
+	return b.data[offset : offset+b.Size]
 }
 
+// Release returns the Buffer to its originating Source for reuse.
+// The Buffer must not be used after calling Release.
 func (b *Buffer) Release() {
 	if b.recycler != nil {
 		clear(b.data)
 		b.recycler.Recycle(b)
 	}
 }
 
+// ReleaseAll calls Release on each non-nil Buffer in the slice, and sets the slice elements to nil.
 func ReleaseAll(bs []*Buffer) {
 	for i := range bs {
 		if bs[i] != nil {
@@ -79,11 +96,14 @@ func ReleaseAll(bs []*Buffer) {
 	}
 }
 
+// Arena is a Buffer with an internal watermark for sequential allocations.
+// FIXME Arena needs a graceful fallback on overflow.
 type Arena struct {
 	*Buffer
 	watermark int
 }
 
+// Get returns a slice of the Arena's Buffer of the requested size, and advances the watermark.
 func (a *Arena) Get(size int) []byte {
 	if a.watermark+size > len(a.Buffer.Data()) {
 		panic("arena overflow") // or return a heap-allocated fallback
@@ -93,6 +113,7 @@ func (a *Arena) Get(size int) []byte {
 	return b
 }
 
+// Flush resets the Arena's watermark to zero, and clears the valid data in the Buffer.
 func (a *Arena) Flush() {
 	clear(a.Buffer.Data()[:a.watermark])
 	a.watermark = 0

buffer/pool.go

@@ -3,13 +3,15 @@ package buffer
 import "sync"
 
 const (
-	min = 2 << 10
-	mid = 10 << 10
-	max = 65 << 10
+	min = 2 << 10  // 2KB, enough for a typical MTU-sized packet
+	mid = 10 << 10 // 10KB, enough for a jumbo frame
+	max = 65 << 10 // 65KB, enough for the maximum possible UDP datagram size
 )
 
 var _ Source = (*FragmentPool)(nil)
 
+// FragmentPool is a tiered source of buffers. Tiers are balanced
+// to accomodate regular MTU sizes, jumbo frames, and the maximum possible UDP datagram size.
 type FragmentPool struct {
 	minPool sync.Pool
 	midPool sync.Pool
@@ -38,6 +40,8 @@ func NewFragmentPool() *FragmentPool {
 	return p
 }
 
+// Get returns a Buffer of at least the requested size. Implementations may chose to return error if the request can not be fulfilled.
+// FIXME current code ignores err return
 func (p *FragmentPool) Get(size int) (*Buffer, error) {
 	var buf *Buffer
 	switch {

conn/conn.go

@@ -27,6 +27,7 @@ const (
 // sizes may be zero, and callers should ignore them. Callers must pass a sizes
 // and eps slice with a length greater than or equal to the length of packets.
 // These lengths must not exceed the length of the associated Bind.BatchSize().
+// Nil entries in bufs are allocated by the implementation.
 type ReceiveFunc func(bufs []*buffer.Buffer, eps []Endpoint) (n int, err error)
 
 // A Bind listens on a port for both IPv6 and IPv4 UDP traffic.

tun/tun_linux.go

@@ -588,7 +588,7 @@ func CreateTUN(name string, mtu int) (Device, error) {
 // CreateTUNFromFile creates a Device from an os.File with the provided MTU.
 func CreateTUNFromFile(file *os.File, mtu int) (Device, error) {
 	bufPool := buffer.NewFragmentPool()
-	arenaBuf, _ := bufPool.Get(32 * 16 << 10)
+	arenaBuf, _ := bufPool.Get(32 * 65 << 10) // 32 buffers of coalesced size
 	tun := &NativeTun{
 		tunFile:                 file,
 		events:                  make(chan Event, 5),
@@ -649,7 +649,7 @@ func CreateUnmonitoredTUNFromFD(fd int) (Device, string, error) {
 	}
 	file := os.NewFile(uintptr(fd), "/dev/tun")
 	bufPool := buffer.NewFragmentPool()
-	arenaBuf, _ := bufPool.Get(32 * 16 << 10)
+	arenaBuf, _ := bufPool.Get(32 * 65 << 10) // 32 buffers of coalesced size
 	tun := &NativeTun{
 		tunFile:       file,
 		events:        make(chan Event, 5),