USB(4) USB(4)
NAME
audio, disk, ether, kb, print, probe, serial, usbfat: -
Universal Serial Bus device drivers
SYNOPSIS
usb/kb [ -dkm ] [ -a accel ] [ dev ... ]
usb/disk [ -Dd ] [ -m mnt ] [ -s srv ] [ dev ... ]
usbfat: [ disk ... ]
usb/audio [ -dpV ] [ -m mnt ] [ -s srv ] [ -v vol ] [ dev ]
usb/ether [ -Dd ] [ -m mnt ] [ -s srv ] [ dev ... ]
usb/serial [ -Dd ] [ -m mnt ] [ -s srv ] [ dev ... ]
usb/print [ -d ] [ dev ... ]
usb/probe
DESCRIPTION
These programs drive USB devices of specific classes via
usb(3). Usually they are started by usbd(4) upon attachment
of the device to the bus. Less often, users start them man-
ually, depending on usbd(4)'s configuration. Usually, kb
and disk are started by usbd and other programs are started
by hand.
Without arguments, the drivers handle all the devices (of
the appropriate USB class) found on the bus. To make a
driver handle only certain devices, supply as arguments the
paths for the directories of the devices (actually of their
zero endpoints).
Drivers that provide file systems accept options -s and -m
to instruct them to post a 9P connection at srv(3) with the
given name and/or to mount themselves at mnt. When embedded
into usbd these options may not be used. In this case, the
file tree supplied by the device driver is available through
the file system provided by usbd, usually mounted at /dev
and reachable through the 9P connection posted at /srv/usb.
Options -d and -D present on most drivers trigger debug
diagnostics and file system debugging diagnostics. Repeat-
ing any one of these may increase verbosity.
To help locate devices of interest, probe lists all the USB
devices available, including those with no driver started.
Page 1 Plan 9 (printed 5/19/12)
USB(4) USB(4)
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 the kernel process
them. Mouse events are sent to /dev/mousein in the same
way.
The following options are understood:
-a Accelerate the mouse to level n (similar to the kernel
mouse driver acceleration).
-k Serve just the keyboard (and not the mouse).
-m Serve just the mouse (and not the keyboard).
Disks
Disk configures and manages USB mass storage devices. It
provides a file system (usually seen at /dev) that includes
one directory per storage device, named sdUN.M in correspon-
dence with the usb device number and the storage unit number
(or LUN). For example, LUN number 2 on /dev/usb/ep3.0 can
be accessed through /dev/sdU3.2.
The storage device directory contains the usual files served
by sd(3): data, raw, and ctl.
The ctl file supplies the device geometry when read.
The convenience script usbfat: mounts the FAT file system in
the DOS partition of the named disks; if none, it mounts
those file systems found at /dev/sdU*.*/data.
Printers
Print provides a single file can be written to print on a
USB printer. Options are similar to those of disk. The file
is also bound at /dev/lp as is customary.
Ethernet adapters
Ether provides a file interface similar to that of ether(3)
for each USB Ethernet adapter found. The name of an Ether-
net device is etherUN where N is the device name. When
started manually, the file interface is mounted at /net as
is customary.
Serial ports
Serial provides a file system (usually mounted at /dev) that
includes one directory per USB serial port, named eiaUN. In
this directory there are two files, eiaUN/data, similar to
eiaN in eia(3), and eiaUN/ctl. Ctl admits writes in the
same format as eiaNctl in eia(3). Reading from ctl gives the
serial port's settings in the same format as eiaNstatus in
eia(3). Options are similar to those of disk.
Page 2 Plan 9 (printed 5/19/12)
USB(4) USB(4)
Audio devices
Usbaudio configures and manages a USB audio device. It
implements a file system, normally mounted on /dev, but this
can be changed with the -m option, with files volume,
audioctl, audio, and audioin. The names volume and audio
maintain backward compatibility with the Soundblaster
driver.
The -V option (verbose) causes usbaudio to print information
about the device on startup. The -s option specifies a name
for a file descriptor to be posted in /srv. The -v options
sets initial volume.
Reading volume or audioctl yields the device's settings.
The data format of volume is compatible with the Sound-
blaster and produces output in this format:
audio out 65
treb out 0
bass out 0
speed out 44100
This file can be written using the same syntax. The keyword
`out' may be omitted. Settings are given as percentages of
the range, except for speed which is in Hz.
The file audioctl provides more information, using up to 6
columns of 12 characters each. From left to right, the
fields are: control name, in or out, current value, minimum
value, maximum, and resolution. There are 3, 5, or 6 columns
present. Maxima and resolution are omitted when they are
not available or not applicable. The resolution for speed
is reported as 1 (one) if the sampling frequency is continu-
ously variable. It is absent if it is settable at a fixed
number of discrete values only.
When all values from audioctl have been read, a zero-length
buffer is returned (the usual end-of-file indication). A
new read will then block until one of the settings changes,
then report its new value.
The file audioctl can be written like volume.
Audio data is written to audio and read from audioin. The
data format is little-endian, samples ordered primarily by
time and secondarily by channel. Samples occupy the minimum
integral number of bytes. Read and write operations of
arbitrary size are allowed.
SOURCE
/sys/src/cmd/usb
Page 3 Plan 9 (printed 5/19/12)
USB(4) USB(4)
SEE ALSO
eia(3), kbin(3), mouse(3), sd(3), usb(3), usbd(4), partfs(8)
BUGS
The various device drivers are generic USB drivers and may
work only for certain devices on each class. The Ethernet
device works only for certain ASIX-based cards and for CDC
devices. ATA storage devices are not supported. Both the
Ethernet and printer drivers have not been tested and it is
likely they will fail. The serial driver works only for the
Prolific chip, and control of the dcd and dsr signals and
some of the extra features are unimplemented.
Not heavily exercised yet. The entire set of drivers is new
and therefore potentially unreliable. A list of working
devices must be compiled.
Page 4 Plan 9 (printed 5/19/12)