memif

Documentation

Overview

Package memif provides the implementation of shared memory interface (memif).

Memif network interfaces communicate using UNIX domain socket. This socket must be first created using NewSocket(). Then interfaces can be added to this socket using NewInterface(). To start communication on each socket socket.StartPolling() must be called. socket.StopPolling() will stop the communication. When the interface changes link status Connected and Disconencted callbacks set in Arguments for each interface are called respectively. Once the interface is connected rx and tx queues can be aquired using interface.GetRxQueue() and interface.GetTxQueue(). Packets can be transmitted by calling queue.ReadPacket() on rx queues and queue.WritePacket() on tx queues. If the interface is disconnected queue.ReadPacket() and queue.WritePacket() MUST not be called.

Data transmission is backed by shared memory. The driver works in promiscuous mode only.

Index

• Constants
• func RoleToString(isMaster bool) string
• type Arguments
• type ConnectedFunc
• type DisconnectedFunc
• type Interface
  • func (i *Interface) Delete() (err error)
  • func (i *Interface) Disconnect() (err error)
  • func (i *Interface) GetId() uint32
  • func (i *Interface) GetMemoryConfig() MemoryConfig
  • func (i *Interface) GetName() string
  • func (i *Interface) GetPeerName() string
  • func (i *Interface) GetPrivateData() interface{}
  • func (i *Interface) GetRemoteName() string
  • func (i *Interface) GetRxQueue(qid int) (*Queue, error)
  • func (i *Interface) GetSocket() *Socket
  • func (i *Interface) GetTxQueue(qid int) (*Queue, error)
  • func (i *Interface) IsConnected() bool
  • func (i *Interface) IsConnecting() bool
  • func (i *Interface) IsMaster() bool
  • func (i *Interface) RequestConnection() error
• type MemoryConfig
• type MsgAddRegion
• type MsgAddRing
• type MsgConnect
• type MsgConnected
• type MsgDisconnect
• type MsgHello
• type MsgInit
• type Queue
  • func (q *Queue) GetEventFd() (int, error)
  • func (q *Queue) ReadPacket(pkt []byte) (int, error)
  • func (q *Queue) WritePacket(pkt []byte) int
• type Socket
  • func NewSocket(appName string, filename string) (socket *Socket, err error)
  • func (socket *Socket) AddListener(fd int) (err error)
  • func (socket *Socket) Delete() (err error)
  • func (socket *Socket) GetFilename() string
  • func (socket *Socket) NewInterface(args *Arguments) (*Interface, error)
  • func (socket *Socket) StartPolling(errChan chan<- error)
  • func (socket *Socket) StopPolling() error

Constants

const (
	DefaultSocketFilename   = "/run/vpp/memif.sock"
	DefaultNumQueuePairs    = 1
	DefaultLog2RingSize     = 10
	DefaultPacketBufferSize = 2048
)

const (
	InterfaceModeEthernet interfaceMode = iota
	InterfaceModeIp
	InterfaceModePuntInject
)

const Version = ((VersionMajor << 8) | VersionMinor)

Version is memif protocols version as uint16 (M-Major m-minor: MMMMMMMMmmmmmmmm)

const VersionMajor = 2

VersionMajor is memif protocols major version

const VersionMinor = 0

VersionMinor is memif protocols minor version

Functions

func RoleToString

func RoleToString(isMaster bool) string

RoleToString returns 'Master' if isMaster os true, else returns 'Slave'

Types

type Arguments

type Arguments struct {
	Id               uint32 // Interface identifier unique across socket. Used to identify peer interface when connecting
	IsMaster         bool   // Interface role master/slave
	Mode             interfaceMode
	Name             string
	Secret           [24]byte // optional parameter, secrets of the interfaces must match if they are to connect
	MemoryConfig     MemoryConfig
	ConnectedFunc    ConnectedFunc    // callback called when interface changes status to connected
	DisconnectedFunc DisconnectedFunc // callback called when interface changes status to disconnected
	PrivateData      interface{}      // private data used by client program
}

Arguments represent interface configuration

type ConnectedFunc

type ConnectedFunc func(i *Interface) error

ConnectedFunc is a callback called when an interface is connected

type DisconnectedFunc

type DisconnectedFunc func(i *Interface) error

DisconnectedFunc is a callback called when an interface is disconnected

type Interface

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

Interface represents memif network interface

func (*Interface) Delete

func (i *Interface) Delete() (err error)

Delete deletes the interface

func (*Interface) Disconnect

func (i *Interface) Disconnect() (err error)

Disconnect disconnects the interface

func (*Interface) GetId

func (i *Interface) GetId() uint32

GetId returns interfaces id

