usb.4: Sync parts of the manual page with FreeBSD.
authorSascha Wildner <saw@online.de>
Sat, 15 Mar 2014 09:20:58 +0000 (10:20 +0100)
committerSascha Wildner <saw@online.de>
Sat, 15 Mar 2014 09:20:58 +0000 (10:20 +0100)
share/man/man4/usb.4

index e35f844..5f97e92 100644 (file)
@@ -1,5 +1,5 @@
-.\" Copyright (c) 1997, 1998
-.\"    Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
+.\" Copyright (c) 1997, 1998 Nick Hibma <n_hibma@FreeBSD.org>
+.\" Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -9,48 +9,64 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. Neither the name of the author nor the names of any co-contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"   without specific prior written permission.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD
-.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-.\" THE POSSIBILITY OF SUCH DAMAGE.
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/share/man/man4/usb.4,v 1.32 2005/04/20 07:33:09 simon Exp $
+.\" $FreeBSD: head/share/man/man4/usb.4 258618 2013-11-26 07:52:40Z lwhsu $
 .\"
-.Dd August 19, 2013
+.Dd March 15, 2014
 .Dt USB 4
 .Os
 .Sh NAME
 .Nm usb
 .Nd Universal Serial Bus
 .Sh SYNOPSIS
+To compile this driver into the kernel,
+place the following line in your
+kernel configuration file:
+.Bd -ragged -offset indent
 .Cd "device usb"
+.Ed
 .Pp
-.In bus/usb/usb.h
-.In bus/usb/usbhid.h
+Alternatively, to load the driver as a
+module at boot time, place the following line in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+usb_load="YES"
+.Ed
+.Sh USERLAND PROGRAMMING
+USB functions can be accessed from userland through the libusb library.
+See
+.Xr libusb 3
+for more information.
 .Sh DESCRIPTION
 .Dx
 provides machine-independent bus support and drivers for
 .Tn USB
-devices.
+devices in host and device side mode.
 .Pp
 The
 .Nm
-driver has three layers: the controller, the bus, and the
-device layer.
+driver has three layers:
+.Bl -tag -width 6n -offset indent
+.It USB Controller (Bus)
+.It USB Device
+.It USB Driver
+.El
+.Pp
 The controller attaches to a physical bus
