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