The file sysfs-power that documents the interface in the /sys/power/ directory
is added to Documentation/ABI/testing.
Signed-off-by: Rafael J. Wysocki <[email protected]>
---
Documentation/ABI/testing/sysfs-power | 88 ++++++++++++++++++++++++++++++++++
1 file changed, 88 insertions(+)
Index: linux-2.6.18-rc4-mm3/Documentation/ABI/testing/sysfs-power
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.18-rc4-mm3/Documentation/ABI/testing/sysfs-power 2006-08-30 23:29:17.000000000 +0200
@@ -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.
On Wed 2006-08-30 23:38:06, Rafael J. Wysocki wrote:
> The file sysfs-power that documents the interface in the /sys/power/ directory
> is added to Documentation/ABI/testing.
>
> Signed-off-by: Rafael J. Wysocki <[email protected]>
Looks good to me, ACK.
Pavel
--
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
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.
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:
>
> > 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.
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.
Signed-off-by: Randy Dunlap <[email protected]>
---
Documentation/SubmitChecklist | 3 +++
1 files changed, 3 insertions(+)
--- linux-2618-rc5all.orig/Documentation/SubmitChecklist
+++ linux-2618-rc5all/Documentation/SubmitChecklist
@@ -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.
On Wed 2006-08-30 14:43:50, Andrew Morton wrote:
> 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!
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
--
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
On Wed, 30 Aug 2006 15:03:58 -0700
"Randy.Dunlap" <[email protected]> wrote:
> 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:
> >
> > > 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.
>
> and people actually using it would be nice(r).
c'mon, it must be taped to 1,000 monitors and bathroom doors by now?
> Is this close to what you are looking for?
I guess so, thanks. Pointing at the README was sneaky.
>
> 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(+)
>
> --- linux-2618-rc5all.orig/Documentation/SubmitChecklist
> +++ linux-2618-rc5all/Documentation/SubmitChecklist
> @@ -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.
On Wed, Aug 30, 2006 at 03:32:42PM -0700, Andrew Morton wrote:
>
> 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.
> 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.
> 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.
> 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.
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