gnet

README

Bare metal Go TCP/IP connectivity

This Go package implements TCP/IP connectivity through a generic network interface to be used with GOOS=tamago as supported by the TamaGo framework for bare metal Go.

The package bridges generic network device and stack interfaces, which on GOOS=tamago can be attached to the Go runtime by setting net.SocketFunc to the interface Socket function.

Support for the following pure Go network stacks is provided:

• gVisor (go branch) tcpip stack.
• lneto networking library

The following packages provide compatible network devices:

• devcpu: Microchip CPU port module
• enet: NXP i.MX ENET Ethernet controller
• gvnic: Google Compute Engine Virtual Ethernet
• uefi: UEFI Simple Network
• usbnet: Ethernet over NXP i.MX USB through tamago nxp/usb
• vnet: VirtIO network device through tamago virtio

Package documentation

Examples

// TamaGo UEFI Simple Network interface
nic, _ := &x64.UEFI.Boot.GetNetwork{}

// gnet interface with gvisor stack
iface := gnet.Interface{
	Stack: NewGVisorStack(1),
}

// gnet interface with lneto stack
iface := gnet.Interface{
	Stack: NewLnetoStack(nil),
}

// initialize IP, MAC, Gateway
_ = iface.Init(nic, "10.0.0.1/24", "", "10.0.0.2")

// Go runtime hook
net.SocketFunc = iface.Stack.Socket

See the following projects for full integration examples of each supported network device:

• i.MX ENET/USB: tamago-example (mx6ullevk, imx8mpevk, usbarmory targets)
• VirtIO: tamago-example (cloud_hypervisor, firecracker, microvm targets)
• gVNIC: tamago-sev-example
• UEFI: tamago-sev-example, go-boot

Authors

Andrea Barisani
andrea@inversepath.com

Andrej Rosano
andrej@inversepath.com

Patricio Whittingslow
graded.sp{at}gmail{dot}com

Documentation

The package API documentation can be found on pkg.go.dev.

For more information about TamaGo see its repository and project wiki.

License

tamago | https://github.com/usbarmory/go-net
Copyright (c) The go-net authors. All Rights Reserved.

These source files are distributed under the BSD-style license found in the LICENSE file.

Documentation

Overview

Package gnet implements TCP/IP connectivity through a generic NetworkDevice interface and TCP/IP Stack.

The package provides GVisorStack as pure Go Stack implementation using gVisor.

This package is designed for, but not limited to, use with `GOOS=tamago` as supported by the TamaGo framework for bare metal Go, see https://github.com/usbarmory/tamago.

Index

• Constants
• Variables
• type GVisorStack
  • func NewGVisorStack(nicid tcpip.NICID) *GVisorStack
  • func (g *GVisorStack) Configure(mac net.HardwareAddr, ip netip.Prefix, gw netip.Addr) (err error)
  • func (g *GVisorStack) EnableICMP() error
  • func (g *GVisorStack) HardwareAddress() (net.HardwareAddr, error)
  • func (g *GVisorStack) ListenerTCP4(port uint16) (net.Listener, error)
  • func (g *GVisorStack) RecvInboundPacket(buf []byte) error
  • func (g *GVisorStack) SetWriteNotify(notifier func(buf []byte))
  • func (g *GVisorStack) Socket(ctx context.Context, network string, family, sotype int, laddr, raddr net.Addr) (c interface{}, err error)
  • func (g *GVisorStack) WriteOutboundPacket(buf []byte) (int, error)
• type Interface
  • func (iface *Interface) Init(addr string, mac string, gateway string) (err error)
  • func (iface *Interface) Start(ctx context.Context) error
• type LnetoConfig
  • func DefaultLnetoStackConfig() *LnetoConfig
• type LnetoStack
  • func NewLnetoStack(cfg *LnetoConfig) *LnetoStack
  • func (ls *LnetoStack) Configure(mac net.HardwareAddr, ip netip.Prefix, gw netip.Addr) error
  • func (ls *LnetoStack) EnableICMP() error
  • func (ls *LnetoStack) HardwareAddress() (net.HardwareAddr, error)
  • func (ls *LnetoStack) RecvInboundPacket(buf []byte) error
  • func (ls *LnetoStack) SeedNeighbor(addr netip.Addr, mac [6]byte) error
  • func (ls *LnetoStack) SetWriteNotify(cb func(buf []byte))
  • func (ls *LnetoStack) Socket(ctx context.Context, network string, family, sotype int, laddr, raddr net.Addr) (c interface{}, err error)
  • func (ls *LnetoStack) WriteOutboundPacket(buf []byte) (int, error)
• type NetworkDevice
• type Stack

Constants

const (
	// MTU represents the Maximum Transmission Unit.
	MTU = 1500

	// EthernetMinimumSize is the minimum size of a valid ethernet frame.
	EthernetMinimumSize = 14

	// EthernetMaximumSize is the maximum size of a valid ethernet frame.
	EthernetMaximumSize = 18
)

