Peripheral-side USB support for NetBSD
H IROYUKI B ESSHOGenetec corp.
bsh@NetBSD.org

Abstract
Some hardware platforms that run NetBSD have type-B
receptacles and USB client controllers, allowing them toact as USB devices.
Currently, the NetBSD kernel doesn’t have genericsupport for the peripheral side of USB. This paper describes a new framework for NetBSD to help implement
functionality as a USB device on those platforms.

1

Introduction

NetBSD has supported USB for many years, but it has
been limited to host-side functionality. Many hardware
platforms that can run NetBSD have some hardware
components to act as USB devices, including:• USB type-B receptacle. (or, micro-AB receptacle)• USB client controller, and related external circuits.
These are often found on embedded platforms. The
client controller is also named as ‘USB device controller’or ‘USB peripheral controller’. They are often found as
sub-components in SoCs, and there are also specialized
LSIs that can be connected to a CPU’s local bus.
In order to utilize those hardware components and become a USB device, some software needs to be written.
This includes:• a driver to control USB client controller• code to handle the USB protocol, for enumerationand configuration• the implementation of the actual functionality as a
USB device
OpenBSD introduced a framework to help implement
those software components in 2007 called ‘usbf’. Linuxalso has such a framework called ‘Gadgets’.

I have implemented a framework for NetBSD to support the peripheral side of USB, partly derived fromOpenBSD’s.

2 Terms
The following terms are defined by the USB specification
and are included here to help facilitate this discussion:
USB function A USB function transmits or receives
data or control information over the bus. Typically,a function is implemented as a separate peripheraldevice, but a physical package may implement multiple USB functions and an embedded hub with single USB port.
From the viewpoint of system software, a USB
function is same as a USB device.
USB interface A USB interface is a related set of endpoints that present a single feature of the USB function to the host.
A USB function can have multiple USB interfaces
as shown in Figure 2. All USB interfaces in a USB
function share single USB address.
Device endpoint An endpoint is a uniquely identifiable
portion of a USB device that is the terminus of acommunication flow between the host and device.
Compound device A USB device that has multiple
USB functions in it. (Figure 1)
Composite device A USB device that has multiple USB
interfaces that are controlled independently of eachother.

3 Components in the framework
The framework has the following components:

To send/receive USB packets to/from the host, the USBP
and USB interface drivers access the controller through acommon interface so that they can be independent of thetype of controllers.
In the kernel configuration file shown in Figure 3, a
usbp device is attached to a client controller device, andUSB interface drivers are attached to the usbp device.

Hub

USB (physical) device

USB device

Hub

USB Function
USB Function

USB Function

4 USB device and interface
Non-compound USB device(Device = Function)

Compound USB device

Figure 1: Compound device
Host side

Peripheral side

4.1 Choosing the USB device to become
With our framework, the platform can act as any kind of
USB device. The kind of USB device can be chosen byattaching USB interface drivers to USBP. In Figure 3, the
FTDI emulation interface is attached to USBP. Different
interfaces can be attached to USBP as in Figure 4, and inthat case, the platform provides Ethernet emulation overUSB to the host.

USB device
USB device driver

Pipes

4.2 Composite device

Endpoint
Endpoint
Endpoint

Endpoint
USB device driver

Endpoint

Interface

Interface

Endpoint
Interface

Load drivers
USB System Software(USB driver)

When two or more USB interface drivers are attached
to USBP, it configures the device as a composite device
as defined in the USB specification. The kernel configuration in Figure 5 will create a composite device thatconsists of USB mass storage and Ethernet emulation.

Endpoint
Control pipe

Endpoint #0

Figure 2: USB Interfaces and endpoints

4.3 Limitation on multiple USB interfaces
Although any number of USB interface drivers can be
attached to USBP, it has some limitations on building a
multi-interface device. There are two classes of limitations:• Limitations related to endpoints

USBP Driver for the peripheral side of the USB protocol. It handles the USB protocol on the control pipe.
This includes, for example, enumeration and configuration.
USB interface drivers Drivers for the peripheral sideof USB interfaces. These drivers implement thefunctionality of USB devices, such as USB serial
adapters, communication-class devices, mass storage devices, human interface devices, audio, video,
etc.
Client controller drivers Drivers for client controllers.
These drivers send USB packets to and receive USB
packets from the USB host through the USB client
controller. There are many kind of USB client controllers on the market, and they vary in design.

• Limitations set by non-cooperative USB interfaces
4.3.1 Endpoint limitations
The USB specification defines that USB devices can haveup to 16 endpoints. The USB host connects a pipe to a
device’s endpoint and use it for communication flow between the host and the device. Among the 16 endpoints,
endpoint #0 is special and used for USB device configuration. A pipe to an endpoint #0 is called a control
pipe. Some USB devices use control pipes for normal
data transactions.
As USB pipes cannot be shared among interfaces1 , thenumber of total endpoints used by all interfaces in thedevice must be less than 15 excluding the control pipe.
Also note that pipes are unidirectional.
1 except for control pipes

pxaudc0 at obio0
usbp0 at pxaudc0
upftdi * at usbp0# USB client controller on PXA250# peripheral - side USB support# emulates FTDI USB serial adapter
Figure 3: Example device tree in kernel configuration

cdcef * at usbp0# CDC ECM
Figure 4: Another kernel configuration example

In addition, even if the USB specification allows 16
endpoints per device, USB client controllers may nothave all of them implemented. Some controllers provide
fewer than 16 endpoints.
Some USB client controllers set specific purposes toeach endpoint. For example, PXA250’s2 client controller
dedicates endpoints #1, 6, 11 to bulk IN pipes, and #4, 9,
14 to isochronous OUT pipes (see Table 1). So if interface drivers require 4 bulk IN pipes total, they can not be
configured in one device on the platforms with PXA250,
even though the total number of endpoints required by
USB interfaces is below 16.
transfer typecontrolbulk
bulk
isochronous
isochronousinterrupt

direction
IN
OUT
IN
OUT
IN

endpoints
0
1, 6, 112, 7, 123, 8, 134, 9, 145, 10, 15

Table 1: Endpoints of PXA250 client controller
4.3.2

Cooperative USB interfaces‘Cooperative USB interface’ is not a term defined in the
USB specification. It is introduced here for this discussion.
USB interfaces are cooperative when they:• are identified by class codes in interface descriptors,
and• don’t require exclusive use of the control pipe (pipe#0) for them.
Some USB devices, such as USB serial devices use
bulk pipes for data transfer, and a control pipe for changing their mode. Thus, they are ‘non-cooperative’.
USB devices that have vendor-specific class codes andare identified by vendor ID and product ID are noncooperative. They require a specific host-side driver.
2 ARM based SoC by Marvell, formerly Intel

Also, USB devices identified by class code in their device descriptors are non-cooperative either.
Any number of cooperative interfaces can form a composite device as long as they satisfy the endpoint limitations.
Two or more non-cooperative interfaces cannot coexist in a single USB device, because they insist on acting as an entire USB device rather than as a single interface in a device.
One non-cooperative USB interface and some cooperative USB interfaces may be able to co-exist in one USB
device, but it may require special handling in a host-side
driver.
4.3.3 Attaching many USB interfaces to USBP
Any number of USB interfaces can be attached to USBP.
Because of the limitations discussed above, however,
USBP may not build up a USB device consisting of all
USB interfaces attached to it. USBP selects as many
USB interfaces as possible to construct a USB device,
and ignores the remaining interfaces.
Thus, priorities among attached interfaces need to be
set. In the current implementation, an interface attachedlater has higher priority.

5 Transform
The functionality of the USB device implemented using
USBP framework is defined by USB interface drivers attached to USBP. That can be changed by attaching/detaching USB interfaces while the peripheral-side platform is running. In other words, that USB device cantransform to a different device without rebooting the kernel with a different configuration.
A USB device can transform by:• loading/unloading kernel modules for USB interface drivers.
• attaching/detaching USB interface drivers to USBP
via drvctl

usbp0 at pxaudc ? # peripheral - side USB support
upmass * at usbp0 # mass storage
cdcef * at usbp0 # CDC ECM
Figure 5: Composite device

5.1

Example use-case

1. The kernel starts with USBP and DFU (Device
Firmware Upgrade).
• Host sees DFU device.

7 USBP’s interface for USB interface
drivers
In this section, we list some of API functions provided
by USBP. The API may change as the implementation of
the framework is now under testing and debugging.

2. Kernel detaches the USB interface driver.
• As no active USB interface is attached, USBP
turns off the pull-up register on the USB dataline.
• Host notices that the USB device is disconnected.
3. Kernel attaches umass interface driver to USBP.

7.1

A USB interface driver calls usbp add interface
shown in Figure 7 to add its interface to the USB device
with the following parameters:• information to build a device descriptor (structusbp device info).

• USBP configures a new USB device, thenturns on the pull-up.
• Host sees an USB device connected, and finds
it is a mass storage device.
In this example, the USB device first appeared as
DFU, and then transforms into mass storage device.

6

This information may be used when the USB interface is actually configured into the USB device.
For a composite device, which has multiple USB interfaces, the device information from the interface
with the highest priority is used.
• information about the
usbp interface spec)

