PERFORCE change 162432 for review
Andrew Thompson
thompsa at FreeBSD.org
Thu May 21 02:44:26 UTC 2009
http://perforce.freebsd.org/chv.cgi?CH=162432
Change 162432 by thompsa at thompsa_burger on 2009/05/21 02:43:54
Integrate from usb.
Affected files ...
.. //depot/projects/usb_buf/src/lib/libusb/libusb.3#2 integrate
.. //depot/projects/usb_buf/src/share/man/man4/usb.4#2 integrate
.. //depot/projects/usb_buf/src/share/man/man4/usb2_core.4#3 delete
.. //depot/projects/usb_buf/src/sys/amd64/amd64/mca.c#2 integrate
.. //depot/projects/usb_buf/src/sys/amd64/include/param.h#2 integrate
.. //depot/projects/usb_buf/src/sys/amd64/pci/pci_cfgreg.c#2 integrate
.. //depot/projects/usb_buf/src/sys/compat/linux/linux_socket.c#3 integrate
.. //depot/projects/usb_buf/src/sys/compat/svr4/svr4_misc.c#2 integrate
.. //depot/projects/usb_buf/src/sys/conf/files#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/aac/aac.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/acpica/acpi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/age/if_age.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/amr/amr.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/amr/amr_linux.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/arcmsr/arcmsr.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ata/ata-all.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ata/chipsets/ata-promise.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ah.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ah.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ah_internal.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5210/ar5210_attach.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5210/ar5210_interrupts.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5211/ar5211_attach.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5211/ar5211_interrupts.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5212/ar5212_attach.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5212/ar5212_interrupts.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5212/ar5212reg.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5416/ar5416_attach.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/ath_hal/ar5416/ar5416_interrupts.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/if_ath.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ath/if_athvar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/bwi/if_bwi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/bwi/if_bwivar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ciss/ciss.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/cxgb/cxgb_main.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/if_ndis/if_ndis.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/iir/iir_ctrl.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ipw/if_ipw.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ipw/if_ipwvar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/iwi/if_iwi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/iwi/if_iwivar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/iwn/if_iwn.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/iwn/if_iwnvar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/malo/if_malo.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/malo/if_malo.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/mfi/mfi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/mfi/mfi_linux.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/mpt/mpt_user.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/pci/pci.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/pci/pci_pci.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/pci/pcib_if.m#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ral/rt2560.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ral/rt2560var.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ral/rt2661.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/ral/rt2661var.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/sound/midi/midi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/sound/pci/emu10kx-midi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/sound/pci/via82c686.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/sound/sbus/cs4231.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/sound/usb/uaudio.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/sound/usb/uaudioreg.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/twa/tw_osl_freebsd.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/twe/twe_freebsd.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/bluetooth/ng_ubt.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/bluetooth/ubtbcmfw.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/at91dci.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/atmegadci.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/atmegadci.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/ehci.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/musb_otg.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/ohci.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/uhci.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/usb_controller.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/uss820dci.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/uss820dci.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/controller/uss820dci_atmelarm.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/input/uhid.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/input/ukbd.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/input/ums.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/misc/udbp.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/misc/ufm.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/net/if_aue.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/net/if_axe.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/net/if_cdce.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/net/if_cue.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/net/if_kue.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/net/if_rue.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/net/if_udav.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/u3g.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/uark.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/ubsa.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/ubser.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/uchcom.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/ucycom.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/ufoma.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/uftdi.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/ugensa.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/uipaq.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/ulpt.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/umct.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/umodem.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/umoscom.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/uplcom.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/uslcom.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/uvisor.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/serial/uvscom.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/storage/umass.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/storage/urio.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/storage/ustorage_fs.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/template/usb_template.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_bus.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_busdma.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_compat_linux.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_compat_linux.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_controller.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_core.h#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_debug.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_dev.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_device.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_device.h#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_generic.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_hub.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_hub.h#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_request.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_revision.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_transfer.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/usb_transfer.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/wlan/if_rum.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/wlan/if_rumvar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/wlan/if_uath.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/wlan/if_uathvar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/wlan/if_upgt.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/wlan/if_ural.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/wlan/if_uralvar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/usb/wlan/if_zyd.c#3 integrate
.. //depot/projects/usb_buf/src/sys/dev/wi/if_wavelan_ieee.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/wi/if_wi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/wi/if_wireg.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/wi/if_wivar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/wpi/if_wpi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/dev/wpi/if_wpivar.h#2 integrate
.. //depot/projects/usb_buf/src/sys/fs/nfs/nfs_var.h#3 integrate
.. //depot/projects/usb_buf/src/sys/fs/nfsclient/nfs_clnode.c#2 integrate
.. //depot/projects/usb_buf/src/sys/fs/nfsclient/nfs_clrpcops.c#2 integrate
.. //depot/projects/usb_buf/src/sys/fs/nfsclient/nfs_clstate.c#2 integrate
.. //depot/projects/usb_buf/src/sys/fs/nfsclient/nfs_clvnops.c#2 integrate
.. //depot/projects/usb_buf/src/sys/fs/nfsserver/nfs_nfsdstate.c#3 integrate
.. //depot/projects/usb_buf/src/sys/i386/acpica/acpi_machdep.c#2 integrate
.. //depot/projects/usb_buf/src/sys/i386/bios/smapi.c#2 integrate
.. //depot/projects/usb_buf/src/sys/i386/i386/mca.c#2 integrate
.. //depot/projects/usb_buf/src/sys/i386/include/param.h#2 integrate
.. //depot/projects/usb_buf/src/sys/i386/pci/pci_cfgreg.c#2 integrate
.. //depot/projects/usb_buf/src/sys/kern/kern_descrip.c#3 integrate
.. //depot/projects/usb_buf/src/sys/kern/kern_mutex.c#2 integrate
.. //depot/projects/usb_buf/src/sys/kern/kern_poll.c#2 integrate
.. //depot/projects/usb_buf/src/sys/kern/subr_bus.c#2 integrate
.. //depot/projects/usb_buf/src/sys/kern/subr_rman.c#2 integrate
.. //depot/projects/usb_buf/src/sys/kern/subr_witness.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net/if_llatbl.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net/if_llatbl.h#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211.h#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_adhoc.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_ddb.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_freebsd.c#3 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_freebsd.h#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_hostap.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_ht.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_input.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_monitor.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_node.c#3 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_node.h#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_output.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_proto.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_proto.h#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_radiotap.c#1 branch
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_scan.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_scan.h#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_scan_sta.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_sta.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_superg.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_tdma.c#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_tdma.h#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_var.h#2 integrate
.. //depot/projects/usb_buf/src/sys/net80211/ieee80211_wds.c#2 integrate
.. //depot/projects/usb_buf/src/sys/netinet/in.c#3 integrate
.. //depot/projects/usb_buf/src/sys/netinet/ip_fw2.c#2 integrate
.. //depot/projects/usb_buf/src/sys/netinet6/in6.c#3 integrate
.. //depot/projects/usb_buf/src/sys/netnatm/natm.c#2 integrate
.. //depot/projects/usb_buf/src/sys/nfs4client/nfs4_dev.c#2 integrate
.. //depot/projects/usb_buf/src/sys/nlm/nlm.h#2 integrate
.. //depot/projects/usb_buf/src/sys/nlm/nlm_prot_impl.c#2 integrate
.. //depot/projects/usb_buf/src/sys/sys/interrupt.h#2 integrate
.. //depot/projects/usb_buf/src/sys/sys/param.h#2 integrate
.. //depot/projects/usb_buf/src/sys/sys/proc.h#2 integrate
.. //depot/projects/usb_buf/src/usr.sbin/usbconfig/usbconfig.8#2 integrate
Differences ...
==== //depot/projects/usb_buf/src/lib/libusb/libusb.3#2 (text+ko) ====
@@ -945,7 +945,7 @@
.
/dev/usb
.Sh SEE ALSO
-.Xr usb2_core 4 ,
+.Xr usb 4 ,
.Xr usbconfig 8
.
.
==== //depot/projects/usb_buf/src/share/man/man4/usb.4#2 (text+ko) ====
@@ -25,9 +25,32 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
.\" THE POSSIBILITY OF SUCH DAMAGE.
.\"
+.\" 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
+.\" 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.
+.\"
+.\" 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 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.37 2009/03/19 20:33:26 thompsa Exp $
.\"
-.Dd November 22, 2006
+.Dd May 18, 2009
.Dt USB 4
.Os
.Sh NAME
@@ -47,22 +70,29 @@
.Bd -literal -offset indent
usb_load="YES"
.Ed
-.Pp
-.In dev/usb/usb.h
-.In dev/usb/usbhid.h
+.Sh USERLAND PROGRAMMING
+USB functions can be accessed from userland through the libusb library.
+See
+.Xr libusb 3
+for more information.
.Sh DESCRIPTION
.Fx
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
+.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
@@ -79,14 +109,20 @@
.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
+.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
@@ -116,286 +152,558 @@
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.
+Any interface 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.
-.It
-If still no drivers have been found, the generic
-.Tn USB
-driver can attach.
+If none is found, generic interface class drivers can attach.
.El
-.Sh USB CONTROLLER INTERFACE
-Use the following to get access to the
-.Tn USB
-specific structures and defines.
+.Sh USB KERNEL PROGRAMMING
+Here is a list of commonly used functions:
+.Pp
+.
+.Ft "usb2_error_t"
+.Fo "usb2_transfer_setup"
+.Fa "udev"
+.Fa "ifaces"
+.Fa "pxfer"
+.Fa "setup_start"
+.Fa "n_setup"
+.Fa "priv_sc"
+.Fa "priv_mtx"
+.Fc
+.
+.Pp
+.
+.Ft "void"
+.Fo "usb2_transfer_unsetup"
+.Fa "pxfer"
+.Fa "n_setup"
+.Fc
+.
+.Pp
+.
+.Ft "void"
+.Fo "usb2_transfer_start"
+.Fa "xfer"
+.Fc
+.
+.Pp
+.
+.Ft "void"
+.Fo "usb2_transfer_stop"
+.Fa "xfer"
+.Fc
+.
.Pp
+.
+.Ft "void"
+.Fo "usb2_transfer_drain"
+.Fa "xfer"
+.Fc
+.
+.
+.Sh DESCRIPTION
The
-.Pa /dev/usb Ns Ar N
-can be opened and a few operations can be performed on it.
+.Nm
+module implements the core functionality of the USB standard and many
+helper functions to make USB device driver programming easier and more
+safe.
+.
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.
+.Nm
+module supports both USB Host and USB Device side mode!
+.
+.Sh USB TRANSFER MANAGEMENT FUNCTIONS
+The USB standard defines four types of USB transfers.
+.
+Control transfers, Bulk transfers, Interrupt transfers and Isochronous
+transfers.
+.
+All the transfer types are managed using the following five functions:
+.
+.Pp
+.
+.Fn usb2_transfer_setup
+This function will allocate memory for and initialise an array of USB
+transfers and all required DMA memory.
+.
+This function can sleep or block waiting for resources to become
+available.
+.Fa udev
+is a pointer to "struct usb2_device".
+.Fa ifaces
+is an array of interface index numbers to use. See "if_index".
+.Fa pxfer
+is a pointer to an array of USB transfer pointers that are initialized
+to NULL, and then pointed to allocated USB transfers.
+.Fa setup_start
+is a pointer to an array of USB config structures.
+.Fa n_setup
+is a number telling the USB system how many USB transfers should be
+setup.
+.Fa priv_sc
+is the private softc pointer, which will be used to initialize
+"xfer->priv_sc".
+.Fa priv_mtx
+is the private mutex protecting the transfer structure and the
+softc. This pointer is used to initialize "xfer->priv_mtx".
+This function returns
+zero upon success. A non-zero return value indicates failure.
+.
+.Pp
+.
+.Fn usb2_transfer_unsetup
+This function will release the given USB transfers and all allocated
+resources associated with these USB transfers.
+.Fa pxfer
+is a pointer to an array of USB transfer pointers, that may be NULL,
+that should be freed by the USB system.
+.Fa n_setup
+is a number telling the USB system how many USB transfers should be
+unsetup.
+.
+This function can sleep waiting for USB transfers to complete.
+.
+This function is NULL safe with regard to the USB transfer structure
+pointer.
+.
+It is not allowed to call this function from the USB transfer
+callback.
+.
+.Pp
+.
+.Fn usb2_transfer_start
+This function will start the USB transfer pointed to by
+.Fa xfer,
+if not already started.
+.
+This function is always non-blocking and must be called with the
+so-called private USB mutex locked.
+.
+This function is NULL safe with regard to the USB transfer structure
+pointer.
+.
+.Pp
+.
+.Fn usb2_transfer_stop
+This function will stop the USB transfer pointed to by
+.Fa xfer,
+if not already stopped.
+.
+This function is always non-blocking and must be called with the
+so-called private USB mutex locked.
+.
+This function can return before the USB callback has been called.
+.
+This function is NULL safe with regard to the USB transfer structure
+pointer.
+.
+If the transfer was in progress, the callback will called with
+"USB_ST_ERROR" and "xfer->error = USB_ERR_CANCELLED".
+.
+.Pp
+.
+.Fn usb2_transfer_drain
+This function will stop an USB transfer, if not already stopped and
+wait for any additional USB hardware operations to complete.
+.
+Buffers that are loaded into DMA using "usb2_set_frame_data()" can
+safely be freed after that this function has returned.
+.
+This function can block the caller and will not return before the USB
+callback has been called.
+.
+This function is NULL safe with regard to the USB transfer structure
+pointer.
+.
+.Sh USB TRANSFER CALLBACK
+.
+The USB callback has three states.
+.
+USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the
+initial state.
+.
+After the callback has been called with this state it will always be
+called back at a later stage in one of the other two states.
+.
+In the USB_ST_ERROR state the "error" field of the USB transfer
+structure is set to the error cause.
+.
+The USB callback should not restart the USB transfer in case the error
+cause is USB_ERR_CANCELLED.
+.
+The USB callback is protected from recursion.
+.
+That means one can start and stop whatever transfer from the callback
+of another transfer one desires.
+.
+Also the transfer that is currently called back.
+.
+Recursion is handled like this that when the callback that wants to
+recurse returns it is called one more time.
+.
+.
.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
+.
+.Fn usb2_start_hardware
+This function should only be called from within the USB callback and
+is used to start the USB hardware.
+.
+Typical parameters that should be set in the USB transfer structure
+before this function is called are "frlengths[]", "nframes" and
+"frbuffers[]".
+.
+An USB transfer can have multiple frames consisting of one or more USB
+packets making up an I/O vector for all USB transfer types.
+.
+After the USB transfer is complete "frlengths[]" is updated to the
+actual USB transfer length for the given frame.
+.Bd -literal -offset indent
+void
+usb2_default_callback(struct usb2_xfer *xfer)
+{
+ switch (USB_GET_STATE(xfer)) {
+ case USB_ST_SETUP:
+ /*
+ * Setup xfer->frlengths[], xfer->nframes
+ * and write data to xfer->frbuffers[], if any
+ */
+ usb2_start_hardware(xfer);
+ break;
+
+ case USB_ST_TRANSFERRED:
+ /*
+ * Read data from xfer->frbuffers[], if any.
+ * "xfer->frlengths[]" should now have been
+ * updated to the actual length.
+ */
+ break;
+
+ default: /* Error */
+ /*
+ * Print error message and clear stall
+ * for example.
+ */
+ break;
+ }
+ /*
+ * Here it is safe to do something without the private
+ * USB mutex locked.
+ */
+ return;
+}
+.Ed
+.
+.Sh USB CONTROL TRANSFERS
+An USB control transfer has three parts.
+.
+First the SETUP packet, then DATA packet(s) and then a STATUS
+packet.
+.
+The SETUP packet is always pointed to by "xfer->frbuffers[0]" and the
+length is stored in "xfer->frlengths[0]" also if there should not be
+sent any SETUP packet! If an USB control transfer has no DATA stage,
+then "xfer->nframes" should be set to 1.
+.
+Else the default value is "xfer->nframes" equal to 2.
+.
+.Bd -literal -offset indent
+
+Example1: SETUP + STATUS
+ xfer->nframes = 1;
+ xfer->frlenghts[0] = 8;
+ usb2_start_hardware(xfer);
+
+Example2: SETUP + DATA + STATUS
+ xfer->nframes = 2;
+ xfer->frlenghts[0] = 8;
+ xfer->frlenghts[1] = 1;
+ usb2_start_hardware(xfer);
+
+Example3: SETUP + DATA + STATUS - split
+1st callback:
+ xfer->nframes = 1;
+ xfer->frlenghts[0] = 8;
+ usb2_start_hardware(xfer);
+
+2nd callback:
+ /* IMPORTANT: frbuffers[0] must still point at the setup packet! */
+ xfer->nframes = 2;
+ xfer->frlenghts[0] = 0;
+ xfer->frlenghts[1] = 1;
+ usb2_start_hardware(xfer);
+
+Example4: SETUP + STATUS - split
+1st callback:
+ xfer->nframes = 1;
+ xfer->frlenghts[0] = 8;
+ xfer->flags.manual_status = 1;
+ usb2_start_hardware(xfer);
+
+2nd callback:
+ xfer->nframes = 1;
+ xfer->frlenghts[0] = 0;
+ xfer->flags.manual_status = 0;
+ usb2_start_hardware(xfer);
+
+.Ed
+.Sh USB TRANSFER CONFIG
+To simply the search for endpoints the
+.Nm
+module defines a USB config structure where it is possible to specify
+the characteristics of the wanted endpoint.
+.Bd -literal -offset indent
+
+struct usb2_config {
+ bufsize,
+ callback
+ direction,
+ endpoint,
+ frames,
+ index flags,
+ interval,
+ timeout,
+ type,
};
+
.Ed
+.
+.Pp
+.Fa type
+field selects the USB pipe type.
+.
+Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK,
+UE_ISOCHRONOUS.
+.
+The special value UE_BULK_INTR will select BULK and INTERRUPT pipes.
+.
+This field is mandatory.
+.
+.Pp
+.Fa endpoint
+field selects the USB endpoint number.
+.
+A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching
+endpoint.
+.
+This field is mandatory.
+.
+.Pp
+.Fa direction
+field selects the USB endpoint direction.
+.
+A value of "UE_DIR_ANY" will select the first matching endpoint.
+.
+Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT".
+.
+"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which
+means that the direction will be swapped in case of
+USB_MODE_DEVICE.
+.
+Note that "UE_DIR_IN" refers to the data transfer direction of the
+"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of
+the "OUT" tokens.
+.
+This field is mandatory.
+.
.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.
+.Fa interval
+field selects the interrupt interval.
+.
+The value of this field is given in milliseconds and is independent of
+device speed.
+.
+Depending on the endpoint type, this field has different meaning:
+.Bl -tag
+.It UE_INTERRUPT
+"0" use the default interrupt interval based on endpoint descriptor.
+"Else" use the given value for polling rate.
+.It UE_ISOCHRONOUS
+"0" use default. "Else" the value is ignored.
+.It UE_BULK
+.It UE_CONTROL
+"0" no transfer pre-delay. "Else" a delay as given by this field in
+milliseconds is inserted before the hardware is started when
+"usb2_start_hardware()" is called.
.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.
+NOTE: The transfer timeout, if any, is started after that the
+pre-delay has elapsed!
+.El
+.
.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
+.Fa timeout
+field, if non-zero, will set the transfer timeout in milliseconds. If
+the "timeout" field is zero and the transfer type is ISOCHRONOUS a
+timeout of 250ms will be used.
+.
.Pp
-The
-.Va udi_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.
+.Fa frames
+field sets the maximum number of frames. If zero is specified it will
+yield the following results:
+.Bl -tag
+.It UE_BULK
+xfer->nframes = 1;
+.It UE_INTERRUPT
+xfer->nframes = 1;
+.It UE_CONTROL
+xfer->nframes = 2;
+.It UE_ISOCHRONOUS
+Not allowed. Will cause an error.
.El
+.
.Pp
-The include file
-.In 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.
+.Fa ep_index
+field allows you to give a number, in case more endpoints match the
+description, that selects which matching "ep_index" should be used.
+.
+.Pp
+.Fa if_index
+field allows you to select which of the interface numbers in the
+"ifaces" array parameter passed to "usb2_transfer_setup" that should
+be used when setting up the given USB transfer.
+.
+.Pp
+.Fa flags
+field has type "struct usb2_xfer_flags" and allows one to set initial
+flags an USB transfer. Valid flags are:
+.Bl -tag
+.It force_short_xfer
+This flag forces the last transmitted USB packet to be short. A short
+packet has a length of less than "xfer->max_packet_size", which
+derives from "wMaxPacketSize". This flag can be changed during
+operation.
+.It short_xfer_ok
+This flag allows the received transfer length, "xfer->actlen" to be
+less than "xfer->sumlen" upon completion of a transfer. This flag can
+be changed during operation.
+.It short_frames_ok
+This flag allows the reception of multiple short USB frames. This flag
+only has effect for BULK and INTERRUPT endpoints and if the number of
+frames received is greater than 1. This flag can be changed during
+operation.
+.It pipe_bof
+This flag causes a failing USB transfer to remain first in the PIPE
+queue except in the case of "xfer->error" equal to
+"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue
+will be started until either:
+.Bl -tag
+.It 1
+The failing USB transfer is stopped using "usb2_transfer_stop()".
+.It 2
+The failing USB transfer performs a successful transfer.
+.El
+The purpose of this flag is to avoid races when multiple transfers are
+queued for execution on an USB endpoint, and the first executing
+transfer fails leading to the need for clearing of stall for
+example.
+.
+In this case this flag is used to prevent the following USB transfers
+from being executed at the same time the clear-stall command is
+executed on the USB control endpoint.
+.
+This flag can be changed during operation.
.Pp
-The include file
-.In dev/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 device 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.
+"BOF" is short for "Block On Failure"
.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
>>> TRUNCATED FOR MAIL (1000 lines) <<<
More information about the p4-projects
mailing list