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

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     isl12028.sgml                                               -->
<!--                                                                 -->
<!--     Documentation for the ISL12028 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/04/14                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="devs-wallclock-intersil-isl12028-part"><title>Intersil ISL12028 Wallclock Device Driver</title>

<refentry id="devs-wallclock-intersil-isl12028">
  <refmeta>
    <refentrytitle>Intersil ISL12028 Wallclock Device Driver</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><varname>CYGPKG_DEVICES_WALLCLOCK_INTERSIL_ISL12028</varname></refname>
    <refpurpose>eCos Support for the Intersil ISL12028 Real-Time Clock</refpurpose>
  </refnamediv>

  <refsect1 id="devs-wallclock-intersil-isl12028-description"><title>Description</title>
    <para>
This package
<varname>CYGPKG_DEVICES_WALLCLOCK_INTERSIL_ISL12028</varname> provides
a device driver for the wallclock device in the Intersil ISL12028
Real-Time Clock chips. These combine a real-time clock, alarm
functionality, and a bank of EEPROM 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-intersil-isl12028-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 driver does not provide direct access to any of the other
functionality provided by the chip. Instead if an application wishes
to access the alarms or the EEPROM memory then it can do so itself,
via the generic I2C API. However any such application code does need
to synchronize with the wallclock driver to prevent concurrent
accesses to the device. The driver exports a mutex lock to allow for
this:
    </para>
    <programlisting width=72>
#include &lt;cyg/io/wallclock/isl12028.h&gt;

extern cyg_drv_mutex_t cyg_isl12028_lock;
    </programlisting>
    <para>
The mutex should be locked via <function>cyg_drv_mutex_lock</function>
to prevent the wallclock driver from accessing the chip, and then
unlocked via <function>cyg_drv_mutex_unlock</function> when the driver
can safely access the chip again.
    </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 before
that constructor has run.
    </para>
  </refsect1>

  <refsect1 id="devs-wallclock-intersil-isl12028-porting"><title>Porting</title>
    <para>
The ISL12028 is accessed via an I2C serial bus, and the driver assumes
the presence of the generic I2C support package
<varname>CYGPKG_IO_I2C</varname> and a suitable hardware driver. In
addition it requires that some other package, typically the platform
HAL, exports a <structname>cyg_i2c_device</structname> structure
<varname>cyg_i2c_wallclock_isl12028</varname>. The ISL12028 device
driver package
<varname>CYGPKG_DEVICES_WALLCLOCK_INTERSIL_ISL12028</varname> can then
be included in the CDL target entry so that it gets loaded
automatically whenever eCos is configured for that target.
    </para>
  </refsect1>

</refentry>

</part>
