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