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.
- Transmit: 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 descriptor 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 ¶
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 New ¶
func New(ifaceIdx, queueID uint32, opts Opts) (*ControlBlock, error)
New returns an initialized AF_XDP socket bound to a particular interface and queue.
func NewFromSocket ¶
func NewFromSocket(sockfd int, ifaceIdx, queueID uint32, opts Opts) (*ControlBlock, error)
NewFromSocket takes an AF_XDP socket, initializes it, and binds it 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 ¶
FillAll posts as many empty buffers as possible for the kernel to fill, then notifies the kernel.
+checklocks:umem.mu
type Opts ¶
type Opts struct {
NFrames uint32
FrameSize uint32
NDescriptors uint32
Bind bool
UseNeedWakeup bool
}
Opts configure an AF_XDP socket.
func DefaultOpts ¶
func DefaultOpts() Opts
DefaultOpts provides recommended default options for initializing an AF_XDP socket. AF_XDP setup is extremely finnicky and can fail if incorrect values are used.
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
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.
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 ¶
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 ¶
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
Source Files