NAME
apm —
Advanced Power Management
pseudo-device driver
SYNOPSIS
apm0 at mainbus0
#include <machine/apmvar.h>
/dev/apm
DESCRIPTION
The
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.
The APM driver's behavior may be adjusted by specifying any of the following
kernel configuration options:
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)
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.)
APM_NO_V12
- Don't attach to the BIOS as APM v1.2 compliant device. (In
case there are problems with v1.2 support.)
APM_NO_STANDBY
- Do not attempt to put the system into standby mode.
APM_NO_POWEROFF
- Do not attempt to turn off power when halting the
system.
APM_FORCE_64K_SEGMENTS
- Force the length of the APM BIOS code and data segments to
64KB.
APM_ALLOW_BOGUS_SEGMENTS
- Allow the use of data segments which are in unexpected
locations.
APMDEBUG
- Enable kernel printout of events received from the APM
BIOS.
APMCALLDEBUG
- Enable kernel printout of every call to the APM BIOS (this
is very noisy).
APM_POWER_PRINT
- Print power state on console at
APM_POWER_CHANGE
events. (Since it increases
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.)
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).
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.
The APM device may be opened by multiple readers but only one writer. Multiple
readers may fetch the status with
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
select(2)ed or manipulated
with
ioctl(2);
read(2) and
write(2) are not supported.
The
ioctl(2) calls supported
are:
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.
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.
APM_IOC_GETPOWER
- Fetch the current power status into an
apm_power_info structure.
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];
};
The structure should be zeroed (except for batteryid)
before being passed.
battery_state is one of
APM_BATT_HIGH
,
APM_BATT_LOW
,
APM_BATT_CRITICAL
,
APM_BATT_CHARGING
, or
APM_BATT_UNKNOWN
.
ac_state is one of APM_AC_OFF
,
APM_AC_ON
, APM_AC_BACKUP
,
or APM_AC_UNKNOWN
.
battery_life is the percentage estimated remaining
normal battery life (or 0 if the BIOS cannot provide an estimate).
minutes_left is an estimated remaining lifetime (or 0
if the BIOS cannot provide an estimate).
nbattery is the number of batteries in the system. If
the system is using APM v1.1 or earlier, nbattery will always return 0.
Batteries are numbered from a base of 1. If the passed value of
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 batteryid is
nonzero, the return values will reflect the indicated battery's percentage
remaining, minutes left, etc. It is an error to set
batteryid to a value greater than that returned by
nbattery. If the system is using APM v1.1 or
earlier, individual batteries cannot be queried, and
nbattery will always return 0.
batteryid is always set to the passed value upon
return.
APM_IOC_NEXTEVENT
- Fetch the next event from the APM BIOS into an
apm_event_info structure. If no more events are
ready, this will return
EAGAIN
.
struct apm_event_info {
u_int type;
u_int index;
u_int spare[8];
};
type is one of the APM event types (APM_STANDBY_REQ
through APM_SYS_STANDBY_RESUME). index is the
ordinal event sequence number.
SEE ALSO
apmd(8)
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.
HISTORY
The
apm pseudo-device driver appeared in
NetBSD 1.3.