Documentation: sysfs-bus-usb: update power/persist description

PATCH Superseded Paul Bolle 2 participants 6 messages Jun 24, 2014 – Jul 2, 2014 ABI/API

Share & tools

Paul Bolle

author

2014-06-24 09:33 UTC #0 lore raw

PATCH 1/1 Documentation: sysfs-bus-usb: update power/persist description

There's no power/persist file for hubs. And CONFIG_USB_PERSIST was removed in v2.6.26. Update the description of power/persist accordingly.

Signed-off-by Paul Bolle <[email protected]>

---
I don't know anything about USB-Persist. Could Greg and Alan please check whether the new description does actually match reality?

 Documentation/ABI/stable/sysfs-bus-usb | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

Documentation/ABI/stable/sysfs-bus-usb +7 -7

index a6b685724740..a61d04b8fc78 100644
@@ -3,13 +3,13 @@ Date:		May 2007
 KernelVersion:	2.6.23
 Contact:	Alan Stern <stern-nwvwT67g6+6dFdvTe/[email protected]>
 Description:
-		If CONFIG_USB_PERSIST is set, then each USB device directory
-		will contain a file named power/persist.  The file holds a
-		boolean value (0 or 1) indicating whether or not the
-		"USB-Persist" facility is enabled for the device.  Since the
-		facility is inherently dangerous, it is disabled by default
-		for all devices except hubs.  For more information, see
-		Documentation/usb/persist.txt.
+		USB device directories for all devices except hubs will contain
+		a file named power/persist.  The file holds a boolean value (0
+		or 1) indicating whether or not the "USB-Persist" facility is
+		enabled for the device.  Since the facility is inherently
+		dangerous, it is disabled by default.  For hubs this facility is
+		always enabled making the file pointless.  For more information,
+		see Documentation/usb/persist.txt.
 
 What:		/sys/bus/usb/devices/.../power/autosuspend
 Date:		March 2007

Signature · 1 line

1.9.3

Alan Stern

2014-06-24 14:15 UTC #1 lore raw

Quoted 7 lines · Paul Bolle

There's no power/persist file for hubs. And CONFIG_USB_PERSIST was removed in v2.6.26. Update the description of power/persist accordingly.
Signed-off-by Paul Bolle <[email protected]>
---
I don't know anything about USB-Persist. Could Greg and Alan please check whether the new description does actually match reality?

Not exactly. More details below.

Quoted 15 lines

 Documentation/ABI/stable/sysfs-bus-usb | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

Documentation/ABI/stable/sysfs-bus-usb +0 -4

index a6b685724740..a61d04b8fc78 100644
@@ -3,13 +3,13 @@ Date:		May 2007
 KernelVersion:	2.6.23
 Contact:	Alan Stern <[email protected]>
 Description:
-		If CONFIG_USB_PERSIST is set, then each USB device directory
-		will contain a file named power/persist.  The file holds a
-		boolean value (0 or 1) indicating whether or not the
-		"USB-Persist" facility is enabled for the device.  Since the

Documentation/ABI/stable/sysfs-bus-usb Date: May 2007 · line 12

Quoted 10 lines

Documentation/ABI/stable/sysfs-bus-usb +7 -3

-		facility is inherently dangerous, it is disabled by default
-		for all devices except hubs.  For more information, see
-		Documentation/usb/persist.txt.
+		USB device directories for all devices except hubs will contain
+		a file named power/persist.  The file holds a boolean value (0
+		or 1) indicating whether or not the "USB-Persist" facility is
+		enabled for the device.  Since the facility is inherently
+		dangerous, it is disabled by default.  For hubs this facility is
+		always enabled making the file pointless.  For more information,
+		see Documentation/usb/persist.txt.

Instead of depending on CONFIG_USB_PERSIST, the power/persist attribute depends on CONFIG_PM. But pointing that out would be redundant, since the power/ device directory itself doesn't exist unless CONFIG_PM is enabled.

The default value for the persist facility depends on the setting of CONFIG_USB_DEFAULT_PERSIST. If that symbol is set then persist is enabled by default for all devices, except those which have the USB_QUIRK_RESET flag set (meaning that they will morph or change modes when reset). If the symbol is not set then persist is enabled by default only for hubs.

Thanks for the documentation update.

Alan Stern

Paul Bolle

author

2014-06-24 16:54 UTC #2 lore raw

Quoted 8 lines · Alan Stern

The default value for the persist facility depends on the setting of CONFIG_USB_DEFAULT_PERSIST. If that symbol is set then persist is enabled by default for all devices, except those which have the USB_QUIRK_RESET flag set (meaning that they will morph or change modes when reset). If the symbol is not set then persist is enabled by default only for hubs.
Thanks for the documentation update.

You do expect a v2 updated to reflect your comments, don't you?

Paul Bolle

Alan Stern

