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