Lines Matching +full:a +full:- +full:side
11 This document presents a Linux-USB "Gadget" kernel mode API, for use
13 an overview of the API structure, and shows how that fits into a system
15 address a number of important problems, including:
17 - Supports USB 2.0, for high speed devices which can stream data at
20 - Handles devices with dozens of endpoints just as well as ones with
21 just two fixed-function ones. Gadget drivers can be written so
24 - Flexible enough to expose more complex USB device capabilities such
28 - USB "On-The-Go" (OTG) support, in conjunction with updates to the
29 Linux-USB host side.
31 - Sharing data structures and API models with the Linux-USB host side
32 API. This helps the OTG support, and looks forward to more-symmetric
34 side drivers).
36 - Minimalist, so it's easier to support new device controller hardware.
41 USB ``host`` hardware in a PC, workstation, or server. Linux users with
44 Linux "USB device drivers", which are host side proxies for the real USB
45 devices, a different term is used: the drivers inside the peripherals
50 The gadget API resembles the host side Linux-USB API in that both use
55 host side's current URB framework exposes a number of implementation
56 details and assumptions that are inappropriate for a gadget API. While
58 necessarily different (one side is a hardware-neutral master, the other
59 is a hardware-aware slave), the endpoint I/0 API used here should also
60 be usable for an overhead-reduced host side API.
65 A system running inside a USB peripheral normally has at least three
82 gadget drivers, but only one of them can be used at a time.
84 Examples of such controller hardware include the PCI-based NetChip
85 2280 USB 2.0 high speed controller, the SA-11x0 or PXA-25x UDC
86 (found within many PDAs), and a variety of other products.
89 The lower boundary of this driver implements hardware-neutral USB
92 in embedded environments where space is at a premium, the gadget
98 automatically for many bulk-oriented drivers.) Gadget driver
101 - handling setup requests (ep0 protocol responses) possibly
102 including class-specific functionality
104 - returning configuration and string descriptors
106 - (re)setting configurations and interface altsettings, including
109 - handling life cycle events, such as managing bindings to
113 - managing IN and OUT transfers on all currently enabled endpoints
124 - user mode code, using generic (gadgetfs) or application specific
127 - networking subsystem (for network gadgets, like the CDC Ethernet
130 - data capture drivers, perhaps video4Linux or a scanner driver; or
133 - input subsystem (for HID gadgets)
135 - sound subsystem (for audio gadgets)
137 - file system (for PTP gadgets)
139 - block i/o subsystem (for usb-storage gadgets)
141 - ... and more
151 OTG-capable systems will also need to include a standard Linux-USB host
152 side stack, with ``usbcore``, one or more *Host Controller Drivers*
156 That helps the host and device side USB controllers implement the two
159 viewed as a more battery-friendly kind of device wakeup protocol.
165 to choose hardware endpoints and initialize their descriptors. A
167 USB-IF protocols for HID, networking, storage, or audio classes. Some
170 hardware-specific, any more than network protocols like X11, HTTP, or
171 NFS are. Such gadget-side interface drivers should eventually be
177 Gadget drivers declare themselves through a struct
179 for a struct usb_gadget. The response to a set_configuration usually
198 and upper kernel versions include a *driver model* framework that has
200 not fully portable. (They are implemented on 2.4 kernels, but in a
206 such as device-to-device DMA (without temporary storage in a memory
207 buffer) that would be added using hardware-specific APIs.
212 types, addressing, packet sizes, buffering, and availability. As a rule,
214 device configuration and management. The API supports limited run-time
223 Like the Linux-USB host side API, this API exposes the "chunky" nature
225 packet boundaries are visible to drivers. Compared to RS-232 serial
230 drivers won't buffer two single byte writes into a single two-byte USB
236 -----------------
242 1. Register a driver for the particular device side usb controller
248 used by the host to detect a device, even if VBUS power is available.
250 2. Register a gadget driver that implements some higher level device
251 function. That will then bind() to a :c:type:`usb_gadget`, which activates
266 host issues a ``set_configuration`` call. It enables all endpoints used
268 That involves using a list of the hardware's endpoints, enabling each
271 allowed by that configuration. For OTG devices, setting a
272 configuration may also involve reporting HNP capabilities through a
286 module (or statically linking it into a Linux kernel) allows the
288 enumeration until some higher level component (like a user mode daemon)
298 only the HNP-related differences are particularly visible to driver
304 -------------------------------------
308 Linux 2.6+ kernels. These are the same types and constants used by host side
312 ------------------------
317 .. kernel-doc:: include/linux/usb/gadget.h
321 ------------------
323 The core API is sufficient for writing a USB Gadget Driver, but some
327 .. kernel-doc:: drivers/usb/gadget/usbstring.c
330 .. kernel-doc:: drivers/usb/gadget/config.c
334 --------------------------
337 (with more than one function in a given configuration), and also
338 multi-configuration devices (also more than one function, but not
339 necessarily sharing a given configuration). There is however an optional
342 Devices using this framework provide a struct usb_composite_driver,
345 :c:type:`usb_function`, which packages a user visible role such as "network
349 .. kernel-doc:: include/linux/usb/composite.h
352 .. kernel-doc:: drivers/usb/gadget/composite.c
356 --------------------------
358 At this writing, a few of the current gadget drivers have been converted
359 to this framework. Near-term plans include converting all of them,
373 "Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx
382 A partial USB simulator, the ``dummy_hcd`` driver, is available. It can
383 act like a net2280, a pxa25x, or an sa11x0 in terms of available
385 extent interrupt transfers. That lets you develop some parts of a gadget
386 driver on a normal PC, without any special hardware, and perhaps with
389 hooking it up to a simulator for a microcontroller. Such simulators can
405 model as one of two mandatory options. Gadgets using this code look to a
406 USB host as if they're an Ethernet adapter. It provides access to a
410 driver also implements a "good parts only" subset of CDC Ethernet. (That
422 This provides a *User Mode API* that presents each endpoint as a single
425 user mode drivers, so that once a robust controller driver is available
428 can stream data with only slightly more overhead than a kernel driver.
430 There's a USB Mass Storage class driver, which provides a different
431 solution for interoperability with systems such as MS-Windows and MacOS.
432 That *Mass Storage* driver uses a file or block device as backing store
433 for a drive, like the ``loop`` driver. The USB host uses the BBB, CB, or
437 There's a "serial line" driver, useful for TTY style operation over USB.
439 a USB modem, and so on most hardware it can interoperate easily with
440 MS-Windows. One interesting use of that driver is in boot firmware (like
441 a BIOS), which can sometimes use that model with very small systems
447 USB On-The-GO (OTG)
456 including a special *Mini-AB* jack and associated transceiver to support
457 *Dual-Role* operation: they can act either as a host, using the standard
458 Linux-USB host side driver stack, or as a peripheral, using this
460 additions to those programming interfaces, and on a new internal
462 connects to the OTG port. In each role, the system can re-use the
463 existing pool of hardware-neutral drivers, layered on top of the
466 support OTG can also benefit non-OTG products.
468 - Gadget drivers test the ``is_otg`` flag, and use it to determine
472 - Gadget drivers may need changes to support the two new OTG protocols,
474 support should be reported through a user interface (two LEDs could
476 peripheral. SRP support can be user-initiated just like remote
479 - On the host side, USB device drivers need to be taught to trigger HNP
481 conserves battery power, which is useful even for non-OTG
484 - Also on the host side, a driver must support the OTG "Targeted
485 Peripheral List". That's just a whitelist, used to reject peripherals
486 not supported with a given Linux OTG host. *This whitelist is
487 product-specific; each product must modify* ``otg_whitelist.h`` *to
490 Non-OTG Linux hosts, like PCs and workstations, normally have some
500 Additional changes are needed below those hardware-neutral :c:type:`usb_bus`
502 detail. Those affect the hardware-specific code for each USB Host or
504 active only on a single port). They also involve what may be called an
509 were needed inside usbcore, so that it can identify OTG-capable devices