NUSB(4) NUSB(4)
NAME
audio, disk, ether, kb, serial, ptp, usbd - Universal Serial
Bus drivers
SYNOPSIS
nusb/audio devid
nusb/cam [ -d ] devid
nusb/disk [ -d ] devid
nusb/ether [ -dD ] [ -t ethertype ] [ -a addr ] devid
nusb/kb [ -d ] devid
nusb/joy [ -d ] [ -b deadband ] devid
nusb/serial [ -d ] devid
nusb/ptp [ -dD ] devid
nusb/usbd [ -dD ]
DESCRIPTION
These programs drive USB devices of specific classes via
usb(3). Usually they are started by nusbrc(8) upon attach-
ment of the device to the bus. All drivers except usbd take
the decimal usb devid of the device they should handle as
their last argument. A driver's instance handles only one
device at a time.
Drivers that provide file systems make them available as
shares under /shr (see shr(3)) or /shr/usb (which is bound
after /dev by nusbrc(8)).
Options -d and -D trigger debug diagnostics and file system
debugging diagnostics for most drivers. Repeating any one of
these may increase verbosity.
Hubs
Usbd enumerates the tree of USB hubs and configures the
device on attachment. It provides a filesystem with the
files usbevent and usbhubctl (usually seen as /dev/usbevent
and /dev/usbhubctl).
When the usbevent file is read, it returns a 6-column,
space-separated line of text, one for each event. The
columns are: attach or detach followed by addr vid did csp
and hname. The addr is the decimal device address assigned.
Vid and did are formatted as 4 digit hexadecimal. Csp is
Page 1 Plan 9 (printed 12/21/24)
NUSB(4) NUSB(4)
the device class, subclass, protocol identifier formatted as
6 digit hexadecimal. Usbd assigns a stable device identi-
fier based on the device descriptor for hname. This informa-
tion is read by nusbrc(8) and the addr and hname are passed
to a suitable driver as devid in the form addr:hname.
The usbhubctl file provides per-port power switching control
(PPPS) by writing the following 4-column command format:
portpower or portindicator followed by hub, port and the
state on or off where hub selects the hub device (using its
device address addr or hname) and port is the decimal port
number (counting from 1).
Keyboards and mice
Kb supports USB keyboards and mice either as separate USB
devices or as a single combined USB device. Scan codes from
the keyboard are sent to /dev/kbin to let kbdfs(8) process
them. Mouse events are sent to /dev/mousein in the same
way. A file /dev/hidNctl supports setting keyboard repeat
and delay setting, the unit is milliseconds.
Joysticks
Joy parses data packets from a given endpoint and prints
back any changes in the device's axes or buttons. Buttons
are identified via an integer id.
Directional buttons are reported either as buttons or axes
with 3 positions: 0, 128, and 255 for left (or up), center
and right (or down) respectively. Messages are in the form
axis id position.
A deadband in the range of [0.0,1.0] can be set with the -b
option to filter out input below a threshold on all analog
axes.
On/off buttons are reported as either down or up respec-
tively. Messages are in the form down|up id.
Disks
Disk configures and manages USB mass storage devices. It
provides a file system (usually seen under /dev) that
includes one directory per storage device, named sdUN[.M] in
correspondence with the USB device identifier and the stor-
age unit number (or LUN). The LUN is omitted for single lun
devices.
The storage device directory contains the usual files served
by sd(3): data, raw, and ctl.
The ctl file supplies the device geometry and partitions
when read. Ptp configures and exposes a camera's (and often
a mobile device's) storage to allow transferring data via
Page 2 Plan 9 (printed 12/21/24)
NUSB(4) NUSB(4)
the Picture Transfer Protocol (PTP).
Ethernet
Ether handles USB ethernet devices. The file system provided
is compatible with ether(3) and added to the share usbnet
(see shr(3)) which is bound after /net by nusbrc(8) so the
device will appear as /net/etherUN. Without specifying the
-t option, the device is assumed to be a CDC compliant eth-
ernet communication device. Other devices might require set-
ting an explicit ethertype, such as rndis, smsc, url,
lan78xx, aue, a88772, a88178, or a88179 (see nusbrc(8)). On
devices that support it, the mac address can be set using
the -a addr option.
Serial and JTAG ports
Serial provides a file system (usually seen under /dev) that
includes one directory per USB serial port, named eiaUN or
eiaUN[.M]. In this directory there are two files, eiaU,
similar to eiaN in uart(3), and eiaUctl, which admits writes
in the same format as eiaNctl in uart(3). Reading from
eiaUctl gives the serial port's settings in the same format
as eiaNstatus in uart(3). Options are similar to those of
disk.
JTAG ports are similar but the files are named jtag and
jtagctl.
Audio devices
Audio configures and manages a USB audio device. It imple-
ments a file system (normally seen under /dev), exporting
audioUN , volumeUN and other files that have the same seman-
tics as audio(3)).
Camera devices
Cam configures and exposes a USB camera device's capabili-
ties, implementing a file system compatible with camv(1),
under a directory named camN[.M]. It provides the following
files: desc, showing all of the device's internal descrip-
tors and their values; format, listing admissible image res-
olutions and framerates; ctl, the picture settings control
file; frame, which captures and outputs a single video frame
as an image(6) file; and video, streaming video in a preset
format, resolution and framerate. In particular, reading
from the ctl file yields a space-separated list of parameter
settings, where the second and third columns correspond to
key-value pairs, and an optional fourth column corresponds
to the range of possible numerical values (formatted as
minimum/increment/maximum). The same pairs can be written
to the file to configure the camera. Currently, only the
YUY2 video format is supported.
SOURCE
Page 3 Plan 9 (printed 12/21/24)
NUSB(4) NUSB(4)
/sys/src/cmd/nusb
SEE ALSO
camv(1), joy(1), audio(3), ether(3), mouse(3), sd(3),
uart(3), usb(3), shr(3), image(6), nusbrc(8), kbdfs(8)
HISTORY
Joy first appeared in 9front (March, 2014).
Cam first appeared in 9front (March, 2018).
BUGS
The various device drivers are generic USB drivers and may
work only for certain devices of each class.
USB ATA storage devices are not supported.
The serial driver works only for the Prolific chip and Ftdi,
and control of the dcd and dsr signals and some of the extra
features are not implemented. For Ftdi, only the Sheevaplug
and Guruplug have been tried. There is support for the EHCI
debug port, but it loses bytes.
USB video format settings cannot be changed while camv(1) is
running, and must be set manually by writing them to
cam(4)'sctl file before starting the viewer.
Page 4 Plan 9 (printed 12/21/24)