man page for apm(4)

2 files changed, 262 insertions, 2 deletions

diff --git a/share/man/man4/man4.loongson/Makefile b/share/man/man4/man4.loongson/Makefile
index 48d4370b23b..20430277bb9 100644
--- a/share/man/man4/man4.loongson/Makefile
+++ b/share/man/man4/man4.loongson/Makefile
@@ -1,6 +1,6 @@
-#	$OpenBSD: Makefile,v 1.5 2010/02/24 22:16:16 miod Exp $
+#	$OpenBSD: Makefile,v 1.6 2010/02/28 08:52:32 otto Exp $
 
-MAN=	autoconf.4 bonito.4 gdiumiic.4 glxpcib.4 intro.4 \
+MAN=	apm.4 autoconf.4 bonito.4 gdiumiic.4 glxpcib.4 intro.4 \
 	mem.4 mfokclock.4 smfb.4 stsec.4 voyager.4 ykbec.4
 MANSUBDIR=loongson
 
diff --git a/share/man/man4/man4.loongson/apm.4 b/share/man/man4/man4.loongson/apm.4
new file mode 100644
index 00000000000..508470dbad8
--- /dev/null
+++ b/share/man/man4/man4.loongson/apm.4
@@ -0,0 +1,260 @@
+.\"     $OpenBSD: apm.4,v 1.1 2010/02/28 08:52:32 otto Exp $
+.\"
+.\" Copyright (c) 1999 Jason L. Wright (jason@thought.net)
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" APM description:
+.\"
+.\"	Copyright (c) 1998 Marco S. Hyman
+.\"
+.\"	Permission to copy all or part of this material for any purpose is
+.\"	granted provided that the above copyright notice and this paragraph
+.\"	are duplicated in all copies.  THIS SOFTWARE IS PROVIDED ``AS IS''
+.\"	AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
+.\"	LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\"	FOR A PARTICULAR PURPOSE.
+.Dd $Mdocdate: February 28 2010 $
+.Dt APM 4 loongson
+.Os
+.Sh NAME
+.Nm apm
+.Nd advanced power management device interface
+.Sh SYNOPSIS
+.Cd "apm0 at mainbus0"
+.Sh DESCRIPTION
+The
+.Nm
+driver provides generic power and battery control,
+relying on device specific drivers to provide the actual information.
+.Pp
+The
+.Nm
+driver provides an interface which simulates the Advanced Power Management
+.Pq Tn APM
+BIOS functions encountered on some x86 hardware.
+The BIOS functions are translated into the appropriate microcontroller requests
+by the hardware specific drivers, like
+.Xr ykbec 4 .
+Currently only battery level, AC connection, and charging status are available
+from the
+.Nm
+device.
+Suspend/resume and other power events are not yet supported.
+.Pp
+The
+.Nm
+driver implements the following
+.Xr ioctl 2
+calls.
+They are defined in
+.Aq Pa machine/apmvar.h .
+.Bl -tag -width Ds
+.\" .It Dv APM_IOC_STANDBY
+.\" .Em NOT YET SUPPORTED on loongson
+.\" .Pq Li "no parameters"
+.\" Request
+.\" .Dq standby
+.\" mode.
+.\" .It Dv APM_IOC_SUSPEND
+.\" .Em NOT YET SUPPORTED on loongson
+.\" .Pq Li "no parameters"
+.\" Request
+.\" .Dq suspend
+.\" mode.
+.It Dv APM_IOC_GETPOWER
+.Pq Li "struct apm_power_info"
+Request the current power state.
+The argument structure is as follows:
+.Bd -literal -offset indent
+struct apm_power_info {
+	u_char battery_state;
+	u_char ac_state;
+	u_char battery_life;
+	u_char spare1;
+	u_int minutes_left;
+	u_int spare2[6];
+};
+.Ed
+.Pp
+The following values are defined for
+.Va battery_state :
+.Bl -tag -width Ds
+.It Dv APM_BATT_HIGH
+Battery has a high state of charge.
+.It Dv APM_BATT_LOW
+Battery has a low state of charge.
+.It Dv APM_BATT_CRITICAL
+Battery has a critical state of charge.
+.It Dv APM_BATT_CHARGING
+Battery is not high, low, or critical and is currently charging.
+.It Dv APM_BATT_UNKNOWN
+Can not read the current battery state.
+.It Dv APM_BATTERY_ABSENT
+No battery installed.
+.El
+.Pp
+The following values are defined for
+.Va ac_state :
+.Bl -tag -width Ds
+.It Dv APM_AC_OFF
+External power not detected.
+.It Dv APM_AC_ON
+External power detected.
+.\" .It Dv APM_AC_BACKUP
+.\" Backup power in use.
+.\" .It Dv APM_AC_UNKNOWN
+.\" External power state unknown.
+.El
+.Pp
+The
+.Va battery_life
+value contains the estimated percentage of battery life available.
+100% indicates a full charge.
+.Pp
+The
+.Va minutes_left
+value is always -1,
+as the hardware does not provide an estimated number of minutes of
+battery life remaining.
+.\" .It Dv APM_IOC_NEXTEVENT
+.\" .Em NOT YET SUPPORTED on loongson
+.\" .Pq Li "struct apm_event_info"
+.\" The
+.\" .Tn APM
+.\" driver stores up to
+.\" .Dv APM_NEVENTS
+.\" events.
+.\" This was defined as 16 at the time this documentation was written.
+.\" If the event list is full when a new event is detected the new event is lost.
+.\" .Dv APM_IOC_NEXTEVENT
+.\" ioctl returns the next event on the list or
+.\" .Er EAGAIN
+.\" if the event list is empty.
+.\" The format of the returned event is:
+.\" .Bd -literal -offset indent
+.\" struct apm_event_info {
+.\"	u_int type;
+.\"	u_int index;
+.\"	u_int spare[8];
+.\" };
+.\" .Ed
+.\" where
+.\" .Va index
+.\" is a sequential count of events that can be used to check if any
+.\" events were lost and
+.\" .Va type
+.\" is one of:
+.\" .Pp
+.\" .Bl -tag -width Ds -offset indent -compact
+.\" .It Dv APM_STANDBY_REQ
+.\" .It Dv APM_SUSPEND_REQ
+.\" .It Dv APM_NORMAL_RESUME
+.\" .It Dv APM_CRIT_RESUME
+.\" .It Dv APM_BATTERY_LOW
+.\" .It Dv APM_POWER_CHANGE
+.\" .It Dv APM_UPDATE_TIME
+.\" .It Dv APM_CRIT_SUSPEND_REQ
+.\" .It Dv APM_USER_STANDBY_REQ
+.\" .It Dv APM_USER_SUSPEND_REQ
+.\" .It Dv APM_SYS_STANDBY_RESUME
+.\" .El
+.\" .It Dv APM_IOC_DEV_CTL
+.\" .Em NOT YET SUPPORTED on loongson
+.\" .Pq Li "struct apm_ctl"
+.\" Allows an application to directly set the
+.\" .Tm APM
+.\" operating mode.
+.\" The argument structure is as follows:
+.\" .Bd -literal -offset indent
+.\" struct apm_ctl {
+.\"	u_int dev;
+.\"	u_int mode;
+.\" };
+.\" .Ed
+.\" .Pp
+.\" .Va dev
+.\" indicates the device, typically
+.\" .Dv APM_DEV_ALLDEVS .
+.\" .Pp
+.\" .Va mode
+.\" indicates the desired operating mode.
+.\" Possible values are
+.\" .Bl -tag -compact -offset indent
+.\" .It Dv APM_SYS_READY
+.\" .It Dv APM_SYS_STANDBY
+.\" .It Dv APM_SYS_SUSPEND
+.\" .It Dv APM_SYS_OFF
+.\" .It Dv APM_LASTREQ_INPROG
+.\" .It Dv APM_LASTREQ_REJECTED
+.\" .El
+.It Dv APM_IOC_PRN_CTL
+.Pq Li "int"
+This
+.Xr ioctl 2
+controls message output by the
+.Nm
+driver when a power change event is detected.
+The integer parameter is one of:
+.Bl -tag -width Ds
+.It Dv APM_PRINT_ON
+All power change events result in a message.
+This is the normal operating mode for the driver.
+.It Dv APM_PRINT_OFF
+Power change event messages are suppressed.
+.It Dv APM_PRINT_PCT
+Power change event messages are suppressed unless the estimated
+battery life percentage changes.
+.El
+.\" .Pp
+.\" However, in no case will power status messages be displayed until the
+.\" battery life goes below the percentage in the
+.\" .Xr sysctl 8
+.\" state variable
+.\" .Dv machdep.apmwarn .
+.\" Setting
+.\" .Dv machdep.apmwarn
+.\" to zero disables all warnings regardless of the
+.\" .Dv APM_IOC_PRN_CTL
+.\" setting.
+.El
+.Sh FILES
+.Bl -tag -width /dev/apmctl
+.It Pa /dev/apm
+APM data device.
+May only be opened read-only.
+May be opened by multiple concurrent users.
+.It Pa /dev/apmctl
+APM control device.
+May be opened read-write or write-only.
+May only be opened by one user at a time.
+An attempt to open the file when in use will fail, returning
+.Er EBUSY .
+.El
+.Sh SEE ALSO
+.Xr intro 4 ,
+.Xr ykbec 4 ,
+.Xr apm 8 ,
+.Xr apmd 8
+.Sh BUGS
+Suspend and resume are not supported.