[RFC][PATCH] 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(+) Index: linux-2.6.20-git13/Documentation/SubmittingDrivers === --- linux-2.6.20-git13.orig/Documentation/SubmittingDrivers +++ 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. Index: linux-2.6.20-git13/Documentation/power/drivers-testing.txt === --- /dev/null +++ linux-2.6.20-git13/Documentation/power/drivers-testing.txt @@ -0,0 +1,146 @@ +Testing suspend and resume support in drivers + (C) 2007 Rafael J. Wysocki <[EMAIL PROTECTED]> + +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. + +Of course, for this purpose the test system has to be known to suspend and +resume without the driver being tested. Thus, if possible, you should first +resolve all suspend/resume-related problems in the test system before you start +testing the new driver. + +I. Preparing the test system + +1. Testing suspend to disk (STD) + +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 show up on a +second attempt at suspending and resuming a driver. You should also test the +"platform" and "shutdown" modes of suspend: + +# echo platform > /sys/power/disk +# echo disk > /sys/power/state + +or + +# echo shutdown > /sys/power/disk +# echo disk > /sys/power/state + +in which cases you will have to press the power button to make the system +resume. If that works, you are ready to test the STD with the new driver +loaded. Otherwise, you have to identify what is wrong. + +a) Test mode of STD + +To verify if there are any drivers that cause problems you can run the STD +in the test mode: + +# echo test > /sys/power/disk +# echo disk > /sys/power/state + +in which case the system should freeze tasks, suspend devices, disable nonboot +CPUs (if any), wait for 5 seconds, enable nonboot CPUs, resume devices, thaw +tasks and return to your command prompt. If that fails, most likely there is +a driver that fails to either suspend or resume (in the latter case the system +may hang or be unstable after the test, so please take that into consideration). +To find this driver, you can carry out a binary search according to the rules: +- if the test fails, unload a half of the drivers currently loaded and repeat +(that would probably involve rebooting the system, so always note what drivers +have been loaded before the test), +- if the test succeeds, load a half of the drivers you have unloaded most +recently and repeat. + +Once you have found the failing driver (there can be more than just one of +them), you have to unload it every time before the STD transition. In that case +please make sure to repo
Re: [RFC][PATCH] Documentation: Ask driver writers to provide suspend/resume support
Hi! > 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 > === > --- linux-2.6.20-git13.orig/Documentation/SubmittingDrivers > +++ 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. Perhaps pointer to Documentation/power/drivers-testing.txt would be useful here? > 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 > === > --- /dev/null > +++ linux-2.6.20-git13/Documentation/power/drivers-testing.txt > @@ -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). > +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 :-). > +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? > +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? > +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). > + > +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 -- (english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body
Re: [RFC][PATCH] Documentation: Ask driver writers to provide suspend/resume support
Hi, On Saturday, 17 February 2007 11:59, Pavel Machek wrote: > Hi! > > > 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 > > === > > --- linux-2.6.20-git13.orig/Documentation/SubmittingDrivers > > +++ 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. > > 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? > > 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 > > === > > --- /dev/null > > +++ linux-2.6.20-git13/Documentation/power/drivers-testing.txt > > @@ -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 > > +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"? > > +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 > > +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 ? > > +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). > > + > > +6. Compile the driver directly into the kernel and attempt to run s2ram > > (cf. 2). > > + > > +Each of the above tests should be
Re: [RFC][PATCH] Documentation: Ask driver writers to provide suspend/resume support
Hi! > > > +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? Looks ok. (BTW you have my ACK). > > > +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"? Sounds good. > > > +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). > > > + > > > +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. ;-) 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 -- (english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC][PATCH] Documentation: Ask driver writers to provide suspend/resume support
Hi, On Saturday, 17 February 2007 12:40, Pavel Machek wrote: > Hi! > > > > > +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? > > Looks ok. (BTW you have my ACK). Thanks. > > > > +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"? > > Sounds good. > > > > +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). > > > > + > > > > +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. ;-) > > 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [RFC][PATCH] Documentation: Ask driver writers to provide suspend/resume support
On Saturday, 17 February 2007 21:57, Rafael J. Wysocki wrote: > On Saturday, 17 February 2007 12:40, Pavel Machek wrote: > > > > > +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? > > > > 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(+) Index: linux-2.6.20-git13/Documentation/SubmittingDrivers === --- linux-2.6.20-git13.orig/Documentation/SubmittingDrivers +++ 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. Index: linux-2.6.20-git13/Documentation/power/drivers-testing.txt === --- /dev/null +++ linux-2.6.20-git13/Documentation/power/drivers-testing.txt @@ -0,0 +1,42 @@ +Testing suspend and resume support in device drivers + (C) 2007 Rafael J. Wysocki <[EMAIL PROTECTED]>, GPL + +1. Preparing the test system + +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 +several times, preferably several 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. + +Of course, for this purpose the test system has to be known to suspend and +resume without the driver being tested. Thus, if possible, you should first +resolve all suspend/resume-related problems in the test system before you start +testing the new driver. Please see Documents/power/basic-pm-debugging.txt for +more information about the debugging of suspend/resume functionality. + +2. 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: + +a) Build the driver as a module, load it and try the STD in the test mode (see: +Documents/power/basic-pm-debugging.txt, 1a)). + +b) Load the driver and attempt to suspend to disk in the "reboot", "shutdown" +and "platform" modes (see: Documents/power/basic-pm-debugging.txt, 1). + +c) Compile the driver directly into the kernel and try the STD in the test mode. + +d) Attempt to suspend to disk with the driver compiled directly into the kernel +in the "reboot", "shut
Re: [RFC][PATCH] Documentation: Ask driver writers to provide suspend/resume support
Hi! > > > 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 -- (english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/