README
¶
i.MX Ethernet over USB driver
This Go package implements TCP/IP connectivity through Ethernet over USB
(CDC-ECM) on NXP i.MX SoCs, to be used with GOOS=tamago GOARCH=arm as supported by the
TamaGo framework for bare metal
Go on ARM SoCs.
The CDC-ECM Ethernet over USB driver is supported natively on Linux and macOS hosts while Windows requires using third-party drivers.
The package supports TCP/IP networking through gVisor (go branch)
tcpip
stack pure Go implementation.
The interface TCP/IP stack can be attached to the Go runtime by setting
net.SocketFunc to the interface Socket function:
iface, _ := usbnet.Init("10.0.0.1", "1a:55:89:a2:69:41", "1a:55:89:a2:69:42", 1)
net.SocketFunc = iface.Socket
See tamago-example for a full integration example.
Authors
Andrea Barisani
andrea.barisani@withsecure.com | andrea@inversepath.com
Andrej Rosano
andrej.rosano@withsecure.com | andrej@inversepath.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/imx-usbnet
Copyright (c) WithSecure Corporation
These source files are distributed under the BSD-style license found in the LICENSE file.
Documentation
¶
Overview ¶
Package usbnet implements TCP/IP connectivity through Ethernet over USB (CDC-ECM) on i.MX6 SoCs.
The CDC-ECM Ethernet over USB driver is supported natively on Linux and macOS hosts, while Windows requires third-party drivers.
The TCP/IP stack is implemented using gVisor pure Go implementation.
This package is only meant to be used with `GOOS=tamago GOARCH=arm` as supported by the TamaGo framework for bare metal Go on ARM SoCs, see https://github.com/usbarmory/tamago.
Index ¶
- Variables
- func ConfigureDevice(device *usb.Device, serial string)
- type Interface
- func (iface *Interface) Add(device *usb.Device, deviceIP string, deviceMAC string, hostMAC string) (err error)
- func (iface *Interface) DialContextTCP4(ctx context.Context, address string) (net.Conn, error)
- func (iface *Interface) DialTCP4(address string) (net.Conn, error)
- func (iface *Interface) DialUDP4(lAddr, rAddr string) (net.Conn, error)
- func (iface *Interface) EnableICMP() error
- func (iface *Interface) Init(deviceIP string, deviceMAC, hostMAC string) error
- func (iface *Interface) ListenerTCP4(port uint16) (net.Listener, error)
- func (iface *Interface) Socket(ctx context.Context, network string, family, sotype int, laddr, raddr net.Addr) (c interface{}, err error)
- type NIC
Constants ¶
This section is empty.
Variables ¶
var ( // MTU represents the Ethernet Maximum Transmission Unit MTU uint32 = 1500 // 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}, } )
var MaxPacketSize uint16 = 512
MaxPacketSize represents the USB data interface endpoint maximum packet size
Functions ¶
func ConfigureDevice ¶
ConfigureDevice configures a USB device with default descriptors for a CDC Ethernet (ECM) device, suitable for Add().
Types ¶
type Interface ¶
type Interface struct {
NICID tcpip.NICID
NIC *NIC
Stack *stack.Stack
Link *channel.Endpoint
// contains filtered or unexported fields
}
Interface represents an Ethernet over USB interface instance.
func (*Interface) Add ¶
func (iface *Interface) Add(device *usb.Device, deviceIP string, deviceMAC string, hostMAC string) (err error)
Add adds an Ethernet over USB configuration to a previously configured USB device, it can be used in place of Init() to create composite USB devices.
func (*Interface) DialContextTCP4 ¶
DialContextTCP4 connects to an IPv4 TCP address with support for timeout supplied by ctx.
func (*Interface) DialUDP4 ¶
DialUDP4 creates a UDP connection to the ip:port specified by rAddr, optionally setting the local ip:port to lAddr.
func (*Interface) EnableICMP ¶
EnableICMP adds an ICMP endpoint to the interface, it is useful to enable ping requests.
func (*Interface) Init ¶
Init initializes an Ethernte over USB interface (see ConfigureDevice() for its defaults) associating it to a gVisor link, a default NICID and TCP/IP gVisor Stack are set if not previously assigned.
func (*Interface) ListenerTCP4 ¶
ListenerTCP4 returns a net.Listener capable of accepting IPv4 TCP connections for the argument port.
type NIC ¶
type NIC struct {
// Host MAC address
HostMAC net.HardwareAddr
// Device MAC address
DeviceMAC net.HardwareAddr
// Link is a gVisor channel endpoint
Link *channel.Endpoint
// Device is the physical interface associated to the virtual one.
Device *usb.Device
// Rx is endpoint 1 OUT function, set by Init() to ECMRx if not
// already defined.
Rx func([]byte, error) ([]byte, error)
// Tx is endpoint 1 IN function, set by Init() to ECMTx if not already
// defined.
Tx func([]byte, error) ([]byte, error)
// Control is endpoint 2 IN function, set by Init() to ECMControl if
// not already defined.
Control func([]byte, error) ([]byte, error)
// contains filtered or unexported fields
}
NIC represents an virtual Ethernet instance.
func (*NIC) ECMControl ¶
ECMControl implements the endpoint 2 IN function.
func (*NIC) ECMRx ¶
ECMRx implements the endpoint 1 OUT function, used to receive Ethernet packet from host to device.
Source Files