Skip to contentSkip to conversation

Documentation: Ask driver writers to provide suspend/resume support

RFC PATCH In review Rafael J. Wysocki 2 participants 7 messages Feb 17, 2007 – Feb 18, 2007

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 Documentation: Ask driver writers to provide suspend/resume support

Add a paragraph in Documentation/SubmittingDrivers requesting that the susped/resume support be provided by new device drivers.

Add the document Documentation/power/drivers-testing.txt giving general instructions for the testing of suspend/resume support in device drivers.

---
 Documentation/SubmittingDrivers         |   10 ++
 Documentation/power/drivers-testing.txt |  146 ++++++++++++++++++++++++++++++++
 2 files changed, 156 insertions(+)
Documentation/SubmittingDrivers +10 -0
Index: linux-2.6.20-git13/Documentation/SubmittingDrivers
===================================================================
@@ -87,6 +87,16 @@ Clarity:	It helps if anyone can see how 
 		driver that intentionally obfuscates how the hardware works
 		it will go in the bitbucket.
 
+PM support:	Since Linux is used on many portable and desktop systems, your
+		driver is likely to be used on such a system and therefore it
+		should support basic power management by implementing, if
+		necessary, the .suspend and .resume methods used during the
+		system-wide suspend and resume transitions.  You should verify
+		that your driver correctly handles the suspend and resume, but
+		if you are unable to ensure that, please at least define the
+		.suspend method returning the -ENOSYS ("Function not
+		implemented") error.
+
 Control:	In general if there is active maintainance of a driver by
 		the author then patches will be redirected to them unless
 		they are totally obvious and without need of checking.
Documentation/power/drivers-testing.txt new file +146 -0

146 lines not on this page · raw message

#1 lore raw

Hi!

Quoted 18 lines

Add a paragraph in Documentation/SubmittingDrivers requesting that the susped/resume support be provided by new device drivers.

Add the document Documentation/power/drivers-testing.txt giving general instructions for the testing of suspend/resume support in device drivers.

---
 Documentation/SubmittingDrivers         |   10 ++
 Documentation/power/drivers-testing.txt |  146 ++++++++++++++++++++++++++++++++
 2 files changed, 156 insertions(+)

Index: linux-2.6.20-git13/Documentation/SubmittingDrivers
===================================================================

Documentation/SubmittingDrivers +0 -0
@@ -87,6 +87,16 @@ Clarity:	It helps if anyone can see how 
 		driver that intentionally obfuscates how the hardware works
 		it will go in the bitbucket.

Documentation/SubmittingDrivers Clarity: It helps if anyone can see how · line 98

Quoted 10 lines
Documentation/SubmittingDrivers +9 -0
 
+PM support:	Since Linux is used on many portable and desktop systems, your
+		driver is likely to be used on such a system and therefore it
+		should support basic power management by implementing, if
+		necessary, the .suspend and .resume methods used during the
+		system-wide suspend and resume transitions.  You should verify
+		that your driver correctly handles the suspend and resume, but
+		if you are unable to ensure that, please at least define the
+		.suspend method returning the -ENOSYS ("Function not
+		implemented") error.

Perhaps pointer to Documentation/power/drivers-testing.txt would be useful here?

Documentation/power/drivers-testing.txt line 2

Quoted 10 lines
Documentation/SubmittingDrivers +0 -0
 Control:	In general if there is active maintainance of a driver by
 		the author then patches will be redirected to them unless
 		they are totally obvious and without need of checking.

Index: linux-2.6.20-git13/Documentation/power/drivers-testing.txt
===================================================================

Documentation/power/drivers-testing.txt new file +2 -0
@@ -0,0 +1,146 @@
+Testing suspend and resume support in drivers
+	(C) 2007 Rafael J. Wysocki <[email protected]>

If you add copyright, maybe specify license, too? (", GPL" should be enough).

Documentation/power/drivers-testing.txt line 10

Quoted 7 lines
Documentation/power/drivers-testing.txt new file +7 -0
+Unfortunately, to effectively test the support for the system-wide suspend and
+resume transitions in a driver, it is necessary to suspend and resume a fully
+functional system with this driver loaded.  Moreover, that should be done many
+times, preferably many times in a row, and separately for the suspend to disk
+(STD) and the suspend to RAM (STR) transitions, because each of these cases
+involves different ordering of operations and different interactions with the
+machine's BIOS.

Hmm, actually it is nice to mix STR + STD, too... and not sure if "many" is right word... It sounds scary :-).

Documentation/power/drivers-testing.txt

Quoted 9 lines
Documentation/power/drivers-testing.txt new file +9 -0
+To verify that the STD works, you can try to suspend in the "reboot" mode:
+
+# echo reboot > /sys/power/disk
+# echo disk > /sys/power/state
+
+and the system should suspend, reboot, resume and get back to the command prompt
+where you have started the transition.  If that happens, the STD is most likely
+to work correctly, but you need to repeat the test at least a couple of times in
+a row for confidence.  This is necessary because some problems only

, because?

Documentation/power/drivers-testing.txt line 92

Quoted 1 line
Documentation/power/drivers-testing.txt new file +1 -0
+c) Advanced debugging

