apm(4) - NetBSD Manual Pages

APM(4)               NetBSD/i386 Kernel Interfaces Manual               APM(4)


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 fea-
     tures 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 fol-
     lowing kernel configuration options:
     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.
     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 bat-
             tery power.  Some systems generate the events too frequently, and
             printing the status may disturb single-user operations.)

     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 process-
     ing 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.

NetBSD 9.0                       July 10, 2018                      NetBSD 9.0