1. Open /dev/usbpN
2. Issue ioctls to give necessary information about the
USB interfaces to USBP, and build up descriptors
for the interface.
3. Assign endpoints using ioctl.
4. Open /dev/usbpN.MM for endpoint access, where
MM is an endpoint number.
5. Read/write endpoints to communicate with the host.
When /dev/usbpN is closed by the process, the USB
interfaces built are removed from the USB device.

interface.

(struct

This is used to build the USB interface descriptor.
Types of endpoints required by the interface are also
included.

USB interfaces in userland

In addition to USB interfaces implemented by in-kernel
device drivers, the framework also supports USB interfaces implemented by userland processes.
Userland programs implement the USB interface byfollowing steps:

usbp add interface• callback functions called by USBP.

7.2

usbp delete interface

A USB interface can be removed from the USB device
by calling usbp delete interface shown in Figure 6.
USBP re-calculates USB descriptors and notify thehost if needed.

7.3 String descriptor
The USB interface driver passes some strings to be
used as human readable descriptions of the device via
usbp add interface.
These strings are presented to the host through USB
string descriptors. USBP manages strings provided by
USB interface drivers, assigns string IDs, and send themon the host’s request.
Conversion to UTF-16 is also done by USBP.

1
2

usbd status usbp delete interface ( struct usbp device ∗ ,struct usbp interface ∗);Figure 6: API function usbp delete interface

8

Differences from OpenBSD implementation

Host side

Peripheral side

usbd_bus

I started this project by porting OpenBSD’s usbf(4)driver, and later modified it significantly. The reasonsfor the significant changes were to:
1. support composite devices and add an ability totransform,
2. handle endpoint limitations imposed by client controllers, and3. share source code between host-side and peripheralside of USB.

8.1

usbd_device

usbf_bus

cdce(4)

cdcef(4)usbf_device

usbd_interface

usbf_interface

usbd_endpoint

usbf_endpoint

usbd_pipe

usbf_pipe

usbd_xfer

usb(4)

usbf(4)

usbf_xfer

Sharing codes with host-side

In OpenBSD’s implementation, usbf(4) device consistsof many objects such as usbf bus, usbf endpoint,usbf pipe, usbf xfer, etc., and they are very similar to objects found in host-side implementation suchas usbd bus, usbd endpoint, usbd pipe, usbd xfer,and so on. Figure 8 illustrates the OpenBSD’s implementation. It is natural for us to want to reuse code for thehost side.
Sharing host-side source code was also necessary inorder to make logical drivers for USB devices run onboth sides of USB. One example of such logical drivers
is ucom(4). The ucom(4) driver provides common functionality for USB serial adapters, and it is designed towork with usbd * objects defined in the host-side USB
subsystem. So it was impossible for OpenBSD’s implementation to let ucom(4) run on peripheral-side of USB.
In our implementation, we add super-class objects forboth side of USB as shown in Figure 10. This madeucom(4) usable for both of host side and peripheral side.

9

Further development

9.1

Client controllers

Only one client controller is supported so far:
• Client controller in PXA250
More controllers should be supported, including ones in
ARM based SoCs such as i.MX3 and OMAP4 .
3 ARM based SoC by Freescale
4 Texas Instruments

Figure 8: USB related objects in OpenBSD

9.2 USB InterfacessCurrently, the following USB interfaces have been implemented:
cdcef(4) CDC Ethernet emulation.
upftdi(4) emulates FTDI USB serial.
More USB interfaces should be implemented. The current targets are mass storage and DFU.

9.3 USB On-The-Go
USB OTG is a supplemental specification of USB thatallows platforms become both host and device sharing
one USB Micro-AB receptacle.
Many modern platforms have micro-AB receptacles.
When two platforms with those receptacles are connected, they need to decide to take either role—host or
peripheral—according to the OTG specification.

10 On going study
10.1 Comparison to Linux’s Gadget
Linux has a framework for peripheral-side USB named
as ‘Gadget’. I haven’t looked at it closely yet.
Comparison to Gadget will help improve our framework.

Host side

tences were added by me after their review.

Peripheral side

usbd_bus

usbf_bus
ucom for
peripheralsideucom(4)

usbd_device

usbd_interface

usbf_interface

can't use

usbd_endpoint

uftdi(4)usbf_device

FTDI emulationin peripheral side

usbd_pipe

usbf_endpoint

References[1] USB Implementers Forum, Inc. (2000). Universal
Serial Bus Revision 2.0 Specification[2] USB Implementers Forum, Inc. (2010). Universal
Serial Bus Class Definitions for Communications
Devices, Revision 1.2 (Errata 1)

usbf_pipe
usb(4)

usbd_xfer

usbf(4)

usbf_xfer

Figure 9: Difficult to use ucom(4) for both side
Peripheral side

Host sideshared by both side
usbd_bus

deviceusbp_device

usbd_device

interface

usbd_interface

usbp_interface
usbd_endpointucom(4)

usbd_pipe
usbp(4)uftdi(4)usb(4)

usbd_xfer

upftdi(4)Figure 10: Sharing USB related objects and ucom(4)11 Conclusion
This paper presented a new framework for NetBSD tosupport peripheral-side USB. With this framework, we
can make platforms with NetBSD run as USB devices,with fairly small amount of new source code. This will
be helpful for developing embedded systems.

Acknowledgment
I started this project by porting OpenBSD’s usbf(4) andcdcef(4) drivers to NetBSD. They were initially written
by Uwe Stühler.
I would like to thank Taylor R. Campbell, Greg Oster,and Masanobu Saitoh for reviewing this paper, suggesting improvements, and fixing many grammatical errors.
If you still find broken English in this paper, those sen-

[3] USB Implementers Forum, Inc. (2007). Universal Serial Bus Micro-USB Cables and Connectors
Specification Revision 1.01

1 /∗2
∗ i n f o r m a t i o n u s e d t o b u i l d USB d e v i c e d e s c r i p t o r .
3∗/4 struct usbp device info {5
int16 t class id ;6
int16 t subclass id ;7
int protocol ;8
int vendor id ;9
int product id ;10
int bcd device ;/∗ d e v i c e r e l e a s e number i n BCD ∗/11const char ∗ manufacturer name ;12
const char ∗ product name ;13
const char ∗ s e r i a l ;/∗ d e v i c e ’ s s e r i a l number ∗/14 } ;
15
16 #d e f i n e USBP ID UNSPECIFIC
( −1)
17
18 /∗
19
∗ r e q u i r e m e n t s o f an e n d p o i n t u s e d by t h e i n t e r f a c e
20∗/
21 s t r u c t u s b p e n d p o i n t r e q u e s t {22
uint8 t direction ;/∗ UE DIR IN o r UE DIR OUT ∗/23
uint8 t attributes ;/∗ T r a n s f e r t y p e :24
UE ISOCHROMOUS , UE BULK , UE INTERRUPT ∗/25
u int packetsize ;26/∗ need more f o r i s o c h r o n o u s ∗/27 } ;
2829 /∗30∗ i n f o r m a t i o n u s e d t o b u i l d an i n t e r f a c e d e s c r i p t o r
31∗/
32 s t r u c t u s b p i n t e r f a c e s p e c {33
uint8 t class id ;34
uint8 t subclass id ;35
uint8 t protocol ;36
enum USBP PIPE0 USAGE {37
USBP PIPE0 NOTUSED , /∗ t h i s i n t e r f a c e d o e s n ’ t u s e p i p e #0 ∗/38
USBP PIPE0 SHARED , /∗ p i p e#0 i s s h a r e d among i n t e r f a c e s ,39
by means o f i n t e r f a c e number i n t h e p a c k e t s ∗/40
USBP PIPE0 EXCLUSIVE /∗ t h i s i n t e r f a c e r e q u i r e s an41
e x c l u s i v e u s e o f p i p e#0 ∗/42} pipe0 usage ;43
const char ∗ d e s c r i p t i o n ;44
u i n t 8 t n u m e n d p o i n t s ; /∗ t h e number o f e n d p o i n t s u s e d by45
t h i s i n t e r f a c e e x c l u d i n g ep0 . ∗/46
struct usbp endpoint request endpoints [ ] ;47 } ;
48
49 u s b d s t a t u s u s b p a d d i n t e r f a c e (50
struct usbp device ∗ ,/∗ USB d e v i c e managed by USBP ∗/51
struct usbp interface ∗ ,/∗ USB i n t e r f a c e t o add ∗/52
const s t r u c t u s b p d e v i c e i n f o ∗ ,/∗ i n f o r m a t i o n t o b u i l d a d e v i c e d e s c r i p t o r ∗/53
c o n s t s t r u c t u s b p i n t e r f a c e s p e c ∗ , /∗ i n f o r m a t i o n t o b u i l d an i n t e r f a c e54
d e s c r i p t o r and e n d p o i n t d e s c r i p t o r s ∗/55
c o n s t s t r u c t u s b p i n t e r f a c e m e t h o d s ∗ ) ; /∗ c a l l b a c k f u n c t i o n s ∗/Figure 7: API function usbp add interface