1.\" $OpenBSD: apm.4,v 1.8 2023/01/30 14:43:29 jcs 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: January 30 2023 $ 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_DEV_CTL 145.\" .Em NOT YET SUPPORTED on loongson 146.\" .Pq Li "struct apm_ctl" 147.\" Allows an application to directly set the 148.\" .Tm APM 149.\" operating mode. 150.\" The argument structure is as follows: 151.\" .Bd -literal -offset indent 152.\" struct apm_ctl { 153.\" u_int dev; 154.\" u_int mode; 155.\" }; 156.\" .Ed 157.\" .Pp 158.\" .Va dev 159.\" indicates the device, typically 160.\" .Dv APM_DEV_ALLDEVS . 161.\" .Pp 162.\" .Va mode 163.\" indicates the desired operating mode. 164.\" Possible values are 165.\" .Bl -tag -compact -offset indent 166.\" .It Dv APM_SYS_READY 167.\" .It Dv APM_SYS_STANDBY 168.\" .It Dv APM_SYS_SUSPEND 169.\" .It Dv APM_SYS_OFF 170.\" .It Dv APM_LASTREQ_INPROG 171.\" .It Dv APM_LASTREQ_REJECTED 172.\" .El 173.It Dv APM_IOC_PRN_CTL 174.Pq Li "int" 175This 176.Xr ioctl 2 177controls message output by the 178.Nm 179driver when a power change event is detected. 180The integer parameter is one of: 181.Bl -tag -width Ds 182.It Dv APM_PRINT_ON 183All power change events result in a message. 184This is the normal operating mode for the driver. 185.It Dv APM_PRINT_OFF 186Power change event messages are suppressed. 187.It Dv APM_PRINT_PCT 188Power change event messages are suppressed unless the estimated 189battery life percentage changes. 190.El 191.El 192.Sh FILES 193.Bl -tag -width /dev/apmctl 194.It Pa /dev/apm 195APM data device. 196May only be opened read-only. 197May be opened by multiple concurrent users. 198.It Pa /dev/apmctl 199APM control device. 200May be opened read-write or write-only. 201May only be opened by one user at a time. 202An attempt to open the file when in use will fail, returning 203.Er EBUSY . 204.El 205.Sh SEE ALSO 206.Xr intro 4 , 207.Xr ykbec 4 , 208.Xr apm 8 , 209.Xr apmd 8 210.Sh BUGS 211Suspend and resume are not supported. 212