sid/component/rtc/hw-rtc-ds1x42.txt

   1 * Name
   2   hw-rtc-ds1642 hw-rtc-ds1742
   3
   4 * Synopsis
   5   The Dallas DS1642 and DS1742 are time-keeping NVRAM devices.  The
   6   DS1742 is Y2K compliant as it maintains a century field in a section
   7   of NVRAM that was previously reserved by Dallas in the DS1642.
   8
   9   Pins: clock clock-control clock-event
  10   Buses: read-write-port
  11   Attributes: epoch-time year month date day-of-week hour minute second
  12               state-snapshot "tk xclock clone"
  13               century (ds1742 only)
  14   Accessors:  memory-bus
  15   Library: librtc.la
  16   Symbol name: rtc_component_library
  17
  18 * Functionality
  19
  20   - Modelling
  21
  22   The DS1x42 components model real time using a single pin that can be
  23   driven at a simulated interval representing one second.  For
  24   modelling time in the target domain, a target scheduler may be used.
  25   For modelling real "wall-clock" time, the host scheduler may be
  26   used.
  27
  28   The DS1x42 have a "frequency test" function that involves toggling
  29   the least significant bit of the "seconds" register at an idealized
  30   frequency of 512Hz.  When managed by a sid scheduler component, the
  31   actual frequency is around 500Hz.
  32
  33   - Behaviors
  34
  35   * Timekeeping
  36
  37     Whenever the "clock" input is driven, it is interpreted as a
  38     signal that one second has passed.  An internal counter is
  39     incremented and all the time-related registers are recomputed.
  40     The counter is accessible by the "epoch-time" attribute.
  41
  42   * Frequency testing
  43
  44     When the "clock-control" and "clock-event" pin-pair is connected
  45     to an external scheduler, the DS1642 standard "test bit" is
  46     toggled at an approximate simulated frequency.
  47
  48   * Register access
  49
  50     The DS1642/DS1742 control registers and 2048-byte NVRAM are
  51     accessed across the "read-write-port" bus for byte-wide
  52     operations.  The control registers are also exposed as attributes.
  53
  54     This family of parts includes 2KB of non-volatile RAM.  This
  55     component does not explicitly model this memory.  Instead, it
  56     interacts through the "memory-bus" accessor with an external
  57     memory like hw-memory-ram/rom-basic.
  58
  59   - SID conventions
  60     * These are functional components.
  61     * They support state save/restore.
  62     * They support setting triggerpoints on the state of data with the following
  63       names:
  64         - "epoch-time"          Canonical internal representation of time.
  65         - "oscillating"         The oscillator is connected.
  66         - "write-mode"          The device is in write mode, for updates.
  67
  68 * Environment
  69   - Related components
  70
  71     * The 2KB of non-volatile memory included in these parts is not
  72       explicitly modeled by this component.  Instead, it uses the
  73       "memory-bus" accessor to interact with an external memory like
  74       hw-memory-ram/rom-basic:
  75
  76         new hw-memory-ram/rom-basic nvram
  77         set nvram size 2048
  78         connect-bus rtc memory-bus nvram read-write-port
  79
  80     * In order to enable the "frequency test" function, you need to
  81       couple an external scheduler to this component. The following is
  82       an example of how to configure such a connection between a
  83       scheduler and the DS1742 component:
  84
  85         new sid-sched-host-accurate sched
  86         new hw-rtc-ds1742 rtc
  87         set sched num-clients 2
  88         set sched 0-regular? 1
  89         set sched 0-time 1000 # 1 sec
  90         connect-pin sched 0-event -> rtc clock
  91         connect-pin rtc clock-control -> sched 1-control
  92         connect-pin rtc clock-event <- sched 1-event
  93
  94     * The "hw-visual-clock" component is a candidate gui for this
  95       component.
  96
  97         new hw-rtc-ds1742 rtc
  98         new hw-visual-clock rtc-gui
  99         relate rtc-gui "your rtc friend" rtc
 100
 101   - Host system
 102
 103     * These components rely on the accuracy and integrity of UTC time
 104       maintained by the host, as the time and date are initialized
 105       when the component is instantiated. The UNIX time() system call
 106       is used to acquire the time.
 107
 108 * SID interface reference
 109   - low level:
 110     * pins
 111       - clock | input | any | timekeeping
 112       - clock-control | output | positive number | frequency testing
 113       - clock-event | input | any | frequency testing
 114
 115     * buses
 116       - read-write-port | 0x0 - 0x7FF | read/write byte-wide | register access
 117
 118     * attributes
 119       - epoch-time | | unsigned 32-bit integer | n/a | timekeeping
 120       - year | register | 0..99 | n/a | register access
 121       - month | register | 1..12 | n/a | register access
 122       - date | register | 1..31 | n/a | register access
 123       - day-of-week | register | 1..7 | n/a | regiser access
 124       - hour | register | 0..23 | n/a | register access
 125       - minute | register | 0..59 | n/a | register access
 126       - second | register | 0..59 | n/a | register access
 127       - century | register | 19..25 | n/a | register access (DS1742 only)
 128       - state-snapshot | | opaque string | n/a | state save/restore
 129       - "tk xclock clone" | gui | "hw-visual-clock" | (same) | component gui
 130
 131     * accessors
 132       - memory-bus | byte-wide accesses | register access
 133
 134 * References
 135
 136   Dallas Semiconductor DS1642 data sheet, revision 031698; DS1742 data
 137   sheet, revision 091498. Obtained from
 138   <http://www.dalsemi.com/Prod_info/Time_Keep/index.html>.