acpi*.4: Update manual pages for the recent ACPI update.
[dragonfly.git] / share / man / man4 / acpi_thinkpad.4
1 .\" Copyright (c) 2005 Christian Brueffer
2 .\" Copyright (c) 2005 Markus Brueffer
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 .\" SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD: src/share/man/man4/man4.i386/acpi_ibm.4,v 1.15.8.1 2009/04/15 03:14:26 kensmith Exp $
27 .\"
28 .Dd November 11, 2009
29 .Dt ACPI_THINKPAD 4
30 .Os
31 .Sh NAME
32 .Nm acpi_thinkpad
33 .Nd "ACPI extras driver for IBM/Lenovo Thinkpad laptops"
34 .Sh SYNOPSIS
35 To compile this driver into the kernel,
36 place the following line in your
37 kernel configuration file:
38 .Bd -ragged -offset indent
39 .Cd "device acpi_thinkpad"
40 .Ed
41 .Pp
42 Alternatively, to load the driver as a
43 module at boot time, place the following line in
44 .Xr loader.conf 5 :
45 .Bd -literal -offset indent
46 acpi_thinkpad_load="YES"
47 .Ed
48 .Sh DESCRIPTION
49 The
50 .Nm
51 driver provides support for hotkeys and other components of IBM/Lenovo
52 Thinkpad laptops.
53 The main purpose of this driver is to provide an interface,
54 accessible via
55 .Xr sysctl 8
56 and
57 .Xr devd 8 ,
58 through which applications can determine the status of
59 various laptop components.
60 .Pp
61 While the
62 .Xr sysctl 8
63 interface is enabled automatically after loading the driver, the
64 .Xr devd 8
65 interface has to be enabled explicitly, as it may alter the default action of
66 certain keys.
67 This is done by setting the
68 .Va events
69 sysctl as described below.
70 Specifying which keys should generate events is done by setting a bitmask,
71 whereas each bit represents one key or key combination.
72 This bitmask, accessible via the
73 .Va eventmask
74 sysctl, is set to
75 .Va availmask
76 by default, a value representing all possible keypress events on the specific
77 ThinkPad model.
78 .Ss Xr devd 8 Ss Events
79 Hotkey events received by
80 .Xr devd 8
81 provide the following information:
82 .Pp
83 .Bl -tag -width "subsystem" -offset indent -compact
84 .It system
85 .Qq Li ACPI
86 .It subsystem
87 .Qq Li THINKPAD
88 .It type
89 The source of the event in the ACPI namespace.
90 The value depends on the model.
91 .It notify
92 Event code (see below).
93 .El
94 .Pp
95 Depending on the ThinkPad model, event codes may vary.
96 On a ThinkPad T41p these are as follows:
97 .Pp
98 .Bl -tag -width "subsystem" -offset indent -compact
99 .It Li 0x01
100 Fn + F1
101 .It Li 0x02
102 Fn + F2
103 .It Li 0x03
104 Fn + F3 (LCD backlight)
105 .It Li 0x04
106 Fn + F4 (Suspend to RAM)
107 .It Li 0x05
108 Fn + F5 (Bluetooth)
109 .It Li 0x06
110 Fn + F6
111 .It Li 0x07
112 Fn + F7 (Screen expand)
113 .It Li 0x08
114 Fn + F8
115 .It Li 0x09
116 Fn + F9
117 .It Li 0x0a
118 Fn + F10
119 .It Li 0x0b
120 Fn + F11
121 .It Li 0x0c
122 Fn + F12 (Suspend to disk)
123 .It Li 0x0d
124 Fn + Backspace
125 .It Li 0x0e
126 Fn + Insert
127 .It Li 0x0f
128 Fn + Delete
129 .It Li 0x10
130 Fn + Home (Brightness up)
131 .It Li 0x11
132 Fn + End (Brightness down)
133 .It Li 0x12
134 Fn + PageUp (ThinkLight)
135 .It Li 0x13
136 Fn + PageDown
137 .It Li 0x14
138 Fn + Space (Zoom)
139 .It Li 0x15
140 Volume Up
141 .It Li 0x16
142 Volume Down
143 .It Li 0x17
144 Mute
145 .It Li 0x18
146 Access IBM Button
147 .El
148 .\".Ss Xr led 4 Ss Interface
149 .\"The
150 .\".Nm
151 .\"driver provides a
152 .\".Xr led 4
153 .\"interface for the ThinkLight.
154 .\"The ThinkLight can be made to blink by writing
155 .\".Tn ASCII
156 .\"strings to the
157 .\".Pa /dev/led/thinklight
158 .\"device.
159 .Sh SYSCTL VARIABLES
160 The following sysctls are currently implemented:
161 .Bl -tag -width indent
162 .It Va dev.acpi_thinkpad.0.initialmask
163 (read-only)
164 Bitmask of ACPI events before the
165 .Nm
166 driver was loaded.
167 .It Va dev.acpi_thinkpad.0.availmask
168 (read-only)
169 Bitmask of all supported ACPI events.
170 .It Va dev.acpi_thinkpad.0.events
171 Enable ACPI events and set the
172 .Va eventmask
173 to
174 .Va availmask .
175 Without the
176 .Nm
177 driver being loaded, only the Fn+F4 button generates an ACPI event.
178 .It Va dev.acpi_thinkpad.0.eventmask
179 Sets the ACPI events which are reported to
180 .Xr devd 8 .
181 Fn+F3, Fn+F4 and Fn+F12 always generate ACPI events, regardless which value
182 .Va eventmask
183 has.
184 Depending on the ThinkPad model, the meaning of different bits in the
185 .Va eventmask
186 may vary.
187 On a ThinkPad T41p this is a bitwise OR of the following:
188 .Pp
189 .Bl -tag -width indent-two -compact
190 .It Li 1
191 Fn + F1
192 .It Li 2
193 Fn + F2
194 .It Li 4
195 Fn + F3 (LCD backlight)
196 .It Li 8
197 Fn + F4 (Suspend to RAM)
198 .It Li 16
199 Fn + F5 (Bluetooth)
200 .It Li 32
201 Fn + F6
202 .It Li 64
203 Fn + F7 (Screen expand)
204 .It Li 128
205 Fn + F8
206 .It Li 256
207 Fn + F9
208 .It Li 512
209 Fn + F10
210 .It Li 1024
211 Fn + F11
212 .It Li 2048
213 Fn + F12 (Suspend to disk)
214 .It Li 4096
215 Fn + Backspace
216 .It Li 8192
217 Fn + Insert
218 .It Li 16384
219 Fn + Delete
220 .It Li 32768
221 Fn + Home (Brightness up)
222 .It Li 65536
223 Fn + End (Brightness down)
224 .It Li 131072
225 Fn + PageUp (ThinkLight)
226 .It Li 262144
227 Fn + PageDown
228 .It Li 524288
229 Fn + Space (Zoom)
230 .It Li 1048576
231 Volume Up
232 .It Li 2097152
233 Volume Down
234 .It Li 4194304
235 Mute
236 .It Li 8388608
237 Access IBM Button
238 .El
239 .It Va dev.acpi_thinkpad.0.hotkey
240 (read-only)
241 Status of several buttons.
242 Every time a button is pressed, the respecting bit is toggled.
243 It is a bitwise OR of the following:
244 .Pp
245 .Bl -tag -width indent-two -compact
246 .It Li 1
247 Home Button
248 .It Li 2
249 Search Button
250 .It Li 4
251 Mail Button
252 .It Li 8
253 Access IBM Button
254 .It Li 16
255 Zoom
256 .It Li 32
257 Wireless LAN Button
258 .It Li 64
259 Video Button
260 .It Li 128
261 Hibernate Button
262 .It Li 256
263 ThinkLight Button
264 .It Li 512
265 Screen Expand
266 .It Li 1024
267 Brightness Up/Down Button
268 .It Li 2048
269 Volume Up/Down/Mute Button
270 .El
271 .It Va dev.acpi_thinkpad.0.lcd_brightness
272 Current brightness level of the display.
273 .It Va dev.acpi_thinkpad.0.volume
274 Speaker volume.
275 .It Va dev.acpi_thinkpad.0.mute
276 Indicates, whether the speakers are muted or not.
277 .It Va dev.acpi_thinkpad.0.thinklight
278 Indicates, whether the ThinkLight keyboard light is activated or not.
279 .It Va dev.acpi_thinkpad.0.bluetooth
280 Toggle Bluetooth chip activity.
281 .It Va dev.acpi_thinkpad.0.wlan
282 (read-only)
283 Indicates whether the WLAN chip is active or not.
284 .It Va dev.acpi_thinkpad.0.fan
285 Indicates whether the fan is in automatic (1) or manual (0) mode.
286 Default is automatic mode.
287 This sysctl should be used with extreme precaution, since disabling automatic
288 fan control might overheat the ThinkPad and lead to permanent damage if the
289 .Va fan_level
290 is not set accordingly.
291 .It Va dev.acpi_thinkpad.0.fan_level
292 Indicates at what speed the fan should run when being in manual mode.
293 Values are ranging from 0 (off) to 7 (max).
294 The resulting speed differs from model to model.
295 On a T41p this is as follows:
296 .Pp
297 .Bl -tag -width indent-two -compact
298 .It Li 0
299 off
300 .It Li 1, 2
301 ~3000 RPM
302 .It Li 3, 4, 5
303 ~3600 RPM
304 .It Li 6, 7
305 ~4300 RPM
306 .El
307 .It Va dev.acpi_ibm.0.fan_speed
308 (read-only)
309 Fan speed in rounds per minute.
310 A few older ThinkPads report the fan speed in levels ranging from 0 (off)
311 to 7 (max).
312 .It Va dev.acpi_ibm.0.thermal
313 (read-only)
314 Shows the readings of up to eight different temperature sensors.
315 Most ThinkPads include six or more temperature sensors but
316 only expose the CPU temperature through
317 .Xr acpi_thermal 4 .
318 Some ThinkPads have the below sensor layout which might vary depending on the
319 specific model:
320 .Pp
321 .Bl -enum -compact
322 .It
323 CPU
324 .It
325 Mini PCI Module
326 .It
327 HDD
328 .It
329 GPU
330 .It
331 Built-in battery
332 .It
333 UltraBay battery
334 .It
335 Built-in battery
336 .It
337 UltraBay battery
338 .El
339 .It Va hw.sensors.acpi_thinkpad0.tempX
340 Show the readings of up to eight different temperature sensors.
341 .It Va hw.sensors.acpi_thinkpad0.fan0
342 Fan speed in rounds per minute.
343 .\" A few older ThinkPads report the fan speed in levels ranging from 0 (off)
344 .\" to 7 (max).
345 .El
346 .Pp
347 Defaults for these sysctls can be set in
348 .Xr sysctl.conf 5 .
349 Sensors can be monitored by
350 .Xr sensorsd 8 .
351 .\".Sh FILES
352 .\".Bl -tag -width ".Pa /dev/led/thinklight"
353 .\".It Pa /dev/led/thinklight
354 .\"ThinkLight
355 .\".Xr led 4
356 .\"device node
357 .\".El
358 .Sh EXAMPLES
359 The following can be added to
360 .Xr devd.conf 5
361 in order to pass button events to a
362 .Pa /usr/local/sbin/acpi_oem_exec.sh
363 script:
364 .Bd -literal -offset indent
365 notify 10 {
366         match "system"          "ACPI";
367         match "subsystem"       "IBM";
368         action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
369 };
370 .Ed
371 .Pp
372 A possible
373 .Pa /usr/local/sbin/acpi_oem_exec.sh
374 script might look like:
375 .Bd -literal -offset indent
376 #!/bin/sh
377 #
378 if [ "$1" = "" -o "$2" = "" ]
379 then
380         echo "usage: $0 notify oem_name"
381         exit 1
382 fi
383 NOTIFY=`echo $1`
384 LOGGER="logger"
385 CALC="bc"
386 BC_PRECOMMANDS="scale=2"
387 ECHO="echo"
388 CUT="cut"
389 MAX_LCD_BRIGHTNESS=7
390 MAX_VOLUME=14
391 OEM=$2
392 DISPLAY_PIPE=/tmp/acpi_${OEM}_display
393
394 case ${NOTIFY} in
395         0x05)
396                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
397                 if [ "$LEVEL" = "1" ]
398                 then
399                         sysctl dev.acpi_${OEM}.0.bluetooth=0
400                         MESSAGE="bluetooth disabled"
401                 else
402                         sysctl dev.acpi_${OEM}.0.bluetooth=1
403                         MESSAGE="bluetooth enabled"
404                 fi
405                 ;;
406         0x10|0x11)
407                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
408                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
409                          ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
410                          ${CALC} | ${CUT} -d . -f 1`
411                 MESSAGE="brightness level ${PERCENT}%"
412                 ;;
413         0x12)
414                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
415                 if [ "$LEVEL" = "1" ]
416                 then
417                         MESSAGE="thinklight enabled"
418                 else
419                         MESSAGE="thinklight disabled"
420                 fi
421                 ;;
422         0x15|0x16)
423                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
424                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
425                         ${LEVEL} / ${MAX_VOLUME} * 100" | \\
426                          ${CALC} | ${CUT} -d . -f 1`
427                 MESSAGE="volume level ${PERCENT}%"
428                 ;;
429         0x17)
430                 LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
431                 if [ "$LEVEL" = "1" ]
432                 then
433                         MESSAGE="volume muted"
434                 else
435                         MESSAGE="volume unmuted"
436                 fi
437                 ;;
438         *)
439                 ;;
440 esac
441 ${LOGGER} ${MESSAGE}
442 if [ -p ${DISPLAY_PIPE} ]
443 then
444         ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
445 fi
446 exit 0
447 .Ed
448 .Sh SEE ALSO
449 .Xr acpi 4 ,
450 .\" .Xr led 4 ,
451 .Xr sysctl.conf 5 ,
452 .Xr devd 8 ,
453 .Xr sensorsd 8 ,
454 .Xr sysctl 8
455 .Sh HISTORY
456 The
457 .Nm
458 device driver first appeared in
459 .Fx 6.0
460 and was imported into
461 .Dx 2.1 .
462 .Sh AUTHORS
463 .An -nosplit
464 The
465 .Nm
466 driver was written by
467 .An Takanori Watanabe Aq takawata@FreeBSD.org
468 and later mostly rewritten by
469 .An Markus Brueffer Aq markus@FreeBSD.org .
470 This manual page was written by
471 .An Christian Brueffer Aq brueffer@FreeBSD.org
472 and
473 .An Markus Brueffer Aq markus@FreeBSD.org .