packages/devs/wallclock/dallas/ds1307/v2_0/doc/ds1307.sgml

   1 <!-- DOCTYPE refentry  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
   2
   3 <!-- {{{ Banner                         -->
   4
   5 <!-- =============================================================== -->
   6 <!--                                                                 -->
   7 <!--     ds1307.sgml                                                 -->
   8 <!--                                                                 -->
   9 <!--     Documentation for the ds1307 wallclock driver               -->
  10 <!--                                                                 -->
  11 <!-- =============================================================== -->
  12 <!-- ####COPYRIGHTBEGIN####                                          -->
  13 <!--                                                                 -->
  14 <!-- =============================================================== -->
  15 <!-- Copyright (C) 2004 eCosCentric Limited.                         -->
  16 <!-- This material may be distributed only subject to the terms      -->
  17 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  18 <!-- or later (the latest version is presently available at          -->
  19 <!-- http://www.opencontent.org/openpub/)                            -->
  20 <!-- Distribution of the work or derivative of the work in any       -->
  21 <!-- standard (paper) book form is prohibited unless prior           -->
  22 <!-- permission obtained from the copyright holder                   -->
  23 <!-- =============================================================== -->
  24 <!--                                                                 -->
  25 <!-- ####COPYRIGHTEND####                                            -->
  26 <!-- =============================================================== -->
  27 <!-- =============================================================== -->
  28 <!-- #####DESCRIPTIONBEGIN####                                       -->
  29 <!--                                                                 -->
  30 <!-- Author(s):   bartv                                              -->
  31 <!-- Contact(s):  bartv                                              -->
  32 <!-- Date:        2004/10/09                                         -->
  33 <!-- Version:     0.01                                               -->
  34 <!--                                                                 -->
  35 <!-- ####DESCRIPTIONEND####                                          -->
  36 <!-- =============================================================== -->
  37
  38 <!-- }}} -->
  39
  40 <part id="devs-wallclock-dallas-ds1307-part"><title>Dallas DS1307 Wallclock Device Driver</title>
  41
  42 <refentry id="devs-wallclock-dallas-ds1307">
  43   <refmeta>
  44     <refentrytitle>Dallas DS1307 Wallclock Device Driver</refentrytitle>
  45   </refmeta>
  46   <refnamediv>
  47     <refname><varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1307</varname></refname>
  48     <refpurpose>eCos Support for the Dallas DS1307 Serial Real-Time Clock</refpurpose>
  49   </refnamediv>
  50
  51   <refsect1 id="devs-wallclock-dallas-ds1307-description"><title>Description</title>
  52     <para>
  53 This package
  54 <varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1307</varname> provides a
  55 device driver for the wallclock device in the Dallas DS1307 Serial
  56 Real-Time Clock chips. This combines a real-time clock and 56 bytes of
  57 battery-backed RAM in a single package. The driver can also be used
  58 with any other chips that provide the same interface to the clock
  59 hardware.
  60     </para>
  61     <para>
  62 The package will usually be loaded into the configuration
  63 automatically whenever selecting a target which contains a compatible
  64 chip. By default it will provide the standard eCos wallclock device,
  65 although another implementation such as software emulation may be
  66 selected if desired. The only other configuration options related to
  67 this package allow users to change the compiler flags. If the
  68 application does not actually use the wallclock device, directly or
  69 indirectly, then the code should get removed automatically at
  70 link-time to ensure that the application does not suffer any
  71 unnecessary overheads.
  72     </para>
  73   </refsect1>
  74
  75   <refsect1 id="devs-wallclock-dallas-ds1307-functions"><title>Functionality</title>
  76     <para>
  77 This wallclock device driver package implements the standard
  78 functionality required by the generic wallclock support
  79 <varname>CYGPKG_IO_WALLCLOCK</varname>. The functionality is not
  80 normally accessed directly. Instead it is used by the C library time
  81 package to implement standard calls such as <function>time</function>
  82 and <function>gmtime</function>. The eCos C library also provides a
  83 non-standard function <function>cyg_libc_time_settime</function> for
  84 changing the current wallclock setting. In addition RedBoot provides
  85 a <command>date</command> command which interacts with the wallclock
  86 device.
  87     </para>
  88   </refsect1>
  89
  90   <refsect1 id="devs-wallclock-dallas-ds1307-porting"><title>Porting</title>
  91     <para>
  92 DS1307 platform support can be implemented in one of two ways. The
  93 preferred approach involves the generic I2C API, as defined by the
  94 package <varname>CYGPKG_IO_I2C</varname>. The platform HAL can just
  95 provide a <structname>cyg_i2c_device</structname> structure
  96 <varname>cyg_i2c_wallclock_ds1307</varname> and implement the CDL
  97 interface
  98 <varname>CYGINT_DEVICES_WALLCLOCK_DALLAS_DS1307_I2C</varname>. The
  99 DS1307 driver will now use I2C rx and tx operations to interact with
 100 the chip.
 101     </para>
 102     <para>
 103 Alternatively the DS1307 driver can use macros or functions provided
 104 by another package to access the chip. This is intended primarily for
 105 older platforms that predate the <varname>CYGPKG_IO_I2C</varname>
 106 package. The other package should export a header file containing
 107 macros <function>DS_GET</function> and <function>DS_PUT</function>
 108 that transfer the eight bytes corresponding to the chip's clock
 109 registers. It should also export the name of this header via a
 110 <literal>#define</literal>
 111 <varname>CYGDAT_DEVS_WALLCLOCK_DS1307_INL</varname> in the global
 112 configuration header <filename
 113 class="headerfile">pkgconf/system.h</filename>. For full details see
 114 the source code.
 115     </para>
 116     <para>
 117 In addition the DS1307 device driver package
 118 <varname>CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1307</varname> should be
 119 included in the CDL target entry so that it gets loaded automatically
 120 whenever eCos is configured for that target.
 121     </para>
 122   </refsect1>
 123
 124 </refentry>
 125
 126 </part>