1.\" $OpenBSD: apm.4,v 1.23 2003/07/09 13:26:20 jmc Exp $ 2.\" 3.\" Copyright (c) 1998 Marco S. Hyman 4.\" 5.\" Permission to copy all or part of this material for any purpose is 6.\" granted provided that the above copyright notice and this paragraph 7.\" are duplicated in all copies. THIS SOFTWARE IS PROVIDED ``AS IS'' 8.\" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT 9.\" LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 10.\" FOR A PARTICULAR PURPOSE. 11.\" 12.Dd July 17, 1998 13.Dt APM 4 i386 14.Os 15.Sh NAME 16.Nm apm 17.Nd advanced power management device interface 18.Sh SYNOPSIS 19.Cd "apm0 at bios0 flags 0x0000" 20.Sh DESCRIPTION 21The 22.Nm 23driver provides an interface to the Advanced Power Management 24.Pq Tn APM 25.Tn BIOS 26functions. 27The driver supports versions 1.0, 1.1, and 1.2 interface specifications. 28.Pp 29The low two bytes of the flags specify the version of the specification 30driver should conform to in binary decimal notation. 31The value of 0x0101 would specify version 1.1 of the interface 32specification to be used. 33.Pp 34The value of 0x10000 specifies whether to leave interrupts enabled 35when calling 36.Tn APM BIOS 37routines. 38This is needed for some 39.Tn IBM 40laptops, the symptoms are 41hangs and freezes on suspend, stand by, and hibernation activities. 42.Pp 43The value of 0x20000 specifies to swap the bytes of the battery 44life estimation (the DX register) as given from the 45.Tn APM BIOS . 46This is needed for some 47.Tn SONY VAIO 48laptops, such as some 505 models. 49.Pp 50Configuration options: 51.Pp 52.Bl -tag -width DIAGNOSTIC -compact -offset indent 53.It Dv APMDEBUG 54Enable various driver status messages. 55.It Dv DIAGNOSTIC 56Enable debugging messages. 57.It Dv DEBUG 58Enable other debugging messages. 59.El 60.Pp 61The 62.Nm 63driver implements the following 64.Xr ioctl 2 65calls. 66They are defined in 67.Aq Pa machine/apmvar.h . 68.Pp 69.Bl -tag -width Ds 70.It Dv APM_IOC_REJECT 71.Em Not implemented . DO NOT USE . 72.It Dv APM_IOC_STANDBY 73.Pq Li "no parameters" 74Request 75.Dq standby 76mode. 77.It Dv APM_IOC_SUSPEND 78.Pq Li "no parameters" 79Request 80.Dq suspend 81mode. 82.It Dv APM_IOC_GETPOWER 83.Pq Li "struct apm_power_info" 84Request the current power state. 85The argument structure is as follows: 86.Bd -literal -offset indent 87struct apm_power_info { 88 u_char battery_state; 89 u_char ac_state; 90 u_char battery_life; 91 u_char spare1; 92 u_int minutes_left; 93 u_int spare2[6]; 94}; 95.Ed 96.Pp 97The following values are defined for 98.Va battery_state : 99.Bl -tag -width Ds 100.It Dv APM_BATT_HIGH 101Battery has a high state of charge. 102.It Dv APM_BATT_LOW 103Battery has a low state of charge. 104.It Dv APM_BATT_CRITICAL 105Battery has a critical state of charge. 106.It Dv APM_BATT_CHARGING 107Battery is not high, low, or critical and is currently charging. 108.It Dv APM_BATT_UNKNOWN 109Can not read the current battery state. 110.It Dv APM_BATTERY_ABSENT 111No battery installed. 112.El 113.Pp 114The following values are defined for 115.Va ac_state : 116.Bl -tag -width Ds 117.It Dv APM_AC_OFF 118External power not detected. 119.It Dv APM_AC_ON 120External power detected. 121.It Dv APM_AC_BACKUP 122Backup power in use. 123.It Dv APM_AC_UNKNOWN 124External power state unknown. 125.El 126.Pp 127The 128.Va battery_life 129value contains the estimated percentage of battery life available. 130100% indicates a full charge. 131.Pp 132The 133.Va minutes_left 134value contains the estimated number of minutes of battery life 135remaining. 136.It Dv APM_IOC_NEXTEVENT 137.Pq Li "struct apm_event_info" 138The 139.Tn APM 140driver stores up to 141.Dv APM_NEVENTS 142events. 143This was defined as 16 at the time this documentation was written. 144If the event list is full when a new event is detected the new event is lost. 145.Dv APM_IOC_NEXTEVENT 146ioctl returns the next event on the list or 147.Er EAGAIN 148if the event list is empty. 149The format of the returned event is: 150.Bd -literal -offset indent 151struct apm_event_info { 152 u_int type; 153 u_int index; 154 u_int spare[8]; 155}; 156.Ed 157where 158.Va index 159is a sequential count of events that can be used to check if any 160events were lost and 161.Va type 162is one of: 163.Bl -tag -width Ds -offset indent -compact 164.It Dv APM_STANDBY_REQ 165.It Dv APM_SUSPEND_REQ 166.It Dv APM_NORMAL_RESUME 167.It Dv APM_CRIT_RESUME 168.It Dv APM_BATTERY_LOW 169.It Dv APM_POWER_CHANGE 170.It Dv APM_UPDATE_TIME 171.It Dv APM_CRIT_SUSPEND_REQ 172.It Dv APM_USER_STANDBY_REQ 173.It Dv APM_USER_SUSPEND_REQ 174.It Dv APM_SYS_STANDBY_RESUME 175.El 176.It Dv APM_IOC_DEV_CTL 177.Pq Li "struct apm_ctl" 178Allows an application to directly set the 179.Tm APM 180operating mode. 181The argument structure is as follows: 182.Bd -literal -offset indent 183struct apm_ctl { 184 u_int dev; 185 u_int mode; 186}; 187.Ed 188.Pp 189.Va dev 190indicates the device, typically 191.Dv APM_DEV_ALLDEVS . 192.Pp 193.Va mode 194indicates the desired operating mode. 195Possible values are 196.Bl -tag -compact -offset indent 197.It Dv APM_SYS_READY 198.It Dv APM_SYS_STANDBY 199.It Dv APM_SYS_SUSPEND 200.It Dv APM_SYS_OFF 201.It Dv APM_LASTREQ_INPROG 202.It Dv APM_LASTREQ_REJECTED 203.El 204.It Dv APM_IOC_PRN_CTL 205.Pq Li "int" 206This 207.Xr ioctl 2 208controls message output by the 209.Tn APM 210driver when a power change event is detected. 211The integer parameter is one of: 212.Bl -tag -width Ds 213.It Dv APM_PRINT_ON 214All power change events result in a message. 215This is the normal operating mode for the driver. 216.It Dv APM_PRINT_OFF 217Power change event messages are suppressed. 218.It Dv APM_PRINT_PCT 219Power change event messages are suppressed unless the estimated 220battery life percentage changes. 221.El 222.Pp 223However, in no case will power status messages be displayed until the 224battery life goes below the percentage in the 225.Xr sysctl 8 226state variable 227.Dv machdep.apmwarn . 228Setting 229.Dv machdep.apmwarn 230to zero disables all warnings regardless of the 231.Dv APM_IOC_PRN_CTL 232setting. 233.El 234.Pp 235As noted above, the operation of the 236.Tn APM 237driver can be modified using the 238.Dv machdep.apmwarn 239.Xr sysctl 8 240variable. 241Another driver modifier is the 242.Dv machdep.apmhalt 243variable. 244When 245.Dv machdep.apmhalt 246is set to 1 the 247.Tn APM 248power down code is modified in a way necessary for correct operation on 249some systems, mainly 250.Tn IBM 251laptops. 252If your system does not power down when given the command 253.Li "halt -p" 254try setting 255.Dv machdep.apmhalt 256to 1 using 257.Xr sysctl 8 . 258The variable can be set at boot time in 259.Xr sysctl.conf 5 . 260.Sh FILES 261.Bl -tag -width /dev/apmctl -compact 262.It Pa /dev/apm 263.Tn APM 264data device. 265May only be opened read-only. 266May be opened by multiple concurrent users. 267.It Pa /dev/apmctl 268.Tn APM 269control device. 270May be opened read-write or write-only. 271May only be opened by one user at a time. 272An attempt to open the file when in use will fail, returning 273.Er EBUSY . 274.El 275.Sh SEE ALSO 276.Xr intro 4 , 277.Xr sysctl.conf 5 , 278.Xr apm 8 , 279.Xr apmd 8 , 280.Xr halt 8 , 281.Xr sysctl 8 282.\" .Pp 283.\" http://developer.intel.com/ial/powermgm/apmv12.pdf 284.Sh HISTORY 285The 286.Nm 287driver source code contains these copyrights: 288.Pp 289.Bl -item -compact 290.It 291.Li Copyright (c) 1995 John T. Kohl. All rights reserved. 292.It 293.Li Copyright (C) 1994 by HOSOKAWA Tatsumi <hosokawa@mt.cs.keio.ac.jp> 294.El 295.Pp 296\&...and has been hacked on by many others since. 297.Sh BUGS 298Not all the BIOSes support power down the way we are attempting 299to execute it. 300.Pp 301Not all BIOS vendors even read the specification. 302