.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "USB_GADGET_DRIVER" "9" "17 July 2003" "" ""

.SH NAME
struct usb_gadget_driver \- driver for usb 'slave' devices
.SH SYNOPSIS

.nf
struct usb_gadget_driver {
  char * function;
  enum usb_device_speed speed;
  int (* bind (struct usb_gadget *);
  void (* unbind (struct usb_gadget *);
  int (* setup (struct usb_gadget *,const struct usb_ctrlrequest *);
  void (* disconnect (struct usb_gadget *);
  void (* suspend (struct usb_gadget *);
  void (* resume (struct usb_gadget *);
};  
.fi
.SH "MEMBERS"
.TP
\fBfunction\fR
String describing the gadget's function
.TP
\fBspeed\fR
Highest speed the driver handles.
.TP
\fBbind\fR
Invoked when the driver is bound to a gadget, usually
after registering the driver.
At that point, ep0 is fully initialized, and ep_list holds
the currently-available endpoints.
Called in a context that permits sleeping.
.TP
\fBunbind\fR
Invoked when the driver is unbound from a gadget,
usually from rmmod (after a disconnect is reported).
Called in a context that permits sleeping.
.TP
\fBsetup\fR
Invoked for ep0 control requests that aren't handled by
the hardware level driver. Most calls must be handled by
the gadget driver, including descriptor and configuration
management.  The 16 bit members of the setup data are in
cpu order. Called in_interrupt; this may not sleep.  Driver
queues a response to ep0, or returns negative to stall.
.TP
\fBdisconnect\fR
Invoked after all transfers have been stopped,
when the host is disconnected.  May be called in_interrupt; this
may not sleep.
.TP
\fBsuspend\fR
Invoked on USB suspend.  May be called in_interrupt.
.TP
\fBresume\fR
Invoked on USB resume.  May be called in_interrupt.
.SH "DESCRIPTION"
.PP
Devices are disabled till a gadget driver successfully \fBbind\fRs, which
means the driver will handle \fBsetup\fR requests needed to enumerate (and
meet ``chapter 9'' requirements) then do some useful work.
.PP
Drivers use hardware-specific knowledge to configure the usb hardware.
endpoint addressing is only one of several hardware characteristics that
are in descriptors the ep0 implementation returns from \fBsetup\fR calls.
.PP
Except for ep0 implementation, most driver code shouldn't need change to
run on top of different usb controllers.  It'll use endpoints set up by
that ep0 implementation.
.PP
The usb controller driver handles a few standard usb requests.  Those
include set_address, and feature flags for devices, interfaces, and
endpoints (the get_status, set_feature, and clear_feature requests).
.PP
Accordingly, the driver's \fBsetup\fR callback must always implement all
get_descriptor requests, returning at least a device descriptor and
a configuration descriptor.  Drivers must make sure the endpoint
descriptors match any hardware constraints. Some hardware also constrains
other descriptors. (The pxa250 allows only configurations 1, 2, or 3).
.PP
The driver's \fBsetup\fR callback must also implement set_configuration,
and should also implement set_interface, get_configuration, and
get_interface.  Setting a configuration (or interface) is where
endpoints should be activated or (config 0) shut down.
.PP
(Note that only the default control endpoint is supported.  Neither
hosts nor devices generally support control traffic except to ep0.)
.PP
Most devices will ignore USB suspend/resume operations, and so will
not provide those callbacks.  However, some may need to change modes
when the host is not longer directing those activities.  For example,
local controls (buttons, dials, etc) may need to be re-enabled since
the (remote) host can't do that any longer. 
.SH "ABOUT THIS DOCUMENT"
.PP
Permission is granted to copy, distribute, and/or modify
this document under the terms of the GNU Free Documentation
License, version 1.2, or any later version published by the
Free Software Foundation; with the Invariant Sections being
the "GNU Free Documentation License",
no Front-Cover Texts,
and
no Back-Cover Texts.
.PP
This documentation 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 Free Documentation License for more details.
.PP
Note that certain sections of this document are merged
into Linux kernel source code.
That content is the bulk of 
[XRef to CORE]> and
[XRef to UTILS]>,
where the "GNU Free Documentation License" is identified
as an alternate licence for its documentation.
.PP
If you have comments on the formatting of this manpage, then please contact
Michael Still (mikal@stillhq.com).
.PP
This documentation was generated with kernel version 2.5.73.