Contents of /alx-src/trunk/kernel26-alx/linux/Documentation/DocBook/gadget.tmpl
Parent Directory | Revision Log
Revision 628 -
(show annotations)
(download)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 29243 byte(s)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 29243 byte(s)
import linux sources based on 2.6.12-alx-r9: -using linux-2.6.12.6 -using 2.6.12-ck6 patch set -using fbsplash-0.9.2-r3 -using vesafb-tng-0.9-rc7 -using squashfs-2.2 -added cddvd-cmdfilter-drop.patch as ck dropped it -added via-epia-dri (cle266) patch -added zd1211-svn-32 wlan driver (http://zd1211.ath.cx/download/) -added debian patches to zd1211 for wep256 etc
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> |
4 | |
5 | <book id="USB-Gadget-API"> |
6 | <bookinfo> |
7 | <title>USB Gadget API for Linux</title> |
8 | <date>20 August 2004</date> |
9 | <edition>20 August 2004</edition> |
10 | |
11 | <legalnotice> |
12 | <para> |
13 | This documentation is free software; you can redistribute |
14 | it and/or modify it under the terms of the GNU General Public |
15 | License as published by the Free Software Foundation; either |
16 | version 2 of the License, or (at your option) any later |
17 | version. |
18 | </para> |
19 | |
20 | <para> |
21 | This program is distributed in the hope that it will be |
22 | useful, but WITHOUT ANY WARRANTY; without even the implied |
23 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
24 | See the GNU General Public License for more details. |
25 | </para> |
26 | |
27 | <para> |
28 | You should have received a copy of the GNU General Public |
29 | License along with this program; if not, write to the Free |
30 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, |
31 | MA 02111-1307 USA |
32 | </para> |
33 | |
34 | <para> |
35 | For more details see the file COPYING in the source |
36 | distribution of Linux. |
37 | </para> |
38 | </legalnotice> |
39 | <copyright> |
40 | <year>2003-2004</year> |
41 | <holder>David Brownell</holder> |
42 | </copyright> |
43 | |
44 | <author> |
45 | <firstname>David</firstname> |
46 | <surname>Brownell</surname> |
47 | <affiliation> |
48 | <address><email>dbrownell@users.sourceforge.net</email></address> |
49 | </affiliation> |
50 | </author> |
51 | </bookinfo> |
52 | |
53 | <toc></toc> |
54 | |
55 | <chapter><title>Introduction</title> |
56 | |
57 | <para>This document presents a Linux-USB "Gadget" |
58 | kernel mode |
59 | API, for use within peripherals and other USB devices |
60 | that embed Linux. |
61 | It provides an overview of the API structure, |
62 | and shows how that fits into a system development project. |
63 | This is the first such API released on Linux to address |
64 | a number of important problems, including: </para> |
65 | |
66 | <itemizedlist> |
67 | <listitem><para>Supports USB 2.0, for high speed devices which |
68 | can stream data at several dozen megabytes per second. |
69 | </para></listitem> |
70 | <listitem><para>Handles devices with dozens of endpoints just as |
71 | well as ones with just two fixed-function ones. Gadget drivers |
72 | can be written so they're easy to port to new hardware. |
73 | </para></listitem> |
74 | <listitem><para>Flexible enough to expose more complex USB device |
75 | capabilities such as multiple configurations, multiple interfaces, |
76 | composite devices, |
77 | and alternate interface settings. |
78 | </para></listitem> |
79 | <listitem><para>USB "On-The-Go" (OTG) support, in conjunction |
80 | with updates to the Linux-USB host side. |
81 | </para></listitem> |
82 | <listitem><para>Sharing data structures and API models with the |
83 | Linux-USB host side API. This helps the OTG support, and |
84 | looks forward to more-symmetric frameworks (where the same |
85 | I/O model is used by both host and device side drivers). |
86 | </para></listitem> |
87 | <listitem><para>Minimalist, so it's easier to support new device |
88 | controller hardware. I/O processing doesn't imply large |
89 | demands for memory or CPU resources. |
90 | </para></listitem> |
91 | </itemizedlist> |
92 | |
93 | |
94 | <para>Most Linux developers will not be able to use this API, since they |
95 | have USB "host" hardware in a PC, workstation, or server. |
96 | Linux users with embedded systems are more likely to |
97 | have USB peripheral hardware. |
98 | To distinguish drivers running inside such hardware from the |
99 | more familiar Linux "USB device drivers", |
100 | which are host side proxies for the real USB devices, |
101 | a different term is used: |
102 | the drivers inside the peripherals are "USB gadget drivers". |
103 | In USB protocol interactions, the device driver is the master |
104 | (or "client driver") |
105 | and the gadget driver is the slave (or "function driver"). |
106 | </para> |
107 | |
108 | <para>The gadget API resembles the host side Linux-USB API in that both |
109 | use queues of request objects to package I/O buffers, and those requests |
110 | may be submitted or canceled. |
111 | They share common definitions for the standard USB |
112 | <emphasis>Chapter 9</emphasis> messages, structures, and constants. |
113 | Also, both APIs bind and unbind drivers to devices. |
114 | The APIs differ in detail, since the host side's current |
115 | URB framework exposes a number of implementation details |
116 | and assumptions that are inappropriate for a gadget API. |
117 | While the model for control transfers and configuration |
118 | management is necessarily different (one side is a hardware-neutral master, |
119 | the other is a hardware-aware slave), the endpoint I/0 API used here |
120 | should also be usable for an overhead-reduced host side API. |
121 | </para> |
122 | |
123 | </chapter> |
124 | |
125 | <chapter id="structure"><title>Structure of Gadget Drivers</title> |
126 | |
127 | <para>A system running inside a USB peripheral |
128 | normally has at least three layers inside the kernel to handle |
129 | USB protocol processing, and may have additional layers in |
130 | user space code. |
131 | The "gadget" API is used by the middle layer to interact |
132 | with the lowest level (which directly handles hardware). |
133 | </para> |
134 | |
135 | <para>In Linux, from the bottom up, these layers are: |
136 | </para> |
137 | |
138 | <variablelist> |
139 | |
140 | <varlistentry> |
141 | <term><emphasis>USB Controller Driver</emphasis></term> |
142 | |
143 | <listitem> |
144 | <para>This is the lowest software level. |
145 | It is the only layer that talks to hardware, |
146 | through registers, fifos, dma, irqs, and the like. |
147 | The <filename><linux/usb_gadget.h></filename> API abstracts |
148 | the peripheral controller endpoint hardware. |
149 | That hardware is exposed through endpoint objects, which accept |
150 | streams of IN/OUT buffers, and through callbacks that interact |
151 | with gadget drivers. |
152 | Since normal USB devices only have one upstream |
153 | port, they only have one of these drivers. |
154 | The controller driver can support any number of different |
155 | gadget drivers, but only one of them can be used at a time. |
156 | </para> |
157 | |
158 | <para>Examples of such controller hardware include |
159 | the PCI-based NetChip 2280 USB 2.0 high speed controller, |
160 | the SA-11x0 or PXA-25x UDC (found within many PDAs), |
161 | and a variety of other products. |
162 | </para> |
163 | |
164 | </listitem></varlistentry> |
165 | |
166 | <varlistentry> |
167 | <term><emphasis>Gadget Driver</emphasis></term> |
168 | |
169 | <listitem> |
170 | <para>The lower boundary of this driver implements hardware-neutral |
171 | USB functions, using calls to the controller driver. |
172 | Because such hardware varies widely in capabilities and restrictions, |
173 | and is used in embedded environments where space is at a premium, |
174 | the gadget driver is often configured at compile time |
175 | to work with endpoints supported by one particular controller. |
176 | Gadget drivers may be portable to several different controllers, |
177 | using conditional compilation. |
178 | (Recent kernels substantially simplify the work involved in |
179 | supporting new hardware, by <emphasis>autoconfiguring</emphasis> |
180 | endpoints automatically for many bulk-oriented drivers.) |
181 | Gadget driver responsibilities include: |
182 | </para> |
183 | <itemizedlist> |
184 | <listitem><para>handling setup requests (ep0 protocol responses) |
185 | possibly including class-specific functionality |
186 | </para></listitem> |
187 | <listitem><para>returning configuration and string descriptors |
188 | </para></listitem> |
189 | <listitem><para>(re)setting configurations and interface |
190 | altsettings, including enabling and configuring endpoints |
191 | </para></listitem> |
192 | <listitem><para>handling life cycle events, such as managing |
193 | bindings to hardware, |
194 | USB suspend/resume, remote wakeup, |
195 | and disconnection from the USB host. |
196 | </para></listitem> |
197 | <listitem><para>managing IN and OUT transfers on all currently |
198 | enabled endpoints |
199 | </para></listitem> |
200 | </itemizedlist> |
201 | |
202 | <para> |
203 | Such drivers may be modules of proprietary code, although |
204 | that approach is discouraged in the Linux community. |
205 | </para> |
206 | </listitem></varlistentry> |
207 | |
208 | <varlistentry> |
209 | <term><emphasis>Upper Level</emphasis></term> |
210 | |
211 | <listitem> |
212 | <para>Most gadget drivers have an upper boundary that connects |
213 | to some Linux driver or framework in Linux. |
214 | Through that boundary flows the data which the gadget driver |
215 | produces and/or consumes through protocol transfers over USB. |
216 | Examples include: |
217 | </para> |
218 | <itemizedlist> |
219 | <listitem><para>user mode code, using generic (gadgetfs) |
220 | or application specific files in |
221 | <filename>/dev</filename> |
222 | </para></listitem> |
223 | <listitem><para>networking subsystem (for network gadgets, |
224 | like the CDC Ethernet Model gadget driver) |
225 | </para></listitem> |
226 | <listitem><para>data capture drivers, perhaps video4Linux or |
227 | a scanner driver; or test and measurement hardware. |
228 | </para></listitem> |
229 | <listitem><para>input subsystem (for HID gadgets) |
230 | </para></listitem> |
231 | <listitem><para>sound subsystem (for audio gadgets) |
232 | </para></listitem> |
233 | <listitem><para>file system (for PTP gadgets) |
234 | </para></listitem> |
235 | <listitem><para>block i/o subsystem (for usb-storage gadgets) |
236 | </para></listitem> |
237 | <listitem><para>... and more </para></listitem> |
238 | </itemizedlist> |
239 | </listitem></varlistentry> |
240 | |
241 | <varlistentry> |
242 | <term><emphasis>Additional Layers</emphasis></term> |
243 | |
244 | <listitem> |
245 | <para>Other layers may exist. |
246 | These could include kernel layers, such as network protocol stacks, |
247 | as well as user mode applications building on standard POSIX |
248 | system call APIs such as |
249 | <emphasis>open()</emphasis>, <emphasis>close()</emphasis>, |
250 | <emphasis>read()</emphasis> and <emphasis>write()</emphasis>. |
251 | On newer systems, POSIX Async I/O calls may be an option. |
252 | Such user mode code will not necessarily be subject to |
253 | the GNU General Public License (GPL). |
254 | </para> |
255 | </listitem></varlistentry> |
256 | |
257 | |
258 | </variablelist> |
259 | |
260 | <para>OTG-capable systems will also need to include a standard Linux-USB |
261 | host side stack, |
262 | with <emphasis>usbcore</emphasis>, |
263 | one or more <emphasis>Host Controller Drivers</emphasis> (HCDs), |
264 | <emphasis>USB Device Drivers</emphasis> to support |
265 | the OTG "Targeted Peripheral List", |
266 | and so forth. |
267 | There will also be an <emphasis>OTG Controller Driver</emphasis>, |
268 | which is visible to gadget and device driver developers only indirectly. |
269 | That helps the host and device side USB controllers implement the |
270 | two new OTG protocols (HNP and SRP). |
271 | Roles switch (host to peripheral, or vice versa) using HNP |
272 | during USB suspend processing, and SRP can be viewed as a |
273 | more battery-friendly kind of device wakeup protocol. |
274 | </para> |
275 | |
276 | <para>Over time, reusable utilities are evolving to help make some |
277 | gadget driver tasks simpler. |
278 | For example, building configuration descriptors from vectors of |
279 | descriptors for the configurations interfaces and endpoints is |
280 | now automated, and many drivers now use autoconfiguration to |
281 | choose hardware endpoints and initialize their descriptors. |
282 | |
283 | A potential example of particular interest |
284 | is code implementing standard USB-IF protocols for |
285 | HID, networking, storage, or audio classes. |
286 | Some developers are interested in KDB or KGDB hooks, to let |
287 | target hardware be remotely debugged. |
288 | Most such USB protocol code doesn't need to be hardware-specific, |
289 | any more than network protocols like X11, HTTP, or NFS are. |
290 | Such gadget-side interface drivers should eventually be combined, |
291 | to implement composite devices. |
292 | </para> |
293 | |
294 | </chapter> |
295 | |
296 | |
297 | <chapter id="api"><title>Kernel Mode Gadget API</title> |
298 | |
299 | <para>Gadget drivers declare themselves through a |
300 | <emphasis>struct usb_gadget_driver</emphasis>, which is responsible for |
301 | most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>. |
302 | The response to a set_configuration usually involves |
303 | enabling one or more of the <emphasis>struct usb_ep</emphasis> objects |
304 | exposed by the gadget, and submitting one or more |
305 | <emphasis>struct usb_request</emphasis> buffers to transfer data. |
306 | Understand those four data types, and their operations, and |
307 | you will understand how this API works. |
308 | </para> |
309 | |
310 | <note><title>Incomplete Data Type Descriptions</title> |
311 | |
312 | <para>This documentation was prepared using the standard Linux |
313 | kernel <filename>docproc</filename> tool, which turns text |
314 | and in-code comments into SGML DocBook and then into usable |
315 | formats such as HTML or PDF. |
316 | Other than the "Chapter 9" data types, most of the significant |
317 | data types and functions are described here. |
318 | </para> |
319 | |
320 | <para>However, docproc does not understand all the C constructs |
321 | that are used, so some relevant information is likely omitted from |
322 | what you are reading. |
323 | One example of such information is endpoint autoconfiguration. |
324 | You'll have to read the header file, and use example source |
325 | code (such as that for "Gadget Zero"), to fully understand the API. |
326 | </para> |
327 | |
328 | <para>The part of the API implementing some basic |
329 | driver capabilities is specific to the version of the |
330 | Linux kernel that's in use. |
331 | The 2.6 kernel includes a <emphasis>driver model</emphasis> |
332 | framework that has no analogue on earlier kernels; |
333 | so those parts of the gadget API are not fully portable. |
334 | (They are implemented on 2.4 kernels, but in a different way.) |
335 | The driver model state is another part of this API that is |
336 | ignored by the kerneldoc tools. |
337 | </para> |
338 | </note> |
339 | |
340 | <para>The core API does not expose |
341 | every possible hardware feature, only the most widely available ones. |
342 | There are significant hardware features, such as device-to-device DMA |
343 | (without temporary storage in a memory buffer) |
344 | that would be added using hardware-specific APIs. |
345 | </para> |
346 | |
347 | <para>This API allows drivers to use conditional compilation to handle |
348 | endpoint capabilities of different hardware, but doesn't require that. |
349 | Hardware tends to have arbitrary restrictions, relating to |
350 | transfer types, addressing, packet sizes, buffering, and availability. |
351 | As a rule, such differences only matter for "endpoint zero" logic |
352 | that handles device configuration and management. |
353 | The API supports limited run-time |
354 | detection of capabilities, through naming conventions for endpoints. |
355 | Many drivers will be able to at least partially autoconfigure |
356 | themselves. |
357 | In particular, driver init sections will often have endpoint |
358 | autoconfiguration logic that scans the hardware's list of endpoints |
359 | to find ones matching the driver requirements |
360 | (relying on those conventions), to eliminate some of the most |
361 | common reasons for conditional compilation. |
362 | </para> |
363 | |
364 | <para>Like the Linux-USB host side API, this API exposes |
365 | the "chunky" nature of USB messages: I/O requests are in terms |
366 | of one or more "packets", and packet boundaries are visible to drivers. |
367 | Compared to RS-232 serial protocols, USB resembles |
368 | synchronous protocols like HDLC |
369 | (N bytes per frame, multipoint addressing, host as the primary |
370 | station and devices as secondary stations) |
371 | more than asynchronous ones |
372 | (tty style: 8 data bits per frame, no parity, one stop bit). |
373 | So for example the controller drivers won't buffer |
374 | two single byte writes into a single two-byte USB IN packet, |
375 | although gadget drivers may do so when they implement |
376 | protocols where packet boundaries (and "short packets") |
377 | are not significant. |
378 | </para> |
379 | |
380 | <sect1 id="lifecycle"><title>Driver Life Cycle</title> |
381 | |
382 | <para>Gadget drivers make endpoint I/O requests to hardware without |
383 | needing to know many details of the hardware, but driver |
384 | setup/configuration code needs to handle some differences. |
385 | Use the API like this: |
386 | </para> |
387 | |
388 | <orderedlist numeration='arabic'> |
389 | |
390 | <listitem><para>Register a driver for the particular device side |
391 | usb controller hardware, |
392 | such as the net2280 on PCI (USB 2.0), |
393 | sa11x0 or pxa25x as found in Linux PDAs, |
394 | and so on. |
395 | At this point the device is logically in the USB ch9 initial state |
396 | ("attached"), drawing no power and not usable |
397 | (since it does not yet support enumeration). |
398 | Any host should not see the device, since it's not |
399 | activated the data line pullup used by the host to |
400 | detect a device, even if VBUS power is available. |
401 | </para></listitem> |
402 | |
403 | <listitem><para>Register a gadget driver that implements some higher level |
404 | device function. That will then bind() to a usb_gadget, which |
405 | activates the data line pullup sometime after detecting VBUS. |
406 | </para></listitem> |
407 | |
408 | <listitem><para>The hardware driver can now start enumerating. |
409 | The steps it handles are to accept USB power and set_address requests. |
410 | Other steps are handled by the gadget driver. |
411 | If the gadget driver module is unloaded before the host starts to |
412 | enumerate, steps before step 7 are skipped. |
413 | </para></listitem> |
414 | |
415 | <listitem><para>The gadget driver's setup() call returns usb descriptors, |
416 | based both on what the bus interface hardware provides and on the |
417 | functionality being implemented. |
418 | That can involve alternate settings or configurations, |
419 | unless the hardware prevents such operation. |
420 | For OTG devices, each configuration descriptor includes |
421 | an OTG descriptor. |
422 | </para></listitem> |
423 | |
424 | <listitem><para>The gadget driver handles the last step of enumeration, |
425 | when the USB host issues a set_configuration call. |
426 | It enables all endpoints used in that configuration, |
427 | with all interfaces in their default settings. |
428 | That involves using a list of the hardware's endpoints, enabling each |
429 | endpoint according to its descriptor. |
430 | It may also involve using <function>usb_gadget_vbus_draw</function> |
431 | to let more power be drawn from VBUS, as allowed by that configuration. |
432 | For OTG devices, setting a configuration may also involve reporting |
433 | HNP capabilities through a user interface. |
434 | </para></listitem> |
435 | |
436 | <listitem><para>Do real work and perform data transfers, possibly involving |
437 | changes to interface settings or switching to new configurations, until the |
438 | device is disconnect()ed from the host. |
439 | Queue any number of transfer requests to each endpoint. |
440 | It may be suspended and resumed several times before being disconnected. |
441 | On disconnect, the drivers go back to step 3 (above). |
442 | </para></listitem> |
443 | |
444 | <listitem><para>When the gadget driver module is being unloaded, |
445 | the driver unbind() callback is issued. That lets the controller |
446 | driver be unloaded. |
447 | </para></listitem> |
448 | |
449 | </orderedlist> |
450 | |
451 | <para>Drivers will normally be arranged so that just loading the |
452 | gadget driver module (or statically linking it into a Linux kernel) |
453 | allows the peripheral device to be enumerated, but some drivers |
454 | will defer enumeration until some higher level component (like |
455 | a user mode daemon) enables it. |
456 | Note that at this lowest level there are no policies about how |
457 | ep0 configuration logic is implemented, |
458 | except that it should obey USB specifications. |
459 | Such issues are in the domain of gadget drivers, |
460 | including knowing about implementation constraints |
461 | imposed by some USB controllers |
462 | or understanding that composite devices might happen to |
463 | be built by integrating reusable components. |
464 | </para> |
465 | |
466 | <para>Note that the lifecycle above can be slightly different |
467 | for OTG devices. |
468 | Other than providing an additional OTG descriptor in each |
469 | configuration, only the HNP-related differences are particularly |
470 | visible to driver code. |
471 | They involve reporting requirements during the SET_CONFIGURATION |
472 | request, and the option to invoke HNP during some suspend callbacks. |
473 | Also, SRP changes the semantics of |
474 | <function>usb_gadget_wakeup</function> |
475 | slightly. |
476 | </para> |
477 | |
478 | </sect1> |
479 | |
480 | <sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title> |
481 | |
482 | <para>Gadget drivers |
483 | rely on common USB structures and constants |
484 | defined in the |
485 | <filename><linux/usb_ch9.h></filename> |
486 | header file, which is standard in Linux 2.6 kernels. |
487 | These are the same types and constants used by host |
488 | side drivers (and usbcore). |
489 | </para> |
490 | |
491 | !Iinclude/linux/usb_ch9.h |
492 | </sect1> |
493 | |
494 | <sect1 id="core"><title>Core Objects and Methods</title> |
495 | |
496 | <para>These are declared in |
497 | <filename><linux/usb_gadget.h></filename>, |
498 | and are used by gadget drivers to interact with |
499 | USB peripheral controller drivers. |
500 | </para> |
501 | |
502 | <!-- yeech, this is ugly in nsgmls PDF output. |
503 | |
504 | the PDF bookmark and refentry output nesting is wrong, |
505 | and the member/argument documentation indents ugly. |
506 | |
507 | plus something (docproc?) adds whitespace before the |
508 | descriptive paragraph text, so it can't line up right |
509 | unless the explanations are trivial. |
510 | --> |
511 | |
512 | !Iinclude/linux/usb_gadget.h |
513 | </sect1> |
514 | |
515 | <sect1 id="utils"><title>Optional Utilities</title> |
516 | |
517 | <para>The core API is sufficient for writing a USB Gadget Driver, |
518 | but some optional utilities are provided to simplify common tasks. |
519 | These utilities include endpoint autoconfiguration. |
520 | </para> |
521 | |
522 | !Edrivers/usb/gadget/usbstring.c |
523 | !Edrivers/usb/gadget/config.c |
524 | <!-- !Edrivers/usb/gadget/epautoconf.c --> |
525 | </sect1> |
526 | |
527 | </chapter> |
528 | |
529 | <chapter id="controllers"><title>Peripheral Controller Drivers</title> |
530 | |
531 | <para>The first hardware supporting this API was the NetChip 2280 |
532 | controller, which supports USB 2.0 high speed and is based on PCI. |
533 | This is the <filename>net2280</filename> driver module. |
534 | The driver supports Linux kernel versions 2.4 and 2.6; |
535 | contact NetChip Technologies for development boards and product |
536 | information. |
537 | </para> |
538 | |
539 | <para>Other hardware working in the "gadget" framework includes: |
540 | Intel's PXA 25x and IXP42x series processors |
541 | (<filename>pxa2xx_udc</filename>), |
542 | Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>), |
543 | Renesas SH7705/7727 (<filename>sh_udc</filename>), |
544 | MediaQ 11xx (<filename>mq11xx_udc</filename>), |
545 | Hynix HMS30C7202 (<filename>h7202_udc</filename>), |
546 | National 9303/4 (<filename>n9604_udc</filename>), |
547 | Texas Instruments OMAP (<filename>omap_udc</filename>), |
548 | Sharp LH7A40x (<filename>lh7a40x_udc</filename>), |
549 | and more. |
550 | Most of those are full speed controllers. |
551 | </para> |
552 | |
553 | <para>At this writing, there are people at work on drivers in |
554 | this framework for several other USB device controllers, |
555 | with plans to make many of them be widely available. |
556 | </para> |
557 | |
558 | <!-- !Edrivers/usb/gadget/net2280.c --> |
559 | |
560 | <para>A partial USB simulator, |
561 | the <filename>dummy_hcd</filename> driver, is available. |
562 | It can act like a net2280, a pxa25x, or an sa11x0 in terms |
563 | of available endpoints and device speeds; and it simulates |
564 | control, bulk, and to some extent interrupt transfers. |
565 | That lets you develop some parts of a gadget driver on a normal PC, |
566 | without any special hardware, and perhaps with the assistance |
567 | of tools such as GDB running with User Mode Linux. |
568 | At least one person has expressed interest in adapting that |
569 | approach, hooking it up to a simulator for a microcontroller. |
570 | Such simulators can help debug subsystems where the runtime hardware |
571 | is unfriendly to software development, or is not yet available. |
572 | </para> |
573 | |
574 | <para>Support for other controllers is expected to be developed |
575 | and contributed |
576 | over time, as this driver framework evolves. |
577 | </para> |
578 | |
579 | </chapter> |
580 | |
581 | <chapter id="gadget"><title>Gadget Drivers</title> |
582 | |
583 | <para>In addition to <emphasis>Gadget Zero</emphasis> |
584 | (used primarily for testing and development with drivers |
585 | for usb controller hardware), other gadget drivers exist. |
586 | </para> |
587 | |
588 | <para>There's an <emphasis>ethernet</emphasis> gadget |
589 | driver, which implements one of the most useful |
590 | <emphasis>Communications Device Class</emphasis> (CDC) models. |
591 | One of the standards for cable modem interoperability even |
592 | specifies the use of this ethernet model as one of two |
593 | mandatory options. |
594 | Gadgets using this code look to a USB host as if they're |
595 | an Ethernet adapter. |
596 | It provides access to a network where the gadget's CPU is one host, |
597 | which could easily be bridging, routing, or firewalling |
598 | access to other networks. |
599 | Since some hardware can't fully implement the CDC Ethernet |
600 | requirements, this driver also implements a "good parts only" |
601 | subset of CDC Ethernet. |
602 | (That subset doesn't advertise itself as CDC Ethernet, |
603 | to avoid creating problems.) |
604 | </para> |
605 | |
606 | <para>Support for Microsoft's <emphasis>RNDIS</emphasis> |
607 | protocol has been contributed by Pengutronix and Auerswald GmbH. |
608 | This is like CDC Ethernet, but it runs on more slightly USB hardware |
609 | (but less than the CDC subset). |
610 | However, its main claim to fame is being able to connect directly to |
611 | recent versions of Windows, using drivers that Microsoft bundles |
612 | and supports, making it much simpler to network with Windows. |
613 | </para> |
614 | |
615 | <para>There is also support for user mode gadget drivers, |
616 | using <emphasis>gadgetfs</emphasis>. |
617 | This provides a <emphasis>User Mode API</emphasis> that presents |
618 | each endpoint as a single file descriptor. I/O is done using |
619 | normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls. |
620 | Familiar tools like GDB and pthreads can be used to |
621 | develop and debug user mode drivers, so that once a robust |
622 | controller driver is available many applications for it |
623 | won't require new kernel mode software. |
624 | Linux 2.6 <emphasis>Async I/O (AIO)</emphasis> |
625 | support is available, so that user mode software |
626 | can stream data with only slightly more overhead |
627 | than a kernel driver. |
628 | </para> |
629 | |
630 | <para>There's a USB Mass Storage class driver, which provides |
631 | a different solution for interoperability with systems such |
632 | as MS-Windows and MacOS. |
633 | That <emphasis>File-backed Storage</emphasis> driver uses a |
634 | file or block device as backing store for a drive, |
635 | like the <filename>loop</filename> driver. |
636 | The USB host uses the BBB, CB, or CBI versions of the mass |
637 | storage class specification, using transparent SCSI commands |
638 | to access the data from the backing store. |
639 | </para> |
640 | |
641 | <para>There's a "serial line" driver, useful for TTY style |
642 | operation over USB. |
643 | The latest version of that driver supports CDC ACM style |
644 | operation, like a USB modem, and so on most hardware it can |
645 | interoperate easily with MS-Windows. |
646 | One interesting use of that driver is in boot firmware (like a BIOS), |
647 | which can sometimes use that model with very small systems without |
648 | real serial lines. |
649 | </para> |
650 | |
651 | <para>Support for other kinds of gadget is expected to |
652 | be developed and contributed |
653 | over time, as this driver framework evolves. |
654 | </para> |
655 | |
656 | </chapter> |
657 | |
658 | <chapter id="otg"><title>USB On-The-GO (OTG)</title> |
659 | |
660 | <para>USB OTG support on Linux 2.6 was initially developed |
661 | by Texas Instruments for |
662 | <ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx |
663 | series processors. |
664 | Other OTG systems should work in similar ways, but the |
665 | hardware level details could be very different. |
666 | </para> |
667 | |
668 | <para>Systems need specialized hardware support to implement OTG, |
669 | notably including a special <emphasis>Mini-AB</emphasis> jack |
670 | and associated transciever to support <emphasis>Dual-Role</emphasis> |
671 | operation: |
672 | they can act either as a host, using the standard |
673 | Linux-USB host side driver stack, |
674 | or as a peripheral, using this "gadget" framework. |
675 | To do that, the system software relies on small additions |
676 | to those programming interfaces, |
677 | and on a new internal component (here called an "OTG Controller") |
678 | affecting which driver stack connects to the OTG port. |
679 | In each role, the system can re-use the existing pool of |
680 | hardware-neutral drivers, layered on top of the controller |
681 | driver interfaces (<emphasis>usb_bus</emphasis> or |
682 | <emphasis>usb_gadget</emphasis>). |
683 | Such drivers need at most minor changes, and most of the calls |
684 | added to support OTG can also benefit non-OTG products. |
685 | </para> |
686 | |
687 | <itemizedlist> |
688 | <listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis> |
689 | flag, and use it to determine whether or not to include |
690 | an OTG descriptor in each of their configurations. |
691 | </para></listitem> |
692 | <listitem><para>Gadget drivers may need changes to support the |
693 | two new OTG protocols, exposed in new gadget attributes |
694 | such as <emphasis>b_hnp_enable</emphasis> flag. |
695 | HNP support should be reported through a user interface |
696 | (two LEDs could suffice), and is triggered in some cases |
697 | when the host suspends the peripheral. |
698 | SRP support can be user-initiated just like remote wakeup, |
699 | probably by pressing the same button. |
700 | </para></listitem> |
701 | <listitem><para>On the host side, USB device drivers need |
702 | to be taught to trigger HNP at appropriate moments, using |
703 | <function>usb_suspend_device()</function>. |
704 | That also conserves battery power, which is useful even |
705 | for non-OTG configurations. |
706 | </para></listitem> |
707 | <listitem><para>Also on the host side, a driver must support the |
708 | OTG "Targeted Peripheral List". That's just a whitelist, |
709 | used to reject peripherals not supported with a given |
710 | Linux OTG host. |
711 | <emphasis>This whitelist is product-specific; |
712 | each product must modify <filename>otg_whitelist.h</filename> |
713 | to match its interoperability specification. |
714 | </emphasis> |
715 | </para> |
716 | <para>Non-OTG Linux hosts, like PCs and workstations, |
717 | normally have some solution for adding drivers, so that |
718 | peripherals that aren't recognized can eventually be supported. |
719 | That approach is unreasonable for consumer products that may |
720 | never have their firmware upgraded, and where it's usually |
721 | unrealistic to expect traditional PC/workstation/server kinds |
722 | of support model to work. |
723 | For example, it's often impractical to change device firmware |
724 | once the product has been distributed, so driver bugs can't |
725 | normally be fixed if they're found after shipment. |
726 | </para></listitem> |
727 | </itemizedlist> |
728 | |
729 | <para> |
730 | Additional changes are needed below those hardware-neutral |
731 | <emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis> |
732 | driver interfaces; those aren't discussed here in any detail. |
733 | Those affect the hardware-specific code for each USB Host or Peripheral |
734 | controller, and how the HCD initializes (since OTG can be active only |
735 | on a single port). |
736 | They also involve what may be called an <emphasis>OTG Controller |
737 | Driver</emphasis>, managing the OTG transceiver and the OTG state |
738 | machine logic as well as much of the root hub behavior for the |
739 | OTG port. |
740 | The OTG controller driver needs to activate and deactivate USB |
741 | controllers depending on the relevant device role. |
742 | Some related changes were needed inside usbcore, so that it |
743 | can identify OTG-capable devices and respond appropriately |
744 | to HNP or SRP protocols. |
745 | </para> |
746 | |
747 | </chapter> |
748 | |
749 | </book> |
750 | <!-- |
751 | vim:syntax=sgml:sw=4 |
752 | --> |