1.\" $OpenBSD: apm.4,v 1.34 2019/01/23 22:33:43 jsg 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: January 23 2019 $ 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 APM 25BIOS functions. 26The driver supports versions 1.0, 1.1, and 1.2 interface specifications. 27.Pp 28This driver also provides an interface to 29.Xr acpi 4 30on some machines. 31.Pp 32The low two bytes of the flags specify the version of the specification 33driver should conform to in binary decimal notation. 34The value of 0x0101 would specify version 1.1 of the interface 35specification to be used. 36.Pp 37The value of 0x10000 specifies whether to leave interrupts enabled 38when calling APM BIOS routines. 39This is needed for some 40.Tn IBM 41laptops, the symptoms are 42hangs and freezes on suspend, stand by, and hibernation activities. 43.Pp 44The value of 0x20000 specifies to swap the bytes of the battery 45life estimation (the DX register) as given from the 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.In machine/apmvar.h . 68.Bl -tag -width Ds 69.It Dv APM_IOC_REJECT 70.Em Not implemented . DO NOT USE . 71.It Dv APM_IOC_STANDBY 72.Pq Li "no parameters" 73Request 74.Dq standby 75mode. 76.It Dv APM_IOC_SUSPEND 77.Pq Li "no parameters" 78Request 79.Dq suspend 80mode. 81.It Dv APM_IOC_HIBERNATE 82.Pq Li "no parameters" 83Request 84.Dq hibernate 85mode. 86.It Dv APM_IOC_GETPOWER 87.Pq Li "struct apm_power_info" 88Request the current power state. 89The argument structure is as follows: 90.Bd -literal -offset indent 91struct apm_power_info { 92 u_char battery_state; 93 u_char ac_state; 94 u_char battery_life; 95 u_char spare1; 96 u_int minutes_left; 97 u_int spare2[6]; 98}; 99.Ed 100.Pp 101The following values are defined for 102.Va battery_state : 103.Bl -tag -width Ds 104.It Dv APM_BATT_HIGH 105Battery has a high state of charge. 106.It Dv APM_BATT_LOW 107Battery has a low state of charge. 108.It Dv APM_BATT_CRITICAL 109Battery has a critical state of charge. 110.It Dv APM_BATT_CHARGING 111Battery is not high, low, or critical and is currently charging. 112.It Dv APM_BATT_UNKNOWN 113Cannot read the current battery state. 114.It Dv APM_BATTERY_ABSENT 115No battery installed. 116.El 117.Pp 118The following values are defined for 119.Va ac_state : 120.Bl -tag -width Ds 121.It Dv APM_AC_OFF 122External power not detected. 123.It Dv APM_AC_ON 124External power detected. 125.It Dv APM_AC_BACKUP 126Backup power in use. 127.It Dv APM_AC_UNKNOWN 128External power state unknown. 129.El 130.Pp 131The 132.Va battery_life 133value contains the estimated percentage of battery life available. 134100% indicates a full charge. 135.Pp 136The 137.Va minutes_left 138value contains the estimated number of minutes of battery life 139remaining. 140.It Dv APM_IOC_NEXTEVENT 141.Pq Li "struct apm_event_info" 142The APM driver stores up to 143.Dv APM_NEVENTS 144events. 145This was defined as 16 at the time this documentation was written. 146If the event list is full when a new event is detected the new event is lost. 147.Dv APM_IOC_NEXTEVENT 148ioctl returns the next event on the list or 149.Er EAGAIN 150if the event list is empty. 151The format of the returned event is: 152.Bd -literal -offset indent 153struct apm_event_info { 154 u_int type; 155 u_int index; 156 u_int spare[8]; 157}; 158.Ed 159where 160.Va index 161is a sequential count of events that can be used to check if any 162events were lost and 163.Va type 164is one of: 165.Bl -tag -width Ds -offset indent -compact 166.It Dv APM_STANDBY_REQ 167.It Dv APM_SUSPEND_REQ 168.It Dv APM_NORMAL_RESUME 169.It Dv APM_CRIT_RESUME 170.It Dv APM_BATTERY_LOW 171.It Dv APM_POWER_CHANGE 172.It Dv APM_UPDATE_TIME 173.It Dv APM_CRIT_SUSPEND_REQ 174.It Dv APM_USER_STANDBY_REQ 175.It Dv APM_USER_SUSPEND_REQ 176.It Dv APM_SYS_STANDBY_RESUME 177.El 178.It Dv APM_IOC_DEV_CTL 179.Pq Li "struct apm_ctl" 180Allows an application to directly set the 181APM operating mode. 182The argument structure is as follows: 183.Bd -literal -offset indent 184struct apm_ctl { 185 u_int dev; 186 u_int mode; 187}; 188.Ed 189.Pp 190.Va dev 191indicates the device, typically 192.Dv APM_DEV_ALLDEVS . 193.Pp 194.Va mode 195indicates the desired operating mode. 196Possible values are 197.Bl -tag -width Ds -compact -offset indent 198.It Dv APM_SYS_READY 199.It Dv APM_SYS_STANDBY 200.It Dv APM_SYS_SUSPEND 201.It Dv APM_SYS_OFF 202.It Dv APM_LASTREQ_INPROG 203.It Dv APM_LASTREQ_REJECTED 204.El 205.It Dv APM_IOC_PRN_CTL 206.Pq Li "int" 207This 208.Xr ioctl 2 209controls message output by the 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.El 223.Sh FILES 224.Bl -tag -width "/dev/apmctlXXX" 225.It /dev/apm 226Power management data device. 227May only be opened read-only. 228May be opened by multiple concurrent users. 229.It /dev/apmctl 230Power management control device. 231May be opened read-write or write-only. 232May only be opened by one user at a time. 233An attempt to open the file when in use will fail, returning 234.Er EBUSY . 235.El 236.Sh SEE ALSO 237.Xr acpi 4 , 238.Xr intro 4 , 239.Xr apm 8 , 240.Xr apmd 8 , 241.Xr halt 8 242.Sh HISTORY 243The 244.Nm 245driver source code contains these copyrights: 246.Pp 247.Bl -item -compact 248.It 249.Li Copyright (c) 1995 John T. Kohl. All rights reserved. 250.It 251.Li Copyright (C) 1994 by HOSOKAWA Tatsumi <hosokawa@mt.cs.keio.ac.jp> 252.El 253.Pp 254\&...and has been hacked on by many others since. 255.Sh BUGS 256Not all the BIOSes support power down the way we are attempting 257to execute it. 258.Pp 259Not all BIOS vendors even read the specification. 260