2014-06-24 17:17 UTC #3 lore raw

Quoted 11 lines · Paul Bolle

Quoted 8 lines · Alan Stern
The default value for the persist facility depends on the setting of CONFIG_USB_DEFAULT_PERSIST. If that symbol is set then persist is enabled by default for all devices, except those which have the USB_QUIRK_RESET flag set (meaning that they will morph or change modes when reset). If the symbol is not set then persist is enabled by default only for hubs.
Thanks for the documentation update.
You do expect a v2 updated to reflect your comments, don't you?

It would be nice.

Alan Stern

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Paul Bolle

author

2014-07-02 10:10 UTC #4 lore raw

PATCH v2 1/1 Documentation: sysfs-bus-usb: update power/persist description

There's no power/persist file for hubs. And CONFIG_USB_PERSIST was removed in v2.6.26. Update the description of power/persist accordingly. Also remove the line on its default value. It is not entirely correct, as CONFIG_USB_DEFAULT_PERSIST and the USB_QUIRK_RESET flag influence the default. It is not needed to understand this file anyhow.

Signed-off-by Paul Bolle <[email protected]>

---
v2: incorporate Alan's feedback. The clearest way to do that was to not mention the default value at all. Trying to do handle the default correctly made the text way too complicated. I hope Alan agrees.

Perhaps the line on hubs should not be added, as the text now states that device directories "can" contain this file.

 Documentation/ABI/stable/sysfs-bus-usb | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

Documentation/ABI/stable/sysfs-bus-usb +7 -7

index a6b685724740..e2bc700a6f9c 100644
@@ -3,13 +3,13 @@ Date:		May 2007
 KernelVersion:	2.6.23
 Contact:	Alan Stern <stern-nwvwT67g6+6dFdvTe/[email protected]>
 Description:
-		If CONFIG_USB_PERSIST is set, then each USB device directory
-		will contain a file named power/persist.  The file holds a
-		boolean value (0 or 1) indicating whether or not the
-		"USB-Persist" facility is enabled for the device.  Since the
-		facility is inherently dangerous, it is disabled by default
-		for all devices except hubs.  For more information, see
-		Documentation/usb/persist.txt.
+		USB device directories can contain a file named power/persist.
+		The file holds a boolean value (0 or 1) indicating whether or
+		not the "USB-Persist" facility is enabled for the device.  For
+		hubs this facility is always enabled and their device
+		directories will not contain this file.
+
+		For more information, see Documentation/usb/persist.txt.
 
 What:		/sys/bus/usb/devices/.../power/autosuspend
 Date:		March 2007

Signature · 1 line

1.9.3

Alan Stern

Acked-by on v2 1/1

2014-07-02 14:36 UTC #5 lore raw

Quoted 34 lines · Paul Bolle

There's no power/persist file for hubs. And CONFIG_USB_PERSIST was removed in v2.6.26. Update the description of power/persist accordingly. Also remove the line on its default value. It is not entirely correct, as CONFIG_USB_DEFAULT_PERSIST and the USB_QUIRK_RESET flag influence the default. It is not needed to understand this file anyhow.
Signed-off-by Paul Bolle <[email protected]>
---
v2: incorporate Alan's feedback. The clearest way to do that was to not mention the default value at all. Trying to do handle the default correctly made the text way too complicated. I hope Alan agrees.
Perhaps the line on hubs should not be added, as the text now states that device directories "can" contain this file.
 Documentation/ABI/stable/sysfs-bus-usb | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)
Documentation/ABI/stable/sysfs-bus-usb +0 -7
index a6b685724740..e2bc700a6f9c 100644
@@ -3,13 +3,13 @@ Date:		May 2007
 KernelVersion:	2.6.23
 Contact:	Alan Stern <stern-nwvwT67g6+6dFdvTe/[email protected]>
 Description:
-		If CONFIG_USB_PERSIST is set, then each USB device directory
-		will contain a file named power/persist.  The file holds a
-		boolean value (0 or 1) indicating whether or not the
-		"USB-Persist" facility is enabled for the device.  Since the
-		facility is inherently dangerous, it is disabled by default
-		for all devices except hubs.  For more information, see
-		Documentation/usb/persist.txt.

Documentation/ABI/stable/sysfs-bus-usb Date: May 2007 · line 15

Quoted 10 lines

Documentation/ABI/stable/sysfs-bus-usb +7 -0

+		USB device directories can contain a file named power/persist.
+		The file holds a boolean value (0 or 1) indicating whether or
+		not the "USB-Persist" facility is enabled for the device.  For
+		hubs this facility is always enabled and their device
+		directories will not contain this file.
+
+		For more information, see Documentation/usb/persist.txt.
 
 What:		/sys/bus/usb/devices/.../power/autosuspend
 Date:		March 2007

Acked-by Alan Stern <stern-nwvwT67g6+6dFdvTe/[email protected]>