<!-- DOCTYPE refentry  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     ds1306.sgml                                                 -->
<!--                                                                 -->
<!--     Documentation for the ds1306 wallclock driver               -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
<!-- =============================================================== -->
<!-- Copyright (C) 2008, 2009 eCosCentric Limited                    -->
<!-- Copyright (C) 2008 Free Software Foundation, Inc.               -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTEND####                                     -->
<!-- =============================================================== -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- Author(s):   bartv                                              -->
<!-- Date:        2008/05/08                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="devs-wallclock-dallas-ds1306-part"><title>Dallas DS1306 Wallclock Device Driver</title>

<refentry id="devs-wallclock-dallas-ds1306">
  <refmeta>
    <refentrytitle>Dallas DS1306 Wallclock Device Driver</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1306</varname></refname>
    <refpurpose>eCos Support for the Dallas DS1306 Real-Time Clock</refpurpose>
  </refnamediv>

  <refsect1 id="devs-wallclock-dallas-ds1306-description"><title>Description</title>
    <para>
This package
<varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1306</varname> 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.
    </para>
    <para>
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.
    </para>
  </refsect1>

  <refsect1 id="devs-wallclock-dallas-ds1306-functions"><title>Functionality</title>
    <para>
This wallclock device driver package implements the standard
functionality required by the generic wallclock support
<varname>CYGPKG_IO_WALLCLOCK</varname>. The functionality is not
normally accessed directly. Instead it is used by the C library time
package to implement standard calls such as <function>time</function>
and <function>gmtime</function>. The eCos C library also provides a
non-standard function <function>cyg_libc_time_settime</function> for
changing the current wallclock setting. In addition RedBoot provides
a <command>date</command> command which interacts with the wallclock
device.
    </para>
    <para>
The package provides a number of additional functions that are
specific to a DS1306:
    </para>
    <programlisting width=72>
#include &lt;cyg/io/wallclock/ds1306.h&gt;

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);
    </programlisting>
    <para>
The <function>read_regs</function> and <function>write_regs</function>
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.
    </para>
    <para>
The <function>_ram</function> 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
<filename>ds1306.c</filename> testcase provides example code.
    </para>
    <para>
The wallclock package is initialized by a static constructor with a
priority immediately after <varname>CYG_INIT_DEV_WALLCLOCK</varname>.
Applications should not call any wallclock-related functions nor any
of the DS1306-specific functions before that constructor has run.
    </para>
  </refsect1>

  <refsect1 id="devs-wallclock-dallas-ds1306-porting"><title>Porting</title>
    <para>
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
<varname>CYGHWR_WALLCLOCK_DALLAS_DS1306_SPI</varname> and provided an
SPI device instance <varname>cyg_spi_wallclock_ds1306</varname>. 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
<varname>CYGHWR_WALLCLOCK_DALLAS_DS1306_3WIRE</varname> and provide a
bit-bang function:
    </para>
    <programlisting width=72>
#include &lt;cyg/io/wallclock/ds1306.h&gt;

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

    switch(op) {
      case CYG_DS1306_BITBANG_INIT: &hellip;
      case CYG_DS1306_BITBANG_CE_HIGH: &hellip;
      case CYG_DS1306_BITBANG_CE_LOW: &hellip;
      case CYG_DS1306_BITBANG_SCLK_HIGH: &hellip;
      case CYG_DS1306_BITBANG_SCLK_LOW: &hellip;
      case CYG_DS1306_BITBANG_DATA_HIGH: &hellip;
      case CYG_DS1306_BITBANG_DATA_LOW: &hellip;
      case CYG_DS1306_BITBANG_DATA_READ: &hellip;
      case CYG_DS1306_BITBANG_INPUT: &hellip;
      case CYG_DS1306_BITBANG_OUTPUT: &hellip;
    }
    return result;
}
    </programlisting>
    <para>
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.
    </para>
    <para>
In addition the DS1306 device driver package
<varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1306</varname> should be
included in the CDL target entry so that it gets loaded automatically
whenever eCos is configured for that target.
    </para>
  </refsect1>

</refentry>

</part>
