sharedmem

Documentation

Overview

Package sharedmem provides the implementation of data-link layer endpoints backed by shared memory.

Shared memory endpoints can be used in the networking stack by calling New() to create a new endpoint, and then passing it as an argument to Stack.CreateNIC().

Index

• Constants
• func New(opts Options) (stack.LinkEndpoint, error)
• func NewServerEndpoint(opts Options) (stack.LinkEndpoint, error)
• type Options
• type QueueConfig
  • func QueueConfigFromFDs(fds []int) (QueueConfig, error)
  • func (q *QueueConfig) FDs() []int
• type QueueOptions
• type QueuePair
  • func NewQueuePair(opts QueueOptions) (*QueuePair, error)
  • func (q *QueuePair) Close()
  • func (q *QueuePair) RXQueueConfig() QueueConfig
  • func (q *QueuePair) TXQueueConfig() QueueConfig

Constants

const (
	// DefaultQueueDataSize is the size of the shared memory data region that
	// holds the scatter/gather buffers.
	DefaultQueueDataSize = 1 << 20 // 1MiB

	// DefaultQueuePipeSize is the size of the pipe that holds the packet descriptors.
	//
	// Assuming each packet data is approximately 1280 bytes (IPv6 Minimum MTU)
	// then we can hold approximately 1024*1024/1280 ~ 819 packets in the data
	// area. Which means the pipe needs to be big enough to hold 819
	// descriptors.
	//
	// Each descriptor is approximately 8 (slot descriptor in pipe) +
	// 16 (packet descriptor) + 12 (for buffer descriptor) assuming each packet is
	// stored in exactly 1 buffer descriptor (see queue/tx.go and pipe/tx.go.)
	//
	// Which means we need approximately 36*819 ~ 29 KiB to store all packet
	// descriptors. We could go with a 32 KiB pipe but to give it some slack in
	// how the upper layer may make use of the scatter gather buffers we double
	// this to hold enough descriptors.
	DefaultQueuePipeSize = 64 << 10 // 64KiB

	// DefaultSharedDataSize is the size of the sharedData region used to
	// enable/disable notifications.
	DefaultSharedDataSize = 4 << 10 // 4KiB

	// DefaultBufferSize is the size of each individual buffer that the data
	// region is broken down into to hold packet data. Should be larger than
	// 1500 + 14 (Ethernet header) + 10 (VirtIO header) to fit each packet
	// in a single buffer.
	DefaultBufferSize = 2048

	// DefaultTmpDir is the path used to create the memory files if a path
	// is not provided.
	DefaultTmpDir = "/dev/shm"
)

Functions

func New

func New(opts Options) (stack.LinkEndpoint, error)

New creates a new shared-memory-based endpoint. Buffers will be broken up into buffers of "bufferSize" bytes.

In order to release all resources held by the returned endpoint, Close() must be called followed by Wait().

func NewServerEndpoint

func NewServerEndpoint(opts Options) (stack.LinkEndpoint, error)

NewServerEndpoint creates a new shared-memory-based endpoint. Buffers will be broken up into buffers of "bufferSize" bytes.

Types

type Options

type Options struct {
	// MTU is the mtu to use for this endpoint.
	MTU uint32

	// BufferSize is the size of each scatter/gather buffer that will hold packet
	// data.
	//
	// NOTE: This directly determines number of packets that can be held in
	// the ring buffer at any time. This does not have to be sized to the MTU as
	// the shared memory queue design allows usage of more than one buffer to be
	// used to make up a given packet.
	BufferSize uint32

	// LinkAddress is the link address for this endpoint (required).
	LinkAddress tcpip.LinkAddress

	// TX is the transmit queue configuration for this shared memory endpoint.
	TX QueueConfig

	// RX is the receive queue configuration for this shared memory endpoint.
	RX QueueConfig

	// PeerFD is the fd for the connected peer which can be used to detect
	// peer disconnects.
	PeerFD int

	// OnClosed is a function that is called when the endpoint is being closed
	// (probably due to peer going away)
	OnClosed func(err tcpip.Error)

	// TXChecksumOffload if true, indicates that this endpoints capability
	// set should include CapabilityTXChecksumOffload.
	TXChecksumOffload bool

	// RXChecksumOffload if true, indicates that this endpoints capability
	// set should include CapabilityRXChecksumOffload.
	RXChecksumOffload bool

	// VirtioNetHeaderRequired if true, indicates that all outbound packets should have
	// a virtio header and inbound packets should have a virtio header as well.
	VirtioNetHeaderRequired bool

	// GSOMaxSize is the maximum GSO packet size. It is zero if GSO is
	// disabled. Note that only gVisor GSO is supported, not host GSO.
	GSOMaxSize uint32
}

Options specify the details about the sharedmem endpoint to be created.

type QueueConfig

type QueueConfig struct {
	// DataFD is a file descriptor for the file that contains the data to
	// be transmitted via this queue. Descriptors contain offsets within
	// this file.
	DataFD int

	// EventFD is a file descriptor for the event that is signaled when
	// data is becomes available in this queue.
	EventFD eventfd.Eventfd

	// TxPipeFD is a file descriptor for the tx pipe associated with the
	// queue.
	TxPipeFD int

	// RxPipeFD is a file descriptor for the rx pipe associated with the
	// queue.
	RxPipeFD int

	// SharedDataFD is a file descriptor for the file that contains shared
	// state between the two ends of the queue. This data specifies, for
	// example, whether EventFD signaling is enabled or disabled.
	SharedDataFD int
}

QueueConfig holds all the file descriptors needed to describe a tx or rx queue over shared memory. It is used when creating new shared memory endpoints to describe tx and rx queues.

func QueueConfigFromFDs

func QueueConfigFromFDs(fds []int) (QueueConfig, error)

QueueConfigFromFDs constructs a QueueConfig out of a slice of ints where each entry represents an file descriptor. The order of FDs in the slice must be in the order specified below for the config to be valid. QueueConfig.FDs() should be used when the config needs to be serialized or sent as part of a control message to ensure the correct order.

func (*QueueConfig) FDs

func (q *QueueConfig) FDs() []int

FDs returns the FD's in the QueueConfig as a slice of ints. This must be used in conjunction with QueueConfigFromFDs to ensure the order of FDs matches when reconstructing the config when serialized or sent as part of control messages.

type QueueOptions

type QueueOptions struct {
	// SharedMemPath is the path to use to create the shared memory backing
	// files for the queue.
	//
	// If unspecified it defaults to "/dev/shm".
	SharedMemPath string
}

QueueOptions allows queue specific configuration to be specified when creating a QueuePair.

type QueuePair

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

A QueuePair represents a pair of TX/RX queues.

func NewQueuePair

func NewQueuePair(opts QueueOptions) (*QueuePair, error)

NewQueuePair creates a shared memory QueuePair.

func (*QueuePair) Close

func (q *QueuePair) Close()

Close closes underlying tx/rx queue fds.

func (*QueuePair) RXQueueConfig

func (q *QueuePair) RXQueueConfig() QueueConfig

RXQueueConfig returns the QueueConfig for the transmit queue.

func (*QueuePair) TXQueueConfig

func (q *QueuePair) TXQueueConfig() QueueConfig

TXQueueConfig returns the QueueConfig for the receive queue.