138 lines
4.7 KiB
Groff
138 lines
4.7 KiB
Groff
.\" $NetBSD: todr.9,v 1.1 2000/07/25 21:12:45 pk Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.Dd July 22, 2000
|
|
.Dt TODR 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm todr_gettime
|
|
.Nm todr_settime
|
|
.Nm todr_getcal
|
|
.Nm todr_setcal
|
|
.Nm clock_ymdhms_to_secs
|
|
.Nm clock_secs_to_ymdhms
|
|
.Nd time-of-day clock support
|
|
.Sh SYNOPSIS
|
|
.Fd #include <dev/clock_subr.h>
|
|
.Ft int
|
|
.Fn todr_gettime "todr_chip_handle_t" "struct timeval *"
|
|
.Ft int
|
|
.Fn todr_settime "todr_chip_handle_t" "struct timeval *"
|
|
.Ft int
|
|
.Fn todr_getcal "todr_chip_handle_t" "int *"
|
|
.Ft int
|
|
.Fn todr_setcal "todr_chip_handle_t" "int"
|
|
.Ft void
|
|
.Fn clock_secs_to_ymdhms "int" "struct clock_ymdhms *"
|
|
.Ft time_t
|
|
.Fn clock_ymdhms_to_secs "struct clock_ymdhms *"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn todr_*
|
|
functions provide an interface to read, set and control
|
|
.Qs time-of-day
|
|
devices. The
|
|
.Fa todr_chip_handle_t
|
|
should be obtained from a driver for a particular hardware device that
|
|
implements this interface. Examples of such drivers currently include
|
|
.Xr mk48txx 4
|
|
and
|
|
.Xr intersil7170 4 .
|
|
.Pp
|
|
The
|
|
.Fn todr_gettime
|
|
retrieves the current data and time from the TODR device and returns it
|
|
in the
|
|
.Fa struct timeval
|
|
storage provided by the caller.
|
|
.Fn todr_settime
|
|
sets the date and time in the TODR device represented by
|
|
.Fa todr_chip_handle_t
|
|
according to the
|
|
.Fa struct timeval
|
|
argument.
|
|
.Pp
|
|
.Fn todr_setcal
|
|
specifies a calibration value in PPM units to be programmed in the TODR
|
|
device. Positive values shall speed up the TODR clock, negative values
|
|
shall slow it down. If the device in not capable of handling calibration,
|
|
this function shall return
|
|
.Va EOPNOTSUPP .
|
|
The measurement and calculations necessary to utilize this method is
|
|
expected to be provided by higher-level software modules.
|
|
.Fn todr_getcal
|
|
returns the current calibration (in PPM units) in effect on the TODR device.
|
|
.Pp
|
|
The utilities
|
|
.Fn clock_secs_to_ymdhms
|
|
and
|
|
.Fn clock_ymdhms_to_secs
|
|
are provided to convert a time value in seconds to and from a structure
|
|
representing the date and time as a
|
|
.Aq year,month,day,weekday,hour,minute,seconds
|
|
tuple. This structure is defined as follows:
|
|
.Bd -literal
|
|
struct clock_ymdhms {
|
|
u_short dt_year; /* Year */
|
|
u_char dt_mon; /* Month (1-12) */
|
|
u_char dt_day; /* Day (0-365) */
|
|
u_char dt_wday; /* Day of week (0-6) */
|
|
u_char dt_hour; /* Hour (0-23) */
|
|
u_char dt_min; /* Minute (0-59) */
|
|
u_char dt_sec; /* Second (0-59) */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Note: leap years are recognised by these conversion routines.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn todr_*
|
|
functions return 0 if the requested operation was successful;
|
|
otherwise an error code from
|
|
.Aq Pa sys/errno.h
|
|
shall be returned. However, behaviour is undefined if an invalid
|
|
.Fa todr_chip_handle_t
|
|
is passed to any of these functions.
|
|
The
|
|
.Fn clock_secs_to_ymdhms
|
|
and
|
|
.Fn clock_ymdhms_to_secs
|
|
functions never fail.
|
|
.Sh SEE ALSO
|
|
.Xr inittodr 9 ,
|
|
.Xr resettodr 9 ,
|
|
.Xr time 9
|