1.\" $OpenBSD: apm.4,v 1.5 2016/02/27 20:57:32 natano Exp $ 2.\" 3.\" Copyright (c) 1999 Jason L. Wright (jason@thought.net) 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 19.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 23.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 24.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" APM description: 28.\" 29.\" Copyright (c) 1998 Marco S. Hyman 30.\" 31.\" Permission to copy all or part of this material for any purpose is 32.\" granted provided that the above copyright notice and this paragraph 33.\" are duplicated in all copies. THIS SOFTWARE IS PROVIDED ``AS IS'' 34.\" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT 35.\" LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 36.\" FOR A PARTICULAR PURPOSE. 37.Dd $Mdocdate: February 27 2016 $ 38.Dt APM 4 loongson 39.Os 40.Sh NAME 41.Nm apm 42.Nd advanced power management device interface 43.Sh SYNOPSIS 44.Cd "apm0 at mainbus0" 45.Sh DESCRIPTION 46The 47.Nm 48driver provides generic power and battery control, 49relying on device specific drivers to provide the actual information. 50.Pp 51The 52.Nm 53driver provides an interface which simulates the Advanced Power Management 54.Pq Tn APM 55BIOS functions encountered on some x86 hardware. 56The BIOS functions are translated into the appropriate microcontroller requests 57by the hardware specific drivers, like 58.Xr ykbec 4 . 59Currently only battery level, AC connection, and charging status are available 60from the 61.Nm 62device. 63Suspend/resume and other power events are not yet supported. 64.Pp 65The 66.Nm 67driver implements the following 68.Xr ioctl 2 69calls. 70They are defined in 71.In machine/apmvar.h . 72.Bl -tag -width Ds 73.\" .It Dv APM_IOC_STANDBY 74.\" .Em NOT YET SUPPORTED on loongson 75.\" .Pq Li "no parameters" 76.\" Request 77.\" .Dq standby 78.\" mode. 79.\" .It Dv APM_IOC_SUSPEND 80.\" .Em NOT YET SUPPORTED on loongson 81.\" .Pq Li "no parameters" 82.\" Request 83.\" .Dq suspend 84.\" mode. 85.\" .It Dv APM_IOC_HIBERNATE 86.\" .Em NOT YET SUPPORTED on loongson 87.\" .Pq Li "no parameters" 88.\" Request 89.\" .Dq hibernate 90.\" mode. 91.It Dv APM_IOC_GETPOWER 92.Pq Li "struct apm_power_info" 93Request the current power state. 94The argument structure is as follows: 95.Bd -literal -offset indent 96struct apm_power_info { 97 u_char battery_state; 98 u_char ac_state; 99 u_char battery_life; 100 u_char spare1; 101 u_int minutes_left; 102 u_int spare2[6]; 103}; 104.Ed 105.Pp 106The following values are defined for 107.Va battery_state : 108.Bl -tag -width Ds 109.It Dv APM_BATT_HIGH 110Battery has a high state of charge. 111.It Dv APM_BATT_LOW 112Battery has a low state of charge. 113.It Dv APM_BATT_CRITICAL 114Battery has a critical state of charge. 115.It Dv APM_BATT_CHARGING 116Battery is not high, low, or critical and is currently charging. 117.It Dv APM_BATT_UNKNOWN 118Cannot read the current battery state. 119.It Dv APM_BATTERY_ABSENT 120No battery installed. 121.El 122.Pp 123The following values are defined for 124.Va ac_state : 125.Bl -tag -width Ds 126.It Dv APM_AC_OFF 127External power not detected. 128.It Dv APM_AC_ON 129External power detected. 130.\" .It Dv APM_AC_BACKUP 131.\" Backup power in use. 132.\" .It Dv APM_AC_UNKNOWN 133.\" External power state unknown. 134.El 135.Pp 136The 137.Va battery_life 138value contains the estimated percentage of battery life available. 139100% indicates a full charge. 140.Pp 141The 142.Va minutes_left 143value contains the estimated number of minutes of battery life remaining. 144.\" .It Dv APM_IOC_NEXTEVENT 145.\" .Em NOT YET SUPPORTED on loongson 146.\" .Pq Li "struct apm_event_info" 147.\" The 148.\" .Tn APM 149.\" driver stores up to 150.\" .Dv APM_NEVENTS 151.\" events. 152.\" This was defined as 16 at the time this documentation was written. 153.\" If the event list is full when a new event is detected the new event is lost. 154.\" .Dv APM_IOC_NEXTEVENT 155.\" ioctl returns the next event on the list or 156.\" .Er EAGAIN 157.\" if the event list is empty. 158.\" The format of the returned event is: 159.\" .Bd -literal -offset indent 160.\" struct apm_event_info { 161.\" u_int type; 162.\" u_int index; 163.\" u_int spare[8]; 164.\" }; 165.\" .Ed 166.\" where 167.\" .Va index 168.\" is a sequential count of events that can be used to check if any 169.\" events were lost and 170.\" .Va type 171.\" is one of: 172.\" .Pp 173.\" .Bl -tag -width Ds -offset indent -compact 174.\" .It Dv APM_STANDBY_REQ 175.\" .It Dv APM_SUSPEND_REQ 176.\" .It Dv APM_NORMAL_RESUME 177.\" .It Dv APM_CRIT_RESUME 178.\" .It Dv APM_BATTERY_LOW 179.\" .It Dv APM_POWER_CHANGE 180.\" .It Dv APM_UPDATE_TIME 181.\" .It Dv APM_CRIT_SUSPEND_REQ 182.\" .It Dv APM_USER_STANDBY_REQ 183.\" .It Dv APM_USER_SUSPEND_REQ 184.\" .It Dv APM_SYS_STANDBY_RESUME 185.\" .El 186.\" .It Dv APM_IOC_DEV_CTL 187.\" .Em NOT YET SUPPORTED on loongson 188.\" .Pq Li "struct apm_ctl" 189.\" Allows an application to directly set the 190.\" .Tm APM 191.\" operating mode. 192.\" The argument structure is as follows: 193.\" .Bd -literal -offset indent 194.\" struct apm_ctl { 195.\" u_int dev; 196.\" u_int mode; 197.\" }; 198.\" .Ed 199.\" .Pp 200.\" .Va dev 201.\" indicates the device, typically 202.\" .Dv APM_DEV_ALLDEVS . 203.\" .Pp 204.\" .Va mode 205.\" indicates the desired operating mode. 206.\" Possible values are 207.\" .Bl -tag -compact -offset indent 208.\" .It Dv APM_SYS_READY 209.\" .It Dv APM_SYS_STANDBY 210.\" .It Dv APM_SYS_SUSPEND 211.\" .It Dv APM_SYS_OFF 212.\" .It Dv APM_LASTREQ_INPROG 213.\" .It Dv APM_LASTREQ_REJECTED 214.\" .El 215.It Dv APM_IOC_PRN_CTL 216.Pq Li "int" 217This 218.Xr ioctl 2 219controls message output by the 220.Nm 221driver when a power change event is detected. 222The integer parameter is one of: 223.Bl -tag -width Ds 224.It Dv APM_PRINT_ON 225All power change events result in a message. 226This is the normal operating mode for the driver. 227.It Dv APM_PRINT_OFF 228Power change event messages are suppressed. 229.It Dv APM_PRINT_PCT 230Power change event messages are suppressed unless the estimated 231battery life percentage changes. 232.El 233.\" .Pp 234.\" However, in no case will power status messages be displayed until the 235.\" battery life goes below the percentage in the 236.\" .Xr sysctl 8 237.\" state variable 238.\" .Dv machdep.apmwarn . 239.\" Setting 240.\" .Dv machdep.apmwarn 241.\" to zero disables all warnings regardless of the 242.\" .Dv APM_IOC_PRN_CTL 243.\" setting. 244.El 245.Sh FILES 246.Bl -tag -width /dev/apmctl 247.It Pa /dev/apm 248APM data device. 249May only be opened read-only. 250May be opened by multiple concurrent users. 251.It Pa /dev/apmctl 252APM control device. 253May be opened read-write or write-only. 254May only be opened by one user at a time. 255An attempt to open the file when in use will fail, returning 256.Er EBUSY . 257.El 258.Sh SEE ALSO 259.Xr intro 4 , 260.Xr ykbec 4 , 261.Xr apm 8 , 262.Xr apmd 8 263.Sh BUGS 264Suspend and resume are not supported. 265