ChangeSet 1.1276.1.44, 2003/08/27 15:02:13-07:00, [EMAIL PROTECTED]
[PATCH] USB: <linux/usb_gadget.h> minor doc updates
Small kerneldoc clarifications:
- more endpoint halt clearing info:
* some hardware can't do it; which causes problems with drivers
that want to use multiple interfaces or altsettings.
* it doesn't affect queuing of data (should help usb-storage
gadget driver, plus it's more sensible this way);
- disconnect() callback not guaranteed: some hardware can't tell
Mostly this captures answers to questions I've been asked.
include/linux/usb_gadget.h | 22 ++++++++++++++++------
1 files changed, 16 insertions(+), 6 deletions(-)
diff -Nru a/include/linux/usb_gadget.h b/include/linux/usb_gadget.h
--- a/include/linux/usb_gadget.h Tue Sep 2 12:43:51 2003
+++ b/include/linux/usb_gadget.h Tue Sep 2 12:43:51 2003
@@ -313,8 +313,8 @@
* arranges to poll once per interval, and the gadget driver usually will
* have queued some data to transfer at that time.
*
- * Returns zero, or a negative error code. Endpoints that are not enabled,
- * or which are enabled but halted, report errors; errors will also be
+ * Returns zero, or a negative error code. Endpoints that are not enabled
+ * report errors; errors will also be
* reported when the usb peripheral is disconnected.
*/
static inline int
@@ -352,6 +352,11 @@
* clears this feature; drivers may need to empty the endpoint's request
* queue first, to make sure no inappropriate transfers happen.
*
+ * Note that while an endpoint CLEAR_FEATURE will be invisible to the
+ * gadget driver, a SET_INTERFACE will not be. To reset endpoints for the
+ * current altsetting, see usb_ep_clear_halt(). When switching altsettings,
+ * it's simplest to use usb_ep_enable() or usb_ep_disable() for the endpoints.
+ *
* Returns zero, or a negative error code. On success, this call sets
* underlying hardware state that blocks data transfers.
*/
@@ -365,12 +370,14 @@
* usb_ep_clear_halt - clears endpoint halt, and resets toggle
* @ep:the bulk or interrupt endpoint being reset
*
- * use this when responding to the standard usb "set interface" request,
+ * Use this when responding to the standard usb "set interface" request,
* for endpoints that aren't reconfigured, after clearing any other state
* in the endpoint's i/o queue.
*
- * returns zero, or a negative error code. on success, this call clears
+ * Returns zero, or a negative error code. On success, this call clears
* the underlying hardware state reflecting endpoint halt and data toggle.
+ * Note that some hardware can't support this request (like pxa2xx_udc),
+ * and accordingly can't correctly implement interface altsettings.
*/
static inline int
usb_ep_clear_halt (struct usb_ep *ep)
@@ -562,7 +569,8 @@
* queues a response to ep0, or returns negative to stall.
* @disconnect: Invoked after all transfers have been stopped,
* when the host is disconnected. May be called in_interrupt; this
- * may not sleep.
+ * may not sleep. Some devices can't detect disconnect, so this might
+ * not be called except as part of controller shutdown.
* @unbind: Invoked when the driver is unbound from a gadget,
* usually from rmmod (after a disconnect is reported).
* Called in a context that permits sleeping.
@@ -603,7 +611,9 @@
* 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.
+ * the (remote) host can't do that any longer; or an error state might
+ * be cleared, to make the device behave identically whether or not
+ * power is maintained.
*/
struct usb_gadget_driver {
char *function;
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
[EMAIL PROTECTED]
To unsubscribe, use the last form field at:
https://lists.sourceforge.net/lists/listinfo/linux-usb-devel
