ST M48T35A Wallclock Device Driver

Description

This package CYGPKG_DEVS_WALLCLOCK_ST_M48T35A provides a device driver for the wallclock device in the ST M48T35AY and M48T35AV timekeeper SRAM chips. These combine 32K 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.

M48T35A 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_m48t35a.h>

externC cyg_int32   cyg_wallclock_m48t35a_get_calibration(void);
externC void        cyg_wallclock_m48t35a_set_calibration(cyg_int32);
    

Porting

For most platforms adding support for the m48t35a wallclock device requires just two steps. The package must be added to the appropriate CDL target entry so that it gets loaded automatically 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_M48T35A_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. 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.

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_M48T35A_STRIDE and macros HAL_WALLCLOCK_M48T35A_READ_UINT8 and HAL_WALLCLOCK_M48T35A_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.

Some variants of the M48T35A do not support the century bit. If the platform defines HAL_WALLCLOCK_M48T35A_NO_CENTURY_BIT then the century bit will be ignred and the driver will instead use a heuristic for determining the century: if the year register < 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.