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