^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) USB Gadget API for Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) :Author: David Brownell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) :Date: 20 August 2004
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This document presents a Linux-USB "Gadget" kernel mode API, for use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) within peripherals and other USB devices that embed Linux. It provides
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) an overview of the API structure, and shows how that fits into a system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) development project. This is the first such API released on Linux to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) address a number of important problems, including:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) - Supports USB 2.0, for high speed devices which can stream data at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) several dozen megabytes per second.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) - Handles devices with dozens of endpoints just as well as ones with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) just two fixed-function ones. Gadget drivers can be written so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) they're easy to port to new hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) - Flexible enough to expose more complex USB device capabilities such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) as multiple configurations, multiple interfaces, composite devices,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) and alternate interface settings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) - USB "On-The-Go" (OTG) support, in conjunction with updates to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Linux-USB host side.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) - Sharing data structures and API models with the Linux-USB host side
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) API. This helps the OTG support, and looks forward to more-symmetric
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) frameworks (where the same I/O model is used by both host and device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) side drivers).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) - Minimalist, so it's easier to support new device controller hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) I/O processing doesn't imply large demands for memory or CPU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) resources.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Most Linux developers will not be able to use this API, since they have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) USB ``host`` hardware in a PC, workstation, or server. Linux users with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) embedded systems are more likely to have USB peripheral hardware. To
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) distinguish drivers running inside such hardware from the more familiar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) Linux "USB device drivers", which are host side proxies for the real USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) devices, a different term is used: the drivers inside the peripherals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) are "USB gadget drivers". In USB protocol interactions, the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) driver is the master (or "client driver") and the gadget driver is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) slave (or "function driver").
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) The gadget API resembles the host side Linux-USB API in that both use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) queues of request objects to package I/O buffers, and those requests may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) be submitted or canceled. They share common definitions for the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) USB *Chapter 9* messages, structures, and constants. Also, both APIs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) bind and unbind drivers to devices. The APIs differ in detail, since the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) host side's current URB framework exposes a number of implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) details and assumptions that are inappropriate for a gadget API. While
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) the model for control transfers and configuration management is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) necessarily different (one side is a hardware-neutral master, the other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) is a hardware-aware slave), the endpoint I/0 API used here should also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) be usable for an overhead-reduced host side API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Structure of Gadget Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) A system running inside a USB peripheral normally has at least three
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) layers inside the kernel to handle USB protocol processing, and may have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) additional layers in user space code. The ``gadget`` API is used by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) middle layer to interact with the lowest level (which directly handles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) hardware).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) In Linux, from the bottom up, these layers are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) *USB Controller Driver*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) This is the lowest software level. It is the only layer that talks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) to hardware, through registers, fifos, dma, irqs, and the like. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) ``<linux/usb/gadget.h>`` API abstracts the peripheral controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) endpoint hardware. That hardware is exposed through endpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) objects, which accept streams of IN/OUT buffers, and through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) callbacks that interact with gadget drivers. Since normal USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) devices only have one upstream port, they only have one of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) drivers. The controller driver can support any number of different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) gadget drivers, but only one of them can be used at a time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) Examples of such controller hardware include the PCI-based NetChip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) 2280 USB 2.0 high speed controller, the SA-11x0 or PXA-25x UDC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) (found within many PDAs), and a variety of other products.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) *Gadget Driver*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) The lower boundary of this driver implements hardware-neutral USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) functions, using calls to the controller driver. Because such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) hardware varies widely in capabilities and restrictions, and is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) in embedded environments where space is at a premium, the gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) driver is often configured at compile time to work with endpoints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) supported by one particular controller. Gadget drivers may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) portable to several different controllers, using conditional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) compilation. (Recent kernels substantially simplify the work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) involved in supporting new hardware, by *autoconfiguring* endpoints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) automatically for many bulk-oriented drivers.) Gadget driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) responsibilities include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) - handling setup requests (ep0 protocol responses) possibly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) including class-specific functionality
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) - returning configuration and string descriptors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) - (re)setting configurations and interface altsettings, including
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) enabling and configuring endpoints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) - handling life cycle events, such as managing bindings to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) hardware, USB suspend/resume, remote wakeup, and disconnection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) from the USB host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) - managing IN and OUT transfers on all currently enabled endpoints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Such drivers may be modules of proprietary code, although that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) approach is discouraged in the Linux community.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) *Upper Level*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Most gadget drivers have an upper boundary that connects to some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Linux driver or framework in Linux. Through that boundary flows the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) data which the gadget driver produces and/or consumes through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) protocol transfers over USB. Examples include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) - user mode code, using generic (gadgetfs) or application specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) files in ``/dev``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) - networking subsystem (for network gadgets, like the CDC Ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Model gadget driver)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - data capture drivers, perhaps video4Linux or a scanner driver; or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) test and measurement hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) - input subsystem (for HID gadgets)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) - sound subsystem (for audio gadgets)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) - file system (for PTP gadgets)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) - block i/o subsystem (for usb-storage gadgets)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) - ... and more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) *Additional Layers*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Other layers may exist. These could include kernel layers, such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) network protocol stacks, as well as user mode applications building
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) on standard POSIX system call APIs such as ``open()``, ``close()``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) ``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) be an option. Such user mode code will not necessarily be subject to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) the GNU General Public License (GPL).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) OTG-capable systems will also need to include a standard Linux-USB host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) side stack, with ``usbcore``, one or more *Host Controller Drivers*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) List", and so forth. There will also be an *OTG Controller Driver*,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) which is visible to gadget and device driver developers only indirectly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) That helps the host and device side USB controllers implement the two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) new OTG protocols (HNP and SRP). Roles switch (host to peripheral, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) vice versa) using HNP during USB suspend processing, and SRP can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) viewed as a more battery-friendly kind of device wakeup protocol.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) Over time, reusable utilities are evolving to help make some gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) driver tasks simpler. For example, building configuration descriptors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) from vectors of descriptors for the configurations interfaces and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) endpoints is now automated, and many drivers now use autoconfiguration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) to choose hardware endpoints and initialize their descriptors. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) potential example of particular interest is code implementing standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) USB-IF protocols for HID, networking, storage, or audio classes. Some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) developers are interested in KDB or KGDB hooks, to let target hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) be remotely debugged. Most such USB protocol code doesn't need to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) hardware-specific, any more than network protocols like X11, HTTP, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) NFS are. Such gadget-side interface drivers should eventually be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) combined, to implement composite devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) Kernel Mode Gadget API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) Gadget drivers declare themselves through a struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) :c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) for a struct usb_gadget. The response to a set_configuration usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) involves enabling one or more of the struct usb_ep objects exposed by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) the gadget, and submitting one or more struct usb_request buffers to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) transfer data. Understand those four data types, and their operations,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) and you will understand how this API works.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) .. Note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) Other than the "Chapter 9" data types, most of the significant data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) types and functions are described here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) However, some relevant information is likely omitted from what you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) are reading. One example of such information is endpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) autoconfiguration. You'll have to read the header file, and use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) example source code (such as that for "Gadget Zero"), to fully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) understand the API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) The part of the API implementing some basic driver capabilities is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) specific to the version of the Linux kernel that's in use. The 2.6
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) and upper kernel versions include a *driver model* framework that has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) no analogue on earlier kernels; so those parts of the gadget API are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) not fully portable. (They are implemented on 2.4 kernels, but in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) different way.) The driver model state is another part of this API that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) ignored by the kerneldoc tools.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) The core API does not expose every possible hardware feature, only the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) most widely available ones. There are significant hardware features,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) such as device-to-device DMA (without temporary storage in a memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) buffer) that would be added using hardware-specific APIs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) This API allows drivers to use conditional compilation to handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) endpoint capabilities of different hardware, but doesn't require that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) Hardware tends to have arbitrary restrictions, relating to transfer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) types, addressing, packet sizes, buffering, and availability. As a rule,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) such differences only matter for "endpoint zero" logic that handles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) device configuration and management. The API supports limited run-time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) detection of capabilities, through naming conventions for endpoints.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) Many drivers will be able to at least partially autoconfigure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) themselves. In particular, driver init sections will often have endpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) autoconfiguration logic that scans the hardware's list of endpoints to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) find ones matching the driver requirements (relying on those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) conventions), to eliminate some of the most common reasons for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) conditional compilation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) Like the Linux-USB host side API, this API exposes the "chunky" nature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) of USB messages: I/O requests are in terms of one or more "packets", and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) packet boundaries are visible to drivers. Compared to RS-232 serial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) protocols, USB resembles synchronous protocols like HDLC (N bytes per
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) frame, multipoint addressing, host as the primary station and devices as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) secondary stations) more than asynchronous ones (tty style: 8 data bits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) per frame, no parity, one stop bit). So for example the controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) drivers won't buffer two single byte writes into a single two-byte USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) IN packet, although gadget drivers may do so when they implement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) protocols where packet boundaries (and "short packets") are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) significant.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) Driver Life Cycle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) Gadget drivers make endpoint I/O requests to hardware without needing to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) know many details of the hardware, but driver setup/configuration code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) needs to handle some differences. Use the API like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 1. Register a driver for the particular device side usb controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) hardware, such as the net2280 on PCI (USB 2.0), sa11x0 or pxa25x as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) found in Linux PDAs, and so on. At this point the device is logically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) in the USB ch9 initial state (``attached``), drawing no power and not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) usable (since it does not yet support enumeration). Any host should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) not see the device, since it's not activated the data line pullup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) used by the host to detect a device, even if VBUS power is available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) 2. Register a gadget driver that implements some higher level device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) function. That will then bind() to a :c:type:`usb_gadget`, which activates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) the data line pullup sometime after detecting VBUS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) 3. The hardware driver can now start enumerating. The steps it handles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) are to accept USB ``power`` and ``set_address`` requests. Other steps are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) handled by the gadget driver. If the gadget driver module is unloaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) before the host starts to enumerate, steps before step 7 are skipped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) 4. The gadget driver's ``setup()`` call returns usb descriptors, based both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) on what the bus interface hardware provides and on the functionality
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) being implemented. That can involve alternate settings or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) configurations, unless the hardware prevents such operation. For OTG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) devices, each configuration descriptor includes an OTG descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) 5. The gadget driver handles the last step of enumeration, when the USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) host issues a ``set_configuration`` call. It enables all endpoints used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) in that configuration, with all interfaces in their default settings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) That involves using a list of the hardware's endpoints, enabling each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) endpoint according to its descriptor. It may also involve using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) ``usb_gadget_vbus_draw`` to let more power be drawn from VBUS, as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) allowed by that configuration. For OTG devices, setting a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) configuration may also involve reporting HNP capabilities through a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) user interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) 6. Do real work and perform data transfers, possibly involving changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) to interface settings or switching to new configurations, until the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) device is disconnect()ed from the host. Queue any number of transfer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) requests to each endpoint. It may be suspended and resumed several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) times before being disconnected. On disconnect, the drivers go back
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) to step 3 (above).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) 7. When the gadget driver module is being unloaded, the driver unbind()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) callback is issued. That lets the controller driver be unloaded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) Drivers will normally be arranged so that just loading the gadget driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) module (or statically linking it into a Linux kernel) allows the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) peripheral device to be enumerated, but some drivers will defer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) enumeration until some higher level component (like a user mode daemon)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) enables it. Note that at this lowest level there are no policies about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) how ep0 configuration logic is implemented, except that it should obey
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) USB specifications. Such issues are in the domain of gadget drivers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) including knowing about implementation constraints imposed by some USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) controllers or understanding that composite devices might happen to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) built by integrating reusable components.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) Note that the lifecycle above can be slightly different for OTG devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) Other than providing an additional OTG descriptor in each configuration,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) only the HNP-related differences are particularly visible to driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) code. They involve reporting requirements during the ``SET_CONFIGURATION``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) request, and the option to invoke HNP during some suspend callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) Also, SRP changes the semantics of ``usb_gadget_wakeup`` slightly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) USB 2.0 Chapter 9 Types and Constants
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) -------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) Gadget drivers rely on common USB structures and constants defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) the :ref:`linux/usb/ch9.h <usb_chapter9>` header file, which is standard in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) Linux 2.6+ kernels. These are the same types and constants used by host side
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) drivers (and usbcore).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) Core Objects and Methods
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) drivers to interact with USB peripheral controller drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) .. kernel-doc:: include/linux/usb/gadget.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) Optional Utilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) The core API is sufficient for writing a USB Gadget Driver, but some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) optional utilities are provided to simplify common tasks. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) utilities include endpoint autoconfiguration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) .. kernel-doc:: drivers/usb/gadget/usbstring.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) .. kernel-doc:: drivers/usb/gadget/config.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) Composite Device Framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) The core API is sufficient for writing drivers for composite USB devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) (with more than one function in a given configuration), and also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) multi-configuration devices (also more than one function, but not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) necessarily sharing a given configuration). There is however an optional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) framework which makes it easier to reuse and combine functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) Devices using this framework provide a struct usb_composite_driver,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) which in turn provides one or more struct usb_configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) instances. Each such configuration includes at least one struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) :c:type:`usb_function`, which packages a user visible role such as "network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) link" or "mass storage device". Management functions may also exist,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) such as "Device Firmware Upgrade".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) .. kernel-doc:: include/linux/usb/composite.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) .. kernel-doc:: drivers/usb/gadget/composite.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) Composite Device Functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) At this writing, a few of the current gadget drivers have been converted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) to this framework. Near-term plans include converting all of them,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) except for ``gadgetfs``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) Peripheral Controller Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) The first hardware supporting this API was the NetChip 2280 controller,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) which supports USB 2.0 high speed and is based on PCI. This is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) ``net2280`` driver module. The driver supports Linux kernel versions 2.4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) and 2.6; contact NetChip Technologies for development boards and product
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) Other hardware working in the ``gadget`` framework includes: Intel's PXA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) 25x and IXP42x series processors (``pxa2xx_udc``), Toshiba TC86c001
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) "Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) (``mq11xx_udc``), Hynix HMS30C7202 (``h7202_udc``), National 9303/4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) (``n9604_udc``), Texas Instruments OMAP (``omap_udc``), Sharp LH7A40x
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) (``lh7a40x_udc``), and more. Most of those are full speed controllers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) At this writing, there are people at work on drivers in this framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) for several other USB device controllers, with plans to make many of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) them be widely available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) A partial USB simulator, the ``dummy_hcd`` driver, is available. It can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) act like a net2280, a pxa25x, or an sa11x0 in terms of available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) endpoints and device speeds; and it simulates control, bulk, and to some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) extent interrupt transfers. That lets you develop some parts of a gadget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) driver on a normal PC, without any special hardware, and perhaps with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) the assistance of tools such as GDB running with User Mode Linux. At
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) least one person has expressed interest in adapting that approach,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) hooking it up to a simulator for a microcontroller. Such simulators can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) help debug subsystems where the runtime hardware is unfriendly to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) software development, or is not yet available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) Support for other controllers is expected to be developed and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) contributed over time, as this driver framework evolves.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) Gadget Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) In addition to *Gadget Zero* (used primarily for testing and development
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) with drivers for usb controller hardware), other gadget drivers exist.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) There's an ``ethernet`` gadget driver, which implements one of the most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) useful *Communications Device Class* (CDC) models. One of the standards
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) for cable modem interoperability even specifies the use of this ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) model as one of two mandatory options. Gadgets using this code look to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) USB host as if they're an Ethernet adapter. It provides access to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) network where the gadget's CPU is one host, which could easily be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) bridging, routing, or firewalling access to other networks. Since some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) hardware can't fully implement the CDC Ethernet requirements, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) driver also implements a "good parts only" subset of CDC Ethernet. (That
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) subset doesn't advertise itself as CDC Ethernet, to avoid creating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) problems.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) Support for Microsoft's ``RNDIS`` protocol has been contributed by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) Pengutronix and Auerswald GmbH. This is like CDC Ethernet, but it runs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) on more slightly USB hardware (but less than the CDC subset). However,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) its main claim to fame is being able to connect directly to recent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) versions of Windows, using drivers that Microsoft bundles and supports,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) making it much simpler to network with Windows.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) There is also support for user mode gadget drivers, using ``gadgetfs``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) This provides a *User Mode API* that presents each endpoint as a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) file descriptor. I/O is done using normal ``read()`` and ``read()`` calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) Familiar tools like GDB and pthreads can be used to develop and debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) user mode drivers, so that once a robust controller driver is available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) many applications for it won't require new kernel mode software. Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) 2.6 *Async I/O (AIO)* support is available, so that user mode software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) can stream data with only slightly more overhead than a kernel driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) There's a USB Mass Storage class driver, which provides a different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) solution for interoperability with systems such as MS-Windows and MacOS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) That *Mass Storage* driver uses a file or block device as backing store
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) for a drive, like the ``loop`` driver. The USB host uses the BBB, CB, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) CBI versions of the mass storage class specification, using transparent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) SCSI commands to access the data from the backing store.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) There's a "serial line" driver, useful for TTY style operation over USB.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) The latest version of that driver supports CDC ACM style operation, like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) a USB modem, and so on most hardware it can interoperate easily with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) MS-Windows. One interesting use of that driver is in boot firmware (like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) a BIOS), which can sometimes use that model with very small systems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) without real serial lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) Support for other kinds of gadget is expected to be developed and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) contributed over time, as this driver framework evolves.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) USB On-The-GO (OTG)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) USB OTG support on Linux 2.6 was initially developed by Texas
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) Instruments for `OMAP <http://www.omap.com>`__ 16xx and 17xx series
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) processors. Other OTG systems should work in similar ways, but the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) hardware level details could be very different.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) Systems need specialized hardware support to implement OTG, notably
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) including a special *Mini-AB* jack and associated transceiver to support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) *Dual-Role* operation: they can act either as a host, using the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) Linux-USB host side driver stack, or as a peripheral, using this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) ``gadget`` framework. To do that, the system software relies on small
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) additions to those programming interfaces, and on a new internal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) component (here called an "OTG Controller") affecting which driver stack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) connects to the OTG port. In each role, the system can re-use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) existing pool of hardware-neutral drivers, layered on top of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) controller driver interfaces (:c:type:`usb_bus` or :c:type:`usb_gadget`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) Such drivers need at most minor changes, and most of the calls added to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) support OTG can also benefit non-OTG products.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) - Gadget drivers test the ``is_otg`` flag, and use it to determine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) whether or not to include an OTG descriptor in each of their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) configurations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) - Gadget drivers may need changes to support the two new OTG protocols,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) exposed in new gadget attributes such as ``b_hnp_enable`` flag. HNP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) support should be reported through a user interface (two LEDs could
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) suffice), and is triggered in some cases when the host suspends the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) peripheral. SRP support can be user-initiated just like remote
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) wakeup, probably by pressing the same button.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) - On the host side, USB device drivers need to be taught to trigger HNP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) at appropriate moments, using ``usb_suspend_device()``. That also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) conserves battery power, which is useful even for non-OTG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) configurations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) - Also on the host side, a driver must support the OTG "Targeted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) Peripheral List". That's just a whitelist, used to reject peripherals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) not supported with a given Linux OTG host. *This whitelist is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) product-specific; each product must modify* ``otg_whitelist.h`` *to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) match its interoperability specification.*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) Non-OTG Linux hosts, like PCs and workstations, normally have some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) solution for adding drivers, so that peripherals that aren't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) recognized can eventually be supported. That approach is unreasonable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) for consumer products that may never have their firmware upgraded,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) and where it's usually unrealistic to expect traditional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) PC/workstation/server kinds of support model to work. For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) it's often impractical to change device firmware once the product has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) been distributed, so driver bugs can't normally be fixed if they're
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) found after shipment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) Additional changes are needed below those hardware-neutral :c:type:`usb_bus`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) and :c:type:`usb_gadget` driver interfaces; those aren't discussed here in any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) detail. Those affect the hardware-specific code for each USB Host or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) Peripheral controller, and how the HCD initializes (since OTG can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) active only on a single port). They also involve what may be called an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) *OTG Controller Driver*, managing the OTG transceiver and the OTG state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) machine logic as well as much of the root hub behavior for the OTG port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) The OTG controller driver needs to activate and deactivate USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) controllers depending on the relevant device role. Some related changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) were needed inside usbcore, so that it can identify OTG-capable devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) and respond appropriately to HNP or SRP protocols.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags