ethface

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: 20 Imported by: 0

README

ndn-dpdk/iface/ethface

This package implements Ethernet faces using DPDK ethdev as transport.

ethFace type represents an Ethernet face. Locator of an Ethernet face has the following fields:

  • scheme is set to "ether".
  • local and remote are MAC-48 addresses written in the six groups of two lower-case hexadecimal digits separated by colons.
  • local must be a unicast address.
  • remote may be unicast or multicast. Every face is assumed to be point-to-point, even when using a multicast remote address.
  • vlan (optional) is an VLAN ID in the range 0x001-0xFFF.
  • port (optional) is the port name as presented by DPDK. If omitted, local is used to search for a suitable port; if specified, this takes priority over local.
  • portConfig (optional) contains configuration for Port creation, considered on the first face on a port. See PortConfig type for details.

Port type organizes faces on the same DPDK ethdev. Each port can have zero or one Ethernet face with multicast remote address, and zero or more Ethernet faces with unicast remote addresses. Faces on the same port can be created and destroyed individually.

Receive Path

There are two receive path implementations. All faces on the same port must use the same receive path implementation.

rxFlow type implements a hardware-accelerated receive path. It uses one RX queue per face, and creates an rte_flow to steer incoming frames to that queue. An incoming frame is accepted only if it has the correct MAC addresses and VLAN tag. There is minimal checking on software side.

rxTable type implements a software receive path. It continuously polls ethdev RX queue 0 for incoming frames. Header of an incoming frame is matched against each face, and labeled with the matching face ID. If no match is found, drop the frame.

Port/face setup procedure is dominated by the choice of receive path implementation. Initially, the port attempts to operate with rxFlows. This can fail if the ethdev does not support rte_flow, does not support the specific rte_flow features used in EthFace_SetupFlow, or has fewer RX queues than the number of requested faces. If rxFlows fail to setup for these or any other reason, the port falls back to rxTable.

Send Path

EthFace_TxBurst function implements the send path. Currently, the send path only uses ethdev TX queue 0. It requires every outgoing packet to have sufficient headroom for the Ethernet header.

The send path is thread-safe only if the underlying DPDK PMD is thread safe, which generally is not the case. Normally, iface.TxLoop invokes EthFace_TxBurst from the same thread.

UDP and VXLAN Tunnel Face

UDP and VXLAN tunnels are supported through this package.

Locator of a UDP tunnel face has the following fields:

  • scheme is set to "udpe". The suffix "e" means "ethface"; it is added to differentiate from the "udp" scheme implemented in socketface package.
  • All fields in "ether" locator are inherited.
  • Both local and remote MAC addresses must be unicast.
  • localIP and remoteIP are local and remote IP addresses. They may be either IPv4 or IPv6, and must be unicast.
  • localUDP and remoteUDP are local and remote UDP port numbers.

Locator of a VXLAN tunnel face has the following fields:

  • scheme is set to "vxlan".
  • All fields in "udpe" locator are inherited.
  • localUDP and remoteUDP are destination port numbers; source port numbers are random.
  • vxlan is the VXLAN Network Identifier.
  • innerLocal and innerRemote are MAC addresses for inner Ethernet header.
  • maxRxQueues (optional) is the maximum number of RX queues. When using rxFlow in the NDN-DPDK forwarder, having multiple RX queues for the same face can alleviate FwInput bottleneck.

UDP and VXLAN tunnels can coexist with Ethernet faces on the same port. Multiple UDP and VXLAN tunnels can coexist if any of the following is true:

  • One of vlan, localIP, and remoteIP is different.
  • Both are UDP tunnels, and one of localUDP and remoteUDP is different.
  • Both localUDP and remoteUDP are different.
  • Both are VXLAN tunnels, and one of vxlan, innerLocal, and innerRemote is different.

Known limitations:

  • NDN-DPDK does not respond to Address Resolution Protocol (ARP) queries.

    • To allow incoming packets to reach NDN-DPDK, configure MAC-IP binding on the IP router.

      sudo ip neigh replace 192.0.2.1 lladdr 5e:c8:55:7a:c9:1f nud noarp dev eth1
sudo ip neigh replace 2001:0db8::3cfe lladdr 5e:c8:55:7a:c9:1f nud noarp dev eth1

    • For mlx5 driver and IPv4 only: add the IP address to the kernel using ip addr command, but do not create the VXLAN interface. Even if DPDK is controlling the Ethernet adapter, the kernel can still receive broadcast frames such as ARP queries and respond to them.

  • NDN-DPDK does not lookup IP routing tables or send ARP queries. To allow outgoing packets to reach the IP router, the remote field of the locator should be the MAC address of the IP router.

  • IPv4 and UDP checksum are computed through hardware offloads if available. In case the Ethernet adapter does not support checksum offloads,

    • IPv4 checksum can be computed in software.
    • UDP checksum cannot be computed and is set to zero, which is illegal in IPv6.

  • IPv4 options and IPv6 extension headers are not allowed. Incoming packets with these are dropped.

  • IPv4 fragments are not accepted.

  • If multiple RX queues are being used, NDNLPv2 reassembly does not work.

