harvey/sys/man/4/usb

.TH USB 4
.SH NAME
audio,
disk,
ether,
kb,
print,
probe,
usbfat:
\- Universal Serial Bus device drivers
.SH SYNOPSIS
.B usb/kb
[
.B -dkm
] [
.B -a
.I accel
] [
.I dev ...
]
.PP
.B usb/disk
[
.B -Dd
]
[
.B -m
.I mnt
]
[
.B -s
.I srv
]
[
.I dev ...
]
.PP
.B usbfat:
[
.I disk ...
]
.PP
.B usb/audio
[
.B -dpV
] [
.B -m
.I mnt
] [
.B -s
.I srv
] [
.B -v
.I vol
] [
.I dev
]
.PP
.B usb/ether
[
.B -Dd
]
[
.B -m
.I mnt
]
[
.B -s
.I srv
]
[
.I dev ...
]
.PP
.B usb/print
[
.B -d
]
[
.I dev ...
]
.PP
.B usb/probe
.SH DESCRIPTION
These programs drive USB devices of specific classes via
.IR usb (3).
Usually they are started by
.IR usbd (4)
upon attachment of the device to the bus.
Less often, users start them manually, depending on
.IR usbd (4)'s
configuration.
Usually,
.I kb
and
.I disk
are started by
.I usbd
and other programs are started by hand.
.PP
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).
.PP
Drivers that provide file systems accept options
.B -s
and
.B -m
to instruct them to post a 9P connection at
.IR srv (3)
with the given name and/or to mount themselves at
.IR mnt .
When embedded into
.IR 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
.IR usbd ,
usually mounted at
.B /dev
and reachable through the 9P connection posted at
.BR /srv/usb .
.PP
Options
.B -d
and
.B -D
present on most drivers trigger debug diagnostics and
file system debugging diagnostics.
Repeating any one of these may increase verbosity.
.PP
To help locate devices of interest,
.I probe
lists all the USB devices available,
including those with no driver started.
.SS Keyboards and mice
.I 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
.B /dev/kbin
to let the kernel process them.
Mouse events are sent to
.B /dev/mousein
in the same way.
.PP
The following options are understood:
.TF -k
.TP
.B \-a
Accelerate the mouse to level
.I n
(similar to the kernel mouse driver acceleration).
.TP
.B \-k
Serve just the keyboard (and not the mouse).
.TP
.B \-m
Serve just the mouse (and not the keyboard).
.SS Disks
.I Disk
configures and manages USB mass storage devices. It
provides a file system (usually seen at
.BR /dev )
that includes one directory per storage device, named
.BI sdU N . M
in correspondence with the usb device number and the storage
unit number (or LUN).
For example, LUN number 2 on
.B /dev/usb/ep3.0
can be accessed through
.BR /dev/sdU3.2 .
.PP
The storage device directory contains the usual files
served by
.IR sd (3):
.BR data ,
.BR raw ,
and
.BR ctl .
.PP
The
.B ctl
file supplies the device
geometry when read.
.PP
The convenience script
.B usbfat:
mounts the FAT file system in the DOS partition of the named
.IR disk s;
if none, it mounts those file systems found at
.BR /dev/sdU*.*/data .
.SS Printers
.I Print
provides a single file can be written to print on a USB printer.
Options are similar to those of
.IR disk .
The file is also bound at
.B /dev/lp
as is customary.
.SS Ethernet adapters
.I Ether
provides a file interface similar to that of
.IR ether (3)
for each USB Ethernet adapter found.
The name of an Ethernet device is
.BI etherU N
where
.I N
is the device name.
When started manually, the file interface is mounted at
.B /net
as is customary.
.SS Audio devices
.I Usbaudio
configures and manages a USB audio device.
It implements a file system,
normally mounted on
.BI /dev ,
but this can be changed with the
.B \-m
option, with files
.BR volume ,
.BR audioctl ,
.BR audio ,
and
.BR audioin .
The names
.B volume
and
.B audio
maintain backward compatibility with the Soundblaster driver.
.PP
The
.B \-V
option (verbose)
causes usbaudio to print information about the device on startup.
The
.B \-s
option specifies a name for a file descriptor to be posted in
.BR /srv .
The
.B \-v
options sets initial
.IR volume .
.PP
Reading
.B volume
or
.B audioctl
yields the device's settings.
The data format of
.B volume
is compatible with the Soundblaster and produces output in this
format:
.IP
.EX
audio out 65
treb out 0
bass out 0
speed out 44100
.EE
.PP
This file can be written using the same syntax.
The keyword
.L out
may be omitted.
Settings are given as percentages of the range,
except for speed which is in Hz.
.PP
The file
.B audioctl
provides more information, using up to 6 columns of 12 characters each.
From left to right, the fields are:
.IR "control name" ,
.I in
or
.IR out ,
.IR "current value" ,
.IR "minimum value" ,
.IR maximum ,
and
.IR 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
.I 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.
.PP
When all values from
.B audioctl
have been read, a zero-length buffer is returned
(the usual end-of-file indication).
A new
.I read
will then block until one of the settings changes,
then report its new value.
.PP
The file
.B audioctl
can be written like
.BR volume .
.PP
Audio data is written to
.B audio
and read from
.BR 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.
.SH SOURCE
.B /sys/src/cmd/usb
.SH "SEE ALSO"
.IR kbin (3),
.IR mouse (3),
.IR sd (3),
.IR usb (3),
.IR usbd (4)
.SH 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.
.PP
Not heavily exercised yet.
The entire set of drivers is new and therefore potentially unreliable.
A list of working devices must be compiled.