Dallas DS1307 Wallclock Device Driver

Description

This package CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1307 provides a device driver for the wallclock device in the Dallas DS1307 Serial Real-Time Clock chips. This combines a real-time clock and 56 bytes of battery-backed RAM 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.

Porting

DS1307 platform support can be implemented in one of two ways. The preferred approach involves the generic I2C API, as defined by the package CYGPKG_IO_I2C. The platform HAL can just provide a cyg_i2c_device structure cyg_i2c_wallclock_ds1307 and implement the CDL interface CYGINT_DEVICES_WALLCLOCK_DALLAS_DS1307_I2C. The DS1307 driver will now use I2C rx and tx operations to interact with the chip.

Alternatively the DS1307 driver can use macros or functions provided by another package to access the chip. This is intended primarily for older platforms that predate the CYGPKG_IO_I2C package. The other package should export a header file containing macros DS_GET and DS_PUT that transfer the eight bytes corresponding to the chip's clock registers. It should also export the name of this header via a #define CYGDAT_DEVS_WALLCLOCK_DS1307_INL in the global configuration header pkgconf/system.h. For full details see the source code.

In addition the DS1307 device driver package CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1307 should be included in the CDL target entry so that it gets loaded automatically whenever eCos is configured for that target.