func (*Interface) GetMemoryConfig

func (i *Interface) GetMemoryConfig() MemoryConfig

GetMemoryConfig returns interfaces active memory config. If interface is not connected the config is invalid.

func (*Interface) GetName

func (i *Interface) GetName() string

GetName returens interfaces name

func (*Interface) GetPeerName

func (i *Interface) GetPeerName() string

GetPeerName returns peer interfaces name

func (*Interface) GetPrivateData

func (i *Interface) GetPrivateData() interface{}

GetPrivateDate returns interfaces private data

func (*Interface) GetRemoteName

func (i *Interface) GetRemoteName() string

GetRemoteName returns the name of the application on which the peer interface exists

func (*Interface) GetRxQueue

func (i *Interface) GetRxQueue(qid int) (*Queue, error)

GetRxQueue returns an rx queue specified by queue index

func (*Interface) GetSocket

func (i *Interface) GetSocket() *Socket

GetSocket returns the socket the interface belongs to

func (*Interface) GetTxQueue

func (i *Interface) GetTxQueue(qid int) (*Queue, error)

GetRxQueue returns a tx queue specified by queue index

func (*Interface) IsConnected

func (i *Interface) IsConnected() bool

IsConnected returns true if the interface is connected

func (*Interface) IsConnecting

func (i *Interface) IsConnecting() bool

IsConnecting returns true if the interface is connecting

func (*Interface) IsMaster

func (i *Interface) IsMaster() bool

IsMaster returns true if the interfaces role is master, else returns false

func (*Interface) RequestConnection

func (i *Interface) RequestConnection() error

RequestConnection is used by slave interface to connect to a socket and create a control channel

type MemoryConfig

type MemoryConfig struct {
	NumQueuePairs    uint16 // number of queue pairs
	Log2RingSize     uint8  // ring size as log2
	PacketBufferSize uint32 // size of single packet buffer
}

MemoryConfig represents shared memory configuration

type MsgAddRegion

type MsgAddRegion struct {
	Index uint16
	Size  uint64
}

type MsgAddRing

type MsgAddRing struct {
	Flags          uint16
	Index          uint16
	Region         uint16
	Offset         uint32
	RingSizeLog2   uint8
	PrivateHdrSize uint16
}

type MsgConnect

type MsgConnect struct {
	// interface name
	Name [32]byte
}

type MsgConnected

type MsgConnected struct {
	// interface name
	Name [32]byte
}

type MsgDisconnect

type MsgDisconnect struct {
	Code   uint32
	String [96]byte
}

type MsgHello

type MsgHello struct {
	// app name
	Name            [32]byte
	VersionMin      uint16
	VersionMax      uint16
	MaxRegion       uint16
	MaxRingM2S      uint16
	MaxRingS2M      uint16
	MaxLog2RingSize uint8
}

type MsgInit

type MsgInit struct {
	Version uint16
	Id      uint32
	Mode    interfaceMode
	Secret  [24]byte
	// app name
	Name [32]byte
}

type Queue

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

Queue represents rx or tx queue

func (*Queue) GetEventFd

func (q *Queue) GetEventFd() (int, error)

GetEventFd returns queues interrupt event fd

func (*Queue) ReadPacket

func (q *Queue) ReadPacket(pkt []byte) (int, error)

ReadPacket reads one packet form the shared memory and returns the number of bytes read

func (*Queue) WritePacket

func (q *Queue) WritePacket(pkt []byte) int

WritePacket writes one packet to the shared memory and returns the number of bytes written

type Socket

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

Socket represents a UNIX domain socket used for communication between memif peers

func NewSocket

func NewSocket(appName string, filename string) (socket *Socket, err error)

NewSocket returns a new Socket

func (*Socket) AddListener

func (socket *Socket) AddListener(fd int) (err error)

AddListener adds a lisntener to the socket. The fd must describe a UNIX domain socket already bound to a UNIX domain filename and marked as listener

func (*Socket) Delete

func (socket *Socket) Delete() (err error)

Delete deletes the socket

func (*Socket) GetFilename

func (socket *Socket) GetFilename() string

GetFilename returns sockets filename

func (*Socket) NewInterface

func (socket *Socket) NewInterface(args *Arguments) (*Interface, error)

NewInterface returns a new memif network interface. When creating an interface it's id must be unique across socket with the exception of loopback interface in which case the id is the same but role differs

func (*Socket) StartPolling

func (socket *Socket) StartPolling(errChan chan<- error)

StartPolling starts polling and handling events on the socket, enabling communication between memif peers

func (*Socket) StopPolling

func (socket *Socket) StopPolling() error

StopPolling stops polling events on the socket