USB: convert usb.h struct usb_device to kernel-doc
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>
diff --git a/include/linux/usb.h b/include/linux/usb.h
index 7e31cac..285011d 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -341,102 +341,142 @@
struct usb_tt;
-/*
+/**
* struct usb_device - kernel's representation of a USB device
+ * @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
*
- * FIXME: Write the kerneldoc!
- *
+ * 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 */
+ struct delayed_work autosuspend;
+ struct mutex pm_mutex;
- unsigned long last_busy; /* time of last use */
- int autosuspend_delay; /* in jiffies */
- unsigned long connect_time; /* time device was first connected */
+ unsigned long last_busy;
+ int autosuspend_delay;
+ unsigned long connect_time;
- 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 */
+ 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)