220 lines
7.4 KiB
Groff
220 lines
7.4 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.17 2003/06/27 18:27:58 wiz 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"
|
|
.In machine/apmvar.h
|
|
.Pa /dev/apm
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm apm
|
|
driver provides support for the Advanced Power Management features of
|
|
some i386 system BIOSes. The driver supports the Advanced Power
|
|
Management (APM) BIOS Interface Specification (revision 1.2), published
|
|
jointly by the Intel Corporation and the Microsoft Corporation.
|
|
.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_V12
|
|
Don't attach to the BIOS as APM v1.2 compliant device.
|
|
(In case there are problems with v1.2 support.)
|
|
.It Dv APM_NO_STANDBY
|
|
Do not attempt to put the system into standby mode.
|
|
.It Dv APM_NO_POWEROFF
|
|
Do not attempt to turn off power when halting the system.
|
|
.It Dv APM_FORCE_64K_SEGMENTS
|
|
Force the length of the APM BIOS code and data segments to 64KB.
|
|
.It Dv APM_ALLOW_BOGUS_SEGMENTS
|
|
Allow the use of data segments which are in unexpected locations.
|
|
.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).
|
|
.It Dv APM_POWER_PRINT
|
|
Print power state on console at
|
|
.Dv APM_POWER_CHANGE
|
|
events. (Since it increases
|
|
.Xr syslogd 8 Ns 's
|
|
activity, it may consume increased
|
|
battery power. Some systems generate the events too frequently,
|
|
and printing the status may disturb single-user operations.)
|
|
.It Dv APM_DISABLE_INTERRUPTS
|
|
Set this to zero if you don't want the kernel to disable interrupts
|
|
before calling the BIOS. This is required for most IBM ThinkPads, and
|
|
some other newer laptops. A good indication that you need this is that
|
|
the machine hangs just after resuming from suspended state. It's
|
|
unclear if doing this has negative effects on older BIOS, therefore it
|
|
defaults to one (i.e interrupts are disabled).
|
|
.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 Ns 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 nbattery;
|
|
u_int batteryid;
|
|
u_int spare2[4];
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The structure should be zeroed (except for
|
|
.Va batteryid )
|
|
before
|
|
being passed.
|
|
.Pp
|
|
.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 .
|
|
.Pp
|
|
.Va ac_state
|
|
is one of
|
|
.Dv APM_AC_OFF ,
|
|
.Dv APM_AC_ON ,
|
|
.Dv APM_AC_BACKUP ,
|
|
or
|
|
.Dv APM_AC_UNKNOWN .
|
|
.Pp
|
|
.Va battery_life
|
|
is the percentage estimated remaining normal battery life (or 0 if the
|
|
BIOS cannot provide an estimate).
|
|
.Pp
|
|
.Va minutes_left
|
|
is an estimated remaining lifetime (or 0 if the BIOS cannot provide an
|
|
estimate).
|
|
.Pp
|
|
.Va nbattery
|
|
is the number of batteries in the system. If the system is using APM
|
|
v1.1 or earlier, nbattery will always return 0.
|
|
.Pp
|
|
Batteries are numbered from a base of 1.
|
|
If the passed value of
|
|
.Va batteryid
|
|
is 0, the returned values will reflect the percentage remaining, minutes
|
|
left, etc. of all of the system's batteries taken together.
|
|
If the passed value of
|
|
.Va batteryid
|
|
is nonzero, the return values will reflect the indicated
|
|
battery's percentage remaining, minutes left, etc.
|
|
It is an error to set
|
|
.Va batteryid
|
|
to a value greater than that returned by
|
|
.Va nbattery .
|
|
If the system is using APM v1.1 or earlier, individual batteries
|
|
cannot be queried, and
|
|
.Va nbattery
|
|
will always return 0.
|
|
.Va batteryid
|
|
is always set to the passed value upon return.
|
|
.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 .
|