home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / src / linux-headers-2.6.28-15 / include / linux / usb / gadget.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-12-24  |  34.2 KB  |  894 lines
  1. /*
  2.  * <linux/usb/gadget.h>
  3.  *
  4.  * We call the USB code inside a Linux-based peripheral device a "gadget"
  5.  * driver, except for the hardware-specific bus glue.  One USB host can
  6.  * master many USB gadgets, but the gadgets are only slaved to one host.
  7.  *
  8.  *
  9.  * (C) Copyright 2002-2004 by David Brownell
  10.  * All Rights Reserved.
  11.  *
  12.  * This software is licensed under the GNU GPL version 2.
  13.  */
  14.  
  15. #ifndef __LINUX_USB_GADGET_H
  16. #define __LINUX_USB_GADGET_H
  17.  
  18. struct usb_ep;
  19.  
  20. /**
  21.  * struct usb_request - describes one i/o request
  22.  * @buf: Buffer used for data.  Always provide this; some controllers
  23.  *    only use PIO, or don't use DMA for some endpoints.
  24.  * @dma: DMA address corresponding to 'buf'.  If you don't set this
  25.  *    field, and the usb controller needs one, it is responsible
  26.  *    for mapping and unmapping the buffer.
  27.  * @length: Length of that data
  28.  * @no_interrupt: If true, hints that no completion irq is needed.
  29.  *    Helpful sometimes with deep request queues that are handled
  30.  *    directly by DMA controllers.
  31.  * @zero: If true, when writing data, makes the last packet be "short"
  32.  *     by adding a zero length packet as needed;
  33.  * @short_not_ok: When reading data, makes short packets be
  34.  *     treated as errors (queue stops advancing till cleanup).
  35.  * @complete: Function called when request completes, so this request and
  36.  *    its buffer may be re-used.  The function will always be called with
  37.  *    interrupts disabled, and it must not sleep.
  38.  *    Reads terminate with a short packet, or when the buffer fills,
  39.  *    whichever comes first.  When writes terminate, some data bytes
  40.  *    will usually still be in flight (often in a hardware fifo).
  41.  *    Errors (for reads or writes) stop the queue from advancing
  42.  *    until the completion function returns, so that any transfers
  43.  *    invalidated by the error may first be dequeued.
  44.  * @context: For use by the completion callback
  45.  * @list: For use by the gadget driver.
  46.  * @status: Reports completion code, zero or a negative errno.
  47.  *    Normally, faults block the transfer queue from advancing until
  48.  *    the completion callback returns.
  49.  *    Code "-ESHUTDOWN" indicates completion caused by device disconnect,
  50.  *    or when the driver disabled the endpoint.
  51.  * @actual: Reports bytes transferred to/from the buffer.  For reads (OUT
  52.  *    transfers) this may be less than the requested length.  If the
  53.  *    short_not_ok flag is set, short reads are treated as errors
  54.  *    even when status otherwise indicates successful completion.
  55.  *    Note that for writes (IN transfers) some data bytes may still
  56.  *    reside in a device-side FIFO when the request is reported as
  57.  *    complete.
  58.  *
  59.  * These are allocated/freed through the endpoint they're used with.  The
  60.  * hardware's driver can add extra per-request data to the memory it returns,
  61.  * which often avoids separate memory allocations (potential failures),
  62.  * later when the request is queued.
  63.  *
  64.  * Request flags affect request handling, such as whether a zero length
  65.  * packet is written (the "zero" flag), whether a short read should be
  66.  * treated as an error (blocking request queue advance, the "short_not_ok"
  67.  * flag), or hinting that an interrupt is not required (the "no_interrupt"
  68.  * flag, for use with deep request queues).
  69.  *
  70.  * Bulk endpoints can use any size buffers, and can also be used for interrupt
  71.  * transfers. interrupt-only endpoints can be much less functional.
  72.  *
  73.  * NOTE:  this is analagous to 'struct urb' on the host side, except that
  74.  * it's thinner and promotes more pre-allocation.
  75.  */
  76.  
  77. struct usb_request {
  78.     void            *buf;
  79.     unsigned        length;
  80.     dma_addr_t        dma;
  81.  
  82.     unsigned        no_interrupt:1;
  83.     unsigned        zero:1;
  84.     unsigned        short_not_ok:1;
  85.  
  86.     void            (*complete)(struct usb_ep *ep,
  87.                     struct usb_request *req);
  88.     void            *context;
  89.     struct list_head    list;
  90.  
  91.     int            status;
  92.     unsigned        actual;
  93. };
  94.  
  95. /*-------------------------------------------------------------------------*/
  96.  
  97. /* endpoint-specific parts of the api to the usb controller hardware.
  98.  * unlike the urb model, (de)multiplexing layers are not required.
  99.  * (so this api could slash overhead if used on the host side...)
  100.  *
  101.  * note that device side usb controllers commonly differ in how many
  102.  * endpoints they support, as well as their capabilities.
  103.  */
  104. struct usb_ep_ops {
  105.     int (*enable) (struct usb_ep *ep,
  106.         const struct usb_endpoint_descriptor *desc);
  107.     int (*disable) (struct usb_ep *ep);
  108.  
  109.     struct usb_request *(*alloc_request) (struct usb_ep *ep,
  110.         gfp_t gfp_flags);
  111.     void (*free_request) (struct usb_ep *ep, struct usb_request *req);
  112.  
  113.     int (*queue) (struct usb_ep *ep, struct usb_request *req,
  114.         gfp_t gfp_flags);
  115.     int (*dequeue) (struct usb_ep *ep, struct usb_request *req);
  116.  
  117.     int (*set_halt) (struct usb_ep *ep, int value);
  118.     int (*set_wedge) (struct usb_ep *ep);
  119.  
  120.     int (*fifo_status) (struct usb_ep *ep);
  121.     void (*fifo_flush) (struct usb_ep *ep);
  122. };
  123.  
  124. /**
  125.  * struct usb_ep - device side representation of USB endpoint
  126.  * @name:identifier for the endpoint, such as "ep-a" or "ep9in-bulk"
  127.  * @ops: Function pointers used to access hardware-specific operations.
  128.  * @ep_list:the gadget's ep_list holds all of its endpoints
  129.  * @maxpacket:The maximum packet size used on this endpoint.  The initial
  130.  *    value can sometimes be reduced (hardware allowing), according to
  131.  *      the endpoint descriptor used to configure the endpoint.
  132.  * @driver_data:for use by the gadget driver.  all other fields are
  133.  *    read-only to gadget drivers.
  134.  *
  135.  * the bus controller driver lists all the general purpose endpoints in
  136.  * gadget->ep_list.  the control endpoint (gadget->ep0) is not in that list,
  137.  * and is accessed only in response to a driver setup() callback.
  138.  */
  139. struct usb_ep {
  140.     void            *driver_data;
  141.  
  142.     const char        *name;
  143.     const struct usb_ep_ops    *ops;
  144.     struct list_head    ep_list;
  145.     unsigned        maxpacket:16;
  146. };
  147.  
  148. /*-------------------------------------------------------------------------*/
  149.  
  150. /**
  151.  * usb_ep_enable - configure endpoint, making it usable
  152.  * @ep:the endpoint being configured.  may not be the endpoint named "ep0".
  153.  *    drivers discover endpoints through the ep_list of a usb_gadget.
  154.  * @desc:descriptor for desired behavior.  caller guarantees this pointer
  155.  *    remains valid until the endpoint is disabled; the data byte order
  156.  *    is little-endian (usb-standard).
  157.  *
  158.  * when configurations are set, or when interface settings change, the driver
  159.  * will enable or disable the relevant endpoints.  while it is enabled, an
  160.  * endpoint may be used for i/o until the driver receives a disconnect() from
  161.  * the host or until the endpoint is disabled.
  162.  *
  163.  * the ep0 implementation (which calls this routine) must ensure that the
  164.  * hardware capabilities of each endpoint match the descriptor provided
  165.  * for it.  for example, an endpoint named "ep2in-bulk" would be usable
  166.  * for interrupt transfers as well as bulk, but it likely couldn't be used
  167.  * for iso transfers or for endpoint 14.  some endpoints are fully
  168.  * configurable, with more generic names like "ep-a".  (remember that for
  169.  * USB, "in" means "towards the USB master".)
  170.  *
  171.  * returns zero, or a negative error code.
  172.  */
  173. static inline int usb_ep_enable(struct usb_ep *ep,
  174.                 const struct usb_endpoint_descriptor *desc)
  175. {
  176.     return ep->ops->enable(ep, desc);
  177. }
  178.  
  179. /**
  180.  * usb_ep_disable - endpoint is no longer usable
  181.  * @ep:the endpoint being unconfigured.  may not be the endpoint named "ep0".
  182.  *
  183.  * no other task may be using this endpoint when this is called.
  184.  * any pending and uncompleted requests will complete with status
  185.  * indicating disconnect (-ESHUTDOWN) before this call returns.
  186.  * gadget drivers must call usb_ep_enable() again before queueing
  187.  * requests to the endpoint.
  188.  *
  189.  * returns zero, or a negative error code.
  190.  */
  191. static inline int usb_ep_disable(struct usb_ep *ep)
  192. {
  193.     return ep->ops->disable(ep);
  194. }
  195.  
  196. /**
  197.  * usb_ep_alloc_request - allocate a request object to use with this endpoint
  198.  * @ep:the endpoint to be used with with the request
  199.  * @gfp_flags:GFP_* flags to use
  200.  *
  201.  * Request objects must be allocated with this call, since they normally
  202.  * need controller-specific setup and may even need endpoint-specific
  203.  * resources such as allocation of DMA descriptors.
  204.  * Requests may be submitted with usb_ep_queue(), and receive a single
  205.  * completion callback.  Free requests with usb_ep_free_request(), when
  206.  * they are no longer needed.
  207.  *
  208.  * Returns the request, or null if one could not be allocated.
  209.  */
  210. static inline struct usb_request *usb_ep_alloc_request(struct usb_ep *ep,
  211.                                gfp_t gfp_flags)
  212. {
  213.     return ep->ops->alloc_request(ep, gfp_flags);
  214. }
  215.  
  216. /**
  217.  * usb_ep_free_request - frees a request object
  218.  * @ep:the endpoint associated with the request
  219.  * @req:the request being freed
  220.  *
  221.  * Reverses the effect of usb_ep_alloc_request().
  222.  * Caller guarantees the request is not queued, and that it will
  223.  * no longer be requeued (or otherwise used).
  224.  */
  225. static inline void usb_ep_free_request(struct usb_ep *ep,
  226.                        struct usb_request *req)
  227. {
  228.     ep->ops->free_request(ep, req);
  229. }
  230.  
  231. /**
  232.  * usb_ep_queue - queues (submits) an I/O request to an endpoint.
  233.  * @ep:the endpoint associated with the request
  234.  * @req:the request being submitted
  235.  * @gfp_flags: GFP_* flags to use in case the lower level driver couldn't
  236.  *    pre-allocate all necessary memory with the request.
  237.  *
  238.  * This tells the device controller to perform the specified request through
  239.  * that endpoint (reading or writing a buffer).  When the request completes,
  240.  * including being canceled by usb_ep_dequeue(), the request's completion
  241.  * routine is called to return the request to the driver.  Any endpoint
  242.  * (except control endpoints like ep0) may have more than one transfer
  243.  * request queued; they complete in FIFO order.  Once a gadget driver
  244.  * submits a request, that request may not be examined or modified until it
  245.  * is given back to that driver through the completion callback.
  246.  *
  247.  * Each request is turned into one or more packets.  The controller driver
  248.  * never merges adjacent requests into the same packet.  OUT transfers
  249.  * will sometimes use data that's already buffered in the hardware.
  250.  * Drivers can rely on the fact that the first byte of the request's buffer
  251.  * always corresponds to the first byte of some USB packet, for both
  252.  * IN and OUT transfers.
  253.  *
  254.  * Bulk endpoints can queue any amount of data; the transfer is packetized
  255.  * automatically.  The last packet will be short if the request doesn't fill it
  256.  * out completely.  Zero length packets (ZLPs) should be avoided in portable
  257.  * protocols since not all usb hardware can successfully handle zero length
  258.  * packets.  (ZLPs may be explicitly written, and may be implicitly written if
  259.  * the request 'zero' flag is set.)  Bulk endpoints may also be used
  260.  * for interrupt transfers; but the reverse is not true, and some endpoints
  261.  * won't support every interrupt transfer.  (Such as 768 byte packets.)
  262.  *
  263.  * Interrupt-only endpoints are less functional than bulk endpoints, for
  264.  * example by not supporting queueing or not handling buffers that are
  265.  * larger than the endpoint's maxpacket size.  They may also treat data
  266.  * toggle differently.
  267.  *
  268.  * Control endpoints ... after getting a setup() callback, the driver queues
  269.  * one response (even if it would be zero length).  That enables the
  270.  * status ack, after transfering data as specified in the response.  Setup
  271.  * functions may return negative error codes to generate protocol stalls.
  272.  * (Note that some USB device controllers disallow protocol stall responses
  273.  * in some cases.)  When control responses are deferred (the response is
  274.  * written after the setup callback returns), then usb_ep_set_halt() may be
  275.  * used on ep0 to trigger protocol stalls.  Depending on the controller,
  276.  * it may not be possible to trigger a status-stage protocol stall when the
  277.  * data stage is over, that is, from within the response's completion
  278.  * routine.
  279.  *
  280.  * For periodic endpoints, like interrupt or isochronous ones, the usb host
  281.  * arranges to poll once per interval, and the gadget driver usually will
  282.  * have queued some data to transfer at that time.
  283.  *
  284.  * Returns zero, or a negative error code.  Endpoints that are not enabled
  285.  * report errors; errors will also be
  286.  * reported when the usb peripheral is disconnected.
  287.  */
  288. static inline int usb_ep_queue(struct usb_ep *ep,
  289.                    struct usb_request *req, gfp_t gfp_flags)
  290. {
  291.     return ep->ops->queue(ep, req, gfp_flags);
  292. }
  293.  
  294. /**
  295.  * usb_ep_dequeue - dequeues (cancels, unlinks) an I/O request from an endpoint
  296.  * @ep:the endpoint associated with the request
  297.  * @req:the request being canceled
  298.  *
  299.  * if the request is still active on the endpoint, it is dequeued and its
  300.  * completion routine is called (with status -ECONNRESET); else a negative
  301.  * error code is returned.
  302.  *
  303.  * note that some hardware can't clear out write fifos (to unlink the request
  304.  * at the head of the queue) except as part of disconnecting from usb.  such
  305.  * restrictions prevent drivers from supporting configuration changes,
  306.  * even to configuration zero (a "chapter 9" requirement).
  307.  */
  308. static inline int usb_ep_dequeue(struct usb_ep *ep, struct usb_request *req)
  309. {
  310.     return ep->ops->dequeue(ep, req);
  311. }
  312.  
  313. /**
  314.  * usb_ep_set_halt - sets the endpoint halt feature.
  315.  * @ep: the non-isochronous endpoint being stalled
  316.  *
  317.  * Use this to stall an endpoint, perhaps as an error report.
  318.  * Except for control endpoints,
  319.  * the endpoint stays halted (will not stream any data) until the host
  320.  * clears this feature; drivers may need to empty the endpoint's request
  321.  * queue first, to make sure no inappropriate transfers happen.
  322.  *
  323.  * Note that while an endpoint CLEAR_FEATURE will be invisible to the
  324.  * gadget driver, a SET_INTERFACE will not be.  To reset endpoints for the
  325.  * current altsetting, see usb_ep_clear_halt().  When switching altsettings,
  326.  * it's simplest to use usb_ep_enable() or usb_ep_disable() for the endpoints.
  327.  *
  328.  * Returns zero, or a negative error code.  On success, this call sets
  329.  * underlying hardware state that blocks data transfers.
  330.  * Attempts to halt IN endpoints will fail (returning -EAGAIN) if any
  331.  * transfer requests are still queued, or if the controller hardware
  332.  * (usually a FIFO) still holds bytes that the host hasn't collected.
  333.  */
  334. static inline int usb_ep_set_halt(struct usb_ep *ep)
  335. {
  336.     return ep->ops->set_halt(ep, 1);
  337. }
  338.  
  339. /**
  340.  * usb_ep_clear_halt - clears endpoint halt, and resets toggle
  341.  * @ep:the bulk or interrupt endpoint being reset
  342.  *
  343.  * Use this when responding to the standard usb "set interface" request,
  344.  * for endpoints that aren't reconfigured, after clearing any other state
  345.  * in the endpoint's i/o queue.
  346.  *
  347.  * Returns zero, or a negative error code.  On success, this call clears
  348.  * the underlying hardware state reflecting endpoint halt and data toggle.
  349.  * Note that some hardware can't support this request (like pxa2xx_udc),
  350.  * and accordingly can't correctly implement interface altsettings.
  351.  */
  352. static inline int usb_ep_clear_halt(struct usb_ep *ep)
  353. {
  354.     return ep->ops->set_halt(ep, 0);
  355. }
  356.  
  357. /**
  358.  * usb_ep_set_wedge - sets the halt feature and ignores clear requests
  359.  * @ep: the endpoint being wedged
  360.  *
  361.  * Use this to stall an endpoint and ignore CLEAR_FEATURE(HALT_ENDPOINT)
  362.  * requests. If the gadget driver clears the halt status, it will
  363.  * automatically unwedge the endpoint.
  364.  *
  365.  * Returns zero on success, else negative errno.
  366.  */
  367. static inline int
  368. usb_ep_set_wedge(struct usb_ep *ep)
  369. {
  370.     if (ep->ops->set_wedge)
  371.         return ep->ops->set_wedge(ep);
  372.     else
  373.         return ep->ops->set_halt(ep, 1);
  374. }
  375.  
  376. /**
  377.  * usb_ep_fifo_status - returns number of bytes in fifo, or error
  378.  * @ep: the endpoint whose fifo status is being checked.
  379.  *
  380.  * FIFO endpoints may have "unclaimed data" in them in certain cases,
  381.  * such as after aborted transfers.  Hosts may not have collected all
  382.  * the IN data written by the gadget driver (and reported by a request
  383.  * completion).  The gadget driver may not have collected all the data
  384.  * written OUT to it by the host.  Drivers that need precise handling for
  385.  * fault reporting or recovery may need to use this call.
  386.  *
  387.  * This returns the number of such bytes in the fifo, or a negative
  388.  * errno if the endpoint doesn't use a FIFO or doesn't support such
  389.  * precise handling.
  390.  */
  391. static inline int usb_ep_fifo_status(struct usb_ep *ep)
  392. {
  393.     if (ep->ops->fifo_status)
  394.         return ep->ops->fifo_status(ep);
  395.     else
  396.         return -EOPNOTSUPP;
  397. }
  398.  
  399. /**
  400.  * usb_ep_fifo_flush - flushes contents of a fifo
  401.  * @ep: the endpoint whose fifo is being flushed.
  402.  *
  403.  * This call may be used to flush the "unclaimed data" that may exist in
  404.  * an endpoint fifo after abnormal transaction terminations.  The call
  405.  * must never be used except when endpoint is not being used for any
  406.  * protocol translation.
  407.  */
  408. static inline void usb_ep_fifo_flush(struct usb_ep *ep)
  409. {
  410.     if (ep->ops->fifo_flush)
  411.         ep->ops->fifo_flush(ep);
  412. }
  413.  
  414.  
  415. /*-------------------------------------------------------------------------*/
  416.  
  417. struct usb_gadget;
  418.  
  419. /* the rest of the api to the controller hardware: device operations,
  420.  * which don't involve endpoints (or i/o).
  421.  */
  422. struct usb_gadget_ops {
  423.     int    (*get_frame)(struct usb_gadget *);
  424.     int    (*wakeup)(struct usb_gadget *);
  425.     int    (*set_selfpowered) (struct usb_gadget *, int is_selfpowered);
  426.     int    (*vbus_session) (struct usb_gadget *, int is_active);
  427.     int    (*vbus_draw) (struct usb_gadget *, unsigned mA);
  428.     int    (*pullup) (struct usb_gadget *, int is_on);
  429.     int    (*ioctl)(struct usb_gadget *,
  430.                 unsigned code, unsigned long param);
  431. };
  432.  
  433. /**
  434.  * struct usb_gadget - represents a usb slave device
  435.  * @ops: Function pointers used to access hardware-specific operations.
  436.  * @ep0: Endpoint zero, used when reading or writing responses to
  437.  *    driver setup() requests
  438.  * @ep_list: List of other endpoints supported by the device.
  439.  * @speed: Speed of current connection to USB host.
  440.  * @is_dualspeed: True if the controller supports both high and full speed
  441.  *    operation.  If it does, the gadget driver must also support both.
  442.  * @is_otg: True if the USB device port uses a Mini-AB jack, so that the
  443.  *    gadget driver must provide a USB OTG descriptor.
  444.  * @is_a_peripheral: False unless is_otg, the "A" end of a USB cable
  445.  *    is in the Mini-AB jack, and HNP has been used to switch roles
  446.  *    so that the "A" device currently acts as A-Peripheral, not A-Host.
  447.  * @a_hnp_support: OTG device feature flag, indicating that the A-Host
  448.  *    supports HNP at this port.
  449.  * @a_alt_hnp_support: OTG device feature flag, indicating that the A-Host
  450.  *    only supports HNP on a different root port.
  451.  * @b_hnp_enable: OTG device feature flag, indicating that the A-Host
  452.  *    enabled HNP support.
  453.  * @name: Identifies the controller hardware type.  Used in diagnostics
  454.  *    and sometimes configuration.
  455.  * @dev: Driver model state for this abstract device.
  456.  *
  457.  * Gadgets have a mostly-portable "gadget driver" implementing device
  458.  * functions, handling all usb configurations and interfaces.  Gadget
  459.  * drivers talk to hardware-specific code indirectly, through ops vectors.
  460.  * That insulates the gadget driver from hardware details, and packages
  461.  * the hardware endpoints through generic i/o queues.  The "usb_gadget"
  462.  * and "usb_ep" interfaces provide that insulation from the hardware.
  463.  *
  464.  * Except for the driver data, all fields in this structure are
  465.  * read-only to the gadget driver.  That driver data is part of the
  466.  * "driver model" infrastructure in 2.6 (and later) kernels, and for
  467.  * earlier systems is grouped in a similar structure that's not known
  468.  * to the rest of the kernel.
  469.  *
  470.  * Values of the three OTG device feature flags are updated before the
  471.  * setup() call corresponding to USB_REQ_SET_CONFIGURATION, and before
  472.  * driver suspend() calls.  They are valid only when is_otg, and when the
  473.  * device is acting as a B-Peripheral (so is_a_peripheral is false).
  474.  */
  475. struct usb_gadget {
  476.     /* readonly to gadget driver */
  477.     const struct usb_gadget_ops    *ops;
  478.     struct usb_ep            *ep0;
  479.     struct list_head        ep_list;    /* of usb_ep */
  480.     enum usb_device_speed        speed;
  481.     unsigned            is_dualspeed:1;
  482.     unsigned            is_otg:1;
  483.     unsigned            is_a_peripheral:1;
  484.     unsigned            b_hnp_enable:1;
  485.     unsigned            a_hnp_support:1;
  486.     unsigned            a_alt_hnp_support:1;
  487.     const char            *name;
  488.     struct device            dev;
  489. };
  490.  
  491. static inline void set_gadget_data(struct usb_gadget *gadget, void *data)
  492.     { dev_set_drvdata(&gadget->dev, data); }
  493. static inline void *get_gadget_data(struct usb_gadget *gadget)
  494.     { return dev_get_drvdata(&gadget->dev); }
  495.  
  496. /* iterates the non-control endpoints; 'tmp' is a struct usb_ep pointer */
  497. #define gadget_for_each_ep(tmp,gadget) \
  498.     list_for_each_entry(tmp, &(gadget)->ep_list, ep_list)
  499.  
  500.  
  501. /**
  502.  * gadget_is_dualspeed - return true iff the hardware handles high speed
  503.  * @g: controller that might support both high and full speeds
  504.  */
  505. static inline int gadget_is_dualspeed(struct usb_gadget *g)
  506. {
  507. #ifdef CONFIG_USB_GADGET_DUALSPEED
  508.     /* runtime test would check "g->is_dualspeed" ... that might be
  509.      * useful to work around hardware bugs, but is mostly pointless
  510.      */
  511.     return 1;
  512. #else
  513.     return 0;
  514. #endif
  515. }
  516.  
  517. /**
  518.  * gadget_is_otg - return true iff the hardware is OTG-ready
  519.  * @g: controller that might have a Mini-AB connector
  520.  *
  521.  * This is a runtime test, since kernels with a USB-OTG stack sometimes
  522.  * run on boards which only have a Mini-B (or Mini-A) connector.
  523.  */
  524. static inline int gadget_is_otg(struct usb_gadget *g)
  525. {
  526. #ifdef CONFIG_USB_OTG
  527.     return g->is_otg;
  528. #else
  529.     return 0;
  530. #endif
  531. }
  532.  
  533. /**
  534.  * usb_gadget_frame_number - returns the current frame number
  535.  * @gadget: controller that reports the frame number
  536.  *
  537.  * Returns the usb frame number, normally eleven bits from a SOF packet,
  538.  * or negative errno if this device doesn't support this capability.
  539.  */
  540. static inline int usb_gadget_frame_number(struct usb_gadget *gadget)
  541. {
  542.     return gadget->ops->get_frame(gadget);
  543. }
  544.  
  545. /**
  546.  * usb_gadget_wakeup - tries to wake up the host connected to this gadget
  547.  * @gadget: controller used to wake up the host
  548.  *
  549.  * Returns zero on success, else negative error code if the hardware
  550.  * doesn't support such attempts, or its support has not been enabled
  551.  * by the usb host.  Drivers must return device descriptors that report
  552.  * their ability to support this, or hosts won't enable it.
  553.  *
  554.  * This may also try to use SRP to wake the host and start enumeration,
  555.  * even if OTG isn't otherwise in use.  OTG devices may also start
  556.  * remote wakeup even when hosts don't explicitly enable it.
  557.  */
  558. static inline int usb_gadget_wakeup(struct usb_gadget *gadget)
  559. {
  560.     if (!gadget->ops->wakeup)
  561.         return -EOPNOTSUPP;
  562.     return gadget->ops->wakeup(gadget);
  563. }
  564.  
  565. /**
  566.  * usb_gadget_set_selfpowered - sets the device selfpowered feature.
  567.  * @gadget:the device being declared as self-powered
  568.  *
  569.  * this affects the device status reported by the hardware driver
  570.  * to reflect that it now has a local power supply.
  571.  *
  572.  * returns zero on success, else negative errno.
  573.  */
  574. static inline int usb_gadget_set_selfpowered(struct usb_gadget *gadget)
  575. {
  576.     if (!gadget->ops->set_selfpowered)
  577.         return -EOPNOTSUPP;
  578.     return gadget->ops->set_selfpowered(gadget, 1);
  579. }
  580.  
  581. /**
  582.  * usb_gadget_clear_selfpowered - clear the device selfpowered feature.
  583.  * @gadget:the device being declared as bus-powered
  584.  *
  585.  * this affects the device status reported by the hardware driver.
  586.  * some hardware may not support bus-powered operation, in which
  587.  * case this feature's value can never change.
  588.  *
  589.  * returns zero on success, else negative errno.
  590.  */
  591. static inline int usb_gadget_clear_selfpowered(struct usb_gadget *gadget)
  592. {
  593.     if (!gadget->ops->set_selfpowered)
  594.         return -EOPNOTSUPP;
  595.     return gadget->ops->set_selfpowered(gadget, 0);
  596. }
  597.  
  598. /**
  599.  * usb_gadget_vbus_connect - Notify controller that VBUS is powered
  600.  * @gadget:The device which now has VBUS power.
  601.  *
  602.  * This call is used by a driver for an external transceiver (or GPIO)
  603.  * that detects a VBUS power session starting.  Common responses include
  604.  * resuming the controller, activating the D+ (or D-) pullup to let the
  605.  * host detect that a USB device is attached, and starting to draw power
  606.  * (8mA or possibly more, especially after SET_CONFIGURATION).
  607.  *
  608.  * Returns zero on success, else negative errno.
  609.  */
  610. static inline int usb_gadget_vbus_connect(struct usb_gadget *gadget)
  611. {
  612.     if (!gadget->ops->vbus_session)
  613.         return -EOPNOTSUPP;
  614.     return gadget->ops->vbus_session(gadget, 1);
  615. }
  616.  
  617. /**
  618.  * usb_gadget_vbus_draw - constrain controller's VBUS power usage
  619.  * @gadget:The device whose VBUS usage is being described
  620.  * @mA:How much current to draw, in milliAmperes.  This should be twice
  621.  *    the value listed in the configuration descriptor bMaxPower field.
  622.  *
  623.  * This call is used by gadget drivers during SET_CONFIGURATION calls,
  624.  * reporting how much power the device may consume.  For example, this
  625.  * could affect how quickly batteries are recharged.
  626.  *
  627.  * Returns zero on success, else negative errno.
  628.  */
  629. static inline int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned mA)
  630. {
  631.     if (!gadget->ops->vbus_draw)
  632.         return -EOPNOTSUPP;
  633.     return gadget->ops->vbus_draw(gadget, mA);
  634. }
  635.  
  636. /**
  637.  * usb_gadget_vbus_disconnect - notify controller about VBUS session end
  638.  * @gadget:the device whose VBUS supply is being described
  639.  *
  640.  * This call is used by a driver for an external transceiver (or GPIO)
  641.  * that detects a VBUS power session ending.  Common responses include
  642.  * reversing everything done in usb_gadget_vbus_connect().
  643.  *
  644.  * Returns zero on success, else negative errno.
  645.  */
  646. static inline int usb_gadget_vbus_disconnect(struct usb_gadget *gadget)
  647. {
  648.     if (!gadget->ops->vbus_session)
  649.         return -EOPNOTSUPP;
  650.     return gadget->ops->vbus_session(gadget, 0);
  651. }
  652.  
  653. /**
  654.  * usb_gadget_connect - software-controlled connect to USB host
  655.  * @gadget:the peripheral being connected
  656.  *
  657.  * Enables the D+ (or potentially D-) pullup.  The host will start
  658.  * enumerating this gadget when the pullup is active and a VBUS session
  659.  * is active (the link is powered).  This pullup is always enabled unless
  660.  * usb_gadget_disconnect() has been used to disable it.
  661.  *
  662.  * Returns zero on success, else negative errno.
  663.  */
  664. static inline int usb_gadget_connect(struct usb_gadget *gadget)
  665. {
  666.     if (!gadget->ops->pullup)
  667.         return -EOPNOTSUPP;
  668.     return gadget->ops->pullup(gadget, 1);
  669. }
  670.  
  671. /**
  672.  * usb_gadget_disconnect - software-controlled disconnect from USB host
  673.  * @gadget:the peripheral being disconnected
  674.  *
  675.  * Disables the D+ (or potentially D-) pullup, which the host may see
  676.  * as a disconnect (when a VBUS session is active).  Not all systems
  677.  * support software pullup controls.
  678.  *
  679.  * This routine may be used during the gadget driver bind() call to prevent
  680.  * the peripheral from ever being visible to the USB host, unless later
  681.  * usb_gadget_connect() is called.  For example, user mode components may
  682.  * need to be activated before the system can talk to hosts.
  683.  *
  684.  * Returns zero on success, else negative errno.
  685.  */
  686. static inline int usb_gadget_disconnect(struct usb_gadget *gadget)
  687. {
  688.     if (!gadget->ops->pullup)
  689.         return -EOPNOTSUPP;
  690.     return gadget->ops->pullup(gadget, 0);
  691. }
  692.  
  693.  
  694. /*-------------------------------------------------------------------------*/
  695.  
  696. /**
  697.  * struct usb_gadget_driver - driver for usb 'slave' devices
  698.  * @function: String describing the gadget's function
  699.  * @speed: Highest speed the driver handles.
  700.  * @bind: Invoked when the driver is bound to a gadget, usually
  701.  *    after registering the driver.
  702.  *    At that point, ep0 is fully initialized, and ep_list holds
  703.  *    the currently-available endpoints.
  704.  *    Called in a context that permits sleeping.
  705.  * @setup: Invoked for ep0 control requests that aren't handled by
  706.  *    the hardware level driver. Most calls must be handled by
  707.  *    the gadget driver, including descriptor and configuration
  708.  *    management.  The 16 bit members of the setup data are in
  709.  *    USB byte order. Called in_interrupt; this may not sleep.  Driver
  710.  *    queues a response to ep0, or returns negative to stall.
  711.  * @disconnect: Invoked after all transfers have been stopped,
  712.  *    when the host is disconnected.  May be called in_interrupt; this
  713.  *    may not sleep.  Some devices can't detect disconnect, so this might
  714.  *    not be called except as part of controller shutdown.
  715.  * @unbind: Invoked when the driver is unbound from a gadget,
  716.  *    usually from rmmod (after a disconnect is reported).
  717.  *    Called in a context that permits sleeping.
  718.  * @suspend: Invoked on USB suspend.  May be called in_interrupt.
  719.  * @resume: Invoked on USB resume.  May be called in_interrupt.
  720.  * @driver: Driver model state for this driver.
  721.  *
  722.  * Devices are disabled till a gadget driver successfully bind()s, which
  723.  * means the driver will handle setup() requests needed to enumerate (and
  724.  * meet "chapter 9" requirements) then do some useful work.
  725.  *
  726.  * If gadget->is_otg is true, the gadget driver must provide an OTG
  727.  * descriptor during enumeration, or else fail the bind() call.  In such
  728.  * cases, no USB traffic may flow until both bind() returns without
  729.  * having called usb_gadget_disconnect(), and the USB host stack has
  730.  * initialized.
  731.  *
  732.  * Drivers use hardware-specific knowledge to configure the usb hardware.
  733.  * endpoint addressing is only one of several hardware characteristics that
  734.  * are in descriptors the ep0 implementation returns from setup() calls.
  735.  *
  736.  * Except for ep0 implementation, most driver code shouldn't need change to
  737.  * run on top of different usb controllers.  It'll use endpoints set up by
  738.  * that ep0 implementation.
  739.  *
  740.  * The usb controller driver handles a few standard usb requests.  Those
  741.  * include set_address, and feature flags for devices, interfaces, and
  742.  * endpoints (the get_status, set_feature, and clear_feature requests).
  743.  *
  744.  * Accordingly, the driver's setup() callback must always implement all
  745.  * get_descriptor requests, returning at least a device descriptor and
  746.  * a configuration descriptor.  Drivers must make sure the endpoint
  747.  * descriptors match any hardware constraints. Some hardware also constrains
  748.  * other descriptors. (The pxa250 allows only configurations 1, 2, or 3).
  749.  *
  750.  * The driver's setup() callback must also implement set_configuration,
  751.  * and should also implement set_interface, get_configuration, and
  752.  * get_interface.  Setting a configuration (or interface) is where
  753.  * endpoints should be activated or (config 0) shut down.
  754.  *
  755.  * (Note that only the default control endpoint is supported.  Neither
  756.  * hosts nor devices generally support control traffic except to ep0.)
  757.  *
  758.  * Most devices will ignore USB suspend/resume operations, and so will
  759.  * not provide those callbacks.  However, some may need to change modes
  760.  * when the host is not longer directing those activities.  For example,
  761.  * local controls (buttons, dials, etc) may need to be re-enabled since
  762.  * the (remote) host can't do that any longer; or an error state might
  763.  * be cleared, to make the device behave identically whether or not
  764.  * power is maintained.
  765.  */
  766. struct usb_gadget_driver {
  767.     char            *function;
  768.     enum usb_device_speed    speed;
  769.     int            (*bind)(struct usb_gadget *);
  770.     void            (*unbind)(struct usb_gadget *);
  771.     int            (*setup)(struct usb_gadget *,
  772.                     const struct usb_ctrlrequest *);
  773.     void            (*disconnect)(struct usb_gadget *);
  774.     void            (*suspend)(struct usb_gadget *);
  775.     void            (*resume)(struct usb_gadget *);
  776.  
  777.     /* FIXME support safe rmmod */
  778.     struct device_driver    driver;
  779. };
  780.  
  781.  
  782.  
  783. /*-------------------------------------------------------------------------*/
  784.  
  785. /* driver modules register and unregister, as usual.
  786.  * these calls must be made in a context that can sleep.
  787.  *
  788.  * these will usually be implemented directly by the hardware-dependent
  789.  * usb bus interface driver, which will only support a single driver.
  790.  */
  791.  
  792. /**
  793.  * usb_gadget_register_driver - register a gadget driver
  794.  * @driver:the driver being registered
  795.  *
  796.  * Call this in your gadget driver's module initialization function,
  797.  * to tell the underlying usb controller driver about your driver.
  798.  * The driver's bind() function will be called to bind it to a
  799.  * gadget before this registration call returns.  It's expected that
  800.  * the bind() functions will be in init sections.
  801.  * This function must be called in a context that can sleep.
  802.  */
  803. int usb_gadget_register_driver(struct usb_gadget_driver *driver);
  804.  
  805. /**
  806.  * usb_gadget_unregister_driver - unregister a gadget driver
  807.  * @driver:the driver being unregistered
  808.  *
  809.  * Call this in your gadget driver's module cleanup function,
  810.  * to tell the underlying usb controller that your driver is
  811.  * going away.  If the controller is connected to a USB host,
  812.  * it will first disconnect().  The driver is also requested
  813.  * to unbind() and clean up any device state, before this procedure
  814.  * finally returns.  It's expected that the unbind() functions
  815.  * will in in exit sections, so may not be linked in some kernels.
  816.  * This function must be called in a context that can sleep.
  817.  */
  818. int usb_gadget_unregister_driver(struct usb_gadget_driver *driver);
  819.  
  820. /*-------------------------------------------------------------------------*/
  821.  
  822. /* utility to simplify dealing with string descriptors */
  823.  
  824. /**
  825.  * struct usb_string - wraps a C string and its USB id
  826.  * @id:the (nonzero) ID for this string
  827.  * @s:the string, in UTF-8 encoding
  828.  *
  829.  * If you're using usb_gadget_get_string(), use this to wrap a string
  830.  * together with its ID.
  831.  */
  832. struct usb_string {
  833.     u8            id;
  834.     const char        *s;
  835. };
  836.  
  837. /**
  838.  * struct usb_gadget_strings - a set of USB strings in a given language
  839.  * @language:identifies the strings' language (0x0409 for en-us)
  840.  * @strings:array of strings with their ids
  841.  *
  842.  * If you're using usb_gadget_get_string(), use this to wrap all the
  843.  * strings for a given language.
  844.  */
  845. struct usb_gadget_strings {
  846.     u16            language;    /* 0x0409 for en-us */
  847.     struct usb_string    *strings;
  848. };
  849.  
  850. /* put descriptor for string with that id into buf (buflen >= 256) */
  851. int usb_gadget_get_string(struct usb_gadget_strings *table, int id, u8 *buf);
  852.  
  853. /*-------------------------------------------------------------------------*/
  854.  
  855. /* utility to simplify managing config descriptors */
  856.  
  857. /* write vector of descriptors into buffer */
  858. int usb_descriptor_fillbuf(void *, unsigned,
  859.         const struct usb_descriptor_header **);
  860.  
  861. /* build config descriptor from single descriptor vector */
  862. int usb_gadget_config_buf(const struct usb_config_descriptor *config,
  863.     void *buf, unsigned buflen, const struct usb_descriptor_header **desc);
  864.  
  865. /* copy a NULL-terminated vector of descriptors */
  866. struct usb_descriptor_header **usb_copy_descriptors(
  867.         struct usb_descriptor_header **);
  868.  
  869. /* return copy of endpoint descriptor given original descriptor set */
  870. struct usb_endpoint_descriptor *usb_find_endpoint(
  871.     struct usb_descriptor_header **src,
  872.     struct usb_descriptor_header **copy,
  873.     struct usb_endpoint_descriptor *match);
  874.  
  875. /**
  876.  * usb_free_descriptors - free descriptors returned by usb_copy_descriptors()
  877.  * @v: vector of descriptors
  878.  */
  879. static inline void usb_free_descriptors(struct usb_descriptor_header **v)
  880. {
  881.     kfree(v);
  882. }
  883.  
  884. /*-------------------------------------------------------------------------*/
  885.  
  886. /* utility wrapping a simple endpoint selection policy */
  887.  
  888. extern struct usb_ep *usb_ep_autoconfig(struct usb_gadget *,
  889.             struct usb_endpoint_descriptor *) __devinit;
  890.  
  891. extern void usb_ep_autoconfig_reset(struct usb_gadget *) __devinit;
  892.  
  893. #endif /* __LINUX_USB_GADGET_H */
  894.