Document sysfs interface to RTC system wakeup

Document sysfs interface to RTC system wakeup

[Pavel Machek]

diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
index 8deffcd..ac843ab 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.txt
@@ -187,6 +187,88 @@ driver returns ENOIOCTLCMD.  Some common
 
 If all else fails, check out the rtc-test.c driver!
 
+	    Even newer /sys interface
+	    ~~~~~~~~~~~~~~~~~~~~~~~~~
+
+tino.keitel@gmx.de
+
+How to use /sys/class/rtc/rtcX/wakealarm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This file takes the seconds since epoch to enable a wake event at the
+specified time.
+
+If a '0' is written, the alarm is disabled.
+
+If the alarm was already enabled, a new alarm can only be set after the
+old alarm is disabled.
+
+
+Migration from /proc/acpi/alarm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Users of /proc/acpi/alarm have to change their code to supply the
+seconds since epoch instead of a date string.
+
+For shell scripts, this can be done using the date command, e.g. like
+this:
+
+date -d tomorrow "+%s"
+
+This returns the seconds since epoch of the current time on the
+following day.
+
+Please note that you have to disable the old alarm first, if you want
+to set a new alarm. Otherwise, you get an error. Example:
+
+echo 12345 > /sys/class/rtc/rtc0/wakealarm
+echo 0 > /sys/class/rtc/rtc0/wakealarm
+echo 23456 > /sys/class/rtc/rtc0/wakealarm
+
+
+cd /proc/acpi
+echo EXP0 > wakeup
+echo PCI1 > wakeup
+echo USB0 > wakeup
+echo USB1 > wakeup
+echo USB2 > wakeup
+echo USB7 > wakeup
+echo HDEF > wakeup
+cd /sys/class/rtc/rtc0
+echo $(( $(cat since_epoch) + 20 )) > wakealarm
+
+    [PATCH] RTC gets sysfs wakealarm attribute
+
+    This adds a new "wakealarm" sysfs attribute to RTC class devices which support
+    alarm operations and are wakeup-capable:
+
+     - It reads as either empty, or the scheduled alarm time as seconds
+       since the POSIX epoch.  (That time may already have passed, since
+       nothing currently enforces one-shot alarm semantics.)
+
+     - It can be written with an alarm time in the future, again seconds
+       since the POSIX epoch, which enables the alarm.
+
+     - It can be written with an alarm time not in the future (such as 0,
+       the start of the POSIX epoch) to disable the alarm.
+
+    Usage examples (some need GNU date) after "cd /sys/class/rtc/rtcN":
+
+        alarm after 10 minutes:
+        # echo $(( $(cat since_epoch) + 10 * 60 )) > wakealarm
+        alarm tuesday evening 10pm:
+        # date -d '10pm tuesday' "+%s" > wakealarm
+        disable alarm:
+                # echo 0 > wakealarm
+
+    This resembles the /proc/acpi/alarm file in that nothing happens when the
+    alarm triggers ...  except possibly waking the system from sleep.  It's also
+    like that in a nasty way: not much can be done to prevent one task from
+    clobbering another task's alarm settings.
+
+    It differs from that file in that there's no in-kernel date parser.
+
+    Note that a few RTCs ignore rtc_wkalrm.enabled when setting alarms, or aren't
+    set up correctly, so they won't yet behave with this attribute.
+
 
 -------------------- 8< ---------------- 8< -----------------------------
 

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

Re: Document sysfs interface to RTC system wakeup

[Jonathan Corbet]

On Wed, 26 Nov 2008 17:15:24 +0100
Pavel Machek <pavel@suse.cz> wrote:

> +How to use /sys/class/rtc/rtcX/wakealarm
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +This file takes the seconds since epoch to enable a wake event at the
> +specified time.

More documentation is cool.  In this case, though, I'm left with an
immediate question: *why* am I interested in wakealarm?  Reading
through, I eventually figure out that it can maybe be used to get a
system to start up at some point in the future, maybe.  It seems like
that should be said at the outset.

Also; why do I want to migrate from /proc/acpi/alarm?

jon

Re: Document sysfs interface to RTC system wakeup

[Pavel Machek]

