Description

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

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

externC void cyg_wallclock_ds1306_read_regs(int offset,
                                  unsigned char* buf, int len);
externC void cyg_wallclock_ds1306_write_regs(int offset,
                                  const unsigned char* buf, int len);
externC void cyg_wallclock_ds1306_read_ram(int offset,
                                  unsigned char* buf, int len);
externC void cyg_wallclock_ds1306_write_ram(int offset,
                                  const unsigned char* buf, int len);

The read_regs and write_regs functions allow direct access to all of the wallclock-related registers including the alarms, the control register 0x0F, the status register 0x10, and the trickle charger register 0x11. The offset should be between 0x00 and 0x1F, specifying the first register that should be read or written. For full details of the DS1306 registers see the manufacturer's data sheet.

The _ram functions allow applications to read and modify the contents of the 96 bytes of battery-backed RAM. The offset specifies the starting address within the RAM and should be between 0x00 and 0x5F. The buffer provides the destination or source of the data, and the length gives the number of bytes transferred. The package's ds1306.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 DS1306-specific functions before that constructor has run.

Porting

The DS1306 can be either attached to an SPI bus or it can be accessed via a 3-wire interface. The driver supports both modes of operation, with a bit of support from the platform HAL. For SPI, the platform HAL should implement the CDL interface CYGHWR_WALLCLOCK_DALLAS_DS1306_SPI and provided an SPI device instance cyg_spi_wallclock_ds1306. The exact details of this device instantiation will depend on the SPI bus driver. For 3-wire the platform HAL should implement the CDL interface CYGHWR_WALLCLOCK_DALLAS_DS1306_3WIRE and provide a bit-bang function:

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

cyg_bool
hal_ds1306_bitbang(cyg_ds1306_bitbang_op op)
{
    cyg_bool result = 0;

    switch(op) {
      case CYG_DS1306_BITBANG_INIT: …
      case CYG_DS1306_BITBANG_CE_HIGH: …
      case CYG_DS1306_BITBANG_CE_LOW: …
      case CYG_DS1306_BITBANG_SCLK_HIGH: …
      case CYG_DS1306_BITBANG_SCLK_LOW: …
      case CYG_DS1306_BITBANG_DATA_HIGH: …
      case CYG_DS1306_BITBANG_DATA_LOW: …
      case CYG_DS1306_BITBANG_DATA_READ: …
      case CYG_DS1306_BITBANG_INPUT: …
      case CYG_DS1306_BITBANG_OUTPUT: …
    }
    return result;
}

The INIT operation should set the 3-wire bus to its default settings: all lines should be output low. The HIGH and LOW operations should set the specified line to the appropriate level. INPUT switches the data line from an output to an input, and OUTPUT switches it back to an output. READ should return the current state of the data line, and is the only operation for which the return value matters.

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