Memif Face

Shared memory packet interface (memif) is supported through this package.

Locator of a memif face has the following fields:

  • scheme is set to "memif".
  • socketName is the control socket filename. It must be an absolute path not exceeding 108 characters.
  • id is the interface identifier in the range 0x00000000-0xFFFFFFFF.

In the data plane:

  • Application must operate its memif interface in "client" mode.
  • Each packet must be an Ethernet frame carrying an NDNLPv2 frame.
  • Application must use Ethernet address F2:71:7E:76:5D:1C.
  • NDN-DPDK uses Ethernet address F2:6C:E6:8D:9E:34.

Documentation

Overview

Package ethface implements Ethernet faces using DPDK Ethernet devices.

Index

Constants

View Source 
const (
	DefaultRxQueueSize = 4096
	DefaultTxQueueSize = 4096
)

Limits and defaults.

View Source 
const (
	// MinVXLAN is the minimum VXLAN Network Identifier.
	MinVXLAN = 0x000000

	// MaxVXLAN is the maximum VXLAN Network Identifier.
	MaxVXLAN = 0xFFFFFF
)

Variables

View Source 
var (
	ErrIP        = errors.New("invalid IP address")
	ErrIPFamily  = errors.New("different address family in LocalIP and RemoteIP")
	ErrUnicastIP = errors.New("invalid unicast IP address")
	ErrUDPPort   = errors.New("invalid UDP port")
)

Error conditions.

View Source 
var (
	ErrNoPort = errors.New("EthDev not found")
)

Error conditions.

View Source 
var (
	ErrVXLAN = errors.New("invalid VXLAN Network Identifier")
)

Error conditions.

Functions

func LocatorCanCoexist 

func LocatorCanCoexist(a, b iface.Locator) bool

LocatorCanCoexist determines whether two locators can coexist on the same port.

func New 

func New(port *Port, loc ethLocator) (iface.Face, error)

New creates a face on the given port.

Types

type EtherLocator 

type EtherLocator struct {
	FaceConfig

	// packettransport.Locator contains MAC addresses.
	packettransport.Locator

	// Port is the EthDev name.
	//
	// During face creation:
	//  * If this is empty:
	//    * Face is created on an EthDev whose physical MAC address matches loc.Local.
	//    * Local MAC address of the face is set to loc.Local, i.e. same as the physical MAC address.
	//  * If this is non-empty:
	//    * Face is created on an EthDev whose name matches loc.Port.
	//    * Local MAC address of the face is set to loc.Local, which could differ from the physical MAC address.
	//  * In either case, if no matching EthDev is found, face creation fails.
	//
	// When retrieving face information, this reflects the EthDev name.
	Port string `json:"port,omitempty"`
}

EtherLocator describes an Ethernet face.

func (EtherLocator) CreateFace 

func (loc EtherLocator) CreateFace() (face iface.Face, e error)

CreateFace creates an Ethernet face.

func (EtherLocator) Scheme 

func (EtherLocator) Scheme() string

Scheme returns "ether".

type FaceConfig 

type FaceConfig struct {
	iface.Config

	// PortConfig specifies additional configuration for Port activation.
	// This is only used when creating the first face on an EthDev.
	PortConfig *PortConfig `json:"portConfig,omitempty"`

	// MaxRxQueues is the maximum number of RX queues for this face.
	// It is meaningful only if the face is using RxFlow dispatching.
	// It is effective in improving performance on VXLAN face only.
	//
	// Default is 1.
	// If this is greater than 1, NDNLPv2 reassembly will not work on this face.
	MaxRxQueues int `json:"maxRxQueues,omitempty"`

	// DisableTxMultiSegOffload forces every packet to be copied into a linear buffer in software.
	DisableTxMultiSegOffload bool `json:"disableTxMultiSegOffload,omitempty"`

	// DisableTxChecksumOffload disables the usage of IPv4 and UDP checksum offloads.
	DisableTxChecksumOffload bool `json:"disableTxChecksumOffload,omitempty"`
	// contains filtered or unexported fields
}

FaceConfig contains additional face configuration. They appear as input-only fields of EtherLocator.

type LocatorConflictError 

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

LocatorConflictError indicates that the locator of a new face conflicts with an existing face.

