xref: /openbsd/share/man/man4/man4.i386/apm.4 (revision 91f110e0) 
1.\"	$OpenBSD: apm.4,v 1.31 2014/01/21 03:15:46 schwarze 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 21 2014 $
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_GETPOWER
82.Pq Li "struct apm_power_info"
83Request the current power state.
84The argument structure is as follows:
85.Bd -literal -offset indent
86struct apm_power_info {
87	u_char battery_state;
88	u_char ac_state;
89	u_char battery_life;
90	u_char spare1;
91	u_int minutes_left;
92	u_int spare2[6];
93};
94.Ed
95.Pp
96The following values are defined for
97.Va battery_state :
98.Bl -tag -width Ds
99.It Dv APM_BATT_HIGH
100Battery has a high state of charge.
101.It Dv APM_BATT_LOW
102Battery has a low state of charge.
103.It Dv APM_BATT_CRITICAL
104Battery has a critical state of charge.
105.It Dv APM_BATT_CHARGING
106Battery is not high, low, or critical and is currently charging.
107.It Dv APM_BATT_UNKNOWN
108Can not read the current battery state.
109.It Dv APM_BATTERY_ABSENT
110No battery installed.
111.El
112.Pp
113The following values are defined for
114.Va ac_state :
115.Bl -tag -width Ds
116.It Dv APM_AC_OFF
117External power not detected.
118.It Dv APM_AC_ON
119External power detected.
120.It Dv APM_AC_BACKUP
121Backup power in use.
122.It Dv APM_AC_UNKNOWN
123External power state unknown.
124.El
125.Pp
126The
127.Va battery_life
128value contains the estimated percentage of battery life available.
129100% indicates a full charge.
130.Pp
131The
132.Va minutes_left
133value contains the estimated number of minutes of battery life
134remaining.
135.It Dv APM_IOC_NEXTEVENT
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.Bl -tag -width Ds -offset indent -compact
161.It Dv APM_STANDBY_REQ
162.It Dv APM_SUSPEND_REQ
163.It Dv APM_NORMAL_RESUME
164.It Dv APM_CRIT_RESUME
165.It Dv APM_BATTERY_LOW
166.It Dv APM_POWER_CHANGE
167.It Dv APM_UPDATE_TIME
168.It Dv APM_CRIT_SUSPEND_REQ
169.It Dv APM_USER_STANDBY_REQ
170.It Dv APM_USER_SUSPEND_REQ
171.It Dv APM_SYS_STANDBY_RESUME
172.El
173.It Dv APM_IOC_DEV_CTL
174.Pq Li "struct apm_ctl"
175Allows an application to directly set the
176APM operating mode.
177The argument structure is as follows:
178.Bd -literal -offset indent
179struct apm_ctl {
180	u_int dev;
181	u_int mode;
182};
183.Ed
184.Pp
185.Va dev
186indicates the device, typically
187.Dv APM_DEV_ALLDEVS .
188.Pp
189.Va mode
190indicates the desired operating mode.
191Possible values are
192.Bl -tag -width Ds -compact -offset indent
193.It Dv APM_SYS_READY
194.It Dv APM_SYS_STANDBY
195.It Dv APM_SYS_SUSPEND
196.It Dv APM_SYS_OFF
197.It Dv APM_LASTREQ_INPROG
198.It Dv APM_LASTREQ_REJECTED
199.El
200.It Dv APM_IOC_PRN_CTL
201.Pq Li "int"
202This
203.Xr ioctl 2
204controls message output by the APM
205driver when a power change event is detected.
206The integer parameter is one of:
207.Bl -tag -width Ds
208.It Dv APM_PRINT_ON
209All power change events result in a message.
210This is the normal operating mode for the driver.
211.It Dv APM_PRINT_OFF
212Power change event messages are suppressed.
213.It Dv APM_PRINT_PCT
214Power change event messages are suppressed unless the estimated
215battery life percentage changes.
216.El
217.Pp
218However, in no case will power status messages be displayed until the
219battery life goes below the percentage in the
220.Xr sysctl 8
221state variable
222.Dv machdep.apmwarn .
223Setting
224.Dv machdep.apmwarn
225to zero disables all warnings regardless of the
226.Dv APM_IOC_PRN_CTL
227setting.
228.El
229.Pp
230As noted above, the operation of the APM
231driver can be modified using the
232.Dv machdep.apmwarn
233.Xr sysctl 8
234variable.
235Another driver modifier is the
236.Dv machdep.apmhalt
237variable.
238When
239.Dv machdep.apmhalt
240is set to 1 the APM
241power down code is modified in a way necessary for correct operation on
242some systems, mainly
243.Tn IBM
244laptops.
245If your system does not power down when given the command
246.Li "halt -p"
247try setting
248.Dv machdep.apmhalt
249to 1 using
250.Xr sysctl 8 .
251The variable can be set at boot time in
252.Xr sysctl.conf 5 .
253.Sh FILES
254.Bl -tag -width "/dev/apmctlXXX"
255.It /dev/apm
256Power management data device.
257May only be opened read-only.
258May be opened by multiple concurrent users.
259.It /dev/apmctl
260Power management control device.
261May be opened read-write or write-only.
262May only be opened by one user at a time.
263An attempt to open the file when in use will fail, returning
264.Er EBUSY .
265.El
266.Sh SEE ALSO
267.Xr acpi 4 ,
268.Xr intro 4 ,
269.Xr sysctl.conf 5 ,
270.Xr apm 8 ,
271.Xr apmd 8 ,
272.Xr halt 8 ,
273.Xr sysctl 8
274.Sh HISTORY
275The
276.Nm
277driver source code contains these copyrights:
278.Pp
279.Bl -item -compact
280.It
281.Li Copyright (c) 1995 John T. Kohl.  All rights reserved.
282.It
283.Li Copyright (C) 1994 by HOSOKAWA Tatsumi <hosokawa@mt.cs.keio.ac.jp>
284.El
285.Pp
286\&...and has been hacked on by many others since.
287.Sh BUGS
288Not all the BIOSes support power down the way we are attempting
289to execute it.
290.Pp
291Not all BIOS vendors even read the specification.
292