472351e13d
.In header.h instead of .Fd #include \*[Lt]header.h\*[Gt] Much easier to read and write, and supported by groff for ages. Okayed by ross.
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.16 2003/04/16 13:35:21 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 '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 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 .
|