Description

This package CYGPKG_DEVS_WALLCLOCK_ST_M48Txxx provides a device driver for the wallclock device in the ST M48T family of TimeKeeper SRAM chips (e.g. the M48T35AV part). These combine an amount of battery-backed SRAM and a real-time clock in a single package. The driver can also be used with any other chips that provide the same interface to the clock hardware.

The package will usually be loaded into the configuration automatically whenever selecting a target which contains a compatible chip. By default it will provide the standard eCos wallclock device, although another implementation such as software emulation may be selected if desired. The only other configuration options related to this package allow users to change the compiler flags. If the application does not actually use the wallclock device, directly or indirectly, then the code should get removed automatically at link-time to ensure that the application does not suffer any unnecessary overheads.

Functionality

This wallclock device driver package implements the standard functionality required by the generic wallclock support CYGPKG_IO_WALLCLOCK. The functionality is not normally accessed directly. Instead it is used by the C library time package to implement standard calls such as time and gmtime. The eCos C library also provides a non-standard function cyg_libc_time_settime for changing the current wallclock setting. In addition RedBoot provides a date command which interacts with the wallclock device.

M48T devices provide some support for a calibration value. If the application has some alternative way of getting a reliable time value, for example NTP over a TCP/IP network, then the wallclock can be made to tick slightly faster or slower. The calibration value is a small integer between -31 and +31. A positive value x adds 512x extra cycles every 125829120 actual cycles, speeding up the clock by approximately 10.7x seconds per month. Alternatively a negative value x subtracts 256x cycles, slowing down the clock by 5.35x seconds per month. The package provides two functions for examining and changing the current calibration value:

#include <cyg/io/wallclock_m48txxx.h>

externC cyg_int32   cyg_wallclock_m48t_get_calibration(void);
externC void        cyg_wallclock_m48t_set_calibration(cyg_int32);

Porting

For most platforms adding support for the M48T wallclock device requires just two steps. The package must be added to the appropriate CDL target entry so that it gets loaded automatically, and selects the relevant ST M48T family device, whenever configuring eCos for that target. Also the platform HAL should specify the location of the clock hardware in the address space, by defining the symbol HAL_WALLCLOCK_M48Txxx_BASE. The definition should go into cyg/hal/hal_io.h or more commonly into a platform-specific header cyg/hal/plf_io.h which gets included automatically by the former. The value should be the address of the control register of the clock device. The driver provides the CYGNUM_DEVS_WALLCLOCK_ST_M48Txxx_OFFSET_CLOCK value which is set to the appropriate offset value for the CYGHWR_DEVS_WALLCLOCK_ST_M48Txxx selected device. For example, given a battery-backed 32K TimeKeeper chip at 0x30000000, the clock hardware will occupy the last eight bytes at 0x30007ff8 and that is the value which should be used, and CYGNUM_DEVS_WALLCLOCK_ST_M48Txxx_OFFSET_CLOCK will have the value 0x7ff8.

The package provides some support for hardware where the clock is mapped into memory in strange ways. The platform HAL can define an additional symbol HAL_WALLCLOCK_M48Txxx_STRIDE and macros HAL_WALLCLOCK_M48Txxx_READ_UINT8 and HAL_WALLCLOCK_M48Txxx_WRITE_UINT8 to change the way in which the driver accesses the hardware. The source code should be consulted for further details of how these work.

If the selected ST M48T device implements the Century bit then the configurarion will define CYGINT_DEVS_WALLCLOCK_ST_M48Txxx_CENTURY_BIT as a non-zero value. The platform can override the CDL device based configuration by defining HAL_WALLCLOCK_M48Txxx_NO_CENTURY_BIT which can be used to notify the driver that a compatible device does not support the Century bit, or that the feature should be explicitly disabled.

If the Century bit is not supported the driver will instead use a heuristic for determining the century: if the year register is < 70 then this is treated as relative to 2000; otherwise it is treated as relative to 1900; this gives an effective range of Jan 1st 1970 to Dec 31st 2069.