usb_gadget.h.rej

linux得一些常用命令,以及linux环境下的c编程

+  * 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 transfering 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.
+  *
+  * 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, int gfp_flags)
+ {
+ 	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.
+  *
+  * 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_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);
+ }
+ 
+ 
+ /*-------------------------------------------------------------------------*/
+ 
+ struct usb_gadget;
+ 
+ /* the rest of the api to the controller hardware: device operations,
+  * which don't involve endpoints (or i/o).
+  */
+ struct usb_gadget_ops {
+ 	int	(*get_frame)(struct usb_gadget *);
+ 	int	(*wakeup)(struct usb_gadget *);
+ 	int	(*set_selfpowered) (struct usb_gadget *, int is_selfpowered);
+ 	int	(*vbus_session) (struct usb_gadget *, int is_active);
+ 	int	(*vbus_draw) (struct usb_gadget *, unsigned mA);
+ 	int	(*pullup) (struct usb_gadget *, int is_on);
+ 	int	(*ioctl)(struct usb_gadget *,
+ 				unsigned code, unsigned long param);
+ };
+ 
+ /**
+  * struct usb_gadget - represents a usb slave device
+  * @ops: Function pointers used to access hardware-specific operations.
+  * @ep0: Endpoint zero, used when reading or writing responses to
+  * 	driver setup() requests
+  * @ep_list: List of other endpoints supported by the device.
+  * @speed: Speed of current connection to USB host.
+  * @is_dualspeed: True if the controller supports both high and full speed
+  *	operation.  If it does, the gadget driver must also support both.
+  * @is_otg: True if the USB device port uses a Mini-AB jack, so that the
+  *	gadget driver must provide a USB OTG descriptor.
+  * @is_a_peripheral: False unless is_otg, the "A" end of a USB cable
+  *	is in the Mini-AB jack, and HNP has been used to switch roles
+  *	so that the "A" device currently acts as A-Peripheral, not A-Host.
+  * @a_hnp_support: OTG device feature flag, indicating that the A-Host
+  *	supports HNP at this port.
+  * @a_alt_hnp_support: OTG device feature flag, indicating that the A-Host
+  *	only supports HNP on a different root port.
+  * @b_hnp_enable: OTG device feature flag, indicating that the A-Host
+  *	enabled HNP support.
+  * @name: Identifies the controller hardware type.  Used in diagnostics
+  * 	and sometimes configuration.
+  * @dev: Driver model state for this abstract device.
+  *
+  * Gadgets have a mostly-portable "gadget driver" implementing device
+  * functions, handling all usb configurations and interfaces.  Gadget
+  * drivers talk to hardware-specific code indirectly, through ops vectors.
+  * That insulates the gadget driver from hardware details, and packages
+  * the hardware endpoints through generic i/o queues.  The "usb_gadget"
+  * and "usb_ep" interfaces provide that insulation from the hardware.
+  *
+  * Except for the driver data, all fields in this structure are
+  * read-only to the gadget driver.  That driver data is part of the
+  * "driver model" infrastructure in 2.6 (and later) kernels, and for
+  * earlier systems is grouped in a similar structure that's not known
+  * to the rest of the kernel.
+  *
+  * Values of the three OTG device feature flags are updated before the
+  * setup() call corresponding to USB_REQ_SET_CONFIGURATION, and before
+  * driver suspend() calls.  They are valid only when is_otg, and when the
+  * device is acting as a B-Peripheral (so is_a_peripheral is false).
+  */
+ struct usb_gadget {
+ 	/* readonly to gadget driver */
+ 	const struct usb_gadget_ops	*ops;
+ 	struct usb_ep			*ep0;
+ 	struct list_head		ep_list;	/* of usb_ep */
+ 	enum usb_device_speed		speed;
+ 	unsigned			is_dualspeed:1;
+ 	unsigned			is_otg:1;
+ 	unsigned			is_a_peripheral:1;
+ 	unsigned			b_hnp_enable:1;
+ 	unsigned			a_hnp_support:1;
+ 	unsigned			a_alt_hnp_support:1;
+ 	const char			*name;
+ 
+ 	struct device			dev;
+ };
+ 
+ static inline void set_gadget_data (struct usb_gadget *gadget, void *data)
+ 	{ gadget->dev.driver_data = data; }
+ static inline void *get_gadget_data (struct usb_gadget *gadget)
+ 	{ return gadget->dev.driver_data; }
+ 
+ 
+ /* iterates the non-control endpoints; 'tmp' is a struct usb_ep pointer */
+ #define gadget_for_each_ep(tmp,gadget) \
+ 	list_for_each_entry(tmp, &(gadget)->ep_list, ep_list)
+ 
+ #ifndef list_for_each_entry
+ /* not available in 2.4.18 */
+ #define list_for_each_entry(pos, head, member)				\
+ 	for (pos = list_entry((head)->next, typeof(*pos), member),	\
+ 		     prefetch(pos->member.next);			\
+ 	     &pos->member != (head); 					\
+ 	     pos = list_entry(pos->member.next, typeof(*pos), member),	\
+ 		     prefetch(pos->member.next))
+ #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