On Tue, May 31, 2016 at 02:58:33PM +0300, Felipe Balbi wrote:
> instead of defining all functions as static inlines,
> let's move them to udc-core and export them with
> EXPORT_SYMBOL_GPL, that way we can make sure that
> only GPL drivers will use them.
>
One concern, current some other modules may use usb gadget symbol,
like drivers/power/isp1704_charger.c uses usb_gadget_connect.
If udc-core is built as module, it may has some build issues.
> As a side effect, it'll be nicer to add tracepoints
> to the gadget API.
Why it is a side effect?
Peter
>
> Signed-off-by: Felipe Balbi <felipe.balbi@xxxxxxxxxxxxxxx>
> ---
> drivers/usb/gadget/udc/udc-core.c | 573 ++++++++++++++++++++++++++++++++++++++
> include/linux/usb/gadget.h | 569 ++-----------------------------------
> 2 files changed, 597 insertions(+), 545 deletions(-)
>
> diff --git a/drivers/usb/gadget/udc/udc-core.c b/drivers/usb/gadget/udc/udc-core.c
> index 6e8300d6a737..d2f28bb6dbda 100644
> --- a/drivers/usb/gadget/udc/udc-core.c
> +++ b/drivers/usb/gadget/udc/udc-core.c
> @@ -59,6 +59,579 @@ static int udc_bind_to_driver(struct usb_udc *udc,
>
> /* ------------------------------------------------------------------------- */
>
> +/**
> + * usb_ep_set_maxpacket_limit - set maximum packet size limit for endpoint
> + * @ep:the endpoint being configured
> + * @maxpacket_limit:value of maximum packet size limit
> + *
> + * This function should be used only in UDC drivers to initialize endpoint
> + * (usually in probe function).
> + */
> +void usb_ep_set_maxpacket_limit(struct usb_ep *ep,
> + unsigned maxpacket_limit)
> +{
> + ep->maxpacket_limit = maxpacket_limit;
> + ep->maxpacket = maxpacket_limit;
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_set_maxpacket_limit);
> +
> +/**
> + * usb_ep_enable - configure endpoint, making it usable
> + * @ep:the endpoint being configured. may not be the endpoint named "ep0".
> + * drivers discover endpoints through the ep_list of a usb_gadget.
> + *
> + * When configurations are set, or when interface settings change, the driver
> + * will enable or disable the relevant endpoints. while it is enabled, an
> + * endpoint may be used for i/o until the driver receives a disconnect() from
> + * the host or until the endpoint is disabled.
> + *
> + * the ep0 implementation (which calls this routine) must ensure that the
> + * hardware capabilities of each endpoint match the descriptor provided
> + * for it. for example, an endpoint named "ep2in-bulk" would be usable
> + * for interrupt transfers as well as bulk, but it likely couldn't be used
> + * for iso transfers or for endpoint 14. some endpoints are fully
> + * configurable, with more generic names like "ep-a". (remember that for
> + * USB, "in" means "towards the USB master".)
> + *
> + * returns zero, or a negative error code.
> + */
> +int usb_ep_enable(struct usb_ep *ep)
> +{
> + int ret;
> +
> + if (ep->enabled)
> + return 0;
> +
> + ret = ep->ops->enable(ep, ep->desc);
> + if (ret)
> + return ret;
> +
> + ep->enabled = true;
> +
> + return 0;
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_enable);
> +
> +/**
> + * usb_ep_disable - endpoint is no longer usable
> + * @ep:the endpoint being unconfigured. may not be the endpoint named "ep0".
> + *
> + * no other task may be using this endpoint when this is called.
> + * any pending and uncompleted requests will complete with status
> + * indicating disconnect (-ESHUTDOWN) before this call returns.
> + * gadget drivers must call usb_ep_enable() again before queueing
> + * requests to the endpoint.
> + *
> + * returns zero, or a negative error code.
> + */
> +int usb_ep_disable(struct usb_ep *ep)
> +{
> + int ret;
> +
> + if (!ep->enabled)
> + return 0;
> +
> + ret = ep->ops->disable(ep);
> + if (ret)
> + return ret;
> +
> + ep->enabled = false;
> +
> + return 0;
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_disable);
> +
> +/**
> + * usb_ep_alloc_request - allocate a request object to use with this endpoint
> + * @ep:the endpoint to be used with with the request
> + * @gfp_flags:GFP_* flags to use
> + *
> + * Request objects must be allocated with this call, since they normally
> + * need controller-specific setup and may even need endpoint-specific
> + * resources such as allocation of DMA descriptors.
> + * Requests may be submitted with usb_ep_queue(), and receive a single
> + * completion callback. Free requests with usb_ep_free_request(), when
> + * they are no longer needed.
> + *
> + * Returns the request, or null if one could not be allocated.
> + */
> +struct usb_request *usb_ep_alloc_request(struct usb_ep *ep,
> + gfp_t gfp_flags)
> +{
> + return ep->ops->alloc_request(ep, gfp_flags);
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_alloc_request);
> +
> +/**
> + * usb_ep_free_request - frees a request object
> + * @ep:the endpoint associated with the request
> + * @req:the request being freed
> + *
> + * Reverses the effect of usb_ep_alloc_request().
> + * Caller guarantees the request is not queued, and that it will
> + * no longer be requeued (or otherwise used).
> + */
> +void usb_ep_free_request(struct usb_ep *ep,
> + struct usb_request *req)
> +{
> + ep->ops->free_request(ep, req);
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_free_request);
> +
> +/**
> + * usb_ep_queue - queues (submits) an I/O request to an endpoint.
> + * @ep:the endpoint associated with the request
> + * @req:the request being submitted
> + * @gfp_flags: GFP_* flags to use in case the lower level driver couldn't
> + * pre-allocate all necessary memory with the request.
> + *
> + * This tells the device controller to perform the specified request through
> + * that endpoint (reading or writing a buffer). When the request completes,
> + * including being canceled by usb_ep_dequeue(), the request's completion
> + * routine is called to return the request to the driver. Any endpoint
> + * (except control endpoints like ep0) may have more than one transfer
> + * request queued; they complete in FIFO order. Once a gadget driver
> + * submits a request, that request may not be examined or modified until it
> + * is given back to that driver through the completion callback.
> + *
> + * Each request is turned into one or more packets. The controller driver
> + * never merges adjacent requests into the same packet. OUT transfers
> + * will sometimes use data that's already buffered in the hardware.
> + * Drivers can rely on the fact that the first byte of the request's buffer
> + * always corresponds to the first byte of some USB packet, for both
> + * IN and OUT transfers.
> + *
> + * Bulk endpoints can queue any amount of data; the transfer is packetized
> + * automatically. The last packet will be short if the request doesn't fill it
> + * out completely. Zero length packets (ZLPs) should be avoided in portable
> + * protocols since not all usb hardware can successfully handle zero length
> + * packets. (ZLPs may be explicitly written, and may be implicitly written if
> + * the request 'zero' flag is set.) Bulk endpoints may also be used
> + * for interrupt transfers; but the reverse is not true, and some endpoints
> + * won't support every interrupt transfer. (Such as 768 byte packets.)
> + *
> + * Interrupt-only endpoints are less functional than bulk endpoints, for
> + * example by not supporting queueing or not handling buffers that are
> + * larger than the endpoint's maxpacket size. They may also treat data
> + * toggle differently.
> + *
> + * Control endpoints ... after getting a setup() callback, the driver queues
> + * one response (even if it would be zero length). That enables the
> + * status ack, after transferring data as specified in the response. Setup
> + * functions may return negative error codes to generate protocol stalls.
> + * (Note that some USB device controllers disallow protocol stall responses
> + * in some cases.) When control responses are deferred (the response is
> + * written after the setup callback returns), then usb_ep_set_halt() may be
> + * used on ep0 to trigger protocol stalls. Depending on the controller,
> + * it may not be possible to trigger a status-stage protocol stall when the
> + * data stage is over, that is, from within the response's completion
> + * routine.
> + *
> + * For periodic endpoints, like interrupt or isochronous ones, the usb host
> + * 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
> + * report errors; errors will also be
> + * reported when the usb peripheral is disconnected.
> + */
> +int usb_ep_queue(struct usb_ep *ep,
> + struct usb_request *req, gfp_t gfp_flags)
> +{
> + if (WARN_ON_ONCE(!ep->enabled && ep->address))
> + return -ESHUTDOWN;
> +
> + return ep->ops->queue(ep, req, gfp_flags);
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_queue);
> +
> +/**
> + * usb_ep_dequeue - dequeues (cancels, unlinks) an I/O request from an endpoint
> + * @ep:the endpoint associated with the request
> + * @req:the request being canceled
> + *
> + * If the request is still active on the endpoint, it is dequeued and its
> + * completion routine is called (with status -ECONNRESET); else a negative
> + * error code is returned. This is guaranteed to happen before the call to
> + * usb_ep_dequeue() returns.
> + *
> + * Note that some hardware can't clear out write fifos (to unlink the request
> + * at the head of the queue) except as part of disconnecting from usb. Such
> + * restrictions prevent drivers from supporting configuration changes,
> + * even to configuration zero (a "chapter 9" requirement).
> + */
> +int usb_ep_dequeue(struct usb_ep *ep, struct usb_request *req)
> +{
> + return ep->ops->dequeue(ep, req);
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_dequeue);
> +
> +/**
> + * usb_ep_set_halt - sets the endpoint halt feature.
> + * @ep: the non-isochronous endpoint being stalled
> + *
> + * Use this to stall an endpoint, perhaps as an error report.
> + * Except for control endpoints,
> + * the endpoint stays halted (will not stream any data) until the host
> + * 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.
> + * Attempts to halt IN endpoints will fail (returning -EAGAIN) if any
> + * transfer requests are still queued, or if the controller hardware
> + * (usually a FIFO) still holds bytes that the host hasn't collected.
> + */
> +int usb_ep_set_halt(struct usb_ep *ep)
> +{
> + return ep->ops->set_halt(ep, 1);
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_set_halt);
> +
> +/**
> + * 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,
> + * 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
> + * 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.
> + */
> +int usb_ep_clear_halt(struct usb_ep *ep)
> +{
> + return ep->ops->set_halt(ep, 0);
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_clear_halt);
> +
> +/**
> + * usb_ep_set_wedge - sets the halt feature and ignores clear requests
> + * @ep: the endpoint being wedged
> + *
> + * Use this to stall an endpoint and ignore CLEAR_FEATURE(HALT_ENDPOINT)
> + * requests. If the gadget driver clears the halt status, it will
> + * automatically unwedge the endpoint.
> + *
> + * Returns zero on success, else negative errno.
> + */
> +int usb_ep_set_wedge(struct usb_ep *ep)
> +{
> + if (ep->ops->set_wedge)
> + return ep->ops->set_wedge(ep);
> + else
> + return ep->ops->set_halt(ep, 1);
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_set_wedge);
> +
> +/**
> + * usb_ep_fifo_status - returns number of bytes in fifo, or error
> + * @ep: the endpoint whose fifo status is being checked.
> + *
> + * FIFO endpoints may have "unclaimed data" in them in certain cases,
> + * such as after aborted transfers. Hosts may not have collected all
> + * the IN data written by the gadget driver (and reported by a request
> + * completion). The gadget driver may not have collected all the data
> + * written OUT to it by the host. Drivers that need precise handling for
> + * fault reporting or recovery may need to use this call.
> + *
> + * This returns the number of such bytes in the fifo, or a negative
> + * errno if the endpoint doesn't use a FIFO or doesn't support such
> + * precise handling.
> + */
> +int usb_ep_fifo_status(struct usb_ep *ep)
> +{
> + if (ep->ops->fifo_status)
> + return ep->ops->fifo_status(ep);
> + else
> + return -EOPNOTSUPP;
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_fifo_status);
> +
> +/**
> + * usb_ep_fifo_flush - flushes contents of a fifo
> + * @ep: the endpoint whose fifo is being flushed.
> + *
> + * This call may be used to flush the "unclaimed data" that may exist in
> + * an endpoint fifo after abnormal transaction terminations. The call
> + * must never be used except when endpoint is not being used for any
> + * protocol translation.
> + */
> +void usb_ep_fifo_flush(struct usb_ep *ep)
> +{
> + if (ep->ops->fifo_flush)
> + ep->ops->fifo_flush(ep);
> +}
> +EXPORT_SYMBOL_GPL(usb_ep_fifo_flush);
> +
> +/* ------------------------------------------------------------------------- */
> +
> +/**
> + * usb_gadget_frame_number - returns the current frame number
> + * @gadget: controller that reports the frame number
> + *
> + * Returns the usb frame number, normally eleven bits from a SOF packet,
> + * or negative errno if this device doesn't support this capability.
> + */
> +int usb_gadget_frame_number(struct usb_gadget *gadget)
> +{
> + return gadget->ops->get_frame(gadget);
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_frame_number);
> +
> +/**
> + * usb_gadget_wakeup - tries to wake up the host connected to this gadget
> + * @gadget: controller used to wake up the host
> + *
> + * Returns zero on success, else negative error code if the hardware
> + * doesn't support such attempts, or its support has not been enabled
> + * by the usb host. Drivers must return device descriptors that report
> + * their ability to support this, or hosts won't enable it.
> + *
> + * This may also try to use SRP to wake the host and start enumeration,
> + * even if OTG isn't otherwise in use. OTG devices may also start
> + * remote wakeup even when hosts don't explicitly enable it.
> + */
> +int usb_gadget_wakeup(struct usb_gadget *gadget)
> +{
> + if (!gadget->ops->wakeup)
> + return -EOPNOTSUPP;
> + return gadget->ops->wakeup(gadget);
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_wakeup);
> +
> +/**
> + * usb_gadget_set_selfpowered - sets the device selfpowered feature.
> + * @gadget:the device being declared as self-powered
> + *
> + * this affects the device status reported by the hardware driver
> + * to reflect that it now has a local power supply.
> + *
> + * returns zero on success, else negative errno.
> + */
> +int usb_gadget_set_selfpowered(struct usb_gadget *gadget)
> +{
> + if (!gadget->ops->set_selfpowered)
> + return -EOPNOTSUPP;
> + return gadget->ops->set_selfpowered(gadget, 1);
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_set_selfpowered);
> +
> +/**
> + * usb_gadget_clear_selfpowered - clear the device selfpowered feature.
> + * @gadget:the device being declared as bus-powered
> + *
> + * this affects the device status reported by the hardware driver.
> + * some hardware may not support bus-powered operation, in which
> + * case this feature's value can never change.
> + *
> + * returns zero on success, else negative errno.
> + */
> +int usb_gadget_clear_selfpowered(struct usb_gadget *gadget)
> +{
> + if (!gadget->ops->set_selfpowered)
> + return -EOPNOTSUPP;
> + return gadget->ops->set_selfpowered(gadget, 0);
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_clear_selfpowered);
> +
> +/**
> + * usb_gadget_vbus_connect - Notify controller that VBUS is powered
> + * @gadget:The device which now has VBUS power.
> + * Context: can sleep
> + *
> + * This call is used by a driver for an external transceiver (or GPIO)
> + * that detects a VBUS power session starting. Common responses include
> + * resuming the controller, activating the D+ (or D-) pullup to let the
> + * host detect that a USB device is attached, and starting to draw power
> + * (8mA or possibly more, especially after SET_CONFIGURATION).
> + *
> + * Returns zero on success, else negative errno.
> + */
> +int usb_gadget_vbus_connect(struct usb_gadget *gadget)
> +{
> + if (!gadget->ops->vbus_session)
> + return -EOPNOTSUPP;
> + return gadget->ops->vbus_session(gadget, 1);
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_vbus_connect);
> +
> +/**
> + * usb_gadget_vbus_draw - constrain controller's VBUS power usage
> + * @gadget:The device whose VBUS usage is being described
> + * @mA:How much current to draw, in milliAmperes. This should be twice
> + * the value listed in the configuration descriptor bMaxPower field.
> + *
> + * This call is used by gadget drivers during SET_CONFIGURATION calls,
> + * reporting how much power the device may consume. For example, this
> + * could affect how quickly batteries are recharged.
> + *
> + * Returns zero on success, else negative errno.
> + */
> +int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned mA)
> +{
> + if (!gadget->ops->vbus_draw)
> + return -EOPNOTSUPP;
> + return gadget->ops->vbus_draw(gadget, mA);
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_vbus_draw);
> +
> +/**
> + * usb_gadget_vbus_disconnect - notify controller about VBUS session end
> + * @gadget:the device whose VBUS supply is being described
> + * Context: can sleep
> + *
> + * This call is used by a driver for an external transceiver (or GPIO)
> + * that detects a VBUS power session ending. Common responses include
> + * reversing everything done in usb_gadget_vbus_connect().
> + *
> + * Returns zero on success, else negative errno.
> + */
> +int usb_gadget_vbus_disconnect(struct usb_gadget *gadget)
> +{
> + if (!gadget->ops->vbus_session)
> + return -EOPNOTSUPP;
> + return gadget->ops->vbus_session(gadget, 0);
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_vbus_disconnect);
> +
> +/**
> + * usb_gadget_connect - software-controlled connect to USB host
> + * @gadget:the peripheral being connected
> + *
> + * Enables the D+ (or potentially D-) pullup. The host will start
> + * enumerating this gadget when the pullup is active and a VBUS session
> + * is active (the link is powered). This pullup is always enabled unless
> + * usb_gadget_disconnect() has been used to disable it.
> + *
> + * Returns zero on success, else negative errno.
> + */
> +int usb_gadget_connect(struct usb_gadget *gadget)
> +{
> + int ret;
> +
> + if (!gadget->ops->pullup)
> + return -EOPNOTSUPP;
> +
> + if (gadget->deactivated) {
> + /*
> + * If gadget is deactivated we only save new state.
> + * Gadget will be connected automatically after activation.
> + */
> + gadget->connected = true;
> + return 0;
> + }
> +
> + ret = gadget->ops->pullup(gadget, 1);
> + if (!ret)
> + gadget->connected = 1;
> + return ret;
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_connect);
> +
> +/**
> + * usb_gadget_disconnect - software-controlled disconnect from USB host
> + * @gadget:the peripheral being disconnected
> + *
> + * Disables the D+ (or potentially D-) pullup, which the host may see
> + * as a disconnect (when a VBUS session is active). Not all systems
> + * support software pullup controls.
> + *
> + * Returns zero on success, else negative errno.
> + */
> +int usb_gadget_disconnect(struct usb_gadget *gadget)
> +{
> + int ret;
> +
> + if (!gadget->ops->pullup)
> + return -EOPNOTSUPP;
> +
> + if (gadget->deactivated) {
> + /*
> + * If gadget is deactivated we only save new state.
> + * Gadget will stay disconnected after activation.
> + */
> + gadget->connected = false;
> + return 0;
> + }
> +
> + ret = gadget->ops->pullup(gadget, 0);
> + if (!ret)
> + gadget->connected = 0;
> + return ret;
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_disconnect);
> +
> +/**
> + * usb_gadget_deactivate - deactivate function which is not ready to work
> + * @gadget: the peripheral being deactivated
> + *
> + * This routine may be used during the gadget driver bind() call to prevent
> + * the peripheral from ever being visible to the USB host, unless later
> + * usb_gadget_activate() is called. For example, user mode components may
> + * need to be activated before the system can talk to hosts.
> + *
> + * Returns zero on success, else negative errno.
> + */
> +int usb_gadget_deactivate(struct usb_gadget *gadget)
> +{
> + int ret;
> +
> + if (gadget->deactivated)
> + return 0;
> +
> + if (gadget->connected) {
> + ret = usb_gadget_disconnect(gadget);
> + if (ret)
> + return ret;
> + /*
> + * If gadget was being connected before deactivation, we want
> + * to reconnect it in usb_gadget_activate().
> + */
> + gadget->connected = true;
> + }
> + gadget->deactivated = true;
> +
> + return 0;
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_deactivate);
> +
> +/**
> + * usb_gadget_activate - activate function which is not ready to work
> + * @gadget: the peripheral being activated
> + *
> + * This routine activates gadget which was previously deactivated with
> + * usb_gadget_deactivate() call. It calls usb_gadget_connect() if needed.
> + *
> + * Returns zero on success, else negative errno.
> + */
> +int usb_gadget_activate(struct usb_gadget *gadget)
> +{
> + if (!gadget->deactivated)
> + return 0;
> +
> + gadget->deactivated = false;
> +
> + /*
> + * If gadget has been connected before deactivation, or became connected
> + * while it was being deactivated, we call usb_gadget_connect().
> + */
> + if (gadget->connected)
> + return usb_gadget_connect(gadget);
> +
> + return 0;
> +}
> +EXPORT_SYMBOL_GPL(usb_gadget_activate);
> +
> +/* ------------------------------------------------------------------------- */
> +
> #ifdef CONFIG_HAS_DMA
>
> int usb_gadget_map_request_by_dev(struct device *dev,
> diff --git a/include/linux/usb/gadget.h b/include/linux/usb/gadget.h
> index 457651bf45b0..89e4a8de68e6 100644
> --- a/include/linux/usb/gadget.h
> +++ b/include/linux/usb/gadget.h
> @@ -228,307 +228,18 @@ struct usb_ep {
>
> /*-------------------------------------------------------------------------*/
>
> -/**
> - * usb_ep_set_maxpacket_limit - set maximum packet size limit for endpoint
> - * @ep:the endpoint being configured
> - * @maxpacket_limit:value of maximum packet size limit
> - *
> - * This function should be used only in UDC drivers to initialize endpoint
> - * (usually in probe function).
> - */
> -static inline void usb_ep_set_maxpacket_limit(struct usb_ep *ep,
> - unsigned maxpacket_limit)
> -{
> - ep->maxpacket_limit = maxpacket_limit;
> - ep->maxpacket = maxpacket_limit;
> -}
> -
> -/**
> - * usb_ep_enable - configure endpoint, making it usable
> - * @ep:the endpoint being configured. may not be the endpoint named "ep0".
> - * drivers discover endpoints through the ep_list of a usb_gadget.
> - *
> - * When configurations are set, or when interface settings change, the driver
> - * will enable or disable the relevant endpoints. while it is enabled, an
> - * endpoint may be used for i/o until the driver receives a disconnect() from
> - * the host or until the endpoint is disabled.
> - *
> - * the ep0 implementation (which calls this routine) must ensure that the
> - * hardware capabilities of each endpoint match the descriptor provided
> - * for it. for example, an endpoint named "ep2in-bulk" would be usable
> - * for interrupt transfers as well as bulk, but it likely couldn't be used
> - * for iso transfers or for endpoint 14. some endpoints are fully
> - * configurable, with more generic names like "ep-a". (remember that for
> - * USB, "in" means "towards the USB master".)
> - *
> - * returns zero, or a negative error code.
> - */
> -static inline int usb_ep_enable(struct usb_ep *ep)
> -{
> - int ret;
> -
> - if (ep->enabled)
> - return 0;
> -
> - ret = ep->ops->enable(ep, ep->desc);
> - if (ret)
> - return ret;
> -
> - ep->enabled = true;
> -
> - return 0;
> -}
> -
> -/**
> - * usb_ep_disable - endpoint is no longer usable
> - * @ep:the endpoint being unconfigured. may not be the endpoint named "ep0".
> - *
> - * no other task may be using this endpoint when this is called.
> - * any pending and uncompleted requests will complete with status
> - * indicating disconnect (-ESHUTDOWN) before this call returns.
> - * gadget drivers must call usb_ep_enable() again before queueing
> - * requests to the endpoint.
> - *
> - * returns zero, or a negative error code.
> - */
> -static inline int usb_ep_disable(struct usb_ep *ep)
> -{
> - int ret;
> -
> - if (!ep->enabled)
> - return 0;
> -
> - ret = ep->ops->disable(ep);
> - if (ret)
> - return ret;
> -
> - ep->enabled = false;
> -
> - return 0;
> -}
> -
> -/**
> - * usb_ep_alloc_request - allocate a request object to use with this endpoint
> - * @ep:the endpoint to be used with with the request
> - * @gfp_flags:GFP_* flags to use
> - *
> - * Request objects must be allocated with this call, since they normally
> - * need controller-specific setup and may even need endpoint-specific
> - * resources such as allocation of DMA descriptors.
> - * Requests may be submitted with usb_ep_queue(), and receive a single
> - * completion callback. Free requests with usb_ep_free_request(), when
> - * they are no longer needed.
> - *
> - * Returns the request, or null if one could not be allocated.
> - */
> -static inline struct usb_request *usb_ep_alloc_request(struct usb_ep *ep,
> - gfp_t gfp_flags)
> -{
> - return ep->ops->alloc_request(ep, gfp_flags);
> -}
> -
> -/**
> - * usb_ep_free_request - frees a request object
> - * @ep:the endpoint associated with the request
> - * @req:the request being freed
> - *
> - * Reverses the effect of usb_ep_alloc_request().
> - * Caller guarantees the request is not queued, and that it will
> - * no longer be requeued (or otherwise used).
> - */
> -static inline void usb_ep_free_request(struct usb_ep *ep,
> - struct usb_request *req)
> -{
> - ep->ops->free_request(ep, req);
> -}
> -
> -/**
> - * usb_ep_queue - queues (submits) an I/O request to an endpoint.
> - * @ep:the endpoint associated with the request
> - * @req:the request being submitted
> - * @gfp_flags: GFP_* flags to use in case the lower level driver couldn't
> - * pre-allocate all necessary memory with the request.
> - *
> - * This tells the device controller to perform the specified request through
> - * that endpoint (reading or writing a buffer). When the request completes,
> - * including being canceled by usb_ep_dequeue(), the request's completion
> - * routine is called to return the request to the driver. Any endpoint
> - * (except control endpoints like ep0) may have more than one transfer
> - * request queued; they complete in FIFO order. Once a gadget driver
> - * submits a request, that request may not be examined or modified until it
> - * is given back to that driver through the completion callback.
> - *
> - * Each request is turned into one or more packets. The controller driver
> - * never merges adjacent requests into the same packet. OUT transfers
> - * will sometimes use data that's already buffered in the hardware.
> - * Drivers can rely on the fact that the first byte of the request's buffer
> - * always corresponds to the first byte of some USB packet, for both
> - * IN and OUT transfers.
> - *
> - * Bulk endpoints can queue any amount of data; the transfer is packetized
> - * automatically. The last packet will be short if the request doesn't fill it
> - * out completely. Zero length packets (ZLPs) should be avoided in portable
> - * protocols since not all usb hardware can successfully handle zero length
> - * packets. (ZLPs may be explicitly written, and may be implicitly written if
> - * the request 'zero' flag is set.) Bulk endpoints may also be used
> - * for interrupt transfers; but the reverse is not true, and some endpoints
> - * won't support every interrupt transfer. (Such as 768 byte packets.)
> - *
> - * Interrupt-only endpoints are less functional than bulk endpoints, for
> - * example by not supporting queueing or not handling buffers that are
> - * larger than the endpoint's maxpacket size. They may also treat data
> - * toggle differently.
> - *
> - * Control endpoints ... after getting a setup() callback, the driver queues
> - * one response (even if it would be zero length). That enables the
> - * status ack, after transferring data as specified in the response. Setup
> - * functions may return negative error codes to generate protocol stalls.
> - * (Note that some USB device controllers disallow protocol stall responses
> - * in some cases.) When control responses are deferred (the response is
> - * written after the setup callback returns), then usb_ep_set_halt() may be
> - * used on ep0 to trigger protocol stalls. Depending on the controller,
> - * it may not be possible to trigger a status-stage protocol stall when the
> - * data stage is over, that is, from within the response's completion
> - * routine.
> - *
> - * For periodic endpoints, like interrupt or isochronous ones, the usb host
> - * 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
> - * report errors; errors will also be
> - * reported when the usb peripheral is disconnected.
> - */
> -static inline int usb_ep_queue(struct usb_ep *ep,
> - struct usb_request *req, gfp_t gfp_flags)
> -{
> - if (WARN_ON_ONCE(!ep->enabled && ep->address))
> - return -ESHUTDOWN;
> -
> - return ep->ops->queue(ep, req, gfp_flags);
> -}
> -
> -/**
> - * usb_ep_dequeue - dequeues (cancels, unlinks) an I/O request from an endpoint
> - * @ep:the endpoint associated with the request
> - * @req:the request being canceled
> - *
> - * If the request is still active on the endpoint, it is dequeued and its
> - * completion routine is called (with status -ECONNRESET); else a negative
> - * error code is returned. This is guaranteed to happen before the call to
> - * usb_ep_dequeue() returns.
> - *
> - * Note that some hardware can't clear out write fifos (to unlink the request
> - * at the head of the queue) except as part of disconnecting from usb. Such
> - * restrictions prevent drivers from supporting configuration changes,
> - * even to configuration zero (a "chapter 9" requirement).
> - */
> -static inline int usb_ep_dequeue(struct usb_ep *ep, struct usb_request *req)
> -{
> - return ep->ops->dequeue(ep, req);
> -}
> -
> -/**
> - * usb_ep_set_halt - sets the endpoint halt feature.
> - * @ep: the non-isochronous endpoint being stalled
> - *
> - * Use this to stall an endpoint, perhaps as an error report.
> - * Except for control endpoints,
> - * the endpoint stays halted (will not stream any data) until the host
> - * 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.
> - * Attempts to halt IN endpoints will fail (returning -EAGAIN) if any
> - * transfer requests are still queued, or if the controller hardware
> - * (usually a FIFO) still holds bytes that the host hasn't collected.
> - */
> -static inline int usb_ep_set_halt(struct usb_ep *ep)
> -{
> - return ep->ops->set_halt(ep, 1);
> -}
> -
> -/**
> - * 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,
> - * 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
> - * 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)
> -{
> - return ep->ops->set_halt(ep, 0);
> -}
> -
> -/**
> - * usb_ep_set_wedge - sets the halt feature and ignores clear requests
> - * @ep: the endpoint being wedged
> - *
> - * Use this to stall an endpoint and ignore CLEAR_FEATURE(HALT_ENDPOINT)
> - * requests. If the gadget driver clears the halt status, it will
> - * automatically unwedge the endpoint.
> - *
> - * Returns zero on success, else negative errno.
> - */
> -static inline int
> -usb_ep_set_wedge(struct usb_ep *ep)
> -{
> - if (ep->ops->set_wedge)
> - return ep->ops->set_wedge(ep);
> - else
> - return ep->ops->set_halt(ep, 1);
> -}
> -
> -/**
> - * usb_ep_fifo_status - returns number of bytes in fifo, or error
> - * @ep: the endpoint whose fifo status is being checked.
> - *
> - * FIFO endpoints may have "unclaimed data" in them in certain cases,
> - * such as after aborted transfers. Hosts may not have collected all
> - * the IN data written by the gadget driver (and reported by a request
> - * completion). The gadget driver may not have collected all the data
> - * written OUT to it by the host. Drivers that need precise handling for
> - * fault reporting or recovery may need to use this call.
> - *
> - * This returns the number of such bytes in the fifo, or a negative
> - * errno if the endpoint doesn't use a FIFO or doesn't support such
> - * precise handling.
> - */
> -static inline int usb_ep_fifo_status(struct usb_ep *ep)
> -{
> - if (ep->ops->fifo_status)
> - return ep->ops->fifo_status(ep);
> - else
> - return -EOPNOTSUPP;
> -}
> -
> -/**
> - * usb_ep_fifo_flush - flushes contents of a fifo
> - * @ep: the endpoint whose fifo is being flushed.
> - *
> - * This call may be used to flush the "unclaimed data" that may exist in
> - * an endpoint fifo after abnormal transaction terminations. The call
> - * must never be used except when endpoint is not being used for any
> - * protocol translation.
> - */
> -static inline void usb_ep_fifo_flush(struct usb_ep *ep)
> -{
> - if (ep->ops->fifo_flush)
> - ep->ops->fifo_flush(ep);
> -}
> -
> +void usb_ep_set_maxpacket_limit(struct usb_ep *ep, unsigned maxpacket_limit);
> +int usb_ep_enable(struct usb_ep *ep);
> +int usb_ep_disable(struct usb_ep *ep);
> +struct usb_request *usb_ep_alloc_request(struct usb_ep *ep, gfp_t gfp_flags);
> +void usb_ep_free_request(struct usb_ep *ep, struct usb_request *req);
> +int usb_ep_queue(struct usb_ep *ep, struct usb_request *req, gfp_t gfp_flags);
> +int usb_ep_dequeue(struct usb_ep *ep, struct usb_request *req);
> +int usb_ep_set_halt(struct usb_ep *ep);
> +int usb_ep_clear_halt(struct usb_ep *ep);
> +int usb_ep_set_wedge(struct usb_ep *ep);
> +int usb_ep_fifo_status(struct usb_ep *ep);
> +void usb_ep_fifo_flush(struct usb_ep *ep);
>
> /*-------------------------------------------------------------------------*/
>
> @@ -760,251 +471,19 @@ static inline int gadget_is_otg(struct usb_gadget *g)
> #endif
> }
>
> -/**
> - * usb_gadget_frame_number - returns the current frame number
> - * @gadget: controller that reports the frame number
> - *
> - * Returns the usb frame number, normally eleven bits from a SOF packet,
> - * or negative errno if this device doesn't support this capability.
> - */
> -static inline int usb_gadget_frame_number(struct usb_gadget *gadget)
> -{
> - return gadget->ops->get_frame(gadget);
> -}
> -
> -/**
> - * usb_gadget_wakeup - tries to wake up the host connected to this gadget
> - * @gadget: controller used to wake up the host
> - *
> - * Returns zero on success, else negative error code if the hardware
> - * doesn't support such attempts, or its support has not been enabled
> - * by the usb host. Drivers must return device descriptors that report
> - * their ability to support this, or hosts won't enable it.
> - *
> - * This may also try to use SRP to wake the host and start enumeration,
> - * even if OTG isn't otherwise in use. OTG devices may also start
> - * remote wakeup even when hosts don't explicitly enable it.
> - */
> -static inline int usb_gadget_wakeup(struct usb_gadget *gadget)
> -{
> - if (!gadget->ops->wakeup)
> - return -EOPNOTSUPP;
> - return gadget->ops->wakeup(gadget);
> -}
> -
> -/**
> - * usb_gadget_set_selfpowered - sets the device selfpowered feature.
> - * @gadget:the device being declared as self-powered
> - *
> - * this affects the device status reported by the hardware driver
> - * to reflect that it now has a local power supply.
> - *
> - * returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_set_selfpowered(struct usb_gadget *gadget)
> -{
> - if (!gadget->ops->set_selfpowered)
> - return -EOPNOTSUPP;
> - return gadget->ops->set_selfpowered(gadget, 1);
> -}
> -
> -/**
> - * usb_gadget_clear_selfpowered - clear the device selfpowered feature.
> - * @gadget:the device being declared as bus-powered
> - *
> - * this affects the device status reported by the hardware driver.
> - * some hardware may not support bus-powered operation, in which
> - * case this feature's value can never change.
> - *
> - * returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_clear_selfpowered(struct usb_gadget *gadget)
> -{
> - if (!gadget->ops->set_selfpowered)
> - return -EOPNOTSUPP;
> - return gadget->ops->set_selfpowered(gadget, 0);
> -}
> -
> -/**
> - * usb_gadget_vbus_connect - Notify controller that VBUS is powered
> - * @gadget:The device which now has VBUS power.
> - * Context: can sleep
> - *
> - * This call is used by a driver for an external transceiver (or GPIO)
> - * that detects a VBUS power session starting. Common responses include
> - * resuming the controller, activating the D+ (or D-) pullup to let the
> - * host detect that a USB device is attached, and starting to draw power
> - * (8mA or possibly more, especially after SET_CONFIGURATION).
> - *
> - * Returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_vbus_connect(struct usb_gadget *gadget)
> -{
> - if (!gadget->ops->vbus_session)
> - return -EOPNOTSUPP;
> - return gadget->ops->vbus_session(gadget, 1);
> -}
> -
> -/**
> - * usb_gadget_vbus_draw - constrain controller's VBUS power usage
> - * @gadget:The device whose VBUS usage is being described
> - * @mA:How much current to draw, in milliAmperes. This should be twice
> - * the value listed in the configuration descriptor bMaxPower field.
> - *
> - * This call is used by gadget drivers during SET_CONFIGURATION calls,
> - * reporting how much power the device may consume. For example, this
> - * could affect how quickly batteries are recharged.
> - *
> - * Returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned mA)
> -{
> - if (!gadget->ops->vbus_draw)
> - return -EOPNOTSUPP;
> - return gadget->ops->vbus_draw(gadget, mA);
> -}
> -
> -/**
> - * usb_gadget_vbus_disconnect - notify controller about VBUS session end
> - * @gadget:the device whose VBUS supply is being described
> - * Context: can sleep
> - *
> - * This call is used by a driver for an external transceiver (or GPIO)
> - * that detects a VBUS power session ending. Common responses include
> - * reversing everything done in usb_gadget_vbus_connect().
> - *
> - * Returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_vbus_disconnect(struct usb_gadget *gadget)
> -{
> - if (!gadget->ops->vbus_session)
> - return -EOPNOTSUPP;
> - return gadget->ops->vbus_session(gadget, 0);
> -}
> -
> -/**
> - * usb_gadget_connect - software-controlled connect to USB host
> - * @gadget:the peripheral being connected
> - *
> - * Enables the D+ (or potentially D-) pullup. The host will start
> - * enumerating this gadget when the pullup is active and a VBUS session
> - * is active (the link is powered). This pullup is always enabled unless
> - * usb_gadget_disconnect() has been used to disable it.
> - *
> - * Returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_connect(struct usb_gadget *gadget)
> -{
> - int ret;
> -
> - if (!gadget->ops->pullup)
> - return -EOPNOTSUPP;
> -
> - if (gadget->deactivated) {
> - /*
> - * If gadget is deactivated we only save new state.
> - * Gadget will be connected automatically after activation.
> - */
> - gadget->connected = true;
> - return 0;
> - }
> -
> - ret = gadget->ops->pullup(gadget, 1);
> - if (!ret)
> - gadget->connected = 1;
> - return ret;
> -}
> -
> -/**
> - * usb_gadget_disconnect - software-controlled disconnect from USB host
> - * @gadget:the peripheral being disconnected
> - *
> - * Disables the D+ (or potentially D-) pullup, which the host may see
> - * as a disconnect (when a VBUS session is active). Not all systems
> - * support software pullup controls.
> - *
> - * Returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_disconnect(struct usb_gadget *gadget)
> -{
> - int ret;
> -
> - if (!gadget->ops->pullup)
> - return -EOPNOTSUPP;
> -
> - if (gadget->deactivated) {
> - /*
> - * If gadget is deactivated we only save new state.
> - * Gadget will stay disconnected after activation.
> - */
> - gadget->connected = false;
> - return 0;
> - }
> -
> - ret = gadget->ops->pullup(gadget, 0);
> - if (!ret)
> - gadget->connected = 0;
> - return ret;
> -}
> -
> -/**
> - * usb_gadget_deactivate - deactivate function which is not ready to work
> - * @gadget: the peripheral being deactivated
> - *
> - * This routine may be used during the gadget driver bind() call to prevent
> - * the peripheral from ever being visible to the USB host, unless later
> - * usb_gadget_activate() is called. For example, user mode components may
> - * need to be activated before the system can talk to hosts.
> - *
> - * Returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_deactivate(struct usb_gadget *gadget)
> -{
> - int ret;
> -
> - if (gadget->deactivated)
> - return 0;
> -
> - if (gadget->connected) {
> - ret = usb_gadget_disconnect(gadget);
> - if (ret)
> - return ret;
> - /*
> - * If gadget was being connected before deactivation, we want
> - * to reconnect it in usb_gadget_activate().
> - */
> - gadget->connected = true;
> - }
> - gadget->deactivated = true;
> -
> - return 0;
> -}
> -
> -/**
> - * usb_gadget_activate - activate function which is not ready to work
> - * @gadget: the peripheral being activated
> - *
> - * This routine activates gadget which was previously deactivated with
> - * usb_gadget_deactivate() call. It calls usb_gadget_connect() if needed.
> - *
> - * Returns zero on success, else negative errno.
> - */
> -static inline int usb_gadget_activate(struct usb_gadget *gadget)
> -{
> - if (!gadget->deactivated)
> - return 0;
> -
> - gadget->deactivated = false;
> -
> - /*
> - * If gadget has been connected before deactivation, or became connected
> - * while it was being deactivated, we call usb_gadget_connect().
> - */
> - if (gadget->connected)
> - return usb_gadget_connect(gadget);
> +/*-------------------------------------------------------------------------*/
>
> - return 0;
> -}
> +int usb_gadget_frame_number(struct usb_gadget *gadget);
> +int usb_gadget_wakeup(struct usb_gadget *gadget);
> +int usb_gadget_set_selfpowered(struct usb_gadget *gadget);
> +int usb_gadget_clear_selfpowered(struct usb_gadget *gadget);
> +int usb_gadget_vbus_connect(struct usb_gadget *gadget);
> +int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned mA);
> +int usb_gadget_vbus_disconnect(struct usb_gadget *gadget);
> +int usb_gadget_connect(struct usb_gadget *gadget);
> +int usb_gadget_disconnect(struct usb_gadget *gadget);
> +int usb_gadget_deactivate(struct usb_gadget *gadget);
> +int usb_gadget_activate(struct usb_gadget *gadget);
>
> /*-------------------------------------------------------------------------*/
>
> --
> 2.8.3
>
> ---------------------------------------------------------------------
> Intel Finland Oy
> Registered Address: PL 281, 00181 Helsinki
> Business Identity Code: 0357606 - 4
> Domiciled in Helsinki
>
> This e-mail and any attachments may contain confidential material for
> the sole use of the intended recipient(s). Any review or distribution
> by others is strictly prohibited. If you are not the intended
> recipient, please contact the sender and delete all copies.
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-usb" in
> the body of a message to majordomo@xxxxxxxxxxxxxxx
> More majordomo info at http://vger.kernel.org/majordomo-info.html
--
Best Regards,
Peter Chen
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
