Lines Matching +full:many +full:- +full:to +full:- +full:one
11 This document presents a Linux-USB "Gadget" kernel mode API, for use
14 development project. This is the first such API released on Linux to
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
22 they're easy to port to new hardware.
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
36 - Minimalist, so it's easier to support new device controller hardware.
40 Most Linux developers will not be able to use this API, since they have
42 embedded systems are more likely to have USB peripheral hardware. To
50 The gadget API resembles the host side Linux-USB API in that both use
51 queues of request objects to package I/O buffers, and those requests may
54 bind and unbind drivers to devices. The APIs differ in detail, since the
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.
66 layers inside the kernel to handle USB protocol processing, and may have
68 middle layer to interact with the lowest level (which directly handles
75 to hardware, through registers, fifos, dma, irqs, and the like. The
80 devices only have one upstream port, they only have one of these
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
90 functions, using calls to the controller driver. Because such
93 driver is often configured at compile time to work with endpoints
94 supported by one particular controller. Gadget drivers may be
95 portable to several different controllers, using conditional
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
119 Most gadget drivers have an upper boundary that connects to some
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
148 be an option. Such user mode code will not necessarily be subject to
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*
153 (HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral
155 which is visible to gadget and device driver developers only indirectly.
157 new OTG protocols (HNP and SRP). Roles switch (host to peripheral, or
159 viewed as a more battery-friendly kind of device wakeup protocol.
161 Over time, reusable utilities are evolving to help make some gadget
164 endpoints is now automated, and many drivers now use autoconfiguration
165 to choose hardware endpoints and initialize their descriptors. A
167 USB-IF protocols for HID, networking, storage, or audio classes. Some
168 developers are interested in KDB or KGDB hooks, to let target hardware
169 be remotely debugged. Most such USB protocol code doesn't need to be
170 hardware-specific, any more than network protocols like X11, HTTP, or
171 NFS are. Such gadget-side interface drivers should eventually be
172 combined, to implement composite devices.
179 for a struct usb_gadget. The response to a set_configuration usually
180 involves enabling one or more of the struct usb_ep objects exposed by
181 the gadget, and submitting one or more struct usb_request buffers to
191 are reading. One example of such information is endpoint
192 autoconfiguration. You'll have to read the header file, and use
193 example source code (such as that for "Gadget Zero"), to fully
197 specific to the version of the Linux kernel that's in use. The 2.6
206 such as device-to-device DMA (without temporary storage in a memory
207 buffer) that would be added using hardware-specific APIs.
209 This API allows drivers to use conditional compilation to handle
211 Hardware tends to have arbitrary restrictions, relating to transfer
214 device configuration and management. The API supports limited run-time
216 Many drivers will be able to at least partially autoconfigure
218 autoconfiguration logic that scans the hardware's list of endpoints to
220 conventions), to eliminate some of the most common reasons for
223 Like the Linux-USB host side API, this API exposes the "chunky" nature
224 of USB messages: I/O requests are in terms of one or more "packets", and
225 packet boundaries are visible to drivers. Compared to RS-232 serial
229 per frame, no parity, one stop bit). So for example the controller
230 drivers won't buffer two single byte writes into a single two-byte USB
236 -----------------
238 Gadget drivers make endpoint I/O requests to hardware without needing to
239 know many details of the hardware, but driver setup/configuration code
240 needs to handle some differences. Use the API like this:
248 used by the host to detect a device, even if VBUS power is available.
251 function. That will then bind() to a :c:type:`usb_gadget`, which activates
255 are to accept USB ``power`` and ``set_address`` requests. Other steps are
257 before the host starts to enumerate, steps before step 7 are skipped.
269 endpoint according to its descriptor. It may also involve using
270 ``usb_gadget_vbus_draw`` to let more power be drawn from VBUS, as
276 to interface settings or switching to new configurations, until the
278 requests to each endpoint. It may be suspended and resumed several
280 to step 3 (above).
287 peripheral device to be enumerated, but some drivers will defer
293 controllers or understanding that composite devices might happen to be
298 only the HNP-related differences are particularly visible to driver
300 request, and the option to invoke HNP during some suspend callbacks.
304 -------------------------------------
312 ------------------------
315 drivers to interact with USB peripheral controller drivers.
317 .. kernel-doc:: include/linux/usb/gadget.h
321 ------------------
324 optional utilities are provided to simplify common tasks. These
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
340 framework which makes it easier to reuse and combine functions.
343 which in turn provides one or more struct usb_configuration
344 instances. Each such configuration includes at least one struct
349 .. kernel-doc:: include/linux/usb/composite.h
352 .. kernel-doc:: drivers/usb/gadget/composite.c
356 --------------------------
359 to this framework. Near-term plans include converting all of them,
373 "Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx
379 for several other USB device controllers, with plans to make many of
384 endpoints and device speeds; and it simulates control, bulk, and to some
388 least one person has expressed interest in adapting that approach,
389 hooking it up to a simulator for a microcontroller. Such simulators can
390 help debug subsystems where the runtime hardware is unfriendly to
393 Support for other controllers is expected to be developed and
399 In addition to *Gadget Zero* (used primarily for testing and development
402 There's an ``ethernet`` gadget driver, which implements one of the most
403 useful *Communications Device Class* (CDC) models. One of the standards
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
407 network where the gadget's CPU is one host, which could easily be
408 bridging, routing, or firewalling access to other networks. Since some
411 subset doesn't advertise itself as CDC Ethernet, to avoid creating
417 its main claim to fame is being able to connect directly to recent
419 making it much simpler to network with Windows.
424 Familiar tools like GDB and pthreads can be used to develop and debug
426 many applications for it won't require new kernel mode software. Linux
431 solution for interoperability with systems such as MS-Windows and MacOS.
435 SCSI commands to access the data from the backing store.
440 MS-Windows. One interesting use of that driver is in boot firmware (like
444 Support for other kinds of gadget is expected to be developed and
447 USB On-The-GO (OTG)
455 Systems need specialized hardware support to implement OTG, notably
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
459 ``gadget`` framework. To do that, the system software relies on small
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
465 Such drivers need at most minor changes, and most of the calls added to
466 support OTG can also benefit non-OTG products.
468 - Gadget drivers test the ``is_otg`` flag, and use it to determine
469 whether or not to include an OTG descriptor in each of their
472 - Gadget drivers may need changes to support the two new OTG protocols,
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
487 product-specific; each product must modify* ``otg_whitelist.h`` *to
490 Non-OTG Linux hosts, like PCs and workstations, normally have some
494 and where it's usually unrealistic to expect traditional
495 PC/workstation/server kinds of support model to work. For example,
496 it's often impractical to change device firmware once the product has
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
507 The OTG controller driver needs to activate and deactivate USB
509 were needed inside usbcore, so that it can identify OTG-capable devices
510 and respond appropriately to HNP or SRP protocols.