netdev

README

Table of Contents

• Netdever
• Netdev Driver
• Netdev Driver Notes

Netdever

TinyGo's network device driver model comprises two Go interfaces: Netdever and Netlinker. This README covers Netdever.

The Netdever interface describes an L4/L3 network interface modeled after the BSD sockets. A netdev is a concrete implementation of a Netdever. See Netlinker for the L2 network interface.

A netdev can:

• Send and receive L4/L3 packets
• Resolve DNS lookups
• Get/set the device's IP address

TinyGo network drivers implement the Netdever interface, providing a BSD sockets interface to TinyGo's "net" package. net.Conn implementations (TCPConn, UDPConn, and TLSConn) use the netdev socket. For example, net.DialTCP, which returns a net.TCPConn, calls netdev.Socket() and netdev.Connect():

func DialTCP(network string, laddr, raddr *TCPAddr) (*TCPConn, error) {

        fd, _ := netdev.Socket(netdev.AF_INET, netdev.SOCK_STREAM, netdev.IPPROTO_TCP)

        netdev.Connect(fd, "", raddr.IP, raddr.Port)

        return &TCPConn{
                fd:    fd,
                laddr: laddr,
                raddr: raddr,
        }, nil
}

Setting Netdev

Before the app can use TinyGo's "net" package, the app must set the netdev using UseNetdev(). This binds the "net" package to the netdev driver. For example, setting the wifinina driver as the netdev:

	nina := wifinina.New(&cfg)
	netdev.UseNetdev(nina)

Netdev Driver Notes

See the wifinina and rtl8720dn for examples of netdev drivers. Here are some notes for netdev drivers.

Locking

Multiple goroutines may invoke methods on a net.Conn simultaneously, and since the net package translates net.Conn calls into netdev socket calls, it follows that multiple goroutines may invoke socket calls, so locking is required to keep socket calls from stepping on one another.

Don't hold a lock while Time.Sleep()ing waiting for a long hardware operation to finish. Unlocking while sleeping let's other goroutines make progress.

Sockfd

The netdev BSD socket interface uses a socket fd (int) to represent a socket connection (end-point). Each fd maps 1:1 to a net.Conn maps. The number of fds available is a hardware limitation. Wifinina, for example, can hand out 10 fds, representing 10 active sockets.

Testing

The netdev driver should minimally run all of the example/net examples.

Documentation

Index

• Constants
• Variables
• func UseNetdev(dev Netdever)
• type Netdever

Constants

const (
	AF_INET       = 0x2
	SOCK_STREAM   = 0x1
	SOCK_DGRAM    = 0x2
	SOL_SOCKET    = 0x1
	SO_KEEPALIVE  = 0x9
	SOL_TCP       = 0x6
	TCP_KEEPINTVL = 0x5
	IPPROTO_TCP   = 0x6
	IPPROTO_UDP   = 0x11
	// Made up, not a real IP protocol number.  This is used to create a
	// TLS socket on the device, assuming the device supports mbed TLS.
	IPPROTO_TLS = 0xFE
	F_SETFL     = 0x4
)

Variables

var (
	ErrHostUnknown = errors.New("Host unknown")
	ErrMalAddr     = errors.New("Malformed address")
)

GethostByName() errors

var (
	ErrFamilyNotSupported   = errors.New("Address family not supported")
	ErrProtocolNotSupported = errors.New("Socket protocol/type not supported")
	ErrStartingDHCPClient   = errors.New("Error starting DHPC client")
	ErrStartingDHCPServer   = errors.New("Error starting DHPC server")
	ErrNoMoreSockets        = errors.New("No more sockets")
	ErrClosingSocket        = errors.New("Error closing socket")
	ErrNotSupported         = errors.New("Not supported")
	ErrInvalidSocketFd      = errors.New("Invalid socket fd")
)

Socket errors

var ErrTimeout error = &timeoutError{}

Duplicate of non-exported net.errTimeout

Functions

func UseNetdev

func UseNetdev(dev Netdever)

Types

type Netdever

type Netdever interface {

	// GetHostByName returns the IP address of either a hostname or IPv4
	// address in standard dot notation
	GetHostByName(name string) (netip.Addr, error)

	// Addr returns IP address assigned to the interface, either by
	// DHCP or statically
	Addr() (netip.Addr, error)

	// Berkely Sockets-like interface, Go-ified.  See man page for socket(2), etc.
	Socket(domain int, stype int, protocol int) (int, error)
	Bind(sockfd int, ip netip.AddrPort) error
	Connect(sockfd int, host string, ip netip.AddrPort) error
	Listen(sockfd int, backlog int) error
	Accept(sockfd int) (int, netip.AddrPort, error)
	Send(sockfd int, buf []byte, flags int, deadline time.Time) (int, error)
	Recv(sockfd int, buf []byte, flags int, deadline time.Time) (int, error)
	Close(sockfd int) error
	SetSockOpt(sockfd int, level int, opt int, value interface{}) error
}