Description

This package CYGPKG_DEVICES_WALLCLOCK_INTERSIL_ISL1208 provides a device driver for the wallclock device in the Intersil ISL1208 Real-Time Clock chips. These combine a real-time clock, alarm functionality, a selectable frequency output, and two bytes of non-volatile memory 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.

The driver does not provide direct access to any of the other functionality provided by the chip. Instead if an application wishes to access the alarms or the non-volatile bytes then it can do so itself, via the generic I²C API. However any such application code does need to synchronize with the wallclock driver to prevent concurrent accesses to the device. The driver exports a mutex lock to allow for this:

#include <cyg/io/wallclock/isl1208.h>

extern cyg_drv_mutex_t cyg_isl1208_lock;

The mutex should be locked via cyg_drv_mutex_lock to prevent the wallclock driver from accessing the chip, and then unlocked via cyg_drv_mutex_unlock when the driver can safely access the chip again.

The wallclock package is initialized by a static constructor with a priority immediately after CYG_INIT_DEV_WALLCLOCK. Applications should not call any wallclock-related functions before that constructor has run.

Porting

The ISL1208 is accessed via an I²C serial bus, and the driver assumes the presence of the generic I²C support package CYGPKG_IO_I2C and a suitable hardware driver. In addition it requires that some other package, typically the platform HAL, exports a cyg_i2c_device structure cyg_i2c_wallclock_isl1208. The ISL1208 device driver package CYGPKG_DEVICES_WALLCLOCK_INTERSIL_ISL1208 can then be included in the CDL target entry so that it gets loaded automatically whenever eCos is configured for that target.