ChangeSet 1.1276.1.44, 2003/08/27 15:02:13-07:00, david-b@pacbell.net [PATCH] USB: 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;