func (LocatorConflictError) Error 

func (e LocatorConflictError) Error() string

type MemifLocator 

type MemifLocator struct {
	memiftransport.Locator
}

MemifLocator describes a memif face.

func (MemifLocator) CreateFace 

func (loc MemifLocator) CreateFace() (iface.Face, error)

CreateFace creates a memif face.

func (MemifLocator) Scheme 

func (MemifLocator) Scheme() string

Scheme returns "memif".

type Port 

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

Port organizes EthFaces on an EthDev.

func FindPort 

func FindPort(ethdev ethdev.EthDev) *Port

FindPort returns a Port associated with given EthDev.

func ListPorts 

func ListPorts() (list []*Port)

ListPorts returns a list of active Ports.

func NewPort 

func NewPort(dev ethdev.EthDev, cfg PortConfig) (port *Port, e error)

NewPort opens a Port.

func (*Port) Close 

func (port *Port) Close() (e error)

Close closes the port.

func (*Port) Faces 

func (port *Port) Faces() (list []iface.Face)

Faces returns a list of active faces.

func (*Port) ImplName 

func (port *Port) ImplName() string

ImplName returns internal implementation name.

type PortConfig 

type PortConfig struct {
	// DisableRxFlow disables RxFlow implementation.
	DisableRxFlow bool `json:"disableRxFlow,omitempty"`

	// RxQueueSize is the hardware RX queue capacity.
	//
	// If this value is zero, it defaults to DefaultRxQueueSize.
	// It is also adjusted to satisfy driver requirements.
	RxQueueSize int `json:"rxQueueSize,omitempty"`

	// TxQueueSize is the hardware TX queue capacity.
	//
	// If this value is zero, it defaults to DefaultTxQueueSize.
	// It is also adjusted to satisfy driver requirements.
	TxQueueSize int `json:"txQueueSize,omitempty"`

	// MTU configures Maximum Transmission Unit (MTU) on the EthDev.
	// This excludes Ethernet headers, but includes VLAN/IP/UDP/VXLAN headers.
	// If this value is zero, the EthDev MTU remains unchanged.
	MTU int `json:"mtu,omitempty"`

	// DisableSetMTU skips setting MTU on the device.
	// Set to true only if the EthDev lacks support for setting MTU.
	DisableSetMTU bool `json:"disableSetMTU,omitempty"`
}

PortConfig contains Port creation arguments.

type UDPLocator 

type UDPLocator struct {
	// EtherLocator contains MAC addresses and EthDev specification.
	// loc.Remote must be a unicast address.
	EtherLocator

	// LocalIP is the local IP address.
	// It may be either IPv4 or IPv6.
	LocalIP net.IP `json:"localIP"`

	// RemoteIP is the remote IP address.
	// It may be either IPv4 or IPv6.
	RemoteIP net.IP `json:"remoteIP"`

	// LocalUDP is the local UDP port number.
	LocalUDP int `json:"localUDP"`

	// RemoteUDP is the remote UDP port number.
	RemoteUDP int `json:"remoteUDP"`
}

UDPLocator describes a UDP face.

func (UDPLocator) CreateFace 

func (loc UDPLocator) CreateFace() (face iface.Face, e error)

CreateFace creates a UDP face.

func (UDPLocator) Scheme 

func (UDPLocator) Scheme() string

Scheme returns "udpe".

func (UDPLocator) Validate 

func (loc UDPLocator) Validate() error

Validate checks Locator fields.

type VxlanLocator 

type VxlanLocator struct {
	// UDPLocator contains MAC addresses, EthDev specification, and UDP endpoints.
	// loc.LocalUDP and loc.RemoteUDP are interpreted as destination port numbers.
	UDPLocator

	// VXLAN is the VXLAN virtual network identifier.
	// This must be between MinVXLAN and MaxVXLAN.
	VXLAN int `json:"vxlan"`

	// InnerLocal is the inner local MAC address.
	// This must be a 48-bit unicast address.
	InnerLocal macaddr.Flag `json:"innerLocal"`

	// InnerRemote is the inner remote MAC address.
	// This must be a 48-bit unicast address.
	InnerRemote macaddr.Flag `json:"innerRemote"`
}

VxlanLocator describes an Ethernet VXLAN face.

func (VxlanLocator) CreateFace 

func (loc VxlanLocator) CreateFace() (face iface.Face, e error)

CreateFace creates a VXLAN face.

func (VxlanLocator) Scheme 

func (VxlanLocator) Scheme() string

Scheme returns "vxlan".

func (VxlanLocator) Validate 

func (loc VxlanLocator) Validate() error

Validate checks Locator fields.

Source Files

View all Source files

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.