.\" $NetBSD: todr.9,v 1.18 2014/09/10 14:28:02 martin Exp $
.\"
.\" Copyright (c) 2000, 2003 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.
.\"
.Dd September 10, 2014
.Dt TODR 9
.Os
.Sh NAME
.Nm todr_attach ,
.Nm todr_gettime ,
.Nm todr_settime ,
.Nm clock_ymdhms_to_secs ,
.Nm clock_secs_to_ymdhms
.Nd time-of-day clock support
.Sh SYNOPSIS
.In dev/clock_subr.h
.Ft void
.Fn todr_attach "todr_chip_handle_t"
.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 clock_secs_to_ymdhms "time_t" "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
.Ql time-of-day
devices.
A driver for a
.Ql time-of-day
device registers its
.Fa todr_chip_handle_t
with machine-dependent code using the
.Fn todr_attach
function.
Alternatively, a machine-dependent front-end to a
.Ql time-of-day
device driver may obtain the
.Fa todr_chip_handle_t
directly.
.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
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 {
	uint64_t dt_year;	/* Year */
	u_char dt_mon;		/* Month (1-12) */
	u_char dt_day;		/* Day (1-31) */
	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
.In 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.
.Pp
The
.Fn clock_ymdhms_to_secs
function returns \-1 if the time in seconds would be less that zero or too
large to fit in a
.Fa time_t .
The
.Fn clock_secs_to_ymdhms
function returns 0 on success or
.Er EINVAL
if the time passed is negative.
.Sh SEE ALSO
.Xr intersil7170 4 ,
.Xr mk48txx 4 ,
.Xr inittodr 9 ,
.Xr resettodr 9 ,
.Xr time_second 9