.\" Copyright (c) 1995,1996 John T. Kohl
.\" 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. 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.
.\"   
.\"   $NetBSD: apm.4,v 1.1 1996/08/25 23:39:11 jtk Exp $
.\"
.Dd May 18, 1996
.Dt APM 4 i386
.Os 
.Sh NAME
.Nm apm
.Nd
Advanced Power Management pseudo-device driver
.Sh SYNOPSIS
.Cd "apm0 at mainbus0"
.Fd #include <machine/apmvar.h>
.Pa /dev/apm
.Sh DESCRIPTION
The
.Nm apm
driver provides support for the Advanced Power Managment features of
some i386 system BIOSes.  The driver supports the Advanced Power
Management (APM) BIOS Interface Specification (revision 1.1), published
jointly by the Intel Corporation and the Microsoft Corporation.
.Pp
The boot loader connects to the APM bios while the system is still
operating in i386 real mode, and places the APM bios into 32-bit
protected mode operation.  The
NetBSD
kernel start-up routines establish the 32-bit protected mode connection
to the APM BIOS.
.Pp
The APM driver may be adjusted with several configuration options:
.Bl -tag -width indent -compact
.It Dv APM_NOIDLE
Do not call the BIOS CPU idle function from the system idle loop.  (Some
systems will hang on certain device accesses, such as sound cards or
floppy diskette drives, without this option)
.It Dv APM_V10_ONLY
Use only the APM revision 1.0 specification calls.  (Some systems do not
implement APM v1.1 very well, and generate weird events instead of the
expected events when the system suspend key is pressed.)
.It Dv APM_NO_POWEROFF
Do not attempt to turn off power when halting the system.
.It Dv APM_FORCE_64KSEG
Force the length of the APM BIOS code and data segments to 64KB.
.It Dv APMDEBUG
Enable kernel printout of events received from the APM BIOS.
.It Dv APMCALLDEBUG
Enable kernel printout of every call to the APM BIOS (this is very noisy).
.El
.Pp
If no processes are holding open file descriptors to the APM device, the
driver will process the APM BIOS events itself.  If a process has the
device open for write, the driver defers all suspend and standby
processing to the user process as long as there is sufficient queue
space to store the event for the process.  If the device is only open
for read, the driver will report events but handle them itself.
.Pp
The APM device may be opened by multiple readers but only one
writer. Multiple readers may fetch the status with
.Xr ioctl 2
without worrying about interference, but they must cooperate to share
events as only a single event queue is provided.  The device may only be
.Xr select 2 ed
or manipulated with
.Xr ioctl 2 ;
.Xr read 2
and
.Xr write 2
are not supported.
The 
.Xr ioctl 2
calls supported are:
.Bl -tag -width indent -compact
.It Dv APM_IOC_STANDBY
initiate an APM standby mode.  This is a deep sleep mode which powers down
most devices.  The device must be open for writing for this command to succeed
.
.It Dv APM_IOC_SUSPEND
initiate an APM suspend mode.  This is a light sleep mode from which the
system can quickly restore normal operation.  The device must be open
for writing for this command to succeed.
.It Dv APM_IOC_GETPOWER
Fetch the current power status into an
.Va apm_power_info
structure.
.Bd -literal
struct apm_power_info {
      u_char battery_state;
      u_char ac_state;
      u_char battery_life;
      u_char spare1;
      u_int minutes_left;             /* estimate */
      u_int spare2[6];
};
.Ed
.Va battery_state
is one of 
.Dv APM_BATT_HIGH ,
.Dv APM_BATT_LOW ,
.Dv APM_BATT_CRITICAL ,
.Dv APM_BATT_CHARGING ,
or
.Dv APM_BATT_UNKNOWN .
.Va ac_state
is one of 
.Dv APM_AC_OFF ,
.Dv APM_AC_ON ,
.Dv APM_AC_BACKUP ,
or
.Dv APM_AC_UNKNOWN .
.Va battery_life
is the percentage estimated remaining normal battery life (or 0 if the
BIOS cannot provide an estimate).
.Va minutes_left
is an estimated remaining lifetime (or 0 if the BIOS cannot provide an
estimate).
.It Dv APM_IOC_NEXTEVENT
Fetch the next event from the APM BIOS into an
.Va apm_event_info
structure.  If no more events are ready, this will return
.Dv EAGAIN .
.Bd -literal
struct apm_event_info {
      u_int type;
      u_int index;
      u_int spare[8];
};
.Ed
.Va type
is one of the APM event types (APM_STANDBY_REQ through
APM_SYS_STANDBY_RESUME).
.Va index
is the ordinal event sequence number.
.El
.Sh SEE ALSO
.Xr apmd 8
.Sh REFERENCES
Advanced Power Management (APM) BIOS Interface Specification (Revision
1.1), Intel Corporation and Microsoft Corporation.  Intel order number
241704-001; Microsoft part number 781-110-X01.
.Sh HISTORY
The
.Nm apm
pseudo-device driver appeared in NetBSD-current.