From 79e0c2e6d4a382a7ac80cf082e3ca60bd42ab475 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:02 -0300 Subject: usb/anchors.txt: convert to ReST and add to driver-api book This document describe some USB core functions. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/usb/anchors.txt | 79 ------------------------------------------- 1 file changed, 79 deletions(-) delete mode 100644 Documentation/usb/anchors.txt (limited to 'Documentation/usb') diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt deleted file mode 100644 index fe6a99a32bbd..000000000000 --- a/Documentation/usb/anchors.txt +++ /dev/null @@ -1,79 +0,0 @@ -What is anchor? -=============== - -A USB driver needs to support some callbacks requiring -a driver to cease all IO to an interface. To do so, a -driver has to keep track of the URBs it has submitted -to know they've all completed or to call usb_kill_urb -for them. The anchor is a data structure takes care of -keeping track of URBs and provides methods to deal with -multiple URBs. - -Allocation and Initialisation -============================= - -There's no API to allocate an anchor. It is simply declared -as struct usb_anchor. init_usb_anchor() must be called to -initialise the data structure. - -Deallocation -============ - -Once it has no more URBs associated with it, the anchor can be -freed with normal memory management operations. - -Association and disassociation of URBs with anchors -=================================================== - -An association of URBs to an anchor is made by an explicit -call to usb_anchor_urb(). The association is maintained until -an URB is finished by (successful) completion. Thus disassociation -is automatic. A function is provided to forcibly finish (kill) -all URBs associated with an anchor. -Furthermore, disassociation can be made with usb_unanchor_urb() - -Operations on multitudes of URBs -================================ - -usb_kill_anchored_urbs() ------------------------- - -This function kills all URBs associated with an anchor. The URBs -are called in the reverse temporal order they were submitted. -This way no data can be reordered. - -usb_unlink_anchored_urbs() --------------------------- - -This function unlinks all URBs associated with an anchor. The URBs -are processed in the reverse temporal order they were submitted. -This is similar to usb_kill_anchored_urbs(), but it will not sleep. -Therefore no guarantee is made that the URBs have been unlinked when -the call returns. They may be unlinked later but will be unlinked in -finite time. - -usb_scuttle_anchored_urbs() ---------------------------- - -All URBs of an anchor are unanchored en masse. - -usb_wait_anchor_empty_timeout() -------------------------------- - -This function waits for all URBs associated with an anchor to finish -or a timeout, whichever comes first. Its return value will tell you -whether the timeout was reached. - -usb_anchor_empty() ------------------- - -Returns true if no URBs are associated with an anchor. Locking -is the caller's responsibility. - -usb_get_from_anchor() ---------------------- - -Returns the oldest anchored URB of an anchor. The URB is unanchored -and returned with a reference. As you may mix URBs to several -destinations in one anchor you have no guarantee the chronologically -first submitted URB is returned. -- cgit v1.2.3-55-g7522 From 401c7be2bad9eea68c1a660d54d1caa00b3098e4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:03 -0300 Subject: usb/bulk-streams.txt: convert to ReST and add to driver-api book This document describe some USB core functions. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/bulk-streams.rst | 83 +++++++++++++++++++++++++++ Documentation/driver-api/usb/index.rst | 1 + Documentation/usb/bulk-streams.txt | 78 ------------------------- 3 files changed, 84 insertions(+), 78 deletions(-) create mode 100644 Documentation/driver-api/usb/bulk-streams.rst delete mode 100644 Documentation/usb/bulk-streams.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/bulk-streams.rst b/Documentation/driver-api/usb/bulk-streams.rst new file mode 100644 index 000000000000..99b515babdeb --- /dev/null +++ b/Documentation/driver-api/usb/bulk-streams.rst @@ -0,0 +1,83 @@ +USB bulk streams +~~~~~~~~~~~~~~~~ + +Background +========== + +Bulk endpoint streams were added in the USB 3.0 specification. Streams allow a +device driver to overload a bulk endpoint so that multiple transfers can be +queued at once. + +Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus +3.0 specification at http://www.usb.org/developers/docs/ The USB Attached SCSI +Protocol, which uses streams to queue multiple SCSI commands, can be found on +the T10 website (http://t10.org/). + + +Device-side implications +======================== + +Once a buffer has been queued to a stream ring, the device is notified (through +an out-of-band mechanism on another endpoint) that data is ready for that stream +ID. The device then tells the host which "stream" it wants to start. The host +can also initiate a transfer on a stream without the device asking, but the +device can refuse that transfer. Devices can switch between streams at any +time. + + +Driver implications +=================== + +:: + + int usb_alloc_streams(struct usb_interface *interface, + struct usb_host_endpoint **eps, unsigned int num_eps, + unsigned int num_streams, gfp_t mem_flags); + +Device drivers will call this API to request that the host controller driver +allocate memory so the driver can use up to num_streams stream IDs. They must +pass an array of usb_host_endpoints that need to be setup with similar stream +IDs. This is to ensure that a UASP driver will be able to use the same stream +ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence. + +The return value is an error condition (if one of the endpoints doesn't support +streams, or the xHCI driver ran out of memory), or the number of streams the +host controller allocated for this endpoint. The xHCI host controller hardware +declares how many stream IDs it can support, and each bulk endpoint on a +SuperSpeed device will say how many stream IDs it can handle. Therefore, +drivers should be able to deal with being allocated less stream IDs than they +requested. + +Do NOT call this function if you have URBs enqueued for any of the endpoints +passed in as arguments. Do not call this function to request less than two +streams. + +Drivers will only be allowed to call this API once for the same endpoint +without calling usb_free_streams(). This is a simplification for the xHCI host +controller driver, and may change in the future. + + +Picking new Stream IDs to use +============================= + +Stream ID 0 is reserved, and should not be used to communicate with devices. If +usb_alloc_streams() returns with a value of N, you may use streams 1 though N. +To queue an URB for a specific stream, set the urb->stream_id value. If the +endpoint does not support streams, an error will be returned. + +Note that new API to choose the next stream ID will have to be added if the xHCI +driver supports secondary stream IDs. + + +Clean up +======== + +If a driver wishes to stop using streams to communicate with the device, it +should call:: + + void usb_free_streams(struct usb_interface *interface, + struct usb_host_endpoint **eps, unsigned int num_eps, + gfp_t mem_flags); + +All stream IDs will be deallocated when the driver releases the interface, to +ensure that drivers that don't support streams will be able to use the endpoint. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 5dfb04b2d730..6fe7611f7332 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -7,6 +7,7 @@ Linux USB API usb gadget anchors + bulk-streams writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/usb/bulk-streams.txt b/Documentation/usb/bulk-streams.txt deleted file mode 100644 index ffc02021863e..000000000000 --- a/Documentation/usb/bulk-streams.txt +++ /dev/null @@ -1,78 +0,0 @@ -Background -========== - -Bulk endpoint streams were added in the USB 3.0 specification. Streams allow a -device driver to overload a bulk endpoint so that multiple transfers can be -queued at once. - -Streams are defined in sections 4.4.6.4 and 8.12.1.4 of the Universal Serial Bus -3.0 specification at http://www.usb.org/developers/docs/ The USB Attached SCSI -Protocol, which uses streams to queue multiple SCSI commands, can be found on -the T10 website (http://t10.org/). - - -Device-side implications -======================== - -Once a buffer has been queued to a stream ring, the device is notified (through -an out-of-band mechanism on another endpoint) that data is ready for that stream -ID. The device then tells the host which "stream" it wants to start. The host -can also initiate a transfer on a stream without the device asking, but the -device can refuse that transfer. Devices can switch between streams at any -time. - - -Driver implications -=================== - -int usb_alloc_streams(struct usb_interface *interface, - struct usb_host_endpoint **eps, unsigned int num_eps, - unsigned int num_streams, gfp_t mem_flags); - -Device drivers will call this API to request that the host controller driver -allocate memory so the driver can use up to num_streams stream IDs. They must -pass an array of usb_host_endpoints that need to be setup with similar stream -IDs. This is to ensure that a UASP driver will be able to use the same stream -ID for the bulk IN and OUT endpoints used in a Bi-directional command sequence. - -The return value is an error condition (if one of the endpoints doesn't support -streams, or the xHCI driver ran out of memory), or the number of streams the -host controller allocated for this endpoint. The xHCI host controller hardware -declares how many stream IDs it can support, and each bulk endpoint on a -SuperSpeed device will say how many stream IDs it can handle. Therefore, -drivers should be able to deal with being allocated less stream IDs than they -requested. - -Do NOT call this function if you have URBs enqueued for any of the endpoints -passed in as arguments. Do not call this function to request less than two -streams. - -Drivers will only be allowed to call this API once for the same endpoint -without calling usb_free_streams(). This is a simplification for the xHCI host -controller driver, and may change in the future. - - -Picking new Stream IDs to use -============================ - -Stream ID 0 is reserved, and should not be used to communicate with devices. If -usb_alloc_streams() returns with a value of N, you may use streams 1 though N. -To queue an URB for a specific stream, set the urb->stream_id value. If the -endpoint does not support streams, an error will be returned. - -Note that new API to choose the next stream ID will have to be added if the xHCI -driver supports secondary stream IDs. - - -Clean up -======== - -If a driver wishes to stop using streams to communicate with the device, it -should call - -void usb_free_streams(struct usb_interface *interface, - struct usb_host_endpoint **eps, unsigned int num_eps, - gfp_t mem_flags); - -All stream IDs will be deallocated when the driver releases the interface, to -ensure that drivers that don't support streams will be able to use the endpoint. -- cgit v1.2.3-55-g7522 From 3b38e4f21868d83ed03d5d101c789c4df2b08e8b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:04 -0300 Subject: usb/callbacks.txt: convert to ReST and add to driver-api book This document describe some USB core functions. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/callbacks.rst | 157 +++++++++++++++++++++++++++++ Documentation/driver-api/usb/index.rst | 1 + Documentation/usb/callbacks.txt | 134 ------------------------ 3 files changed, 158 insertions(+), 134 deletions(-) create mode 100644 Documentation/driver-api/usb/callbacks.rst delete mode 100644 Documentation/usb/callbacks.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/callbacks.rst b/Documentation/driver-api/usb/callbacks.rst new file mode 100644 index 000000000000..93a8d53e27e7 --- /dev/null +++ b/Documentation/driver-api/usb/callbacks.rst @@ -0,0 +1,157 @@ +USB core callbacks +~~~~~~~~~~~~~~~~~~ + +What callbacks will usbcore do? +=============================== + +Usbcore will call into a driver through callbacks defined in the driver +structure and through the completion handler of URBs a driver submits. +Only the former are in the scope of this document. These two kinds of +callbacks are completely independent of each other. Information on the +completion callback can be found in Documentation/usb/URB.txt. + +The callbacks defined in the driver structure are: + +1. Hotplugging callbacks: + + - @probe: + Called to see if the driver is willing to manage a particular + interface on a device. + + - @disconnect: + Called when the interface is no longer accessible, usually + because its device has been (or is being) disconnected or the + driver module is being unloaded. + +2. Odd backdoor through usbfs: + + - @ioctl: + Used for drivers that want to talk to userspace through + the "usbfs" filesystem. This lets devices provide ways to + expose information to user space regardless of where they + do (or don't) show up otherwise in the filesystem. + +3. Power management (PM) callbacks: + + - @suspend: + Called when the device is going to be suspended. + + - @resume: + Called when the device is being resumed. + + - @reset_resume: + Called when the suspended device has been reset instead + of being resumed. + +4. Device level operations: + + - @pre_reset: + Called when the device is about to be reset. + + - @post_reset: + Called after the device has been reset + +The ioctl interface (2) should be used only if you have a very good +reason. Sysfs is preferred these days. The PM callbacks are covered +separately in Documentation/usb/power-management.txt. + +Calling conventions +=================== + +All callbacks are mutually exclusive. There's no need for locking +against other USB callbacks. All callbacks are called from a task +context. You may sleep. However, it is important that all sleeps have a +small fixed upper limit in time. In particular you must not call out to +user space and await results. + +Hotplugging callbacks +===================== + +These callbacks are intended to associate and disassociate a driver with +an interface. A driver's bond to an interface is exclusive. + +The probe() callback +-------------------- + +:: + + int (*probe) (struct usb_interface *intf, + const struct usb_device_id *id); + +Accept or decline an interface. If you accept the device return 0, +otherwise -ENODEV or -ENXIO. Other error codes should be used only if a +genuine error occurred during initialisation which prevented a driver +from accepting a device that would else have been accepted. +You are strongly encouraged to use usbcore's facility, +usb_set_intfdata(), to associate a data structure with an interface, so +that you know which internal state and identity you associate with a +particular interface. The device will not be suspended and you may do IO +to the interface you are called for and endpoint 0 of the device. Device +initialisation that doesn't take too long is a good idea here. + +The disconnect() callback +------------------------- + +:: + + void (*disconnect) (struct usb_interface *intf); + +This callback is a signal to break any connection with an interface. +You are not allowed any IO to a device after returning from this +callback. You also may not do any other operation that may interfere +with another driver bound the interface, eg. a power management +operation. +If you are called due to a physical disconnection, all your URBs will be +killed by usbcore. Note that in this case disconnect will be called some +time after the physical disconnection. Thus your driver must be prepared +to deal with failing IO even prior to the callback. + +Device level callbacks +====================== + +pre_reset +--------- + +:: + + int (*pre_reset)(struct usb_interface *intf); + +A driver or user space is triggering a reset on the device which +contains the interface passed as an argument. Cease IO, wait for all +outstanding URBs to complete, and save any device state you need to +restore. No more URBs may be submitted until the post_reset method +is called. + +If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you +are in atomic context. + +post_reset +---------- + +:: + + int (*post_reset)(struct usb_interface *intf); + +The reset has completed. Restore any saved device state and begin +using the device again. + +If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you +are in atomic context. + +Call sequences +============== + +No callbacks other than probe will be invoked for an interface +that isn't bound to your driver. + +Probe will never be called for an interface bound to a driver. +Hence following a successful probe, disconnect will be called +before there is another probe for the same interface. + +Once your driver is bound to an interface, disconnect can be +called at any time except in between pre_reset and post_reset. +pre_reset is always followed by post_reset, even if the reset +failed or the device has been unplugged. + +suspend is always followed by one of: resume, reset_resume, or +disconnect. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 6fe7611f7332..441c5dacdf27 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -8,6 +8,7 @@ Linux USB API gadget anchors bulk-streams + callbacks writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/usb/callbacks.txt b/Documentation/usb/callbacks.txt deleted file mode 100644 index 9e85846bdb98..000000000000 --- a/Documentation/usb/callbacks.txt +++ /dev/null @@ -1,134 +0,0 @@ -What callbacks will usbcore do? -=============================== - -Usbcore will call into a driver through callbacks defined in the driver -structure and through the completion handler of URBs a driver submits. -Only the former are in the scope of this document. These two kinds of -callbacks are completely independent of each other. Information on the -completion callback can be found in Documentation/usb/URB.txt. - -The callbacks defined in the driver structure are: - -1. Hotplugging callbacks: - - * @probe: Called to see if the driver is willing to manage a particular - * interface on a device. - * @disconnect: Called when the interface is no longer accessible, usually - * because its device has been (or is being) disconnected or the - * driver module is being unloaded. - -2. Odd backdoor through usbfs: - - * @ioctl: Used for drivers that want to talk to userspace through - * the "usbfs" filesystem. This lets devices provide ways to - * expose information to user space regardless of where they - * do (or don't) show up otherwise in the filesystem. - -3. Power management (PM) callbacks: - - * @suspend: Called when the device is going to be suspended. - * @resume: Called when the device is being resumed. - * @reset_resume: Called when the suspended device has been reset instead - * of being resumed. - -4. Device level operations: - - * @pre_reset: Called when the device is about to be reset. - * @post_reset: Called after the device has been reset - -The ioctl interface (2) should be used only if you have a very good -reason. Sysfs is preferred these days. The PM callbacks are covered -separately in Documentation/usb/power-management.txt. - -Calling conventions -=================== - -All callbacks are mutually exclusive. There's no need for locking -against other USB callbacks. All callbacks are called from a task -context. You may sleep. However, it is important that all sleeps have a -small fixed upper limit in time. In particular you must not call out to -user space and await results. - -Hotplugging callbacks -===================== - -These callbacks are intended to associate and disassociate a driver with -an interface. A driver's bond to an interface is exclusive. - -The probe() callback --------------------- - -int (*probe) (struct usb_interface *intf, - const struct usb_device_id *id); - -Accept or decline an interface. If you accept the device return 0, -otherwise -ENODEV or -ENXIO. Other error codes should be used only if a -genuine error occurred during initialisation which prevented a driver -from accepting a device that would else have been accepted. -You are strongly encouraged to use usbcore's facility, -usb_set_intfdata(), to associate a data structure with an interface, so -that you know which internal state and identity you associate with a -particular interface. The device will not be suspended and you may do IO -to the interface you are called for and endpoint 0 of the device. Device -initialisation that doesn't take too long is a good idea here. - -The disconnect() callback -------------------------- - -void (*disconnect) (struct usb_interface *intf); - -This callback is a signal to break any connection with an interface. -You are not allowed any IO to a device after returning from this -callback. You also may not do any other operation that may interfere -with another driver bound the interface, eg. a power management -operation. -If you are called due to a physical disconnection, all your URBs will be -killed by usbcore. Note that in this case disconnect will be called some -time after the physical disconnection. Thus your driver must be prepared -to deal with failing IO even prior to the callback. - -Device level callbacks -====================== - -pre_reset ---------- - -int (*pre_reset)(struct usb_interface *intf); - -A driver or user space is triggering a reset on the device which -contains the interface passed as an argument. Cease IO, wait for all -outstanding URBs to complete, and save any device state you need to -restore. No more URBs may be submitted until the post_reset method -is called. - -If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you -are in atomic context. - -post_reset ----------- - -int (*post_reset)(struct usb_interface *intf); - -The reset has completed. Restore any saved device state and begin -using the device again. - -If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you -are in atomic context. - -Call sequences -============== - -No callbacks other than probe will be invoked for an interface -that isn't bound to your driver. - -Probe will never be called for an interface bound to a driver. -Hence following a successful probe, disconnect will be called -before there is another probe for the same interface. - -Once your driver is bound to an interface, disconnect can be -called at any time except in between pre_reset and post_reset. -pre_reset is always followed by post_reset, even if the reset -failed or the device has been unplugged. - -suspend is always followed by one of: resume, reset_resume, or -disconnect. -- cgit v1.2.3-55-g7522 From 3db5f406e4440c486cec4772210b9802bf4546b3 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:05 -0300 Subject: usb/power-management.txt: convert to ReST and add to driver-api book This document describe some USB core functions. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/index.rst | 1 + Documentation/driver-api/usb/power-management.rst | 794 ++++++++++++++++++++++ Documentation/usb/power-management.txt | 772 --------------------- 3 files changed, 795 insertions(+), 772 deletions(-) create mode 100644 Documentation/driver-api/usb/power-management.rst delete mode 100644 Documentation/usb/power-management.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 441c5dacdf27..23c76c17fc19 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -9,6 +9,7 @@ Linux USB API anchors bulk-streams callbacks + power-management writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/driver-api/usb/power-management.rst b/Documentation/driver-api/usb/power-management.rst new file mode 100644 index 000000000000..c068257f6d27 --- /dev/null +++ b/Documentation/driver-api/usb/power-management.rst @@ -0,0 +1,794 @@ +.. _usb-power-management: + +Power Management for USB +~~~~~~~~~~~~~~~~~~~~~~~~ + +:Author: Alan Stern +:Date: Last-updated: February 2014 + +.. + Contents: + --------- + * What is Power Management? + * What is Remote Wakeup? + * When is a USB device idle? + * Forms of dynamic PM + * The user interface for dynamic PM + * Changing the default idle-delay time + * Warnings + * The driver interface for Power Management + * The driver interface for autosuspend and autoresume + * Other parts of the driver interface + * Mutual exclusion + * Interaction between dynamic PM and system PM + * xHCI hardware link PM + * USB Port Power Control + * User Interface for Port Power Control + * Suggested Userspace Port Power Policy + + +What is Power Management? +------------------------- + +Power Management (PM) is the practice of saving energy by suspending +parts of a computer system when they aren't being used. While a +component is ``suspended`` it is in a nonfunctional low-power state; it +might even be turned off completely. A suspended component can be +``resumed`` (returned to a functional full-power state) when the kernel +needs to use it. (There also are forms of PM in which components are +placed in a less functional but still usable state instead of being +suspended; an example would be reducing the CPU's clock rate. This +document will not discuss those other forms.) + +When the parts being suspended include the CPU and most of the rest of +the system, we speak of it as a "system suspend". When a particular +device is turned off while the system as a whole remains running, we +call it a "dynamic suspend" (also known as a "runtime suspend" or +"selective suspend"). This document concentrates mostly on how +dynamic PM is implemented in the USB subsystem, although system PM is +covered to some extent (see ``Documentation/power/*.txt`` for more +information about system PM). + +System PM support is present only if the kernel was built with +``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled. Dynamic PM support + +for USB is present whenever +the kernel was built with ``CONFIG_PM`` enabled. + +[Historically, dynamic PM support for USB was present only if the +kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on +``CONFIG_PM_RUNTIME``). Starting with the 3.10 kernel release, dynamic PM +support for USB was present whenever the kernel was built with +``CONFIG_PM_RUNTIME`` enabled. The ``CONFIG_USB_SUSPEND`` option had been +eliminated.] + + +What is Remote Wakeup? +---------------------- + +When a device has been suspended, it generally doesn't resume until +the computer tells it to. Likewise, if the entire computer has been +suspended, it generally doesn't resume until the user tells it to, say +by pressing a power button or opening the cover. + +However some devices have the capability of resuming by themselves, or +asking the kernel to resume them, or even telling the entire computer +to resume. This capability goes by several names such as "Wake On +LAN"; we will refer to it generically as "remote wakeup". When a +device is enabled for remote wakeup and it is suspended, it may resume +itself (or send a request to be resumed) in response to some external +event. Examples include a suspended keyboard resuming when a key is +pressed, or a suspended USB hub resuming when a device is plugged in. + + +When is a USB device idle? +-------------------------- + +A device is idle whenever the kernel thinks it's not busy doing +anything important and thus is a candidate for being suspended. The +exact definition depends on the device's driver; drivers are allowed +to declare that a device isn't idle even when there's no actual +communication taking place. (For example, a hub isn't considered idle +unless all the devices plugged into that hub are already suspended.) +In addition, a device isn't considered idle so long as a program keeps +its usbfs file open, whether or not any I/O is going on. + +If a USB device has no driver, its usbfs file isn't open, and it isn't +being accessed through sysfs, then it definitely is idle. + + +Forms of dynamic PM +------------------- + +Dynamic suspends occur when the kernel decides to suspend an idle +device. This is called ``autosuspend`` for short. In general, a device +won't be autosuspended unless it has been idle for some minimum period +of time, the so-called idle-delay time. + +Of course, nothing the kernel does on its own initiative should +prevent the computer or its devices from working properly. If a +device has been autosuspended and a program tries to use it, the +kernel will automatically resume the device (autoresume). For the +same reason, an autosuspended device will usually have remote wakeup +enabled, if the device supports remote wakeup. + +It is worth mentioning that many USB drivers don't support +autosuspend. In fact, at the time of this writing (Linux 2.6.23) the +only drivers which do support it are the hub driver, kaweth, asix, +usblp, usblcd, and usb-skeleton (which doesn't count). If a +non-supporting driver is bound to a device, the device won't be +autosuspended. In effect, the kernel pretends the device is never +idle. + +We can categorize power management events in two broad classes: +external and internal. External events are those triggered by some +agent outside the USB stack: system suspend/resume (triggered by +userspace), manual dynamic resume (also triggered by userspace), and +remote wakeup (triggered by the device). Internal events are those +triggered within the USB stack: autosuspend and autoresume. Note that +all dynamic suspend events are internal; external agents are not +allowed to issue dynamic suspends. + + +The user interface for dynamic PM +--------------------------------- + +The user interface for controlling dynamic PM is located in the ``power/`` +subdirectory of each USB device's sysfs directory, that is, in +``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The +relevant attribute files are: wakeup, control, and +``autosuspend_delay_ms``. (There may also be a file named ``level``; this +file was deprecated as of the 2.6.35 kernel and replaced by the +``control`` file. In 2.6.38 the ``autosuspend`` file will be deprecated +and replaced by the ``autosuspend_delay_ms`` file. The only difference +is that the newer file expresses the delay in milliseconds whereas the +older file uses seconds. Confusingly, both files are present in 2.6.37 +but only ``autosuspend`` works.) + + ``power/wakeup`` + + This file is empty if the device does not support + remote wakeup. Otherwise the file contains either the + word ``enabled`` or the word ``disabled``, and you can + write those words to the file. The setting determines + whether or not remote wakeup will be enabled when the + device is next suspended. (If the setting is changed + while the device is suspended, the change won't take + effect until the following suspend.) + + ``power/control`` + + This file contains one of two words: ``on`` or ``auto``. + You can write those words to the file to change the + device's setting. + + - ``on`` means that the device should be resumed and + autosuspend is not allowed. (Of course, system + suspends are still allowed.) + + - ``auto`` is the normal state in which the kernel is + allowed to autosuspend and autoresume the device. + + (In kernels up to 2.6.32, you could also specify + ``suspend``, meaning that the device should remain + suspended and autoresume was not allowed. This + setting is no longer supported.) + + ``power/autosuspend_delay_ms`` + + This file contains an integer value, which is the + number of milliseconds the device should remain idle + before the kernel will autosuspend it (the idle-delay + time). The default is 2000. 0 means to autosuspend + as soon as the device becomes idle, and negative + values mean never to autosuspend. You can write a + number to the file to change the autosuspend + idle-delay time. + +Writing ``-1`` to ``power/autosuspend_delay_ms`` and writing ``on`` to +``power/control`` do essentially the same thing -- they both prevent the +device from being autosuspended. Yes, this is a redundancy in the +API. + +(In 2.6.21 writing ``0`` to ``power/autosuspend`` would prevent the device +from being autosuspended; the behavior was changed in 2.6.22. The +``power/autosuspend`` attribute did not exist prior to 2.6.21, and the +``power/level`` attribute did not exist prior to 2.6.22. ``power/control`` +was added in 2.6.34, and ``power/autosuspend_delay_ms`` was added in +2.6.37 but did not become functional until 2.6.38.) + + +Changing the default idle-delay time +------------------------------------ + +The default autosuspend idle-delay time (in seconds) is controlled by +a module parameter in usbcore. You can specify the value when usbcore +is loaded. For example, to set it to 5 seconds instead of 2 you would +do:: + + modprobe usbcore autosuspend=5 + +Equivalently, you could add to a configuration file in /etc/modprobe.d +a line saying:: + + options usbcore autosuspend=5 + +Some distributions load the usbcore module very early during the boot +process, by means of a program or script running from an initramfs +image. To alter the parameter value you would have to rebuild that +image. + +If usbcore is compiled into the kernel rather than built as a loadable +module, you can add:: + + usbcore.autosuspend=5 + +to the kernel's boot command line. + +Finally, the parameter value can be changed while the system is +running. If you do:: + + echo 5 >/sys/module/usbcore/parameters/autosuspend + +then each new USB device will have its autosuspend idle-delay +initialized to 5. (The idle-delay values for already existing devices +will not be affected.) + +Setting the initial default idle-delay to -1 will prevent any +autosuspend of any USB device. This has the benefit of allowing you +then to enable autosuspend for selected devices. + + +Warnings +-------- + +The USB specification states that all USB devices must support power +management. Nevertheless, the sad fact is that many devices do not +support it very well. You can suspend them all right, but when you +try to resume them they disconnect themselves from the USB bus or +they stop working entirely. This seems to be especially prevalent +among printers and scanners, but plenty of other types of device have +the same deficiency. + +For this reason, by default the kernel disables autosuspend (the +``power/control`` attribute is initialized to ``on``) for all devices other +than hubs. Hubs, at least, appear to be reasonably well-behaved in +this regard. + +(In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled +by default for almost all USB devices. A number of people experienced +problems as a result.) + +This means that non-hub devices won't be autosuspended unless the user +or a program explicitly enables it. As of this writing there aren't +any widespread programs which will do this; we hope that in the near +future device managers such as HAL will take on this added +responsibility. In the meantime you can always carry out the +necessary operations by hand or add them to a udev script. You can +also change the idle-delay time; 2 seconds is not the best choice for +every device. + +If a driver knows that its device has proper suspend/resume support, +it can enable autosuspend all by itself. For example, the video +driver for a laptop's webcam might do this (in recent kernels they +do), since these devices are rarely used and so should normally be +autosuspended. + +Sometimes it turns out that even when a device does work okay with +autosuspend there are still problems. For example, the usbhid driver, +which manages keyboards and mice, has autosuspend support. Tests with +a number of keyboards show that typing on a suspended keyboard, while +causing the keyboard to do a remote wakeup all right, will nonetheless +frequently result in lost keystrokes. Tests with mice show that some +of them will issue a remote-wakeup request in response to button +presses but not to motion, and some in response to neither. + +The kernel will not prevent you from enabling autosuspend on devices +that can't handle it. It is even possible in theory to damage a +device by suspending it at the wrong time. (Highly unlikely, but +possible.) Take care. + + +The driver interface for Power Management +----------------------------------------- + +The requirements for a USB driver to support external power management +are pretty modest; the driver need only define:: + + .suspend + .resume + .reset_resume + +methods in its :c:type:`usb_driver` structure, and the ``reset_resume`` method +is optional. The methods' jobs are quite simple: + + - The ``suspend`` method is called to warn the driver that the + device is going to be suspended. If the driver returns a + negative error code, the suspend will be aborted. Normally + the driver will return 0, in which case it must cancel all + outstanding URBs (:c:func:`usb_kill_urb`) and not submit any more. + + - The ``resume`` method is called to tell the driver that the + device has been resumed and the driver can return to normal + operation. URBs may once more be submitted. + + - The ``reset_resume`` method is called to tell the driver that + the device has been resumed and it also has been reset. + The driver should redo any necessary device initialization, + since the device has probably lost most or all of its state + (although the interfaces will be in the same altsettings as + before the suspend). + +If the device is disconnected or powered down while it is suspended, +the ``disconnect`` method will be called instead of the ``resume`` or +``reset_resume`` method. This is also quite likely to happen when +waking up from hibernation, as many systems do not maintain suspend +current to the USB host controllers during hibernation. (It's +possible to work around the hibernation-forces-disconnect problem by +using the USB Persist facility.) + +The ``reset_resume`` method is used by the USB Persist facility (see +``Documentation/usb/persist.txt``) and it can also be used under certain +circumstances when ``CONFIG_USB_PERSIST`` is not enabled. Currently, if a +device is reset during a resume and the driver does not have a +``reset_resume`` method, the driver won't receive any notification about +the resume. Later kernels will call the driver's ``disconnect`` method; +2.6.23 doesn't do this. + +USB drivers are bound to interfaces, so their ``suspend`` and ``resume`` +methods get called when the interfaces are suspended or resumed. In +principle one might want to suspend some interfaces on a device (i.e., +force the drivers for those interface to stop all activity) without +suspending the other interfaces. The USB core doesn't allow this; all +interfaces are suspended when the device itself is suspended and all +interfaces are resumed when the device is resumed. It isn't possible +to suspend or resume some but not all of a device's interfaces. The +closest you can come is to unbind the interfaces' drivers. + + +The driver interface for autosuspend and autoresume +--------------------------------------------------- + +To support autosuspend and autoresume, a driver should implement all +three of the methods listed above. In addition, a driver indicates +that it supports autosuspend by setting the ``.supports_autosuspend`` flag +in its usb_driver structure. It is then responsible for informing the +USB core whenever one of its interfaces becomes busy or idle. The +driver does so by calling these six functions:: + + int usb_autopm_get_interface(struct usb_interface *intf); + void usb_autopm_put_interface(struct usb_interface *intf); + int usb_autopm_get_interface_async(struct usb_interface *intf); + void usb_autopm_put_interface_async(struct usb_interface *intf); + void usb_autopm_get_interface_no_resume(struct usb_interface *intf); + void usb_autopm_put_interface_no_suspend(struct usb_interface *intf); + +The functions work by maintaining a usage counter in the +usb_interface's embedded device structure. When the counter is > 0 +then the interface is deemed to be busy, and the kernel will not +autosuspend the interface's device. When the usage counter is = 0 +then the interface is considered to be idle, and the kernel may +autosuspend the device. + +Drivers need not be concerned about balancing changes to the usage +counter; the USB core will undo any remaining "get"s when a driver +is unbound from its interface. As a corollary, drivers must not call +any of the ``usb_autopm_*`` functions after their ``disconnect`` +routine has returned. + +Drivers using the async routines are responsible for their own +synchronization and mutual exclusion. + + :c:func:`usb_autopm_get_interface` increments the usage counter and + does an autoresume if the device is suspended. If the + autoresume fails, the counter is decremented back. + + :c:func:`usb_autopm_put_interface` decrements the usage counter and + attempts an autosuspend if the new value is = 0. + + :c:func:`usb_autopm_get_interface_async` and + :c:func:`usb_autopm_put_interface_async` do almost the same things as + their non-async counterparts. The big difference is that they + use a workqueue to do the resume or suspend part of their + jobs. As a result they can be called in an atomic context, + such as an URB's completion handler, but when they return the + device will generally not yet be in the desired state. + + :c:func:`usb_autopm_get_interface_no_resume` and + :c:func:`usb_autopm_put_interface_no_suspend` merely increment or + decrement the usage counter; they do not attempt to carry out + an autoresume or an autosuspend. Hence they can be called in + an atomic context. + +The simplest usage pattern is that a driver calls +:c:func:`usb_autopm_get_interface` in its open routine and +:c:func:`usb_autopm_put_interface` in its close or release routine. But other +patterns are possible. + +The autosuspend attempts mentioned above will often fail for one +reason or another. For example, the ``power/control`` attribute might be +set to ``on``, or another interface in the same device might not be +idle. This is perfectly normal. If the reason for failure was that +the device hasn't been idle for long enough, a timer is scheduled to +carry out the operation automatically when the autosuspend idle-delay +has expired. + +Autoresume attempts also can fail, although failure would mean that +the device is no longer present or operating properly. Unlike +autosuspend, there's no idle-delay for an autoresume. + + +Other parts of the driver interface +----------------------------------- + +Drivers can enable autosuspend for their devices by calling:: + + usb_enable_autosuspend(struct usb_device *udev); + +in their :c:func:`probe` routine, if they know that the device is capable of +suspending and resuming correctly. This is exactly equivalent to +writing ``auto`` to the device's ``power/control`` attribute. Likewise, +drivers can disable autosuspend by calling:: + + usb_disable_autosuspend(struct usb_device *udev); + +This is exactly the same as writing ``on`` to the ``power/control`` attribute. + +Sometimes a driver needs to make sure that remote wakeup is enabled +during autosuspend. For example, there's not much point +autosuspending a keyboard if the user can't cause the keyboard to do a +remote wakeup by typing on it. If the driver sets +``intf->needs_remote_wakeup`` to 1, the kernel won't autosuspend the +device if remote wakeup isn't available. (If the device is already +autosuspended, though, setting this flag won't cause the kernel to +autoresume it. Normally a driver would set this flag in its ``probe`` +method, at which time the device is guaranteed not to be +autosuspended.) + +If a driver does its I/O asynchronously in interrupt context, it +should call :c:func:`usb_autopm_get_interface_async` before starting output and +:c:func:`usb_autopm_put_interface_async` when the output queue drains. When +it receives an input event, it should call:: + + usb_mark_last_busy(struct usb_device *udev); + +in the event handler. This tells the PM core that the device was just +busy and therefore the next autosuspend idle-delay expiration should +be pushed back. Many of the usb_autopm_* routines also make this call, +so drivers need to worry only when interrupt-driven input arrives. + +Asynchronous operation is always subject to races. For example, a +driver may call the :c:func:`usb_autopm_get_interface_async` routine at a time +when the core has just finished deciding the device has been idle for +long enough but not yet gotten around to calling the driver's ``suspend`` +method. The ``suspend`` method must be responsible for synchronizing with +the I/O request routine and the URB completion handler; it should +cause autosuspends to fail with -EBUSY if the driver needs to use the +device. + +External suspend calls should never be allowed to fail in this way, +only autosuspend calls. The driver can tell them apart by applying +the :c:func:`PMSG_IS_AUTO` macro to the message argument to the ``suspend`` +method; it will return True for internal PM events (autosuspend) and +False for external PM events. + + +Mutual exclusion +---------------- + +For external events -- but not necessarily for autosuspend or +autoresume -- the device semaphore (udev->dev.sem) will be held when a +``suspend`` or ``resume`` method is called. This implies that external +suspend/resume events are mutually exclusive with calls to ``probe``, +``disconnect``, ``pre_reset``, and ``post_reset``; the USB core guarantees that +this is true of autosuspend/autoresume events as well. + +If a driver wants to block all suspend/resume calls during some +critical section, the best way is to lock the device and call +:c:func:`usb_autopm_get_interface` (and do the reverse at the end of the +critical section). Holding the device semaphore will block all +external PM calls, and the :c:func:`usb_autopm_get_interface` will prevent any +internal PM calls, even if it fails. (Exercise: Why?) + + +Interaction between dynamic PM and system PM +-------------------------------------------- + +Dynamic power management and system power management can interact in +a couple of ways. + +Firstly, a device may already be autosuspended when a system suspend +occurs. Since system suspends are supposed to be as transparent as +possible, the device should remain suspended following the system +resume. But this theory may not work out well in practice; over time +the kernel's behavior in this regard has changed. As of 2.6.37 the +policy is to resume all devices during a system resume and let them +handle their own runtime suspends afterward. + +Secondly, a dynamic power-management event may occur as a system +suspend is underway. The window for this is short, since system +suspends don't take long (a few seconds usually), but it can happen. +For example, a suspended device may send a remote-wakeup signal while +the system is suspending. The remote wakeup may succeed, which would +cause the system suspend to abort. If the remote wakeup doesn't +succeed, it may still remain active and thus cause the system to +resume as soon as the system suspend is complete. Or the remote +wakeup may fail and get lost. Which outcome occurs depends on timing +and on the hardware and firmware design. + + +xHCI hardware link PM +--------------------- + +xHCI host controller provides hardware link power management to usb2.0 +(xHCI 1.0 feature) and usb3.0 devices which support link PM. By +enabling hardware LPM, the host can automatically put the device into +lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices), +which state device can enter and resume very quickly. + +The user interface for controlling hardware LPM is located in the +``power/`` subdirectory of each USB device's sysfs directory, that is, in +``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The +relevant attribute files are ``usb2_hardware_lpm`` and ``usb3_hardware_lpm``. + + ``power/usb2_hardware_lpm`` + + When a USB2 device which support LPM is plugged to a + xHCI host root hub which support software LPM, the + host will run a software LPM test for it; if the device + enters L1 state and resume successfully and the host + supports USB2 hardware LPM, this file will show up and + driver will enable hardware LPM for the device. You + can write y/Y/1 or n/N/0 to the file to enable/disable + USB2 hardware LPM manually. This is for test purpose mainly. + + ``power/usb3_hardware_lpm_u1`` + ``power/usb3_hardware_lpm_u2`` + + When a USB 3.0 lpm-capable device is plugged in to a + xHCI host which supports link PM, it will check if U1 + and U2 exit latencies have been set in the BOS + descriptor; if the check is passed and the host + supports USB3 hardware LPM, USB3 hardware LPM will be + enabled for the device and these files will be created. + The files hold a string value (enable or disable) + indicating whether or not USB3 hardware LPM U1 or U2 + is enabled for the device. + +USB Port Power Control +---------------------- + +In addition to suspending endpoint devices and enabling hardware +controlled link power management, the USB subsystem also has the +capability to disable power to ports under some conditions. Power is +controlled through ``Set/ClearPortFeature(PORT_POWER)`` requests to a hub. +In the case of a root or platform-internal hub the host controller +driver translates ``PORT_POWER`` requests into platform firmware (ACPI) +method calls to set the port power state. For more background see the +Linux Plumbers Conference 2012 slides [#f1]_ and video [#f2]_: + +Upon receiving a ``ClearPortFeature(PORT_POWER)`` request a USB port is +logically off, and may trigger the actual loss of VBUS to the port [#f3]_. +VBUS may be maintained in the case where a hub gangs multiple ports into +a shared power well causing power to remain until all ports in the gang +are turned off. VBUS may also be maintained by hub ports configured for +a charging application. In any event a logically off port will lose +connection with its device, not respond to hotplug events, and not +respond to remote wakeup events. + +.. warning:: + + turning off a port may result in the inability to hot add a device. + Please see "User Interface for Port Power Control" for details. + +As far as the effect on the device itself it is similar to what a device +goes through during system suspend, i.e. the power session is lost. Any +USB device or driver that misbehaves with system suspend will be +similarly affected by a port power cycle event. For this reason the +implementation shares the same device recovery path (and honors the same +quirks) as the system resume path for the hub. + +.. [#f1] + + http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf + +.. [#f2] + + http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/ + +.. [#f3] + + USB 3.1 Section 10.12 + + wakeup note: if a device is configured to send wakeup events the port + power control implementation will block poweroff attempts on that + port. + + +User Interface for Port Power Control +------------------------------------- + +The port power control mechanism uses the PM runtime system. Poweroff is +requested by clearing the ``power/pm_qos_no_power_off`` flag of the port device +(defaults to 1). If the port is disconnected it will immediately receive a +``ClearPortFeature(PORT_POWER)`` request. Otherwise, it will honor the pm +runtime rules and require the attached child device and all descendants to be +suspended. This mechanism is dependent on the hub advertising port power +switching in its hub descriptor (wHubCharacteristics logical power switching +mode field). + +Note, some interface devices/drivers do not support autosuspend. Userspace may +need to unbind the interface drivers before the :c:type:`usb_device` will +suspend. An unbound interface device is suspended by default. When unbinding, +be careful to unbind interface drivers, not the driver of the parent usb +device. Also, leave hub interface drivers bound. If the driver for the usb +device (not interface) is unbound the kernel is no longer able to resume the +device. If a hub interface driver is unbound, control of its child ports is +lost and all attached child-devices will disconnect. A good rule of thumb is +that if the 'driver/module' link for a device points to +``/sys/module/usbcore`` then unbinding it will interfere with port power +control. + +Example of the relevant files for port power control. Note, in this example +these files are relative to a usb hub device (prefix):: + + prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1 + + attached child device + + hub port device + | + hub interface device + | | + v v v + $prefix/3-1:1.0/3-1-port1/device + + $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off + $prefix/3-1:1.0/3-1-port1/device/power/control + $prefix/3-1:1.0/3-1-port1/device/3-1.1:/driver/unbind + $prefix/3-1:1.0/3-1-port1/device/3-1.1:/driver/unbind + ... + $prefix/3-1:1.0/3-1-port1/device/3-1.1:/driver/unbind + +In addition to these files some ports may have a 'peer' link to a port on +another hub. The expectation is that all superspeed ports have a +hi-speed peer:: + + $prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1 + ../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1 + +Distinct from 'companion ports', or 'ehci/xhci shared switchover ports' +peer ports are simply the hi-speed and superspeed interface pins that +are combined into a single usb3 connector. Peer ports share the same +ancestor XHCI device. + +While a superspeed port is powered off a device may downgrade its +connection and attempt to connect to the hi-speed pins. The +implementation takes steps to prevent this: + +1. Port suspend is sequenced to guarantee that hi-speed ports are powered-off + before their superspeed peer is permitted to power-off. The implication is + that the setting ``pm_qos_no_power_off`` to zero on a superspeed port may + not cause the port to power-off until its highspeed peer has gone to its + runtime suspend state. Userspace must take care to order the suspensions + if it wants to guarantee that a superspeed port will power-off. + +2. Port resume is sequenced to force a superspeed port to power-on prior to its + highspeed peer. + +3. Port resume always triggers an attached child device to resume. After a + power session is lost the device may have been removed, or need reset. + Resuming the child device when the parent port regains power resolves those + states and clamps the maximum port power cycle frequency at the rate the + child device can suspend (autosuspend-delay) and resume (reset-resume + latency). + +Sysfs files relevant for port power control: + + ``/power/pm_qos_no_power_off``: + This writable flag controls the state of an idle port. + Once all children and descendants have suspended the + port may suspend/poweroff provided that + pm_qos_no_power_off is '0'. If pm_qos_no_power_off is + '1' the port will remain active/powered regardless of + the stats of descendants. Defaults to 1. + + ``/power/runtime_status``: + This file reflects whether the port is 'active' (power is on) + or 'suspended' (logically off). There is no indication to + userspace whether VBUS is still supplied. + + ``/connect_type``: + An advisory read-only flag to userspace indicating the + location and connection type of the port. It returns + one of four values 'hotplug', 'hardwired', 'not used', + and 'unknown'. All values, besides unknown, are set by + platform firmware. + + ``hotplug`` indicates an externally connectable/visible + port on the platform. Typically userspace would choose + to keep such a port powered to handle new device + connection events. + + ``hardwired`` refers to a port that is not visible but + connectable. Examples are internal ports for USB + bluetooth that can be disconnected via an external + switch or a port with a hardwired USB camera. It is + expected to be safe to allow these ports to suspend + provided pm_qos_no_power_off is coordinated with any + switch that gates connections. Userspace must arrange + for the device to be connected prior to the port + powering off, or to activate the port prior to enabling + connection via a switch. + + ``not used`` refers to an internal port that is expected + to never have a device connected to it. These may be + empty internal ports, or ports that are not physically + exposed on a platform. Considered safe to be + powered-off at all times. + + ``unknown`` means platform firmware does not provide + information for this port. Most commonly refers to + external hub ports which should be considered 'hotplug' + for policy decisions. + + .. note:: + + - since we are relying on the BIOS to get this ACPI + information correct, the USB port descriptions may + be missing or wrong. + + - Take care in clearing ``pm_qos_no_power_off``. Once + power is off this port will + not respond to new connect events. + + Once a child device is attached additional constraints are + applied before the port is allowed to poweroff. + + ``/power/control``: + Must be ``auto``, and the port will not + power down until ``/power/runtime_status`` + reflects the 'suspended' state. Default + value is controlled by child device driver. + + ``/power/persist``: + This defaults to ``1`` for most devices and indicates if + kernel can persist the device's configuration across a + power session loss (suspend / port-power event). When + this value is ``0`` (quirky devices), port poweroff is + disabled. + + ``/driver/unbind``: + Wakeup capable devices will block port poweroff. At + this time the only mechanism to clear the usb-internal + wakeup-capability for an interface device is to unbind + its driver. + +Summary of poweroff pre-requisite settings relative to a port device:: + + echo 0 > power/pm_qos_no_power_off + echo 0 > peer/power/pm_qos_no_power_off # if it exists + echo auto > power/control # this is the default value + echo auto > /power/control + echo 1 > /power/persist # this is the default value + +Suggested Userspace Port Power Policy +------------------------------------- + +As noted above userspace needs to be careful and deliberate about what +ports are enabled for poweroff. + +The default configuration is that all ports start with +``power/pm_qos_no_power_off`` set to ``1`` causing ports to always remain +active. + +Given confidence in the platform firmware's description of the ports +(ACPI _PLD record for a port populates 'connect_type') userspace can +clear pm_qos_no_power_off for all 'not used' ports. The same can be +done for 'hardwired' ports provided poweroff is coordinated with any +connection switch for the port. + +A more aggressive userspace policy is to enable USB port power off for +all ports (set ``/power/pm_qos_no_power_off`` to ``0``) when +some external factor indicates the user has stopped interacting with the +system. For example, a distro may want to enable power off all USB +ports when the screen blanks, and re-power them when the screen becomes +active. Smart phones and tablets may want to power off USB ports when +the user pushes the power button. diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt deleted file mode 100644 index 00e706997130..000000000000 --- a/Documentation/usb/power-management.txt +++ /dev/null @@ -1,772 +0,0 @@ - Power Management for USB - - Alan Stern - - Last-updated: February 2014 - - - Contents: - --------- - * What is Power Management? - * What is Remote Wakeup? - * When is a USB device idle? - * Forms of dynamic PM - * The user interface for dynamic PM - * Changing the default idle-delay time - * Warnings - * The driver interface for Power Management - * The driver interface for autosuspend and autoresume - * Other parts of the driver interface - * Mutual exclusion - * Interaction between dynamic PM and system PM - * xHCI hardware link PM - * USB Port Power Control - * User Interface for Port Power Control - * Suggested Userspace Port Power Policy - - - What is Power Management? - ------------------------- - -Power Management (PM) is the practice of saving energy by suspending -parts of a computer system when they aren't being used. While a -component is "suspended" it is in a nonfunctional low-power state; it -might even be turned off completely. A suspended component can be -"resumed" (returned to a functional full-power state) when the kernel -needs to use it. (There also are forms of PM in which components are -placed in a less functional but still usable state instead of being -suspended; an example would be reducing the CPU's clock rate. This -document will not discuss those other forms.) - -When the parts being suspended include the CPU and most of the rest of -the system, we speak of it as a "system suspend". When a particular -device is turned off while the system as a whole remains running, we -call it a "dynamic suspend" (also known as a "runtime suspend" or -"selective suspend"). This document concentrates mostly on how -dynamic PM is implemented in the USB subsystem, although system PM is -covered to some extent (see Documentation/power/*.txt for more -information about system PM). - -System PM support is present only if the kernel was built with CONFIG_SUSPEND -or CONFIG_HIBERNATION enabled. Dynamic PM support for USB is present whenever -the kernel was built with CONFIG_PM enabled. - -[Historically, dynamic PM support for USB was present only if the -kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on -CONFIG_PM_RUNTIME). Starting with the 3.10 kernel release, dynamic PM support -for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME -enabled. The CONFIG_USB_SUSPEND option had been eliminated.] - - - What is Remote Wakeup? - ---------------------- - -When a device has been suspended, it generally doesn't resume until -the computer tells it to. Likewise, if the entire computer has been -suspended, it generally doesn't resume until the user tells it to, say -by pressing a power button or opening the cover. - -However some devices have the capability of resuming by themselves, or -asking the kernel to resume them, or even telling the entire computer -to resume. This capability goes by several names such as "Wake On -LAN"; we will refer to it generically as "remote wakeup". When a -device is enabled for remote wakeup and it is suspended, it may resume -itself (or send a request to be resumed) in response to some external -event. Examples include a suspended keyboard resuming when a key is -pressed, or a suspended USB hub resuming when a device is plugged in. - - - When is a USB device idle? - -------------------------- - -A device is idle whenever the kernel thinks it's not busy doing -anything important and thus is a candidate for being suspended. The -exact definition depends on the device's driver; drivers are allowed -to declare that a device isn't idle even when there's no actual -communication taking place. (For example, a hub isn't considered idle -unless all the devices plugged into that hub are already suspended.) -In addition, a device isn't considered idle so long as a program keeps -its usbfs file open, whether or not any I/O is going on. - -If a USB device has no driver, its usbfs file isn't open, and it isn't -being accessed through sysfs, then it definitely is idle. - - - Forms of dynamic PM - ------------------- - -Dynamic suspends occur when the kernel decides to suspend an idle -device. This is called "autosuspend" for short. In general, a device -won't be autosuspended unless it has been idle for some minimum period -of time, the so-called idle-delay time. - -Of course, nothing the kernel does on its own initiative should -prevent the computer or its devices from working properly. If a -device has been autosuspended and a program tries to use it, the -kernel will automatically resume the device (autoresume). For the -same reason, an autosuspended device will usually have remote wakeup -enabled, if the device supports remote wakeup. - -It is worth mentioning that many USB drivers don't support -autosuspend. In fact, at the time of this writing (Linux 2.6.23) the -only drivers which do support it are the hub driver, kaweth, asix, -usblp, usblcd, and usb-skeleton (which doesn't count). If a -non-supporting driver is bound to a device, the device won't be -autosuspended. In effect, the kernel pretends the device is never -idle. - -We can categorize power management events in two broad classes: -external and internal. External events are those triggered by some -agent outside the USB stack: system suspend/resume (triggered by -userspace), manual dynamic resume (also triggered by userspace), and -remote wakeup (triggered by the device). Internal events are those -triggered within the USB stack: autosuspend and autoresume. Note that -all dynamic suspend events are internal; external agents are not -allowed to issue dynamic suspends. - - - The user interface for dynamic PM - --------------------------------- - -The user interface for controlling dynamic PM is located in the power/ -subdirectory of each USB device's sysfs directory, that is, in -/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The -relevant attribute files are: wakeup, control, and -autosuspend_delay_ms. (There may also be a file named "level"; this -file was deprecated as of the 2.6.35 kernel and replaced by the -"control" file. In 2.6.38 the "autosuspend" file will be deprecated -and replaced by the "autosuspend_delay_ms" file. The only difference -is that the newer file expresses the delay in milliseconds whereas the -older file uses seconds. Confusingly, both files are present in 2.6.37 -but only "autosuspend" works.) - - power/wakeup - - This file is empty if the device does not support - remote wakeup. Otherwise the file contains either the - word "enabled" or the word "disabled", and you can - write those words to the file. The setting determines - whether or not remote wakeup will be enabled when the - device is next suspended. (If the setting is changed - while the device is suspended, the change won't take - effect until the following suspend.) - - power/control - - This file contains one of two words: "on" or "auto". - You can write those words to the file to change the - device's setting. - - "on" means that the device should be resumed and - autosuspend is not allowed. (Of course, system - suspends are still allowed.) - - "auto" is the normal state in which the kernel is - allowed to autosuspend and autoresume the device. - - (In kernels up to 2.6.32, you could also specify - "suspend", meaning that the device should remain - suspended and autoresume was not allowed. This - setting is no longer supported.) - - power/autosuspend_delay_ms - - This file contains an integer value, which is the - number of milliseconds the device should remain idle - before the kernel will autosuspend it (the idle-delay - time). The default is 2000. 0 means to autosuspend - as soon as the device becomes idle, and negative - values mean never to autosuspend. You can write a - number to the file to change the autosuspend - idle-delay time. - -Writing "-1" to power/autosuspend_delay_ms and writing "on" to -power/control do essentially the same thing -- they both prevent the -device from being autosuspended. Yes, this is a redundancy in the -API. - -(In 2.6.21 writing "0" to power/autosuspend would prevent the device -from being autosuspended; the behavior was changed in 2.6.22. The -power/autosuspend attribute did not exist prior to 2.6.21, and the -power/level attribute did not exist prior to 2.6.22. power/control -was added in 2.6.34, and power/autosuspend_delay_ms was added in -2.6.37 but did not become functional until 2.6.38.) - - - Changing the default idle-delay time - ------------------------------------ - -The default autosuspend idle-delay time (in seconds) is controlled by -a module parameter in usbcore. You can specify the value when usbcore -is loaded. For example, to set it to 5 seconds instead of 2 you would -do: - - modprobe usbcore autosuspend=5 - -Equivalently, you could add to a configuration file in /etc/modprobe.d -a line saying: - - options usbcore autosuspend=5 - -Some distributions load the usbcore module very early during the boot -process, by means of a program or script running from an initramfs -image. To alter the parameter value you would have to rebuild that -image. - -If usbcore is compiled into the kernel rather than built as a loadable -module, you can add - - usbcore.autosuspend=5 - -to the kernel's boot command line. - -Finally, the parameter value can be changed while the system is -running. If you do: - - echo 5 >/sys/module/usbcore/parameters/autosuspend - -then each new USB device will have its autosuspend idle-delay -initialized to 5. (The idle-delay values for already existing devices -will not be affected.) - -Setting the initial default idle-delay to -1 will prevent any -autosuspend of any USB device. This has the benefit of allowing you -then to enable autosuspend for selected devices. - - - Warnings - -------- - -The USB specification states that all USB devices must support power -management. Nevertheless, the sad fact is that many devices do not -support it very well. You can suspend them all right, but when you -try to resume them they disconnect themselves from the USB bus or -they stop working entirely. This seems to be especially prevalent -among printers and scanners, but plenty of other types of device have -the same deficiency. - -For this reason, by default the kernel disables autosuspend (the -power/control attribute is initialized to "on") for all devices other -than hubs. Hubs, at least, appear to be reasonably well-behaved in -this regard. - -(In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled -by default for almost all USB devices. A number of people experienced -problems as a result.) - -This means that non-hub devices won't be autosuspended unless the user -or a program explicitly enables it. As of this writing there aren't -any widespread programs which will do this; we hope that in the near -future device managers such as HAL will take on this added -responsibility. In the meantime you can always carry out the -necessary operations by hand or add them to a udev script. You can -also change the idle-delay time; 2 seconds is not the best choice for -every device. - -If a driver knows that its device has proper suspend/resume support, -it can enable autosuspend all by itself. For example, the video -driver for a laptop's webcam might do this (in recent kernels they -do), since these devices are rarely used and so should normally be -autosuspended. - -Sometimes it turns out that even when a device does work okay with -autosuspend there are still problems. For example, the usbhid driver, -which manages keyboards and mice, has autosuspend support. Tests with -a number of keyboards show that typing on a suspended keyboard, while -causing the keyboard to do a remote wakeup all right, will nonetheless -frequently result in lost keystrokes. Tests with mice show that some -of them will issue a remote-wakeup request in response to button -presses but not to motion, and some in response to neither. - -The kernel will not prevent you from enabling autosuspend on devices -that can't handle it. It is even possible in theory to damage a -device by suspending it at the wrong time. (Highly unlikely, but -possible.) Take care. - - - The driver interface for Power Management - ----------------------------------------- - -The requirements for a USB driver to support external power management -are pretty modest; the driver need only define - - .suspend - .resume - .reset_resume - -methods in its usb_driver structure, and the reset_resume method is -optional. The methods' jobs are quite simple: - - The suspend method is called to warn the driver that the - device is going to be suspended. If the driver returns a - negative error code, the suspend will be aborted. Normally - the driver will return 0, in which case it must cancel all - outstanding URBs (usb_kill_urb()) and not submit any more. - - The resume method is called to tell the driver that the - device has been resumed and the driver can return to normal - operation. URBs may once more be submitted. - - The reset_resume method is called to tell the driver that - the device has been resumed and it also has been reset. - The driver should redo any necessary device initialization, - since the device has probably lost most or all of its state - (although the interfaces will be in the same altsettings as - before the suspend). - -If the device is disconnected or powered down while it is suspended, -the disconnect method will be called instead of the resume or -reset_resume method. This is also quite likely to happen when -waking up from hibernation, as many systems do not maintain suspend -current to the USB host controllers during hibernation. (It's -possible to work around the hibernation-forces-disconnect problem by -using the USB Persist facility.) - -The reset_resume method is used by the USB Persist facility (see -Documentation/usb/persist.txt) and it can also be used under certain -circumstances when CONFIG_USB_PERSIST is not enabled. Currently, if a -device is reset during a resume and the driver does not have a -reset_resume method, the driver won't receive any notification about -the resume. Later kernels will call the driver's disconnect method; -2.6.23 doesn't do this. - -USB drivers are bound to interfaces, so their suspend and resume -methods get called when the interfaces are suspended or resumed. In -principle one might want to suspend some interfaces on a device (i.e., -force the drivers for those interface to stop all activity) without -suspending the other interfaces. The USB core doesn't allow this; all -interfaces are suspended when the device itself is suspended and all -interfaces are resumed when the device is resumed. It isn't possible -to suspend or resume some but not all of a device's interfaces. The -closest you can come is to unbind the interfaces' drivers. - - - The driver interface for autosuspend and autoresume - --------------------------------------------------- - -To support autosuspend and autoresume, a driver should implement all -three of the methods listed above. In addition, a driver indicates -that it supports autosuspend by setting the .supports_autosuspend flag -in its usb_driver structure. It is then responsible for informing the -USB core whenever one of its interfaces becomes busy or idle. The -driver does so by calling these six functions: - - int usb_autopm_get_interface(struct usb_interface *intf); - void usb_autopm_put_interface(struct usb_interface *intf); - int usb_autopm_get_interface_async(struct usb_interface *intf); - void usb_autopm_put_interface_async(struct usb_interface *intf); - void usb_autopm_get_interface_no_resume(struct usb_interface *intf); - void usb_autopm_put_interface_no_suspend(struct usb_interface *intf); - -The functions work by maintaining a usage counter in the -usb_interface's embedded device structure. When the counter is > 0 -then the interface is deemed to be busy, and the kernel will not -autosuspend the interface's device. When the usage counter is = 0 -then the interface is considered to be idle, and the kernel may -autosuspend the device. - -Drivers need not be concerned about balancing changes to the usage -counter; the USB core will undo any remaining "get"s when a driver -is unbound from its interface. As a corollary, drivers must not call -any of the usb_autopm_* functions after their disconnect() routine has -returned. - -Drivers using the async routines are responsible for their own -synchronization and mutual exclusion. - - usb_autopm_get_interface() increments the usage counter and - does an autoresume if the device is suspended. If the - autoresume fails, the counter is decremented back. - - usb_autopm_put_interface() decrements the usage counter and - attempts an autosuspend if the new value is = 0. - - usb_autopm_get_interface_async() and - usb_autopm_put_interface_async() do almost the same things as - their non-async counterparts. The big difference is that they - use a workqueue to do the resume or suspend part of their - jobs. As a result they can be called in an atomic context, - such as an URB's completion handler, but when they return the - device will generally not yet be in the desired state. - - usb_autopm_get_interface_no_resume() and - usb_autopm_put_interface_no_suspend() merely increment or - decrement the usage counter; they do not attempt to carry out - an autoresume or an autosuspend. Hence they can be called in - an atomic context. - -The simplest usage pattern is that a driver calls -usb_autopm_get_interface() in its open routine and -usb_autopm_put_interface() in its close or release routine. But other -patterns are possible. - -The autosuspend attempts mentioned above will often fail for one -reason or another. For example, the power/control attribute might be -set to "on", or another interface in the same device might not be -idle. This is perfectly normal. If the reason for failure was that -the device hasn't been idle for long enough, a timer is scheduled to -carry out the operation automatically when the autosuspend idle-delay -has expired. - -Autoresume attempts also can fail, although failure would mean that -the device is no longer present or operating properly. Unlike -autosuspend, there's no idle-delay for an autoresume. - - - Other parts of the driver interface - ----------------------------------- - -Drivers can enable autosuspend for their devices by calling - - usb_enable_autosuspend(struct usb_device *udev); - -in their probe() routine, if they know that the device is capable of -suspending and resuming correctly. This is exactly equivalent to -writing "auto" to the device's power/control attribute. Likewise, -drivers can disable autosuspend by calling - - usb_disable_autosuspend(struct usb_device *udev); - -This is exactly the same as writing "on" to the power/control attribute. - -Sometimes a driver needs to make sure that remote wakeup is enabled -during autosuspend. For example, there's not much point -autosuspending a keyboard if the user can't cause the keyboard to do a -remote wakeup by typing on it. If the driver sets -intf->needs_remote_wakeup to 1, the kernel won't autosuspend the -device if remote wakeup isn't available. (If the device is already -autosuspended, though, setting this flag won't cause the kernel to -autoresume it. Normally a driver would set this flag in its probe -method, at which time the device is guaranteed not to be -autosuspended.) - -If a driver does its I/O asynchronously in interrupt context, it -should call usb_autopm_get_interface_async() before starting output and -usb_autopm_put_interface_async() when the output queue drains. When -it receives an input event, it should call - - usb_mark_last_busy(struct usb_device *udev); - -in the event handler. This tells the PM core that the device was just -busy and therefore the next autosuspend idle-delay expiration should -be pushed back. Many of the usb_autopm_* routines also make this call, -so drivers need to worry only when interrupt-driven input arrives. - -Asynchronous operation is always subject to races. For example, a -driver may call the usb_autopm_get_interface_async() routine at a time -when the core has just finished deciding the device has been idle for -long enough but not yet gotten around to calling the driver's suspend -method. The suspend method must be responsible for synchronizing with -the I/O request routine and the URB completion handler; it should -cause autosuspends to fail with -EBUSY if the driver needs to use the -device. - -External suspend calls should never be allowed to fail in this way, -only autosuspend calls. The driver can tell them apart by applying -the PMSG_IS_AUTO() macro to the message argument to the suspend -method; it will return True for internal PM events (autosuspend) and -False for external PM events. - - - Mutual exclusion - ---------------- - -For external events -- but not necessarily for autosuspend or -autoresume -- the device semaphore (udev->dev.sem) will be held when a -suspend or resume method is called. This implies that external -suspend/resume events are mutually exclusive with calls to probe, -disconnect, pre_reset, and post_reset; the USB core guarantees that -this is true of autosuspend/autoresume events as well. - -If a driver wants to block all suspend/resume calls during some -critical section, the best way is to lock the device and call -usb_autopm_get_interface() (and do the reverse at the end of the -critical section). Holding the device semaphore will block all -external PM calls, and the usb_autopm_get_interface() will prevent any -internal PM calls, even if it fails. (Exercise: Why?) - - - Interaction between dynamic PM and system PM - -------------------------------------------- - -Dynamic power management and system power management can interact in -a couple of ways. - -Firstly, a device may already be autosuspended when a system suspend -occurs. Since system suspends are supposed to be as transparent as -possible, the device should remain suspended following the system -resume. But this theory may not work out well in practice; over time -the kernel's behavior in this regard has changed. As of 2.6.37 the -policy is to resume all devices during a system resume and let them -handle their own runtime suspends afterward. - -Secondly, a dynamic power-management event may occur as a system -suspend is underway. The window for this is short, since system -suspends don't take long (a few seconds usually), but it can happen. -For example, a suspended device may send a remote-wakeup signal while -the system is suspending. The remote wakeup may succeed, which would -cause the system suspend to abort. If the remote wakeup doesn't -succeed, it may still remain active and thus cause the system to -resume as soon as the system suspend is complete. Or the remote -wakeup may fail and get lost. Which outcome occurs depends on timing -and on the hardware and firmware design. - - - xHCI hardware link PM - --------------------- - -xHCI host controller provides hardware link power management to usb2.0 -(xHCI 1.0 feature) and usb3.0 devices which support link PM. By -enabling hardware LPM, the host can automatically put the device into -lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices), -which state device can enter and resume very quickly. - -The user interface for controlling hardware LPM is located in the -power/ subdirectory of each USB device's sysfs directory, that is, in -/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The -relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm. - - power/usb2_hardware_lpm - - When a USB2 device which support LPM is plugged to a - xHCI host root hub which support software LPM, the - host will run a software LPM test for it; if the device - enters L1 state and resume successfully and the host - supports USB2 hardware LPM, this file will show up and - driver will enable hardware LPM for the device. You - can write y/Y/1 or n/N/0 to the file to enable/disable - USB2 hardware LPM manually. This is for test purpose mainly. - - power/usb3_hardware_lpm_u1 - power/usb3_hardware_lpm_u2 - - When a USB 3.0 lpm-capable device is plugged in to a - xHCI host which supports link PM, it will check if U1 - and U2 exit latencies have been set in the BOS - descriptor; if the check is passed and the host - supports USB3 hardware LPM, USB3 hardware LPM will be - enabled for the device and these files will be created. - The files hold a string value (enable or disable) - indicating whether or not USB3 hardware LPM U1 or U2 - is enabled for the device. - - USB Port Power Control - ---------------------- - -In addition to suspending endpoint devices and enabling hardware -controlled link power management, the USB subsystem also has the -capability to disable power to ports under some conditions. Power is -controlled through Set/ClearPortFeature(PORT_POWER) requests to a hub. -In the case of a root or platform-internal hub the host controller -driver translates PORT_POWER requests into platform firmware (ACPI) -method calls to set the port power state. For more background see the -Linux Plumbers Conference 2012 slides [1] and video [2]: - -Upon receiving a ClearPortFeature(PORT_POWER) request a USB port is -logically off, and may trigger the actual loss of VBUS to the port [3]. -VBUS may be maintained in the case where a hub gangs multiple ports into -a shared power well causing power to remain until all ports in the gang -are turned off. VBUS may also be maintained by hub ports configured for -a charging application. In any event a logically off port will lose -connection with its device, not respond to hotplug events, and not -respond to remote wakeup events*. - -WARNING: turning off a port may result in the inability to hot add a device. -Please see "User Interface for Port Power Control" for details. - -As far as the effect on the device itself it is similar to what a device -goes through during system suspend, i.e. the power session is lost. Any -USB device or driver that misbehaves with system suspend will be -similarly affected by a port power cycle event. For this reason the -implementation shares the same device recovery path (and honors the same -quirks) as the system resume path for the hub. - -[1]: http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf -[2]: http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/ -[3]: USB 3.1 Section 10.12 -* wakeup note: if a device is configured to send wakeup events the port - power control implementation will block poweroff attempts on that - port. - - - User Interface for Port Power Control - ------------------------------------- - -The port power control mechanism uses the PM runtime system. Poweroff is -requested by clearing the power/pm_qos_no_power_off flag of the port device -(defaults to 1). If the port is disconnected it will immediately receive a -ClearPortFeature(PORT_POWER) request. Otherwise, it will honor the pm runtime -rules and require the attached child device and all descendants to be suspended. -This mechanism is dependent on the hub advertising port power switching in its -hub descriptor (wHubCharacteristics logical power switching mode field). - -Note, some interface devices/drivers do not support autosuspend. Userspace may -need to unbind the interface drivers before the usb_device will suspend. An -unbound interface device is suspended by default. When unbinding, be careful -to unbind interface drivers, not the driver of the parent usb device. Also, -leave hub interface drivers bound. If the driver for the usb device (not -interface) is unbound the kernel is no longer able to resume the device. If a -hub interface driver is unbound, control of its child ports is lost and all -attached child-devices will disconnect. A good rule of thumb is that if the -'driver/module' link for a device points to /sys/module/usbcore then unbinding -it will interfere with port power control. - -Example of the relevant files for port power control. Note, in this example -these files are relative to a usb hub device (prefix). - - prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1 - - attached child device + - hub port device + | - hub interface device + | | - v v v - $prefix/3-1:1.0/3-1-port1/device - - $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off - $prefix/3-1:1.0/3-1-port1/device/power/control - $prefix/3-1:1.0/3-1-port1/device/3-1.1:/driver/unbind - $prefix/3-1:1.0/3-1-port1/device/3-1.1:/driver/unbind - ... - $prefix/3-1:1.0/3-1-port1/device/3-1.1:/driver/unbind - -In addition to these files some ports may have a 'peer' link to a port on -another hub. The expectation is that all superspeed ports have a -hi-speed peer. - -$prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1 -../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1 - -Distinct from 'companion ports', or 'ehci/xhci shared switchover ports' -peer ports are simply the hi-speed and superspeed interface pins that -are combined into a single usb3 connector. Peer ports share the same -ancestor XHCI device. - -While a superspeed port is powered off a device may downgrade its -connection and attempt to connect to the hi-speed pins. The -implementation takes steps to prevent this: - -1/ Port suspend is sequenced to guarantee that hi-speed ports are powered-off - before their superspeed peer is permitted to power-off. The implication is - that the setting pm_qos_no_power_off to zero on a superspeed port may not cause - the port to power-off until its highspeed peer has gone to its runtime suspend - state. Userspace must take care to order the suspensions if it wants to - guarantee that a superspeed port will power-off. - -2/ Port resume is sequenced to force a superspeed port to power-on prior to its - highspeed peer. - -3/ Port resume always triggers an attached child device to resume. After a - power session is lost the device may have been removed, or need reset. - Resuming the child device when the parent port regains power resolves those - states and clamps the maximum port power cycle frequency at the rate the child - device can suspend (autosuspend-delay) and resume (reset-resume latency). - -Sysfs files relevant for port power control: - /power/pm_qos_no_power_off: - This writable flag controls the state of an idle port. - Once all children and descendants have suspended the - port may suspend/poweroff provided that - pm_qos_no_power_off is '0'. If pm_qos_no_power_off is - '1' the port will remain active/powered regardless of - the stats of descendants. Defaults to 1. - - /power/runtime_status: - This file reflects whether the port is 'active' (power is on) - or 'suspended' (logically off). There is no indication to - userspace whether VBUS is still supplied. - - /connect_type: - An advisory read-only flag to userspace indicating the - location and connection type of the port. It returns - one of four values 'hotplug', 'hardwired', 'not used', - and 'unknown'. All values, besides unknown, are set by - platform firmware. - - "hotplug" indicates an externally connectable/visible - port on the platform. Typically userspace would choose - to keep such a port powered to handle new device - connection events. - - "hardwired" refers to a port that is not visible but - connectable. Examples are internal ports for USB - bluetooth that can be disconnected via an external - switch or a port with a hardwired USB camera. It is - expected to be safe to allow these ports to suspend - provided pm_qos_no_power_off is coordinated with any - switch that gates connections. Userspace must arrange - for the device to be connected prior to the port - powering off, or to activate the port prior to enabling - connection via a switch. - - "not used" refers to an internal port that is expected - to never have a device connected to it. These may be - empty internal ports, or ports that are not physically - exposed on a platform. Considered safe to be - powered-off at all times. - - "unknown" means platform firmware does not provide - information for this port. Most commonly refers to - external hub ports which should be considered 'hotplug' - for policy decisions. - - NOTE1: since we are relying on the BIOS to get this ACPI - information correct, the USB port descriptions may be - missing or wrong. - - NOTE2: Take care in clearing pm_qos_no_power_off. Once - power is off this port will - not respond to new connect events. - - Once a child device is attached additional constraints are - applied before the port is allowed to poweroff. - - /power/control: - Must be 'auto', and the port will not - power down until /power/runtime_status - reflects the 'suspended' state. Default - value is controlled by child device driver. - - /power/persist: - This defaults to '1' for most devices and indicates if - kernel can persist the device's configuration across a - power session loss (suspend / port-power event). When - this value is '0' (quirky devices), port poweroff is - disabled. - - /driver/unbind: - Wakeup capable devices will block port poweroff. At - this time the only mechanism to clear the usb-internal - wakeup-capability for an interface device is to unbind - its driver. - -Summary of poweroff pre-requisite settings relative to a port device: - - echo 0 > power/pm_qos_no_power_off - echo 0 > peer/power/pm_qos_no_power_off # if it exists - echo auto > power/control # this is the default value - echo auto > /power/control - echo 1 > /power/persist # this is the default value - - Suggested Userspace Port Power Policy - ------------------------------------- - -As noted above userspace needs to be careful and deliberate about what -ports are enabled for poweroff. - -The default configuration is that all ports start with -power/pm_qos_no_power_off set to '1' causing ports to always remain -active. - -Given confidence in the platform firmware's description of the ports -(ACPI _PLD record for a port populates 'connect_type') userspace can -clear pm_qos_no_power_off for all 'not used' ports. The same can be -done for 'hardwired' ports provided poweroff is coordinated with any -connection switch for the port. - -A more aggressive userspace policy is to enable USB port power off for -all ports (set /power/pm_qos_no_power_off to '0') when -some external factor indicates the user has stopped interacting with the -system. For example, a distro may want to enable power off all USB -ports when the screen blanks, and re-power them when the screen becomes -active. Smart phones and tablets may want to power off USB ports when -the user pushes the power button. -- cgit v1.2.3-55-g7522 From 2a373331dd7405f7a1d6bfd21e5e9b4465350c34 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:06 -0300 Subject: usb/dma.txt: convert to ReST and add to driver-api book This document describe some USB core features. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/dma.rst | 136 +++++++++++++++++++++++++++++++++ Documentation/driver-api/usb/index.rst | 1 + Documentation/usb/dma.txt | 133 -------------------------------- 3 files changed, 137 insertions(+), 133 deletions(-) create mode 100644 Documentation/driver-api/usb/dma.rst delete mode 100644 Documentation/usb/dma.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst new file mode 100644 index 000000000000..59d5aee89e37 --- /dev/null +++ b/Documentation/driver-api/usb/dma.rst @@ -0,0 +1,136 @@ +USB DMA +~~~~~~~ + +In Linux 2.5 kernels (and later), USB device drivers have additional control +over how DMA may be used to perform I/O operations. The APIs are detailed +in the kernel usb programming guide (kerneldoc, from the source code). + +API overview +============ + +The big picture is that USB drivers can continue to ignore most DMA issues, +though they still must provide DMA-ready buffers (see +``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through +the 2.4 (and earlier) kernels, or they can now be DMA-aware. + +DMA-aware usb drivers: + +- New calls enable DMA-aware drivers, letting them allocate dma buffers and + manage dma mappings for existing dma-ready buffers (see below). + +- URBs have an additional "transfer_dma" field, as well as a transfer_flags + bit saying if it's valid. (Control requests also have "setup_dma", but + drivers must not use it.) + +- "usbcore" will map this DMA address, if a DMA-aware driver didn't do + it first and set ``URB_NO_TRANSFER_DMA_MAP``. HCDs + don't manage dma mappings for URBs. + +- There's a new "generic DMA API", parts of which are usable by USB device + drivers. Never use dma_set_mask() on any USB interface or device; that + would potentially break all devices sharing that bus. + +Eliminating copies +================== + +It's good to avoid making CPUs copy data needlessly. The costs can add up, +and effects like cache-trashing can impose subtle penalties. + +- If you're doing lots of small data transfers from the same buffer all + the time, that can really burn up resources on systems which use an + IOMMU to manage the DMA mappings. It can cost MUCH more to set up and + tear down the IOMMU mappings with each request than perform the I/O! + + For those specific cases, USB has primitives to allocate less expensive + memory. They work like kmalloc and kfree versions that give you the right + kind of addresses to store in urb->transfer_buffer and urb->transfer_dma. + You'd also set ``URB_NO_TRANSFER_DMA_MAP`` in urb->transfer_flags:: + + void *usb_alloc_coherent (struct usb_device *dev, size_t size, + int mem_flags, dma_addr_t *dma); + + void usb_free_coherent (struct usb_device *dev, size_t size, + void *addr, dma_addr_t dma); + + Most drivers should **NOT** be using these primitives; they don't need + to use this type of memory ("dma-coherent"), and memory returned from + :c:func:`kmalloc` will work just fine. + + The memory buffer returned is "dma-coherent"; sometimes you might need to + force a consistent memory access ordering by using memory barriers. It's + not using a streaming DMA mapping, so it's good for small transfers on + systems where the I/O would otherwise thrash an IOMMU mapping. (See + ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and + "streaming" DMA mappings.) + + Asking for 1/Nth of a page (as well as asking for N pages) is reasonably + space-efficient. + + On most systems the memory returned will be uncached, because the + semantics of dma-coherent memory require either bypassing CPU caches + or using cache hardware with bus-snooping support. While x86 hardware + has such bus-snooping, many other systems use software to flush cache + lines to prevent DMA conflicts. + +- Devices on some EHCI controllers could handle DMA to/from high memory. + + Unfortunately, the current Linux DMA infrastructure doesn't have a sane + way to expose these capabilities ... and in any case, HIGHMEM is mostly a + design wart specific to x86_32. So your best bet is to ensure you never + pass a highmem buffer into a USB driver. That's easy; it's the default + behavior. Just don't override it; e.g. with ``NETIF_F_HIGHDMA``. + + This may force your callers to do some bounce buffering, copying from + high memory to "normal" DMA memory. If you can come up with a good way + to fix this issue (for x86_32 machines with over 1 GByte of memory), + feel free to submit patches. + +Working with existing buffers +============================= + +Existing buffers aren't usable for DMA without first being mapped into the +DMA address space of the device. However, most buffers passed to your +driver can safely be used with such DMA mapping. (See the first section +of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") + +- When you're using scatterlists, you can map everything at once. On some + systems, this kicks in an IOMMU and turns the scatterlists into single + DMA transactions:: + + int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe, + struct scatterlist *sg, int nents); + + void usb_buffer_dmasync_sg (struct usb_device *dev, unsigned pipe, + struct scatterlist *sg, int n_hw_ents); + + void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe, + struct scatterlist *sg, int n_hw_ents); + + It's probably easier to use the new ``usb_sg_*()`` calls, which do the DMA + mapping and apply other tweaks to make scatterlist i/o be fast. + +- Some drivers may prefer to work with the model that they're mapping large + buffers, synchronizing their safe re-use. (If there's no re-use, then let + usbcore do the map/unmap.) Large periodic transfers make good examples + here, since it's cheaper to just synchronize the buffer than to unmap it + each time an urb completes and then re-map it on during resubmission. + + These calls all work with initialized urbs: ``urb->dev``, ``urb->pipe``, + ``urb->transfer_buffer``, and ``urb->transfer_buffer_length`` must all be + valid when these calls are used (``urb->setup_packet`` must be valid too + if urb is a control request):: + + struct urb *usb_buffer_map (struct urb *urb); + + void usb_buffer_dmasync (struct urb *urb); + + void usb_buffer_unmap (struct urb *urb); + + The calls manage ``urb->transfer_dma`` for you, and set + ``URB_NO_TRANSFER_DMA_MAP`` so that usbcore won't map or unmap the buffer. + They cannot be used for setup_packet buffers in control requests. + +Note that several of those interfaces are currently commented out, since +they don't have current users. See the source code. Other than the dmasync +calls (where the underlying DMA primitives have changed), most of them can +easily be commented back in if you want to use them. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 23c76c17fc19..d7610777784b 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -9,6 +9,7 @@ Linux USB API anchors bulk-streams callbacks + dma power-management writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/usb/dma.txt b/Documentation/usb/dma.txt deleted file mode 100644 index 444651e70d95..000000000000 --- a/Documentation/usb/dma.txt +++ /dev/null @@ -1,133 +0,0 @@ -In Linux 2.5 kernels (and later), USB device drivers have additional control -over how DMA may be used to perform I/O operations. The APIs are detailed -in the kernel usb programming guide (kerneldoc, from the source code). - - -API OVERVIEW - -The big picture is that USB drivers can continue to ignore most DMA issues, -though they still must provide DMA-ready buffers (see -Documentation/DMA-API-HOWTO.txt). That's how they've worked through -the 2.4 (and earlier) kernels. - -OR: they can now be DMA-aware. - -- New calls enable DMA-aware drivers, letting them allocate dma buffers and - manage dma mappings for existing dma-ready buffers (see below). - -- URBs have an additional "transfer_dma" field, as well as a transfer_flags - bit saying if it's valid. (Control requests also have "setup_dma", but - drivers must not use it.) - -- "usbcore" will map this DMA address, if a DMA-aware driver didn't do - it first and set URB_NO_TRANSFER_DMA_MAP. HCDs - don't manage dma mappings for URBs. - -- There's a new "generic DMA API", parts of which are usable by USB device - drivers. Never use dma_set_mask() on any USB interface or device; that - would potentially break all devices sharing that bus. - - -ELIMINATING COPIES - -It's good to avoid making CPUs copy data needlessly. The costs can add up, -and effects like cache-trashing can impose subtle penalties. - -- If you're doing lots of small data transfers from the same buffer all - the time, that can really burn up resources on systems which use an - IOMMU to manage the DMA mappings. It can cost MUCH more to set up and - tear down the IOMMU mappings with each request than perform the I/O! - - For those specific cases, USB has primitives to allocate less expensive - memory. They work like kmalloc and kfree versions that give you the right - kind of addresses to store in urb->transfer_buffer and urb->transfer_dma. - You'd also set URB_NO_TRANSFER_DMA_MAP in urb->transfer_flags: - - void *usb_alloc_coherent (struct usb_device *dev, size_t size, - int mem_flags, dma_addr_t *dma); - - void usb_free_coherent (struct usb_device *dev, size_t size, - void *addr, dma_addr_t dma); - - Most drivers should *NOT* be using these primitives; they don't need - to use this type of memory ("dma-coherent"), and memory returned from - kmalloc() will work just fine. - - The memory buffer returned is "dma-coherent"; sometimes you might need to - force a consistent memory access ordering by using memory barriers. It's - not using a streaming DMA mapping, so it's good for small transfers on - systems where the I/O would otherwise thrash an IOMMU mapping. (See - Documentation/DMA-API-HOWTO.txt for definitions of "coherent" and - "streaming" DMA mappings.) - - Asking for 1/Nth of a page (as well as asking for N pages) is reasonably - space-efficient. - - On most systems the memory returned will be uncached, because the - semantics of dma-coherent memory require either bypassing CPU caches - or using cache hardware with bus-snooping support. While x86 hardware - has such bus-snooping, many other systems use software to flush cache - lines to prevent DMA conflicts. - -- Devices on some EHCI controllers could handle DMA to/from high memory. - - Unfortunately, the current Linux DMA infrastructure doesn't have a sane - way to expose these capabilities ... and in any case, HIGHMEM is mostly a - design wart specific to x86_32. So your best bet is to ensure you never - pass a highmem buffer into a USB driver. That's easy; it's the default - behavior. Just don't override it; e.g. with NETIF_F_HIGHDMA. - - This may force your callers to do some bounce buffering, copying from - high memory to "normal" DMA memory. If you can come up with a good way - to fix this issue (for x86_32 machines with over 1 GByte of memory), - feel free to submit patches. - - -WORKING WITH EXISTING BUFFERS - -Existing buffers aren't usable for DMA without first being mapped into the -DMA address space of the device. However, most buffers passed to your -driver can safely be used with such DMA mapping. (See the first section -of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") - -- When you're using scatterlists, you can map everything at once. On some - systems, this kicks in an IOMMU and turns the scatterlists into single - DMA transactions: - - int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int nents); - - void usb_buffer_dmasync_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int n_hw_ents); - - void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int n_hw_ents); - - It's probably easier to use the new usb_sg_*() calls, which do the DMA - mapping and apply other tweaks to make scatterlist i/o be fast. - -- Some drivers may prefer to work with the model that they're mapping large - buffers, synchronizing their safe re-use. (If there's no re-use, then let - usbcore do the map/unmap.) Large periodic transfers make good examples - here, since it's cheaper to just synchronize the buffer than to unmap it - each time an urb completes and then re-map it on during resubmission. - - These calls all work with initialized urbs: urb->dev, urb->pipe, - urb->transfer_buffer, and urb->transfer_buffer_length must all be - valid when these calls are used (urb->setup_packet must be valid too - if urb is a control request): - - struct urb *usb_buffer_map (struct urb *urb); - - void usb_buffer_dmasync (struct urb *urb); - - void usb_buffer_unmap (struct urb *urb); - - The calls manage urb->transfer_dma for you, and set URB_NO_TRANSFER_DMA_MAP - so that usbcore won't map or unmap the buffer. They cannot be used for - setup_packet buffers in control requests. - -Note that several of those interfaces are currently commented out, since -they don't have current users. See the source code. Other than the dmasync -calls (where the underlying DMA primitives have changed), most of them can -easily be commented back in if you want to use them. -- cgit v1.2.3-55-g7522 From 360a7b5f57e7734d34bc37574822ce74c5ba5d25 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:07 -0300 Subject: error-codes.rst: convert to ReST and add to driver-api book This document describe some USB core features. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/error-codes.rst | 205 +++++++++++++++++++++++++++ Documentation/driver-api/usb/index.rst | 1 + Documentation/usb/error-codes.txt | 175 ----------------------- 3 files changed, 206 insertions(+), 175 deletions(-) create mode 100644 Documentation/driver-api/usb/error-codes.rst delete mode 100644 Documentation/usb/error-codes.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/error-codes.rst b/Documentation/driver-api/usb/error-codes.rst new file mode 100644 index 000000000000..9c11a0fd16cb --- /dev/null +++ b/Documentation/driver-api/usb/error-codes.rst @@ -0,0 +1,205 @@ +USB Error codes +~~~~~~~~~~~~~~~ + +:Revised: 2004-Oct-21 + +This is the documentation of (hopefully) all possible error codes (and +their interpretation) that can be returned from usbcore. + +Some of them are returned by the Host Controller Drivers (HCDs), which +device drivers only see through usbcore. As a rule, all the HCDs should +behave the same except for transfer speed dependent behaviors and the +way certain faults are reported. + + +Error codes returned by :c:func:`usb_submit_urb` +================================================ + +Non-USB-specific: + + +=============== =============================================== +0 URB submission went fine + +``-ENOMEM`` no memory for allocation of internal structures +=============== =============================================== + +USB-specific: + +======================= ======================================================= +``-EBUSY`` The URB is already active. + +``-ENODEV`` specified USB-device or bus doesn't exist + +``-ENOENT`` specified interface or endpoint does not exist or + is not enabled + +``-ENXIO`` host controller driver does not support queuing of + this type of urb. (treat as a host controller bug.) + +``-EINVAL`` a) Invalid transfer type specified (or not supported) + b) Invalid or unsupported periodic transfer interval + c) ISO: attempted to change transfer interval + d) ISO: ``number_of_packets`` is < 0 + e) various other cases + +``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the + frames the URB would be scheduled in have already + expired. + +``-EFBIG`` Host controller driver can't schedule that many ISO + frames. + +``-EPIPE`` The pipe type specified in the URB doesn't match the + endpoint's actual type. + +``-EMSGSIZE`` (a) endpoint maxpacket size is zero; it is not usable + in the current interface altsetting. + (b) ISO packet is larger than the endpoint maxpacket. + (c) requested data transfer length is invalid: negative + or too large for the host controller. + +``-ENOSPC`` This request would overcommit the usb bandwidth reserved + for periodic transfers (interrupt, isochronous). + +``-ESHUTDOWN`` The device or host controller has been disabled due to + some problem that could not be worked around. + +``-EPERM`` Submission failed because ``urb->reject`` was set. + +``-EHOSTUNREACH`` URB was rejected because the device is suspended. + +``-ENOEXEC`` A control URB doesn't contain a Setup packet. +======================= ======================================================= + +Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO) +======================================================================================= + +USB device drivers may only test urb status values in completion handlers. +This is because otherwise there would be a race between HCDs updating +these values on one CPU, and device drivers testing them on another CPU. + +A transfer's actual_length may be positive even when an error has been +reported. That's because transfers often involve several packets, so that +one or more packets could finish before an error stops further endpoint I/O. + +For isochronous URBs, the urb status value is non-zero only if the URB is +unlinked, the device is removed, the host controller is disabled, or the total +transferred length is less than the requested length and the +``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs +should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``, +``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields +may report more status codes. + + +=============================== =============================================== +0 Transfer completed successfully + +``-ENOENT`` URB was synchronously unlinked by + :c:func:`usb_unlink_urb` + +``-EINPROGRESS`` URB still pending, no results yet + (That is, if drivers see this it's a bug.) + +``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error + b) no response packet received within the + prescribed bus turn-around time + c) unknown USB error + +``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch + b) no response packet received within the + prescribed bus turn-around time + c) unknown USB error + + Note that often the controller hardware does + not distinguish among cases a), b), and c), so + a driver cannot tell whether there was a + protocol error, a failure to respond (often + caused by device disconnect), or some other + fault. + +``-ETIME`` [#f2]_ No response packet received within the + prescribed bus turn-around time. This error + may instead be reported as + ``-EPROTO`` or ``-EILSEQ``. + +``-ETIMEDOUT`` Synchronous USB message functions use this code + to indicate timeout expired before the transfer + completed, and no other error was reported + by HC. + +``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints, + reset this status with + :c:func:`usb_clear_halt`. + +``-ECOMM`` During an IN transfer, the host controller + received data from an endpoint faster than it + could be written to system memory + +``-ENOSR`` During an OUT transfer, the host controller + could not retrieve data from system memory fast + enough to keep up with the USB data rate + +``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was + greater than either the max packet size of the + endpoint or the remaining buffer size. + "Babble". + +``-EREMOTEIO`` The data read from the endpoint did not fill + the specified buffer, and ``URB_SHORT_NOT_OK`` + was set in ``urb->transfer_flags``. + +``-ENODEV`` Device was removed. Often preceded by a burst + of other errors, since the hub driver doesn't + detect device removal events immediately. + +``-EXDEV`` ISO transfer only partially completed + (only set in ``iso_frame_desc[n].status``, + not ``urb->status``) + +``-EINVAL`` ISO madness, if this happens: Log off and + go home + +``-ECONNRESET`` URB was asynchronously unlinked by + :c:func:`usb_unlink_urb` + +``-ESHUTDOWN`` The device or host controller has been + disabled due to some problem that could not + be worked around, such as a physical + disconnect. +=============================== =============================================== + + +.. [#f1] + + Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally + indicate hardware problems such as bad devices (including firmware) + or cables. + +.. [#f2] + + This is also one of several codes that different kinds of host + controller use to indicate a transfer has failed because of device + disconnect. In the interval before the hub driver starts disconnect + processing, devices may receive such fault reports for every request. + + + +Error codes returned by usbcore-functions +========================================= + +.. note:: expect also other submit and transfer status codes + +:c:func:`usb_register`: + +======================= =================================== +``-EINVAL`` error during registering new driver +======================= =================================== + +``usb_get_*/usb_set_*()``, +:c:func:`usb_control_msg`, +:c:func:`usb_bulk_msg()`: + +======================= ============================================== +``-ETIMEDOUT`` Timeout expired before the transfer completed. +======================= ============================================== diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index d7610777784b..1e2a0c54eb3d 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -11,6 +11,7 @@ Linux USB API callbacks dma power-management + error-codes writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/usb/error-codes.txt b/Documentation/usb/error-codes.txt deleted file mode 100644 index 9c3eb845ebe5..000000000000 --- a/Documentation/usb/error-codes.txt +++ /dev/null @@ -1,175 +0,0 @@ -Revised: 2004-Oct-21 - -This is the documentation of (hopefully) all possible error codes (and -their interpretation) that can be returned from usbcore. - -Some of them are returned by the Host Controller Drivers (HCDs), which -device drivers only see through usbcore. As a rule, all the HCDs should -behave the same except for transfer speed dependent behaviors and the -way certain faults are reported. - - -************************************************************************** -* Error codes returned by usb_submit_urb * -************************************************************************** - -Non-USB-specific: - -0 URB submission went fine - --ENOMEM no memory for allocation of internal structures - -USB-specific: - --EBUSY The URB is already active. - --ENODEV specified USB-device or bus doesn't exist - --ENOENT specified interface or endpoint does not exist or - is not enabled - --ENXIO host controller driver does not support queuing of this type - of urb. (treat as a host controller bug.) - --EINVAL a) Invalid transfer type specified (or not supported) - b) Invalid or unsupported periodic transfer interval - c) ISO: attempted to change transfer interval - d) ISO: number_of_packets is < 0 - e) various other cases - --EXDEV ISO: URB_ISO_ASAP wasn't specified and all the frames - the URB would be scheduled in have already expired. - --EFBIG Host controller driver can't schedule that many ISO frames. - --EPIPE The pipe type specified in the URB doesn't match the - endpoint's actual type. - --EMSGSIZE (a) endpoint maxpacket size is zero; it is not usable - in the current interface altsetting. - (b) ISO packet is larger than the endpoint maxpacket. - (c) requested data transfer length is invalid: negative - or too large for the host controller. - --ENOSPC This request would overcommit the usb bandwidth reserved - for periodic transfers (interrupt, isochronous). - --ESHUTDOWN The device or host controller has been disabled due to some - problem that could not be worked around. - --EPERM Submission failed because urb->reject was set. - --EHOSTUNREACH URB was rejected because the device is suspended. - --ENOEXEC A control URB doesn't contain a Setup packet. - - -************************************************************************** -* Error codes returned by in urb->status * -* or in iso_frame_desc[n].status (for ISO) * -************************************************************************** - -USB device drivers may only test urb status values in completion handlers. -This is because otherwise there would be a race between HCDs updating -these values on one CPU, and device drivers testing them on another CPU. - -A transfer's actual_length may be positive even when an error has been -reported. That's because transfers often involve several packets, so that -one or more packets could finish before an error stops further endpoint I/O. - -For isochronous URBs, the urb status value is non-zero only if the URB is -unlinked, the device is removed, the host controller is disabled, or the total -transferred length is less than the requested length and the URB_SHORT_NOT_OK -flag is set. Completion handlers for isochronous URBs should only see -urb->status set to zero, -ENOENT, -ECONNRESET, -ESHUTDOWN, or -EREMOTEIO. -Individual frame descriptor status fields may report more status codes. - - -0 Transfer completed successfully - --ENOENT URB was synchronously unlinked by usb_unlink_urb - --EINPROGRESS URB still pending, no results yet - (That is, if drivers see this it's a bug.) - --EPROTO (*, **) a) bitstuff error - b) no response packet received within the - prescribed bus turn-around time - c) unknown USB error - --EILSEQ (*, **) a) CRC mismatch - b) no response packet received within the - prescribed bus turn-around time - c) unknown USB error - - Note that often the controller hardware does not - distinguish among cases a), b), and c), so a - driver cannot tell whether there was a protocol - error, a failure to respond (often caused by - device disconnect), or some other fault. - --ETIME (**) No response packet received within the prescribed - bus turn-around time. This error may instead be - reported as -EPROTO or -EILSEQ. - --ETIMEDOUT Synchronous USB message functions use this code - to indicate timeout expired before the transfer - completed, and no other error was reported by HC. - --EPIPE (**) Endpoint stalled. For non-control endpoints, - reset this status with usb_clear_halt(). - --ECOMM During an IN transfer, the host controller - received data from an endpoint faster than it - could be written to system memory - --ENOSR During an OUT transfer, the host controller - could not retrieve data from system memory fast - enough to keep up with the USB data rate - --EOVERFLOW (*) The amount of data returned by the endpoint was - greater than either the max packet size of the - endpoint or the remaining buffer size. "Babble". - --EREMOTEIO The data read from the endpoint did not fill the - specified buffer, and URB_SHORT_NOT_OK was set in - urb->transfer_flags. - --ENODEV Device was removed. Often preceded by a burst of - other errors, since the hub driver doesn't detect - device removal events immediately. - --EXDEV ISO transfer only partially completed - (only set in iso_frame_desc[n].status, not urb->status) - --EINVAL ISO madness, if this happens: Log off and go home - --ECONNRESET URB was asynchronously unlinked by usb_unlink_urb - --ESHUTDOWN The device or host controller has been disabled due - to some problem that could not be worked around, - such as a physical disconnect. - - -(*) Error codes like -EPROTO, -EILSEQ and -EOVERFLOW normally indicate -hardware problems such as bad devices (including firmware) or cables. - -(**) This is also one of several codes that different kinds of host -controller use to indicate a transfer has failed because of device -disconnect. In the interval before the hub driver starts disconnect -processing, devices may receive such fault reports for every request. - - - -************************************************************************** -* Error codes returned by usbcore-functions * -* (expect also other submit and transfer status codes) * -************************************************************************** - -usb_register(): --EINVAL error during registering new driver - -usb_get_*/usb_set_*(): -usb_control_msg(): -usb_bulk_msg(): --ETIMEDOUT Timeout expired before the transfer completed. -- cgit v1.2.3-55-g7522 From 76f650f077f3edd7001c89da44eade2449e8f495 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:08 -0300 Subject: usb/hotplug.txt: convert to ReST and add to driver-api book This document describe some USB core features. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/hotplug.rst | 154 +++++++++++++++++++++++++++++++ Documentation/driver-api/usb/index.rst | 1 + Documentation/usb/hotplug.txt | 148 ----------------------------- 3 files changed, 155 insertions(+), 148 deletions(-) create mode 100644 Documentation/driver-api/usb/hotplug.rst delete mode 100644 Documentation/usb/hotplug.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/hotplug.rst b/Documentation/driver-api/usb/hotplug.rst new file mode 100644 index 000000000000..79663e653ca1 --- /dev/null +++ b/Documentation/driver-api/usb/hotplug.rst @@ -0,0 +1,154 @@ +USB hotplugging +~~~~~~~~~~~~~~~ + +Linux Hotplugging +================= + + +In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices +into the bus with power on. In most cases, users expect the devices to become +immediately usable. That means the system must do many things, including: + + - Find a driver that can handle the device. That may involve + loading a kernel module; newer drivers can use module-init-tools + to publish their device (and class) support to user utilities. + + - Bind a driver to that device. Bus frameworks do that using a + device driver's probe() routine. + + - Tell other subsystems to configure the new device. Print + queues may need to be enabled, networks brought up, disk + partitions mounted, and so on. In some cases these will + be driver-specific actions. + +This involves a mix of kernel mode and user mode actions. Making devices +be immediately usable means that any user mode actions can't wait for an +administrator to do them: the kernel must trigger them, either passively +(triggering some monitoring daemon to invoke a helper program) or +actively (calling such a user mode helper program directly). + +Those triggered actions must support a system's administrative policies; +such programs are called "policy agents" here. Typically they involve +shell scripts that dispatch to more familiar administration tools. + +Because some of those actions rely on information about drivers (metadata) +that is currently available only when the drivers are dynamically linked, +you get the best hotplugging when you configure a highly modular system. + +Kernel Hotplug Helper (``/sbin/hotplug``) +========================================= + +There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally +holds the pathname ``/sbin/hotplug``. That parameter names a program +which the kernel may invoke at various times. + +The /sbin/hotplug program can be invoked by any subsystem as part of its +reaction to a configuration change, from a thread in that subsystem. +Only one parameter is required: the name of a subsystem being notified of +some kernel event. That name is used as the first key for further event +dispatch; any other argument and environment parameters are specified by +the subsystem making that invocation. + +Hotplug software and other resources is available at: + + http://linux-hotplug.sourceforge.net + +Mailing list information is also available at that site. + + +USB Policy Agent +================ + +The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices +are added or removed from system. The invocation is done by the kernel +hub workqueue [hub_wq], or else as part of root hub initialization +(done by init, modprobe, kapmd, etc). Its single command line parameter +is the string "usb", and it passes these environment variables: + +========== ============================================ +ACTION ``add``, ``remove`` +PRODUCT USB vendor, product, and version codes (hex) +TYPE device class codes (decimal) +INTERFACE interface 0 class codes (decimal) +========== ============================================ + +If "usbdevfs" is configured, DEVICE and DEVFS are also passed. DEVICE is +the pathname of the device, and is useful for devices with multiple and/or +alternate interfaces that complicate driver selection. By design, USB +hotplugging is independent of ``usbdevfs``: you can do most essential parts +of USB device setup without using that filesystem, and without running a +user mode daemon to detect changes in system configuration. + +Currently available policy agent implementations can load drivers for +modules, and can invoke driver-specific setup scripts. The newest ones +leverage USB module-init-tools support. Later agents might unload drivers. + + +USB Modutils Support +==================== + +Current versions of module-init-tools will create a ``modules.usbmap`` file +which contains the entries from each driver's ``MODULE_DEVICE_TABLE``. Such +files can be used by various user mode policy agents to make sure all the +right driver modules get loaded, either at boot time or later. + +See ``linux/usb.h`` for full information about such table entries; or look +at existing drivers. Each table entry describes one or more criteria to +be used when matching a driver to a device or class of devices. The +specific criteria are identified by bits set in "match_flags", paired +with field values. You can construct the criteria directly, or with +macros such as these, and use driver_info to store more information:: + + USB_DEVICE (vendorId, productId) + ... matching devices with specified vendor and product ids + USB_DEVICE_VER (vendorId, productId, lo, hi) + ... like USB_DEVICE with lo <= productversion <= hi + USB_INTERFACE_INFO (class, subclass, protocol) + ... matching specified interface class info + USB_DEVICE_INFO (class, subclass, protocol) + ... matching specified device class info + +A short example, for a driver that supports several specific USB devices +and their quirks, might have a MODULE_DEVICE_TABLE like this:: + + static const struct usb_device_id mydriver_id_table[] = { + { USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X }, + { USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z }, + ... + { } /* end with an all-zeroes entry */ + }; + MODULE_DEVICE_TABLE(usb, mydriver_id_table); + +Most USB device drivers should pass these tables to the USB subsystem as +well as to the module management subsystem. Not all, though: some driver +frameworks connect using interfaces layered over USB, and so they won't +need such a struct :c:type:`usb_driver`. + +Drivers that connect directly to the USB subsystem should be declared +something like this:: + + static struct usb_driver mydriver = { + .name = "mydriver", + .id_table = mydriver_id_table, + .probe = my_probe, + .disconnect = my_disconnect, + + /* + if using the usb chardev framework: + .minor = MY_USB_MINOR_START, + .fops = my_file_ops, + if exposing any operations through usbdevfs: + .ioctl = my_ioctl, + */ + }; + +When the USB subsystem knows about a driver's device ID table, it's used when +choosing drivers to probe(). The thread doing new device processing checks +drivers' device ID entries from the ``MODULE_DEVICE_TABLE`` against interface +and device descriptors for the device. It will only call ``probe()`` if there +is a match, and the third argument to ``probe()`` will be the entry that +matched. + +If you don't provide an ``id_table`` for your driver, then your driver may get +probed for each new device; the third parameter to ``probe()`` will be +``NULL``. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 1e2a0c54eb3d..43f0a8b72b11 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -11,6 +11,7 @@ Linux USB API callbacks dma power-management + hotplug error-codes writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt deleted file mode 100644 index 5b243f315b2c..000000000000 --- a/Documentation/usb/hotplug.txt +++ /dev/null @@ -1,148 +0,0 @@ -LINUX HOTPLUGGING - -In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices -into the bus with power on. In most cases, users expect the devices to become -immediately usable. That means the system must do many things, including: - - - Find a driver that can handle the device. That may involve - loading a kernel module; newer drivers can use module-init-tools - to publish their device (and class) support to user utilities. - - - Bind a driver to that device. Bus frameworks do that using a - device driver's probe() routine. - - - Tell other subsystems to configure the new device. Print - queues may need to be enabled, networks brought up, disk - partitions mounted, and so on. In some cases these will - be driver-specific actions. - -This involves a mix of kernel mode and user mode actions. Making devices -be immediately usable means that any user mode actions can't wait for an -administrator to do them: the kernel must trigger them, either passively -(triggering some monitoring daemon to invoke a helper program) or -actively (calling such a user mode helper program directly). - -Those triggered actions must support a system's administrative policies; -such programs are called "policy agents" here. Typically they involve -shell scripts that dispatch to more familiar administration tools. - -Because some of those actions rely on information about drivers (metadata) -that is currently available only when the drivers are dynamically linked, -you get the best hotplugging when you configure a highly modular system. - - -KERNEL HOTPLUG HELPER (/sbin/hotplug) - -There is a kernel parameter: /proc/sys/kernel/hotplug, which normally -holds the pathname "/sbin/hotplug". That parameter names a program -which the kernel may invoke at various times. - -The /sbin/hotplug program can be invoked by any subsystem as part of its -reaction to a configuration change, from a thread in that subsystem. -Only one parameter is required: the name of a subsystem being notified of -some kernel event. That name is used as the first key for further event -dispatch; any other argument and environment parameters are specified by -the subsystem making that invocation. - -Hotplug software and other resources is available at: - - http://linux-hotplug.sourceforge.net - -Mailing list information is also available at that site. - - --------------------------------------------------------------------------- - - -USB POLICY AGENT - -The USB subsystem currently invokes /sbin/hotplug when USB devices -are added or removed from system. The invocation is done by the kernel -hub workqueue [hub_wq], or else as part of root hub initialization -(done by init, modprobe, kapmd, etc). Its single command line parameter -is the string "usb", and it passes these environment variables: - - ACTION ... "add", "remove" - PRODUCT ... USB vendor, product, and version codes (hex) - TYPE ... device class codes (decimal) - INTERFACE ... interface 0 class codes (decimal) - -If "usbdevfs" is configured, DEVICE and DEVFS are also passed. DEVICE is -the pathname of the device, and is useful for devices with multiple and/or -alternate interfaces that complicate driver selection. By design, USB -hotplugging is independent of "usbdevfs": you can do most essential parts -of USB device setup without using that filesystem, and without running a -user mode daemon to detect changes in system configuration. - -Currently available policy agent implementations can load drivers for -modules, and can invoke driver-specific setup scripts. The newest ones -leverage USB module-init-tools support. Later agents might unload drivers. - - -USB MODUTILS SUPPORT - -Current versions of module-init-tools will create a "modules.usbmap" file -which contains the entries from each driver's MODULE_DEVICE_TABLE. Such -files can be used by various user mode policy agents to make sure all the -right driver modules get loaded, either at boot time or later. - -See for full information about such table entries; or look -at existing drivers. Each table entry describes one or more criteria to -be used when matching a driver to a device or class of devices. The -specific criteria are identified by bits set in "match_flags", paired -with field values. You can construct the criteria directly, or with -macros such as these, and use driver_info to store more information. - - USB_DEVICE (vendorId, productId) - ... matching devices with specified vendor and product ids - USB_DEVICE_VER (vendorId, productId, lo, hi) - ... like USB_DEVICE with lo <= productversion <= hi - USB_INTERFACE_INFO (class, subclass, protocol) - ... matching specified interface class info - USB_DEVICE_INFO (class, subclass, protocol) - ... matching specified device class info - -A short example, for a driver that supports several specific USB devices -and their quirks, might have a MODULE_DEVICE_TABLE like this: - - static const struct usb_device_id mydriver_id_table[] = { - { USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X }, - { USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z }, - ... - { } /* end with an all-zeroes entry */ - }; - MODULE_DEVICE_TABLE(usb, mydriver_id_table); - -Most USB device drivers should pass these tables to the USB subsystem as -well as to the module management subsystem. Not all, though: some driver -frameworks connect using interfaces layered over USB, and so they won't -need such a "struct usb_driver". - -Drivers that connect directly to the USB subsystem should be declared -something like this: - - static struct usb_driver mydriver = { - .name = "mydriver", - .id_table = mydriver_id_table, - .probe = my_probe, - .disconnect = my_disconnect, - - /* - if using the usb chardev framework: - .minor = MY_USB_MINOR_START, - .fops = my_file_ops, - if exposing any operations through usbdevfs: - .ioctl = my_ioctl, - */ - }; - -When the USB subsystem knows about a driver's device ID table, it's used when -choosing drivers to probe(). The thread doing new device processing checks -drivers' device ID entries from the MODULE_DEVICE_TABLE against interface and -device descriptors for the device. It will only call probe() if there is a -match, and the third argument to probe() will be the entry that matched. - -If you don't provide an id_table for your driver, then your driver may get -probed for each new device; the third parameter to probe() will be null. - - -- cgit v1.2.3-55-g7522 From 32a3bebce9d09598d4f4c5afca929a2ce148b8c4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:09 -0300 Subject: usb/persist.txt: convert to ReST and add to driver-api book This document describe some USB core features. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/index.rst | 1 + Documentation/driver-api/usb/persist.rst | 169 +++++++++++++++++++++++++++++++ Documentation/usb/persist.txt | 165 ------------------------------ 3 files changed, 170 insertions(+), 165 deletions(-) create mode 100644 Documentation/driver-api/usb/persist.rst delete mode 100644 Documentation/usb/persist.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 43f0a8b72b11..3f08cb5d5feb 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -12,6 +12,7 @@ Linux USB API dma power-management hotplug + persist error-codes writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/driver-api/usb/persist.rst b/Documentation/driver-api/usb/persist.rst new file mode 100644 index 000000000000..ea1b43f0559e --- /dev/null +++ b/Documentation/driver-api/usb/persist.rst @@ -0,0 +1,169 @@ +USB device persistence during system suspend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:Author: Alan Stern +:Date: September 2, 2006 (Updated February 25, 2008) + + +What is the problem? +==================== + +According to the USB specification, when a USB bus is suspended the +bus must continue to supply suspend current (around 1-5 mA). This +is so that devices can maintain their internal state and hubs can +detect connect-change events (devices being plugged in or unplugged). +The technical term is "power session". + +If a USB device's power session is interrupted then the system is +required to behave as though the device has been unplugged. It's a +conservative approach; in the absence of suspend current the computer +has no way to know what has actually happened. Perhaps the same +device is still attached or perhaps it was removed and a different +device plugged into the port. The system must assume the worst. + +By default, Linux behaves according to the spec. If a USB host +controller loses power during a system suspend, then when the system +wakes up all the devices attached to that controller are treated as +though they had disconnected. This is always safe and it is the +"officially correct" thing to do. + +For many sorts of devices this behavior doesn't matter in the least. +If the kernel wants to believe that your USB keyboard was unplugged +while the system was asleep and a new keyboard was plugged in when the +system woke up, who cares? It'll still work the same when you type on +it. + +Unfortunately problems _can_ arise, particularly with mass-storage +devices. The effect is exactly the same as if the device really had +been unplugged while the system was suspended. If you had a mounted +filesystem on the device, you're out of luck -- everything in that +filesystem is now inaccessible. This is especially annoying if your +root filesystem was located on the device, since your system will +instantly crash. + +Loss of power isn't the only mechanism to worry about. Anything that +interrupts a power session will have the same effect. For example, +even though suspend current may have been maintained while the system +was asleep, on many systems during the initial stages of wakeup the +firmware (i.e., the BIOS) resets the motherboard's USB host +controllers. Result: all the power sessions are destroyed and again +it's as though you had unplugged all the USB devices. Yes, it's +entirely the BIOS's fault, but that doesn't do _you_ any good unless +you can convince the BIOS supplier to fix the problem (lots of luck!). + +On many systems the USB host controllers will get reset after a +suspend-to-RAM. On almost all systems, no suspend current is +available during hibernation (also known as swsusp or suspend-to-disk). +You can check the kernel log after resuming to see if either of these +has happened; look for lines saying "root hub lost power or was reset". + +In practice, people are forced to unmount any filesystems on a USB +device before suspending. If the root filesystem is on a USB device, +the system can't be suspended at all. (All right, it _can_ be +suspended -- but it will crash as soon as it wakes up, which isn't +much better.) + + +What is the solution? +===================== + +The kernel includes a feature called USB-persist. It tries to work +around these issues by allowing the core USB device data structures to +persist across a power-session disruption. + +It works like this. If the kernel sees that a USB host controller is +not in the expected state during resume (i.e., if the controller was +reset or otherwise had lost power) then it applies a persistence check +to each of the USB devices below that controller for which the +"persist" attribute is set. It doesn't try to resume the device; that +can't work once the power session is gone. Instead it issues a USB +port reset and then re-enumerates the device. (This is exactly the +same thing that happens whenever a USB device is reset.) If the +re-enumeration shows that the device now attached to that port has the +same descriptors as before, including the Vendor and Product IDs, then +the kernel continues to use the same device structure. In effect, the +kernel treats the device as though it had merely been reset instead of +unplugged. + +The same thing happens if the host controller is in the expected state +but a USB device was unplugged and then replugged, or if a USB device +fails to carry out a normal resume. + +If no device is now attached to the port, or if the descriptors are +different from what the kernel remembers, then the treatment is what +you would expect. The kernel destroys the old device structure and +behaves as though the old device had been unplugged and a new device +plugged in. + +The end result is that the USB device remains available and usable. +Filesystem mounts and memory mappings are unaffected, and the world is +now a good and happy place. + +Note that the "USB-persist" feature will be applied only to those +devices for which it is enabled. You can enable the feature by doing +(as root):: + + echo 1 >/sys/bus/usb/devices/.../power/persist + +where the "..." should be filled in the with the device's ID. Disable +the feature by writing 0 instead of 1. For hubs the feature is +automatically and permanently enabled and the power/persist file +doesn't even exist, so you only have to worry about setting it for +devices where it really matters. + + +Is this the best solution? +========================== + +Perhaps not. Arguably, keeping track of mounted filesystems and +memory mappings across device disconnects should be handled by a +centralized Logical Volume Manager. Such a solution would allow you +to plug in a USB flash device, create a persistent volume associated +with it, unplug the flash device, plug it back in later, and still +have the same persistent volume associated with the device. As such +it would be more far-reaching than USB-persist. + +On the other hand, writing a persistent volume manager would be a big +job and using it would require significant input from the user. This +solution is much quicker and easier -- and it exists now, a giant +point in its favor! + +Furthermore, the USB-persist feature applies to _all_ USB devices, not +just mass-storage devices. It might turn out to be equally useful for +other device types, such as network interfaces. + + +WARNING: USB-persist can be dangerous!! +======================================= + +When recovering an interrupted power session the kernel does its best +to make sure the USB device hasn't been changed; that is, the same +device is still plugged into the port as before. But the checks +aren't guaranteed to be 100% accurate. + +If you replace one USB device with another of the same type (same +manufacturer, same IDs, and so on) there's an excellent chance the +kernel won't detect the change. The serial number string and other +descriptors are compared with the kernel's stored values, but this +might not help since manufacturers frequently omit serial numbers +entirely in their devices. + +Furthermore it's quite possible to leave a USB device exactly the same +while changing its media. If you replace the flash memory card in a +USB card reader while the system is asleep, the kernel will have no +way to know you did it. The kernel will assume that nothing has +happened and will continue to use the partition tables, inodes, and +memory mappings for the old card. + +If the kernel gets fooled in this way, it's almost certain to cause +data corruption and to crash your system. You'll have no one to blame +but yourself. + +For those devices with avoid_reset_quirk attribute being set, persist +maybe fail because they may morph after reset. + +YOU HAVE BEEN WARNED! USE AT YOUR OWN RISK! + +That having been said, most of the time there shouldn't be any trouble +at all. The USB-persist feature can be extremely useful. Make the +most of it. diff --git a/Documentation/usb/persist.txt b/Documentation/usb/persist.txt deleted file mode 100644 index 35d70eda9ad6..000000000000 --- a/Documentation/usb/persist.txt +++ /dev/null @@ -1,165 +0,0 @@ - USB device persistence during system suspend - - Alan Stern - - September 2, 2006 (Updated February 25, 2008) - - - What is the problem? - -According to the USB specification, when a USB bus is suspended the -bus must continue to supply suspend current (around 1-5 mA). This -is so that devices can maintain their internal state and hubs can -detect connect-change events (devices being plugged in or unplugged). -The technical term is "power session". - -If a USB device's power session is interrupted then the system is -required to behave as though the device has been unplugged. It's a -conservative approach; in the absence of suspend current the computer -has no way to know what has actually happened. Perhaps the same -device is still attached or perhaps it was removed and a different -device plugged into the port. The system must assume the worst. - -By default, Linux behaves according to the spec. If a USB host -controller loses power during a system suspend, then when the system -wakes up all the devices attached to that controller are treated as -though they had disconnected. This is always safe and it is the -"officially correct" thing to do. - -For many sorts of devices this behavior doesn't matter in the least. -If the kernel wants to believe that your USB keyboard was unplugged -while the system was asleep and a new keyboard was plugged in when the -system woke up, who cares? It'll still work the same when you type on -it. - -Unfortunately problems _can_ arise, particularly with mass-storage -devices. The effect is exactly the same as if the device really had -been unplugged while the system was suspended. If you had a mounted -filesystem on the device, you're out of luck -- everything in that -filesystem is now inaccessible. This is especially annoying if your -root filesystem was located on the device, since your system will -instantly crash. - -Loss of power isn't the only mechanism to worry about. Anything that -interrupts a power session will have the same effect. For example, -even though suspend current may have been maintained while the system -was asleep, on many systems during the initial stages of wakeup the -firmware (i.e., the BIOS) resets the motherboard's USB host -controllers. Result: all the power sessions are destroyed and again -it's as though you had unplugged all the USB devices. Yes, it's -entirely the BIOS's fault, but that doesn't do _you_ any good unless -you can convince the BIOS supplier to fix the problem (lots of luck!). - -On many systems the USB host controllers will get reset after a -suspend-to-RAM. On almost all systems, no suspend current is -available during hibernation (also known as swsusp or suspend-to-disk). -You can check the kernel log after resuming to see if either of these -has happened; look for lines saying "root hub lost power or was reset". - -In practice, people are forced to unmount any filesystems on a USB -device before suspending. If the root filesystem is on a USB device, -the system can't be suspended at all. (All right, it _can_ be -suspended -- but it will crash as soon as it wakes up, which isn't -much better.) - - - What is the solution? - -The kernel includes a feature called USB-persist. It tries to work -around these issues by allowing the core USB device data structures to -persist across a power-session disruption. - -It works like this. If the kernel sees that a USB host controller is -not in the expected state during resume (i.e., if the controller was -reset or otherwise had lost power) then it applies a persistence check -to each of the USB devices below that controller for which the -"persist" attribute is set. It doesn't try to resume the device; that -can't work once the power session is gone. Instead it issues a USB -port reset and then re-enumerates the device. (This is exactly the -same thing that happens whenever a USB device is reset.) If the -re-enumeration shows that the device now attached to that port has the -same descriptors as before, including the Vendor and Product IDs, then -the kernel continues to use the same device structure. In effect, the -kernel treats the device as though it had merely been reset instead of -unplugged. - -The same thing happens if the host controller is in the expected state -but a USB device was unplugged and then replugged, or if a USB device -fails to carry out a normal resume. - -If no device is now attached to the port, or if the descriptors are -different from what the kernel remembers, then the treatment is what -you would expect. The kernel destroys the old device structure and -behaves as though the old device had been unplugged and a new device -plugged in. - -The end result is that the USB device remains available and usable. -Filesystem mounts and memory mappings are unaffected, and the world is -now a good and happy place. - -Note that the "USB-persist" feature will be applied only to those -devices for which it is enabled. You can enable the feature by doing -(as root): - - echo 1 >/sys/bus/usb/devices/.../power/persist - -where the "..." should be filled in the with the device's ID. Disable -the feature by writing 0 instead of 1. For hubs the feature is -automatically and permanently enabled and the power/persist file -doesn't even exist, so you only have to worry about setting it for -devices where it really matters. - - - Is this the best solution? - -Perhaps not. Arguably, keeping track of mounted filesystems and -memory mappings across device disconnects should be handled by a -centralized Logical Volume Manager. Such a solution would allow you -to plug in a USB flash device, create a persistent volume associated -with it, unplug the flash device, plug it back in later, and still -have the same persistent volume associated with the device. As such -it would be more far-reaching than USB-persist. - -On the other hand, writing a persistent volume manager would be a big -job and using it would require significant input from the user. This -solution is much quicker and easier -- and it exists now, a giant -point in its favor! - -Furthermore, the USB-persist feature applies to _all_ USB devices, not -just mass-storage devices. It might turn out to be equally useful for -other device types, such as network interfaces. - - - WARNING: USB-persist can be dangerous!! - -When recovering an interrupted power session the kernel does its best -to make sure the USB device hasn't been changed; that is, the same -device is still plugged into the port as before. But the checks -aren't guaranteed to be 100% accurate. - -If you replace one USB device with another of the same type (same -manufacturer, same IDs, and so on) there's an excellent chance the -kernel won't detect the change. The serial number string and other -descriptors are compared with the kernel's stored values, but this -might not help since manufacturers frequently omit serial numbers -entirely in their devices. - -Furthermore it's quite possible to leave a USB device exactly the same -while changing its media. If you replace the flash memory card in a -USB card reader while the system is asleep, the kernel will have no -way to know you did it. The kernel will assume that nothing has -happened and will continue to use the partition tables, inodes, and -memory mappings for the old card. - -If the kernel gets fooled in this way, it's almost certain to cause -data corruption and to crash your system. You'll have no one to blame -but yourself. - -For those devices with avoid_reset_quirk attribute being set, persist -maybe fail because they may morph after reset. - -YOU HAVE BEEN WARNED! USE AT YOUR OWN RISK! - -That having been said, most of the time there shouldn't be any trouble -at all. The USB-persist feature can be extremely useful. Make the -most of it. -- cgit v1.2.3-55-g7522 From e463c06335d04043c079f1d1d66472ec049de5dd Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 10:23:10 -0300 Subject: usb/URB.txt: convert to ReST and update it The URB doc describes the Kernel mechanism that do USB transfers. While the functions are already described at urb.h, there are a number of concepts and theory that are important for USB driver developers. Convert it to ReST and use C ref links to point to the places at usb.h where each function and struct is located. A few of those descriptions were incomplete. While here, update to reflect the current API status. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/URB.rst | 288 +++++++++++++++++++++++++++++++++ Documentation/driver-api/usb/index.rst | 1 + Documentation/driver-api/usb/usb.rst | 2 + Documentation/usb/URB.txt | 261 ------------------------------ 4 files changed, 291 insertions(+), 261 deletions(-) create mode 100644 Documentation/driver-api/usb/URB.rst delete mode 100644 Documentation/usb/URB.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/URB.rst b/Documentation/driver-api/usb/URB.rst new file mode 100644 index 000000000000..c4a141f29477 --- /dev/null +++ b/Documentation/driver-api/usb/URB.rst @@ -0,0 +1,288 @@ +USB Request Block (URB) +~~~~~~~~~~~~~~~~~~~~~~~ + +:Revised: 2000-Dec-05 +:Again: 2002-Jul-06 +:Again: 2005-Sep-19 +:Again: 2017-Mar-29 + + +.. note:: + + The USB subsystem now has a substantial section at :ref:`usb-hostside-api` + section, generated from the current source code. + This particular documentation file isn't complete and may not be + updated to the last version; don't rely on it except for a quick + overview. + +Basic concept or 'What is an URB?' +================================== + +The basic idea of the new driver is message passing, the message itself is +called USB Request Block, or URB for short. + +- An URB consists of all relevant information to execute any USB transaction + and deliver the data and status back. + +- Execution of an URB is inherently an asynchronous operation, i.e. the + :c:func:`usb_submit_urb` call returns immediately after it has successfully + queued the requested action. + +- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb` + at any time. + +- Each URB has a completion handler, which is called after the action + has been successfully completed or canceled. The URB also contains a + context-pointer for passing information to the completion handler. + +- Each endpoint for a device logically supports a queue of requests. + You can fill that queue, so that the USB hardware can still transfer + data to an endpoint while your driver handles completion of another. + This maximizes use of USB bandwidth, and supports seamless streaming + of data to (or from) devices when using periodic transfer modes. + + +The URB structure +================= + +Some of the fields in struct :c:type:`urb` are:: + + struct urb + { + // (IN) device and pipe specify the endpoint queue + struct usb_device *dev; // pointer to associated USB device + unsigned int pipe; // endpoint information + + unsigned int transfer_flags; // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc. + + // (IN) all urbs need completion routines + void *context; // context for completion routine + usb_complete_t complete; // pointer to completion routine + + // (OUT) status after each completion + int status; // returned status + + // (IN) buffer used for data transfers + void *transfer_buffer; // associated data buffer + u32 transfer_buffer_length; // data buffer length + int number_of_packets; // size of iso_frame_desc + + // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used + u32 actual_length; // actual data buffer length + + // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest) + unsigned char *setup_packet; // setup packet (control only) + + // Only for PERIODIC transfers (ISO, INTERRUPT) + // (IN/OUT) start_frame is set unless URB_ISO_ASAP isn't set + int start_frame; // start frame + int interval; // polling interval + + // ISO only: packets are only "best effort"; each can have errors + int error_count; // number of errors + struct usb_iso_packet_descriptor iso_frame_desc[0]; + }; + +Your driver must create the "pipe" value using values from the appropriate +endpoint descriptor in an interface that it's claimed. + + +How to get an URB? +================== + +URBs are allocated by calling :c:func:`usb_alloc_urb`:: + + struct urb *usb_alloc_urb(int isoframes, int mem_flags) + +Return value is a pointer to the allocated URB, 0 if allocation failed. +The parameter isoframes specifies the number of isochronous transfer frames +you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter +holds standard memory allocation flags, letting you control (among other +things) whether the underlying code may block or not. + +To free an URB, use :c:func:`usb_free_urb`:: + + void usb_free_urb(struct urb *urb) + +You may free an urb that you've submitted, but which hasn't yet been +returned to you in a completion callback. It will automatically be +deallocated when it is no longer in use. + + +What has to be filled in? +========================= + +Depending on the type of transaction, there are some inline functions +defined in ``linux/usb.h`` to simplify the initialization, such as +:c:func:`usb_fill_control_urb`, :c:func:`usb_fill_bulk_urb` and +:c:func:`usb_fill_int_urb`. In general, they need the usb device pointer, +the pipe (usual format from usb.h), the transfer buffer, the desired transfer +length, the completion handler, and its context. Take a look at the some +existing drivers to see how they're used. + +Flags: + +- For ISO there are two startup behaviors: Specified start_frame or ASAP. +- For ASAP set ``URB_ISO_ASAP`` in transfer_flags. + +If short packets should NOT be tolerated, set ``URB_SHORT_NOT_OK`` in +transfer_flags. + + +How to submit an URB? +===================== + +Just call :c:func:`usb_submit_urb`:: + + int usb_submit_urb(struct urb *urb, int mem_flags) + +The ``mem_flags`` parameter, such as ``GFP_ATOMIC``, controls memory +allocation, such as whether the lower levels may block when memory is tight. + +It immediately returns, either with status 0 (request queued) or some +error code, usually caused by the following: + +- Out of memory (``-ENOMEM``) +- Unplugged device (``-ENODEV``) +- Stalled endpoint (``-EPIPE``) +- Too many queued ISO transfers (``-EAGAIN``) +- Too many requested ISO frames (``-EFBIG``) +- Invalid INT interval (``-EINVAL``) +- More than one packet for INT (``-EINVAL``) + +After submission, ``urb->status`` is ``-EINPROGRESS``; however, you should +never look at that value except in your completion callback. + +For isochronous endpoints, your completion handlers should (re)submit +URBs to the same endpoint with the ``URB_ISO_ASAP`` flag, using +multi-buffering, to get seamless ISO streaming. + + +How to cancel an already running URB? +===================================== + +There are two ways to cancel an URB you've submitted but which hasn't +been returned to your driver yet. For an asynchronous cancel, call +:c:func:`usb_unlink_urb`:: + + int usb_unlink_urb(struct urb *urb) + +It removes the urb from the internal list and frees all allocated +HW descriptors. The status is changed to reflect unlinking. Note +that the URB will not normally have finished when :c:func:`usb_unlink_urb` +returns; you must still wait for the completion handler to be called. + +To cancel an URB synchronously, call :c:func:`usb_kill_urb`:: + + void usb_kill_urb(struct urb *urb) + +It does everything :c:func:`usb_unlink_urb` does, and in addition it waits +until after the URB has been returned and the completion handler +has finished. It also marks the URB as temporarily unusable, so +that if the completion handler or anyone else tries to resubmit it +they will get a ``-EPERM`` error. Thus you can be sure that when +:c:func:`usb_kill_urb` returns, the URB is totally idle. + +There is a lifetime issue to consider. An URB may complete at any +time, and the completion handler may free the URB. If this happens +while :c:func:`usb_unlink_urb` or :c:func:`usb_kill_urb` is running, it will +cause a memory-access violation. The driver is responsible for avoiding this, +which often means some sort of lock will be needed to prevent the URB +from being deallocated while it is still in use. + +On the other hand, since usb_unlink_urb may end up calling the +completion handler, the handler must not take any lock that is held +when usb_unlink_urb is invoked. The general solution to this problem +is to increment the URB's reference count while holding the lock, then +drop the lock and call usb_unlink_urb or usb_kill_urb, and then +decrement the URB's reference count. You increment the reference +count by calling :c:func`usb_get_urb`:: + + struct urb *usb_get_urb(struct urb *urb) + +(ignore the return value; it is the same as the argument) and +decrement the reference count by calling :c:func:`usb_free_urb`. Of course, +none of this is necessary if there's no danger of the URB being freed +by the completion handler. + + +What about the completion handler? +================================== + +The handler is of the following type:: + + typedef void (*usb_complete_t)(struct urb *) + +I.e., it gets the URB that caused the completion call. In the completion +handler, you should have a look at ``urb->status`` to detect any USB errors. +Since the context parameter is included in the URB, you can pass +information to the completion handler. + +Note that even when an error (or unlink) is reported, data may have been +transferred. That's because USB transfers are packetized; it might take +sixteen packets to transfer your 1KByte buffer, and ten of them might +have transferred successfully before the completion was called. + + +.. warning:: + + NEVER SLEEP IN A COMPLETION HANDLER. + + These are often called in atomic context. + +In the current kernel, completion handlers run with local interrupts +disabled, but in the future this will be changed, so don't assume that +local IRQs are always disabled inside completion handlers. + +How to do isochronous (ISO) transfers? +====================================== + +Besides the fields present on a bulk transfer, for ISO, you also +also have to set ``urb->interval`` to say how often to make transfers; it's +often one per frame (which is once every microframe for highspeed devices). +The actual interval used will be a power of two that's no bigger than what +you specify. You can use the :c:func:`usb_fill_int_urb` macro to fill +most ISO transfer fields. + +For ISO transfers you also have to fill a :c:type:`usb_iso_packet_descriptor` +structure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for +each packet you want to schedule. + +The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented +interval value that is less than or equal to the requested interval value. If +``URB_ISO_ASAP`` scheduling is used, ``urb->start_frame`` is also updated. + +For each entry you have to specify the data offset for this frame (base is +transfer_buffer), and the length you want to write/expect to read. +After completion, actual_length contains the actual transferred length and +status contains the resulting status for the ISO transfer for this frame. +It is allowed to specify a varying length from frame to frame (e.g. for +audio synchronisation/adaptive transfer rates). You can also use the length +0 to omit one or more frames (striping). + +For scheduling you can choose your own start frame or ``URB_ISO_ASAP``. As +explained earlier, if you always keep at least one URB queued and your +completion keeps (re)submitting a later URB, you'll get smooth ISO streaming +(if usb bandwidth utilization allows). + +If you specify your own start frame, make sure it's several frames in advance +of the current frame. You might want this model if you're synchronizing +ISO data with some other event stream. + + +How to start interrupt (INT) transfers? +======================================= + +Interrupt transfers, like isochronous transfers, are periodic, and happen +in intervals that are powers of two (1, 2, 4 etc) units. Units are frames +for full and low speed devices, and microframes for high speed ones. +You can use the :c:func:`usb_fill_int_urb` macro to fill INT transfer fields. + +The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented +interval value that is less than or equal to the requested interval value. + +In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically +restarted when they complete. They end when the completion handler is +called, just like other URBs. If you want an interrupt URB to be restarted, +your completion handler must resubmit it. +s diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 3f08cb5d5feb..1bf64edc8c8a 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -10,6 +10,7 @@ Linux USB API bulk-streams callbacks dma + URB power-management hotplug persist diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 7e820768ee4f..d15ab8ae5239 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -1,3 +1,5 @@ +.. _usb-hostside-api: + =========================== The Linux-USB Host Side API =========================== diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt deleted file mode 100644 index 50da0d455444..000000000000 --- a/Documentation/usb/URB.txt +++ /dev/null @@ -1,261 +0,0 @@ -Revised: 2000-Dec-05. -Again: 2002-Jul-06 -Again: 2005-Sep-19 - - NOTE: - - The USB subsystem now has a substantial section in "The Linux Kernel API" - guide (in Documentation/DocBook), generated from the current source - code. This particular documentation file isn't particularly current or - complete; don't rely on it except for a quick overview. - - -1.1. Basic concept or 'What is an URB?' - -The basic idea of the new driver is message passing, the message itself is -called USB Request Block, or URB for short. - -- An URB consists of all relevant information to execute any USB transaction - and deliver the data and status back. - -- Execution of an URB is inherently an asynchronous operation, i.e. the - usb_submit_urb(urb) call returns immediately after it has successfully - queued the requested action. - -- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. - -- Each URB has a completion handler, which is called after the action - has been successfully completed or canceled. The URB also contains a - context-pointer for passing information to the completion handler. - -- Each endpoint for a device logically supports a queue of requests. - You can fill that queue, so that the USB hardware can still transfer - data to an endpoint while your driver handles completion of another. - This maximizes use of USB bandwidth, and supports seamless streaming - of data to (or from) devices when using periodic transfer modes. - - -1.2. The URB structure - -Some of the fields in an URB are: - -struct urb -{ -// (IN) device and pipe specify the endpoint queue - struct usb_device *dev; // pointer to associated USB device - unsigned int pipe; // endpoint information - - unsigned int transfer_flags; // ISO_ASAP, SHORT_NOT_OK, etc. - -// (IN) all urbs need completion routines - void *context; // context for completion routine - void (*complete)(struct urb *); // pointer to completion routine - -// (OUT) status after each completion - int status; // returned status - -// (IN) buffer used for data transfers - void *transfer_buffer; // associated data buffer - int transfer_buffer_length; // data buffer length - int number_of_packets; // size of iso_frame_desc - -// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used - int actual_length; // actual data buffer length - -// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest) - unsigned char* setup_packet; // setup packet (control only) - -// Only for PERIODIC transfers (ISO, INTERRUPT) - // (IN/OUT) start_frame is set unless ISO_ASAP isn't set - int start_frame; // start frame - int interval; // polling interval - - // ISO only: packets are only "best effort"; each can have errors - int error_count; // number of errors - struct usb_iso_packet_descriptor iso_frame_desc[0]; -}; - -Your driver must create the "pipe" value using values from the appropriate -endpoint descriptor in an interface that it's claimed. - - -1.3. How to get an URB? - -URBs are allocated with the following call - - struct urb *usb_alloc_urb(int isoframes, int mem_flags) - -Return value is a pointer to the allocated URB, 0 if allocation failed. -The parameter isoframes specifies the number of isochronous transfer frames -you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter -holds standard memory allocation flags, letting you control (among other -things) whether the underlying code may block or not. - -To free an URB, use - - void usb_free_urb(struct urb *urb) - -You may free an urb that you've submitted, but which hasn't yet been -returned to you in a completion callback. It will automatically be -deallocated when it is no longer in use. - - -1.4. What has to be filled in? - -Depending on the type of transaction, there are some inline functions -defined in to simplify the initialization, such as -fill_control_urb() and fill_bulk_urb(). In general, they need the usb -device pointer, the pipe (usual format from usb.h), the transfer buffer, -the desired transfer length, the completion handler, and its context. -Take a look at the some existing drivers to see how they're used. - -Flags: -For ISO there are two startup behaviors: Specified start_frame or ASAP. -For ASAP set URB_ISO_ASAP in transfer_flags. - -If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in -transfer_flags. - - -1.5. How to submit an URB? - -Just call - - int usb_submit_urb(struct urb *urb, int mem_flags) - -The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation, -such as whether the lower levels may block when memory is tight. - -It immediately returns, either with status 0 (request queued) or some -error code, usually caused by the following: - -- Out of memory (-ENOMEM) -- Unplugged device (-ENODEV) -- Stalled endpoint (-EPIPE) -- Too many queued ISO transfers (-EAGAIN) -- Too many requested ISO frames (-EFBIG) -- Invalid INT interval (-EINVAL) -- More than one packet for INT (-EINVAL) - -After submission, urb->status is -EINPROGRESS; however, you should never -look at that value except in your completion callback. - -For isochronous endpoints, your completion handlers should (re)submit -URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering, -to get seamless ISO streaming. - - -1.6. How to cancel an already running URB? - -There are two ways to cancel an URB you've submitted but which hasn't -been returned to your driver yet. For an asynchronous cancel, call - - int usb_unlink_urb(struct urb *urb) - -It removes the urb from the internal list and frees all allocated -HW descriptors. The status is changed to reflect unlinking. Note -that the URB will not normally have finished when usb_unlink_urb() -returns; you must still wait for the completion handler to be called. - -To cancel an URB synchronously, call - - void usb_kill_urb(struct urb *urb) - -It does everything usb_unlink_urb does, and in addition it waits -until after the URB has been returned and the completion handler -has finished. It also marks the URB as temporarily unusable, so -that if the completion handler or anyone else tries to resubmit it -they will get a -EPERM error. Thus you can be sure that when -usb_kill_urb() returns, the URB is totally idle. - -There is a lifetime issue to consider. An URB may complete at any -time, and the completion handler may free the URB. If this happens -while usb_unlink_urb or usb_kill_urb is running, it will cause a -memory-access violation. The driver is responsible for avoiding this, -which often means some sort of lock will be needed to prevent the URB -from being deallocated while it is still in use. - -On the other hand, since usb_unlink_urb may end up calling the -completion handler, the handler must not take any lock that is held -when usb_unlink_urb is invoked. The general solution to this problem -is to increment the URB's reference count while holding the lock, then -drop the lock and call usb_unlink_urb or usb_kill_urb, and then -decrement the URB's reference count. You increment the reference -count by calling - - struct urb *usb_get_urb(struct urb *urb) - -(ignore the return value; it is the same as the argument) and -decrement the reference count by calling usb_free_urb. Of course, -none of this is necessary if there's no danger of the URB being freed -by the completion handler. - - -1.7. What about the completion handler? - -The handler is of the following type: - - typedef void (*usb_complete_t)(struct urb *) - -I.e., it gets the URB that caused the completion call. In the completion -handler, you should have a look at urb->status to detect any USB errors. -Since the context parameter is included in the URB, you can pass -information to the completion handler. - -Note that even when an error (or unlink) is reported, data may have been -transferred. That's because USB transfers are packetized; it might take -sixteen packets to transfer your 1KByte buffer, and ten of them might -have transferred successfully before the completion was called. - - -NOTE: ***** WARNING ***** -NEVER SLEEP IN A COMPLETION HANDLER. These are often called in atomic -context. - -In the current kernel, completion handlers run with local interrupts -disabled, but in the future this will be changed, so don't assume that -local IRQs are always disabled inside completion handlers. - -1.8. How to do isochronous (ISO) transfers? - -For ISO transfers you have to fill a usb_iso_packet_descriptor structure, -allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each -packet you want to schedule. You also have to set urb->interval to say -how often to make transfers; it's often one per frame (which is once -every microframe for highspeed devices). The actual interval used will -be a power of two that's no bigger than what you specify. - -The usb_submit_urb() call modifies urb->interval to the implemented interval -value that is less than or equal to the requested interval value. If -ISO_ASAP scheduling is used, urb->start_frame is also updated. - -For each entry you have to specify the data offset for this frame (base is -transfer_buffer), and the length you want to write/expect to read. -After completion, actual_length contains the actual transferred length and -status contains the resulting status for the ISO transfer for this frame. -It is allowed to specify a varying length from frame to frame (e.g. for -audio synchronisation/adaptive transfer rates). You can also use the length -0 to omit one or more frames (striping). - -For scheduling you can choose your own start frame or ISO_ASAP. As explained -earlier, if you always keep at least one URB queued and your completion -keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb -bandwidth utilization allows). - -If you specify your own start frame, make sure it's several frames in advance -of the current frame. You might want this model if you're synchronizing -ISO data with some other event stream. - - -1.9. How to start interrupt (INT) transfers? - -Interrupt transfers, like isochronous transfers, are periodic, and happen -in intervals that are powers of two (1, 2, 4 etc) units. Units are frames -for full and low speed devices, and microframes for high speed ones. -The usb_submit_urb() call modifies urb->interval to the implemented interval -value that is less than or equal to the requested interval value. - -In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically -restarted when they complete. They end when the completion handler is -called, just like other URBs. If you want an interrupt URB to be restarted, -your completion handler must resubmit it. -- cgit v1.2.3-55-g7522 From 8a6a285d61fd0d602859c945892927ef87d26895 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 16 Apr 2017 21:51:06 -0300 Subject: docs-rst: usb: update old usbfs-related documentation There's no usbfs anymore. The old features are now either exported to /dev/bus/usb or via debugfs. Update documentation accordingly, pointing to the new places where the character devices and usb/devices are now placed. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/usb.rst | 180 ++++++++++++---------------------- Documentation/networking/cdc_mbim.txt | 2 +- Documentation/usb/acm.txt | 2 +- Documentation/usb/gadget_serial.txt | 4 +- Documentation/usb/proc_usb_info.txt | 20 ++-- 5 files changed, 74 insertions(+), 134 deletions(-) (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 6824089ef4c8..a98f78c91ab6 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -111,7 +111,8 @@ USB-Standard Types In ```` you will find the USB data types defined in chapter 9 of the USB specification. These data types are used throughout -USB, and in APIs including this host side API, gadget APIs, and usbfs. +USB, and in APIs including this host side API, gadget APIs, usb character +devices and debugfs interfaces. .. kernel-doc:: include/linux/usb/ch9.h :internal: @@ -204,40 +205,32 @@ significantly reduce hcd-specific behaviors. .. kernel-doc:: drivers/usb/core/buffer.c :internal: -The USB Filesystem (usbfs) -========================== +The USB character device nodes +============================== -This chapter presents the Linux *usbfs*. You may prefer to avoid writing -new kernel code for your USB driver; that's the problem that usbfs set -out to solve. User mode device drivers are usually packaged as -applications or libraries, and may use usbfs through some programming -library that wraps it. Such libraries include +This chapter presents the Linux character device nodes. You may prefer +to avoid writing new kernel code for your USB driver. User mode device +drivers are usually packaged as applications or libraries, and may use +character devices through some programming library that wraps it. +Such libraries include `libusb `__ for C/C++, and `jUSB `__ for Java. .. note:: - This particular documentation is incomplete, especially with respect - to the asynchronous mode. As of kernel 2.5.66 the code and this - (new) documentation need to be cross-reviewed. + - They were used to be implemented via *usbfs*, but this is not part of + the sysfs debug interface. -Configure usbfs into Linux kernels by enabling the *USB filesystem* -option (CONFIG_USB_DEVICEFS), and you get basic support for user mode -USB device drivers. Until relatively recently it was often (confusingly) -called *usbdevfs* although it wasn't solving what *devfs* was. Every USB -device will appear in usbfs, regardless of whether or not it has a -kernel driver. + - This particular documentation is incomplete, especially with respect + to the asynchronous mode. As of kernel 2.5.66 the code and this + (new) documentation need to be cross-reviewed. -What files are in "usbfs"? --------------------------- +What files are in "devtmpfs"? +----------------------------- -Conventionally mounted at ``/proc/bus/usb``, usbfs features include: +Conventionally mounted at ``/dev/bus/usb/``, usbfs features include: -- ``/proc/bus/usb/devices`` ... a text file showing each of the USB - devices on known to the kernel, and their configuration descriptors. - You can also poll() this to learn about new devices. - -- ``/proc/bus/usb/BBB/DDD`` ... magic files exposing the each device's +- ``/dev/bus/usb//BBB/DDD`` ... magic files exposing the each device's configuration descriptors, and supporting a series of ioctls for making device requests, including I/O to devices. (Purely for access by programs.) @@ -252,100 +245,7 @@ them. HID and networking devices expose these stable IDs, so that for example you can be sure that you told the right UPS to power down its second server. "usbfs" doesn't (yet) expose those IDs. -Mounting and Access Control ---------------------------- - -There are a number of mount options for usbfs, which will be of most -interest to you if you need to override the default access control -policy. That policy is that only root may read or write device files -(``/proc/bus/BBB/DDD``) although anyone may read the ``devices`` or -``drivers`` files. I/O requests to the device also need the -CAP_SYS_RAWIO capability, - -The significance of that is that by default, all user mode device -drivers need super-user privileges. You can change modes or ownership in -a driver setup when the device hotplugs, or maye just start the driver -right then, as a privileged server (or some activity within one). That's -the most secure approach for multi-user systems, but for single user -systems ("trusted" by that user) it's more convenient just to grant -everyone all access (using the *devmode=0666* option) so the driver can -start whenever it's needed. - -The mount options for usbfs, usable in /etc/fstab or in command line -invocations of *mount*, are: - -*busgid*\ =NNNNN - Controls the GID used for the /proc/bus/usb/BBB directories. - (Default: 0) - -*busmode*\ =MMM - Controls the file mode used for the /proc/bus/usb/BBB directories. - (Default: 0555) - -*busuid*\ =NNNNN - Controls the UID used for the /proc/bus/usb/BBB directories. - (Default: 0) - -*devgid*\ =NNNNN - Controls the GID used for the /proc/bus/usb/BBB/DDD files. (Default: - 0) - -*devmode*\ =MMM - Controls the file mode used for the /proc/bus/usb/BBB/DDD files. - (Default: 0644) - -*devuid*\ =NNNNN - Controls the UID used for the /proc/bus/usb/BBB/DDD files. (Default: - 0) - -*listgid*\ =NNNNN - Controls the GID used for the /proc/bus/usb/devices and drivers - files. (Default: 0) - -*listmode*\ =MMM - Controls the file mode used for the /proc/bus/usb/devices and - drivers files. (Default: 0444) - -*listuid*\ =NNNNN - Controls the UID used for the /proc/bus/usb/devices and drivers - files. (Default: 0) - -Note that many Linux distributions hard-wire the mount options for usbfs -in their init scripts, such as ``/etc/rc.d/rc.sysinit``, rather than -making it easy to set this per-system policy in ``/etc/fstab``. - -/proc/bus/usb/devices ---------------------- - -This file is handy for status viewing tools in user mode, which can scan -the text format and ignore most of it. More detailed device status -(including class and vendor status) is available from device-specific -files. For information about the current format of this file, see the -``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel -sources. - -This file, in combination with the poll() system call, can also be used -to detect when devices are added or removed:: - - int fd; - struct pollfd pfd; - - fd = open("/proc/bus/usb/devices", O_RDONLY); - pfd = { fd, POLLIN, 0 }; - for (;;) { - /* The first time through, this call will return immediately. */ - poll(&pfd, 1, -1); - - /* To see what's changed, compare the file's previous and current - contents or scan the filesystem. (Scanning is more precise.) */ - } - -Note that this behavior is intended to be used for informational and -debug purposes. It would be more appropriate to use programs such as -udev or HAL to initialize a device or start a user-mode helper program, -for instance. - -/proc/bus/usb/BBB/DDD +/dev/bus/usb//BBB/DDD --------------------- Use these files in one of these basic ways: @@ -376,7 +276,7 @@ Life Cycle of User Mode Drivers Such a driver first needs to find a device file for a device it knows how to handle. Maybe it was told about it because a ``/sbin/hotplug`` event handling agent chose that driver to handle the new device. Or -maybe it's an application that scans all the /proc/bus/usb device files, +maybe it's an application that scans all the /dev/bus/usb/ device files, and ignores most devices. In either case, it should :c:func:`read()` all the descriptors from the device file, and check them against what it knows how to handle. It might just reject everything except a particular @@ -734,3 +634,43 @@ USBDEVFS_REAPURBNDELAY USBDEVFS_SUBMITURB *TBS* + +The USB devices +=============== + +The USB devices are now exported via debugfs: + +- ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB + devices on known to the kernel, and their configuration descriptors. + You can also poll() this to learn about new devices. + +/sys/kernel/debug/usb/devices +----------------------------- + +This file is handy for status viewing tools in user mode, which can scan +the text format and ignore most of it. More detailed device status +(including class and vendor status) is available from device-specific +files. For information about the current format of this file, see the +``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel +sources. + +This file, in combination with the poll() system call, can also be used +to detect when devices are added or removed:: + + int fd; + struct pollfd pfd; + + fd = open("/sys/kernel/debug/usb/devices", O_RDONLY); + pfd = { fd, POLLIN, 0 }; + for (;;) { + /* The first time through, this call will return immediately. */ + poll(&pfd, 1, -1); + + /* To see what's changed, compare the file's previous and current + contents or scan the filesystem. (Scanning is more precise.) */ + } + +Note that this behavior is intended to be used for informational and +debug purposes. It would be more appropriate to use programs such as +udev or HAL to initialize a device or start a user-mode helper program, +for instance. diff --git a/Documentation/networking/cdc_mbim.txt b/Documentation/networking/cdc_mbim.txt index b9482ca10254..e4c376abbdad 100644 --- a/Documentation/networking/cdc_mbim.txt +++ b/Documentation/networking/cdc_mbim.txt @@ -332,7 +332,7 @@ References [5] "MBIM (Mobile Broadband Interface Model) Registry" - http://compliance.usb.org/mbim/ -[6] "/proc/bus/usb filesystem output" +[6] "/dev/bus/usb filesystem output" - Documentation/usb/proc_usb_info.txt [7] "/sys/bus/usb/devices/.../descriptors" diff --git a/Documentation/usb/acm.txt b/Documentation/usb/acm.txt index 17f5c2e1a570..903abca10517 100644 --- a/Documentation/usb/acm.txt +++ b/Documentation/usb/acm.txt @@ -64,7 +64,7 @@ minicom, ppp and mgetty with them. 2. Verifying that it works ~~~~~~~~~~~~~~~~~~~~~~~~~~ - The first step would be to check /proc/bus/usb/devices, it should look + The first step would be to check /sys/kernel/debug/usb/devices, it should look like this: T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt index 6b4a88a8c8e3..d1def3186782 100644 --- a/Documentation/usb/gadget_serial.txt +++ b/Documentation/usb/gadget_serial.txt @@ -189,7 +189,7 @@ Once the gadget serial driver is loaded and the USB device connected to the Linux host with a USB cable, the host system should recognize the gadget serial device. For example, the command - cat /proc/bus/usb/devices + cat /sys/kernel/debug/usb/devices should show something like this: @@ -221,7 +221,7 @@ Once the gadget serial driver is loaded and the USB device connected to the Linux host with a USB cable, the host system should recognize the gadget serial device. For example, the command - cat /proc/bus/usb/devices + cat /sys/kernel/debug/usb/devices should show something like this: diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index 98be91982677..06d7960e9ae6 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt @@ -4,7 +4,7 @@ The usbfs filesystem for USB devices is traditionally mounted at -/proc/bus/usb. It provides the /proc/bus/usb/devices file, as well as +/proc/bus/usb. It provides the /sys/kernel/debug/usb/devices file, as well as the /proc/bus/usb/BBB/DDD files. In many modern systems the usbfs filesystem isn't used at all. Instead @@ -24,7 +24,7 @@ USB device nodes are created under /dev/usb/ or someplace similar. The none /proc/bus/usb usbfs defaults 0 0 to /etc/fstab. This will mount usbfs at each reboot. - You can then issue `cat /proc/bus/usb/devices` to extract + You can then issue `cat /sys/kernel/debug/usb/devices` to extract USB device information, and user mode drivers can use usbfs to interact with USB devices. @@ -60,7 +60,7 @@ descriptors are in bus endian format! The configuration descriptor are wTotalLength bytes apart. If a device returns less configuration descriptor data than indicated by wTotalLength there will be a hole in the file for the missing bytes. This information is also shown -in text form by the /proc/bus/usb/devices file, described later. +in text form by the /sys/kernel/debug/usb/devices file, described later. These files may also be used to write user-level drivers for the USB devices. You would open the /proc/bus/usb/BBB/DDD file read/write, @@ -79,9 +79,9 @@ usbfs mount options such as "devmode=0666" may be helpful. -THE /proc/bus/usb/devices FILE: +THE /sys/kernel/debug/usb/devices FILE: ------------------------------- -In /proc/bus/usb/devices, each device's output has multiple +In /sys/kernel/debug/usb/devices, each device's output has multiple lines of ASCII output. I made it ASCII instead of binary on purpose, so that someone can obtain some useful data from it without the use of an @@ -104,7 +104,7 @@ E = Endpoint descriptor info. ======================================================================= -/proc/bus/usb/devices output format: +/sys/kernel/debug/usb/devices output format: Legend: d = decimal number (may have leading spaces or 0's) @@ -277,16 +277,16 @@ E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss If a user or script is interested only in Topology info, for -example, use something like "grep ^T: /proc/bus/usb/devices" +example, use something like "grep ^T: /sys/kernel/debug/usb/devices" for only the Topology lines. A command like -"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list +"grep -i ^[tdp]: /sys/kernel/debug/usb/devices" can be used to list only the lines that begin with the characters in square brackets, where the valid characters are TDPCIE. With a slightly more able script, it can display any selected lines (for example, only T, D, and P lines) and change their output format. (The "procusb" Perl script is the beginning of this idea. It will list only selected lines [selected from TBDPSCIE] or "All" lines from -/proc/bus/usb/devices.) +/sys/kernel/debug/usb/devices.) The Topology lines can be used to generate a graphic/pictorial of the USB devices on a system's root hub. (See more below @@ -297,7 +297,7 @@ being used for each device, and which altsetting it activated. The Configuration lines could be used to list maximum power (in milliamps) that a system's USB devices are using. -For example, "grep ^C: /proc/bus/usb/devices". +For example, "grep ^C: /sys/kernel/debug/usb/devices". Here's an example, from a system which has a UHCI root hub, -- cgit v1.2.3-55-g7522 From 96801b35f07ec85ffd4bb542e4b0d5122d32fc9d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 16 Apr 2017 21:51:09 -0300 Subject: usb.rst: move documentation from proc_usb_info.txt to USB ReST book The contents of proc_usb_info.txt complements what's there at driver-api usb book. Yet, it is outdated, as it still refers to the USB character devices as usbfs. So, move the contents to usb.rst, adjusting it to point to the right places. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/usb.rst | 439 ++++++++++++++++++++++++++++++++--- Documentation/usb/proc_usb_info.txt | 390 ------------------------------- 2 files changed, 405 insertions(+), 424 deletions(-) delete mode 100644 Documentation/usb/proc_usb_info.txt (limited to 'Documentation/usb') diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index a98f78c91ab6..dba0f876b36f 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -212,9 +212,14 @@ This chapter presents the Linux character device nodes. You may prefer to avoid writing new kernel code for your USB driver. User mode device drivers are usually packaged as applications or libraries, and may use character devices through some programming library that wraps it. -Such libraries include -`libusb `__ for C/C++, and -`jUSB `__ for Java. +Such libraries include: + + - `libusb `__ for C/C++, and + - `jUSB `__ for Java. + +Some old information about it can be seen at the "USB Device Filesystem" +section of the USB Guide. The latest copy of the USB Guide can be found +at http://www.linux-usb.org/ .. note:: @@ -230,45 +235,80 @@ What files are in "devtmpfs"? Conventionally mounted at ``/dev/bus/usb/``, usbfs features include: -- ``/dev/bus/usb//BBB/DDD`` ... magic files exposing the each device's +- ``/dev/bus/usb/BBB/DDD`` ... magic files exposing the each device's configuration descriptors, and supporting a series of ioctls for making device requests, including I/O to devices. (Purely for access by programs.) -Each bus is given a number (BBB) based on when it was enumerated; within -each bus, each device is given a similar number (DDD). Those BBB/DDD +Each bus is given a number (``BBB``) based on when it was enumerated; within +each bus, each device is given a similar number (``DDD``). Those ``BBB/DDD`` paths are not "stable" identifiers; expect them to change even if you always leave the devices plugged in to the same hub port. *Don't even think of saving these in application configuration files.* Stable identifiers are available, for user mode applications that want to use them. HID and networking devices expose these stable IDs, so that for example you can be sure that you told the right UPS to power down its -second server. "usbfs" doesn't (yet) expose those IDs. +second server. Pleast note that it doesn't (yet) expose those IDs. -/dev/bus/usb//BBB/DDD ---------------------- +/dev/bus/usb/BBB/DDD +-------------------- Use these files in one of these basic ways: -*They can be read,* producing first the device descriptor (18 bytes) and -then the descriptors for the current configuration. See the USB 2.0 spec -for details about those binary data formats. You'll need to convert most -multibyte values from little endian format to your native host byte -order, although a few of the fields in the device descriptor (both of -the BCD-encoded fields, and the vendor and product IDs) will be -byteswapped for you. Note that configuration descriptors include -descriptors for interfaces, altsettings, endpoints, and maybe additional -class descriptors. - -*Perform USB operations* using *ioctl()* requests to make endpoint I/O -requests (synchronously or asynchronously) or manage the device. These -requests need the CAP_SYS_RAWIO capability, as well as filesystem -access permissions. Only one ioctl request can be made on one of these -device files at a time. This means that if you are synchronously reading -an endpoint from one thread, you won't be able to write to a different -endpoint from another thread until the read completes. This works for -*half duplex* protocols, but otherwise you'd use asynchronous i/o -requests. +- *They can be read,* producing first the device descriptor (18 bytes) and + then the descriptors for the current configuration. See the USB 2.0 spec + for details about those binary data formats. You'll need to convert most + multibyte values from little endian format to your native host byte + order, although a few of the fields in the device descriptor (both of + the BCD-encoded fields, and the vendor and product IDs) will be + byteswapped for you. Note that configuration descriptors include + descriptors for interfaces, altsettings, endpoints, and maybe additional + class descriptors. + +- *Perform USB operations* using *ioctl()* requests to make endpoint I/O + requests (synchronously or asynchronously) or manage the device. These + requests need the ``CAP_SYS_RAWIO`` capability, as well as filesystem + access permissions. Only one ioctl request can be made on one of these + device files at a time. This means that if you are synchronously reading + an endpoint from one thread, you won't be able to write to a different + endpoint from another thread until the read completes. This works for + *half duplex* protocols, but otherwise you'd use asynchronous i/o + requests. + +Each connected USB device has one file. The ``BBB`` indicates the bus +number. The ``DDD`` indicates the device address on that bus. Both +of these numbers are assigned sequentially, and can be reused, so +you can't rely on them for stable access to devices. For example, +it's relatively common for devices to re-enumerate while they are +still connected (perhaps someone jostled their power supply, hub, +or USB cable), so a device might be ``002/027`` when you first connect +it and ``002/048`` sometime later. + +These files can be read as binary data. The binary data consists +of first the device descriptor, then the descriptors for each +configuration of the device. Multi-byte fields in the device descriptor +are converted to host endianness by the kernel. The configuration +descriptors are in bus endian format! The configuration descriptor +are wTotalLength bytes apart. If a device returns less configuration +descriptor data than indicated by wTotalLength there will be a hole in +the file for the missing bytes. This information is also shown +in text form by the ``/sys/kernel/debug/usb/devices`` file, described later. + +These files may also be used to write user-level drivers for the USB +devices. You would open the ``/dev/bus/usb/BBB/DDD`` file read/write, +read its descriptors to make sure it's the device you expect, and then +bind to an interface (or perhaps several) using an ioctl call. You +would issue more ioctls to the device to communicate to it using +control, bulk, or other kinds of USB transfers. The IOCTLs are +listed in the ```` file, and at this writing the +source code (``linux/drivers/usb/core/devio.c``) is the primary reference +for how to access devices through those files. + +Note that since by default these ``BBB/DDD`` files are writable only by +root, only root can write such user mode drivers. You can selectively +grant read/write permissions to other users by using ``chmod``. Also, +usbfs mount options such as ``devmode=0666`` may be helpful. + Life Cycle of User Mode Drivers ------------------------------- @@ -276,7 +316,7 @@ Life Cycle of User Mode Drivers Such a driver first needs to find a device file for a device it knows how to handle. Maybe it was told about it because a ``/sbin/hotplug`` event handling agent chose that driver to handle the new device. Or -maybe it's an application that scans all the /dev/bus/usb/ device files, +maybe it's an application that scans all the ``/dev/bus/usb`` device files, and ignores most devices. In either case, it should :c:func:`read()` all the descriptors from the device file, and check them against what it knows how to handle. It might just reject everything except a particular @@ -430,7 +470,7 @@ USBDEVFS_RELEASEINTERFACE the number of the interface (bInterfaceNumber from descriptor); File modification time is not updated by this request. -.. warning:: + .. warning:: *No security check is made to ensure that the task which made the claim is the one which is releasing it. This means that user @@ -442,7 +482,7 @@ USBDEVFS_RESETEP as identified in the endpoint descriptor), with USB_DIR_IN added if the device's endpoint sends data to the host. - **Warning** + .. Warning:: *Avoid using this request. It should probably be removed.* Using it typically means the device and driver will lose toggle @@ -479,10 +519,10 @@ USBDEVFS_BULK void *data; }; - The "ep" value identifies a bulk endpoint number (1 to 15, as + The ``ep`` value identifies a bulk endpoint number (1 to 15, as identified in an endpoint descriptor), masked with USB_DIR_IN when referring to an endpoint which sends data to the host from the - device. The length of the data buffer is identified by "len"; Recent + device. The length of the data buffer is identified by ``len``; Recent kernels support requests up to about 128KBytes. *FIXME say how read length is returned, and how short reads are handled.*. @@ -494,7 +534,7 @@ USBDEVFS_CLEAR_HALT which sends data to the host from the device. Use this on bulk or interrupt endpoints which have stalled, - returning *-EPIPE* status to a data transfer request. Do not issue + returning ``-EPIPE`` status to a data transfer request. Do not issue the control request directly, since that could invalidate the host's record of the data toggle. @@ -674,3 +714,334 @@ Note that this behavior is intended to be used for informational and debug purposes. It would be more appropriate to use programs such as udev or HAL to initialize a device or start a user-mode helper program, for instance. + +In this file, each device's output has multiple lines of ASCII output. + +I made it ASCII instead of binary on purpose, so that someone +can obtain some useful data from it without the use of an +auxiliary program. However, with an auxiliary program, the numbers +in the first 4 columns of each ``T:`` line (topology info: +Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram. + +Each line is tagged with a one-character ID for that line:: + + T = Topology (etc.) + B = Bandwidth (applies only to USB host controllers, which are + virtualized as root hubs) + D = Device descriptor info. + P = Product ID info. (from Device descriptor, but they won't fit + together on one line) + S = String descriptors. + C = Configuration descriptor info. (* = active configuration) + I = Interface descriptor info. + E = Endpoint descriptor info. + +/sys/kernel/debug/usb/devices output format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Legend:: + d = decimal number (may have leading spaces or 0's) + x = hexadecimal number (may have leading spaces or 0's) + s = string + + + +Topology info +^^^^^^^^^^^^^ + +:: + + T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd + | | | | | | | | |__MaxChildren + | | | | | | | |__Device Speed in Mbps + | | | | | | |__DeviceNumber + | | | | | |__Count of devices at this level + | | | | |__Connector/Port on Parent for this device + | | | |__Parent DeviceNumber + | | |__Level in topology for this bus + | |__Bus number + |__Topology info tag + +Speed may be: + + ======= ====================================================== + 1.5 Mbit/s for low speed USB + 12 Mbit/s for full speed USB + 480 Mbit/s for high speed USB (added for USB 2.0); + also used for Wireless USB, which has no fixed speed + 5000 Mbit/s for SuperSpeed USB (added for USB 3.0) + ======= ====================================================== + +For reasons lost in the mists of time, the Port number is always +too low by 1. For example, a device plugged into port 4 will +show up with ``Port=03``. + +Bandwidth info +^^^^^^^^^^^^^^ + +:: + + B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd + | | | |__Number of isochronous requests + | | |__Number of interrupt requests + | |__Total Bandwidth allocated to this bus + |__Bandwidth info tag + +Bandwidth allocation is an approximation of how much of one frame +(millisecond) is in use. It reflects only periodic transfers, which +are the only transfers that reserve bandwidth. Control and bulk +transfers use all other bandwidth, including reserved bandwidth that +is not used for transfers (such as for short packets). + +The percentage is how much of the "reserved" bandwidth is scheduled by +those transfers. For a low or full speed bus (loosely, "USB 1.1"), +90% of the bus bandwidth is reserved. For a high speed bus (loosely, +"USB 2.0") 80% is reserved. + + +Device descriptor info & Product ID info +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd + P: Vendor=xxxx ProdID=xxxx Rev=xx.xx + +where:: + + D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd + | | | | | | |__NumberConfigurations + | | | | | |__MaxPacketSize of Default Endpoint + | | | | |__DeviceProtocol + | | | |__DeviceSubClass + | | |__DeviceClass + | |__Device USB version + |__Device info tag #1 + +where:: + + P: Vendor=xxxx ProdID=xxxx Rev=xx.xx + | | | |__Product revision number + | | |__Product ID code + | |__Vendor ID code + |__Device info tag #2 + + +String descriptor info +^^^^^^^^^^^^^^^^^^^^^^ +:: + + S: Manufacturer=ssss + | |__Manufacturer of this device as read from the device. + | For USB host controller drivers (virtual root hubs) this may + | be omitted, or (for newer drivers) will identify the kernel + | version and the driver which provides this hub emulation. + |__String info tag + + S: Product=ssss + | |__Product description of this device as read from the device. + | For older USB host controller drivers (virtual root hubs) this + | indicates the driver; for newer ones, it's a product (and vendor) + | description that often comes from the kernel's PCI ID database. + |__String info tag + + S: SerialNumber=ssss + | |__Serial Number of this device as read from the device. + | For USB host controller drivers (virtual root hubs) this is + | some unique ID, normally a bus ID (address or slot name) that + | can't be shared with any other device. + |__String info tag + + + +Configuration descriptor info +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:: + + C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA + | | | | | |__MaxPower in mA + | | | | |__Attributes + | | | |__ConfiguratioNumber + | | |__NumberOfInterfaces + | |__ "*" indicates the active configuration (others are " ") + |__Config info tag + +USB devices may have multiple configurations, each of which act +rather differently. For example, a bus-powered configuration +might be much less capable than one that is self-powered. Only +one device configuration can be active at a time; most devices +have only one configuration. + +Each configuration consists of one or more interfaces. Each +interface serves a distinct "function", which is typically bound +to a different USB device driver. One common example is a USB +speaker with an audio interface for playback, and a HID interface +for use with software volume control. + +Interface descriptor info (can be multiple per Config) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:: + + I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss + | | | | | | | | |__Driver name + | | | | | | | | or "(none)" + | | | | | | | |__InterfaceProtocol + | | | | | | |__InterfaceSubClass + | | | | | |__InterfaceClass + | | | | |__NumberOfEndpoints + | | | |__AlternateSettingNumber + | | |__InterfaceNumber + | |__ "*" indicates the active altsetting (others are " ") + |__Interface info tag + +A given interface may have one or more "alternate" settings. +For example, default settings may not use more than a small +amount of periodic bandwidth. To use significant fractions +of bus bandwidth, drivers must select a non-default altsetting. + +Only one setting for an interface may be active at a time, and +only one driver may bind to an interface at a time. Most devices +have only one alternate setting per interface. + + +Endpoint descriptor info (can be multiple per Interface) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss + | | | | |__Interval (max) between transfers + | | | |__EndpointMaxPacketSize + | | |__Attributes(EndpointType) + | |__EndpointAddress(I=In,O=Out) + |__Endpoint info tag + +The interval is nonzero for all periodic (interrupt or isochronous) +endpoints. For high speed endpoints the transfer interval may be +measured in microseconds rather than milliseconds. + +For high speed periodic endpoints, the ``EndpointMaxPacketSize`` reflects +the per-microframe data transfer size. For "high bandwidth" +endpoints, that can reflect two or three packets (for up to +3KBytes every 125 usec) per endpoint. + +With the Linux-USB stack, periodic bandwidth reservations use the +transfer intervals and sizes provided by URBs, which can be less +than those found in endpoint descriptor. + +Usage examples +~~~~~~~~~~~~~~ + +If a user or script is interested only in Topology info, for +example, use something like ``grep ^T: /sys/kernel/debug/usb/devices`` +for only the Topology lines. A command like +``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list +only the lines that begin with the characters in square brackets, +where the valid characters are TDPCIE. With a slightly more able +script, it can display any selected lines (for example, only T, D, +and P lines) and change their output format. (The ``procusb`` +Perl script is the beginning of this idea. It will list only +selected lines [selected from TBDPSCIE] or "All" lines from +``/sys/kernel/debug/usb/devices``.) + +The Topology lines can be used to generate a graphic/pictorial +of the USB devices on a system's root hub. (See more below +on how to do this.) + +The Interface lines can be used to determine what driver is +being used for each device, and which altsetting it activated. + +The Configuration lines could be used to list maximum power +(in milliamps) that a system's USB devices are using. +For example, ``grep ^C: /sys/kernel/debug/usb/devices``. + + +Here's an example, from a system which has a UHCI root hub, +an external hub connected to the root hub, and a mouse and +a serial converter connected to the external hub. + +:: + + T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 + B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0 + D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0000 ProdID=0000 Rev= 0.00 + S: Product=USB UHCI Root Hub + S: SerialNumber=dce0 + C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub + E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms + + T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 + D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0451 ProdID=1446 Rev= 1.00 + C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub + E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms + + T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 + D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=04b4 ProdID=0001 Rev= 0.00 + C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse + E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms + + T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 + D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0565 ProdID=0001 Rev= 1.08 + S: Manufacturer=Peracom Networks, Inc. + S: Product=Peracom USB to Serial Converter + C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA + I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial + E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms + E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms + E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms + + +Selecting only the ``T:`` and ``I:`` lines from this (for example, by using +``procusb ti``), we have + +:: + + T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 + T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 + I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub + T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 + I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse + T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 + I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial + + +Physically this looks like (or could be converted to):: + + +------------------+ + | PC/root_hub (12)| Dev# = 1 + +------------------+ (nn) is Mbps. + Level 0 | CN.0 | CN.1 | [CN = connector/port #] + +------------------+ + / + / + +-----------------------+ + Level 1 | Dev#2: 4-port hub (12)| + +-----------------------+ + |CN.0 |CN.1 |CN.2 |CN.3 | + +-----------------------+ + \ \____________________ + \_____ \ + \ \ + +--------------------+ +--------------------+ + Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)| + +--------------------+ +--------------------+ + + + +Or, in a more tree-like structure (ports [Connectors] without +connections could be omitted):: + + PC: Dev# 1, root hub, 2 ports, 12 Mbps + |_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps + |_ CN.0: Dev #3, mouse, 1.5 Mbps + |_ CN.1: + |_ CN.2: Dev #4, serial, 12 Mbps + |_ CN.3: + |_ CN.1: diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt deleted file mode 100644 index 06d7960e9ae6..000000000000 --- a/Documentation/usb/proc_usb_info.txt +++ /dev/null @@ -1,390 +0,0 @@ -/proc/bus/usb filesystem output -=============================== -(version 2010.09.13) - - -The usbfs filesystem for USB devices is traditionally mounted at -/proc/bus/usb. It provides the /sys/kernel/debug/usb/devices file, as well as -the /proc/bus/usb/BBB/DDD files. - -In many modern systems the usbfs filesystem isn't used at all. Instead -USB device nodes are created under /dev/usb/ or someplace similar. The -"devices" file is available in debugfs, typically as -/sys/kernel/debug/usb/devices. - - -**NOTE**: If /proc/bus/usb appears empty, and a host controller - driver has been linked, then you need to mount the - filesystem. Issue the command (as root): - - mount -t usbfs none /proc/bus/usb - - An alternative and more permanent method would be to add - - none /proc/bus/usb usbfs defaults 0 0 - - to /etc/fstab. This will mount usbfs at each reboot. - You can then issue `cat /sys/kernel/debug/usb/devices` to extract - USB device information, and user mode drivers can use usbfs - to interact with USB devices. - - There are a number of mount options supported by usbfs. - Consult the source code (linux/drivers/usb/core/inode.c) for - information about those options. - -**NOTE**: The filesystem has been renamed from "usbdevfs" to - "usbfs", to reduce confusion with "devfs". You may - still see references to the older "usbdevfs" name. - -For more information on mounting the usbfs file system, see the -"USB Device Filesystem" section of the USB Guide. The latest copy -of the USB Guide can be found at http://www.linux-usb.org/ - - -THE /proc/bus/usb/BBB/DDD FILES: --------------------------------- -Each connected USB device has one file. The BBB indicates the bus -number. The DDD indicates the device address on that bus. Both -of these numbers are assigned sequentially, and can be reused, so -you can't rely on them for stable access to devices. For example, -it's relatively common for devices to re-enumerate while they are -still connected (perhaps someone jostled their power supply, hub, -or USB cable), so a device might be 002/027 when you first connect -it and 002/048 sometime later. - -These files can be read as binary data. The binary data consists -of first the device descriptor, then the descriptors for each -configuration of the device. Multi-byte fields in the device descriptor -are converted to host endianness by the kernel. The configuration -descriptors are in bus endian format! The configuration descriptor -are wTotalLength bytes apart. If a device returns less configuration -descriptor data than indicated by wTotalLength there will be a hole in -the file for the missing bytes. This information is also shown -in text form by the /sys/kernel/debug/usb/devices file, described later. - -These files may also be used to write user-level drivers for the USB -devices. You would open the /proc/bus/usb/BBB/DDD file read/write, -read its descriptors to make sure it's the device you expect, and then -bind to an interface (or perhaps several) using an ioctl call. You -would issue more ioctls to the device to communicate to it using -control, bulk, or other kinds of USB transfers. The IOCTLs are -listed in the file, and at this writing the -source code (linux/drivers/usb/core/devio.c) is the primary reference -for how to access devices through those files. - -Note that since by default these BBB/DDD files are writable only by -root, only root can write such user mode drivers. You can selectively -grant read/write permissions to other users by using "chmod". Also, -usbfs mount options such as "devmode=0666" may be helpful. - - - -THE /sys/kernel/debug/usb/devices FILE: -------------------------------- -In /sys/kernel/debug/usb/devices, each device's output has multiple -lines of ASCII output. -I made it ASCII instead of binary on purpose, so that someone -can obtain some useful data from it without the use of an -auxiliary program. However, with an auxiliary program, the numbers -in the first 4 columns of each "T:" line (topology info: -Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram. - -Each line is tagged with a one-character ID for that line: - -T = Topology (etc.) -B = Bandwidth (applies only to USB host controllers, which are - virtualized as root hubs) -D = Device descriptor info. -P = Product ID info. (from Device descriptor, but they won't fit - together on one line) -S = String descriptors. -C = Configuration descriptor info. (* = active configuration) -I = Interface descriptor info. -E = Endpoint descriptor info. - -======================================================================= - -/sys/kernel/debug/usb/devices output format: - -Legend: - d = decimal number (may have leading spaces or 0's) - x = hexadecimal number (may have leading spaces or 0's) - s = string - - -Topology info: - -T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd -| | | | | | | | |__MaxChildren -| | | | | | | |__Device Speed in Mbps -| | | | | | |__DeviceNumber -| | | | | |__Count of devices at this level -| | | | |__Connector/Port on Parent for this device -| | | |__Parent DeviceNumber -| | |__Level in topology for this bus -| |__Bus number -|__Topology info tag - - Speed may be: - 1.5 Mbit/s for low speed USB - 12 Mbit/s for full speed USB - 480 Mbit/s for high speed USB (added for USB 2.0); - also used for Wireless USB, which has no fixed speed - 5000 Mbit/s for SuperSpeed USB (added for USB 3.0) - - For reasons lost in the mists of time, the Port number is always - too low by 1. For example, a device plugged into port 4 will - show up with "Port=03". - -Bandwidth info: -B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd -| | | |__Number of isochronous requests -| | |__Number of interrupt requests -| |__Total Bandwidth allocated to this bus -|__Bandwidth info tag - - Bandwidth allocation is an approximation of how much of one frame - (millisecond) is in use. It reflects only periodic transfers, which - are the only transfers that reserve bandwidth. Control and bulk - transfers use all other bandwidth, including reserved bandwidth that - is not used for transfers (such as for short packets). - - The percentage is how much of the "reserved" bandwidth is scheduled by - those transfers. For a low or full speed bus (loosely, "USB 1.1"), - 90% of the bus bandwidth is reserved. For a high speed bus (loosely, - "USB 2.0") 80% is reserved. - - -Device descriptor info & Product ID info: - -D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd -P: Vendor=xxxx ProdID=xxxx Rev=xx.xx - -where -D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd -| | | | | | |__NumberConfigurations -| | | | | |__MaxPacketSize of Default Endpoint -| | | | |__DeviceProtocol -| | | |__DeviceSubClass -| | |__DeviceClass -| |__Device USB version -|__Device info tag #1 - -where -P: Vendor=xxxx ProdID=xxxx Rev=xx.xx -| | | |__Product revision number -| | |__Product ID code -| |__Vendor ID code -|__Device info tag #2 - - -String descriptor info: - -S: Manufacturer=ssss -| |__Manufacturer of this device as read from the device. -| For USB host controller drivers (virtual root hubs) this may -| be omitted, or (for newer drivers) will identify the kernel -| version and the driver which provides this hub emulation. -|__String info tag - -S: Product=ssss -| |__Product description of this device as read from the device. -| For older USB host controller drivers (virtual root hubs) this -| indicates the driver; for newer ones, it's a product (and vendor) -| description that often comes from the kernel's PCI ID database. -|__String info tag - -S: SerialNumber=ssss -| |__Serial Number of this device as read from the device. -| For USB host controller drivers (virtual root hubs) this is -| some unique ID, normally a bus ID (address or slot name) that -| can't be shared with any other device. -|__String info tag - - - -Configuration descriptor info: - -C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA -| | | | | |__MaxPower in mA -| | | | |__Attributes -| | | |__ConfiguratioNumber -| | |__NumberOfInterfaces -| |__ "*" indicates the active configuration (others are " ") -|__Config info tag - - USB devices may have multiple configurations, each of which act - rather differently. For example, a bus-powered configuration - might be much less capable than one that is self-powered. Only - one device configuration can be active at a time; most devices - have only one configuration. - - Each configuration consists of one or more interfaces. Each - interface serves a distinct "function", which is typically bound - to a different USB device driver. One common example is a USB - speaker with an audio interface for playback, and a HID interface - for use with software volume control. - - -Interface descriptor info (can be multiple per Config): - -I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss -| | | | | | | | |__Driver name -| | | | | | | | or "(none)" -| | | | | | | |__InterfaceProtocol -| | | | | | |__InterfaceSubClass -| | | | | |__InterfaceClass -| | | | |__NumberOfEndpoints -| | | |__AlternateSettingNumber -| | |__InterfaceNumber -| |__ "*" indicates the active altsetting (others are " ") -|__Interface info tag - - A given interface may have one or more "alternate" settings. - For example, default settings may not use more than a small - amount of periodic bandwidth. To use significant fractions - of bus bandwidth, drivers must select a non-default altsetting. - - Only one setting for an interface may be active at a time, and - only one driver may bind to an interface at a time. Most devices - have only one alternate setting per interface. - - -Endpoint descriptor info (can be multiple per Interface): - -E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss -| | | | |__Interval (max) between transfers -| | | |__EndpointMaxPacketSize -| | |__Attributes(EndpointType) -| |__EndpointAddress(I=In,O=Out) -|__Endpoint info tag - - The interval is nonzero for all periodic (interrupt or isochronous) - endpoints. For high speed endpoints the transfer interval may be - measured in microseconds rather than milliseconds. - - For high speed periodic endpoints, the "MaxPacketSize" reflects - the per-microframe data transfer size. For "high bandwidth" - endpoints, that can reflect two or three packets (for up to - 3KBytes every 125 usec) per endpoint. - - With the Linux-USB stack, periodic bandwidth reservations use the - transfer intervals and sizes provided by URBs, which can be less - than those found in endpoint descriptor. - - -======================================================================= - - -If a user or script is interested only in Topology info, for -example, use something like "grep ^T: /sys/kernel/debug/usb/devices" -for only the Topology lines. A command like -"grep -i ^[tdp]: /sys/kernel/debug/usb/devices" can be used to list -only the lines that begin with the characters in square brackets, -where the valid characters are TDPCIE. With a slightly more able -script, it can display any selected lines (for example, only T, D, -and P lines) and change their output format. (The "procusb" -Perl script is the beginning of this idea. It will list only -selected lines [selected from TBDPSCIE] or "All" lines from -/sys/kernel/debug/usb/devices.) - -The Topology lines can be used to generate a graphic/pictorial -of the USB devices on a system's root hub. (See more below -on how to do this.) - -The Interface lines can be used to determine what driver is -being used for each device, and which altsetting it activated. - -The Configuration lines could be used to list maximum power -(in milliamps) that a system's USB devices are using. -For example, "grep ^C: /sys/kernel/debug/usb/devices". - - -Here's an example, from a system which has a UHCI root hub, -an external hub connected to the root hub, and a mouse and -a serial converter connected to the external hub. - -T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 -B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0 -D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0000 ProdID=0000 Rev= 0.00 -S: Product=USB UHCI Root Hub -S: SerialNumber=dce0 -C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA -I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub -E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms - -T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 -D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0451 ProdID=1446 Rev= 1.00 -C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub -E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms - -T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 -D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=04b4 ProdID=0001 Rev= 0.00 -C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse -E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms - -T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 -D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0565 ProdID=0001 Rev= 1.08 -S: Manufacturer=Peracom Networks, Inc. -S: Product=Peracom USB to Serial Converter -C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial -E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms -E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms -E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms - - -Selecting only the "T:" and "I:" lines from this (for example, by using -"procusb ti"), we have: - -T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 -T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 -I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub -T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 -I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse -T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 -I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial - - -Physically this looks like (or could be converted to): - - +------------------+ - | PC/root_hub (12)| Dev# = 1 - +------------------+ (nn) is Mbps. - Level 0 | CN.0 | CN.1 | [CN = connector/port #] - +------------------+ - / - / - +-----------------------+ - Level 1 | Dev#2: 4-port hub (12)| - +-----------------------+ - |CN.0 |CN.1 |CN.2 |CN.3 | - +-----------------------+ - \ \____________________ - \_____ \ - \ \ - +--------------------+ +--------------------+ - Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)| - +--------------------+ +--------------------+ - - - -Or, in a more tree-like structure (ports [Connectors] without -connections could be omitted): - -PC: Dev# 1, root hub, 2 ports, 12 Mbps -|_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps - |_ CN.0: Dev #3, mouse, 1.5 Mbps - |_ CN.1: - |_ CN.2: Dev #4, serial, 12 Mbps - |_ CN.3: -|_ CN.1: - - - ### END ### -- cgit v1.2.3-55-g7522