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

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     ds1307.sgml                                                 -->
<!--                                                                 -->
<!--     Documentation for the ds1307 wallclock driver               -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
<!-- =============================================================== -->
<!-- Copyright (C) 2006 Free Software Foundation, Inc.               -->
<!-- Copyright (C) 2006 eCosCentric Limited                          -->
<!-- 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, nickg                                       -->
<!-- Contact(s):  bartv, nickg                                       -->
<!-- Date:        2006/09/01                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

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

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

  <refsect1 id="devs-wallclock-dallas-ds1390-description"><title>Description</title>
    <para>
This package
<varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1390</varname> provides a
device driver for the wallclock device in the Dallas DS1390 Serial
Real-Time Clock chips. 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-ds1390-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>
  </refsect1>

  <refsect1 id="devs-wallclock-dallas-ds1390-porting"><title>Porting</title>
    <para>
The DS1390 driver uses the SPI driver API defined by the 
package <varname>CYGPKG_IO_SPI</varname>. A suitable SPI device driver
must be available for the target. The platform HAL must
provide a <structname>cyg_spi_device</structname> structure
<varname>cyg_spi_wallclock_ds1390</varname>. The platform HAL should
initialize this structure and any associated SPI driver specific
struture with the correct phase, polarity and chip select parameters
for this device.
    </para>
    <para>
In addition the DS1390 device driver package
<varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1390</varname> should be
included in the CDL target entry so that it gets loaded automatically
whenever eCos is configured for that target.
    </para>
  </refsect1>

  <refsect1 id="devs-wallclock-dallas-ds1390-extras"><title>Extra API Calls</title>

<para>
In addition to the standard wallclock API calls, this driver exports a
number of additional functions to permit direct access to additional
features of the device. A header,
<filename>cyg/io/wallclock/ds1390.h</filename> is available to define
this API.
</para>

<variablelist>

<varlistentry>
<term><literal>cyg_uint8     cyg_ds1390_read_reg( int addr )</literal></term>
<listitem>
<para>
Read and return a single 8-bit register from the DS1390,
<parameter>addr</parameter> should be in the range 0x00 to 0x0F.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>void          cyg_ds1390_write_reg( int addr, int val )</literal></term>
<listitem>
<para>
Write a single 8-bit register to the DS1390,
<parameter>addr</parameter> should be in the range 0x00 to 0x0F and
<parameter>val</parameter> in the range 0x00 to 0xFF.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>void          cyg_ds1390_set_control( cyg_uint8 val )</literal></term>
<listitem>
<para>
Write the DS1390 control register with the content of
<parameter>val</parameter>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>cyg_uint8     cyg_ds1390_get_control( void )</literal></term>
<listitem>
<para>
Read and return the value of the DS1390 control register.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>void          cyg_ds1390_set_status( cyg_uint8 val )</literal></term>
<listitem>
<para>
Write the DS1390 status register with the content of
<parameter>val</parameter>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>cyg_uint8     cyg_ds1390_get_status( void )</literal></term>
<listitem>
<para>
Read and return the value of the DS1390 control register.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>void          cyg_ds1390_set_charger( cyg_uint8 val )</literal></term>
<listitem>
<para>
Write the DS1390 trickle-charge register with the content of
<parameter>val</parameter>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>cyg_uint8     cyg_ds1390_get_charger( void )</literal></term>
<listitem>
<para>
Read and return the value of the DS1390 trickle-charge register.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>int           cyg_wallclock_set_alarm( cyg_uint32 secs )</literal></term>
<listitem>
<para>
Set the DS1390 alarm to trigger when the wallclock time matches the
value of <parameter>secs</parameter>. The DS1390 alarm will match only
up to days of the month, so the alarm cannot be set more than one
month in the future. This function only initializes the DS1390 to
generate the alarm interrupt; it is the responsibility of the caller
to attach an ISR to the appropriate vector and unmask it in the
interrupt controller.
</para>
</listitem>
</varlistentry>

</variablelist>

  </refsect1>

</refentry>

</part>
