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 .Bd -literal
  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);
  71 .Ed
  72 .Bd -literal
  73 struct mk48txx_softc {
  74         struct resource sc_res;
  75         struct mtx      sc_mtx;
  76         eventhandler_tag        sc_wet;
  77         const char      *sc_model;
  78         bus_size_t      sc_nvramsz;
  79         bus_size_t      sc_clkoffset;
  80         u_int           sc_year0;
  81         u_int           sc_flag;
  82         mk48txx_nvrd_t  sc_nvrd;
  83         mk48txx_nvwr_t  sc_nvwr;
  84 };
  85 .Ed
  86 .Bl -tag -width indent
  87 .It Fa sc_res
  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
  91 .Pq see below .
  92 Otherwise this member is optional.
  93 .It Fa sc_mtx
  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
  97 .Dv MTX_DEF
  98 by the front-end.
  99 .It Fa sc_wet
 100 The event handler tag for the watchdog functionality,
 101 which is registered by the
 102 .Fn mk48txx_attach
 103 function if supported by the chip and specified as part of the
 104 machine-dependent features
 105 .Pq see below .
 106 .It Fa sc_model
 107 The chip model which this instance should serve.
 108 This member must be set to one of
 109 .Dq mk48t02 ,
 110 .Dq mk48t08 ,
 111 .Dq mk48t18 ,
 112 or
 113 .Dq mk48t59
 114 by the front-end.
 115 .It Fa sc_nvramsz
 116 The size of the non-volatile RAM in the
 117 .Tn Mostek
 118 chip,
 119 which is set by the
 120 .Fn mk48txx_attach
 121 function.
 122 .It Fa sc_clkoffset
 123 The offset into the control registers of the
 124 .Tn Mostek
 125 chip,
 126 which is set by the
 127 .Fn mk48txx_attach
 128 function.
 129 .It Fa sc_year0
 130 The year offset to be used with the
 131 .Sq year
 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.
 136 For instance, on
 137 .Tn Sun Microsystems
 138 machines the convention is to have clock's two-digit year represent
 139 the year since 1968.
 140 .It Fa sc_flag
 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,
 151 which causes the
 152 .Nm
 153 driver to respect the clock's century bit instead.
 154 .It Dv MK48TXX_WDOG_REGISTER
 155 When this flag is set,
 156 the
 157 .Nm
 158 driver will register as a watchdog via the interface defined in
 159 .Xr watchdog 9
 160 if supported by the specific chip model.
 161 .It Dv MK48TXX_WDOG_ENABLE_WDS
 162 When this flag is set,
 163 the
 164 .Nm
 165 driver will set the watchdog steering
 166 .Pq WDS
 167 bit when enabling the watchdog functionality of the chip.
 168 enabled
 169 .Pq see the chip documentation for further information regarding the WDS bit .
 170 .El
 171 .It Fa sc_nvread
 172 .It Fa sc_nvwrite
 173 These members specify the access methods for reading respectively writing
 174 clock device registers.
 175 The default,
 176 when
 177 .Dv NULL
 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.
 182 .Pp
 183 Otherwise, the driver will call the respective function supplied by the
 184 front-end to perform the access,
 185 passing it the offset
 186 .Va off
 187 of the chip memory
 188 .Pq or clock register
 189 location to be read from or written to, respectively.
 190 .El
 191 .Sh HARDWARE
 192 The following models are supported:
 193 .Pp
 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
 199 .El
 200 .Sh SEE ALSO
 201 .Xr intro 4 ,
 202 .Xr watchdog 9
 203 .Sh HISTORY
 204 The
 205 .Nm mk48txx
 206 driver appeared in
 207 .Nx 1.5 .
 208 The first
 209 .Fx
 210 version to include it was
 211 .Fx 5.0 .
 212 .Sh AUTHORS
 213 .An -nosplit
 214 The
 215 .Nm
 216 driver was written for
 217 .Nx
 218 by
 219 .An Paul Kranenburg
 220 .Aq pk@NetBSD.org .
 221 It was ported to
 222 .Fx
 223 by
 224 .An Thomas Moestl
 225 .Aq tmm@FreeBSD.org
 226 and later on improved by
 227 .An Marius Strobl
 228 .Aq marius@FreeBSD.org .