Peripheral-side USB support for
NetBSD

Hiroyuki Bessho(別所 博之)bsh@NetBSD.org,bessho@genetec.co.jp

What is this?
●With this framework, Platforms that run
NetBSD kernel can act as USB devices, suchas USB serials, mass storage, printers,
Ethernet adapters, etc.

Host

PeripheralSoC
NetBSD
kernelUSB HostController

This side of
USB have been
supported formany years.

USB cable

USB
ClientController

NetBSD
kernelNow we support
this side ofUSB.

USB Bus
Host
Address=3
USB HostController

Address=7
USB Device

HubAddress=5
USB Device

RootHub

Address=6Address=2
USB Device

Address=4
USB Device

USB Device

Host (or Hub)Physical Connection
Type-B
receptacle

RVBus (+5V)

D+D-(ID)

RGND

Logical Connection
Host side

Peripheral side
USB device

USB device driver
Pipes

Endpoint #7
Endpoint #12
Endpoint

Loaddrivers
USB System Software(USB driver)Endpoint
Control pipe

Endpoint #0

InterfaceComposite device
Host side

Peripheral side
USB device

USB device driver

Pipes

Endpoint
Endpoint
Endpoint
Endpoint

USB device driver

Endpoint

Interface

Interface

Endpoint
Loaddrivers
USB System Software(USB driver)InterfaceEndpoint
Control pipe

Endpoint #0

USB descriptors
Device Descriptor
Device ID,Vendor ID,
Device Class, ...

Configuration Descriptor
Interface Descriptor
Interface Class Id, ...

Configuration Descriptor
Endpoint Descriptor
Configuration Descriptor
Endpoint Descriptor

Interface Descriptor
Interface Descriptor
String Descriptor

Standard Device Descriptor

From USB 2.0 specification.

Composite device and host-sidedrivers(1)
Determined by
Device ID,
Device ClassID, etc.

Host side

USB device driver
for the device
as-a whole

Peripheral side

USB device

Pipes
Endpoint
Endpoint

Interface

Endpoint
Loaddrivers
USB System Software(USB driver)Interface
Endpoint
Control pipe

Endpoint #0

Composite device and host-sidedrivers(2)
Determined byInterface ID,
Interface ClassID, etc.

Host side

Peripheral side

USB device
USB device driver
for the interface APipes

Endpoint
USB device driver
for the interface B

Endpoint

Interface A

Endpoint
Loaddrivers
USB System Software(USB driver)Interface B
Endpoint
Control pipe

Endpoint #0

Design Goal of our Framework●Common tasks among many USB devices aredone in the framework.
– Let framework users to focus on codes forfunctionality of interfaces they want to implement.
●The framwork and interface implementation
should be independent of the characteristic of
USB client controllers.

Design Goal of our Framework●Interfaces can be implemented either as– in-kernel device drivers, or– userland programs●

Design Goal of our Framework●

A USB device implemented using thisframework can “transform” into a different USB
device without rebooting into an another kernel
binary.
– Interfaces can be attached to/detached from theUSB device on-the-fly.
●Design Goal of our Framework●

USB Interface implementation can be used tomake a simple USB device, or to form acomposite device combined with other interface
implementations.

components in the framework
●

USBP

●

Client controller drivers●

USB interface drivers●

Userland interface to USBP.

●

Userland programs for USB interfaces.

components in the framework
UserlandKernel space

USBP

USB
ClientController

USB client
controller
dirverI/F to USBP

USB
interface
implemented
as a inkernel
device driverread/write/
ioctl

USB
interface
implemented
as auserland
program.

components in the framework
●

●

USBP
– logical driver for peripheral-side USB support.
– handles USB protocol on control pipe, such as
enumeration and configuration.
– implements functionality of the USB devices
Client controller drivers– there are many kind of client controllers– control send/receive of USB packets.
– USBP and interface drivers access to the controller
through a common interface.

components in the framework●●●

USB interface drivers– USB serial, communication device class, massstorage, human interface device, audio, video, etc.
Userland interface to USBP.
– in order to implement USB interface functionality
as userland programs.
Userland programs for USB interfaces.

Kernel configuration for peripheralside support
in config(5)pxaudc0 at obio0
usbp0 at pxaudc0# Client controller driver# USB Peripheral-side support

cdcef0 at usbp0# CDC Ethernet model

upftdi0 at usbp0
ucom* at upftdi?

# FTDI USB serial emulation

usbpusr* at usbp?

#Userland gateway for USBP

Multiple interfaces and a composite
deviceDevice tree in kernel

