Description

This package CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1302 provides a device driver for the wallclock device in the Dallas DS1302 Real-Time Clock chips. This combines a real-time clock and 31 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.

The package provides a number of additional functions that are specific to a DS1302:

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

externC unsigned char cyg_wallclock_ds1302_read_tcs_ds_rs(void);
externC void cyg_wallclock_ds1302_write_tcs_ds_rs(unsigned char val);
externC void cyg_wallclock_ds1302_read_ram(int offset,
                        unsigned char* buf, int len);
externC void cyg_wallclock_ds1302_write_ram(int offset,
                        unsigned char* buf, int len);

The _tcs_ds_rs functions allow applications to read and update the trickle charge register in the DS1302. The manufacturer's data sheet should be consulted for further information on this register.

The _ram functions allow applications to read and modify the contents of the 31 bytes of battery-backed RAM. The offset specifies the starting address within the RAM and should be between 0 and 31. The buffer provides the destination or source of the data, and the length gives the number of bytes transferred. Wrap-around is not supported so the sum of the offset and length should also be less than 31. The package's ds1302.c testcase provides example code.

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 nor any of the DS1302-specific functions before that constructor has run.

Porting

The DS1302 is accessed via a 3-wire bus. At the time of writing there is no generic 3-wire support package within eCos, so instead the wallclock driver expects to bit-bang some GPIO lines. Typically the platform HAL provides appropriate hardware-specific macros for this, via the header file cyg/hal/plf_io.h. The required macros are:

HAL_DS1302_CE(_setting_);
HAL_DS1302_SCLK(_setting_);
HAL_DS1302_OUT(_setting_);
HAL_DS1302_IN(_setting_);
HAL_DS1302_SELECT_OUT(_setting_);

The argument to the first three macros will always be 0 or 1 and corresponds to the desired state of the chip-enable, clock, or I/O line. For example, at the start of a transfer the wallclock driver will invoke:

    …
    HAL_DS1302_CE(1);
    …

Asserting the CE line should activate the DS1302 chip. The HAL_DS1302_IN macro is used to sample the state of the I/O line and should set its argument to 0 or 1. The HAL_DS1302_SELECT_OUT macro is used to switch the I/O line between output (1) or input (0).

Platform HALs may provide two additional macros:

HAL_DS1302_DATA
HAL_DS1302_INIT();

HAL_DS1302_DATA can be used to define one or more static variables needed by the other macros, for example to hold a shadow copy of the GPIO output register. If defined, HAL_DS1302_INIT will be invoked during driver initialization and typically sets up the GPIO lines such that the CE and SCLK lines are outputs.

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