Actually, those debugging instructions look really cool. Perhaps we should split them into separate file, as it is also interesting for users trying to get suspend working on their machine?

Quoted 13 lines
Documentation/power/drivers-testing.txt new file +13 -0
+II. Testing the driver
+
+Once you have resolved the suspend/resume-related problems with your test system
+without the new driver, you are ready to test it:
+
+1. Build the driver as a module, load it and try the STD in the test mode
+(cf. 1a)).
+
+2. Compile the driver directly into the kernel and try the STD in the test mode
+(cf. 1a)).
+
+3. Build the driver as a module, load it and attempt to suspend to disk in the
+"reboot", "shutdown" and "platform" modes (cf. 1).

Documentation/power/drivers-testing.txt line 146

Quoted 10 lines
Documentation/power/drivers-testing.txt new file +10 -0
+
+4. Compile the driver directly into the kernel and attempt to suspend to disk in
+the "reboot", "shutdown" and "platform" modes (cf. 1).
+
+5. Build the driver as a module, load it and attempt to run s2ram (cf. 2).
+
+6. Compile the driver directly into the kernel and attempt to run s2ram (cf. 2).
+
+Each of the above tests should be repeated several times and if any of them
+fails, the driver cannot be regarded as suspend/resume-safe.

Maybe reorder the tests so that poor submitter will not have to do 3 kernel compiles?
Pavel

Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
#2 lore raw

Hi,

Quoted 21 lines · Pavel Machek

Hi!

Quoted 19 lines

Add a paragraph in Documentation/SubmittingDrivers requesting that the susped/resume support be provided by new device drivers.

Add the document Documentation/power/drivers-testing.txt giving general instructions for the testing of suspend/resume support in device drivers.

---
 Documentation/SubmittingDrivers         |   10 ++
 Documentation/power/drivers-testing.txt |  146 ++++++++++++++++++++++++++++++++
 2 files changed, 156 insertions(+)

Index: linux-2.6.20-git13/Documentation/SubmittingDrivers
===================================================================

Documentation/SubmittingDrivers +0 -0
@@ -87,6 +87,16 @@ Clarity:	It helps if anyone can see how 
 		driver that intentionally obfuscates how the hardware works
 		it will go in the bitbucket.
 
Quoted 12 lines

Documentation/SubmittingDrivers Clarity: It helps if anyone can see how · line 98

Quoted 9 lines
Documentation/SubmittingDrivers +9 -0
+PM support:	Since Linux is used on many portable and desktop systems, your
+		driver is likely to be used on such a system and therefore it
+		should support basic power management by implementing, if
+		necessary, the .suspend and .resume methods used during the
+		system-wide suspend and resume transitions.  You should verify
+		that your driver correctly handles the suspend and resume, but
+		if you are unable to ensure that, please at least define the
+		.suspend method returning the -ENOSYS ("Function not
+		implemented") error.

Perhaps pointer to Documentation/power/drivers-testing.txt would be useful here?

Okay, maybe something like this:

"Please see Documentation/power/drivers-testing.txt for the driver testing instructions."

as the last sentence?

Quoted 4 lines
Quoted 4 lines
Documentation/SubmittingDrivers +0 -0
 Control:	In general if there is active maintainance of a driver by
 		the author then patches will be redirected to them unless
 		they are totally obvious and without need of checking.

Index: linux-2.6.20-git13/Documentation/power/drivers-testing.txt

Quoted 8 lines

Documentation/power/drivers-testing.txt line 2

Quoted 6 lines

===================================================================

Documentation/power/drivers-testing.txt new file +2 -0
@@ -0,0 +1,146 @@
+Testing suspend and resume support in drivers
+	(C) 2007 Rafael J. Wysocki <[email protected]>

If you add copyright, maybe specify license, too? (", GPL" should be enough).

OK

Quoted 10 lines

Documentation/power/drivers-testing.txt line 10

Quoted 7 lines
Documentation/power/drivers-testing.txt new file +7 -0
+Unfortunately, to effectively test the support for the system-wide suspend and
+resume transitions in a driver, it is necessary to suspend and resume a fully
+functional system with this driver loaded.  Moreover, that should be done many
+times, preferably many times in a row, and separately for the suspend to disk
+(STD) and the suspend to RAM (STR) transitions, because each of these cases
+involves different ordering of operations and different interactions with the
+machine's BIOS.

Hmm, actually it is nice to mix STR + STD, too... and not sure if "many" is right word... It sounds scary :-).