> On Wed, 26 Nov 2008 17:15:24 +0100
> Pavel Machek <pavel@suse.cz> wrote:
> 
> > +How to use /sys/class/rtc/rtcX/wakealarm
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +This file takes the seconds since epoch to enable a wake event at the
> > +specified time.
> 
> More documentation is cool.  In this case, though, I'm left with an
> immediate question: *why* am I interested in wakealarm?  Reading
> through, I eventually figure out that it can maybe be used to get a
> system to start up at some point in the future, maybe.  It seems like
> that should be said at the outset.

You can suspend/power down your machine, and it will power itself up
at appropriate time.

> Also; why do I want to migrate from /proc/acpi/alarm?

Because /proc/acpi/alarm is ugly hack that is going to go away :-).
									Pavel
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

Re: Document sysfs interface to RTC system wakeup

[Michael Kerrisk]

On Wed, Nov 26, 2008 at 12:00 PM, Pavel Machek <pavel@suse.cz> wrote:
>> On Wed, 26 Nov 2008 17:15:24 +0100
>> Pavel Machek <pavel@suse.cz> wrote:
>>
>> > +How to use /sys/class/rtc/rtcX/wakealarm
>> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> > +This file takes the seconds since epoch to enable a wake event at the
>> > +specified time.
>>
>> More documentation is cool.  In this case, though, I'm left with an
>> immediate question: *why* am I interested in wakealarm?  Reading
>> through, I eventually figure out that it can maybe be used to get a
>> system to start up at some point in the future, maybe.  It seems like
>> that should be said at the outset.
>
> You can suspend/power down your machine, and it will power itself up
> at appropriate time.
>
>> Also; why do I want to migrate from /proc/acpi/alarm?
>
> Because /proc/acpi/alarm is ugly hack that is going to go away :-).

And these are the statements that (in slightly more polished terms)
should be in your doc ;-), in order to address Jonathan's quite
reasonable questions.
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html

Re: Document sysfs interface to RTC system wakeup

[Pavel Machek]

On Fri 2008-11-28 16:40:35, Michael Kerrisk wrote:
> On Wed, Nov 26, 2008 at 12:00 PM, Pavel Machek <pavel@suse.cz> wrote:
> >> On Wed, 26 Nov 2008 17:15:24 +0100
> >> Pavel Machek <pavel@suse.cz> wrote:
> >>
> >> > +How to use /sys/class/rtc/rtcX/wakealarm
> >> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >> > +This file takes the seconds since epoch to enable a wake event at the
> >> > +specified time.
> >>
> >> More documentation is cool.  In this case, though, I'm left with an
> >> immediate question: *why* am I interested in wakealarm?  Reading
> >> through, I eventually figure out that it can maybe be used to get a
> >> system to start up at some point in the future, maybe.  It seems like
> >> that should be said at the outset.
> >
> > You can suspend/power down your machine, and it will power itself up
> > at appropriate time.
> >
> >> Also; why do I want to migrate from /proc/acpi/alarm?
> >
> > Because /proc/acpi/alarm is ugly hack that is going to go away :-).
> 
> And these are the statements that (in slightly more polished terms)
> should be in your doc ;-), in order to address Jonathan's quite
> reasonable questions.

I'm bad at polishing, but I'll add short explanation.

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

Re: Document sysfs interface to RTC system wakeup

[Alan Jenkins]

On 11/26/08, Pavel Machek <pavel@suse.cz> wrote:
> diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
> index 8deffcd..ac843ab 100644
> --- a/Documentation/rtc.txt
> +++ b/Documentation/rtc.txt
> @@ -187,6 +187,88 @@ driver returns ENOIOCTLCMD.  Some common
>
>  If all else fails, check out the rtc-test.c driver!
>
> +	    Even newer /sys interface
> +	    ~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +tino.keitel@gmx.de
> +

It's unclear what the purpose of this email address is :).

<snip>

> +cd /proc/acpi
> +echo EXP0 > wakeup
> +echo PCI1 > wakeup
> +echo USB0 > wakeup
> +echo USB1 > wakeup
> +echo USB2 > wakeup
> +echo USB7 > wakeup
> +echo HDEF > wakeup

Can you add a comment before this block, something like

# Toggle example wakeup devices
# "cat wakeup" will show the list of devices on your specific system,
and their current state

There are two points here

1) This part of the example depends on the exact system.  AFAIK the
BIOS is free to call the devices whatever it likes.

