shithub: riscv

ref: a54fcac01609be9438f6fb05b4da4be01c303383
dir: /sys/man/4/nusb/

View raw version
.TH NUSB 4
.SH NAME
audio,
disk,
ether,
kb,
serial,
ptp,
usbd - Universal Serial Bus drivers
.SH SYNOPSIS
.B nusb/audio
.I devid
.PP
.B nusb/cam
[
.B -d
]
.I devid
.PP
.B nusb/disk
[
.B -d
]
.I devid
.PP
.B nusb/ether
[
.B -dD
] [
.B -t
.I ethertype
] [
.B -a
.I addr
]
.I devid
.PP
.B nusb/kb
[
.B -d
]
.I devid
.PP
.B nusb/joy
[
.B -d
]
.I devid
.PP
.B nusb/serial
[
.B -d
]
.I devid
.PP
.B nusb/ptp
[
.B -dD
]
.I devid
.PP
.B nusb/usbd
[
.B -dD
]
.SH DESCRIPTION
These programs drive USB devices of specific classes via
.IR usb (3).
Usually they are started by
.IR nusbrc (8)
upon attachment of the device to the bus. All drivers except
.I usbd
take the decimal usb 
.I devid
of the device they should handle as their last argument. A
driver's instance handles only one device at a time.
.PP
Drivers that provide file systems make them available as shares under
.B /shr
(see
.IR shr (3))
or
.BR /shr/usb
(which is bound after
.BR /dev
by
.IR nusbrc (8)). 
.PP
Options
.B \-d
and
.B \-D
trigger debug diagnostics and file system debugging
diagnostics for most drivers. Repeating any one of these may
increase verbosity.
.SS Hubs
.I Usbd
enumerates the tree of USB hubs and configures the device on
attachment. It provides a filesystem with the file
.B usbevent
(usually seen as
.BR /dev/usbevent )
which, when read, returns a 6-column, space-separated line of
text, one for each event. The columns are:
.B attach
or
.B detach
followed by
.I addr
.I vid
.I did
.I csp
and
.IR hname .
The
.I addr
is the decimal device address assigned.
.I Vid
and
.I did
are formatted as 4 digit hexadecimal.
.I Csp
is the device class, subclass, protocol indentifier
formatted as 6 digit hexadecimal.
.I Usbd
assigns a stable device identifier based on the
device descriptor for
.IR hname .
This information is read by
.IR nusbrc (8)
and the
.I addr
and
.I hname
are passed to a suitable driver as
.I devid
in the form \fIaddr\fB:\fIhname
.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
.IR kbdfs (8)
process them.
Mouse events are sent to
.B /dev/mousein
in the same way.
A file
.BI /dev/hid N ctl
supports setting keyboard repeat and delay setting, the unit is
milliseconds.
.SS Joysticks
.I 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.
.PP
Directional buttons are reported as axes
with 3 positions:
.IR 0 ,
.IR 128 ,
and
.I 255
for left (or up), center and right (or down) respectively.
Messages are in the form \fIaxis id position\fR.
.PP
On/off buttons are reported as either
.I down
or
.I up
respectively.
Messages are in the form \fIdown\fB|\fIup id\fR.
.SS Disks
.I Disk
configures and manages USB mass storage devices. It
provides a file system (usually seen under
.BR /dev )
that includes one directory per storage device, named
.BI sdU N [. M ]
in correspondence with the USB device identifier
and the storage unit number (or LUN). The LUN is omited
for single lun devices.
.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 and partitions when read.
.I Ptp
configures and exposes a camera's (and often a mobile
device's) storage to allow transferring data via the
Picture Transfer Protocol (PTP).
.SS Ethernet
.I Ether
handles USB ethernet devices. The file system provided is
compatible with
.IR ether (3)
and added to the share
.B usbnet
(see
.IR shr (3))
which is bound after
.B /net
by
.IR nusbrc (8)
so the device will appear as
.BI /net/etherU N .
Without specifying the
.B -t
option, the device is assumed to be a CDC compliant ethernet
communication device. Other devices might require setting an
explicit
.IR ethertype ,
such as
.BR rndis ,
.BR smsc ,
.BR url ,
.BR lan78xx ,
.BR aue ,
.BR a88772,
.BR a88178,
or
.BR a88179
(see
.IR nusbrc (8)).
On devices that support it, the mac address can be set using
the
.B -a
.IR addr
option.
.SS Serial and JTAG ports
.I Serial
provides a file system (usually seen under
.BR /dev )
that includes one directory per USB serial port, named
.BI eiaU N
or
.BI eiaU N [. M ].
In this directory there are two files,
.BR eiaU ,
similar to
.BI eia N
in
.IR uart (3),
and
.BR eiaUctl ,
which admits writes in the same format as
.BI eia N ctl
in
.IR uart (3).
Reading from
.B eiaUctl
gives the serial port's settings in the same format as
.BI eia N status
in
.IR uart (3).
Options are similar to those of
.IR disk .
.PP
JTAG ports are similar
but the files are named
.B jtag
and
.BR jtagctl .
.
.SS Audio devices
.I Audio
configures and manages a USB audio device.
It implements a file system (normally seen under
.BR /dev ),
exporting
.BI audioU N
,
.BI volumeU N
and other files that have the same semantics as
.IR audio (3)).
.SS Camera devices
.I Cam
configures and exposes a USB camera device's capabilities,
implementing a file system compatible with
.IR camv (1),
under a directory named
.BI cam N [. M ].
It provides the following files:
.BR desc ,
showing all of the device's internal descriptors and their values;
.BR format ,
listing admissible image resolutions and framerates;
.BR ctl ,
the picture settings control file;
.BR frame ,
which captures and outputs a single video frame as an
.IR image (6)
file;
and
.IR video ,
streaming video in a preset format, resolution and framerate.
In particular, reading from the
.B 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
.IR minimum / increment / maximum ).
The same pairs can be written to the file to configure the camera.
Currently, only the YUY2 video format is supported.
.SH SOURCE
.B /sys/src/cmd/nusb
.SH "SEE ALSO"
.IR camv (1),
.IR joy (1),
.IR audio (3),
.IR ether (3),
.IR mouse (3),
.IR sd (3),
.IR uart (3),
.IR usb (3),
.IR shr (3),
.IR image (6),
.IR nusbrc (8),
.IR kbdfs (8)
.SH HISTORY
.I Joy
first appeared in 9front (March, 2014).
.br
.I Cam
first appeared in 9front (March, 2018).
.SH BUGS
The various device drivers are generic USB drivers and
may work only for certain devices of each class.
.PP
USB ATA storage devices are not supported.
.PP
The serial driver works only for the Prolific chip and Ftdi,
and control of the
.B dcd
and
.B 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.
.PP
USB video format settings cannot be changed while
.IR camv (1)
is running, and must be set manually by writing them to
.IR cam (4)'s ctl
file before starting the viewer.