"a couple of"?

Quoted 11 lines

Documentation/power/drivers-testing.txt

Quoted 9 lines
Documentation/power/drivers-testing.txt new file +9 -0
+To verify that the STD works, you can try to suspend in the "reboot" mode:
+
+# echo reboot > /sys/power/disk
+# echo disk > /sys/power/state
+
+and the system should suspend, reboot, resume and get back to the command prompt
+where you have started the transition.  If that happens, the STD is most likely
+to work correctly, but you need to repeat the test at least a couple of times in
+a row for confidence.  This is necessary because some problems only

, because?

OK

Quoted 5 lines

Documentation/power/drivers-testing.txt line 92

Quoted 1 line
Documentation/power/drivers-testing.txt new file +1 -0
+c) Advanced debugging

Actually, those debugging instructions look really cool. Perhaps we should split them into separate file, as it is also interesting for users trying to get suspend working on their machine?

OK

basic-pm-debugging.txt and driver-testing.txt ?

Quoted 18 lines
Quoted 18 lines
Documentation/power/drivers-testing.txt new file +18 -0
+II. Testing the driver
+
+Once you have resolved the suspend/resume-related problems with your test system
+without the new driver, you are ready to test it:
+
+1. Build the driver as a module, load it and try the STD in the test mode
+(cf. 1a)).
+
+2. Compile the driver directly into the kernel and try the STD in the test mode
+(cf. 1a)).
+
+3. Build the driver as a module, load it and attempt to suspend to disk in the
+"reboot", "shutdown" and "platform" modes (cf. 1).
+
+4. Compile the driver directly into the kernel and attempt to suspend to disk in
+the "reboot", "shutdown" and "platform" modes (cf. 1).
+
+5. Build the driver as a module, load it and attempt to run s2ram (cf. 2).
Quoted 8 lines

Documentation/power/drivers-testing.txt line 146

Quoted 5 lines
Documentation/power/drivers-testing.txt new file +5 -0
+
+6. Compile the driver directly into the kernel and attempt to run s2ram (cf. 2).
+
+Each of the above tests should be repeated several times and if any of them
+fails, the driver cannot be regarded as suspend/resume-safe.

Maybe reorder the tests so that poor submitter will not have to do 3 kernel compiles?

I thought he would figure out that there's more efficient way. ;-)

Greetings,
Rafael

#3 lore raw

Hi!

Quoted 13 lines
Quoted 4 lines
Quoted 4 lines
Documentation/SubmittingDrivers +4 -0
+PM support:	Since Linux is used on many portable and desktop systems, your
+		driver is likely to be used on such a system and therefore it
+		should support basic power management by implementing, if
+		necessary, the .suspend and .resume methods used during the
Quoted 8 lines

Documentation/SubmittingDrivers Clarity: It helps if anyone can see how · line 98

Quoted 5 lines
Documentation/SubmittingDrivers +5 -0
+		system-wide suspend and resume transitions.  You should verify
+		that your driver correctly handles the suspend and resume, but
+		if you are unable to ensure that, please at least define the
+		.suspend method returning the -ENOSYS ("Function not
+		implemented") error.

Perhaps pointer to Documentation/power/drivers-testing.txt would be useful here?

Quoted 6 lines

Okay, maybe something like this:

"Please see Documentation/power/drivers-testing.txt for the driver testing instructions."

as the last sentence?

Looks ok. (BTW you have my ACK).

Quoted 11 lines
Quoted 10 lines

Documentation/power/drivers-testing.txt line 10

Quoted 7 lines
Documentation/power/drivers-testing.txt new file +7 -0
+Unfortunately, to effectively test the support for the system-wide suspend and
+resume transitions in a driver, it is necessary to suspend and resume a fully
+functional system with this driver loaded.  Moreover, that should be done many
+times, preferably many times in a row, and separately for the suspend to disk
+(STD) and the suspend to RAM (STR) transitions, because each of these cases
+involves different ordering of operations and different interactions with the
+machine's BIOS.

Hmm, actually it is nice to mix STR + STD, too... and not sure if "many" is right word... It sounds scary :-).

