xdp

package
v0.0.0-...-9ec6d29 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 9, 2022 License: Apache-2.0, MIT Imports: 10 Imported by: 0

Documentation

Overview

Package xdp provides tools for working with AF_XDP sockets.

AF_XDP shares a memory area (UMEM) with the kernel to pass packets back and forth. Communication is done via a number of queues. Briefly, the queues work as follows:

  • Receive: Userspace adds a descriptor to the fill queue. The descriptor points to an area of the UMEM that the kernel should fill with an incoming packet. The packet is filled by the kernel, which places a descriptor to the same UMEM area in the RX queue, signifying that userspace may read the packet.
  • Trasmit: Userspace adds a descriptor to TX queue. The kernel sends the packet (stored in UMEM) pointed to by the descriptor. Upon completion, the kernel places a desciptor in the completion queue to notify userspace that the packet is sent and the UMEM area can be reused.

So in short: RX packets move from the fill to RX queue, and TX packets move from the TX to completion queue.

Note that the shared UMEM for RX and TX means that packet forwarding can be done without copying; only the queues need to be updated to point to the packet in UMEM.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CompletionQueue

type CompletionQueue struct {
	// contains filtered or unexported fields
}

The CompletionQueue is how the kernel tells a process which buffers have been transmitted and can be reused.

CompletionQueue is not thread-safe and requires external synchronization

func (*CompletionQueue) FreeAll

func (cq *CompletionQueue) FreeAll(umem *UMEM)

FreeAll dequeues as many buffers as possible from the queue and returns them to the UMEM.

+checklocks:umem.mu

func (*CompletionQueue) Get

func (cq *CompletionQueue) Get(index uint32) uint64

Get gets the descriptor at index.

func (*CompletionQueue) Peek

func (cq *CompletionQueue) Peek() (nAvailable, index uint32)

Peek returns the number of buffers available to reuse as well as the index at which they start. Peek will only return a buffer once, so callers must process any received buffers.

func (*CompletionQueue) Release

func (cq *CompletionQueue) Release(nDone uint32)

Release notifies the kernel that we have consumed nDone packets.

type ControlBlock

type ControlBlock struct {
	UMEM       UMEM
	Fill       FillQueue
	RX         RXQueue
	TX         TXQueue
	Completion CompletionQueue
}

A ControlBlock contains all the control structures necessary to use an AF_XDP socket.

The ControlBlock and the structures it contains are meant to be used with a single RX goroutine and a single TX goroutine.

func ReadOnlyFromSocket

func ReadOnlyFromSocket(sockfd int, ifaceIdx, queueID uint32, opts ReadOnlySocketOpts) (*ControlBlock, error)

ReadOnlyFromSocket takes an AF_XDP socket, initializes it, and binds it to a particular interface and queue.

func ReadOnlySocket

func ReadOnlySocket(ifaceIdx, queueID uint32, opts ReadOnlySocketOpts) (*ControlBlock, error)

ReadOnlySocket returns an initialized read-only AF_XDP socket bound to a particular interface and queue.

type FillQueue

type FillQueue struct {
	// contains filtered or unexported fields
}

The FillQueue is how a process tells the kernel which buffers are available to be filled by incoming packets.

FillQueue is not thread-safe and requires external synchronization

func (*FillQueue) FillAll

func (fq *FillQueue) FillAll(umem *UMEM)

FillAll posts as many empty buffers as possible for the kernel to fill, then notifies the kernel.

+checklocks:umem.mu

func (*FillQueue) Notify

func (fq *FillQueue) Notify()

Notify updates the producer such that it is visible to the kernel.

func (*FillQueue) Set

func (fq *FillQueue) Set(index uint32, addr uint64)

Set sets the fill queue's descriptor at index to addr.

type RXQueue

type RXQueue struct {
	// contains filtered or unexported fields
}

The RXQueue is how the kernel tells a process which buffers are full with incoming packets.

RXQueue is not thread-safe and requires external synchronization

func (*RXQueue) Get

func (rq *RXQueue) Get(index uint32) unix.XDPDesc

Get gets the descriptor at index.

func (*RXQueue) Peek

func (rq *RXQueue) Peek() (nReceived, index uint32)

Peek returns the number of packets available to read as well as the index at which they start. Peek will only return a packet once, so callers must process any received packets.

func (*RXQueue) Release

func (rq *RXQueue) Release(nDone uint32)

Release notifies the kernel that we have consumed nDone packets.

type ReadOnlySocketOpts

type ReadOnlySocketOpts struct {
	NFrames      uint32
	FrameSize    uint32
	NDescriptors uint32
}

ReadOnlySocketOpts configure a read-only AF_XDP socket.

func DefaultReadOnlyOpts

func DefaultReadOnlyOpts() ReadOnlySocketOpts

DefaultReadOnlyOpts provides recommended default options for initializing a readonly AF_XDP socket. AF_XDP setup is extremely finnicky and can fail if incorrect values are used.

type TXQueue

type TXQueue struct {
	// contains filtered or unexported fields
}

The TXQueue is how a process tells the kernel which buffers are available to be sent via the NIC.

TXQueue is not thread-safe and requires external synchronization

func (*TXQueue) Notify

func (tq *TXQueue) Notify()

Notify updates the producer such that it is visible to the kernel.

func (*TXQueue) Reserve

func (tq *TXQueue) Reserve(umem *UMEM, toReserve uint32) (nReserved, index uint32)

Reserve reserves descriptors in the queue. If toReserve descriptors cannot be reserved, none are reserved.

+checklocks:umem.mu

func (*TXQueue) Set

func (tq *TXQueue) Set(index uint32, desc unix.XDPDesc)

Set sets the TX queue's descriptor at index to addr.

type UMEM

type UMEM struct {
	// contains filtered or unexported fields
}

UMEM is the shared memory area that the kernel and userspace put packets in.

func (*UMEM) AllocFrame

func (um *UMEM) AllocFrame() uint64

AllocFrame returns the address of a frame that can be enqueued to the fill or TX queue. It will panic if there are no frames left, so callers must call it no more than the number of buffers reserved via TXQueue.Reserve().

The UMEM must be locked during the call to AllocFrame.

+checklocks:um.mu

func (*UMEM) FreeFrame

func (um *UMEM) FreeFrame(addr uint64)

FreeFrame returns the frame containing addr to the set of free frames.

The UMEM must be locked during the call to FreeFrame.

+checklocks:um.mu

func (*UMEM) Get

func (um *UMEM) Get(desc unix.XDPDesc) []byte

Get gets the bytes of the packet pointed to by desc.

func (*UMEM) Lock

func (um *UMEM) Lock()

Lock locks the UMEM.

+checklocksacquire:um.mu

func (*UMEM) SockFD

func (um *UMEM) SockFD() uint32

SockFD returns the underlying AF_XDP socket FD.

func (*UMEM) Unlock

func (um *UMEM) Unlock()

Unlock unlocks the UMEM.

+checklocksrelease:um.mu

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL