1.\" $OpenBSD: apm.4,v 1.29 2007/11/29 11:35:35 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 $Mdocdate: November 29 2007 $ 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 29This driver also provides an interface to 30.Xr acpi 4 31on some machines. 32.Pp 33The low two bytes of the flags specify the version of the specification 34driver should conform to in binary decimal notation. 35The value of 0x0101 would specify version 1.1 of the interface 36specification to be used. 37.Pp 38The value of 0x10000 specifies whether to leave interrupts enabled 39when calling 40.Tn APM BIOS 41routines. 42This is needed for some 43.Tn IBM 44laptops, the symptoms are 45hangs and freezes on suspend, stand by, and hibernation activities. 46.Pp 47The value of 0x20000 specifies to swap the bytes of the battery 48life estimation (the DX register) as given from the 49.Tn APM BIOS . 50This is needed for some 51.Tn SONY VAIO 52laptops, such as some 505 models. 53.Pp 54Configuration options: 55.Pp 56.Bl -tag -width DIAGNOSTIC -compact -offset indent 57.It Dv APMDEBUG 58Enable various driver status messages. 59.It Dv DIAGNOSTIC 60Enable debugging messages. 61.It Dv DEBUG 62Enable other debugging messages. 63.El 64.Pp 65The 66.Nm 67driver implements the following 68.Xr ioctl 2 69calls. 70They are defined in 71.Aq Pa machine/apmvar.h . 72.Bl -tag -width Ds 73.It Dv APM_IOC_REJECT 74.Em Not implemented . DO NOT USE . 75.It Dv APM_IOC_STANDBY 76.Pq Li "no parameters" 77Request 78.Dq standby 79mode. 80.It Dv APM_IOC_SUSPEND 81.Pq Li "no parameters" 82Request 83.Dq suspend 84mode. 85.It Dv APM_IOC_GETPOWER 86.Pq Li "struct apm_power_info" 87Request the current power state. 88The argument structure is as follows: 89.Bd -literal -offset indent 90struct apm_power_info { 91 u_char battery_state; 92 u_char ac_state; 93 u_char battery_life; 94 u_char spare1; 95 u_int minutes_left; 96 u_int spare2[6]; 97}; 98.Ed 99.Pp 100The following values are defined for 101.Va battery_state : 102.Bl -tag -width Ds 103.It Dv APM_BATT_HIGH 104Battery has a high state of charge. 105.It Dv APM_BATT_LOW 106Battery has a low state of charge. 107.It Dv APM_BATT_CRITICAL 108Battery has a critical state of charge. 109.It Dv APM_BATT_CHARGING 110Battery is not high, low, or critical and is currently charging. 111.It Dv APM_BATT_UNKNOWN 112Can not read the current battery state. 113.It Dv APM_BATTERY_ABSENT 114No battery installed. 115.El 116.Pp 117The following values are defined for 118.Va ac_state : 119.Bl -tag -width Ds 120.It Dv APM_AC_OFF 121External power not detected. 122.It Dv APM_AC_ON 123External power detected. 124.It Dv APM_AC_BACKUP 125Backup power in use. 126.It Dv APM_AC_UNKNOWN 127External power state unknown. 128.El 129.Pp 130The 131.Va battery_life 132value contains the estimated percentage of battery life available. 133100% indicates a full charge. 134.Pp 135The 136.Va minutes_left 137value contains the estimated number of minutes of battery life 138remaining. 139.It Dv APM_IOC_NEXTEVENT 140.Pq Li "struct apm_event_info" 141The 142.Tn APM 143driver stores up to 144.Dv APM_NEVENTS 145events. 146This was defined as 16 at the time this documentation was written. 147If the event list is full when a new event is detected the new event is lost. 148.Dv APM_IOC_NEXTEVENT 149ioctl returns the next event on the list or 150.Er EAGAIN 151if the event list is empty. 152The format of the returned event is: 153.Bd -literal -offset indent 154struct apm_event_info { 155 u_int type; 156 u_int index; 157 u_int spare[8]; 158}; 159.Ed 160where 161.Va index 162is a sequential count of events that can be used to check if any 163events were lost and 164.Va type 165is one of: 166.Bl -tag -width Ds -offset indent -compact 167.It Dv APM_STANDBY_REQ 168.It Dv APM_SUSPEND_REQ 169.It Dv APM_NORMAL_RESUME 170.It Dv APM_CRIT_RESUME 171.It Dv APM_BATTERY_LOW 172.It Dv APM_POWER_CHANGE 173.It Dv APM_UPDATE_TIME 174.It Dv APM_CRIT_SUSPEND_REQ 175.It Dv APM_USER_STANDBY_REQ 176.It Dv APM_USER_SUSPEND_REQ 177.It Dv APM_SYS_STANDBY_RESUME 178.El 179.It Dv APM_IOC_DEV_CTL 180.Pq Li "struct apm_ctl" 181Allows an application to directly set the 182.Tm APM 183operating mode. 184The argument structure is as follows: 185.Bd -literal -offset indent 186struct apm_ctl { 187 u_int dev; 188 u_int mode; 189}; 190.Ed 191.Pp 192.Va dev 193indicates the device, typically 194.Dv APM_DEV_ALLDEVS . 195.Pp 196.Va mode 197indicates the desired operating mode. 198Possible values are 199.Bl -tag -compact -offset indent 200.It Dv APM_SYS_READY 201.It Dv APM_SYS_STANDBY 202.It Dv APM_SYS_SUSPEND 203.It Dv APM_SYS_OFF 204.It Dv APM_LASTREQ_INPROG 205.It Dv APM_LASTREQ_REJECTED 206.El 207.It Dv APM_IOC_PRN_CTL 208.Pq Li "int" 209This 210.Xr ioctl 2 211controls message output by the 212.Tn APM 213driver when a power change event is detected. 214The integer parameter is one of: 215.Bl -tag -width Ds 216.It Dv APM_PRINT_ON 217All power change events result in a message. 218This is the normal operating mode for the driver. 219.It Dv APM_PRINT_OFF 220Power change event messages are suppressed. 221.It Dv APM_PRINT_PCT 222Power change event messages are suppressed unless the estimated 223battery life percentage changes. 224.El 225.Pp 226However, in no case will power status messages be displayed until the 227battery life goes below the percentage in the 228.Xr sysctl 8 229state variable 230.Dv machdep.apmwarn . 231Setting 232.Dv machdep.apmwarn 233to zero disables all warnings regardless of the 234.Dv APM_IOC_PRN_CTL 235setting. 236.El 237.Pp 238As noted above, the operation of the 239.Tn APM 240driver can be modified using the 241.Dv machdep.apmwarn 242.Xr sysctl 8 243variable. 244Another driver modifier is the 245.Dv machdep.apmhalt 246variable. 247When 248.Dv machdep.apmhalt 249is set to 1 the 250.Tn APM 251power down code is modified in a way necessary for correct operation on 252some systems, mainly 253.Tn IBM 254laptops. 255If your system does not power down when given the command 256.Li "halt -p" 257try setting 258.Dv machdep.apmhalt 259to 1 using 260.Xr sysctl 8 . 261The variable can be set at boot time in 262.Xr sysctl.conf 5 . 263.Sh FILES 264.Bl -tag -width "/dev/apmctlXXX" 265.It /dev/apm 266Power management data device. 267May only be opened read-only. 268May be opened by multiple concurrent users. 269.It /dev/apmctl 270Power management control device. 271May be opened read-write or write-only. 272May only be opened by one user at a time. 273An attempt to open the file when in use will fail, returning 274.Er EBUSY . 275.El 276.Sh SEE ALSO 277.Xr acpi 4 , 278.Xr intro 4 , 279.Xr sysctl.conf 5 , 280.Xr apm 8 , 281.Xr apmd 8 , 282.Xr halt 8 , 283.Xr sysctl 8 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