share/man/man4/mk48txx.4

   1 .\"     $NetBSD: mk48txx.4,v 1.15 2008/04/30 13:10:54 martin 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 .Dd October 1, 2006
  31 .Dt MK48TXX 4
  32 .Os
  33 .Sh NAME
  34 .Nm mk48txx
  35 .Nd
  36 .Tn Mostek
  37 time-of-day clock driver
  38 .Sh SYNOPSIS
  39 .In dev/ic/mk48txxreg.h
  40 .In dev/ic/mk48txxvar.h
  41 .Cd "define mk48txx"
  42 .Cd "file   dev/ic/mk48txx.c    mk48txx"
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 driver provides access to several models of
  47 .Tn Mostek
  48 time-of-day clock chips.
  49 Access methods to retrieve and set date and time
  50 are provided through the
  51 .Em TODR
  52 interface defined in
  53 .Xr todr 9 .
  54 .Pp
  55 To tie an instance of this device to the system, use the
  56 .Fn mk48txx_attach
  57 function and the mk48txx_softc structure defined as follows:
  58 .Pp
  59 .Ft "void"
  60 .Fn mk48txx_attach "struct mk48txx_softc *"
  61 .Pp
  62 .Bd -literal
  63 typedef uint8_t (*mk48txx_nvrd_t)(struct mk48txx_softc *, int off);
  64 typedef void (*mk48txx_nvwr_t)(struct mk48txx_softc *, int off,
  65     uint8_t datum);
  66 .Ed
  67 .Bd -literal
  68 struct mk48txx_softc {
  69         struct device   sc_dev;
  70         bus_space_tag_t sc_bst;
  71         bus_space_handle_t sc_bsh;
  72         struct todr_chip_handle sc_handle;
  73         const char      *sc_model;
  74         bus_size_t      sc_nvramsz;
  75         bus_size_t      sc_clkoffset;
  76         u_int           sc_year0;
  77         u_int           sc_flag;
  78         mk48txx_nvrd_t  sc_nvrd;
  79         mk48txx_nvwr_t  sc_nvwr;
  80 };
  81 .Ed
  82 .Pp
  83 .Bl -tag -width Dv -offset indent
  84 .It Fa sc_bst
  85 .It Fa sc_bsh
  86 Specify bus space access to the chip's non-volatile memory
  87 .Pq including the clock registers .
  88 .It Fa sc_handle
  89 TODR handle passed to the
  90 .Fn todr_attach
  91 function to register
  92 .Xr todr 9
  93 interface.
  94 .It Fa sc_model
  95 The chip model which this instance should serve.
  96 Must be one of
  97 .Dq mk48t02 ,
  98 .Dq mk48t08 ,
  99 .Dq mk48t18 ,
 100 or
 101 .Dq mk48t59 .
 102 .It Fa sc_nvramsz
 103 Size of non-volatile RAM in the
 104 .Tn Mostek
 105 chip.
 106 This value is set by
 107 .Fn mk48txx_attach .
 108 .It Fa sc_clkoffset
 109 Offset into the control registers of the
 110 .Tn Mostek
 111 chip.
 112 This value is set by
 113 .Fn mk48txx_attach .
 114 .It Fa sc_year0
 115 The actual year represented by the clock's
 116 .Sq year
 117 counter.
 118 This is generally dependent on the system configuration in which
 119 the clock device is mounted.
 120 For instance, on
 121 .Tn Sun Microsystems
 122 machines the convention is to have clock's two-digit year represent
 123 the year 1968.
 124 .It Fa sc_flag
 125 This flag is used to specify machine-dependent features.
 126 .It Fa sc_nvread
 127 .It Fa sc_nvwrite
 128 Specify alternate access methods for reading resp. writing clock
 129 device registers.
 130 The default, when
 131 .Dv NULL
 132 is passed as an access method, is to access the chip memory
 133 .Pq and clock registers
 134 as if they were direct-mapped with using the specified bus space.
 135 .Pp
 136 Otherwise, the driver will call the respective function to perform the
 137 access, passing it the specified bus space and the offset
 138 .Va off
 139 of the chip memory
 140 .Pq or clock register
 141 location to be read from or written to, respectively.
 142 .El
 143 .Pp
 144 Note that if the resulting date retrieved with the todr_gettime() method
 145 is earlier that January 1, 1970, the driver will assume that the chip's
 146 year counter actually represents a year in the 21st century.
 147 This behaviour can be overridden by setting the
 148 .Va MK48TXX_NO_CENT_ADJUST
 149 flag in
 150 .Fa sc_flag .
 151 .Sh HARDWARE
 152 The following models are supported:
 153 .Pp
 154 .Bl -tag -width indent -offset indent -compact
 155 .It Tn Mostek MK48T02
 156 .It Tn Mostek MK48T08
 157 .It Tn Mostek MK48T18
 158 .It Tn Mostek MK48T59
 159 .El
 160 .Sh SEE ALSO
 161 .Xr intro 4 ,
 162 .Xr todr 9
 163 .Sh HISTORY
 164 The
 165 .Nm mk48txx
 166 driver first appeared in
 167 .Nx 1.5 .
 168 .Sh AUTHORS
 169 The
 170 .Nm
 171 driver was written by
 172 .An Paul Kranenburg
 173 .Aq pk@NetBSD.org .