From f476fbaba7b2051bafdb527eea1a8bed649187d4 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 13 Feb 2008 18:33:15 -0800 Subject: [PATCH] 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 Cc: Alan Stern Signed-off-by: Greg Kroah-Hartman --- include/linux/usb.h | 168 +++++++++++++++++++++++++++----------------- 1 file changed, 104 insertions(+), 64 deletions(-) diff --git a/include/linux/usb.h b/include/linux/usb.h index 7e31cacfe69..285011d9af1 100644 --- a/include/linux/usb.h +++ b/include/linux/usb.h @@ -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) -- 2.41.0