first attempt to consolidate some of the apm/acpi documentation.

ok deraadt

3 files changed, 232 insertions, 4 deletions

diff --git a/share/man/man4/acpi.4 b/share/man/man4/acpi.4
index 04b63d4c31b..6dba0f01e94 100644
--- a/share/man/man4/acpi.4
+++ b/share/man/man4/acpi.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: acpi.4,v 1.24 2007/11/16 02:14:48 deraadt Exp $
+.\"	$OpenBSD: acpi.4,v 1.25 2007/11/28 12:58:30 tedu Exp $
 .\"
 .\" Copyright (c) 2006 Alexander Yurchenko <grange@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: November 16 2007 $
+.Dd $Mdocdate: November 28 2007 $
 .Dt ACPI 4
 .Os
 .Sh NAME
@@ -35,6 +35,11 @@ If the configuration option
 .Dq Dv ACPIVERBOSE
 is set, information about all detected ACPI devices will be displayed
 on boot.
+Userland may access
+.Nm
+by using the
+.Xr apm 4
+device.
 .Pp
 The following devices can attach to
 .Nm :
@@ -64,6 +69,7 @@ ACPI power management timer
 ACPI thermal zone
 .El
 .Sh SEE ALSO
+.Xr apm 4
 .Xr intro 4
 .Sh HISTORY
 The
diff --git a/share/man/man4/man4.amd64/apm.4 b/share/man/man4/man4.amd64/apm.4
new file mode 100644
index 00000000000..bdc2a19e5df
--- /dev/null
+++ b/share/man/man4/man4.amd64/apm.4
@@ -0,0 +1,221 @@
+.\"	$OpenBSD: apm.4,v 1.1 2007/11/28 12:58:30 tedu Exp $
+.\"
+.\"	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: November 28 2007 $
+.Dt APM 4 i386
+.Os
+.Sh NAME
+.Nm apm
+.Nd power management interface
+.Sh SYNOPSIS
+.Cd "acpi0 at mainbus?"
+.Sh DESCRIPTION
+The
+.Nm
+driver provides a user interface to the
+.Xr acpi 4
+driver.
+.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_REJECT
+.Em Not implemented . DO NOT USE .
+.It Dv APM_IOC_STANDBY
+.Pq Li "no parameters"
+Request
+.Dq standby
+mode.
+.It Dv APM_IOC_SUSPEND
+.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 contains the estimated number of minutes of battery life
+remaining.
+.It Dv APM_IOC_NEXTEVENT
+.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:
+.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
+.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
+.Tn APM
+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 -compact
+.It Pa /dev/apm
+.Tn APM
+data device.
+May only be opened read-only.
+May be opened by multiple concurrent users.
+.It Pa /dev/apmctl
+.Tn 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 acpi 4 ,
+.Xr intro 4 ,
+.Xr sysctl.conf 5 ,
+.Xr apm 8 ,
+.Xr apmd 8 ,
+.Xr halt 8 ,
+.Xr sysctl 8
diff --git a/share/man/man4/man4.i386/apm.4 b/share/man/man4/man4.i386/apm.4
index d9fbf05f605..8077ad89eed 100644
--- a/share/man/man4/man4.i386/apm.4
+++ b/share/man/man4/man4.i386/apm.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: apm.4,v 1.26 2007/05/31 19:19:54 jmc Exp $
+.\"	$OpenBSD: apm.4,v 1.27 2007/11/28 12:58:30 tedu Exp $
 .\"
 .\"	Copyright (c) 1998 Marco S. Hyman
 .\"
@@ -9,7 +9,7 @@
 .\"	LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 .\"	FOR A PARTICULAR PURPOSE.
 .\"
-.Dd $Mdocdate: May 31 2007 $
+.Dd $Mdocdate: November 28 2007 $
 .Dt APM 4 i386
 .Os
 .Sh NAME
@@ -272,6 +272,7 @@ An attempt to open the file when in use will fail, returning
 .Er EBUSY .
 .El
 .Sh SEE ALSO
+.Xr acpi 4 ,
 .Xr intro 4 ,
 .Xr sysctl.conf 5 ,
 .Xr apm 8 ,