term% cat index.txt USB(4) Kernel Interfaces Manual USB(4)
NAME
audio, ccid, disk, ether, kb, print, probe, serial, usbeject, usbfat: -
Universal Serial Bus device drivers
SYNOPSIS
usb/kb [ -dkm ] [ -a accel ] [ dev ... ]
usb/disk [ -Dd ] [ -m mnt ] [ -s srv ] [ dev ... ]
usbfat: [ disk ... ]
usbeject [ 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/ccid [ -d ] usb/probe
DESCRIPTION
These programs drive USB devices of specific classes via usb(3). Usu‐
ally they are started by usbd(4) upon attachment of the device to the
bus. Less often, users start them manually, depending on usbd(4)'s
configuration. Usually, kb and disk are started by usbd and other pro‐
grams are started by hand.
Without arguments, the drivers handle all the devices (of the appropri‐
ate USB class) found on the bus. To make a driver handle only certain
devices, supply as arguments the paths for the directories of the de‐
vices (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. Repeating any one of these may in‐
crease verbosity.
To help locate devices of interest, probe lists all the USB devices
available, including those with no driver started.
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 correspondence with the usb device num‐
ber 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 script usbfat: mounts the FAT file systems in the DOS partitions of
the named disks; if none, it mounts those file systems found at
/dev/sdU*.*/data. When more than one partition is found, a suffix is
appended to the disk name to identify the partition number. The script
usbeject undoes the effect. If no argument is given, it unmounts all
USB disks. An argument sdUN unmounts all partitions from disk with USB
target N.
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 Ethernet device is etherUN
where N is the device name. When started manually, the file interface
is mounted at /net as is customary.
Serial and JTAG ports
Serial provides a file system (usually mounted at /dev) that includes
one directory per USB serial port, named eiaUN or eiaUN.M. In this di‐
rectory 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 for‐
mat 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
Usbaudio configures and manages a USB audio device. It implements a
file system, normally mounted on /dev, but this can be changed with -m,
containing files volume, audioctl, audio, and audioin. The names vol‐
ume and audio maintain backward compatibility with the Soundblaster
driver.
The -V option (verbose) causes audio to print information about the de‐
vice 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 for‐
mat of volume is compatible with the Soundblaster 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 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 omit‐
ted when they are not available or not applicable. The resolution for
speed is reported as 1 (one) if the sampling frequency is continuously
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.
Ccid
Ccid discovers and configures SIM or SAM cards using the CCID standard.
It provides a file system (usually mounted at /dev) that includes three
files, ctl, raw and rpc. Reading from ctl a description of the smart‐
card reader capabilities is printed. raw is just intended for debug‐
ging. Reads and writes to the raw file send and receive raw CCID pack‐
ets. Smart cards identify themselves by giving out an ATR, an array of
characters describing the card uniquely. Users of the driver write the
ATR to the rpc file and are blocked until a card with that ATR is seen.
From then on they can do ICC RPCs using whatever language the smart
card speaks. A small write cancels an outstanding RPC.
The driver takes care of powering the card adequately, based on its
ATR, and tunnelling the RPCs through the USB device. Only slot 0 is
supported.
When the smartcard disappears, all reads and write fail until the file
is reopened and a new ATR is written to it.
SOURCE
/sys/src/cmd/usb
SEE ALSO
kbin(3), mouse(3), sd(3), uart(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.
USB ATA storage devices are not supported.
The Ethernet device works only for certain ASIX-based cards and for CDC
devices. 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 Ftdi, and con‐
trol of the dcd and dsr signals and some of the extra features are
unimplemented. For Ftdi, only the Sheevaplug and Guruplug have been
tried. There is support for the EHCI debug port, but it loses bytes.
USB(4)