Quoted 1 line

"a couple of"?

Sounds good.

Quoted 27 lines
Quoted 18 lines
Quoted 18 lines
Documentation/power/drivers-testing.txt new file +18 -0
+II. Testing the driver
+
+Once you have resolved the suspend/resume-related problems with your test system
+without the new driver, you are ready to test it:
+
+1. Build the driver as a module, load it and try the STD in the test mode
+(cf. 1a)).
+
+2. Compile the driver directly into the kernel and try the STD in the test mode
+(cf. 1a)).
+
+3. Build the driver as a module, load it and attempt to suspend to disk in the
+"reboot", "shutdown" and "platform" modes (cf. 1).
+
+4. Compile the driver directly into the kernel and attempt to suspend to disk in
+the "reboot", "shutdown" and "platform" modes (cf. 1).
+
+5. Build the driver as a module, load it and attempt to run s2ram (cf. 2).
Quoted 8 lines

Documentation/power/drivers-testing.txt line 146

Quoted 5 lines
Documentation/power/drivers-testing.txt new file +5 -0
+
+6. Compile the driver directly into the kernel and attempt to run s2ram (cf. 2).
+
+Each of the above tests should be repeated several times and if any of them
+fails, the driver cannot be regarded as suspend/resume-safe.

Maybe reorder the tests so that poor submitter will not have to do 3 kernel compiles?

Quoted 1 line

I thought he would figure out that there's more efficient way. ;-)

He probably will... but it reads strangely.

5. Build the driver as a module, load it and attempt to run s2ram. Then repeat with driver build-in?

Hmm, and maybe driver loaded/build in is not a difference for s2ram?

Pavel

Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
#4 lore raw

Hi,

Quoted 15 lines · Pavel Machek

Hi!

Quoted 13 lines
Quoted 12 lines

Documentation/SubmittingDrivers Clarity: It helps if anyone can see how · line 98

Quoted 9 lines
Documentation/SubmittingDrivers +9 -0
+PM support:	Since Linux is used on many portable and desktop systems, your
+		driver is likely to be used on such a system and therefore it
+		should support basic power management by implementing, if
+		necessary, the .suspend and .resume methods used during the
+		system-wide suspend and resume transitions.  You should verify
+		that your driver correctly handles the suspend and resume, but
+		if you are unable to ensure that, please at least define the
+		.suspend method returning the -ENOSYS ("Function not
+		implemented") error.

Perhaps pointer to Documentation/power/drivers-testing.txt would be useful here?

Quoted 8 lines
Quoted 6 lines

Okay, maybe something like this:

"Please see Documentation/power/drivers-testing.txt for the driver testing instructions."

as the last sentence?

Looks ok. (BTW you have my ACK).

Thanks.

Quoted 41 lines
Quoted 11 lines
Quoted 10 lines

Documentation/power/drivers-testing.txt line 10

Quoted 7 lines
Documentation/power/drivers-testing.txt new file +7 -0
+Unfortunately, to effectively test the support for the system-wide suspend and
+resume transitions in a driver, it is necessary to suspend and resume a fully
+functional system with this driver loaded.  Moreover, that should be done many
+times, preferably many times in a row, and separately for the suspend to disk
+(STD) and the suspend to RAM (STR) transitions, because each of these cases
+involves different ordering of operations and different interactions with the
+machine's BIOS.

Hmm, actually it is nice to mix STR + STD, too... and not sure if "many" is right word... It sounds scary :-).

Quoted 1 line

"a couple of"?

Sounds good.

Quoted 27 lines
Quoted 26 lines
Quoted 13 lines
Documentation/power/drivers-testing.txt new file +13 -0
+II. Testing the driver
+
+Once you have resolved the suspend/resume-related problems with your test system
+without the new driver, you are ready to test it:
+
+1. Build the driver as a module, load it and try the STD in the test mode
+(cf. 1a)).
+
+2. Compile the driver directly into the kernel and try the STD in the test mode
+(cf. 1a)).
+
+3. Build the driver as a module, load it and attempt to suspend to disk in the
+"reboot", "shutdown" and "platform" modes (cf. 1).

