Added man page usb uhci ohci

1 files changed, 297 insertions, 0 deletions

diff --git a/share/man/man4/usb.4 b/share/man/man4/usb.4
new file mode 100644
index 0000000..0c6f989
--- /dev/null
+++ b/share/man/man4/usb.4
@@ -0,0 +1,297 @@
+.\" Copyright (c) 1997, 1998
+.\"	Nick Hibma <hibma@skylink.it>. All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by Bill Paul.
+.\" 4. 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
+.\" 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.
+.\"
+.\"	$Id: xl.4,v 1.3 1998/12/05 09:36:15 rnordier Exp $
+.\"
+.Dd February 21, 1999
+.Dt USB 4 i386
+.Os FreeBSD
+.Sh NAME
+.Nm usb
+.Nd Universal Serial Bus
+.Sh SYNOPSIS
+.Cd "controller usb0"
+.Sh DESCRIPTION
+.Nx
+provides machine-independent bus support and drivers for
+.Tn USB
+devices.
+.Pp
+The
+.Nm
+driver has three layers: the controller, the bus, and the
+device layer. The controller attaches to a physical bus
+(like
+.Xr pci 4 ).
+The
+.Tn USB
+bus attaches to the controller and the root hub attaches
+to the controller.
+Any devices attached to the bus will attach to the root hub
+or another hub attached to the USB bus.
+.Pp
+The
+.Nm uhub
+device will always be present as it is needed for the
+root hub.
+.Pp
+.Sh INTRODUCTION TO USB
+The
+.Tn USB
+is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
+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.
+.Pp
+There can be up to 127 devices (apart from the host controller)
+on a bus, each with its own address.
+The addresses are assigned
+dynamically by the host when each device is attached to the bus.
+.Pp
+Within each device there can be up to 16 endpoints.
+Each endpoint
+is individually addressed and the addresses are static.
+Each of these endpoints will communicate in one of four different modes:
+control, isochronous, bulk, or interrupt.
+A device always has at least one endpoint.
+This endpoint has address 0 and is a control
+endpoint and is used to give commands to and extract basic data,
+such as descriptors, from the device.
+Each endpoint, except the control endpoint, is unidirectional.
+.Pp
+The endpoints in a device are grouped into interfaces.
+An interface is a logical unit within a device; e.g.
+a compound device with both a keyboard and a trackball would present
+one interface for each.
+An interface can sometimes be set into different modes,
+called alternate settings, which affects how it operates.
+Different alternate settings can have different endpoints
+within it.
+.Pp
+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.
+.El
+.Pp
+The bus enumeration of the
+.Tn USB
+bus proceeds in several steps:
+.Bl -enum
+.It
+Any device specific driver can to 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 interface are iterated over and interface
+drivers can attach.
+If any interface driver attached in a certain
+configuration the iteration over configurations is stopped.
+.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 structurs and defines.
+.Bd -literal
+#include <sys/dev/usb.h>
+.Ed
+.Pp
+The
+.Pa /dev/usbN
+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 Fa "struct usb_device_info"
+This command can be used to retrieve some information about a device
+on the bus.
+The
+.Va 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
+struct usb_device_info {
+        uByte   addr;           /* device address */
+        char    product[USB_MAX_STRING_LEN];
+        char    vendor[USB_MAX_STRING_LEN];
+        char    revision[8];
+        uByte   class;
+        uByte   config;
+        uByte   lowspeed;
+        int     power;
+        int     nports;
+        uByte   ports[16];
+#define USB_PORT_ENABLED 0xff
+#define USB_PORT_SUSPENDED 0xfe
+#define USB_PORT_POWERED 0xfd
+#define USB_PORT_DISABLED 0xfc
+};
+.Ed
+.Pp
+The
+.Va product ,
+.Va vendor ,
+and
+.Va revision
+fields contain self-explanatory descriptions of the device.
+.Pp
+The
+.Va class
+field contains the device class.
+.Pp
+The
+.Va config
+field shows the current configuration of the device.
+.Pp
+The
+.Va lowspeed
+field
+is set if the device is a
+.Tn USB
+low speed device.
+.Pp
+The
+.Va 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 nports
+field is non-zero and the
+.Va ports
+field contains the addresses of the connected devices.
+If no device is connected to a port one of the
+.Va USB_PORT_*
+values indicates its status.
+.It Dv USB_DEVICESTATS Fa "struct usb_device_stats"
+This command retrieves statistics about the controller.
+.Bd -literal
+struct usb_device_stats {
+        u_long  requests[4];
+};
+.Ed
+.Pp
+The
+.Va requests
+field is indexed by the transfer kind, i.e.
+.Va UE_* ,
+and indicates how many transfers of each kind that has been completed
+by the controller.
+.It Dv USB_REQUEST Fa "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.
+.El
+.Pp
+The include file
+.Aq Pa dev/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
+.Aq Pa dev/usb/usbhid.h
+similarly contains the definitions for
+Human Interface Devices
+.Pq Tn HID .
+.Sh SEE ALSO
+The
+.Tn USB
+specifications can be found at
+.Dv http://www.usb.org/developers/docs.htm .
+.Pp
+.Xr pci 4 ,
+.Xr ohci 4 ,
+.Xr uhci 4 ,
+.Xr ugen 4 ,
+.Xr uhid 4 ,
+.Xr ukbd 4 ,
+.Xr ulpt 4 ,
+.Xr ums 4 ,
+.Xr usbd 8 ,
+.Xr usbdevs 8
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Fx 3.0 .
+.Sh AUTHOR
+The
+.Nm
+driver was written by
+.An Lennart Augustsson (augustss@carlstedt.se) for the
+.Nx
+project.