Commit 0d2cc6b7 authored by David Brownell's avatar David Brownell Committed by Greg Kroah-Hartman

[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.
parent d5d4f8fe
......@@ -313,8 +313,8 @@ usb_ep_free_buffer (struct usb_ep *ep, void *buf, dma_addr_t dma, unsigned len)
* 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 @@ static inline int usb_ep_dequeue (struct usb_ep *ep, struct usb_request *req)
* 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_set_halt (struct usb_ep *ep)
* 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 @@ usb_gadget_clear_selfpowered (struct usb_gadget *gadget)
* 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 @@ usb_gadget_clear_selfpowered (struct usb_gadget *gadget)
* 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;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment