NetBSD/share/man/man4/man4.x68k/pow.4

.\"	$NetBSD: pow.4,v 1.2 1998/01/09 08:04:39 perry Exp $
.\"
.\" Copyright (c) 1995 MINOURA Makoto.
.\" All rights reserved.
.\"
.\" 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 Minoura Makoto.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 2, 1995
.Os
.Dt pow 4 
.Sh NAME
.Nm pow
.Nd "X68k power switch device"
.Sh DESCRIPTION
Files
.Pa /dev/pow
and
.Pa /dev/pow1
are devices used to access the x68k power switch / bootstrap information and
the RTC alarm timer. The following operations are allowed using
.Xr ioctl 2
system call:

.Bl -tag -width POWIOCGPOWERINFO -compact -offset indent
.It POWIOGPOWERINFO
Getting power switch status
.It POWIOGALARMINFO
Getting RTC alarm timer status
.It POWIOSALARMINFO
Setting RTC alarm timer
.It POWIOSSIGNAL
Setting signal number which is sent at changing the power status
.El
.Sh GETTING POWER SWITCH STATUS
.Bd -literal
.Fd #include <sys/ioctl.h>
.Fd #include <machine/powioctl.h>

.Fd ioctl (fd, POWIOCGPOWERINFO, &powerinfo);
.Fd struct x68k_powerinfo powerinfo;
.Ed
.Pp
Returns the power switch status etc. in the following structure.
.Bd -literal -offset indent
struct x68k_powerinfo {
	int pow_switch_boottime;
	int pow_switch_current;
	time_t pow_boottime;
	unsigned int pow_bootcount;
	time_t pow_usedtotal;
};
.Ed
.Pp
Each member means:
.Bl -hang -compact
.It pow_switch_boottime:
The power switch status at the system start time.
The status is known by applying logical and (&) with:

.Bl -tag -compact -width POW_EXTERNALSW
.It POW_ALARMSW
True if the system started by the RTC alarm timer
.It POW_EXTERNALSW
True if the EXPWON signal of the I/O slot is on
.It POW_FRONTSW
True if the front power switch is on
.El

EXPWON-related information is not tested.

.It pow_switch_current:
Current power switch status. See above.

.It pow_boottime:
The time when NetBSD started.

.It pow_bootcount:
.It pow_usedtotal:
Host's boot information from the system memory switch.
Total usage in count (pow_bootcount) and second (pow_usedtotal).
.El
.Sh ACCESSING RTC ALARM TIMER
.Bd -literal
.Fd #include <sys/ioctl.h>
.Fd #include <machine/powioctl.h>

.Fd ioctl (fd, POWIOCGALARMINFO, &alarminfo);
.Fd struct x68k_alarminfo alarminfo;
.Ed
.Pp
Returns x68k's alarm timer information in the following structure.
.Bd -literal -offset indent
struct x68k_alarminfo {
	int al_enable;
	unsigned int al_ontime;
	int al_dowhat;
	time_t al_offtime;
};
.Ed
.Pp
Each of the members means:
.Bl -hang
.It al_enable:
True if the alarm timer is enable.
.It al_ontime:
Internal expression of the alarm timer. See `C Compiler PRO-68K Programmers' Manual'
Chapter 3 Section ALARMSET.
.It al_dowhat:
What to do when started by the alarm timer.
See `Programers' manual'.
.It al_offtime:
Display the time in seconds since the alarm is activated until
the power is turned off (though the resolution
is resolved to minutes). Be cautious when using IOCS
and the like as these require minute time units. 0 indicates an infinity.
.El

.Bd -literal
.Fd ioctl (fd, POWIOCSALARMINFO, &alarminfo);
.Fd struct x68k_alarminfo alarminfo;
.Ed
.Pp
Sets the alarm timer according to the argument
.Ar alarminfo
(see above).
.Pp
.Sh SIGNAL
.Bd -literal
.Fd #include <sys/ioctl.h>
.Fd #include <machine/powioctl.h>

.Fd ioctl (fd, POWIOCSSIGNAL, &signum);
.Fd int signum;
.Ed
.Pp
Signal
.Ar signum
is sent when the state of the power switch
(front or external) changes. It becomes invalid when
.Xr close 2
is called.
Note that this function is not provided with
.Pa /dev/pow1 .
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr poffd 8 ,
.Xr rtcalarm 8
.Rs
`C Compiler PRO-68K Programmers' Manual', Chapter 3 IOCS Calls, Section ALARMSET, Sharp
.Re
.Sh AUTHOR
Minoura Makoto <minoura@flab.fujitsu.co.jp>.
.Sh SPECIAL THANKS
Liam Hahne Minn <hahne@sail.t.u-tokyo.ac.jp>.
.Sh BUGS
The file
.Pa /dev/pow
can only be opened by one process at a time.