2) These commands *toggle* the enabled state of the relevant wakeup
device.  If you naively wrote a script based on this example, it
_might_ work once.  It would probably fail the second time, because it
would disable all the devices again.


For added fun, my desktop systems, has a group of wakeup devices which
toggle as a single unit.  There are six devices in the group,
PEX[0-5].  If you do

for i in 0 1 2 3 4 5; do echo PEX$i > wakeup; done

the group toggles 6 times -so the state at the end will be the same as
the start!  Hopefully readers will read the values back after applying
them anyway, so they will notice if anything similarly strange
happens.

Alan

Re: Document sysfs interface to RTC system wakeup

[Pavel Machek]

Hi!

> > +tino.keitel@gmx.de
> > +
> 
> It's unclear what the purpose of this email address is :).
> 
> <snip>
> 
> > +cd /proc/acpi
> > +echo EXP0 > wakeup
> > +echo PCI1 > wakeup
> > +echo USB0 > wakeup
> > +echo USB1 > wakeup
> > +echo USB2 > wakeup
> > +echo USB7 > wakeup
> > +echo HDEF > wakeup
> 
> Can you add a comment before this block, something like
> 
> # Toggle example wakeup devices
> # "cat wakeup" will show the list of devices on your specific system,
> and their current state

Thanks for the comments. I'd apply them and spin new version.
								Pavel
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

Re: Document sysfs interface to RTC system wakeup

[Michael Kerrisk]

Pavel,

Some comments and suggestions below.

On Wed, Nov 26, 2008 at 11:15 AM, Pavel Machek <pavel@suse.cz> wrote:
> diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
> index 8deffcd..ac843ab 100644
> --- a/Documentation/rtc.txt
> +++ b/Documentation/rtc.txt
> @@ -187,6 +187,88 @@ driver returns ENOIOCTLCMD.  Some common
>
>  If all else fails, check out the rtc-test.c driver!
>
> +           Even newer /sys interface
> +           ~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +tino.keitel@gmx.de
> +
> +How to use /sys/class/rtc/rtcX/wakealarm
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +This file takes the seconds since epoch to enable a wake event at the
> +specified time.

Better:

This file can be used to view / set the time of a wakeup event.  The
contents of the file are time measured in seconds since the Epoch
(00:00:00h, 1 Jan 1970, UTC).

> +
> +If a '0' is written, the alarm is disabled.

Now -- you started off talking about a "wake event" and now you
switched to talking about an "alarm" -- which is it?  Be consistent.

> +
> +If the alarm was already enabled, a new alarm can only be set after the
> +old alarm is disabled.
> +
> +
> +Migration from /proc/acpi/alarm
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +Users of /proc/acpi/alarm have to change their code to supply the
> +seconds since epoch instead of a date string.

As Jonathan said -- if I'm using  /proc/acpi/alarm, why do I care?
What advantages does the new interface provide for me that would
motivate me to change?

> +For shell scripts, this can be done using the date command, e.g. like
> +this:
> +
> +date -d tomorrow "+%s"
> +
> +This returns the seconds since epoch of the current time on the

s/epoch/the Epoch/

> +following day.
> +
> +Please note that you have to disable the old alarm first, if you want
> +to set a new alarm. Otherwise, you get an error. Example:
> +
> +echo 12345 > /sys/class/rtc/rtc0/wakealarm
> +echo 0 > /sys/class/rtc/rtc0/wakealarm
> +echo 23456 > /sys/class/rtc/rtc0/wakealarm

Here, it might be useful to show an example of an error.  E.g., if one
does these commands instead, show the error from the second command:

echo 12345 > /sys/class/rtc/rtc0/wakealarm
echo 23456 > /sys/class/rtc/rtc0/wakealarm
echo 0 > /sys/class/rtc/rtc0/wakealarm
echo 34567 > /sys/class/rtc/rtc0/wakealarm