Variables

var (
	// NICID represents the default gVisor NIC identifier
	NICID = tcpip.NICID(1)

	// DefaultStackOptions represents the default gVisor Stack configuration
	DefaultStackOptions = stack.Options{
		NetworkProtocols: []stack.NetworkProtocolFactory{
			ipv4.NewProtocol,
			arp.NewProtocol},
		TransportProtocols: []stack.TransportProtocolFactory{
			tcp.NewProtocol,
			icmp.NewProtocol4,
			udp.NewProtocol},
	}
)

Types

type GVisorStack

type GVisorStack struct {
	Stack *stack.Stack
	Link  *channel.Endpoint

	NICID tcpip.NICID
	// contains filtered or unexported fields
}

GVisorStack implements Stack using the gvisor.dev/gvisor package.

func NewGVisorStack

func NewGVisorStack(nicid tcpip.NICID) *GVisorStack

NewGVisorStack returns a gvisor stack ready to configure with the given tcpip.NICID.

func (*GVisorStack) Configure

func (g *GVisorStack) Configure(mac net.HardwareAddr, ip netip.Prefix, gw netip.Addr) (err error)

Configure implements Stack.Configure.

func (*GVisorStack) EnableICMP

func (g *GVisorStack) EnableICMP() error

EnableICMP implements Stack.

func (*GVisorStack) HardwareAddress

func (g *GVisorStack) HardwareAddress() (net.HardwareAddr, error)

HardwareAddress implements Stack.HardwareAddress.

func (*GVisorStack) ListenerTCP4

func (g *GVisorStack) ListenerTCP4(port uint16) (net.Listener, error)

ListenerTCP4 returns a net.Listener capable of accepting IPv4 TCP connections for the argument port on this stack.

func (*GVisorStack) RecvInboundPacket

func (g *GVisorStack) RecvInboundPacket(buf []byte) error

RecvInboundPacket implements Stack.RecvInboundPacket.

func (*GVisorStack) SetWriteNotify

func (g *GVisorStack) SetWriteNotify(notifier func(buf []byte))

SetWriteNotify implements Stack.SetWriteNotify.

func (*GVisorStack) Socket

func (g *GVisorStack) Socket(ctx context.Context, network string, family, sotype int, laddr, raddr net.Addr) (c interface{}, err error)

Socket implements Stack.Socket.

func (*GVisorStack) WriteOutboundPacket

func (g *GVisorStack) WriteOutboundPacket(buf []byte) (int, error)

WriteOutboundPacket implements Stack.WriteOutboundPacket.

type Interface

type Interface struct {
	// Stack represents a [Stack] instance.
	Stack Stack
	// HandleStackErr defines an optional function to handle [Stack]
	// errors.
	HandleStackErr func(err error, tx bool)

	// NetworkDevice represents a [NetworkDevice] instance.
	NetworkDevice NetworkDevice
}

Interface bridges a Stack and a NetworkDevice, driving packet I/O between them.

func (*Interface) Init

func (iface *Interface) Init(addr string, mac string, gateway string) (err error)

Init initializes an Interface bridging its Stack and NetworkDevice.

If Stack is not set a default implementation is initialized, the stack is configured with the CIDR address and hardware (MAC) address.

If NetworkDevice is not set the Stack is left without a transmission callback and Interface.Start has no effect.

The gateway may or may not be provided, an empty MAC will result in a random Stack.HardwareAddress.

func (*Interface) Start

func (iface *Interface) Start(ctx context.Context) error

Start begins processing of incoming packets, the function receives packets through NetworkDevice.Receive and handles them through Stack.RecvInboundPacket, it should never return.

type LnetoConfig

type LnetoConfig struct {
	// Hostname specifies the hostname to use for DHCP. Optional.
	Hostname string
	// MaxActiveTCPPorts is a heap-memory guardrail to limit number of simultaneous open TCP ports.
	MaxActiveTCPPorts uint16
	// MaxActiveUDPPorts is the same guardrail for UDP. It must be non-zero for
	// anything UDP-based to work at all: with no slots every socket fails with
	// [lneto.ErrExhausted]. That silently takes out DNS resolution and SNTP,
	// and a node whose clock stays at the epoch cannot verify any certificate —
	// so plain-looking HTTPS failures ("certificate is not yet valid") trace
	// back to this number. A port costs on the order of 64 bytes.
	MaxActiveUDPPorts uint16
	// MaxListenerConns limits the amount of open [net.Listener] connections that can be established
	// in simultaneous. Each newly allocated listener conn consumes 2*TCPBufferSize*MaxListenerConns so
	// this can have drastic memory consumption impact.
	MaxListenerConns uint16

	// determine size of each TCP rx/tx ring buffers.
	TCPBufferSize int
	// BackoffStack sets the time between protocol checks for completion like DHCP, NTP, DNS etc. via the blocking APIs.
	// BackoffStack can use a channel driven approach behind the scenes
	// and return [lneto.BackoffFlagNop] to signal backoff yield is
	// implemented by the callback and that no sleep should be performed.
	BackoffStack lneto.BackoffStrategy
	// NewBackoffTCP returns a per-connection backoff strategy for TCP read/write retries.
	// If nil, a short-exponential default is used (or [lneto.BackoffFlagGosched] on GOMAXPROCS=1).
	NewBackoffTCP func() lneto.BackoffStrategy
	// TCPQueueSize sets the number of packets that can be sent out and not be acknowledged before halting new packet tx.
	TCPQueueSize int
	// GatewayHardwareAddr statically sets the gateway MAC. When zero the
	// gateway is resolved over ARP at Configure time. Networks with a
	// deterministic address plan know it up front; setting it skips the
	// resolve entirely.
	GatewayHardwareAddr [6]byte
}

