gokm/netdev

import "gokm/netdev"

Package netdev creates network interfaces whose driver is Go code.

By default interfaces are point-to-point IP devices (no link-layer header, no ARP), like a TUN device: Transmit gets each IPv4/IPv6 packet the kernel routes out of the interface, and Receive injects packets into the kernel as if they arrived on it. With Ethernet set they are Ethernet devices instead, like a TAP device: Transmit and Receive carry whole frames (destination MAC, source MAC, EtherType, payload; no FCS), and the kernel does ARP and IPv6 neighbor discovery over them.

type driver struct{ iface *netdev.Interface }

func (d *driver) Transmit(pkt []byte) {
	reply := handle(pkt)     // pkt is only valid during the call
	d.iface.Receive(reply)
}

d := &driver{}
d.iface = &netdev.Interface{Name: "go%d", Driver: d}
err := netdev.Register(d.iface)

By default Transmit runs in process context, from a workqueue: packets are queued (up to 1000; more are dropped and counted as tx_dropped). With AtomicTransmit it runs directly in the kernel’s transmit path (atomic context, BH disabled): much lower latency, but Transmit must not block (no sync.Mutex, channels, time.Sleep or blocking calls: use atomics or kernel.SpinLock), and an allocation can fail with an “out of memory” panic if the heap is full (the packet is then dropped). While a garbage collection is in progress packets take the workqueue path instead. Interfaces are unregistered automatically at module exit.

Index#

Functions#

func Register#

func Register(i *Interface) error

Register creates and registers the interface. Name is updated with the name the kernel assigned.

Types#

type Driver#

type Driver interface {
	// Transmit receives an outgoing IP packet. pkt is kernel memory valid
	// only during the call: copy what you keep.
	Transmit(pkt []byte)
}

Driver handles packets sent through the interface.

type Interface#

type Interface struct {
	// Name is the interface name; a "%d" in it is replaced with the first
	// free number (e.g. "go%d" -> go0).
	Name   string
	Driver Driver
	// MTU defaults to 1500.
	MTU int
	// AtomicTransmit runs Transmit directly in the transmit path; see the
	// package documentation.
	AtomicTransmit bool
	// Ethernet makes it an Ethernet device, with hardware address MAC
	// (random if zero). MTU excludes the 14-byte header.
	Ethernet bool
	MAC      [6]byte

}

Interface is a network interface.

func (*Interface) HardwareAddr#

func (i *Interface) HardwareAddr() [6]byte

HardwareAddr returns the current MAC address of an Ethernet interface (it can be changed with ip link set … address). Process context only.

func (*Interface) Receive#

func (i *Interface) Receive(pkt []byte) error

Receive injects an IPv4 or IPv6 packet (an Ethernet frame on Ethernet interfaces) into the kernel as if it arrived on the interface. The data is copied.

func (*Interface) TransmitStats#

func (i *Interface) TransmitStats() (direct, deferred uint64)

TransmitStats returns how many packets Transmit got directly in the transmit path (AtomicTransmit) and how many through the workqueue.

func (*Interface) Unregister#

func (i *Interface) Unregister()

Unregister removes the interface.

type Opener#

type Opener interface{ Open() error }

Optional Driver interfaces, called when the interface is brought up and down (ip link set … up/down).

type Stopper#

type Stopper interface{ Stop() error }

Optional Driver interfaces, called when the interface is brought up and down (ip link set … up/down).