A neat feature with most PCs is the ability to program the Real Time Clock (RTC) to trigger an alarm event at some time in the future and wake the PC up. Some projects such as MythTV use this to wake up a PC to record a TV programme. I've used it to make my laptop wake me up when I've forgotten my alarm clock when I've been travelling.
The method of programming the alarm is relatively straight forward - with the older kernels one would write the date and time to wake up into /proc/acpi/alarm and with newer kernels since 2.6.22 use /sys/class/rtc/rtc0/wakealarm. The API documented fairly well at the ACPI wakeup wiki page at mythtv.org.
The ACPI wake alarm is also used by the Ubuntu Kernel Team suspend/resume tests; these tests suspend a laptop for a specific amount of time and re-awaken the machine for programmatic suspend/resume soak testing. Unfortately, we are finding that some machines have a flakey or broken ACPI implementation for the wake alarm - for example, some machines need the alarm setting to zero or being set twice to work.
One can test quite easily of the ACPI wake alarm works - simply program it to trigger in some short time in the future and check to see if the alarm_IRQ field in /proc/driver/rtc is set to "yes". The second test is to wait until the alarm has triggered and check if the same alarm_IRQ field is now set to "no".
I've hacked up a quick-n-dirty test script to check this out and it can be found it my test script git repository here. Run this test and see - if your machine fails then it may be a good idea to check out the MythTV ACPI wake alarm troubleshooting section here. It may be a BIOS bug that's fixed with a new BIOS upgrade. Failing that, one should file a bug with upstream.
So far, I've see this problem on Lenovo 0768 series laptops, but I expect to see it on other machines too.
UPDATE: It appears the issue is more to do with the hwclock not being in UTC. One can sleep correctly using:
echo 0 > /sys/class/rtc/rtc0/wakealarm
echo $SECS > /sys/class/rtc/rtc0/wakealarm
Note that I've written to wakealarm twice, the first time writes a zero which apparently helps some buggy BIOSs.
Or the heavy handed way (which will give Windows a headache):
hwclock --utc --systohc