Add new apm(4) man page for zaurus based on macppc, and add zaurus to

MANSUBDIR for apm(8).
ok deraadt@

2 files changed, 311 insertions, 2 deletions

diff --git a/share/man/man4/man4.zaurus/Makefile b/share/man/man4/man4.zaurus/Makefile
index fb226b686cd..af8e3a81cb8 100644
--- a/share/man/man4/man4.zaurus/Makefile
+++ b/share/man/man4/man4.zaurus/Makefile
@@ -1,7 +1,7 @@
-#	$OpenBSD: Makefile,v 1.3 2005/01/15 17:30:39 miod Exp $
+#	$OpenBSD: Makefile,v 1.4 2005/02/21 21:59:40 uwe Exp $
 
 # TODO: aupxa(eventually) cpu
-MAN=	autoconf.4 intro.4 lcd.4 mem.4 \
+MAN=	apm.4 autoconf.4 intro.4 lcd.4 mem.4 \
 	pxagpio.4 pxaintc.4 pxaip.4 pxapcic.4 saost.4 zkbd.4
 
 MLINKS+= mem.4 kmem.4
diff --git a/share/man/man4/man4.zaurus/apm.4 b/share/man/man4/man4.zaurus/apm.4
new file mode 100644
index 00000000000..a4e5086f510
--- /dev/null
+++ b/share/man/man4/man4.zaurus/apm.4
@@ -0,0 +1,309 @@
+.\"	$OpenBSD: apm.4,v 1.1 2005/02/21 21:59:40 uwe 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 February 21, 2005
+.Dt APM 4 zaurus
+.Os
+.Sh NAME
+.Nm apm
+.Nd advanced power management device interface
+.Sh SYNOPSIS
+.Cd "apm0 at pxaip?"
+.Sh DESCRIPTION
+The
+.Nm
+driver provides an interface which simulates the Advanced Power Management
+.Pq Tn APM
+.Tn BIOS
+functions.
+The
+.Tn BIOS
+functions are translated into the appropriate Power Manager requests.
+Currently only battery level, AC connection, and charging status is available
+from the
+.Nm
+device.
+Suspend mode is
+.Ud .
+Standby and other power events are
+.Em NOT YET SUPPORTED .
+.Pp
+Configuration options:
+.Pp
+.Bl -tag -width DIAGNOSTIC -compact -offset indent
+.It Dv APMDEBUG
+Enable various driver status messages.
+.It Dv DIAGNOSTIC
+Enable debugging messages.
+.It Dv DEBUG
+Enable other debugging messages.
+.El
+.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
+.Pq Li "struct apm_event_info"
+.Em Not implemented . DO NOT USE .
+.It Dv APM_IOC_STANDBY
+.Em NOT YET SUPPORTED on zaurus
+.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
+If the battery is charging, i.e. when
+.Va battery_state
+is equal to
+.Dv APM_BATT_CHARGING ,
+the
+.Va battery_life
+value is invalid.
+Otherwise, the
+.Va minutes_left
+value contains the estimated number of minutes of battery life
+remaining.
+If no time estimate is available, the
+.Va minutes_left
+value is 0.
+(See also
+.Sx BUGS ,
+below.)
+.It Dv APM_IOC_NEXTEVENT
+.Em NOT YET SUPPORTED on zaurus
+.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 zaurus
+.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
+.Em NOT YET SUPPORTED on zaurus
+.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
+.Pp
+.Em NOT YET SUPPORTED on zaurus:
+As noted above, the operation of the
+.Tn APM
+driver can be modified using the
+.Dv machdep.apmwarn
+.Xr sysctl 8
+variable.
+Another driver modifier is the
+.Dv machdep.apmhalt
+variable.
+When
+.Dv machdep.apmhalt
+is set to 1 the
+.Tn APM
+power down code is modified in a way necessary for correct operation on
+some systems, mainly
+.Tn IBM
+laptops.
+If your system does not power down when given the command
+.Li "halt -p"
+try setting
+.Dv machdep.apmhalt
+to 1 using
+.Xr sysctl 8 .
+The variable can be set at boot time in
+.Xr sysctl.conf 5 .
+.Sh FILES
+.Bl -tag -width /dev/apmctl
+.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 adb 4 ,
+.Xr intro 4 ,
+.Xr sysctl.conf 5 ,
+.Xr apm 8 ,
+.Xr apmd 8 ,
+.Xr halt 8 ,
+.Xr sysctl 8
+.Sh HISTORY
+The
+.Nm
+driver source code contains these copyrights:
+.Pp
+.Bl -item -compact
+.It
+.Li Copyright (c) 1995 John T. Kohl.  All rights reserved.
+.It
+.Li Copyright (C) 1994 by HOSOKAWA Tatsumi <hosokawa@mt.cs.keio.ac.jp>
+.El
+.Pp
+\&...and has been hacked on by many others since.
+.Sh BUGS
+Standby mode and power events are not supported.
+.Pp
+If the battery is charging, the battery life remaining is incorrectly
+reported as 100% until charging is complete.
+The estimated number of minutes left is constantly 0 minutes.