iface

package
v0.0.0-...-c2e30b8 Latest Latest
Warning

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

 Go to latest Published: Jan 26, 2021 License: NIST-PD-fallback Imports: 25 Imported by: 2

README

ndn-dpdk/iface

This package implements the face system, which provides network interfaces (faces) that can send and receive NDN packets. Each face has a ID, a uint16 number that identifies the face.

There are three lower layer implementations:

  • EthFace communicates on Ethernet via DPDK ethdev.
  • SocketFace communicates on Unix/TCP/UDP tunnels via Go sockets.
  • MockFace is for unit testing.

Unit tests of this package are in ifacetest subdirectory.

Face System API

In C, public APIs are defined in term of FaceID. There are functions to query face status, and to transmit a burst of packets. Notably, there isn't a function to receive packets; instead, RxLoop type is used for receiving packets.

In Go, Face type defines what methods a face must provide. Lower layer implementation invokes New to construct an object that satisfy this interface. Get function retrieves an existing Face by ID; List returns a list of all faces.

All faces are assumed to be point-to-point. Locator type identifies the endpoints of a face. It has a Scheme field that indicates the underlying network protocol, as well as other fields added by each lower layer implementation. This type can be marshaled as JSON.

Receive Path

RxLoop type implements the receive path. Lower layer implementation places each face into one or more RxGroups, which are then added into RxLoops. RxLoop_Run function continually invokes RxGroup.rxBurstOp function to retrieve L2 frames arriving on these faces.

