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.17 2003/06/27 18:27:58 wiz Exp $ 28.\" 29.Dd May 18, 1996 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. The driver supports the Advanced Power 45Management (APM) BIOS Interface Specification (revision 1.2), published 46jointly by the Intel Corporation and the Microsoft Corporation. 47.Pp 48The APM driver's behavior may be adjusted by specifying any of the 49following kernel configuration options: 50.Bl -tag -width indent -compact 51.It Dv APM_NO_IDLE 52Do not call the BIOS CPU idle function from the system idle loop. (Some 53systems will hang on certain device accesses, such as sound cards or 54floppy diskette drives, without this option) 55.It Dv APM_V10_ONLY 56Use only the APM revision 1.0 specification calls. (Some systems do not 57implement APM v1.1 very well, and generate weird events instead of the 58expected events when the system suspend key is pressed.) 59.It Dv APM_NO_V12 60Don't attach to the BIOS as APM v1.2 compliant device. 61(In case there are problems with v1.2 support.) 62.It Dv APM_NO_STANDBY 63Do not attempt to put the system into standby mode. 64.It Dv APM_NO_POWEROFF 65Do not attempt to turn off power when halting the system. 66.It Dv APM_FORCE_64K_SEGMENTS 67Force the length of the APM BIOS code and data segments to 64KB. 68.It Dv APM_ALLOW_BOGUS_SEGMENTS 69Allow the use of data segments which are in unexpected locations. 70.It Dv APMDEBUG 71Enable kernel printout of events received from the APM BIOS. 72.It Dv APMCALLDEBUG 73Enable kernel printout of every call to the APM BIOS (this is very noisy). 74.It Dv APM_POWER_PRINT 75Print power state on console at 76.Dv APM_POWER_CHANGE 77events. (Since it increases 78.Xr syslogd 8 Ns 's 79activity, it may consume increased 80battery power. Some systems generate the events too frequently, 81and printing the status may disturb single-user operations.) 82.It Dv APM_DISABLE_INTERRUPTS 83Set this to zero if you don't want the kernel to disable interrupts 84before calling the BIOS. This is required for most IBM ThinkPads, and 85some other newer laptops. A good indication that you need this is that 86the machine hangs just after resuming from suspended state. It's 87unclear if doing this has negative effects on older BIOS, therefore it 88defaults to one (i.e interrupts are disabled). 89.El 90.Pp 91If no processes are holding open file descriptors to the APM device, the 92driver will process the APM BIOS events itself. If a process has the 93device open for write, the driver defers all suspend and standby 94processing to the user process as long as there is sufficient queue 95space to store the event for the process. If the device is only open 96for read, the driver will report events but handle them itself. 97.Pp 98The APM device may be opened by multiple readers but only one 99writer. Multiple readers may fetch the status with 100.Xr ioctl 2 101without worrying about interference, but they must cooperate to share 102events as only a single event queue is provided. The device may only be 103.Xr select 2 Ns ed 104or manipulated with 105.Xr ioctl 2 ; 106.Xr read 2 107and 108.Xr write 2 109are not supported. 110The 111.Xr ioctl 2 112calls supported are: 113.Bl -tag -width indent -compact 114.It Dv APM_IOC_SUSPEND 115Initiate an APM suspend mode. This is a deep sleep mode which powers down 116most devices. The device must be open for writing for this command to succeed. 117.It Dv APM_IOC_STANDBY 118Initiate an APM standby mode. This is a light sleep mode from which the 119system can quickly restore normal operation. The device must be open 120for writing for this command to succeed. 121.It Dv APM_IOC_GETPOWER 122Fetch the current power status into an 123.Va apm_power_info 124structure. 125.Bd -literal 126struct apm_power_info { 127 u_char battery_state; 128 u_char ac_state; 129 u_char battery_life; 130 u_char spare1; 131 u_int minutes_left; /* estimate */ 132 u_int nbattery; 133 u_int batteryid; 134 u_int spare2[4]; 135}; 136.Ed 137.Pp 138The structure should be zeroed (except for 139.Va batteryid ) 140before 141being passed. 142.Pp 143.Va battery_state 144is one of 145.Dv APM_BATT_HIGH , 146.Dv APM_BATT_LOW , 147.Dv APM_BATT_CRITICAL , 148.Dv APM_BATT_CHARGING , 149or 150.Dv APM_BATT_UNKNOWN . 151.Pp 152.Va ac_state 153is one of 154.Dv APM_AC_OFF , 155.Dv APM_AC_ON , 156.Dv APM_AC_BACKUP , 157or 158.Dv APM_AC_UNKNOWN . 159.Pp 160.Va battery_life 161is the percentage estimated remaining normal battery life (or 0 if the 162BIOS cannot provide an estimate). 163.Pp 164.Va minutes_left 165is an estimated remaining lifetime (or 0 if the BIOS cannot provide an 166estimate). 167.Pp 168.Va nbattery 169is the number of batteries in the system. If the system is using APM 170v1.1 or earlier, nbattery will always return 0. 171.Pp 172Batteries are numbered from a base of 1. 173If the passed value of 174.Va batteryid 175is 0, the returned values will reflect the percentage remaining, minutes 176left, etc. of all of the system's batteries taken together. 177If the passed value of 178.Va batteryid 179is nonzero, the return values will reflect the indicated 180battery's percentage remaining, minutes left, etc. 181It is an error to set 182.Va batteryid 183to a value greater than that returned by 184.Va nbattery . 185If the system is using APM v1.1 or earlier, individual batteries 186cannot be queried, and 187.Va nbattery 188will always return 0. 189.Va batteryid 190is always set to the passed value upon return. 191.It Dv APM_IOC_NEXTEVENT 192Fetch the next event from the APM BIOS into an 193.Va apm_event_info 194structure. If no more events are ready, this will return 195.Dv EAGAIN . 196.Bd -literal 197struct apm_event_info { 198 u_int type; 199 u_int index; 200 u_int spare[8]; 201}; 202.Ed 203.Va type 204is one of the APM event types (APM_STANDBY_REQ through 205APM_SYS_STANDBY_RESUME). 206.Va index 207is the ordinal event sequence number. 208.El 209.Sh SEE ALSO 210.Xr apmd 8 211.Sh REFERENCES 212Advanced Power Management (APM) BIOS Interface Specification (Revision 2131.1), Intel Corporation and Microsoft Corporation. Intel order number 214241704-001; Microsoft part number 781-110-X01. 215.Sh HISTORY 216The 217.Nm apm 218pseudo-device driver appeared in 219.Nx 1.3 . 220