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

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     ds1302.sgml                                                 -->
<!--                                                                 -->
<!--     Documentation for the ds1302 wallclock driver               -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
<!-- =============================================================== -->
<!-- Copyright (C) 2007, 2009 eCosCentric Limited                    -->
<!-- Copyright (C) 2007 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:        2007/11/28                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

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

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

  <refsect1 id="devs-wallclock-dallas-ds1302-description"><title>Description</title>
    <para>
This package
<varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1302</varname> 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.
    </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-ds1302-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 DS1302:
    </para>
    <programlisting width=72>
#include &lt;cyg/io/wallclock/ds1302.h&gt;

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);
    </programlisting>
    <para>
The <function>_tcs_ds_rs</function> 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.
    </para>
    <para>
The <function>_ram</function> 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 <filename>ds1302.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 DS1302-specific functions before that constructor has run.
    </para>
  </refsect1>

  <refsect1 id="devs-wallclock-dallas-ds1302-porting"><title>Porting</title>
    <para>
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 <filename
class="headerfile">cyg/hal/plf_io.h</filename>. The required macros
are:
    </para>
    <programlisting width=72>
HAL_DS1302_CE(_setting_);
HAL_DS1302_SCLK(_setting_);
HAL_DS1302_OUT(_setting_);
HAL_DS1302_IN(_setting_);
HAL_DS1302_SELECT_OUT(_setting_);
    </programlisting>
    <para>
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:
    </para>
    <programlisting width=72>
    &hellip;
    HAL_DS1302_CE(1);
    &hellip;
    </programlisting>
    <para>
Asserting the CE line should activate the DS1302 chip. The
<function>HAL_DS1302_IN</function> macro is used to sample the state
of the I/O line and should set its argument to 0 or 1. The
<function>HAL_DS1302_SELECT_OUT</function> macro is used to switch the
I/O line between output (1) or input (0).
    </para>
    <para>
Platform HALs may provide two additional macros:
    </para>
    <programlisting width=72>
HAL_DS1302_DATA
HAL_DS1302_INIT();
    </programlisting>
    <para>
<varname>HAL_DS1302_DATA</varname> 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,
<function>HAL_DS1302_INIT</function> will be invoked during driver
initialization and typically sets up the GPIO lines such that the CE
and SCLK lines are outputs.
    </para>
    <para>
In addition the DS1302 device driver package
<varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1302</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>
