Re: [RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

Re: [RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

[Pavel Machek]

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 <rjw@sisk.pl>

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

[RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

[Rafael J. Wysocki]

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 <rjw@sisk.pl>
---
 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 <rjw@sisk.pl>
+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 <rjw@sisk.pl>
+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 <rjw@sisk.pl>
+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 <rjw@sisk.pl>
+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 <rjw@sisk.pl>
+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.

Re: [RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

[Andrew Morton]

On Wed, 30 Aug 2006 23:38:06 +0200
"Rafael J. Wysocki" <rjw@sisk.pl> 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.

Re: [RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

[Randy.Dunlap]

On Wed, 30 Aug 2006 14:43:50 -0700 Andrew Morton wrote:

> On Wed, 30 Aug 2006 23:38:06 +0200
> "Rafael J. Wysocki" <rjw@sisk.pl> 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 <rdunlap@xenotime.net>

Mention Documenation/ABI/ requirements in Documentation/SubmitChecklist.

Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
---
 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.

Re: [RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

[Pavel Machek]

On Wed 2006-08-30 14:43:50, Andrew Morton wrote:
> On Wed, 30 Aug 2006 23:38:06 +0200
> "Rafael J. Wysocki" <rjw@sisk.pl> 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

Re: [RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

[Andrew Morton]

On Wed, 30 Aug 2006 15:03:58 -0700
"Randy.Dunlap" <rdunlap@xenotime.net> 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" <rjw@sisk.pl> 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 <rdunlap@xenotime.net>
> 
> Mention Documenation/ABI/ requirements in Documentation/SubmitChecklist.
> 
> Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
> ---
>  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.

Re: [RFC][PATCH -mm] PM: add /sys/power documentation to Documentation/ABI

[Greg KH]

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