Date: Thu, 21 May 2009 02:44:24 GMT From: Andrew Thompson <thompsa@FreeBSD.org> To: Perforce Change Reviews <perforce@freebsd.org> Subject: PERFORCE change 162432 for review Message-ID: <200905210244.n4L2iOte072439@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=162432 Change 162432 by thompsa@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) <<<
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200905210244.n4L2iOte072439>