share/man/man4/mk48txx.4

   1 .\"     $NetBSD: mk48txx.4,v 1.16 2009/04/10 17:14:07 joerg Exp $
   2 .\"
   3 .\" Copyright (c) 2000, 2002 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Paul Kranenburg.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  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.
  17 .\"
  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.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd December 25, 2009
  33 .Dt MK48TXX 4
  34 .Os
  35 .Sh NAME
  36 .Nm mk48txx
  37 .Nd
  38 .Tn Mostek
  39 time-of-day clock driver
  40 .Sh SYNOPSIS
  41 .In sys/eventhandler.h
  42 .In sys/lock.h
  43 .In sys/mutex.h
  44 .In dev/mk48txx/mk48txxvar.h
  45 .Pp
  46 To compile this driver into the kernel,
  47 place the following line in your
  48 kernel configuration file:
  49 .Bd -ragged -offset indent
  50 .Cd "device mk48txx"
  51 .Ed
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 driver is a back-end for several models of
  56 .Tn Mostek
  57 time-of-day clock chips.
  58 It provides access methods to retrieve and set date and time for use with the
  59 .Dq Li clock
  60 KOBJ interface.
  61 .Pp
  62 To tie an instance of this device to the system, use the
  63 .Fn mk48txx_attach
  64 function and the mk48txx_softc structure defined as follows:
  65 .Pp
  66 .Ft "int"
  67 .Fn mk48txx_attach "device_t dev"
  68 .Pp
  69 .Bd -literal
  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);
  72 .Ed
  73 .Bd -literal
  74 struct mk48txx_softc {
  75         struct resource sc_res;
  76         struct mtx      sc_mtx;
  77         eventhandler_tag        sc_wet;
  78         const char      *sc_model;
  79         bus_size_t      sc_nvramsz;
  80         bus_size_t      sc_clkoffset;
  81         u_int           sc_year0;
  82         u_int           sc_flag;
  83         mk48txx_nvrd_t  sc_nvrd;
  84         mk48txx_nvwr_t  sc_nvwr;
  85 };
  86 .Ed
  87 .Pp
  88 .Bl -tag -width indent
  89 .It Fa sc_res
  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
  93 .Pq see below .
  94 Otherwise this member is optional.
  95 .It Fa sc_mtx
  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
  99 .Dv MTX_DEF
 100 by the front-end.
 101 .It Fa sc_wet
 102 The event handler tag for the watchdog functionality,
 103 which is registered by the
 104 .Fn mk48txx_attach
 105 function if supported by the chip and specified as part of the
 106 machine-dependent features
 107 .Pq see below .
 108 .It Fa sc_model
 109 The chip model which this instance should serve.
 110 This member must be set to one of
 111 .Dq mk48t02 ,
 112 .Dq mk48t08 ,
 113 .Dq mk48t18 ,
 114 or
 115 .Dq mk48t59
 116 by the front-end.
 117 .It Fa sc_nvramsz
 118 The size of the non-volatile RAM in the
 119 .Tn Mostek
 120 chip,
 121 which is set by the
 122 .Fn mk48txx_attach
 123 function.
 124 .It Fa sc_clkoffset
 125 The offset into the control registers of the
 126 .Tn Mostek
 127 chip,
 128 which is set by the the
 129 .Fn mk48txx_attach
 130 function.
 131 .It Fa sc_year0
 132 The year offset to be used with the
 133 .Sq year
 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.
 138 For instance, on
 139 .Tn Sun Microsystems
 140 machines the convention is to have clock's two-digit year represent
 141 the year since 1968.
 142 .It Fa sc_flag
 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,
 153 which causes the
 154 .Nm
 155 driver to respect the clock's century bit instead.
 156 .It Dv MK48TXX_WDOG_REGISTER
 157 When this flag is set,
 158 the
 159 .Nm
 160 driver will register as a watchdog via the interface defined in
 161 .Xr 9 watchdog
 162 if supported by the specific chip model.
 163 .It Dv MK48TXX_WDOG_ENABLE_WDS
 164 When this flag is set,
 165 the
 166 .Nm
 167 driver will set the watchdog steering
 168 .Pq WDS
 169 bit when enabling the watchdog functionality of the chip.
 170 enabled
 171 .Pq see the chip documentation for further information regarding the WDS bit .
 172 .El
 173 .It Fa sc_nvread
 174 .It Fa sc_nvwrite
 175 These members specify the access methods for reading respectively writing
 176 clock device registers.
 177 The default,
 178 when
 179 .Dv NULL
 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.
 184 .Pp
 185 Otherwise, the driver will call the respective function supplied by the
 186 front-end to perform the access,
 187 passing it the offset
 188 .Va off
 189 of the chip memory
 190 .Pq or clock register
 191 location to be read from or written to, respectively.
 192 .El
 193 .Sh HARDWARE
 194 The following models are supported:
 195 .Pp
 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
 201 .El
 202 .Sh SEE ALSO
 203 .Xr intro 4 ,
 204 .Xr watchdog 9
 205 .Sh HISTORY
 206 The
 207 .Nm mk48txx
 208 driver appeared in
 209 .Nx 1.5 .
 210 The first
 211 .Fx
 212 version to include it was
 213 .Fx 5.0 .
 214 .Sh AUTHORS
 215 .An -nosplit
 216 The
 217 .Nm
 218 driver was written for
 219 .Nx
 220 by
 221 .An Paul Kranenburg
 222 .Aq pk@NetBSD.org .
 223 It was ported to
 224 .Fx
 225 by
 226 .An Thomas Moestl
 227 .Aq tmm@FreeBSD.org
 228 and later on improved by
 229 .An Marius Strobl
 230 .Aq marius@FreeBSD.org .