Each frame is decoded by RxProc, which also performs NDNLPv2 reassembly on fragments using the Reassembler. Successfully decoded L3 Interest, Data, or Nack packets are passed to the upper layer (such as the forwarder's forwarding thread) via an InputDemux of that packet type.

It's possible to receive packets arriving on one face in multiple RxLoop threads, by placing the face into multiple RxGroups. However, currently only "thread 0" can perform reassembly; fragments arriving on other threads are dropped.

Send Path

The send path starts from Face_TxBurst function. It enqueues a burst of L3 packets in Face.txQueue (the "before-Tx queue"). Face_TxBurst function is thread-safe.

TxLoop type implements the send path. It dequeues a burst of L3 packets from Face.txQueue, calls TxProc to encode them into L2 frames. It then passes a burst of L2 frames to the lower layer implementation via TxProc.l2Burst function. TxProc is non-thread-safe, so that only one thread should be running TxProc for a face.

Packet Queue

PktQueue type implements a packet queue that can operate in one of three modes.

Plain mode: a simple drop-tail queue.

Delay mode: a drop-tail queue that enforces a minimum amount of delay. This is useful for simulating a processing delay.

CoDel mode: a queue that uses the CoDel algorithm. This CoDel implementation differs from a standard implementation in that it dequeues packets in bursts instead of one at a time. The last packet in each burst is used to calculate the sojourn time, and at most one packet can be dropped in each burst. The CoDel_* functions are adapted from the CoDel implementation in the Linux kernel, under the BSD license (see codel.LICENSE).

Documentation

Overview

Package iface implements basics of the face system.

Index

Constants

View Source 
const (
	// MaxBurstSize is the maximum and default burst size.
	MaxBurstSize = 64

	// MinReassemblerCapacity is the minimum partial message store capacity in the reassembler.
	MinReassemblerCapacity = 4

	// MaxReassemblerCapacity is the maximum partial message store capacity in the reassembler.
	MaxReassemblerCapacity = 8192

	// DefaultReassemblerCapacity is the default partial message store capacity in the reassembler.
	DefaultReassemblerCapacity = 64

	// MinOutputQueueSize is the minimum packet queue capacity before the output thread.
	MinOutputQueueSize = 256

	// DefaultOutputQueueSize is the default packet queue capacity before the output thread.
	DefaultOutputQueueSize = 1024

	// MinMTU is the minimum value of Maximum Transmission Unit (MTU).
	MinMTU = 960

	// MaxMTU is the maximum value of Maximum Transmission Unit (MTU).
	MaxMTU = 65000
)
View Source 
const (
	StateUnused = iota
	StateUp
	StateDown
	StateRemoved
)

State values.

View Source 
const (
	MinID = 0x1000
	MaxID = 0xEFFF
)

ID limits.

Variables

View Source 
var (
	GqlCountersType *graphql.Object
	GqlFaceNodeType *gqlserver.NodeType
	GqlFaceType     *graphql.Object
)

GraphQL types.

View Source 
var (
	// ChooseRxLoop customizes RxLoop selection in ActivateRxGroup.
	// Return nil to use default algorithm.
	ChooseRxLoop = func(rxg RxGroup) RxLoop { return nil }
)
View Source 
var (
	// ChooseTxLoop customizes TxLoop selection in ActivateTxFace.
	// Return nil to use default algorithm.
	ChooseTxLoop = func(face Face) TxLoop { return nil }
)

Functions

func ActivateRxGroup 

func ActivateRxGroup(rxg RxGroup)

ActivateRxGroup selects an available RxLoop and adds the RxGroup to it. Panics if no RxLoop is available.

func ActivateTxFace 

func ActivateTxFace(face Face)

ActivateTxFace selects an available TxLoop and adds the Face to it. Panics if no TxLoop is available.

func CloseAll 

func CloseAll()

CloseAll closes all faces, RxLoops, and TxLoops.

func DeactivateRxGroup 

func DeactivateRxGroup(rxg RxGroup)

DeactivateRxGroup removes the RxGroup from the owning RxLoop.

func DeactivateTxFace 

func DeactivateTxFace(face Face)

DeactivateTxFace removes the Face from the owning TxLoop.

func IsDown 

func IsDown(id ID) bool

IsDown returns true if the face does not exist or is down.

func LocatorString 

func LocatorString(loc Locator) string

LocatorString converts a locator to JSON string

func OnFaceClosed 

func OnFaceClosed(cb func(ID)) io.Closer

OnFaceClosed registers a callback when a face is closed. Return a Closer that cancels the callback registration.

func OnFaceClosing 

func OnFaceClosing(cb func(ID)) io.Closer

OnFaceClosing registers a callback when a face is closing. Return a Closer that cancels the callback registration.

func OnFaceDown 

func OnFaceDown(cb func(ID)) io.Closer

OnFaceDown registers a callback when a face becomes DOWN. Return a Closer that cancels the callback registration.

func OnFaceNew 

func OnFaceNew(cb func(ID)) io.Closer

OnFaceNew registers a callback when a new face is created. Return a Closer that cancels the callback registration.

func OnFaceUp 

func OnFaceUp(cb func(ID)) io.Closer

OnFaceUp registers a callback when a face becomes UP. Return a Closer that cancels the callback registration.

func RegisterLocatorType 

func RegisterLocatorType(loc Locator, schemes ...string)

RegisterLocatorType registers Locator schemes.

func TxBurst 

func TxBurst(id ID, pkts []*ndni.Packet)

TxBurst transmits a burst of L3 packets.

Types

type Config 

type Config struct {
	// ReassemblerCapacity is the partial message store capacity in the reassembler.
	//
	// If this value is zero, it defaults to DefaultReassemblerCapacity.
	// Otherwise, it is clamped between MinReassemblerCapacity and MaxReassemblerCapacity.
	ReassemblerCapacity int `json:"reassemblerCapacity,omitempty"`

	// OutputQueueSize is the packet queue capacity before the output thread.
	//
	// The minimum is MinOutputQueueSize.
	// If this value is less than the minimum, it defaults to DefaultOutputQueueSize.
	// Otherwise, it is adjusted up to the next power of 2.
	OutputQueueSize int `json:"outputQueueSize,omitempty"`

	// MTU is the maximum size of outgoing NDNLP packets.
	// This excludes lower layer headers, such as Ethernet/VXLAN headers.
	//
	// Default is the lesser of MaxMTU and what's allowed by network interface and lower layer protocols.
	// If this is less than MinMTU or greater than the maximum, the face will fail to initialize.
	MTU int `json:"mtu,omitempty"`
	// contains filtered or unexported fields
}

Config contains face configuration.

func (*Config) ApplyDefaults 

func (c *Config) ApplyDefaults()

ApplyDefaults applies defaults.

func (Config) WithMaxMTU 

func (c Config) WithMaxMTU(max int) Config

WithMaxMTU returns a copy of Config with consideration of device MTU.

type Counters 

type Counters struct {
	RxFrames uint64 `json:"rxFrames"` // RX total frames
	RxOctets uint64 `json:"rxOctets"` // RX total bytes

	DecodeErrs   uint64 `json:"decodeErrs"`   // decode errors
	ReassPackets uint64 `json:"reassPackets"` // RX packets that were reassembled
	ReassDrops   uint64 `json:"reassDrops"`   // RX frames that were dropped by reassembler

	RxInterests uint64 `json:"rxInterests"` // RX Interest packets
	RxData      uint64 `json:"rxData"`      // RX Data packets
	RxNacks     uint64 `json:"rxNacks"`     // RX Nack packets

	TxInterests uint64 `json:"txInterests"` // TX Interest packets
	TxData      uint64 `json:"txData"`      // TX Data packets
	TxNacks     uint64 `json:"txNacks"`     // TX Nack packets

	FragGood    uint64 `json:"fragGood"`    // fragmented L3 packets
	FragBad     uint64 `json:"fragBad"`     // fragmentation failures
	TxAllocErrs uint64 `json:"txAllocErrs"` // allocation errors during TX
	TxDropped   uint64 `json:"txDropped"`   // L2 frames dropped due to full queue
	TxFrames    uint64 `json:"txFrames"`    // sent total frames
	TxOctets    uint64 `json:"txOctets"`    // sent total bytes
}

Counters contains basic face counters.

func (Counters) String 

func (cnt Counters) String() string

type Face 

type Face interface {
	eal.WithNumaSocket
	io.Closer

	// Ptr returns *C.Face pointer.
	Ptr() unsafe.Pointer

	// ID returns face ID.
	ID() ID

	// Locator returns a Locator describing face endpoints.
	Locator() Locator

	// ReadCounters returns basic face counters.
	ReadCounters() Counters

	// ReadExCounters returns extended counters.
	ReadExCounters() interface{}

	// SetDown changes face UP/DOWN state.
	SetDown(isDown bool)
}

Face represents a network layer face.

func Get 

func Get(id ID) Face

Get retrieves face by ID. Returns nil if id is invalid.

func List 

func List() (list []Face)

List returns a list of existing faces.

func New 

func New(p NewParams) (face Face, e error)

New creates a Face.

type ID 

type ID uint16

ID identifies a face. Zero ID is invalid.

func AllocID 

func AllocID() (id ID)

AllocID allocates a random ID. Warning: endless loop if all possible IDs are used up.

func (ID) Valid 

func (id ID) Valid() bool

Valid determines whether id is valid.

type InitResult 

type InitResult struct {
	// TxLinearize indicates whether TX mbufs must be direct mbufs in contiguous memory.
	// See C.PacketTxAlign.linearize field.
	TxLinearize bool

	// L2TxBurst is a C function of C.Face_L2TxBurst type.
	L2TxBurst unsafe.Pointer
}

InitResult contains results of NewParams.Init callback.

type InputDemux 

type InputDemux C.InputDemux

InputDemux is a demultiplexer for incoming packets of one L3 type.

func InputDemuxFromPtr 

func InputDemuxFromPtr(ptr unsafe.Pointer) *InputDemux

InputDemuxFromPtr converts *C.InputDemux pointer to InputDemux.

func (*InputDemux) InitDrop 

func (demux *InputDemux) InitDrop()

InitDrop configures to drop all packets.

func (*InputDemux) InitFirst 

func (demux *InputDemux) InitFirst()

InitFirst configures to pass all packets to the first and only destination.

func (*InputDemux) InitNdt 

func (demux *InputDemux) InitNdt(ndtt *ndt.Thread)

InitNdt configures to dispatch via NDT loopup.

func (*InputDemux) InitRoundrobin 

func (demux *InputDemux) InitRoundrobin(nDest int)

InitRoundrobin configures to pass all packets to each destination in a round-robin fashion.

func (*InputDemux) InitToken 

func (demux *InputDemux) InitToken()

InitToken configures to dispatch according to high 8 bits of PIT token.

func (*InputDemux) ReadDestCounters 

func (demux *InputDemux) ReadDestCounters(i int) (cnt InputDemuxDestCounters)

ReadDestCounters returns counters of i-th destination.

func (*InputDemux) SetDest 

func (demux *InputDemux) SetDest(i int, q *PktQueue)

SetDest assigns i-th destination.

type InputDemuxDestCounters 

type InputDemuxDestCounters struct {
	NQueued  uint64
	NDropped uint64
}

InputDemuxDestCounters contains counters of an InputDemux destination.

type Locator 

type Locator interface {
	// Scheme returns a string that identifies the type of this Locator.
	// Possible values must be registered through RegisterLocatorType().
	Scheme() string

	// Validate checks whether Locator fields are correct according to the chosen scheme.
	Validate() error

	// CreateFace creates a face from this Locator.
	CreateFace() (Face, error)
}

Locator identifies the endpoints of a face.

type LocatorWrapper 

type LocatorWrapper struct {
	Locator
}

LocatorWrapper wraps Locator to facilitate JSON serialization.

func (LocatorWrapper) MarshalJSON 

func (locw LocatorWrapper) MarshalJSON() (data []byte, e error)

MarshalJSON implements json.Marshaler.

func (*LocatorWrapper) UnmarshalJSON 

func (locw *LocatorWrapper) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type NewParams 

type NewParams struct {
	Config

	// Socket indicates where to allocate memory.
	Socket eal.NumaSocket

	// SizeOfPriv is the size of C.FaceImpl.priv struct.
	SizeofPriv uintptr

	// Init callback is invoked after allocating C.FaceImpl.
	// This is always invoked on the main thread.
	Init func(f Face) (InitResult, error)

	// Start callback is invoked after data structure initialization.
	// It should activate RxGroups associated with the face.
	// It may return a 'subclass' Face interface implementation to make available via Get(id).
	// This is always invoked on the main thread.
	Start func(f Face) (Face, error)

	// Locator callback returns a Locator describing the face.
	Locator func(f Face) Locator

	// Stop callback is invoked to stop the face.
	// It should deactivate RxGroups associated with the face.
	// This is always invoked on the main thread.
	Stop func(f Face) error

	// Close callback is invoked after the face has been removed.
	// This is optional.
	// This is always invoked on the main thread.
	Close func(f Face) error

	// ReadExCounters callback returns extended counters.
	// This is optional.
	ReadExCounters func(f Face) interface{}
}

NewParams contains parameters to New().

type PktQueue 

type PktQueue C.PktQueue

PktQueue is a packet queue with simplified CoDel algorithm.

func PktQueueFromPtr 

func PktQueueFromPtr(ptr unsafe.Pointer) (q *PktQueue)

PktQueueFromPtr converts *C.PktQueue to PktQueue.

func (*PktQueue) Close 

func (q *PktQueue) Close() error

Close deallocates the PktQueue.

func (*PktQueue) Init 

func (q *PktQueue) Init(cfg PktQueueConfig, socket eal.NumaSocket) error

Init initializes PktQueue.

func (*PktQueue) Pop 

func (q *PktQueue) Pop(vec pktmbuf.Vector, now eal.TscTime) (count int, drop bool)

Pop dequeues a slice of packets.

func (*PktQueue) Ptr 

func (q *PktQueue) Ptr() unsafe.Pointer

Ptr return *C.PktQueue pointer.

func (*PktQueue) Push 

func (q *PktQueue) Push(vec pktmbuf.Vector, now eal.TscTime) (nRej int)

Push enqueues a slice of packets.

type PktQueueConfig 

type PktQueueConfig struct {
	// Ring capacity, must be power of 2, default 131072 with delay/CoDel or 4096 without
	Capacity int `json:"capacity,omitempty"`
	// dequeue burst size limit, default MaxBurstSize
	DequeueBurstSize int `json:"dequeueBurstSize,omitempty"`

	// if non-zero, enforce minimum delay, implies DisableCoDel
	Delay nnduration.Nanoseconds `json:"delay,omitempty"`
	// if true, disable CoDel algorithm
	DisableCoDel bool `json:"disableCoDel,omitempty"`
	// CoDel TARGET parameter, default 5ms
	Target nnduration.Nanoseconds `json:"target,omitempty"`
	// CoDel INTERVAL parameter, default 100ms
	Interval nnduration.Nanoseconds `json:"interval,omitempty"`
}

PktQueueConfig contains PktQueue configuration.

type RxGroup 

type RxGroup interface {
	eal.WithNumaSocket

	// IsRxGroup identifies an implementation as RxGroup.
	IsRxGroup()

	// Ptr returns *C.RxGroup pointer.
	Ptr() unsafe.Pointer
}

RxGroup is a receive channel for a group of faces.

type RxLoop 

type RxLoop interface {
	ealthread.ThreadWithRole
	eal.WithNumaSocket
	io.Closer

	InterestDemux() *InputDemux
	DataDemux() *InputDemux
	NackDemux() *InputDemux

	CountRxGroups() int
	// contains filtered or unexported methods
}

RxLoop is the input thread that processes incoming packets on a set of RxGroups. Functions are non-thread-safe.

func ListRxLoops 

func ListRxLoops() (list []RxLoop)

ListRxLoops returns a list of RxLoops.

func NewRxLoop 

func NewRxLoop(socket eal.NumaSocket) RxLoop

NewRxLoop creates an RxLoop.

type State 

type State uint8

State indicates face state.

func (State) String 

func (st State) String() string

type TxLoop 

type TxLoop interface {
	ealthread.ThreadWithRole
	eal.WithNumaSocket
	io.Closer

	CountFaces() int
	// contains filtered or unexported methods
}

TxLoop is the output thread that processes outgoing packets on a set of faces. Functions are non-thread-safe.

func ListTxLoops 

func ListTxLoops() (list []TxLoop)

ListTxLoops returns a list of TxLoops.

func NewTxLoop 

func NewTxLoop(socket eal.NumaSocket) TxLoop

NewTxLoop creates a TxLoop.

Source Files

View all Source files

Directories

Path Synopsis
Package ethface implements Ethernet faces using DPDK Ethernet devices.
 Package ethface implements Ethernet faces using DPDK Ethernet devices.
Package ifacetestenv provides a test fixture for a face type.
 Package ifacetestenv provides a test fixture for a face type.
Package intface implements an internal face for internal applications.
 Package intface implements an internal face for internal applications.
Package socketface implements UDP/TCP socket faces using Go net.Conn type.
 Package socketface implements UDP/TCP socket faces using Go net.Conn type.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.