Documentation/power/drivers-testing.txt line 146

Quoted 10 lines
Documentation/power/drivers-testing.txt new file +10 -0
+
+4. Compile the driver directly into the kernel and attempt to suspend to disk in
+the "reboot", "shutdown" and "platform" modes (cf. 1).
+
+5. Build the driver as a module, load it and attempt to run s2ram (cf. 2).
+
+6. Compile the driver directly into the kernel and attempt to run s2ram (cf. 2).
+
+Each of the above tests should be repeated several times and if any of them
+fails, the driver cannot be regarded as suspend/resume-safe.

Maybe reorder the tests so that poor submitter will not have to do 3 kernel compiles?

Quoted 8 lines
Quoted 1 line

I thought he would figure out that there's more efficient way. ;-)

He probably will... but it reads strangely.

5. Build the driver as a module, load it and attempt to run s2ram. Then repeat with driver build-in?

Hmm, and maybe driver loaded/build in is not a difference for s2ram?

Good point. :-)

Greetings,
Rafael

#5 lore raw
Quoted 16 lines · Rafael J. Wysocki
Quoted 15 lines · Pavel Machek
Quoted 15 lines
Quoted 4 lines
Quoted 4 lines
(quoted diff) +4 -0
+PM support:	Since Linux is used on many portable and desktop systems, your
+		driver is likely to be used on such a system and therefore it
+		should support basic power management by implementing, if
+		necessary, the .suspend and .resume methods used during the
Quoted 8 lines

Review

Quoted 5 lines
(quoted diff) +5 -0
+		system-wide suspend and resume transitions.  You should verify
+		that your driver correctly handles the suspend and resume, but
+		if you are unable to ensure that, please at least define the
+		.suspend method returning the -ENOSYS ("Function not
+		implemented") error.

Perhaps pointer to Documentation/power/drivers-testing.txt would be useful here?

Okay, maybe something like this:

Quoted 8 lines
Quoted 6 lines
Quoted 4 lines

"Please see Documentation/power/drivers-testing.txt for the driver testing instructions."

as the last sentence?

Looks ok. (BTW you have my ACK).

Thanks.

Anyway, please have a look at the appended revised version. I have separated the driver testing and debugging documents and changed the paragraph in SubmittingDrivers a bit.

Greetings,
Rafael

---
 Documentation/SubmittingDrivers            |   11 +++
 Documentation/power/basic-pm-debugging.txt |  106 +++++++++++++++++++++++++++++
 Documentation/power/drivers-testing.txt    |   42 +++++++++++
 3 files changed, 159 insertions(+)
Documentation/SubmittingDrivers +11 -0
Index: linux-2.6.20-git13/Documentation/SubmittingDrivers
===================================================================
@@ -87,6 +87,17 @@ Clarity:	It helps if anyone can see how 
 		driver that intentionally obfuscates how the hardware works
 		it will go in the bitbucket.
 
+PM support:	Since Linux is used on many portable and desktop systems, your
+		driver is likely to be used on such a system and therefore it
+		should support basic power management by implementing, if
+		necessary, the .suspend and .resume methods used during the
+		system-wide suspend and resume transitions.  You should verify
+		that your driver correctly handles the suspend and resume, but
+		if you are unable to ensure that, please at least define the
+		.suspend method returning the -ENOSYS ("Function not
+		implemented") error.  For the driver testing instructions see
+		Documentation/power/drivers-testing.txt .
+
 Control:	In general if there is active maintainance of a driver by
 		the author then patches will be redirected to them unless
 		they are totally obvious and without need of checking.
Documentation/power/drivers-testing.txt new file +42 -0

42 lines not on this page · raw message

Documentation/power/basic-pm-debugging.txt new file +106 -0

106 lines not on this page · raw message

#6 lore raw

Hi!

Quoted 7 lines
Quoted 3 lines
Quoted 1 line

Looks ok. (BTW you have my ACK).

Thanks.

Anyway, please have a look at the appended revised version. I have separated the driver testing and debugging documents and changed the paragraph in SubmittingDrivers a bit.

Looks ok to me, but this time I've only scanned it quickly. Thanks!
Pavel

Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html