ChangeSet 1.1315.8.20, 2003/09/17 17:06:26-07:00, david-b@pacbell.net
[PATCH] USB: psdocs fails for usbgadget
It updates the "gadget" kerneldoc, removing some (new) warnings, and
showing some fields it hadn't previously been showing (due to
limitations in docproc). Plus it adds a bit of information about recent
changes (new drivers).
Documentation/DocBook/gadget.tmpl | 27 ++++++++++++++++++++++++++-
include/linux/usb_gadget.h | 30 ++++++++++++++++--------------
2 files changed, 42 insertions(+), 15 deletions(-)
diff -Nru a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl
--- a/Documentation/DocBook/gadget.tmpl Fri Sep 19 17:10:51 2003
+++ b/Documentation/DocBook/gadget.tmpl Fri Sep 19 17:10:51 2003
@@ -468,6 +468,15 @@
information.
+For users of Intel's PXA 2xx series processors,
+a pxa2xx_udc driver is available.
+
+
+At this writing, there are people at work on drivers in
+this framework for several other USB device controllers,
+with plans to make many of them be widely available.
+
+
A partial USB simulator,
@@ -500,7 +509,7 @@
There's an ethernet gadget
driver, which implements one of the most useful
-Communications Device Class models.
+Communications Device Class (CDC) models.
One of the standards for cable modem interoperability even
specifies the use of this ethernet model as one of two
mandatory options.
@@ -509,6 +518,11 @@
It provides access to a network where the gadget's CPU is one host,
which could easily be bridging, routing, or firewalling
access to other networks.
+Since some hardware can't fully implement the CDC Ethernet
+requirements, this driver also implements a "good parts only"
+subset of CDC Ethernet.
+(That subset doesn't advertise itself as CDC Ethernet,
+to avoid creating problems.)
There is also support for user mode gadget drivers,
@@ -520,6 +534,17 @@
develop and debug user mode drivers, so that once a robust
controller driver is available many applications for it
won't require new kernel mode software.
+
+
+There's a USB Mass Storage class driver, which provides
+a different solution for interoperability with systems such
+as MS-Windows and MacOS.
+That File-backed Storage driver uses a
+file or block device as backing store for a drive,
+like the loop driver.
+The USB host uses the BBB, CB, or CBI versions of the mass
+storage class specification, using transparent SCSI commands
+to access the data from the backing store.
Support for other kinds of gadget is expected to
diff -Nru a/include/linux/usb_gadget.h b/include/linux/usb_gadget.h
--- a/include/linux/usb_gadget.h Fri Sep 19 17:10:51 2003
+++ b/include/linux/usb_gadget.h Fri Sep 19 17:10:51 2003
@@ -72,9 +72,9 @@
unsigned length;
dma_addr_t dma;
- unsigned no_interrupt : 1,
- zero : 1,
- short_not_ok : 1;
+ unsigned no_interrupt:1;
+ unsigned zero:1;
+ unsigned short_not_ok:1;
void (*complete)(struct usb_ep *ep,
struct usb_request *req);
@@ -122,9 +122,11 @@
/**
* 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, as
- * configured when the endpoint was enabled.
+ * @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.
*
@@ -138,7 +140,7 @@
const char *name;
const struct usb_ep_ops *ops;
struct list_head ep_list;
- unsigned maxpacket : 16;
+ unsigned maxpacket:16;
};
/*-------------------------------------------------------------------------*/
@@ -443,18 +445,21 @@
/**
* 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.
* @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. They
- * also have a hardware-specific driver (accessed through ops vectors),
- * which insulates the gadget driver from hardware details and packages
- * the hardware endpoints through generic i/o queues.
+ * 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
@@ -469,10 +474,6 @@
struct list_head ep_list; /* of usb_ep */
enum usb_device_speed speed;
const char *name;
-
- /* use this to allocate dma-coherent buffers or set up
- * dma mappings. or print diagnostics, etc.
- */
struct device dev;
};
@@ -576,6 +577,7 @@
* Called in a context that permits sleeping.
* @suspend: Invoked on USB suspend. May be called in_interrupt.
* @resume: Invoked on USB resume. May be called in_interrupt.
+ * @driver: Driver model state for this driver.
*
* Devices are disabled till a gadget driver successfully bind()s, which
* means the driver will handle setup() requests needed to enumerate (and