The wallclock device provides real time stamps, as opposed to the eCos kernel timers which typically just count the number of clock ticks since the hardware was powered up. Depending on the target platform this device may involve interacting with a suitable on-chip device or an external clock chip, or it may be emulated by using the kernel timers.
The wallclock package operates using the standard UNIX epoch of midnight 1st January 1970. When times and dates are expressed in seconds, this is zero point for that count. However, many wallclock devices only have a two digit year field. In order to get a further 30 years duration from this field, and to avoid Y2K issues, many drivers actually store dates starting from the year 2000. It is therefore inavisable to try setting the wallclock to any date before 2000.
The Wallclock package contains a number of configuration options, most of which are set by either the wallclock device driver, or the platform HAL.
This interface is implemented by the wallclock device driver to signal to this package that a hardware wallclock device is present. If this interface is zero, then this package will implement the wallclock using the kernel timer.
This interface is implement by the wallclock device driver to signal to this package that the device can set the current value as well as get it and that the set value is preserved when the power is off.
The wallclock driver can be used in one of two modes. Set/get mode allows time to be kept during power off (assuming there's a battery backed clock). Init/get mode is slightly smaller and can be used when there is no battery backed clock - in this mode time 0 is the time of the board power up. The default value of this option depends on whether CYGINT_WALLCLOCK_SET_GET_MODE_SUPPORTED but may be changed by the user.
When this option is enabled, a wallclock device will be emulated using the kernel real-time clock. The default value depends on the value of CYGINT_WALLCLOCK_HW_IMPLEMENTATIONS but may be changed by the user.
This option disables the wallclock even if a hardware driver is present. The default value is depends on the value of CYGINT_WALLCLOCK_HW_IMPLEMENTATIONS.
If the underlying wallclock driver implements this interface, that means that it supports scratch space. This feature exists in some hardware to allow users to store some information in battery backed RAM, alongside the wallclock RTC's data. An API is provided by this package to access it.
Some wallclock hardware provides alarms which will generate an interrupt when a certain date/time is reached. This interface can be implemented by the underlying wallclock driver to indicate that such support can be used. An API is provided by this package to set and disable these alarms. Note these alarms are wholly separate from eCos kernel alarms.
This package contains a number of test programs. The wallclock and wallclock2 programs test basic functionality of the wallclock device. The alarm program tests the functionality of any alarms supported by the device. The subsec program tests the functionality and accuracy of device subsecond support if it is present.