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