LnetoConfig provides configuration options to better optimize the LnetoStack.

func DefaultLnetoStackConfig

func DefaultLnetoStackConfig() *LnetoConfig

DefaultLnetoStackConfig returns an LnetoConfig ready for use with NewLnetoStack with sane configuration parameters.

type LnetoStack

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

LnetoStack implements Stack with the lneto networking package.

func NewLnetoStack

func NewLnetoStack(cfg *LnetoConfig) *LnetoStack

NewLnetoStack returns a stack using the Lneto userspace networking library.

func (*LnetoStack) Configure

func (ls *LnetoStack) Configure(mac net.HardwareAddr, ip netip.Prefix, gw netip.Addr) error

Configure sets the MAC address, IP prefix and gateway. Gateway may be invalid.

func (*LnetoStack) EnableICMP

func (ls *LnetoStack) EnableICMP() error

EnableICMP registers an ICMP handler on the stack.

func (*LnetoStack) HardwareAddress

func (ls *LnetoStack) HardwareAddress() (net.HardwareAddr, error)

HardwareAddress returns the MAC address of the NIC.

func (*LnetoStack) RecvInboundPacket

func (ls *LnetoStack) RecvInboundPacket(buf []byte) error

RecvInboundPacket delivers an inbound packet to the stack.

func (*LnetoStack) SeedNeighbor

func (ls *LnetoStack) SeedNeighbor(addr netip.Addr, mac [6]byte) error

SeedNeighbor pre-populates the neighbor table with a static IP→MAC mapping; see xnet.StackAsync.SeedNeighbor. Requires a Configure'd stack.

func (*LnetoStack) SetWriteNotify

func (ls *LnetoStack) SetWriteNotify(cb func(buf []byte))

SetWriteNotify registers a callback invoked when outbound data is ready.

func (*LnetoStack) Socket

func (ls *LnetoStack) Socket(ctx context.Context, network string, family, sotype int, laddr, raddr net.Addr) (c interface{}, err error)

Socket creates a network socket bound to laddr and connected to raddr.

func (*LnetoStack) WriteOutboundPacket

func (ls *LnetoStack) WriteOutboundPacket(buf []byte) (int, error)

WriteOutboundPacket dequeues one outbound packet into buf, returning bytes written.

type NetworkDevice

type NetworkDevice interface {
	// Receive receives a single Ethernet frame from a network adapter.
	Receive(buf []byte) (n int, err error)
	// Transmit transmits a single Ethernet frame to a network adapter.
	Transmit(buf []byte) (err error)
}

NetworkDevice represents a generic network device interface capable of receiving and transmitting raw Ethernet frames.

type Stack

type Stack interface {
	// Configure sets the NIC ID, MAC address, IP prefix and gateway.
	// Gateway may be invalid.
	Configure(mac net.HardwareAddr, ip netip.Prefix, gw netip.Addr) error
	// HardwareAddress returns the MAC address of the NIC.
	HardwareAddress() (net.HardwareAddr, error)
	// EnableICMP registers an ICMP handler on the stack.
	EnableICMP() error
	// Socket creates a network socket bound to laddr and connected to raddr.
	Socket(ctx context.Context, network string, family, sotype int, laddr, raddr net.Addr) (c interface{}, err error)
	// SetWriteNotify registers a callback invoked when outbound data is ready.
	// The argument buffer if present can be used by the callback to fulfill data exchange.
	SetWriteNotify(cb func(auxbuf []byte))
	// WriteOutboundPacket dequeues one outbound packet into buf, returning bytes written.
	WriteOutboundPacket(buf []byte) (int, error)
	// RecvInboundPacket delivers an inbound packet to the stack.
	RecvInboundPacket(buf []byte) error
}

Stack is the interface for a network stack implementation. It manages a single NIC and provides socket-level networking.