From owner-svn-src-stable-7@FreeBSD.ORG Fri Jan 15 16:21:32 2010 Return-Path: Delivered-To: svn-src-stable-7@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 97AC31065676; Fri, 15 Jan 2010 16:21:32 +0000 (UTC) (envelope-from marius@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 845D78FC17; Fri, 15 Jan 2010 16:21:32 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id o0FGLWHl025017; Fri, 15 Jan 2010 16:21:32 GMT (envelope-from marius@svn.freebsd.org) Received: (from marius@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id o0FGLWhG025014; Fri, 15 Jan 2010 16:21:32 GMT (envelope-from marius@svn.freebsd.org) Message-Id: <201001151621.o0FGLWhG025014@svn.freebsd.org> From: Marius Strobl Date: Fri, 15 Jan 2010 16:21:32 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-7@freebsd.org X-SVN-Group: stable-7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r202388 - stable/7/share/man/man4 X-BeenThere: svn-src-stable-7@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for only the 7-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 15 Jan 2010 16:21:32 -0000 Author: marius Date: Fri Jan 15 16:21:32 2010 New Revision: 202388 URL: http://svn.freebsd.org/changeset/base/202388 Log: MFC: r201007 Add a man page for mk48txx(4). Requested by: n_hibma Obtained from: NetBSD (original version) Added: stable/7/share/man/man4/mk48txx.4 - copied unchanged from r201006, head/share/man/man4/mk48txx.4 Modified: stable/7/share/man/man4/Makefile Directory Properties: stable/7/share/man/man4/ (props changed) Modified: stable/7/share/man/man4/Makefile ============================================================================== --- stable/7/share/man/man4/Makefile Fri Jan 15 16:04:30 2010 (r202387) +++ stable/7/share/man/man4/Makefile Fri Jan 15 16:21:32 2010 (r202388) @@ -180,6 +180,7 @@ MAN= aac.4 \ meteor.4 \ mfi.4 \ miibus.4 \ + mk48txx.4 \ mlx.4 \ mly.4 \ mmc.4 \ Copied: stable/7/share/man/man4/mk48txx.4 (from r201006, head/share/man/man4/mk48txx.4) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/7/share/man/man4/mk48txx.4 Fri Jan 15 16:21:32 2010 (r202388, copy of r201006, head/share/man/man4/mk48txx.4) @@ -0,0 +1,230 @@ +.\" $NetBSD: mk48txx.4,v 1.16 2009/04/10 17:14:07 joerg Exp $ +.\" +.\" Copyright (c) 2000, 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 25, 2009 +.Dt MK48TXX 4 +.Os +.Sh NAME +.Nm mk48txx +.Nd +.Tn Mostek +time-of-day clock driver +.Sh SYNOPSIS +.In sys/eventhandler.h +.In sys/lock.h +.In sys/mutex.h +.In dev/mk48txx/mk48txxvar.h +.Pp +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device mk48txx" +.Ed +.Sh DESCRIPTION +The +.Nm +driver is a back-end for several models of +.Tn Mostek +time-of-day clock chips. +It provides access methods to retrieve and set date and time for use with the +.Dq Li clock +KOBJ interface. +.Pp +To tie an instance of this device to the system, use the +.Fn mk48txx_attach +function and the mk48txx_softc structure defined as follows: +.Pp +.Ft "int" +.Fn mk48txx_attach "device_t dev" +.Pp +.Bd -literal +typedef uint8_t (*mk48txx_nvrd_t)(device_t dev, int off); +typedef void (*mk48txx_nvwr_t)(device_t dev, int off, uint8_t v); +.Ed +.Bd -literal +struct mk48txx_softc { + struct resource sc_res; + struct mtx sc_mtx; + eventhandler_tag sc_wet; + const char *sc_model; + bus_size_t sc_nvramsz; + bus_size_t sc_clkoffset; + u_int sc_year0; + u_int sc_flag; + mk48txx_nvrd_t sc_nvrd; + mk48txx_nvwr_t sc_nvwr; +}; +.Ed +.Pp +.Bl -tag -width indent +.It Fa sc_res +The bus resource used for accessing the chip's non-volatile memory +.Pq including the clock registers , +which must be supplied by the front-end when using the default access methods +.Pq see below . +Otherwise this member is optional. +.It Fa sc_mtx +The hardware mutex used when accessing the chip's non-volatile memory +.Pq including the clock registers , +which must be initialized with +.Dv MTX_DEF +by the front-end. +.It Fa sc_wet +The event handler tag for the watchdog functionality, +which is registered by the +.Fn mk48txx_attach +function if supported by the chip and specified as part of the +machine-dependent features +.Pq see below . +.It Fa sc_model +The chip model which this instance should serve. +This member must be set to one of +.Dq mk48t02 , +.Dq mk48t08 , +.Dq mk48t18 , +or +.Dq mk48t59 +by the front-end. +.It Fa sc_nvramsz +The size of the non-volatile RAM in the +.Tn Mostek +chip, +which is set by the +.Fn mk48txx_attach +function. +.It Fa sc_clkoffset +The offset into the control registers of the +.Tn Mostek +chip, +which is set by the the +.Fn mk48txx_attach +function. +.It Fa sc_year0 +The year offset to be used with the +.Sq year +counter of the clock, +which must be set by the front-end. +This value is generally dependent on the system configuration in which +the clock device is mounted. +For instance, on +.Tn Sun Microsystems +machines the convention is to have clock's two-digit year represent +the year since 1968. +.It Fa sc_flag +This flag is used to specify machine-dependent features. +The following flags are supported: +.Bl -tag -width ".Dv MK48TXX_WDOG_ENABLE_WDS" +.It Dv MK48TXX_NO_CENT_ADJUST +If the resulting date retrieved with the +.Dq Li clock_gettime() method +would be earlier than January 1, 1970, +the driver will assume that the chip's year counter actually represents a +year in the 21st century. +This behavior can be overridden by setting this flag, +which causes the +.Nm +driver to respect the clock's century bit instead. +.It Dv MK48TXX_WDOG_REGISTER +When this flag is set, +the +.Nm +driver will register as a watchdog via the interface defined in +.Xr 9 watchdog +if supported by the specific chip model. +.It Dv MK48TXX_WDOG_ENABLE_WDS +When this flag is set, +the +.Nm +driver will set the watchdog steering +.Pq WDS +bit when enabling the watchdog functionality of the chip. +enabled +.Pq see the chip documentation for further information regarding the WDS bit . +.El +.It Fa sc_nvread +.It Fa sc_nvwrite +These members specify the access methods for reading respectively writing +clock device registers. +The default, +when +.Dv NULL +is passed as an access method, +is to access the chip memory +.Pq and clock registers +as if they were direct-mapped using the specified bus resource. +.Pp +Otherwise, the driver will call the respective function supplied by the +front-end to perform the access, +passing it the offset +.Va off +of the chip memory +.Pq or clock register +location to be read from or written to, respectively. +.El +.Sh HARDWARE +The following models are supported: +.Pp +.Bl -tag -width indent -offset indent -compact +.It Tn Mostek MK48T02 +.It Tn Mostek MK48T08 +.It Tn Mostek MK48T18 +.It Tn Mostek MK48T59 +.El +.Sh SEE ALSO +.Xr intro 4 , +.Xr watchdog 9 +.Sh HISTORY +The +.Nm mk48txx +driver appeared in +.Nx 1.5 . +The first +.Fx +version to include it was +.Fx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written for +.Nx +by +.An Paul Kranenburg +.Aq pk@NetBSD.org . +It was ported to +.Fx +by +.An Thomas Moestl +.Aq tmm@FreeBSD.org +and later on improved by +.An Marius Strobl +.Aq marius@FreeBSD.org .