1.\" Copyright (c) 1995,1996 John T. Kohl 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. The name of the author may not be used to endorse or promote products 13.\" derived from this software without specific prior written permission. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR `AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 19.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 23.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 24.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $NetBSD: apm.4,v 1.19 2018/07/10 15:12:29 maya Exp $ 28.\" 29.Dd July 10, 2018 30.Dt APM 4 i386 31.Os 32.Sh NAME 33.Nm apm 34.Nd 35Advanced Power Management pseudo-device driver 36.Sh SYNOPSIS 37.Cd "apm0 at mainbus0" 38.In machine/apmvar.h 39.Pa /dev/apm 40.Sh DESCRIPTION 41The 42.Nm apm 43driver provides support for the Advanced Power Management features of 44some i386 system BIOSes. 45The driver supports the Advanced Power 46Management (APM) BIOS Interface Specification (revision 1.2), published 47jointly by the Intel Corporation and the Microsoft Corporation. 48.Pp 49The APM driver's behavior may be adjusted by specifying any of the 50following kernel configuration options: 51.Bl -tag -width indent -compact 52.It Dv APM_V10_ONLY 53Use only the APM revision 1.0 specification calls. 54(Some systems do not implement APM v1.1 very well, and generate 55weird events instead of the expected events when the system suspend 56key is pressed.) 57.It Dv APM_NO_V12 58Don't attach to the BIOS as APM v1.2 compliant device. 59(In case there are problems with v1.2 support.) 60.It Dv APM_NO_STANDBY 61Do not attempt to put the system into standby mode. 62.It Dv APM_NO_POWEROFF 63Do not attempt to turn off power when halting the system. 64.It Dv APMDEBUG 65Enable kernel printout of events received from the APM BIOS. 66.It Dv APMCALLDEBUG 67Enable kernel printout of every call to the APM BIOS (this is very noisy). 68.It Dv APM_POWER_PRINT 69Print power state on console at 70.Dv APM_POWER_CHANGE 71events. 72(Since it increases 73.Xr syslogd 8 Ns 's 74activity, it may consume increased battery power. 75Some systems generate the events too frequently, 76and printing the status may disturb single-user operations.) 77.El 78.Pp 79If no processes are holding open file descriptors to the APM device, the 80driver will process the APM BIOS events itself. 81If a process has the 82device open for write, the driver defers all suspend and standby 83processing to the user process as long as there is sufficient queue 84space to store the event for the process. 85If the device is only open 86for read, the driver will report events but handle them itself. 87.Pp 88The APM device may be opened by multiple readers but only one 89writer. 90Multiple readers may fetch the status with 91.Xr ioctl 2 92without worrying about interference, but they must cooperate to share 93events as only a single event queue is provided. 94The device may only be 95.Xr select 2 Ns ed 96or manipulated with 97.Xr ioctl 2 ; 98.Xr read 2 99and 100.Xr write 2 101are not supported. 102The 103.Xr ioctl 2 104calls supported are: 105.Bl -tag -width indent -compact 106.It Dv APM_IOC_SUSPEND 107Initiate an APM suspend mode. 108This is a deep sleep mode which powers down most devices. 109The device must be open for writing for this command to succeed. 110.It Dv APM_IOC_STANDBY 111Initiate an APM standby mode. 112This is a light sleep mode from which the 113system can quickly restore normal operation. 114The device must be open for writing for this command to succeed. 115.It Dv APM_IOC_GETPOWER 116Fetch the current power status into an 117.Va apm_power_info 118structure. 119.Bd -literal 120struct apm_power_info { 121 u_char battery_state; 122 u_char ac_state; 123 u_char battery_life; 124 u_char spare1; 125 u_int minutes_left; /* estimate */ 126 u_int nbattery; 127 u_int batteryid; 128 u_int spare2[4]; 129}; 130.Ed 131.Pp 132The structure should be zeroed (except for 133.Va batteryid ) 134before 135being passed. 136.Pp 137.Va battery_state 138is one of 139.Dv APM_BATT_HIGH , 140.Dv APM_BATT_LOW , 141.Dv APM_BATT_CRITICAL , 142.Dv APM_BATT_CHARGING , 143or 144.Dv APM_BATT_UNKNOWN . 145.Pp 146.Va ac_state 147is one of 148.Dv APM_AC_OFF , 149.Dv APM_AC_ON , 150.Dv APM_AC_BACKUP , 151or 152.Dv APM_AC_UNKNOWN . 153.Pp 154.Va battery_life 155is the percentage estimated remaining normal battery life (or 0 if the 156BIOS cannot provide an estimate). 157.Pp 158.Va minutes_left 159is an estimated remaining lifetime (or 0 if the BIOS cannot provide an 160estimate). 161.Pp 162.Va nbattery 163is the number of batteries in the system. 164If the system is using APM v1.1 or earlier, nbattery will always return 0. 165.Pp 166Batteries are numbered from a base of 1. 167If the passed value of 168.Va batteryid 169is 0, the returned values will reflect the percentage remaining, minutes 170left, etc. of all of the system's batteries taken together. 171If the passed value of 172.Va batteryid 173is nonzero, the return values will reflect the indicated 174battery's percentage remaining, minutes left, etc. 175It is an error to set 176.Va batteryid 177to a value greater than that returned by 178.Va nbattery . 179If the system is using APM v1.1 or earlier, individual batteries 180cannot be queried, and 181.Va nbattery 182will always return 0. 183.Va batteryid 184is always set to the passed value upon return. 185.It Dv APM_IOC_NEXTEVENT 186Fetch the next event from the APM BIOS into an 187.Va apm_event_info 188structure. 189If no more events are ready, this will return 190.Dv EAGAIN . 191.Bd -literal 192struct apm_event_info { 193 u_int type; 194 u_int index; 195 u_int spare[8]; 196}; 197.Ed 198.Va type 199is one of the APM event types (APM_STANDBY_REQ through 200APM_SYS_STANDBY_RESUME). 201.Va index 202is the ordinal event sequence number. 203.El 204.Sh SEE ALSO 205.Xr apmd 8 206.Sh REFERENCES 207Advanced Power Management (APM) BIOS Interface Specification (Revision 2081.1), Intel Corporation and Microsoft Corporation. 209Intel order number 241704-001; Microsoft part number 781-110-X01. 210.Sh HISTORY 211The 212.Nm apm 213pseudo-device driver appeared in 214.Nx 1.3 . 215