Document sysfs interface to RTC system wakeup
Documentation/rtc.txt +82 -0
@@ -187,6 +187,88 @@ driver returns ENOIOCTLCMD. Some common If all else fails, check out the rtc-test.c driver! + Even newer /sys interface + ~~~~~~~~~~~~~~~~~~~~~~~~~ + [email protected] + +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< -----------------------------
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Jonathan Corbet
maintainerDocumentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 198
Quoted 4 lines · On Wed, 26 Nov 2008 17:15:24 +0100 Pavel Machek <[email protected]> wrote:
Documentation/rtc.txt +4
-0+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
Quoted 13 lines
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 198
Quoted 4 lines · On Wed, 26 Nov 2008 17:15:24 +0100 Pavel Machek <[email protected]> wrote:
Documentation/rtc.txt +4
-0+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.
Quoted 1 line
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
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Quoted 14 lines · Pavel Machek
Quoted 13 lines
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 198
Quoted 4 lines · On Wed, 26 Nov 2008 17:15:24 +0100 Pavel Machek <[email protected]> wrote:
Documentation/rtc.txt +4
-0+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.
Quoted 6 lines
You can suspend/power down your machine, and it will power itself up at appropriate time.
Quoted 1 line
Also; why do I want to migrate from
/proc/acpi/alarm?Because
/proc/acpi/alarmis 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.
Signature · 5 lines
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
Quoted 18 lines · Michael Kerrisk
Quoted 17 lines · Pavel Machek
Quoted 13 lines
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 198
Quoted 4 lines · On Wed, 26 Nov 2008 17:15:24 +0100 Pavel Machek <[email protected]> wrote:
Documentation/rtc.txt +4
-0+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.
Quoted 7 lines
Quoted 3 lines
Quoted 1 line
Also; why do I want to migrate from
/proc/acpi/alarm?Because
/proc/acpi/alarmis 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.
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 194
Quoted 13 lines · Pavel Machek
Documentation/rtc.txt +5
-0@@ -187,6 +187,88 @@ driver returns ENOIOCTLCMD. Some common If all else fails, check out the rtc-test.c driver! + Even newer /sys interface + ~~~~~~~~~~~~~~~~~~~~~~~~~ + [email protected] +
It's unclear what the purpose of this email address is :).
<snip>
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 234
Quoted 8 lines
Documentation/rtc.txt +8
-0+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
Hi!
Quoted 18 lines
Review
Quoted 2 lines
(quoted diff) +2
-0[email protected] +It's unclear what the purpose of this email address is :).
<snip>
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 234
Quoted 8 lines
Documentation/rtc.txt +8
-0+cd /proc/acpi +echo EXP0 > wakeup +echo PCI1 > wakeup +echo USB0 > wakeup +echo USB1 > wakeup +echo USB2 > wakeup +echo USB7 > wakeup +echo HDEF > wakeupCan you add a comment before this block, something like
Quoted 3 lines
# 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
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Pavel,
Some comments and suggestions below.
Quoted 7 lines · Pavel Machek
Documentation/rtc.txt +0
-0@@ -187,6 +187,88 @@ driver returns ENOIOCTLCMD. Some common If all else fails, check out the rtc-test.c driver!
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 198
Quoted 10 lines
Documentation/rtc.txt +9
-0+ Even newer /sys interface + ~~~~~~~~~~~~~~~~~~~~~~~~~ + [email protected] + +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).
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 200
Quoted 2 lines
Documentation/rtc.txt +2
-0+ +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.
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 209
Quoted 9 lines
Documentation/rtc.txt +9
-0+ +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?
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 216
Quoted 6 lines
Documentation/rtc.txt +6
-0+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/
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 224
Quoted 8 lines
Documentation/rtc.txt +8
-0+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
Quoted 8 lines
Documentation/rtc.txt +8
-0+cd /proc/acpi +echo EXP0 > wakeup +echo PCI1 > wakeup +echo USB0 > wakeup +echo USB1 > wakeup +echo USB2 > wakeup +echo USB7 > wakeup +echo HDEF > wakeup
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 244
Quoted 10 lines
Documentation/rtc.txt +10
-0+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)
Quoted 16 lines
Documentation/rtc.txt +16
-0+ 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
Documentation/rtc.txt driver returns ENOIOCTLCMD. Some common · line 270
Quoted 10 lines
Documentation/rtc.txt +10
-0+ + 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
Signature · 5 lines
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
Add wakealarm description to rtc.txt, now including comments from Michael and others.
Documentation/rtc.txt +58 -0
@@ -187,6 +187,64 @@ If all else fails, check out the rtc-test.c driver! + Even newer /sys interface + ~~~~~~~~~~~~~~~~~~~~~~~~~ + (thanks to [email protected]) + +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< -----------------------------
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html