]> err.no Git - linux-2.6/commitdiff
USB: convert usb.h struct usb_device to kernel-doc
authorRandy Dunlap <randy.dunlap@oracle.com>
Thu, 14 Feb 2008 02:33:15 +0000 (18:33 -0800)
committerGreg Kroah-Hartman <gregkh@suse.de>
Fri, 25 Apr 2008 04:16:33 +0000 (21:16 -0700)
Convert struct usb_device to use kernel-doc notation.
Please especially check the @filelist and @usb_classdev descriptions.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
include/linux/usb.h

index 7e31cacfe69cc8239f2d23c0594b781f2df08301..285011d9af1746f350c0214a0315ea885e38aaea 100644 (file)
@@ -341,102 +341,142 @@ struct usb_bus {
 
 struct usb_tt;
 
-/*
+/**
  * struct usb_device - kernel's representation of a USB device
- *
- * FIXME: Write the kerneldoc!
- *
+ * @devnum: device number; address on a USB bus
+ * @devpath: device ID string for use in messages (e.g., /port/...)
+ * @state: device state: configured, not attached, etc.
+ * @speed: device speed: high/full/low (or error)
+ * @tt: Transaction Translator info; used with low/full speed dev, highspeed hub
+ * @ttport: device port on that tt hub
+ * @toggle: one bit for each endpoint, with ([0] = IN, [1] = OUT) endpoints
+ * @parent: our hub, unless we're the root
+ * @bus: bus we're part of
+ * @ep0: endpoint 0 data (default control pipe)
+ * @dev: generic device interface
+ * @descriptor: USB device descriptor
+ * @config: all of the device's configs
+ * @actconfig: the active configuration
+ * @ep_in: array of IN endpoints
+ * @ep_out: array of OUT endpoints
+ * @rawdescriptors: raw descriptors for each config
+ * @bus_mA: Current available from the bus
+ * @portnum: parent port number (origin 1)
+ * @level: number of USB hub ancestors
+ * @can_submit: URBs may be submitted
+ * @discon_suspended: disconnected while suspended
+ * @persist_enabled:  USB_PERSIST enabled for this device
+ * @have_langid: whether string_langid is valid
+ * @authorized: policy has said we can use it;
+ *     (user space) policy determines if we authorize this device to be
+ *     used or not. By default, wired USB devices are authorized.
+ *     WUSB devices are not, until we authorize them from user space.
+ *     FIXME -- complete doc
+ * @wusb: device is Wireless USB
+ * @string_langid: language ID for strings
+ * @product: iProduct string, if present (static)
+ * @manufacturer: iManufacturer string, if present (static)
+ * @serial: iSerialNumber string, if present (static)
+ * @filelist: usbfs files that are open to this device
+ * @usb_classdev: USB class device that was created for usbfs device
+ *     access from userspace
+ * @usbfs_dentry: usbfs dentry entry for the device
+ * @maxchild: number of ports if hub
+ * @children: child devices - USB devices that are attached to this hub
+ * @pm_usage_cnt: usage counter for autosuspend
+ * @quirks: quirks of the whole device
+ * @urbnum: number of URBs submitted for the whole device
+ * @active_duration: total time device is not suspended
+ * @autosuspend: for delayed autosuspends
+ * @pm_mutex: protects PM operations
+ * @last_busy: time of last use
+ * @autosuspend_delay: in jiffies
+ * @connect_time: time device was first connected
+ * @auto_pm: autosuspend/resume in progress
+ * @do_remote_wakeup:  remote wakeup should be enabled
+ * @reset_resume: needs reset instead of resume
+ * @autosuspend_disabled: autosuspend disabled by the user
+ * @autoresume_disabled: autoresume disabled by the user
+ * @skip_sys_resume: skip the next system resume
+ *
+ * Notes:
  * Usbcore drivers should not set usbdev->state directly.  Instead use
  * usb_set_device_state().
- *
- * @authorized: (user space) policy determines if we authorize this
- *              device to be used or not. By default, wired USB
- *              devices are authorized. WUSB devices are not, until we
- *              authorize them from user space. FIXME -- complete doc
  */
 struct usb_device {
-       int             devnum;         /* Address on USB bus */
-       char            devpath [16];   /* Use in messages: /port/port/... */
-       enum usb_device_state   state;  /* configured, not attached, etc */
-       enum usb_device_speed   speed;  /* high/full/low (or error) */
+       int             devnum;
+       char            devpath [16];
+       enum usb_device_state   state;
+       enum usb_device_speed   speed;
 
-       struct usb_tt   *tt;            /* low/full speed dev, highspeed hub */
-       int             ttport;         /* device port on that tt hub */
+       struct usb_tt   *tt;
+       int             ttport;
 
-       unsigned int toggle[2];         /* one bit for each endpoint
-                                        * ([0] = IN, [1] = OUT) */
+       unsigned int toggle[2];
 
-       struct usb_device *parent;      /* our hub, unless we're the root */
-       struct usb_bus *bus;            /* Bus we're part of */
+       struct usb_device *parent;
+       struct usb_bus *bus;
        struct usb_host_endpoint ep0;
 
-       struct device dev;              /* Generic device interface */
+       struct device dev;
 
-       struct usb_device_descriptor descriptor;/* Descriptor */
-       struct usb_host_config *config; /* All of the configs */
+       struct usb_device_descriptor descriptor;
+       struct usb_host_config *config;
 
-       struct usb_host_config *actconfig;/* the active configuration */
+       struct usb_host_config *actconfig;
        struct usb_host_endpoint *ep_in[16];
        struct usb_host_endpoint *ep_out[16];
 
-       char **rawdescriptors;          /* Raw descriptors for each config */
+       char **rawdescriptors;
 
-       unsigned short bus_mA;          /* Current available from the bus */
-       u8 portnum;                     /* Parent port number (origin 1) */
-       u8 level;                       /* Number of USB hub ancestors */
+       unsigned short bus_mA;
+       u8 portnum;
+       u8 level;
 
-       unsigned can_submit:1;          /* URBs may be submitted */
-       unsigned discon_suspended:1;    /* Disconnected while suspended */
-       unsigned persist_enabled:1;     /* USB_PERSIST enabled for this dev */
-       unsigned have_langid:1;         /* whether string_langid is valid */
-       unsigned authorized:1;          /* Policy has said we can use it */
-       unsigned wusb:1;                /* Device is Wireless USB */
-       int string_langid;              /* language ID for strings */
+       unsigned can_submit:1;
+       unsigned discon_suspended:1;
+       unsigned persist_enabled:1;
+       unsigned have_langid:1;
+       unsigned authorized:1;
+       unsigned wusb:1;
+       int string_langid;
 
        /* static strings from the device */
-       char *product;                  /* iProduct string, if present */
-       char *manufacturer;             /* iManufacturer string, if present */
-       char *serial;                   /* iSerialNumber string, if present */
+       char *product;
+       char *manufacturer;
+       char *serial;
 
        struct list_head filelist;
 #ifdef CONFIG_USB_DEVICE_CLASS
        struct device *usb_classdev;
 #endif
 #ifdef CONFIG_USB_DEVICEFS
-       struct dentry *usbfs_dentry;    /* usbfs dentry entry for the device */
+       struct dentry *usbfs_dentry;
 #endif
-       /*
-        * Child devices - these can be either new devices
-        * (if this is a hub device), or different instances
-        * of this same device.
-        *
-        * Each instance needs its own set of data structures.
-        */
 
-       int maxchild;                   /* Number of ports if hub */
+       int maxchild;
        struct usb_device *children[USB_MAXCHILDREN];
 
-       int pm_usage_cnt;               /* usage counter for autosuspend */
-       u32 quirks;                     /* quirks of the whole device */
-       atomic_t urbnum;                /* number of URBs submitted for
-                                          the whole device */
+       int pm_usage_cnt;
+       u32 quirks;
+       atomic_t urbnum;
 
-       unsigned long active_duration;  /* total time device is not suspended */
+       unsigned long active_duration;
 
 #ifdef CONFIG_PM
-       struct delayed_work autosuspend; /* for delayed autosuspends */
-       struct mutex pm_mutex;          /* protects PM operations */
-
-       unsigned long last_busy;        /* time of last use */
-       int autosuspend_delay;          /* in jiffies */
-       unsigned long connect_time;     /* time device was first connected */
-
-       unsigned auto_pm:1;             /* autosuspend/resume in progress */
-       unsigned do_remote_wakeup:1;    /* remote wakeup should be enabled */
-       unsigned reset_resume:1;        /* needs reset instead of resume */
-       unsigned autosuspend_disabled:1; /* autosuspend and autoresume */
-       unsigned autoresume_disabled:1;  /*  disabled by the user */
-       unsigned skip_sys_resume:1;     /* skip the next system resume */
+       struct delayed_work autosuspend;
+       struct mutex pm_mutex;
+
+       unsigned long last_busy;
+       int autosuspend_delay;
+       unsigned long connect_time;
+
+       unsigned auto_pm:1;
+       unsigned do_remote_wakeup:1;
+       unsigned reset_resume:1;
+       unsigned autosuspend_disabled:1;
+       unsigned autoresume_disabled:1;
+       unsigned skip_sys_resume:1;
 #endif
 };
 #define        to_usb_device(d) container_of(d, struct usb_device, dev)