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"
70 typedef uint8_t (*mk48txx_nvrd_t)(device_t dev, int off);
71 typedef void (*mk48txx_nvwr_t)(device_t dev, int off, uint8_t v);
74 struct mk48txx_softc {
75 struct resource sc_res;
77 eventhandler_tag sc_wet;
79 bus_size_t sc_nvramsz;
80 bus_size_t sc_clkoffset;
83 mk48txx_nvrd_t sc_nvrd;
84 mk48txx_nvwr_t sc_nvwr;
88 .Bl -tag -width indent
90 The bus resource used for accessing the chip's non-volatile memory
91 .Pq including the clock registers ,
92 which must be supplied by the front-end when using the default access methods
94 Otherwise this member is optional.
96 The hardware mutex used when accessing the chip's non-volatile memory
97 .Pq including the clock registers ,
98 which must be initialized with
102 The event handler tag for the watchdog functionality,
103 which is registered by the
105 function if supported by the chip and specified as part of the
106 machine-dependent features
109 The chip model which this instance should serve.
110 This member must be set to one of
118 The size of the non-volatile RAM in the
125 The offset into the control registers of the
128 which is set by the the
132 The year offset to be used with the
134 counter of the clock,
135 which must be set by the front-end.
136 This value is generally dependent on the system configuration in which
137 the clock device is mounted.
140 machines the convention is to have clock's two-digit year represent
143 This flag is used to specify machine-dependent features.
144 The following flags are supported:
145 .Bl -tag -width ".Dv MK48TXX_WDOG_ENABLE_WDS"
146 .It Dv MK48TXX_NO_CENT_ADJUST
147 If the resulting date retrieved with the
148 .Dq Li clock_gettime() method
149 would be earlier than January 1, 1970,
150 the driver will assume that the chip's year counter actually represents a
151 year in the 21st century.
152 This behavior can be overridden by setting this flag,
155 driver to respect the clock's century bit instead.
156 .It Dv MK48TXX_WDOG_REGISTER
157 When this flag is set,
160 driver will register as a watchdog via the interface defined in
162 if supported by the specific chip model.
163 .It Dv MK48TXX_WDOG_ENABLE_WDS
164 When this flag is set,
167 driver will set the watchdog steering
169 bit when enabling the watchdog functionality of the chip.
171 .Pq see the chip documentation for further information regarding the WDS bit .
175 These members specify the access methods for reading respectively writing
176 clock device registers.
180 is passed as an access method,
181 is to access the chip memory
182 .Pq and clock registers
183 as if they were direct-mapped using the specified bus resource.
185 Otherwise, the driver will call the respective function supplied by the
186 front-end to perform the access,
187 passing it the offset
190 .Pq or clock register
191 location to be read from or written to, respectively.
194 The following models are supported:
196 .Bl -tag -width indent -offset indent -compact
197 .It Tn Mostek MK48T02
198 .It Tn Mostek MK48T08
199 .It Tn Mostek MK48T18
200 .It Tn Mostek MK48T59
212 version to include it was
218 driver was written for
228 and later on improved by
230 .Aq marius@FreeBSD.org .