PM: add /sys/power documentation to Documentation/ABI
RFC PATCH 1/1 PM: add /sys/power documentation to Documentation/ABI
The file sysfs-power that documents the interface in the /sys/power/ directory is added to Documentation/ABI/testing.
--- Documentation/ABI/testing/sysfs-power | 88 ++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+)
Documentation/ABI/testing/sysfs-power new file +88 -0
@@ -0,0 +1,88 @@ +What: /sys/power/ +Date: August 2006 +Contact: Rafael J. Wysocki <[email protected]> +Description: + The /sys/power directory will contain files that will + provide a unified interface to the power management + subsystem. + +What: /sys/power/state +Date: August 2006 +Contact: Rafael J. Wysocki <[email protected]> +Description: + The /sys/power/state file controls the system power state. + Reading from this file returns what states are supported, + which is hard-coded to 'standby' (Power-On Suspend), 'mem' + (Suspend-to-RAM), and 'disk' (Suspend-to-Disk). + + Writing to this file one of these strings causes the system to + transition into that state. Please see the file + Documentation/power/states.txt for a description of each of + these states. + +What: /sys/power/disk +Date: August 2006 +Contact: Rafael J. Wysocki <[email protected]> +Description: + The /sys/power/disk file controls the operating mode of the + suspend-to-disk mechanism. Reading from this file returns + the name of the method by which the system will be put to + sleep on the next suspend. There are four methods supported: + 'firmware' - means that the memory image will be saved to disk + by some firmware, in which case we also assume that the + firmware will handle the system suspend. + 'platform' - the memory image will be saved by the kernel and + the system will be put to sleep by the platform driver (e.g. + ACPI or other PM registers). + 'shutdown' - the memory image will be saved by the kernel and + the system will be powered off. + 'reboot' - the memory image will be saved by the kernel and + the system will be rebooted. + + The suspend-to-disk method may be chosen by writing to this + file one of the accepted strings: + + 'firmware' + 'platform' + 'shutdown' + 'reboot' + + It will only change to 'firmware' or 'platform' if the system + supports that. + +What: /sys/power/image_size +Date: August 2006 +Contact: Rafael J. Wysocki <[email protected]> +Description: + The /sys/power/image_size file controls the size of the image + created by the suspend-to-disk mechanism. It can be written a + string representing a non-negative integer that will be used + as an upper limit of the image size, in bytes. The kernel's + suspend-to-disk code will do its best to ensure the image size + will not exceed this number. However, if it turns out to be + impossible, the kernel will try to suspend anyway using the + smallest image possible. In particular, if "0" is written to + this file, the suspend image will be as small as possible. + + Reading from this file will display the current image size + limit, which is set to 500 MB by default. + +What: /sys/power/pm_trace +Date: August 2006 +Contact: Rafael J. Wysocki <[email protected]> +Description: + The /sys/power/pm_trace file controls the code which saves the + last PM event point in the RTC across reboots, so that you can + debug a machine that just hangs during suspend (or more + commonly, during resume). Namely, the RTC is only used to save + the last PM event point if this file contains '1'. Initially + it contains '0' which may be changed to '1' by writing a + string representing a nonzero integer into it. + + To use this debugging feature you should attempt to suspend + the machine, then reboot it and run + + dmesg -s 1000000 | grep 'hash matches' + + CAUTION: Using it will cause your machine's real-time (CMOS) + clock to be set to a random invalid time after a resume.
Quoted 4 lines · Rafael J. Wysocki
The file sysfs-power that documents the interface in the
/sys/power/directory is added toDocumentation/ABI/testing.Signed-off-by Rafael J. Wysocki <[email protected]>
Looks good to me, ACK.
Pavel
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Quoted 1 line · On Wed, 30 Aug 2006 23:38:06 +0200 "Rafael J. Wysocki" <[email protected]> wrote:
Documentation/ABI/testing
psst, Greg, they're still sending too much stuff: need more paperwork!
Some words about this in Documentation/SubmitChecklist would be nice.
Quoted 8 lines · On Wed, 30 Aug 2006 14:43:50 -0700 Andrew Morton wrote:
Quoted 1 line · On Wed, 30 Aug 2006 23:38:06 +0200 "Rafael J. Wysocki" <[email protected]> wrote:
Documentation/ABI/testingpsst, Greg, they're still sending too much stuff: need more paperwork!
Some words about this in
Documentation/SubmitChecklistwould be nice.
and people actually using it would be nice(r).
Is this close to what you are looking for?
---
From: Randy Dunlap <[email protected]>
Mention Documenation/ABI/ requirements in Documentation/SubmitChecklist.
--- Documentation/SubmitChecklist | 3 +++ 1 files changed, 3 insertions(+)
Documentation/SubmitChecklist +3 -0
@@ -61,3 +61,6 @@ kernel patches. Documentation/kernel-parameters.txt. 18: All new module parameters are documented with MODULE_PARM_DESC() + +19: All new userspace interfaces are documented in Documentation/ABI/. + See Documentation/ABI/README for more information.
Quoted 5 lines · On Wed, 30 Aug 2006 15:03:58 -0700 "Randy.Dunlap" <[email protected]> wrote:
Quoted 3 lines · On Wed, 30 Aug 2006 14:43:50 -0700 Andrew Morton wrote:
On Wed, 30 Aug 2006 23:38:06 +0200
"Rafael J. Wysocki" <[email protected]> wrote:
Quoted 7 lines
Quoted 5 lines
Quoted 1 line
Documentation/ABI/testingpsst, Greg, they're still sending too much stuff: need more paperwork!
Some words about this in
Documentation/SubmitChecklistwould be nice.and people actually using it would be nice(r).
c'mon, it must be taped to 1,000 monitors and bathroom doors by now?
Quoted 1 line
Is this close to what you are looking for?
I guess so, thanks. Pointing at the README was sneaky.
Quoted 13 lines
From: Randy Dunlap <[email protected]>
Mention Documenation/ABI/ requirements in
Documentation/SubmitChecklist.Signed-off-by Randy Dunlap <[email protected]>--- Documentation/SubmitChecklist | 3 +++ 1 files changed, 3 insertions(+)
Documentation/SubmitChecklist kernel patches. · line 66
Quoted 6 lines
Documentation/SubmitChecklist +3
-0@@ -61,3 +61,6 @@ kernel patches. Documentation/kernel-parameters.txt. 18: All new module parameters are documented with MODULE_PARM_DESC() + +19: All new userspace interfaces are documented in Documentation/ABI/. + See Documentation/ABI/README for more information.
This ABI/ thing rather snuck under my radar (I saw it go past, but a lot of things go past).
It'll be good if it works, but it is going to take quite a lot of thought, effort and maintainer vigilance to be successful and to avoid becoming rotware.
I wonder how hard it would be to write a script which parses a diff, works out if it touches ABI things, complain if it doesn't alter Documentation/ABI/*? Not very - it's just a matter of defining a suitable regexp.
What _should_ be documented in there, anyway?
- syscalls, obviously.
- /proc? If so, everything, or are there exceptions?
- /sys? If so, everything, or are there exceptions?
- ioctl numbers and payloads?
- netlink messages?
- ethtool thingies? netdev interface names? /proc/iomem identifiers? module names? kernel-thread comm[] contents? The ABI is pretty fat.
scary.
Quoted 3 lines · Andrew Morton
This ABI/ thing rather snuck under my radar (I saw it go past, but a lot of things go past).
It had a lot of review the first time around. The second and third had relatively little.
Quoted 3 lines
It'll be good if it works, but it is going to take quite a lot of thought, effort and maintainer vigilance to be successful and to avoid becoming rotware.
I agree.
Quoted 4 lines
I wonder how hard it would be to write a script which parses a diff, works out if it touches ABI things, complain if it doesn't alter
Documentation/ABI/*? Not very - it's just a matter of defining a suitable regexp.
That would be good to have.
Quoted 8 lines
What _should_ be documented in there, anyway?
- syscalls, obviously.
- /proc? If so, everything, or are there exceptions?
- /sys? If so, everything, or are there exceptions?
Quoted 8 lines
- ioctl numbers and payloads?
- netlink messages?
- ethtool thingies? netdev interface names?
/proc/iomemidentifiers? module names? kernel-thread comm[] contents? The ABI is pretty fat.scary.
Yes, our ABI is scary. And yes, all of the above is needed to be documented if we want to have a handle on this thing.
It is probably something that we can throw at the janitors list for the existing stuff to get some help.
thanks,
greg k-h
Quoted 6 lines · Andrew Morton
Quoted 1 line · On Wed, 30 Aug 2006 23:38:06 +0200 "Rafael J. Wysocki" <[email protected]> wrote:
Documentation/ABI/testingpsst, Greg, they're still sending too much stuff: need more paperwork!
Pavel's secret plan for world domination:
a) pick one of those google job offers, and reply to them
b) get employed by google
c) sneak into akpm's office
d) install backdoor allowing patches to be installed
Pavel
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html