APM(4) OpenBSD Programmer's Manual (i386) APM(4)
NAME
apm - advanced power management device interface
SYNOPSIS
apm0 at bios0 flags 0x0000
DESCRIPTION
The apm driver provides an interface to the Advanced Power Management
(APM) BIOS functions. The driver supports versions 1.0, 1.1, and 1.2 in-
terface specifications.
The low two bytes of the flags specify the version of the specification
driver should conform to in binary decimal notation. The value of 0x0101
would specify version 1.1 of the interface specification to be used.
The value of 0x10000 specifies whether to leave interrupts enabled when
calling APM BIOS routines. This is needed for some IBM laptops, the
symptoms are hangs and freezes on suspend, stand by, and hibernation ac-
tivities.
The value of 0x20000 specifies to swap the bytes of the battery life es-
timation (the DX register) as given from the APM BIOS. This is needed
for some SONY VAIO laptops, such as some 505 models.
Configuration options:
APMDEBUG Enable various driver status messages.
DIAGNOSTIC Enable debugging messages.
DEBUG Enable other debugging messages.
The apm driver implements the following ioctl(2) calls. They are defined
in <machine/apmvar.h>.
APM_IOC_REJECT
Not implemented. DO NOT USE.
APM_IOC_STANDBY
(no parameters) Request ``standby'' mode.
APM_IOC_SUSPEND
(no parameters) Request ``suspend'' mode.
APM_IOC_GETPOWER
(struct apm_power_info) Request the current power state. The ar-
gument structure is as follows:
struct apm_power_info {
u_char battery_state;
u_char ac_state;
u_char battery_life;
u_char spare1;
u_int minutes_left;
u_int spare2[6];
};
The following values are defined for battery_state:
APM_BATT_HIGH
Battery has a high state of charge.
APM_BATT_LOW
Battery has a low state of charge.
APM_BATT_CRITICAL
Battery has a critical state of charge.
APM_BATT_CHARGING
Battery is not high, low, or critical and is currently
charging.
APM_BATT_UNKNOWN
Can not read the current battery state.
APM_BATTERY_ABSENT
No battery installed.
The following values are defined for ac_state:
APM_AC_OFF
External power not detected.
APM_AC_ON
External power detected.
APM_AC_BACKUP
Backup power in use.
APM_AC_UNKNOWN
External power state unknown.
The battery_life value contains the estimated percentage of bat-
tery life available. 100% indicates a full charge.
The minutes_left value contains the estimated number of minutes
of battery life remaining.
APM_IOC_NEXTEVENT
(struct apm_event_info) The APM driver stores up to APM_NEVENTS
events. This was defined as 16 at the time this documentation
was written. If the event list is full when a new event is de-
tected the new event is lost. APM_IOC_NEXTEVENT ioctl returns
the next event on the list or EAGAIN if the event list is empty.
The format of the returned event is:
struct apm_event_info {
u_int type;
u_int index;
u_int spare[8];
};
where index is a sequential count of events that can be used to
check if any events were lost and type is one of:
APM_STANDBY_REQ
APM_SUSPEND_REQ
APM_NORMAL_RESUME
APM_CRIT_RESUME
APM_BATTERY_LOW
APM_POWER_CHANGE
APM_UPDATE_TIME
APM_CRIT_SUSPEND_REQ
APM_USER_STANDBY_REQ
APM_USER_SUSPEND_REQ
APM_SYS_STANDBY_RESUME
APM_IOC_DEV_CTL
(struct apm_ctl) Allows an application to directly set the oper-
ating mode. The argument structure is as follows:
struct apm_ctl {
u_int dev;
u_int mode;
};
dev indicates the device, typically APM_DEV_ALLDEVS.
mode indicates the desired operating mode. Possible values are
APM_SYS_READY
APM_SYS_STANDBY
APM_SYS_SUSPEND
APM_SYS_OFF
APM_LASTREQ_INPROG
APM_LASTREQ_REJECTED
APM_IOC_PRN_CTL
(int) This ioctl(2) controls message output by the APM driver
when a power change event is detected. The integer parameter is
one of:
APM_PRINT_ON
All power change events result in a message. This is the
normal operating mode for the driver.
APM_PRINT_OFF
Power change event messages are suppressed.
APM_PRINT_PCT
Power change event messages are suppressed unless the es-
timated battery life percentage changes.
However, in no case will power status messages be displayed until
the battery life goes below the percentage in the sysctl(8) state
variable machdep.apmwarn. Setting machdep.apmwarn to zero dis-
ables all warnings regardless of the APM_IOC_PRN_CTL setting.
As noted above, the operation of the APM driver can be modified using the
machdep.apmwarn sysctl(8) variable. Another driver modifier is the
machdep.apmhalt variable. When machdep.apmhalt is set to 1 the APM power
down code is modified in a way necessary for correct operation on some
systems, mainly IBM laptops. If your system does not power down when
given the command halt -p try setting machdep.apmhalt to 1 using
sysctl(8). The variable can be set at boot time in sysctl.conf(5).
FILES
/dev/apm APM data device. May only be opened read-only. May be
opened by multiple concurrent users.
/dev/apmctl APM control device. May be opened read-write or write-only.
May only be opened by one user at a time. An attempt to
open the file when in use will fail, returning EBUSY.
SEE ALSO
intro(4), sysctl.conf(5), apm(8), apmd(8), halt(8), sysctl(8)
HISTORY
The apm driver source code contains these copyrights:
Copyright (c) 1995 John T. Kohl. All rights reserved.
Copyright (C) 1994 by HOSOKAWA Tatsumi <hosokawa@mt.cs.keio.ac.jp>
...and has been hacked on by many others since.
BUGS
Not all the BIOSes support power down the way we are attempting to exe-
cute it.
Not all BIOS vendors even read the specification.
OpenBSD 4.2 May 31, 2007 3