753 lines
29 KiB
Cheetah
753 lines
29 KiB
Cheetah
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||
|
|
|
||
|
|
<book id="USB-Gadget-API">
|
||
|
|
<bookinfo>
|
||
|
|
<title>USB Gadget API for Linux</title>
|
||
|
|
<date>20 August 2004</date>
|
||
|
|
<edition>20 August 2004</edition>
|
||
|
|
|
||
|
|
<legalnotice>
|
||
|
|
<para>
|
||
|
|
This documentation is free software; you can redistribute
|
||
|
|
it and/or modify it under the terms of the GNU General Public
|
||
|
|
License as published by the Free Software Foundation; either
|
||
|
|
version 2 of the License, or (at your option) any later
|
||
|
|
version.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This program is distributed in the hope that it will be
|
||
|
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||
|
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||
|
|
See the GNU General Public License for more details.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
You should have received a copy of the GNU General Public
|
||
|
|
License along with this program; if not, write to the Free
|
||
|
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||
|
|
MA 02111-1307 USA
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
For more details see the file COPYING in the source
|
||
|
|
distribution of Linux.
|
||
|
|
</para>
|
||
|
|
</legalnotice>
|
||
|
|
<copyright>
|
||
|
|
<year>2003-2004</year>
|
||
|
|
<holder>David Brownell</holder>
|
||
|
|
</copyright>
|
||
|
|
|
||
|
|
<author>
|
||
|
|
<firstname>David</firstname>
|
||
|
|
<surname>Brownell</surname>
|
||
|
|
<affiliation>
|
||
|
|
<address><email>dbrownell@users.sourceforge.net</email></address>
|
||
|
|
</affiliation>
|
||
|
|
</author>
|
||
|
|
</bookinfo>
|
||
|
|
|
||
|
|
<toc></toc>
|
||
|
|
|
||
|
|
<chapter><title>Introduction</title>
|
||
|
|
|
||
|
|
<para>This document presents a Linux-USB "Gadget"
|
||
|
|
kernel mode
|
||
|
|
API, for use within peripherals and other USB devices
|
||
|
|
that embed Linux.
|
||
|
|
It provides an overview of the API structure,
|
||
|
|
and shows how that fits into a system development project.
|
||
|
|
This is the first such API released on Linux to address
|
||
|
|
a number of important problems, including: </para>
|
||
|
|
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>Supports USB 2.0, for high speed devices which
|
||
|
|
can stream data at several dozen megabytes per second.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>Handles devices with dozens of endpoints just as
|
||
|
|
well as ones with just two fixed-function ones. Gadget drivers
|
||
|
|
can be written so they're easy to port to new hardware.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>Flexible enough to expose more complex USB device
|
||
|
|
capabilities such as multiple configurations, multiple interfaces,
|
||
|
|
composite devices,
|
||
|
|
and alternate interface settings.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>USB "On-The-Go" (OTG) support, in conjunction
|
||
|
|
with updates to the Linux-USB host side.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>Sharing data structures and API models with the
|
||
|
|
Linux-USB host side API. This helps the OTG support, and
|
||
|
|
looks forward to more-symmetric frameworks (where the same
|
||
|
|
I/O model is used by both host and device side drivers).
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>Minimalist, so it's easier to support new device
|
||
|
|
controller hardware. I/O processing doesn't imply large
|
||
|
|
demands for memory or CPU resources.
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
|
||
|
|
|
||
|
|
<para>Most Linux developers will not be able to use this API, since they
|
||
|
|
have USB "host" hardware in a PC, workstation, or server.
|
||
|
|
Linux users with embedded systems are more likely to
|
||
|
|
have USB peripheral hardware.
|
||
|
|
To distinguish drivers running inside such hardware from the
|
||
|
|
more familiar Linux "USB device drivers",
|
||
|
|
which are host side proxies for the real USB devices,
|
||
|
|
a different term is used:
|
||
|
|
the drivers inside the peripherals are "USB gadget drivers".
|
||
|
|
In USB protocol interactions, the device driver is the master
|
||
|
|
(or "client driver")
|
||
|
|
and the gadget driver is the slave (or "function driver").
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>The gadget API resembles the host side Linux-USB API in that both
|
||
|
|
use queues of request objects to package I/O buffers, and those requests
|
||
|
|
may be submitted or canceled.
|
||
|
|
They share common definitions for the standard USB
|
||
|
|
<emphasis>Chapter 9</emphasis> messages, structures, and constants.
|
||
|
|
Also, both APIs bind and unbind drivers to devices.
|
||
|
|
The APIs differ in detail, since the host side's current
|
||
|
|
URB framework exposes a number of implementation details
|
||
|
|
and assumptions that are inappropriate for a gadget API.
|
||
|
|
While the model for control transfers and configuration
|
||
|
|
management is necessarily different (one side is a hardware-neutral master,
|
||
|
|
the other is a hardware-aware slave), the endpoint I/0 API used here
|
||
|
|
should also be usable for an overhead-reduced host side API.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
</chapter>
|
||
|
|
|
||
|
|
<chapter id="structure"><title>Structure of Gadget Drivers</title>
|
||
|
|
|
||
|
|
<para>A system running inside a USB peripheral
|
||
|
|
normally has at least three layers inside the kernel to handle
|
||
|
|
USB protocol processing, and may have additional layers in
|
||
|
|
user space code.
|
||
|
|
The "gadget" API is used by the middle layer to interact
|
||
|
|
with the lowest level (which directly handles hardware).
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>In Linux, from the bottom up, these layers are:
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<variablelist>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><emphasis>USB Controller Driver</emphasis></term>
|
||
|
|
|
||
|
|
<listitem>
|
||
|
|
<para>This is the lowest software level.
|
||
|
|
It is the only layer that talks to hardware,
|
||
|
|
through registers, fifos, dma, irqs, and the like.
|
||
|
|
The <filename><linux/usb_gadget.h></filename> API abstracts
|
||
|
|
the peripheral controller endpoint hardware.
|
||
|
|
That hardware is exposed through endpoint objects, which accept
|
||
|
|
streams of IN/OUT buffers, and through callbacks that interact
|
||
|
|
with gadget drivers.
|
||
|
|
Since normal USB devices only have one upstream
|
||
|
|
port, they only have one of these drivers.
|
||
|
|
The controller driver can support any number of different
|
||
|
|
gadget drivers, but only one of them can be used at a time.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Examples of such controller hardware include
|
||
|
|
the PCI-based NetChip 2280 USB 2.0 high speed controller,
|
||
|
|
the SA-11x0 or PXA-25x UDC (found within many PDAs),
|
||
|
|
and a variety of other products.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
</listitem></varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><emphasis>Gadget Driver</emphasis></term>
|
||
|
|
|
||
|
|
<listitem>
|
||
|
|
<para>The lower boundary of this driver implements hardware-neutral
|
||
|
|
USB functions, using calls to the controller driver.
|
||
|
|
Because such hardware varies widely in capabilities and restrictions,
|
||
|
|
and is used in embedded environments where space is at a premium,
|
||
|
|
the gadget driver is often configured at compile time
|
||
|
|
to work with endpoints supported by one particular controller.
|
||
|
|
Gadget drivers may be portable to several different controllers,
|
||
|
|
using conditional compilation.
|
||
|
|
(Recent kernels substantially simplify the work involved in
|
||
|
|
supporting new hardware, by <emphasis>autoconfiguring</emphasis>
|
||
|
|
endpoints automatically for many bulk-oriented drivers.)
|
||
|
|
Gadget driver responsibilities include:
|
||
|
|
</para>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>handling setup requests (ep0 protocol responses)
|
||
|
|
possibly including class-specific functionality
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>returning configuration and string descriptors
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>(re)setting configurations and interface
|
||
|
|
altsettings, including enabling and configuring endpoints
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>handling life cycle events, such as managing
|
||
|
|
bindings to hardware,
|
||
|
|
USB suspend/resume, remote wakeup,
|
||
|
|
and disconnection from the USB host.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>managing IN and OUT transfers on all currently
|
||
|
|
enabled endpoints
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Such drivers may be modules of proprietary code, although
|
||
|
|
that approach is discouraged in the Linux community.
|
||
|
|
</para>
|
||
|
|
</listitem></varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><emphasis>Upper Level</emphasis></term>
|
||
|
|
|
||
|
|
<listitem>
|
||
|
|
<para>Most gadget drivers have an upper boundary that connects
|
||
|
|
to some Linux driver or framework in Linux.
|
||
|
|
Through that boundary flows the data which the gadget driver
|
||
|
|
produces and/or consumes through protocol transfers over USB.
|
||
|
|
Examples include:
|
||
|
|
</para>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>user mode code, using generic (gadgetfs)
|
||
|
|
or application specific files in
|
||
|
|
<filename>/dev</filename>
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>networking subsystem (for network gadgets,
|
||
|
|
like the CDC Ethernet Model gadget driver)
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>data capture drivers, perhaps video4Linux or
|
||
|
|
a scanner driver; or test and measurement hardware.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>input subsystem (for HID gadgets)
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>sound subsystem (for audio gadgets)
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>file system (for PTP gadgets)
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>block i/o subsystem (for usb-storage gadgets)
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>... and more </para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</listitem></varlistentry>
|
||
|
|
|
||
|
|
<varlistentry>
|
||
|
|
<term><emphasis>Additional Layers</emphasis></term>
|
||
|
|
|
||
|
|
<listitem>
|
||
|
|
<para>Other layers may exist.
|
||
|
|
These could include kernel layers, such as network protocol stacks,
|
||
|
|
as well as user mode applications building on standard POSIX
|
||
|
|
system call APIs such as
|
||
|
|
<emphasis>open()</emphasis>, <emphasis>close()</emphasis>,
|
||
|
|
<emphasis>read()</emphasis> and <emphasis>write()</emphasis>.
|
||
|
|
On newer systems, POSIX Async I/O calls may be an option.
|
||
|
|
Such user mode code will not necessarily be subject to
|
||
|
|
the GNU General Public License (GPL).
|
||
|
|
</para>
|
||
|
|
</listitem></varlistentry>
|
||
|
|
|
||
|
|
|
||
|
|
</variablelist>
|
||
|
|
|
||
|
|
<para>OTG-capable systems will also need to include a standard Linux-USB
|
||
|
|
host side stack,
|
||
|
|
with <emphasis>usbcore</emphasis>,
|
||
|
|
one or more <emphasis>Host Controller Drivers</emphasis> (HCDs),
|
||
|
|
<emphasis>USB Device Drivers</emphasis> to support
|
||
|
|
the OTG "Targeted Peripheral List",
|
||
|
|
and so forth.
|
||
|
|
There will also be an <emphasis>OTG Controller Driver</emphasis>,
|
||
|
|
which is visible to gadget and device driver developers only indirectly.
|
||
|
|
That helps the host and device side USB controllers implement the
|
||
|
|
two new OTG protocols (HNP and SRP).
|
||
|
|
Roles switch (host to peripheral, or vice versa) using HNP
|
||
|
|
during USB suspend processing, and SRP can be viewed as a
|
||
|
|
more battery-friendly kind of device wakeup protocol.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Over time, reusable utilities are evolving to help make some
|
||
|
|
gadget driver tasks simpler.
|
||
|
|
For example, building configuration descriptors from vectors of
|
||
|
|
descriptors for the configurations interfaces and endpoints is
|
||
|
|
now automated, and many drivers now use autoconfiguration to
|
||
|
|
choose hardware endpoints and initialize their descriptors.
|
||
|
|
|
||
|
|
A potential example of particular interest
|
||
|
|
is code implementing standard USB-IF protocols for
|
||
|
|
HID, networking, storage, or audio classes.
|
||
|
|
Some developers are interested in KDB or KGDB hooks, to let
|
||
|
|
target hardware be remotely debugged.
|
||
|
|
Most such USB protocol code doesn't need to be hardware-specific,
|
||
|
|
any more than network protocols like X11, HTTP, or NFS are.
|
||
|
|
Such gadget-side interface drivers should eventually be combined,
|
||
|
|
to implement composite devices.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
</chapter>
|
||
|
|
|
||
|
|
|
||
|
|
<chapter id="api"><title>Kernel Mode Gadget API</title>
|
||
|
|
|
||
|
|
<para>Gadget drivers declare themselves through a
|
||
|
|
<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for
|
||
|
|
most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>.
|
||
|
|
The response to a set_configuration usually involves
|
||
|
|
enabling one or more of the <emphasis>struct usb_ep</emphasis> objects
|
||
|
|
exposed by the gadget, and submitting one or more
|
||
|
|
<emphasis>struct usb_request</emphasis> buffers to transfer data.
|
||
|
|
Understand those four data types, and their operations, and
|
||
|
|
you will understand how this API works.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<note><title>Incomplete Data Type Descriptions</title>
|
||
|
|
|
||
|
|
<para>This documentation was prepared using the standard Linux
|
||
|
|
kernel <filename>docproc</filename> tool, which turns text
|
||
|
|
and in-code comments into SGML DocBook and then into usable
|
||
|
|
formats such as HTML or PDF.
|
||
|
|
Other than the "Chapter 9" data types, most of the significant
|
||
|
|
data types and functions are described here.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>However, docproc does not understand all the C constructs
|
||
|
|
that are used, so some relevant information is likely omitted from
|
||
|
|
what you are reading.
|
||
|
|
One example of such information is endpoint autoconfiguration.
|
||
|
|
You'll have to read the header file, and use example source
|
||
|
|
code (such as that for "Gadget Zero"), to fully understand the API.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>The part of the API implementing some basic
|
||
|
|
driver capabilities is specific to the version of the
|
||
|
|
Linux kernel that's in use.
|
||
|
|
The 2.6 kernel includes a <emphasis>driver model</emphasis>
|
||
|
|
framework that has no analogue on earlier kernels;
|
||
|
|
so those parts of the gadget API are not fully portable.
|
||
|
|
(They are implemented on 2.4 kernels, but in a different way.)
|
||
|
|
The driver model state is another part of this API that is
|
||
|
|
ignored by the kerneldoc tools.
|
||
|
|
</para>
|
||
|
|
</note>
|
||
|
|
|
||
|
|
<para>The core API does not expose
|
||
|
|
every possible hardware feature, only the most widely available ones.
|
||
|
|
There are significant hardware features, such as device-to-device DMA
|
||
|
|
(without temporary storage in a memory buffer)
|
||
|
|
that would be added using hardware-specific APIs.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>This API allows drivers to use conditional compilation to handle
|
||
|
|
endpoint capabilities of different hardware, but doesn't require that.
|
||
|
|
Hardware tends to have arbitrary restrictions, relating to
|
||
|
|
transfer types, addressing, packet sizes, buffering, and availability.
|
||
|
|
As a rule, such differences only matter for "endpoint zero" logic
|
||
|
|
that handles device configuration and management.
|
||
|
|
The API supports limited run-time
|
||
|
|
detection of capabilities, through naming conventions for endpoints.
|
||
|
|
Many drivers will be able to at least partially autoconfigure
|
||
|
|
themselves.
|
||
|
|
In particular, driver init sections will often have endpoint
|
||
|
|
autoconfiguration logic that scans the hardware's list of endpoints
|
||
|
|
to find ones matching the driver requirements
|
||
|
|
(relying on those conventions), to eliminate some of the most
|
||
|
|
common reasons for conditional compilation.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Like the Linux-USB host side API, this API exposes
|
||
|
|
the "chunky" nature of USB messages: I/O requests are in terms
|
||
|
|
of one or more "packets", and packet boundaries are visible to drivers.
|
||
|
|
Compared to RS-232 serial protocols, USB resembles
|
||
|
|
synchronous protocols like HDLC
|
||
|
|
(N bytes per frame, multipoint addressing, host as the primary
|
||
|
|
station and devices as secondary stations)
|
||
|
|
more than asynchronous ones
|
||
|
|
(tty style: 8 data bits per frame, no parity, one stop bit).
|
||
|
|
So for example the controller drivers won't buffer
|
||
|
|
two single byte writes into a single two-byte USB IN packet,
|
||
|
|
although gadget drivers may do so when they implement
|
||
|
|
protocols where packet boundaries (and "short packets")
|
||
|
|
are not significant.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<sect1 id="lifecycle"><title>Driver Life Cycle</title>
|
||
|
|
|
||
|
|
<para>Gadget drivers make endpoint I/O requests to hardware without
|
||
|
|
needing to know many details of the hardware, but driver
|
||
|
|
setup/configuration code needs to handle some differences.
|
||
|
|
Use the API like this:
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<orderedlist numeration='arabic'>
|
||
|
|
|
||
|
|
<listitem><para>Register a driver for the particular device side
|
||
|
|
usb controller hardware,
|
||
|
|
such as the net2280 on PCI (USB 2.0),
|
||
|
|
sa11x0 or pxa25x as found in Linux PDAs,
|
||
|
|
and so on.
|
||
|
|
At this point the device is logically in the USB ch9 initial state
|
||
|
|
("attached"), drawing no power and not usable
|
||
|
|
(since it does not yet support enumeration).
|
||
|
|
Any host should not see the device, since it's not
|
||
|
|
activated the data line pullup used by the host to
|
||
|
|
detect a device, even if VBUS power is available.
|
||
|
|
</para></listitem>
|
||
|
|
|
||
|
|
<listitem><para>Register a gadget driver that implements some higher level
|
||
|
|
device function. That will then bind() to a usb_gadget, which
|
||
|
|
activates the data line pullup sometime after detecting VBUS.
|
||
|
|
</para></listitem>
|
||
|
|
|
||
|
|
<listitem><para>The hardware driver can now start enumerating.
|
||
|
|
The steps it handles are to accept USB power and set_address requests.
|
||
|
|
Other steps are handled by the gadget driver.
|
||
|
|
If the gadget driver module is unloaded before the host starts to
|
||
|
|
enumerate, steps before step 7 are skipped.
|
||
|
|
</para></listitem>
|
||
|
|
|
||
|
|
<listitem><para>The gadget driver's setup() call returns usb descriptors,
|
||
|
|
based both on what the bus interface hardware provides and on the
|
||
|
|
functionality being implemented.
|
||
|
|
That can involve alternate settings or configurations,
|
||
|
|
unless the hardware prevents such operation.
|
||
|
|
For OTG devices, each configuration descriptor includes
|
||
|
|
an OTG descriptor.
|
||
|
|
</para></listitem>
|
||
|
|
|
||
|
|
<listitem><para>The gadget driver handles the last step of enumeration,
|
||
|
|
when the USB host issues a set_configuration call.
|
||
|
|
It enables all endpoints used in that configuration,
|
||
|
|
with all interfaces in their default settings.
|
||
|
|
That involves using a list of the hardware's endpoints, enabling each
|
||
|
|
endpoint according to its descriptor.
|
||
|
|
It may also involve using <function>usb_gadget_vbus_draw</function>
|
||
|
|
to let more power be drawn from VBUS, as allowed by that configuration.
|
||
|
|
For OTG devices, setting a configuration may also involve reporting
|
||
|
|
HNP capabilities through a user interface.
|
||
|
|
</para></listitem>
|
||
|
|
|
||
|
|
<listitem><para>Do real work and perform data transfers, possibly involving
|
||
|
|
changes to interface settings or switching to new configurations, until the
|
||
|
|
device is disconnect()ed from the host.
|
||
|
|
Queue any number of transfer requests to each endpoint.
|
||
|
|
It may be suspended and resumed several times before being disconnected.
|
||
|
|
On disconnect, the drivers go back to step 3 (above).
|
||
|
|
</para></listitem>
|
||
|
|
|
||
|
|
<listitem><para>When the gadget driver module is being unloaded,
|
||
|
|
the driver unbind() callback is issued. That lets the controller
|
||
|
|
driver be unloaded.
|
||
|
|
</para></listitem>
|
||
|
|
|
||
|
|
</orderedlist>
|
||
|
|
|
||
|
|
<para>Drivers will normally be arranged so that just loading the
|
||
|
|
gadget driver module (or statically linking it into a Linux kernel)
|
||
|
|
allows the peripheral device to be enumerated, but some drivers
|
||
|
|
will defer enumeration until some higher level component (like
|
||
|
|
a user mode daemon) enables it.
|
||
|
|
Note that at this lowest level there are no policies about how
|
||
|
|
ep0 configuration logic is implemented,
|
||
|
|
except that it should obey USB specifications.
|
||
|
|
Such issues are in the domain of gadget drivers,
|
||
|
|
including knowing about implementation constraints
|
||
|
|
imposed by some USB controllers
|
||
|
|
or understanding that composite devices might happen to
|
||
|
|
be built by integrating reusable components.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Note that the lifecycle above can be slightly different
|
||
|
|
for OTG devices.
|
||
|
|
Other than providing an additional OTG descriptor in each
|
||
|
|
configuration, only the HNP-related differences are particularly
|
||
|
|
visible to driver code.
|
||
|
|
They involve reporting requirements during the SET_CONFIGURATION
|
||
|
|
request, and the option to invoke HNP during some suspend callbacks.
|
||
|
|
Also, SRP changes the semantics of
|
||
|
|
<function>usb_gadget_wakeup</function>
|
||
|
|
slightly.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
</sect1>
|
||
|
|
|
||
|
|
<sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title>
|
||
|
|
|
||
|
|
<para>Gadget drivers
|
||
|
|
rely on common USB structures and constants
|
||
|
|
defined in the
|
||
|
|
<filename><linux/usb_ch9.h></filename>
|
||
|
|
header file, which is standard in Linux 2.6 kernels.
|
||
|
|
These are the same types and constants used by host
|
||
|
|
side drivers (and usbcore).
|
||
|
|
</para>
|
||
|
|
|
||
|
|
!Iinclude/linux/usb_ch9.h
|
||
|
|
</sect1>
|
||
|
|
|
||
|
|
<sect1 id="core"><title>Core Objects and Methods</title>
|
||
|
|
|
||
|
|
<para>These are declared in
|
||
|
|
<filename><linux/usb_gadget.h></filename>,
|
||
|
|
and are used by gadget drivers to interact with
|
||
|
|
USB peripheral controller drivers.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<!-- yeech, this is ugly in nsgmls PDF output.
|
||
|
|
|
||
|
|
the PDF bookmark and refentry output nesting is wrong,
|
||
|
|
and the member/argument documentation indents ugly.
|
||
|
|
|
||
|
|
plus something (docproc?) adds whitespace before the
|
||
|
|
descriptive paragraph text, so it can't line up right
|
||
|
|
unless the explanations are trivial.
|
||
|
|
-->
|
||
|
|
|
||
|
|
!Iinclude/linux/usb_gadget.h
|
||
|
|
</sect1>
|
||
|
|
|
||
|
|
<sect1 id="utils"><title>Optional Utilities</title>
|
||
|
|
|
||
|
|
<para>The core API is sufficient for writing a USB Gadget Driver,
|
||
|
|
but some optional utilities are provided to simplify common tasks.
|
||
|
|
These utilities include endpoint autoconfiguration.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
!Edrivers/usb/gadget/usbstring.c
|
||
|
|
!Edrivers/usb/gadget/config.c
|
||
|
|
<!-- !Edrivers/usb/gadget/epautoconf.c -->
|
||
|
|
</sect1>
|
||
|
|
|
||
|
|
</chapter>
|
||
|
|
|
||
|
|
<chapter id="controllers"><title>Peripheral Controller Drivers</title>
|
||
|
|
|
||
|
|
<para>The first hardware supporting this API was the NetChip 2280
|
||
|
|
controller, which supports USB 2.0 high speed and is based on PCI.
|
||
|
|
This is the <filename>net2280</filename> driver module.
|
||
|
|
The driver supports Linux kernel versions 2.4 and 2.6;
|
||
|
|
contact NetChip Technologies for development boards and product
|
||
|
|
information.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Other hardware working in the "gadget" framework includes:
|
||
|
|
Intel's PXA 25x and IXP42x series processors
|
||
|
|
(<filename>pxa2xx_udc</filename>),
|
||
|
|
Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>),
|
||
|
|
Renesas SH7705/7727 (<filename>sh_udc</filename>),
|
||
|
|
MediaQ 11xx (<filename>mq11xx_udc</filename>),
|
||
|
|
Hynix HMS30C7202 (<filename>h7202_udc</filename>),
|
||
|
|
National 9303/4 (<filename>n9604_udc</filename>),
|
||
|
|
Texas Instruments OMAP (<filename>omap_udc</filename>),
|
||
|
|
Sharp LH7A40x (<filename>lh7a40x_udc</filename>),
|
||
|
|
and more.
|
||
|
|
Most of those are full speed controllers.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>At this writing, there are people at work on drivers in
|
||
|
|
this framework for several other USB device controllers,
|
||
|
|
with plans to make many of them be widely available.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<!-- !Edrivers/usb/gadget/net2280.c -->
|
||
|
|
|
||
|
|
<para>A partial USB simulator,
|
||
|
|
the <filename>dummy_hcd</filename> driver, is available.
|
||
|
|
It can act like a net2280, a pxa25x, or an sa11x0 in terms
|
||
|
|
of available endpoints and device speeds; and it simulates
|
||
|
|
control, bulk, and to some extent interrupt transfers.
|
||
|
|
That lets you develop some parts of a gadget driver on a normal PC,
|
||
|
|
without any special hardware, and perhaps with the assistance
|
||
|
|
of tools such as GDB running with User Mode Linux.
|
||
|
|
At least one person has expressed interest in adapting that
|
||
|
|
approach, hooking it up to a simulator for a microcontroller.
|
||
|
|
Such simulators can help debug subsystems where the runtime hardware
|
||
|
|
is unfriendly to software development, or is not yet available.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Support for other controllers is expected to be developed
|
||
|
|
and contributed
|
||
|
|
over time, as this driver framework evolves.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
</chapter>
|
||
|
|
|
||
|
|
<chapter id="gadget"><title>Gadget Drivers</title>
|
||
|
|
|
||
|
|
<para>In addition to <emphasis>Gadget Zero</emphasis>
|
||
|
|
(used primarily for testing and development with drivers
|
||
|
|
for usb controller hardware), other gadget drivers exist.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>There's an <emphasis>ethernet</emphasis> gadget
|
||
|
|
driver, which implements one of the most useful
|
||
|
|
<emphasis>Communications Device Class</emphasis> (CDC) models.
|
||
|
|
One of the standards for cable modem interoperability even
|
||
|
|
specifies the use of this ethernet model as one of two
|
||
|
|
mandatory options.
|
||
|
|
Gadgets using this code look to a USB host as if they're
|
||
|
|
an Ethernet adapter.
|
||
|
|
It provides access to a network where the gadget's CPU is one host,
|
||
|
|
which could easily be bridging, routing, or firewalling
|
||
|
|
access to other networks.
|
||
|
|
Since some hardware can't fully implement the CDC Ethernet
|
||
|
|
requirements, this driver also implements a "good parts only"
|
||
|
|
subset of CDC Ethernet.
|
||
|
|
(That subset doesn't advertise itself as CDC Ethernet,
|
||
|
|
to avoid creating problems.)
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Support for Microsoft's <emphasis>RNDIS</emphasis>
|
||
|
|
protocol has been contributed by Pengutronix and Auerswald GmbH.
|
||
|
|
This is like CDC Ethernet, but it runs on more slightly USB hardware
|
||
|
|
(but less than the CDC subset).
|
||
|
|
However, its main claim to fame is being able to connect directly to
|
||
|
|
recent versions of Windows, using drivers that Microsoft bundles
|
||
|
|
and supports, making it much simpler to network with Windows.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>There is also support for user mode gadget drivers,
|
||
|
|
using <emphasis>gadgetfs</emphasis>.
|
||
|
|
This provides a <emphasis>User Mode API</emphasis> that presents
|
||
|
|
each endpoint as a single file descriptor. I/O is done using
|
||
|
|
normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls.
|
||
|
|
Familiar tools like GDB and pthreads can be used to
|
||
|
|
develop and debug user mode drivers, so that once a robust
|
||
|
|
controller driver is available many applications for it
|
||
|
|
won't require new kernel mode software.
|
||
|
|
Linux 2.6 <emphasis>Async I/O (AIO)</emphasis>
|
||
|
|
support is available, so that user mode software
|
||
|
|
can stream data with only slightly more overhead
|
||
|
|
than a kernel driver.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>There's a USB Mass Storage class driver, which provides
|
||
|
|
a different solution for interoperability with systems such
|
||
|
|
as MS-Windows and MacOS.
|
||
|
|
That <emphasis>File-backed Storage</emphasis> driver uses a
|
||
|
|
file or block device as backing store for a drive,
|
||
|
|
like the <filename>loop</filename> driver.
|
||
|
|
The USB host uses the BBB, CB, or CBI versions of the mass
|
||
|
|
storage class specification, using transparent SCSI commands
|
||
|
|
to access the data from the backing store.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>There's a "serial line" driver, useful for TTY style
|
||
|
|
operation over USB.
|
||
|
|
The latest version of that driver supports CDC ACM style
|
||
|
|
operation, like a USB modem, and so on most hardware it can
|
||
|
|
interoperate easily with MS-Windows.
|
||
|
|
One interesting use of that driver is in boot firmware (like a BIOS),
|
||
|
|
which can sometimes use that model with very small systems without
|
||
|
|
real serial lines.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Support for other kinds of gadget is expected to
|
||
|
|
be developed and contributed
|
||
|
|
over time, as this driver framework evolves.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
</chapter>
|
||
|
|
|
||
|
|
<chapter id="otg"><title>USB On-The-GO (OTG)</title>
|
||
|
|
|
||
|
|
<para>USB OTG support on Linux 2.6 was initially developed
|
||
|
|
by Texas Instruments for
|
||
|
|
<ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx
|
||
|
|
series processors.
|
||
|
|
Other OTG systems should work in similar ways, but the
|
||
|
|
hardware level details could be very different.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Systems need specialized hardware support to implement OTG,
|
||
|
|
notably including a special <emphasis>Mini-AB</emphasis> jack
|
||
|
|
and associated transciever to support <emphasis>Dual-Role</emphasis>
|
||
|
|
operation:
|
||
|
|
they can act either as a host, using the standard
|
||
|
|
Linux-USB host side driver stack,
|
||
|
|
or as a peripheral, using this "gadget" framework.
|
||
|
|
To do that, the system software relies on small additions
|
||
|
|
to those programming interfaces,
|
||
|
|
and on a new internal component (here called an "OTG Controller")
|
||
|
|
affecting which driver stack connects to the OTG port.
|
||
|
|
In each role, the system can re-use the existing pool of
|
||
|
|
hardware-neutral drivers, layered on top of the controller
|
||
|
|
driver interfaces (<emphasis>usb_bus</emphasis> or
|
||
|
|
<emphasis>usb_gadget</emphasis>).
|
||
|
|
Such drivers need at most minor changes, and most of the calls
|
||
|
|
added to support OTG can also benefit non-OTG products.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis>
|
||
|
|
flag, and use it to determine whether or not to include
|
||
|
|
an OTG descriptor in each of their configurations.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>Gadget drivers may need changes to support the
|
||
|
|
two new OTG protocols, exposed in new gadget attributes
|
||
|
|
such as <emphasis>b_hnp_enable</emphasis> flag.
|
||
|
|
HNP support should be reported through a user interface
|
||
|
|
(two LEDs could suffice), and is triggered in some cases
|
||
|
|
when the host suspends the peripheral.
|
||
|
|
SRP support can be user-initiated just like remote wakeup,
|
||
|
|
probably by pressing the same button.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>On the host side, USB device drivers need
|
||
|
|
to be taught to trigger HNP at appropriate moments, using
|
||
|
|
<function>usb_suspend_device()</function>.
|
||
|
|
That also conserves battery power, which is useful even
|
||
|
|
for non-OTG configurations.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>Also on the host side, a driver must support the
|
||
|
|
OTG "Targeted Peripheral List". That's just a whitelist,
|
||
|
|
used to reject peripherals not supported with a given
|
||
|
|
Linux OTG host.
|
||
|
|
<emphasis>This whitelist is product-specific;
|
||
|
|
each product must modify <filename>otg_whitelist.h</filename>
|
||
|
|
to match its interoperability specification.
|
||
|
|
</emphasis>
|
||
|
|
</para>
|
||
|
|
<para>Non-OTG Linux hosts, like PCs and workstations,
|
||
|
|
normally have some solution for adding drivers, so that
|
||
|
|
peripherals that aren't recognized can eventually be supported.
|
||
|
|
That approach is unreasonable for consumer products that may
|
||
|
|
never have their firmware upgraded, and where it's usually
|
||
|
|
unrealistic to expect traditional PC/workstation/server kinds
|
||
|
|
of support model to work.
|
||
|
|
For example, it's often impractical to change device firmware
|
||
|
|
once the product has been distributed, so driver bugs can't
|
||
|
|
normally be fixed if they're found after shipment.
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Additional changes are needed below those hardware-neutral
|
||
|
|
<emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis>
|
||
|
|
driver interfaces; those aren't discussed here in any detail.
|
||
|
|
Those affect the hardware-specific code for each USB Host or Peripheral
|
||
|
|
controller, and how the HCD initializes (since OTG can be active only
|
||
|
|
on a single port).
|
||
|
|
They also involve what may be called an <emphasis>OTG Controller
|
||
|
|
Driver</emphasis>, managing the OTG transceiver and the OTG state
|
||
|
|
machine logic as well as much of the root hub behavior for the
|
||
|
|
OTG port.
|
||
|
|
The OTG controller driver needs to activate and deactivate USB
|
||
|
|
controllers depending on the relevant device role.
|
||
|
|
Some related changes were needed inside usbcore, so that it
|
||
|
|
can identify OTG-capable devices and respond appropriately
|
||
|
|
to HNP or SRP protocols.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
</chapter>
|
||
|
|
|
||
|
|
</book>
|
||
|
|
<!--
|
||
|
|
vim:syntax=sgml:sw=4
|
||
|
|
-->
|