Implemented USB composite device
DeviceUSBPInterface driver #1

Interface driver #2…..
Interface driver #N

Interface #1

×Interface #2

API for USB interface drivers
Note: the API is now being debugged and may be modified in the future.
It is already modified from the version in my paper.

usbd_status usbp_add_interface(struct usbp_device *device,
const struct usbp_add_iface_request *request,
const struct usbp_interface_methods *iface_methods,
struct usbp_interface **interface);struct usbp_add_iface_request
used to build the device descriptor
struct usbp_add_iface_request {characteristic of the interface
struct usbp_device_info devinfo;
struct usbp_interface_spec ispec;
struct usbp_endpoint_request endpoints[];};
type and directions of required endpoints●

struct usbp_device_info
struct usbp_device_info {int16_t class_id;/* can be USBP_ID_UNSPECIFIED */uint8_t subclass_id;
uint8_t protocol;
int vendor_id;/* can be USBP_ID_UNSPECIFIED */uint16_t product_id;
uint16_t bcd_device;/* device release number in BCD */const char *manufacturer_name;const char *product_name;const char *serial;/* device's serial number */};●●

Used to build a device descriptor.
If class_id is USBP_ID_UNSPECIFIED, thevalue from other interface or the default value isused.

struct usbp_interface_spec
struct usbp_interface_spec {uByte class_id;
uByte subclass_id;
uByte protocol;
const char *description;enum USBP_PIPE0_USAGE {USBP_PIPE0_NOTUSED,USBP_PIPE0_SHARED,USBP_PIPE0_EXCLUSIVE} pipe0_usage;
uint8_t num_endpoints;};●

Used to build aninterface descriptor

Used to build a interface descriptor, and torequest endpoints to be used for the interface.

struct usbp_endpoint_request
struct usbp_endpoint_request {uint8_t dir;/* UE_DIR_IN or UE_DIR_OUT*/
uint8_t attributes; /* Transfer type: UE_ISOCHROMOUS,
UE_BULK,
UE_INTERRUPT */uint8_t epnum; /* endpoint number. recommended to set 0 */bool optional;
u_int packetsize;/* need more for isochronous */};

●

●

●

request an endpoint for a interface.
if the client controller can not provide the non-optional endpoint, theinterface is not used.
when epnum is 0, platform choose a suitable endpoint. You can explicitly
specify endpoint number here, but it is not recommended.

struct usbp_interface_methodsstruct usbp_interface_methods {usbd_status (* configured)(struct usbp_interface *);usbd_status (* unconfigured)(struct usbp_interface *);usbd_status (* handle_device_request)(
struct usbp_interface *,usb_device_request_t *,void **);
usbd_status (* fixup_idesc)(
struct usbp_interface *,usb_interface_descriptor_t *);};●●callback methods from USBP to interface drivers.
“configured” method is called when the interface isactually put in the device. In this method, the interface
driver starts real task.

example sequence
Interface #2

Interface #1

USBP

kernelattachconfig_search, andconfig_attach
attachusbp_add_interface
attachusbp_add_interfacebuild a USB device
configured
open pipes, etc.

Other APIs●

usbp_delete_interface●

usbp_get_endpoint●

usbp_open_pipe●

usbd_alloc_xfer●

usbd_alloc_buffer●

usbd_free_xfer●

usbd_setup_xfer●

usbd_get_xfer_status●

usbd_transfer●

usbd_abort_pipe●….

Userland gateway●/dev/usbp0/ctl●/dev/usbp0/0, /dev/usbp0/1 … for endpoints.

●

ioctl(USBP_IOC_ADDIFACE)●ioctl(USBP_GETEP)– blocks until the interface is selected in the device.

●

read/write on endpoint nodes.

Current implementation

https://github.com/bsh-git/netbsd-usb-peripheral.git

Comparison●

OpenBD– usbf(4)●Linux– Gadget– http://www.linux-usb.org/gadget/Demonstration●

FTDI USB serial adapter●

CDC Ethernet emulation (port of cdcef(4) of O)●

Umass in the userland (not working yet)Future development●

Clean up the code , get reviewed, commit it intothe codebase.

●More client controllers●More interface drivers●DMA support●USB 2.0, 3.0●

Questions?

Acknowledgement●●●I started this project by porting OpenBSD's
usbf(4) to NetBSD, which was written by Uwe
stühler and other OpenBSD developers.
Taylor R. Campbell, Greg Oster, and Masanobu
Saitoh for reviewing my paper.
Dan Harris and co-workers at Genetec corp. forgood advice in my presentation rehearsal.