-(like
-.Xr pci 4 .
+like
+.Xr pci 4 .
 The
 .Tn USB
 bus attaches to the controller, and the root hub attaches
@@ -64,27 +80,34 @@ The
 .Nm uhub
 device will always be present as it is needed for the
 root hub.
+.Pp
+.Dx
+provides support for the following devices.
 .Ss Storage devices
 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
 .\".It Xr natausb 4
 .\"...
 .It Xr umass 4
 Mass Storage Devices, e.g., external disk drives
+.It Xr usfs 4
+Mass storage driver for device-side mode
 .El
 .Ss Wired network interfaces
 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
-.It Xr aue 4
-ADMtek AN986 Pegasus Ethernet driver
+.\".It Xr aue 4
+.\"ADMtek AN986 Pegasus Ethernet driver
 .It Xr axe 4
-ASIX Electronics AX88172 Ethernet driver
-.It Xr cue 4
-CATC USB-EL1210A Ethernet driver
-.It Xr kue 4
-Kawasaki LSI KL5KUSB101B Ethernet driver
-.It Xr lgue 4
-USB CDC (communication device class) driver for the LG P-500 smartphone
-.It Xr rue 4
-RealTek RTL8150 Ethernet driver
+ASIX Electronics AX88x7x/760 USB Ethernet driver
+.\".It Xr cue 4
+.\"CATC USB-EL1210A Ethernet driver
+.\".It Xr kue 4
+.\"Kawasaki LSI KL5KUSB101B Ethernet driver
+.\".It Xr lgue 4
+.\"USB CDC (communication device class) driver for the LG P-500 smartphone
+.\".It Xr rue 4
+.\"RealTek RTL8150 Ethernet driver
+.It Xr udav 4
+Davicom DM9601 USB Ethernet driver
 .El
 .Ss Wireless network interfaces
 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
@@ -94,8 +117,8 @@ NDIS miniport driver wrapper
 Ralink Technology RT2501USB/RT2601USB IEEE 802.11 driver
 .It Xr run 4
 Ralink Technology RT2700U/RT2800U/RT3000U IEEE 802.11 driver
-.It Xr ubt 4
-Bluetooth adapters
+.\".It Xr ubt 4
+.\"Bluetooth adapters
 .\".It Xr ural 4
 .\"Ralink Technology RT2500USB IEEE 802.11 driver
 .It Xr urtwn 4
@@ -103,49 +126,67 @@ Realtek RTL8188CU/RTL8192CU IEEE 802.11 driver
 .El
 .Ss Serial and parallel interfaces
 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
-.It Xr moscom 4
-MosChip Semiconductor MCS7703 based serial adapters
+.\".It Xr moscom 4
+.\"MosChip Semiconductor MCS7703 based serial adapters
+.It Xr u3g 4
+support for 3G datacards
 .It Xr uark 4
 Arkmicro Technologies ARK3116 based serial adapters
 .It Xr ubsa 4
 Belkin serial adapters
+.It Xr ubser 4
+support for BWCT console serial adapters
 .It Xr uchcom 4
 WinChipHead CH341/CH340 serial adapters
 .It Xr ucom 4
 tty support
+.It Xr ucycom 4
+Cypress CY7C63743 and CY7C64013 USB to RS232 bridges
+.It Xr ufoma 4
+mobile phone support
 .It Xr uftdi 4
 serial devices based on the FTDI chips
 .It Xr ugensa 4
 generic serial device
+.It Xr uipaq 4
+support for iPAQ units
 .It Xr ulpt 4
 printer support
+.It Xr umcs 4
+serial adapters based on the MCS7820 and MCS7840 chips
 .It Xr umct 4
 Magic Control Technology USB-232 based serial adapters
+.It Xr umodem 4
+modem support
+.It Xr umoscom 4
+serial adapters based on the MCS7703 chip
 .It Xr uplcom 4
 Prolific PL-2303/2303X/2303HX serial adapters
 .It Xr uslcom 4
 Silicon Laboratories CP2101, CP2102 and CP2103 USB to serial bridge
-.It Xr uticom 4
-Texas Instruments TUSB3410 RS232 to USB converter
+.\".It Xr uticom 4
+.\"Texas Instruments TUSB3410 RS232 to USB converter
 .It Xr uvisor 4
 support for the Handspring Visor, a Palmpilot compatible PDA
 .It Xr uvscom 4
 SUNTAC Slipper U VS-10U serial adapters
 .El
-.Ss Audio devices
-.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
-.It Xr snd_uaudio 4
-audio device driver
-.It Xr urio 4
-driver for the Rio500 MP3 player
-.El
-.Ss Radio receiver devices
-.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
-.It Xr ufm 4
-Cypress Semiconductor FM Radio
-.El
+.\".Ss Audio devices
+.\".Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
+.\".It Xr snd_uaudio 4
+.\"audio device driver
+.\".It Xr urio 4
+.\"driver for the Rio500 MP3 player
+.\".El
+.\".Ss Radio receiver devices
+.\".Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
+.\".It Xr ufm 4
+.\"Cypress Semiconductor FM Radio
+.\".El
 .Ss Human Interface Devices
 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
+.It Xr uep 4
+eGalax touchscreen driver
 .It Xr uhid 4
 generic driver for Human Interface Devices
 .It Xr ukbd 4
@@ -153,24 +194,28 @@ keyboards that follow the boot protocol
 .It Xr ums 4
 mouse devices
 .El
-.Ss Miscellaneous devices
-.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
-.It Xr ugen 4
-generic device support
-.It Xr uscanner 4
-scanner support
-.El
+.\".Ss Miscellaneous devices
+.\".Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
+.\".It Xr uscanner 4
+.\"scanner support
+.\".El
 .Sh INTRODUCTION TO USB
 The
 .Tn USB
-is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
+is a system where external devices can be connected to a PC.
+The most common USB speeds are:
+.Bl -tag -width 6n -offset indent
+.It Low Speed (1.5MBit/sec)
+.It Full Speed (12MBit/sec)
+.It High Speed (480MBit/sec)
+.El
+.Pp
 Each
 .Tn USB
-has a host controller that is the master of the bus;
-all other devices on the bus only speak when spoken to.
+has a USB controller that is the master of the bus.
+The physical communication is simplex which means the host controller only communicates with one USB device at a time.
 .Pp
-There can be up to 127 devices (apart from the host controller)
-on a bus, each with its own address.
+There can be up to 127 devices connected to an USB HUB tree.
 The addresses are assigned
 dynamically by the host when each device is attached to the bus.
 .Pp
@@ -200,288 +245,16 @@ A device may operate in different configurations.
 Depending on the
 configuration, the device may present different sets of endpoints
 and interfaces.
-.\".Pp
-.\"Each device located on a hub has several
-.\".Xr config 8
-.\"locators:
-.\".Bl -tag -compact -width xxxxxx
-.\".It Cd port
-.\"this is the number of the port on the closest upstream hub.
-.\".It Cd configuration
-.\"this is the configuration the device must be in for this driver to attach.
-.\"This locator does not set the configuration; it is iterated by the bus
-.\"enumeration.
-.\".It Cd interface
-.\"this is the interface number within a device that an interface driver
-.\"attaches to.
-.\".It Cd vendor
-.\"this is the 16 bit vendor id of the device.
-.\".It Cd product
-.\"this is the 16 bit product id of the device.
-.\".It Cd release
-.\"this is the 16 bit release (revision) number of the device.
-.\".El
-.\"The first locator can be used to pin down a particular device
-.\"according to its physical position in the device tree.
-.\"The last three locators can be used to pin down a particular
-.\"device according to what device it actually is.
 .Pp
 The bus enumeration of the
 .Tn USB
 bus proceeds in several steps:
 .Bl -enum
 .It
-Any device specific driver can attach to the device.
-.It
-If none is found, any device class specific driver can attach.
-.It
-If none is found, all configurations are iterated over.
-For each configuration, all the interfaces are iterated over, and interface
-drivers can attach.
-If any interface driver attached in a certain
-configuration, the iteration over configurations is stopped.
+Any interface specific driver can attach to the device.
 .It
-If still no drivers have been found, the generic
-.Tn USB
-driver can attach.
-.El
-.Sh USB CONTROLLER INTERFACE
-Use the following to get access to the
-.Tn USB
-specific structures and defines.
-.Pp
-.In bus/usb/usb.h
-.Pp
-The
-.Pa /dev/usb Ns Ar N
-can be opened and a few operations can be performed on it.
-The
-.Xr poll 2
-system call will say that I/O is possible on the controller device when a
-.Tn USB
-device has been connected or disconnected to the bus.
-.Pp
-The following
-.Xr ioctl 2
-commands are supported on the controller device:
-.Bl -tag -width xxxxxx
-.It Dv USB_DISCOVER
-This command will cause a complete bus discovery to be initiated.
-If any devices attached or detached from the bus they will be
-processed during this command.
-This is the only way that new devices are found on the bus.
-.It Dv USB_DEVICEINFO Vt "struct usb_device_info"
-This command can be used to retrieve some information about a device
-on the bus.
-The
-.Va udi_addr
-field should be filled before the call and the other fields will
-be filled by information about the device on that address.
-Should no such device exist, an error is reported.
-.Bd -literal
-#define USB_MAX_DEVNAMES 4
-#define USB_MAX_DEVNAMELEN 16
-struct usb_device_info {
-       u_int8_t        udi_bus;
-       u_int8_t        udi_addr;       /* device address */
-       usb_event_cookie_t udi_cookie;
-       char            udi_product[USB_MAX_STRING_LEN];
-       char            udi_vendor[USB_MAX_STRING_LEN];
-       char            udi_release[8];
-       u_int16_t       udi_productNo;
-       u_int16_t       udi_vendorNo;
-       u_int16_t       udi_releaseNo;
-       u_int8_t        udi_class;
-       u_int8_t        udi_subclass;
-       u_int8_t        udi_protocol;
-       u_int8_t        udi_config;
-       u_int8_t        udi_speed;
-#define USB_SPEED_LOW  1
-#define USB_SPEED_FULL 2
-#define USB_SPEED_HIGH 3
-       int             udi_power;      /* power consumption in mA, 0 if selfpowered */
-       int             udi_nports;
-       char            udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
-       u_int8_t        udi_ports[16];/* hub only: addresses of devices on ports */
-#define USB_PORT_ENABLED 0xff
-#define USB_PORT_SUSPENDED 0xfe
-#define USB_PORT_POWERED 0xfd
-#define USB_PORT_DISABLED 0xfc
-};
-.Ed
-.Pp
-.Va udi_bus
-and
-.Va udi_addr
-contain the topological information for the device.
-.Va udi_devnames
-contains the device names of the connected drivers.
-For example, the
-third
-.Tn USB
-Zip drive connected will be
-.Li umass2 .
-The
-.Va udi_product , udi_vendor
-and
-.Va udi_release
-fields contain self-explanatory descriptions of the device.
-.Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass
-and
-.Va udi_protocol
-contain the corresponding values from the device descriptors.
-The
-.Va udi_config
-field shows the current configuration of the device.
-.Pp
-.Va udi_speed
-indicates whether the device is at low speed
-.Pq Dv USB_SPEED_LOW ,
-full speed
-.Pq Dv USB_SPEED_FULL
-or high speed
-.Pq Dv USB_SPEED_HIGH .
-The
-.Va udi_power
-field shows the power consumption in milli-amps drawn at 5 volts,
-or zero if the device is self powered.
-.Pp
-If the device is a hub, the
-.Va udi_nports
-field is non-zero, and the
-.Va udi_ports
-field contains the addresses of the connected devices.
-If no device is connected to a port, one of the
-.Dv USB_PORT_*
-values indicates its status.
-.It Dv USB_DEVICESTATS Vt "struct usb_device_stats"
-This command retrieves statistics about the controller.
-.Bd -literal
-struct usb_device_stats {
-       u_long  uds_requests[4];
-};
-.Ed
-.Pp
-The
-.Va uds_requests
-field is indexed by the transfer kind, i.e.\&
-.Dv UE_* ,
-and indicates how many transfers of each kind that has been completed
-by the controller.
-.It Dv USB_REQUEST Vt "struct usb_ctl_request"
-This command can be used to execute arbitrary requests on the control pipe.
-This is
-.Em DANGEROUS
-and should be used with great care since it
-can destroy the bus integrity.
+If none is found, generic interface class drivers can attach.
 .El
-.Pp
-The include file
-.In bus/usb/usb.h
-contains definitions for the types used by the various
-.Xr ioctl 2
-calls.
-The naming convention of the fields for the various
-.Tn USB
-descriptors exactly follows the naming in the
-.Tn USB
-specification.
-Byte sized fields can be accessed directly, but word (16 bit)
-sized fields must be access by the
-.Fn UGETW field
-and
-.Fn USETW field value
-macros to handle byte order and alignment properly.
-.Pp
-The include file
-.In bus/usb/usbhid.h
-similarly contains the definitions for
-Human Interface Devices
-.Pq Tn HID .
-.Sh USB EVENT INTERFACE
-All
-.Tn USB
-events are reported via the
-.Pa /dev/usb
-device.
-This devices can be opened for reading and each
-.Xr read 2
-will yield an event record (if something has happened).
-The
-.Xr poll 2
-system call can be used to determine if an event record is available
-for reading.
-.Pp
-The event record has the following definition:
-.Bd -literal
-struct usb_event {
-        int                                 ue_type;
-#define USB_EVENT_CTRLR_ATTACH 1
-#define USB_EVENT_CTRLR_DETACH 2
-#define USB_EVENT_DEVICE_ATTACH 3
-#define USB_EVENT_DEVICE_DETACH 4
-#define USB_EVENT_DRIVER_ATTACH 5
-#define USB_EVENT_DRIVER_DETACH 6
-        struct timespec                     ue_time;
-        union {
-                struct {
-                        int                 ue_bus;
-                } ue_ctrlr;
-                struct usb_device_info      ue_device;
-                struct {
-                        usb_event_cookie_t  ue_cookie;
-                        char                ue_devname[16];
-                } ue_driver;
-        } u;
-};
-.Ed
-The
-.Va ue_type
-field identifies the type of event that is described.
-The possible events are attach/detach of a host controller,
-a device, or a device driver.
-The union contains information
-pertinent to the different types of events.
-Macros,
-.Fn USB_EVENT_IS_ATTACH "ue_type"
-and
-.Fn USB_EVENT_IS_DETACH "ue_type"
-can be used to determine if an event was an
-.Dq attach
-or a
-.Dq detach
-request.
-.Pp
-The
-.Va ue_bus
-contains the number of the
-.Tn USB
-bus for host controller events.
-.Pp
-The
-.Va ue_device
-record contains information about the device in a device event.
-.Pp
-The
-.Va ue_cookie
-is an opaque value that uniquely determines which
-device a device driver has been attached to (i.e., it equals
-the cookie value in the device that the driver attached to).
-.Pp
-The
-.Va ue_devname
-contains the name of the device (driver) as seen in, e.g.,
-kernel messages.
-.Pp
-Note that there is a separation between device and device
-driver events.
-A device event is generated when a physical
-.Tn USB
-device is attached or detached.
-A single
-.Tn USB
-device may
-have zero, one, or many device drivers associated with it.
 .Sh SEE ALSO
 The
 .Tn USB
@@ -489,22 +262,63 @@ specifications can be found at:
 .Pp
 .D1 Pa http://www.usb.org/developers/docs/
 .Pp
+.Xr libusb 3 ,
+.Xr usbdi 4 ,
+.\".Xr aue 4 ,
+.Xr axe 4 ,
+.\".Xr axge 4 ,
+.\".Xr cue 4 ,
 .Xr ehci 4 ,
+.\".Xr kue 4 ,
+.\".Xr mos 4 ,
+.Xr ndis 4 ,
 .Xr ohci 4 ,
 .Xr pci 4 ,
+.\".Xr rue 4 ,
+.Xr rum 4 ,
+.Xr run 4 ,
+.Xr u3g 4 ,
+.Xr uark 4 ,
+.Xr ubsa 4 ,
+.Xr ubser 4 ,
+.Xr uchcom 4 ,
+.Xr ucom 4 ,
+.Xr ucycom 4 ,
+.Xr udav 4 ,
+.Xr uep 4 ,
+.Xr ufoma 4 ,
+.Xr uftdi 4 ,
+.Xr ugensa 4 ,
 .Xr uhci 4 ,
-.Xr usbd 8 ,
-.Xr usbdevs 8
+.Xr uhid 4 ,
+.Xr uipaq 4 ,
+.Xr ukbd 4 ,
+.Xr ulpt 4 ,
+.Xr umass 4 ,
+.Xr umcs 4 ,
+.Xr umct 4 ,
+.Xr umodem 4 ,
+.Xr umoscom 4 ,
+.Xr ums 4 ,
+.Xr uplcom 4 ,
+.\".Xr urio 4 ,
+.Xr urtwn 4 ,
+.Xr usfs 4 ,
+.Xr uslcom 4 ,
+.Xr uvisor 4 ,
+.Xr uvscom 4 ,
+.Xr usbconfig 8 ,
+.Xr xhci 4
+.Sh STANDARDS
+The
+.Nm
+module complies with the USB 2.0 standard.
 .Sh HISTORY
 The
 .Nm
-driver first appeared in
-.Fx 3.0 .
-.Sh AUTHORS
+module has been inspired by the NetBSD USB stack initially written by
+Lennart Augustsson.
 The
 .Nm
-driver was written by
-.An Lennart Augustsson Aq Mt augustss@carlstedt.se
-for the
-.Nx
-project.
+module was written by
+.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org .