^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. _usb-hostside-api:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) The Linux-USB Host Side API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Introduction to USB on Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) A Universal Serial Bus (USB) is used to connect a host, such as a PC or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) workstation, to a number of peripheral devices. USB uses a tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) structure, with the host as the root (the system's master), hubs as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) interior nodes, and peripherals as leaves (and slaves). Modern PCs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) support several such trees of USB devices, usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) USB 2.0 (480 MBit/s) busses just in case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) That master/slave asymmetry was designed-in for a number of reasons, one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) being ease of use. It is not physically possible to mistake upstream and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) downstream or it does not matter with a type C plug (or they are built into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) peripheral). Also, the host software doesn't need to deal with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) distributed auto-configuration since the pre-designated master node
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) manages all that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) Kernel developers added USB support to Linux early in the 2.2 kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) series and have been developing it further since then. Besides support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) for each new generation of USB, various host controllers gained support,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) new drivers for peripherals have been added and advanced features for latency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) measurement and improved power management introduced.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Linux can run inside USB devices as well as on the hosts that control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) the devices. But USB device drivers running inside those peripherals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) don't do the same things as the ones running inside hosts, so they've
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) been given a different name: *gadget drivers*. This document does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) cover gadget drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) USB Host-Side API Model
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Host-side drivers for USB devices talk to the "usbcore" APIs. There are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) two. One is intended for *general-purpose* drivers (exposed through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) driver frameworks), and the other is for drivers that are *part of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) core*. Such core drivers include the *hub* driver (which manages trees
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) of USB devices) and several different kinds of *host controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) drivers*, which control individual busses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) The device model seen by USB drivers is relatively complex.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) - USB supports four kinds of data transfers (control, bulk, interrupt,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) and isochronous). Two of them (control and bulk) use bandwidth as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) it's available, while the other two (interrupt and isochronous) are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) scheduled to provide guaranteed bandwidth.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) - The device description model includes one or more "configurations"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) per device, only one of which is active at a time. Devices are supposed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) to be capable of operating at lower than their top
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) speeds and may provide a BOS descriptor showing the lowest speed they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) remain fully operational at.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) - From USB 3.0 on configurations have one or more "functions", which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) provide a common functionality and are grouped together for purposes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) of power management.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) - Configurations or functions have one or more "interfaces", each of which may have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) "alternate settings". Interfaces may be standardized by USB "Class"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) specifications, or may be specific to a vendor or device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) USB device drivers actually bind to interfaces, not devices. Think of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) them as "interface drivers", though you may not see many devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) where the distinction is important. *Most USB devices are simple,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) with only one function, one configuration, one interface, and one alternate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) setting.*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) - Interfaces have one or more "endpoints", each of which supports one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) type and direction of data transfer such as "bulk out" or "interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) in". The entire configuration may have up to sixteen endpoints in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) each direction, allocated as needed among all the interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) - Data transfer on USB is packetized; each endpoint has a maximum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) packet size. Drivers must often be aware of conventions such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) flagging the end of bulk transfers using "short" (including zero
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) length) packets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) - The Linux USB API supports synchronous calls for control and bulk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) messages. It also supports asynchronous calls for all kinds of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) transfer, using request structures called "URBs" (USB Request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) Blocks).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) Accordingly, the USB Core API exposed to device drivers covers quite a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) lot of territory. You'll probably need to consult the USB 3.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) specification, available online from www.usb.org at no cost, as well as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) class or device specifications.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) The only host-side drivers that actually touch hardware (reading/writing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) registers, handling IRQs, and so on) are the HCDs. In theory, all HCDs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) provide the same functionality through the same API. In practice, that's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) becoming more true, but there are still differences
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) that crop up especially with fault handling on the less common controllers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) Different controllers don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) necessarily report the same aspects of failures, and recovery from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) faults (including software-induced ones like unlinking an URB) isn't yet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) fully consistent. Device driver authors should make a point of doing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) disconnect testing (while the device is active) with each different host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) controller driver, to make sure drivers don't have bugs of their own as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) well as to make sure they aren't relying on some HCD-specific behavior.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) .. _usb_chapter9:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) USB-Standard Types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) In ``<linux/usb/ch9.h>`` you will find the USB data types defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) chapter 9 of the USB specification. These data types are used throughout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) USB, and in APIs including this host side API, gadget APIs, usb character
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) devices and debugfs interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) .. kernel-doc:: include/linux/usb/ch9.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) .. _usb_header:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) Host-Side Data Types and Macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) The host side API exposes several layers to drivers, some of which are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) more necessary than others. These support lifecycle models for host side
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) drivers and devices, and support passing buffers through usbcore to some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) HCD that performs the I/O for the device driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) .. kernel-doc:: include/linux/usb.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) USB Core APIs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) There are two basic I/O models in the USB API. The most elemental one is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) asynchronous: drivers submit requests in the form of an URB, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) URB's completion callback handles the next step. All USB transfer types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) support that model, although there are special cases for control URBs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) (which always have setup and status stages, but may not have a data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) stage) and isochronous URBs (which allow large packets and include
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) per-packet fault reports). Built on top of that is synchronous API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) support, where a driver calls a routine that allocates one or more URBs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) submits them, and waits until they complete. There are synchronous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) wrappers for single-buffer control and bulk transfers (which are awkward
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) to use in some driver disconnect scenarios), and for scatterlist based
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) streaming i/o (bulk or interrupt).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) USB drivers need to provide buffers that can be used for DMA, although
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) they don't necessarily need to provide the DMA mapping themselves. There
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) are APIs to use used when allocating DMA buffers, which can prevent use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) of bounce buffers on some systems. In some cases, drivers may be able to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) rely on 64bit DMA to eliminate another kind of bounce buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) .. kernel-doc:: drivers/usb/core/urb.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) .. kernel-doc:: drivers/usb/core/message.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) .. kernel-doc:: drivers/usb/core/file.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) .. kernel-doc:: drivers/usb/core/driver.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) .. kernel-doc:: drivers/usb/core/usb.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) .. kernel-doc:: drivers/usb/core/hub.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) Host Controller APIs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) These APIs are only for use by host controller drivers, most of which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) implement standard register interfaces such as XHCI, EHCI, OHCI, or UHCI. UHCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) was one of the first interfaces, designed by Intel and also used by VIA;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) it doesn't do much in hardware. OHCI was designed later, to have the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) hardware do more work (bigger transfers, tracking protocol state, and so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) on). EHCI was designed with USB 2.0; its design has features that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) resemble OHCI (hardware does much more work) as well as UHCI (some parts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) of ISO support, TD list processing). XHCI was designed with USB 3.0. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) continues to shift support for functionality into hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) There are host controllers other than the "big three", although most PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) based controllers (and a few non-PCI based ones) use one of those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) interfaces. Not all host controllers use DMA; some use PIO, and there is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) also a simulator and a virtual host controller to pipe USB over the network.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) The same basic APIs are available to drivers for all those controllers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) For historical reasons they are in two layers: :c:type:`struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) usb_bus <usb_bus>` is a rather thin layer that became available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) in the 2.2 kernels, while :c:type:`struct usb_hcd <usb_hcd>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) is a more featureful layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) that lets HCDs share common code, to shrink driver size and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) significantly reduce hcd-specific behaviors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) .. kernel-doc:: drivers/usb/core/hcd.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) .. kernel-doc:: drivers/usb/core/hcd-pci.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) .. kernel-doc:: drivers/usb/core/buffer.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) The USB character device nodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) This chapter presents the Linux character device nodes. You may prefer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) to avoid writing new kernel code for your USB driver. User mode device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) drivers are usually packaged as applications or libraries, and may use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) character devices through some programming library that wraps it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) Such libraries include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) - `libusb <http://libusb.sourceforge.net>`__ for C/C++, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) - `jUSB <http://jUSB.sourceforge.net>`__ for Java.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) Some old information about it can be seen at the "USB Device Filesystem"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) section of the USB Guide. The latest copy of the USB Guide can be found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) at http://www.linux-usb.org/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) - They were used to be implemented via *usbfs*, but this is not part of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) the sysfs debug interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) - This particular documentation is incomplete, especially with respect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) to the asynchronous mode. As of kernel 2.5.66 the code and this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) (new) documentation need to be cross-reviewed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) What files are in "devtmpfs"?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) Conventionally mounted at ``/dev/bus/usb/``, usbfs features include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) - ``/dev/bus/usb/BBB/DDD`` ... magic files exposing the each device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) configuration descriptors, and supporting a series of ioctls for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) making device requests, including I/O to devices. (Purely for access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) by programs.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) Each bus is given a number (``BBB``) based on when it was enumerated; within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) each bus, each device is given a similar number (``DDD``). Those ``BBB/DDD``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) paths are not "stable" identifiers; expect them to change even if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) always leave the devices plugged in to the same hub port. *Don't even
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) think of saving these in application configuration files.* Stable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) identifiers are available, for user mode applications that want to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) them. HID and networking devices expose these stable IDs, so that for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) example you can be sure that you told the right UPS to power down its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) second server. Pleast note that it doesn't (yet) expose those IDs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) /dev/bus/usb/BBB/DDD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) Use these files in one of these basic ways:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) - *They can be read,* producing first the device descriptor (18 bytes) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) then the descriptors for the current configuration. See the USB 2.0 spec
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) for details about those binary data formats. You'll need to convert most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) multibyte values from little endian format to your native host byte
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) order, although a few of the fields in the device descriptor (both of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) the BCD-encoded fields, and the vendor and product IDs) will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) byteswapped for you. Note that configuration descriptors include
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) descriptors for interfaces, altsettings, endpoints, and maybe additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) class descriptors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) - *Perform USB operations* using *ioctl()* requests to make endpoint I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) requests (synchronously or asynchronously) or manage the device. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) requests need the ``CAP_SYS_RAWIO`` capability, as well as filesystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) access permissions. Only one ioctl request can be made on one of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) device files at a time. This means that if you are synchronously reading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) an endpoint from one thread, you won't be able to write to a different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) endpoint from another thread until the read completes. This works for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) *half duplex* protocols, but otherwise you'd use asynchronous i/o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) requests.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) Each connected USB device has one file. The ``BBB`` indicates the bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) number. The ``DDD`` indicates the device address on that bus. Both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) of these numbers are assigned sequentially, and can be reused, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) you can't rely on them for stable access to devices. For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) it's relatively common for devices to re-enumerate while they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) still connected (perhaps someone jostled their power supply, hub,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) or USB cable), so a device might be ``002/027`` when you first connect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) it and ``002/048`` sometime later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) These files can be read as binary data. The binary data consists
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) of first the device descriptor, then the descriptors for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) configuration of the device. Multi-byte fields in the device descriptor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) are converted to host endianness by the kernel. The configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) descriptors are in bus endian format! The configuration descriptor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) are wTotalLength bytes apart. If a device returns less configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) descriptor data than indicated by wTotalLength there will be a hole in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) the file for the missing bytes. This information is also shown
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) in text form by the ``/sys/kernel/debug/usb/devices`` file, described later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) These files may also be used to write user-level drivers for the USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) devices. You would open the ``/dev/bus/usb/BBB/DDD`` file read/write,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) read its descriptors to make sure it's the device you expect, and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) bind to an interface (or perhaps several) using an ioctl call. You
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) would issue more ioctls to the device to communicate to it using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) control, bulk, or other kinds of USB transfers. The IOCTLs are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) listed in the ``<linux/usbdevice_fs.h>`` file, and at this writing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) source code (``linux/drivers/usb/core/devio.c``) is the primary reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) for how to access devices through those files.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) Note that since by default these ``BBB/DDD`` files are writable only by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) root, only root can write such user mode drivers. You can selectively
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) grant read/write permissions to other users by using ``chmod``. Also,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) usbfs mount options such as ``devmode=0666`` may be helpful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) Life Cycle of User Mode Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) Such a driver first needs to find a device file for a device it knows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) how to handle. Maybe it was told about it because a ``/sbin/hotplug``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) event handling agent chose that driver to handle the new device. Or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) maybe it's an application that scans all the ``/dev/bus/usb`` device files,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) and ignores most devices. In either case, it should :c:func:`read()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) all the descriptors from the device file, and check them against what it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) knows how to handle. It might just reject everything except a particular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) vendor and product ID, or need a more complex policy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) Never assume there will only be one such device on the system at a time!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) If your code can't handle more than one device at a time, at least
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) detect when there's more than one, and have your users choose which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) device to use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) Once your user mode driver knows what device to use, it interacts with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) it in either of two styles. The simple style is to make only control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) requests; some devices don't need more complex interactions than those.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) (An example might be software using vendor-specific control requests for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) some initialization or configuration tasks, with a kernel driver for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) rest.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) More likely, you need a more complex style driver: one using non-control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) endpoints, reading or writing data and claiming exclusive use of an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) interface. *Bulk* transfers are easiest to use, but only their sibling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) *interrupt* transfers work with low speed devices. Both interrupt and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) *isochronous* transfers offer service guarantees because their bandwidth
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) is reserved. Such "periodic" transfers are awkward to use through usbfs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) unless you're using the asynchronous calls. However, interrupt transfers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) can also be used in a synchronous "one shot" style.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) Your user-mode driver should never need to worry about cleaning up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) request state when the device is disconnected, although it should close
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) its open file descriptors as soon as it starts seeing the ENODEV errors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) The ioctl() Requests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) To use these ioctls, you need to include the following headers in your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) userspace program::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) #include <linux/usb.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) #include <linux/usbdevice_fs.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) #include <asm/byteorder.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) The standard USB device model requests, from "Chapter 9" of the USB 2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) specification, are automatically included from the ``<linux/usb/ch9.h>``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) header.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) Unless noted otherwise, the ioctl requests described here will update
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) the modification time on the usbfs file to which they are applied
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) (unless they fail). A return of zero indicates success; otherwise, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) standard USB error code is returned (These are documented in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) :ref:`usb-error-codes`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) Each of these files multiplexes access to several I/O streams, one per
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) endpoint. Each device has one control endpoint (endpoint zero) which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) supports a limited RPC style RPC access. Devices are configured by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) hub_wq (in the kernel) setting a device-wide *configuration* that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) affects things like power consumption and basic functionality. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) endpoints are part of USB *interfaces*, which may have *altsettings*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) affecting things like which endpoints are available. Many devices only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) have a single configuration and interface, so drivers for them will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) ignore configurations and altsettings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) Management/Status Requests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) ~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) A number of usbfs requests don't deal very directly with device I/O.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) They mostly relate to device management and status. These are all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) synchronous requests.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) USBDEVFS_CLAIMINTERFACE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) This is used to force usbfs to claim a specific interface, which has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) not previously been claimed by usbfs or any other kernel driver. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) ioctl parameter is an integer holding the number of the interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) (bInterfaceNumber from descriptor).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) Note that if your driver doesn't claim an interface before trying to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) use one of its endpoints, and no other driver has bound to it, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) the interface is automatically claimed by usbfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) This claim will be released by a RELEASEINTERFACE ioctl, or by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) closing the file descriptor. File modification time is not updated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) USBDEVFS_CONNECTINFO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) Says whether the device is lowspeed. The ioctl parameter points to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) structure like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) struct usbdevfs_connectinfo {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) unsigned int devnum;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) unsigned char slow;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) File modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) *You can't tell whether a "not slow" device is connected at high
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) speed (480 MBit/sec) or just full speed (12 MBit/sec).* You should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) know the devnum value already, it's the DDD value of the device file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) USBDEVFS_GETDRIVER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) Returns the name of the kernel driver bound to a given interface (a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) string). Parameter is a pointer to this structure, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) modified::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) struct usbdevfs_getdriver {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) unsigned int interface;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) char driver[USBDEVFS_MAXDRIVERNAME + 1];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) File modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) USBDEVFS_IOCTL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) Passes a request from userspace through to a kernel driver that has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) an ioctl entry in the *struct usb_driver* it registered::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) struct usbdevfs_ioctl {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) int ifno;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) int ioctl_code;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) void *data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) /* user mode call looks like this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) * 'request' becomes the driver->ioctl() 'code' parameter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) * the size of 'param' is encoded in 'request', and that data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) * is copied to or from the driver->ioctl() 'buf' parameter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) static int
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) struct usbdevfs_ioctl wrapper;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) wrapper.ifno = ifno;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) wrapper.ioctl_code = request;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) wrapper.data = param;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) File modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) This request lets kernel drivers talk to user mode code through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) filesystem operations even when they don't create a character or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) block special device. It's also been used to do things like ask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) devices what device special file should be used. Two pre-defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) ioctls are used to disconnect and reconnect kernel drivers, so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) user mode code can completely manage binding and configuration of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) USBDEVFS_RELEASEINTERFACE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) This is used to release the claim usbfs made on interface, either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) implicitly or because of a USBDEVFS_CLAIMINTERFACE call, before the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) file descriptor is closed. The ioctl parameter is an integer holding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) the number of the interface (bInterfaceNumber from descriptor); File
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) *No security check is made to ensure that the task which made
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) the claim is the one which is releasing it. This means that user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) mode driver may interfere other ones.*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) USBDEVFS_RESETEP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) Resets the data toggle value for an endpoint (bulk or interrupt) to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) DATA0. The ioctl parameter is an integer endpoint number (1 to 15,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) as identified in the endpoint descriptor), with USB_DIR_IN added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) if the device's endpoint sends data to the host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) .. Warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) *Avoid using this request. It should probably be removed.* Using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) it typically means the device and driver will lose toggle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) synchronization. If you really lost synchronization, you likely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) need to completely handshake with the device, using a request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) like CLEAR_HALT or SET_INTERFACE.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) USBDEVFS_DROP_PRIVILEGES
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) This is used to relinquish the ability to do certain operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) which are considered to be privileged on a usbfs file descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) This includes claiming arbitrary interfaces, resetting a device on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) which there are currently claimed interfaces from other users, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) issuing USBDEVFS_IOCTL calls. The ioctl parameter is a 32 bit mask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) of interfaces the user is allowed to claim on this file descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) You may issue this ioctl more than one time to narrow said mask.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) Synchronous I/O Support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) ~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) Synchronous requests involve the kernel blocking until the user mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) request completes, either by finishing successfully or by reporting an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) error. In most cases this is the simplest way to use usbfs, although as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) noted above it does prevent performing I/O to more than one endpoint at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) a time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) USBDEVFS_BULK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) Issues a bulk read or write request to the device. The ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) parameter is a pointer to this structure::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) struct usbdevfs_bulktransfer {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) unsigned int ep;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) unsigned int len;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) unsigned int timeout; /* in milliseconds */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) void *data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) The ``ep`` value identifies a bulk endpoint number (1 to 15, as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) identified in an endpoint descriptor), masked with USB_DIR_IN when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) referring to an endpoint which sends data to the host from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) device. The length of the data buffer is identified by ``len``; Recent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) kernels support requests up to about 128KBytes. *FIXME say how read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) length is returned, and how short reads are handled.*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) USBDEVFS_CLEAR_HALT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) Clears endpoint halt (stall) and resets the endpoint toggle. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) only meaningful for bulk or interrupt endpoints. The ioctl parameter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) is an integer endpoint number (1 to 15, as identified in an endpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) descriptor), masked with USB_DIR_IN when referring to an endpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) which sends data to the host from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) Use this on bulk or interrupt endpoints which have stalled,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) returning ``-EPIPE`` status to a data transfer request. Do not issue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) the control request directly, since that could invalidate the host's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) record of the data toggle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) USBDEVFS_CONTROL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) Issues a control request to the device. The ioctl parameter points
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) to a structure like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) struct usbdevfs_ctrltransfer {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) __u8 bRequestType;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) __u8 bRequest;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) __u16 wValue;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) __u16 wIndex;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) __u16 wLength;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) __u32 timeout; /* in milliseconds */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) void *data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) The first eight bytes of this structure are the contents of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) SETUP packet to be sent to the device; see the USB 2.0 specification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) for details. The bRequestType value is composed by combining a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) ``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) value (from ``linux/usb.h``). If wLength is nonzero, it describes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) the length of the data buffer, which is either written to the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) (USB_DIR_OUT) or read from the device (USB_DIR_IN).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) At this writing, you can't transfer more than 4 KBytes of data to or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) from a device; usbfs has a limit, and some host controller drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) have a limit. (That's not usually a problem.) *Also* there's no way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) to say it's not OK to get a short read back from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) USBDEVFS_RESET
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) Does a USB level device reset. The ioctl parameter is ignored. After
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) the reset, this rebinds all device interfaces. File modification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) *Avoid using this call* until some usbcore bugs get fixed, since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) it does not fully synchronize device, interface, and driver (not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) just usbfs) state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) USBDEVFS_SETINTERFACE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) Sets the alternate setting for an interface. The ioctl parameter is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) a pointer to a structure like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) struct usbdevfs_setinterface {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) unsigned int interface;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) unsigned int altsetting;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) File modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) Those struct members are from some interface descriptor applying to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) the current configuration. The interface number is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) bInterfaceNumber value, and the altsetting number is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) bAlternateSetting value. (This resets each endpoint in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) interface.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) USBDEVFS_SETCONFIGURATION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) Issues the :c:func:`usb_set_configuration()` call for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) device. The parameter is an integer holding the number of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) configuration (bConfigurationValue from descriptor). File
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) *Avoid using this call* until some usbcore bugs get fixed, since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) it does not fully synchronize device, interface, and driver (not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) just usbfs) state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) Asynchronous I/O Support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) ~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) As mentioned above, there are situations where it may be important to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) initiate concurrent operations from user mode code. This is particularly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) important for periodic transfers (interrupt and isochronous), but it can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) be used for other kinds of USB requests too. In such cases, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) asynchronous requests described here are essential. Rather than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) submitting one request and having the kernel block until it completes,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) the blocking is separate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) These requests are packaged into a structure that resembles the URB used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) (number, masked with USB_DIR_IN as appropriate), buffer and length,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) and a user "context" value serving to uniquely identify each request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) (It's usually a pointer to per-request data.) Flags can modify requests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) (not as many as supported for kernel drivers).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) Each request can specify a realtime signal number (between SIGRTMIN and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) SIGRTMAX, inclusive) to request a signal be sent when the request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) completes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) When usbfs returns these urbs, the status value is updated, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) buffer may have been modified. Except for isochronous transfers, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) actual_length is updated to say how many bytes were transferred; if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) USBDEVFS_URB_DISABLE_SPD flag is set ("short packets are not OK"), if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) fewer bytes were read than were requested then you get an error report::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) struct usbdevfs_iso_packet_desc {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) unsigned int length;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) unsigned int actual_length;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) unsigned int status;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) struct usbdevfs_urb {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) unsigned char type;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) unsigned char endpoint;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) int status;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) unsigned int flags;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) void *buffer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) int buffer_length;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) int actual_length;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) int start_frame;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) int number_of_packets;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) int error_count;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) unsigned int signr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) void *usercontext;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) struct usbdevfs_iso_packet_desc iso_frame_desc[];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) For these asynchronous requests, the file modification time reflects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) when the request was initiated. This contrasts with their use with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) synchronous requests, where it reflects when requests complete.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) USBDEVFS_DISCARDURB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) *TBS* File modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) USBDEVFS_DISCSIGNAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) *TBS* File modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) USBDEVFS_REAPURB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) *TBS* File modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) USBDEVFS_REAPURBNDELAY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) *TBS* File modification time is not updated by this request.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) USBDEVFS_SUBMITURB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) *TBS*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) The USB devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) The USB devices are now exported via debugfs:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) - ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) devices on known to the kernel, and their configuration descriptors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) You can also poll() this to learn about new devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) /sys/kernel/debug/usb/devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) This file is handy for status viewing tools in user mode, which can scan
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) the text format and ignore most of it. More detailed device status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) (including class and vendor status) is available from device-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) files. For information about the current format of this file, see below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) This file, in combination with the poll() system call, can also be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) to detect when devices are added or removed::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) int fd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) struct pollfd pfd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) fd = open("/sys/kernel/debug/usb/devices", O_RDONLY);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) pfd = { fd, POLLIN, 0 };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) for (;;) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704) /* The first time through, this call will return immediately. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) poll(&pfd, 1, -1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) /* To see what's changed, compare the file's previous and current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) contents or scan the filesystem. (Scanning is more precise.) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) Note that this behavior is intended to be used for informational and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) debug purposes. It would be more appropriate to use programs such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) udev or HAL to initialize a device or start a user-mode helper program,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) for instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) In this file, each device's output has multiple lines of ASCII output.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) I made it ASCII instead of binary on purpose, so that someone
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) can obtain some useful data from it without the use of an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) auxiliary program. However, with an auxiliary program, the numbers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) in the first 4 columns of each ``T:`` line (topology info:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) Each line is tagged with a one-character ID for that line::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) T = Topology (etc.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) B = Bandwidth (applies only to USB host controllers, which are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) virtualized as root hubs)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) D = Device descriptor info.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) P = Product ID info. (from Device descriptor, but they won't fit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) together on one line)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) S = String descriptors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) C = Configuration descriptor info. (* = active configuration)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) I = Interface descriptor info.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735) E = Endpoint descriptor info.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) /sys/kernel/debug/usb/devices output format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) Legend::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) d = decimal number (may have leading spaces or 0's)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) x = hexadecimal number (may have leading spaces or 0's)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) s = string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) Topology info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) ^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) | | | | | | | | |__MaxChildren
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) | | | | | | | |__Device Speed in Mbps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) | | | | | | |__DeviceNumber
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) | | | | | |__Count of devices at this level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) | | | | |__Connector/Port on Parent for this device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) | | | |__Parent DeviceNumber
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) | | |__Level in topology for this bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) | |__Bus number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) |__Topology info tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) Speed may be:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) ======= ======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) 1.5 Mbit/s for low speed USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) 12 Mbit/s for full speed USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) 480 Mbit/s for high speed USB (added for USB 2.0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) also used for Wireless USB, which has no fixed speed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) 5000 Mbit/s for SuperSpeed USB (added for USB 3.0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771) ======= ======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) For reasons lost in the mists of time, the Port number is always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774) too low by 1. For example, a device plugged into port 4 will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) show up with ``Port=03``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) Bandwidth info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) ^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) | | | |__Number of isochronous requests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) | | |__Number of interrupt requests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) | |__Total Bandwidth allocated to this bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) |__Bandwidth info tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) Bandwidth allocation is an approximation of how much of one frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789) (millisecond) is in use. It reflects only periodic transfers, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) are the only transfers that reserve bandwidth. Control and bulk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) transfers use all other bandwidth, including reserved bandwidth that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) is not used for transfers (such as for short packets).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) The percentage is how much of the "reserved" bandwidth is scheduled by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) those transfers. For a low or full speed bus (loosely, "USB 1.1"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) 90% of the bus bandwidth is reserved. For a high speed bus (loosely,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) "USB 2.0") 80% is reserved.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) Device descriptor info & Product ID info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) where::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) | | | | | | |__NumberConfigurations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) | | | | | |__MaxPacketSize of Default Endpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) | | | | |__DeviceProtocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) | | | |__DeviceSubClass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) | | |__DeviceClass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) | |__Device USB version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) |__Device info tag #1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) where::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) | | | |__Product revision number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) | | |__Product ID code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) | |__Vendor ID code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) |__Device info tag #2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) String descriptor info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) ^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832) S: Manufacturer=ssss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) | |__Manufacturer of this device as read from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) | For USB host controller drivers (virtual root hubs) this may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) | be omitted, or (for newer drivers) will identify the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) | version and the driver which provides this hub emulation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) |__String info tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) S: Product=ssss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) | |__Product description of this device as read from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) | For older USB host controller drivers (virtual root hubs) this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) | indicates the driver; for newer ones, it's a product (and vendor)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) | description that often comes from the kernel's PCI ID database.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) |__String info tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) S: SerialNumber=ssss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) | |__Serial Number of this device as read from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) | For USB host controller drivers (virtual root hubs) this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) | some unique ID, normally a bus ID (address or slot name) that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850) | can't be shared with any other device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) |__String info tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855) Configuration descriptor info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) | | | | | |__MaxPower in mA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) | | | | |__Attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) | | | |__ConfiguratioNumber
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) | | |__NumberOfInterfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) | |__ "*" indicates the active configuration (others are " ")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) |__Config info tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) USB devices may have multiple configurations, each of which act
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) rather differently. For example, a bus-powered configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) might be much less capable than one that is self-powered. Only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) one device configuration can be active at a time; most devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) have only one configuration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) Each configuration consists of one or more interfaces. Each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) interface serves a distinct "function", which is typically bound
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) to a different USB device driver. One common example is a USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) speaker with an audio interface for playback, and a HID interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) for use with software volume control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) Interface descriptor info (can be multiple per Config)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883) I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) | | | | | | | | |__Driver name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885) | | | | | | | | or "(none)"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) | | | | | | | |__InterfaceProtocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) | | | | | | |__InterfaceSubClass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888) | | | | | |__InterfaceClass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) | | | | |__NumberOfEndpoints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) | | | |__AlternateSettingNumber
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) | | |__InterfaceNumber
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) | |__ "*" indicates the active altsetting (others are " ")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) |__Interface info tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) A given interface may have one or more "alternate" settings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) For example, default settings may not use more than a small
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) amount of periodic bandwidth. To use significant fractions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) of bus bandwidth, drivers must select a non-default altsetting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) Only one setting for an interface may be active at a time, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) only one driver may bind to an interface at a time. Most devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902) have only one alternate setting per interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) Endpoint descriptor info (can be multiple per Interface)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910) E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911) | | | | |__Interval (max) between transfers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) | | | |__EndpointMaxPacketSize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) | | |__Attributes(EndpointType)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914) | |__EndpointAddress(I=In,O=Out)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) |__Endpoint info tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) The interval is nonzero for all periodic (interrupt or isochronous)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) endpoints. For high speed endpoints the transfer interval may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919) measured in microseconds rather than milliseconds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921) For high speed periodic endpoints, the ``EndpointMaxPacketSize`` reflects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) the per-microframe data transfer size. For "high bandwidth"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) endpoints, that can reflect two or three packets (for up to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924) 3KBytes every 125 usec) per endpoint.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) With the Linux-USB stack, periodic bandwidth reservations use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) transfer intervals and sizes provided by URBs, which can be less
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928) than those found in endpoint descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) Usage examples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933) If a user or script is interested only in Topology info, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934) example, use something like ``grep ^T: /sys/kernel/debug/usb/devices``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) for only the Topology lines. A command like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) ``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937) only the lines that begin with the characters in square brackets,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938) where the valid characters are TDPCIE. With a slightly more able
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) script, it can display any selected lines (for example, only T, D,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) and P lines) and change their output format. (The ``procusb``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) Perl script is the beginning of this idea. It will list only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942) selected lines [selected from TBDPSCIE] or "All" lines from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943) ``/sys/kernel/debug/usb/devices``.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945) The Topology lines can be used to generate a graphic/pictorial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946) of the USB devices on a system's root hub. (See more below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947) on how to do this.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949) The Interface lines can be used to determine what driver is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950) being used for each device, and which altsetting it activated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952) The Configuration lines could be used to list maximum power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953) (in milliamps) that a system's USB devices are using.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954) For example, ``grep ^C: /sys/kernel/debug/usb/devices``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957) Here's an example, from a system which has a UHCI root hub,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958) an external hub connected to the root hub, and a mouse and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959) a serial converter connected to the external hub.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963) T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964) B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965) D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966) P: Vendor=0000 ProdID=0000 Rev= 0.00
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967) S: Product=USB UHCI Root Hub
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968) S: SerialNumber=dce0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969) C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971) E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973) T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974) D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975) P: Vendor=0451 ProdID=1446 Rev= 1.00
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976) C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977) I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978) E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980) T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981) D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982) P: Vendor=04b4 ProdID=0001 Rev= 0.00
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983) C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984) I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985) E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987) T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988) D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) P: Vendor=0565 ProdID=0001 Rev= 1.08
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990) S: Manufacturer=Peracom Networks, Inc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991) S: Product=Peracom USB to Serial Converter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992) C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993) I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994) E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995) E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996) E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999) Selecting only the ``T:`` and ``I:`` lines from this (for example, by using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000) ``procusb ti``), we have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005) T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006) I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007) T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008) I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009) T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010) I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013) Physically this looks like (or could be converted to)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015) +------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) | PC/root_hub (12)| Dev# = 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017) +------------------+ (nn) is Mbps.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018) Level 0 | CN.0 | CN.1 | [CN = connector/port #]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019) +------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020) /
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021) /
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022) +-----------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023) Level 1 | Dev#2: 4-port hub (12)|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024) +-----------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025) |CN.0 |CN.1 |CN.2 |CN.3 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026) +-----------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) \ \____________________
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028) \_____ \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029) \ \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030) +--------------------+ +--------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031) Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032) +--------------------+ +--------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036) Or, in a more tree-like structure (ports [Connectors] without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037) connections could be omitted)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) PC: Dev# 1, root hub, 2 ports, 12 Mbps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040) |_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041) |_ CN.0: Dev #3, mouse, 1.5 Mbps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042) |_ CN.1:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043) |_ CN.2: Dev #4, serial, 12 Mbps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) |_ CN.3:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045) |_ CN.1:
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags