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
9  * (C) Copyright 2002-2004 by David Brownell
14  * Ported to U-Boot by: Thomas Smits <ts.smits@gmail.com> and
29  * struct usb_request - describes one i/o request
45  *	its buffer may be re-used.
48  *	will usually still be in flight (often in a hardware fifo).
57  *	Code "-ESHUTDOWN" indicates completion caused by device disconnect,
64  *	reside in a device-side FIFO when the request is reported as
68  * hardware's driver can add extra per-request data to the memory it returns,
79  * transfers. interrupt-only endpoints can be much less functional.
82  * it's thinner and promotes more pre-allocation.
104 /*-------------------------------------------------------------------------*/
106 /* endpoint-specific parts of the api to the usb controller hardware.
133  * struct usb_ep - device side representation of USB endpoint
134  * @name:identifier for the endpoint, such as "ep-a" or "ep9in-bulk"
135  * @ops: Function pointers used to access hardware-specific operations.
138  *	value can sometimes be reduced (hardware allowing), according to
144  * 	by this EP (0 - 16, actual number is 2^n)
147  *	read-only to gadget drivers.
154  * gadget->ep_list.  the control endpoint (gadget->ep0) is not in that list,
170 /*-------------------------------------------------------------------------*/
173  * usb_ep_set_maxpacket_limit - set maximum packet size limit for endpoint
183 	ep->maxpacket_limit = maxpacket_limit;  in usb_ep_set_maxpacket_limit()
184 	ep->maxpacket = maxpacket_limit;  in usb_ep_set_maxpacket_limit()
188  * usb_ep_enable - configure endpoint, making it usable
193  *	is little-endian (usb-standard).
201  * hardware capabilities of each endpoint match the descriptor provided
202  * for it.  for example, an endpoint named "ep2in-bulk" would be usable
205  * configurable, with more generic names like "ep-a".  (remember that for
213 	return ep->ops->enable(ep, desc);  in usb_ep_enable()
217  * usb_ep_disable - endpoint is no longer usable
222  * indicating disconnect (-ESHUTDOWN) before this call returns.
230 	return ep->ops->disable(ep);  in usb_ep_disable()
234  * usb_ep_alloc_request - allocate a request object to use with this endpoint
239  * need controller-specific setup and may even need endpoint-specific
250 	return ep->ops->alloc_request(ep, gfp_flags);  in usb_ep_alloc_request()
254  * usb_ep_free_request - frees a request object
265 	ep->ops->free_request(ep, req);  in usb_ep_free_request()
269  * usb_ep_queue - queues (submits) an I/O request to an endpoint.
273  *	pre-allocate all necessary memory with the request.
280  * request queued; they complete in FIFO order.  Once a gadget driver
286  * will sometimes use data that's already buffered in the hardware.
294  * protocols since not all usb hardware can successfully handle zero length
300  * Interrupt-only endpoints are less functional than bulk endpoints, for
325 	return ep->ops->queue(ep, req, gfp_flags);  in usb_ep_queue()
329  * usb_ep_dequeue - dequeues (cancels, unlinks) an I/O request from an endpoint
334  * completion routine is called (with status -ECONNRESET); else a negative
337  * note that some hardware can't clear out write fifos (to unlink the request
344 	return ep->ops->dequeue(ep, req);  in usb_ep_dequeue()
348  * usb_ep_set_halt - sets the endpoint halt feature.
349  * @ep: the non-isochronous endpoint being stalled
363  * underlying hardware state that blocks data transfers.
364  * Attempts to halt IN endpoints will fail (returning -EAGAIN) if any
365  * transfer requests are still queued, or if the controller hardware
366  * (usually a FIFO) still holds bytes that the host hasn't collected.
370 	return ep->ops->set_halt(ep, 1);  in usb_ep_set_halt()
374  * usb_ep_clear_halt - clears endpoint halt, and resets toggle
382  * the underlying hardware state reflecting endpoint halt and data toggle.
383  * Note that some hardware can't support this request (like pxa2xx_udc),
388 	return ep->ops->set_halt(ep, 0);  in usb_ep_clear_halt()
392  * usb_ep_fifo_status - returns number of bytes in fifo, or error
393  * @ep: the endpoint whose fifo status is being checked.
395  * FIFO endpoints may have "unclaimed data" in them in certain cases,
402  * This returns the number of such bytes in the fifo, or a negative
403  * errno if the endpoint doesn't use a FIFO or doesn't support such
408 	if (ep->ops->fifo_status)  in usb_ep_fifo_status()
409 		return ep->ops->fifo_status(ep);  in usb_ep_fifo_status()
411 		return -EOPNOTSUPP;  in usb_ep_fifo_status()
415  * usb_ep_fifo_flush - flushes contents of a fifo
416  * @ep: the endpoint whose fifo is being flushed.
419  * an endpoint fifo after abnormal transaction terminations.  The call
425 	if (ep->ops->fifo_flush)  in usb_ep_fifo_flush()
426 		ep->ops->fifo_flush(ep);  in usb_ep_fifo_flush()
430 /*-------------------------------------------------------------------------*/
435 /* the rest of the api to the controller hardware: device operations,
453  * struct usb_gadget - represents a usb slave device
454  * @ops: Function pointers used to access hardware-specific operations.
463  * @is_otg: true if the USB device port uses a Mini-AB jack, so that the
466  *	is in the Mini-AB jack, and HNP has been used to switch roles
467  *	so that the "A" device currently acts as A-Peripheral, not A-Host.
468  * @a_hnp_support: OTG device feature flag, indicating that the A-Host
470  * @a_alt_hnp_support: OTG device feature flag, indicating that the A-Host
472  * @b_hnp_enable: OTG device feature flag, indicating that the A-Host
474  * @name: Identifies the controller hardware type.  Used in diagnostics
480  * Gadgets have a mostly-portable "gadget driver" implementing device
482  * drivers talk to hardware-specific code indirectly, through ops vectors.
483  * That insulates the gadget driver from hardware details, and packages
484  * the hardware endpoints through generic i/o queues.  The "usb_gadget"
485  * and "usb_ep" interfaces provide that insulation from the hardware.
488  * read-only to the gadget driver.  That driver data is part of the
496  * device is acting as a B-Peripheral (so is_a_peripheral is false).
519 	gadget->dev.driver_data = data;  in set_gadget_data()
524 	return gadget->dev.driver_data;  in get_gadget_data()
532 /* iterates the non-control endpoints; 'tmp' is a struct usb_ep pointer */
534 	list_for_each_entry(tmp, &(gadget)->ep_list, ep_list)
538  * gadget_is_dualspeed - return true iff the hardware handles high speed
544 	/* runtime test would check "g->is_dualspeed" ... that might be  in gadget_is_dualspeed()
545 	 * useful to work around hardware bugs, but is mostly pointless  in gadget_is_dualspeed()
554  * gadget_is_otg - return true iff the hardware is OTG-ready
555  * @g: controller that might have a Mini-AB connector
557  * This is a runtime test, since kernels with a USB-OTG stack sometimes
558  * run on boards which only have a Mini-B (or Mini-A) connector.
563 	return g->is_otg;  in gadget_is_otg()
570  * usb_gadget_frame_number - returns the current frame number
578 	return gadget->ops->get_frame(gadget);  in usb_gadget_frame_number()
582  * usb_gadget_wakeup - tries to wake up the host connected to this gadget
585  * Returns zero on success, else negative error code if the hardware
596 	if (!gadget->ops->wakeup)  in usb_gadget_wakeup()
597 		return -EOPNOTSUPP;  in usb_gadget_wakeup()
598 	return gadget->ops->wakeup(gadget);  in usb_gadget_wakeup()
602  * usb_gadget_set_selfpowered - sets the device selfpowered feature.
603  * @gadget:the device being declared as self-powered
605  * this affects the device status reported by the hardware driver
612 	if (!gadget->ops->set_selfpowered)  in usb_gadget_set_selfpowered()
613 		return -EOPNOTSUPP;  in usb_gadget_set_selfpowered()
614 	return gadget->ops->set_selfpowered(gadget, 1);  in usb_gadget_set_selfpowered()
618  * usb_gadget_clear_selfpowered - clear the device selfpowered feature.
619  * @gadget:the device being declared as bus-powered
621  * this affects the device status reported by the hardware driver.
622  * some hardware may not support bus-powered operation, in which
629 	if (!gadget->ops->set_selfpowered)  in usb_gadget_clear_selfpowered()
630 		return -EOPNOTSUPP;  in usb_gadget_clear_selfpowered()
631 	return gadget->ops->set_selfpowered(gadget, 0);  in usb_gadget_clear_selfpowered()
635  * usb_gadget_vbus_connect - Notify controller that VBUS is powered
640  * resuming the controller, activating the D+ (or D-) pullup to let the
648 	if (!gadget->ops->vbus_session)  in usb_gadget_vbus_connect()
649 		return -EOPNOTSUPP;  in usb_gadget_vbus_connect()
650 	return gadget->ops->vbus_session(gadget, 1);  in usb_gadget_vbus_connect()
654  * usb_gadget_vbus_draw - constrain controller's VBUS power usage
667 	if (!gadget->ops->vbus_draw)  in usb_gadget_vbus_draw()
668 		return -EOPNOTSUPP;  in usb_gadget_vbus_draw()
669 	return gadget->ops->vbus_draw(gadget, mA);  in usb_gadget_vbus_draw()
673  * usb_gadget_vbus_disconnect - notify controller about VBUS session end
684 	if (!gadget->ops->vbus_session)  in usb_gadget_vbus_disconnect()
685 		return -EOPNOTSUPP;  in usb_gadget_vbus_disconnect()
686 	return gadget->ops->vbus_session(gadget, 0);  in usb_gadget_vbus_disconnect()
690  * usb_gadget_connect - software-controlled connect to USB host
693  * Enables the D+ (or potentially D-) pullup.  The host will start
702 	if (!gadget->ops->pullup)  in usb_gadget_connect()
703 		return -EOPNOTSUPP;  in usb_gadget_connect()
704 	return gadget->ops->pullup(gadget, 1);  in usb_gadget_connect()
708  * usb_gadget_disconnect - software-controlled disconnect from USB host
711  * Disables the D+ (or potentially D-) pullup, which the host may see
724 	if (!gadget->ops->pullup)  in usb_gadget_disconnect()
725 		return -EOPNOTSUPP;  in usb_gadget_disconnect()
726 	return gadget->ops->pullup(gadget, 0);  in usb_gadget_disconnect()
730 /*-------------------------------------------------------------------------*/
733  * struct usb_gadget_driver - driver for usb 'slave' devices
739  *	the currently-available endpoints.
742  *	the hardware level driver. Most calls must be handled by
763  * If gadget->is_otg is true, the gadget driver must provide an OTG
769  * Drivers use hardware-specific knowledge to configure the usb hardware.
770  * endpoint addressing is only one of several hardware characteristics that
784  * descriptors match any hardware constraints. Some hardware also constrains
798  * local controls (buttons, dials, etc) may need to be re-enabled since
817 /*-------------------------------------------------------------------------*/
822  * these will usually be implemented directly by the hardware-dependent
827  * usb_gadget_register_driver - register a gadget driver
840  * usb_gadget_unregister_driver - unregister a gadget driver
858 /*-------------------------------------------------------------------------*/
863  * struct usb_gadget_strings - a set of USB strings in a given language
864  * @language:identifies the strings' language (0x0409 for en-us)
871 	u16			language;	/* 0x0409 for en-us */
878 /*-------------------------------------------------------------------------*/
890 /*-------------------------------------------------------------------------*/
899 /*-------------------------------------------------------------------------*/
906 /*-------------------------------------------------------------------------*/
912 /*-------------------------------------------------------------------------*/
919 /*-------------------------------------------------------------------------*/