1 .\" $NetBSD: mk48txx.4,v 1.16 2009/04/10 17:14:07 joerg Exp $
3 .\" Copyright (c) 2000, 2002 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Paul Kranenburg.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
39 time-of-day clock driver
41 .In sys/eventhandler.h
44 .In dev/mk48txx/mk48txxvar.h
46 To compile this driver into the kernel,
47 place the following line in your
48 kernel configuration file:
49 .Bd -ragged -offset indent
55 driver is a back-end for several models of
57 time-of-day clock chips.
58 It provides access methods to retrieve and set date and time for use with the
62 To tie an instance of this device to the system, use the
64 function and the mk48txx_softc structure defined as follows:
67 .Fn mk48txx_attach "device_t dev"
69 typedef uint8_t (*mk48txx_nvrd_t)(device_t dev, int off);
70 typedef void (*mk48txx_nvwr_t)(device_t dev, int off, uint8_t v);
73 struct mk48txx_softc {
74 struct resource sc_res;
76 eventhandler_tag sc_wet;
78 bus_size_t sc_nvramsz;
79 bus_size_t sc_clkoffset;
82 mk48txx_nvrd_t sc_nvrd;
83 mk48txx_nvwr_t sc_nvwr;
86 .Bl -tag -width indent
88 The bus resource used for accessing the chip's non-volatile memory
89 .Pq including the clock registers ,
90 which must be supplied by the front-end when using the default access methods
92 Otherwise this member is optional.
94 The hardware mutex used when accessing the chip's non-volatile memory
95 .Pq including the clock registers ,
96 which must be initialized with
100 The event handler tag for the watchdog functionality,
101 which is registered by the
103 function if supported by the chip and specified as part of the
104 machine-dependent features
107 The chip model which this instance should serve.
108 This member must be set to one of
116 The size of the non-volatile RAM in the
123 The offset into the control registers of the
130 The year offset to be used with the
132 counter of the clock,
133 which must be set by the front-end.
134 This value is generally dependent on the system configuration in which
135 the clock device is mounted.
138 machines the convention is to have clock's two-digit year represent
141 This flag is used to specify machine-dependent features.
142 The following flags are supported:
143 .Bl -tag -width ".Dv MK48TXX_WDOG_ENABLE_WDS"
144 .It Dv MK48TXX_NO_CENT_ADJUST
145 If the resulting date retrieved with the
146 .Dq Li clock_gettime() method
147 would be earlier than January 1, 1970,
148 the driver will assume that the chip's year counter actually represents a
149 year in the 21st century.
150 This behavior can be overridden by setting this flag,
153 driver to respect the clock's century bit instead.
154 .It Dv MK48TXX_WDOG_REGISTER
155 When this flag is set,
158 driver will register as a watchdog via the interface defined in
160 if supported by the specific chip model.
161 .It Dv MK48TXX_WDOG_ENABLE_WDS
162 When this flag is set,
165 driver will set the watchdog steering
167 bit when enabling the watchdog functionality of the chip.
169 .Pq see the chip documentation for further information regarding the WDS bit .
173 These members specify the access methods for reading respectively writing
174 clock device registers.
178 is passed as an access method,
179 is to access the chip memory
180 .Pq and clock registers
181 as if they were direct-mapped using the specified bus resource.
183 Otherwise, the driver will call the respective function supplied by the
184 front-end to perform the access,
185 passing it the offset
188 .Pq or clock register
189 location to be read from or written to, respectively.
192 The following models are supported:
194 .Bl -tag -width indent -offset indent -compact
195 .It Tn Mostek MK48T02
196 .It Tn Mostek MK48T08
197 .It Tn Mostek MK48T18
198 .It Tn Mostek MK48T59
210 version to include it was
216 driver was written for
219 .An Paul Kranenburg Aq Mt pk@NetBSD.org .
223 .An Thomas Moestl Aq Mt tmm@FreeBSD.org
224 and later on improved by
225 .An Marius Strobl Aq Mt marius@FreeBSD.org .