usb_gadget.h.rej

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

***************
*** 0 ****
--- 1,890 ----
+ /*
+  * <linux/usb_gadget.h>
+  *
+  * We call the USB code inside a Linux-based peripheral device a "gadget"
+  * driver, except for the hardware-specific bus glue.  One USB host can
+  * master many USB gadgets, but the gadgets are only slaved to one host.
+  *
+  *
+  * (C) Copyright 2002-2004 by David Brownell
+  * All Rights Reserved.
+  *
+  * This software is licensed under the GNU GPL version 2.
+  */
+ 
+ #ifndef __LINUX_USB_GADGET_H
+ #define __LINUX_USB_GADGET_H
+ 
+ #ifdef __KERNEL__
+ 
+ struct usb_ep;
+ 
+ /**
+  * struct usb_request - describes one i/o request
+  * @buf: Buffer used for data.  Always provide this; some controllers
+  * 	only use PIO, or don't use DMA for some endpoints.
+  * @dma: DMA address corresponding to 'buf'.  If you don't set this
+  * 	field, and the usb controller needs one, it is responsible
+  * 	for mapping and unmapping the buffer.
+  * @length: Length of that data
+  * @no_interrupt: If true, hints that no completion irq is needed.
+  *	Helpful sometimes with deep request queues that are handled
+  *	directly by DMA controllers.
+  * @zero: If true, when writing data, makes the last packet be "short"
+  *     by adding a zero length packet as needed;
+  * @short_not_ok: When reading data, makes short packets be
+  *     treated as errors (queue stops advancing till cleanup).
+  * @complete: Function called when request completes, so this request and
+  *	its buffer may be re-used.
+  *	Reads terminate with a short packet, or when the buffer fills,
+  *	whichever comes first.  When writes terminate, some data bytes
+  *	will usually still be in flight (often in a hardware fifo).
+  *	Errors (for reads or writes) stop the queue from advancing
+  *	until the completion function returns, so that any transfers
+  *	invalidated by the error may first be dequeued.
+  * @context: For use by the completion callback
+  * @list: For use by the gadget driver.
+  * @status: Reports completion code, zero or a negative errno.
+  * 	Normally, faults block the transfer queue from advancing until
+  * 	the completion callback returns.
+  * 	Code "-ESHUTDOWN" indicates completion caused by device disconnect,
+  * 	or when the driver disabled the endpoint.
+  * @actual: Reports bytes transferred to/from the buffer.  For reads (OUT
+  * 	transfers) this may be less than the requested length.  If the
+  * 	short_not_ok flag is set, short reads are treated as errors
+  * 	even when status otherwise indicates successful completion.
+  * 	Note that for writes (IN transfers) some data bytes may still
+  * 	reside in a device-side FIFO when the request is reported as
+  *	complete.
+  *
+  * These are allocated/freed through the endpoint they're used with.  The
+  * hardware's driver can add extra per-request data to the memory it returns,
+  * which often avoids separate memory allocations (potential failures),
+  * later when the request is queued.
+  *
+  * Request flags affect request handling, such as whether a zero length
+  * packet is written (the "zero" flag), whether a short read should be
+  * treated as an error (blocking request queue advance, the "short_not_ok"
+  * flag), or hinting that an interrupt is not required (the "no_interrupt"
+  * flag, for use with deep request queues).
+  *
+  * Bulk endpoints can use any size buffers, and can also be used for interrupt
+  * transfers. interrupt-only endpoints can be much less functional.
+  */
+ 	// NOTE this is analagous to 'struct urb' on the host side,
+ 	// except that it's thinner and promotes more pre-allocation.
+ 
+ struct usb_request {
+ 	void			*buf;
+ 	unsigned		length;
+ 	dma_addr_t		dma;
+ 
+ 	unsigned		no_interrupt:1;
+ 	unsigned		zero:1;
+ 	unsigned		short_not_ok:1;
+ 
+ 	void			(*complete)(struct usb_ep *ep,
+ 					struct usb_request *req);
+ 	void			*context;
+ 	struct list_head	list;
+ 
+ 	int			status;
+ 	unsigned		actual;
+ };
+ 
+ /*-------------------------------------------------------------------------*/
+ 
+ /* endpoint-specific parts of the api to the usb controller hardware.
+  * unlike the urb model, (de)multiplexing layers are not required.
+  * (so this api could slash overhead if used on the host side...)
+  *
+  * note that device side usb controllers commonly differ in how many
+  * endpoints they support, as well as their capabilities.
+  */
+ struct usb_ep_ops {
+ 	int (*enable) (struct usb_ep *ep,
+ 		const struct usb_endpoint_descriptor *desc);
+ 	int (*disable) (struct usb_ep *ep);
+ 
+ 	struct usb_request *(*alloc_request) (struct usb_ep *ep,
+ 		int gfp_flags);
+ 	void (*free_request) (struct usb_ep *ep, struct usb_request *req);
+ 
+ 	void *(*alloc_buffer) (struct usb_ep *ep, unsigned bytes,
+ 		dma_addr_t *dma, int gfp_flags);
+ 	void (*free_buffer) (struct usb_ep *ep, void *buf, dma_addr_t dma,
+ 		unsigned bytes);
+ 	// NOTE:  on 2.6, drivers may also use dma_map() and
+ 	// dma_sync_single_*() to directly manage dma overhead. 
+ 
+ 	int (*queue) (struct usb_ep *ep, struct usb_request *req,
+ 		int gfp_flags);
+ 	int (*dequeue) (struct usb_ep *ep, struct usb_request *req);
+ 
+ 	int (*set_halt) (struct usb_ep *ep, int value);
+ 	int (*fifo_status) (struct usb_ep *ep);
+ 	void (*fifo_flush) (struct usb_ep *ep);
+ };
+ 
+ /**
+  * struct usb_ep - device side representation of USB endpoint
+  * @name:identifier for the endpoint, such as "ep-a" or "ep9in-bulk"
+  * @ops: Function pointers used to access hardware-specific operations.
+  * @ep_list:the gadget's ep_list holds all of its endpoints
+  * @maxpacket:The maximum packet size used on this endpoint.  The initial
+  *	value can sometimes be reduced (hardware allowing), according to
+  *      the endpoint descriptor used to configure the endpoint.
+  * @driver_data:for use by the gadget driver.  all other fields are
+  * 	read-only to gadget drivers.
+  *
+  * the bus controller driver lists all the general purpose endpoints in
+  * gadget->ep_list.  the control endpoint (gadget->ep0) is not in that list,
+  * and is accessed only in response to a driver setup() callback.
+  */
+ struct usb_ep {
+ 	void			*driver_data;
+ 
+ 	const char		*name;
+ 	const struct usb_ep_ops	*ops;
+ 	struct list_head	ep_list;
+ 	unsigned		maxpacket:16;
+ };
+ 
+ /*-------------------------------------------------------------------------*/
+ 
+ /**
+  * 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.
+  * @desc:descriptor for desired behavior.  caller guarantees this pointer
+  * 	remains valid until the endpoint is disabled; the data byte order
+  * 	is little-endian (usb-standard).
+  *
+  * 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, const struct usb_endpoint_descriptor *desc)
+ {
+ 	return ep->ops->enable (ep, desc);
+ }
+ 
+ /**
+  * 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)
+ {
+ 	return ep->ops->disable (ep);
+ }
+ 
+ /**
+  * 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, int 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_alloc_buffer - allocate an I/O buffer
+  * @ep:the endpoint associated with the buffer
+  * @len:length of the desired buffer
+  * @dma:pointer to the buffer's DMA address; must be valid
+  * @gfp_flags:GFP_* flags to use
+  *
+  * Returns a new buffer, or null if one could not be allocated.
+  * The buffer is suitably aligned for dma, if that endpoint uses DMA,
+  * and the caller won't have to care about dma-inconsistency
+  * or any hidden "bounce buffer" mechanism.  No additional per-request
+  * DMA mapping will be required for such buffers.
+  * Free it later with usb_ep_free_buffer().
+  *
+  * You don't need to use this call to allocate I/O buffers unless you
+  * want to make sure drivers don't incur costs for such "bounce buffer"
+  * copies or per-request DMA mappings.
+  */
+ static inline void *
+ usb_ep_alloc_buffer (struct usb_ep *ep, unsigned len, dma_addr_t *dma,
+ 	int gfp_flags)
+ {
+ 	return ep->ops->alloc_buffer (ep, len, dma, gfp_flags);
+ }
+ 
+ /**
+  * usb_ep_free_buffer - frees an i/o buffer
+  * @ep:the endpoint associated with the buffer
+  * @buf:CPU view address of the buffer
+  * @dma:the buffer's DMA address
+  * @len:length of the buffer
+  *
+  * reverses the effect of usb_ep_alloc_buffer().
+  * caller guarantees the buffer will no longer be accessed
+  */
+ static inline void
+ usb_ep_free_buffer (struct usb_ep *ep, void *buf, dma_addr_t dma, unsigned len)
+ {
+ 	ep->ops->free_buffer (ep, buf, dma, len);
+ }
+ 
+ /**
+  * 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