> +cd /proc/acpi
> +echo EXP0 > wakeup
> +echo PCI1 > wakeup
> +echo USB0 > wakeup
> +echo USB1 > wakeup
> +echo USB2 > wakeup
> +echo USB7 > wakeup
> +echo HDEF > wakeup
> +cd /sys/class/rtc/rtc0
> +echo $(( $(cat since_epoch) + 20 )) > wakealarm
> +
> +    [PATCH] RTC gets sysfs wakealarm attribute
> +
> +    This adds a new "wakealarm" sysfs attribute to RTC class devices which support
> +    alarm operations and are wakeup-capable:
> +
> +     - It reads as either empty, or the scheduled alarm time as seconds
> +       since the POSIX epoch.  (That time may already have passed, since

s/epoch/Epoch/
(and other instances below)

> +       nothing currently enforces one-shot alarm semantics.)
> +
> +     - It can be written with an alarm time in the future, again seconds
> +       since the POSIX epoch, which enables the alarm.
> +
> +     - It can be written with an alarm time not in the future (such as 0,
> +       the start of the POSIX epoch) to disable the alarm.
> +
> +    Usage examples (some need GNU date) after "cd /sys/class/rtc/rtcN":
> +
> +        alarm after 10 minutes:
> +        # echo $(( $(cat since_epoch) + 10 * 60 )) > wakealarm
> +        alarm tuesday evening 10pm:
> +        # date -d '10pm tuesday' "+%s" > wakealarm
> +        disable alarm:
> +                # echo 0 > wakealarm
> +
> +    This resembles the /proc/acpi/alarm file in that nothing happens when the
> +    alarm triggers ...  except possibly waking the system from sleep.  It's also
> +    like that in a nasty way: not much can be done to prevent one task from
> +    clobbering another task's alarm settings.
> +
> +    It differs from that file in that there's no in-kernel date parser.
> +
> +    Note that a few RTCs ignore rtc_wkalrm.enabled when setting alarms, or aren't
> +    set up correctly, so they won't yet behave with this attribute.

The last sentence is garbled -- bad grammar/missing words -- somewhere
near "or aren't".

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html

Re: Document sysfs interface to RTC system wakeup

[Pavel Machek]

Add wakealarm description to rtc.txt, now including comments from
Michael and others.

Signed-off-by: Pavel Machek <pavel@suse.cz>

--- clean-cg/Documentation/rtc.txt	2008-02-07 10:28:47.000000000 +0100
+++ linux/Documentation/rtc.txt	2008-12-09 13:51:06.000000000 +0100
@@ -187,6 +187,64 @@
 
 If all else fails, check out the rtc-test.c driver!
 
+	    Even newer /sys interface
+	    ~~~~~~~~~~~~~~~~~~~~~~~~~
+	    (thanks to tino.keitel@gmx.de)
+
+How to use /sys/class/rtc/rtcX/wakealarm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This file can be used to view / set the time of an alarm (wakeup event).  The
+contents of the file are time measured in seconds since the Epoch
+(00:00:00h, 1 Jan 1970, UTC).
+
+     - It reads as either empty, or the scheduled alarm time as seconds
+       since the POSIX Epoch.  (That time may already have passed, since
+       nothing currently enforces one-shot alarm semantics.)
+
+     - It can be written with an alarm time in the future, again seconds
+       since the POSIX Epoch, which enables the alarm.
+
+     - It can be written with an alarm time not in the future (such as 0,
+       the start of the POSIX epoch) to disable the alarm.
+
+If the alarm was already enabled, a new alarm can only be set after the
+old alarm is disabled.
+
+    This resembles the /proc/acpi/alarm file in that nothing happens when the
+    alarm triggers ...  except possibly waking the system from sleep.  It's also
+    like that in a nasty way: not much can be done to prevent one task from
+    clobbering another task's alarm settings.
+
+
+
+Migration from /proc/acpi/alarm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Users of /proc/acpi/alarm have to change their code to supply the
+seconds since the Epoch instead of a date string. (The date string in
+/proc is quite and ugly hack, and it will be removed one day, with
+rest of /proc/acpi).  
+
+For shell scripts, this can be done using the date command, e.g. like
+this:
+
+date -d tomorrow "+%s"
+
+This returns the seconds since the Epoch of the current time on the
+following day.
+
+Please note that you have to disable the old alarm first, if you want
+to set a new alarm. Otherwise, you get an error. Example:
+
+# Toggle example wakeup devices. Be sure to do 'cat wakeup' to check
+# the status when you are done.
+cd /proc/acpi
+echo EXP0 > wakeup
+echo PCI1 > wakeup
+echo HDEF > wakeup
+cd /sys/class/rtc/rtc0
+echo 0 > wakealarm
+echo $(( $(cat since_epoch) + 20 )) > wakealarm
+
 
 -------------------- 8< ---------------- 8< -----------------------------
 

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