Module ffi.rtc
Module for interfacing with the RTC (real time clock).
This module provides the ability to schedule wakeups through RTC.
See http://man7.org/linux/man-pages/man4/rtc.4.html for technical details.
Things to keep in mind: the RTC tracks time in UTC. So do we, as the API only passes around what amounts to time_t values, i.e., a Posix epoch, which is intrinsically UTC.
Functions
| RTC:secondsFromNowToEpoch (seconds_from_now) | Adds seconds to epoch. |
| RTC:toggleAlarmInterrupt (enabled) | Enable/Disable the alarm interrupt. |
| RTC:setWakeupAlarm (Epoch) | Set wakeup alarm. |
| RTC:unsetWakeupAlarm () | Unset wakeup alarm. |
| RTC:getWakeupAlarm () | Get a copy of the wakealarm we set (if any). |
| RTC:getWakeupAlarmEpoch () | Return the timestamp of the alarm we set (if any). |
| RTC:getWakeupAlarmSys () | Get RTC wakealarm from system. |
| RTC:readHardwareClock () | Get RTC clock from system. |
| RTC:validateWakeupAlarmByProximity (task_alarm, proximity) | Checks if the alarm we set matches the system alarm as well as the current time. |
| RTC:isWakeupAlarmScheduled () | Checks if we scheduled a wakeup alarm. |
| RTC:HCToSys () | Sets the system clock based on the hardware clock. |
Functions
- RTC:secondsFromNowToEpoch (seconds_from_now)
-
Adds seconds to epoch.
Parameters:
- seconds_from_now integer Number of seconds.
Returns:
-
int
(cdata) Epoch (UTC).
- RTC:toggleAlarmInterrupt (enabled)
-
Enable/Disable the alarm interrupt.
The use of RTCWKALMSET allows us to bypass the need for RTCAIE* calls,
thanks to the enabled field in the rtcwkalrm struct.
Busybox rtcwake still does an RTCAIEOFF when resuming from an alarm wakeup,
as does Nickel when powering off.
In this scenario, the modern util-linux rtcwake, which never uses legacy RTCALMSET calls,
instead uses RTCWKALMSET filled from RTCWKALM_RD but with enabled set to 0.
Parameters:
- enabled
Returns:
- bool Success.
- re Error code (if any).
- err Error string (if any).
- RTC:setWakeupAlarm (Epoch)
-
Set wakeup alarm.
If you want to set the alarm to a certain amount of time from now, you can process your value with secondsFromNowToEpoch.
Parameters:
- Epoch integer (UTC).
Returns:
- bool Success.
- re Error code (if any).
- err Error string (if any).
- RTC:unsetWakeupAlarm ()
- Unset wakeup alarm.
- RTC:getWakeupAlarm ()
-
Get a copy of the wakealarm we set (if any).
This value is compared with getWakeupAlarmSys in validateWakeupAlarmByProximity.
Returns:
-
tm
(time struct)
- RTC:getWakeupAlarmEpoch ()
-
Return the timestamp of the alarm we set (if any).
Returns:
-
Epoch (UTC)
- RTC:getWakeupAlarmSys ()
-
Get RTC wakealarm from system.
Returns:
-
tm
(time struct)
- RTC:readHardwareClock ()
-
Get RTC clock from system.
Returns:
-
tm
(time struct)
- RTC:validateWakeupAlarmByProximity (task_alarm, proximity)
-
Checks if the alarm we set matches the system alarm as well as the current time.
Parameters:
- task_alarm
- proximity In principle alarm time and current time should match within a second, but let's be absurdly generous and assume anything within 30 is a match. In practice, Kobo's suspend() schedules checkunexpectedwakeup 15s after the actual wakeup, so we need to account for at least that much ;).
- RTC:isWakeupAlarmScheduled ()
-
Checks if we scheduled a wakeup alarm.
Returns:
-
bool
- RTC:HCToSys ()
-
Sets the system clock based on the hardware clock.
(e.g., hwclock --hctosys). Heavily inspired by busybox's hwclock applet.