diff options
Diffstat (limited to 'static/netbsd/man4/usb.4')
| -rw-r--r-- | static/netbsd/man4/usb.4 | 580 |
1 files changed, 580 insertions, 0 deletions
diff --git a/static/netbsd/man4/usb.4 b/static/netbsd/man4/usb.4 new file mode 100644 index 00000000..ecb58cae --- /dev/null +++ b/static/netbsd/man4/usb.4 @@ -0,0 +1,580 @@ +.\" $NetBSD: usb.4,v 1.124 2025/04/01 18:13:03 nia Exp $ +.\" +.\" Copyright (c) 1999-2024 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.Dd April 1, 2025 +.Dt USB 4 +.Os +.Sh NAME +.Nm usb +.Nd Universal Serial Bus driver +.Sh SYNOPSIS +.Cd "ehci* at cardbus? function ?" +.Cd "ehci* at pci? dev ? function ?" +.Cd "ohci* at cardbus? function ?" +.Cd "ohci* at pci? dev ? function ?" +.Cd "xhci* at pci? dev ? function ?" +.Cd "slhci* at isa? port ? irq ?" +.Cd "slhci* at pcmcia? function ?" +.Cd "uhci* at cardbus? function ?" +.Cd "uhci* at pci? dev ? function ?" +.Cd "usb* at ehci?" +.Cd "usb* at ohci?" +.Cd "usb* at uhci?" +.Cd "usb* at slhci?" +.Cd "uhub* at usb?" +.Cd "uhub* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" +.Cd "XX* at uhub? port ? configuration ? interface ? vendor ? product ? release ?" +.Pp +.Cd options USBVERBOSE +.Pp +.In dev/usb/usb.h +.In dev/usb/usbhid.h +.Sh DESCRIPTION +.Nx +provides machine-independent bus support and drivers for USB devices. +.Pp +The +.Nx +.Nm +driver has three layers (like +.Xr scsi 4 +and +.Xr pcmcia 4 ) : +the controller, the bus, and the device layer. +The controller attaches to a physical bus (like +.Xr pci 4 ) . +The USB bus attaches to the controller and the root hub attaches +to the bus. +Further devices, which may include further hubs, +attach to other hubs. +The attachment forms the same tree structure as the physical +USB device tree. +For each USB device there may be additional drivers attached to it. +.Pp +The +.Cm uhub +device controls USB hubs and must always be present since there is +at least a root hub in any USB system. +.Pp +.Nx +supports the following machine-independent USB drivers: +.Ss Storage devices +.Bl -tag -width 12n -offset ind -compact +.It Xr umass 4 +USB Mass Storage Devices, e.g., external disk drives +.El +.Ss Wired network interfaces +.Bl -tag -width 12n -offset ind -compact +.It Xr aue 4 +ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device +.It Xr axe 4 +ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device +.It Xr axen 4 +ASIX Electronics AX88178a/AX88179 10/100/Gigabit USB Ethernet device +.It Xr cdce 4 +USB Communication Device Class Ethernet device +.It Xr cue 4 +CATC USB-EL1201A USB Ethernet device +.It Xr kue 4 +Kawasaki LSI KL5KUSB101B USB Ethernet device +.It Xr mos 4 +MosChip MCS7730/7830/7832 10/100 USB Ethernet device +.It Xr mue 4 +Microchip LAN75xx/LAN78xx 10/100/Gigabit USB Ethernet device +.It Xr ncm 4 +USB Network Control Model Ethernet device +.It Xr udav 4 +Davicom DM9601 10/100 USB Ethernet device +.It Xr ure 4 +Realtek RTL8152/RTL8153 10/100/Gigabit USB Ethernet device +.It Xr url 4 +Realtek RTL8150L 10/100 USB Ethernet device +.It Xr urndis 4 +USB Remote NDIS Ethernet device +.It Xr usmsc 4 +SMSC LAN95xx 10/100 USB Ethernet device +.El +.Ss Wireless network interfaces +.Bl -tag -width 12n -offset ind -compact +.It Xr atu 4 +Atmel AT76C50x IEEE 802.11b wireless network device +.It Xr ral 4 +Ralink Technology USB IEEE 802.11b/g wireless network device +.It Xr rum 4 +Ralink Technology USB IEEE 802.11a/b/g wireless network device +.It Xr run 4 +Ralink Technology USB IEEE 802.11a/b/g/n wireless network device +.It Xr ubt 4 +USB Bluetooth dongles +.It Xr upgt 4 +Conexant/Intersil PrismGT SoftMAC USB 802.11b/g wireless network device +.It Xr urtwn 4 +Realtek RTL8188CU/RTL8192CU USB IEEE 802.11b/g/n wireless network device +.It Xr zyd 4 +ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device +.El +.Ss Serial and parallel interfaces +.Bl -tag -width 12n -offset ind -compact +.It Xr uark 4 +Arkmicro Technologies ARK3116 based USB serial adapters +.It Xr ubsa 4 +Belkin USB serial adapter +.It Xr uchcom 4 +WinChipHead CH341/340 based USB serial adapter +.It Xr ucom 4 +USB tty support +.It Xr ucycom 4 +Cypress microcontroller based USB serial adapter +.It Xr uftdi 4 +FT8U100AX USB serial adapter +.It Xr ugensa 4 +USB generic serial adapter +.It Xr uipaq 4 +iPAQ USB units +.It Xr ukyopon 4 +USB Kyocera AIR-EDGE PHONE device +.It Xr ulpt 4 +USB printer support +.It Xr umct 4 +MCT USB-RS232 USB serial adapter +.It Xr umodem 4 +USB modem support +.It Xr uplcom 4 +Prolific PL-2303 USB serial adapter +.It Xr uslsa 4 +Silicon Laboratories CP2101/CP2102 based USB serial adapter +.It Xr uvisor 4 +USB Handspring Visor +.It Xr uvscom 4 +SUNTAC Slipper U VS-10U USB serial adapter +.It Xr uxrcom 4 +Exar XR21V141x USB serial adapter +.El +.Ss Cellular WAN interfaces +.Bl -tag -width 12n -offset ind -compact +.It Xr u3g 4 +USB 3G modems +.It Xr uhmodem 4 +Huawei 3G wireless modems +.It Xr uhso 4 +Option N.V. Wireless WAN modems +.It Xr umb 4 +USB Mobile Broadband Interface Model (MBIM) devices +.El +.Ss Audio devices +.Bl -tag -width 12n -offset ind -compact +.It Xr uaudio 4 +USB audio devices +.It Xr umidi 4 +USB MIDI devices +.El +.Ss Video devices +.Bl -tag -width 12n -offset ind -compact +.It Xr pseye 4 +Sony PlayStation Eye webcam device driver +.It Xr udl 4 +DisplayLink DL-1x0/1x5 USB display devices +.It Xr uvideo 4 +USB video class devices (e.g. webcams, capture cards) +.El +.Ss Radio receiver devices +.Bl -tag -width 12n -offset ind -compact +.It Xr slurm 4 +Silicon Labs USB FM radios +.It Xr udsbr 4 +D-Link DSB-R100 USB radio device +.El +.Ss Human Interface Devices +.Bl -tag -width 12n -offset ind -compact +.It Xr uatp 4 +Apple trackpads +.It Xr uep 4 +eGalax touch panel controllers +.It Xr uhid 4 +Generic driver for Human Interface Devices +.It Xr uhidev 4 +Base driver for all Human Interface Devices +.It Xr uintuos 4 +Wacom Intuos drawing tablets +.It Xr ukbd 4 +USB keyboards that follow the boot protocol +.It Xr ums 4 +USB mouse devices +.It Xr uthum 4 +TEMPer and TEMPerHUM temperature and humidity sensors +.It Xr uts 4 +Generic driver for touchscreens and touch digitizers +.El +.Ss Miscellaneous devices +.Bl -tag -width 12n -offset ind -compact +.It Xr stuirda 4 +Sigmaltel 4116/4220 USB-IrDA bridge +.It Xr ualea 4 +USB Araneus Alea I/II random number generators +.It Xr uberry 4 +Battery charging RIM BlackBerry phones via USB +.\" .It Xr udsir 4 +.\" KingSun/DonShine USB IrDA bridge +.It Xr ugen 4 +USB generic devices +.It Xr uipad 4 +Battery charging iOS devices via USB +.It Xr uirda 4 +USB IrDA bridges +.It Xr upl 4 +Prolific based host-to-host adapters +.It Xr usscanner 4 +SCSI-over-USB scanners +.It Xr ustir 4 +SigmaTel STIr4200 USB IrDA bridges +.It Xr utoppy 4 +Topfield TF5000PVR range of digital video recorders +.El +.Sh INTRODUCTION TO USB +The USB 1.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices. +USB 2.x handles 480 Mb/s. +Each 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 1 +locators: +.Bl -tag -compact -width xxxxxxxxx +.It Cd port +this is the number of the port on 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 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 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 USB driver can attach. +.El +.Sh USB CONTROLLER INTERFACE +Use the following to get access to the USB specific structures and defines. +.Bd -literal +#include <dev/usb/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 +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 { + uint8_t udi_bus; + uint8_t udi_addr; + usb_event_cookie_t udi_cookie; + char udi_product[USB_MAX_ENCODED_STRING_LEN]; + char udi_vendor[USB_MAX_ENCODED_STRING_LEN]; + char udi_release[8]; + char udi_serial[USB_MAX_ENCODED_STRING_LEN]; + uint16_t udi_productNo; + uint16_t udi_vendorNo; + uint16_t udi_releaseNo; + uint8_t udi_class; + uint8_t udi_subclass; + uint8_t udi_protocol; + uint8_t udi_config; + uint8_t udi_speed; +#define USB_SPEED_LOW 1 +#define USB_SPEED_FULL 2 +#define USB_SPEED_HIGH 3 + int udi_power; + int udi_nports; + char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN]; + uint8_t udi_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 , +.Va release , +and +.Va serial +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 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 uds_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 have 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 +.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 USB +descriptors exactly follows the naming in the 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 dev/usb/usbhid.h +similarly contains the definitions for +Human Interface Devices (HID). +.Sh USB EVENT INTERFACE +All 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 +.Pp +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. +.Pp +The +.Va ue_bus +contains the number of the USB bus for host controller events. +.Pp +The +.Va ue_device +record contains information about the device in a device event 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). +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 +USB device is attached or detached. +A single USB device may +have zero, one, or many device drivers associated with it. +.Sh KERNEL THREADS +For each USB bus, i.e., for each host controller, there is +a kernel thread that handles attach and detach of devices on +that bus. +The thread is named +.Va usbN +where +.Va N +is the bus number. +.Pp +In addition there is a kernel thread, +.Va usbtask , +which handles various minor tasks that are initiated from +an interrupt context, but need to sleep, e.g., time-out +abort of transfers. +.Sh SEE ALSO +.Xr usbhidaction 1 , +.Xr usbhidctl 1 , +.Xr cardbus 4 , +.Xr ehci 4 , +.Xr isa 4 , +.Xr ohci 4 , +.Xr pci 4 , +.Xr pcmcia 4 , +.Xr slhci 4 , +.Xr uhci 4 , +.Xr xhci 4 , +.Xr usbdevs 8 +.Rs +.%T Universal Serial Bus Specifications Documents +.%U http://www.usb.org/developers/docs/ +.Re +.Sh HISTORY +The +.Nm +driver +appeared in +.Nx 1.4 . +.Sh BUGS +There should be a serial number locator, but +.Nx +does not have string valued locators. |