170 lines
5.8 KiB
Groff
170 lines
5.8 KiB
Groff
.\" 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.5 1999/04/15 01:01:17 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
|
|
.Nx
|
|
kernel start-up routines establish the 32-bit protected mode connection
|
|
to the APM BIOS.
|
|
.Pp
|
|
The APM driver's behavior may be adjusted by specifying any of the
|
|
following kernel configuration options:
|
|
.Bl -tag -width indent -compact
|
|
.It Dv APM_NO_IDLE
|
|
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_SUSPEND
|
|
Initiate an APM suspend 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_STANDBY
|
|
Initiate an APM standby 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
|
|
.Nx 1.3 .
|