d26d7e611371b8a309c9ced1e94928e7b5349aa0
[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: head/share/man/man4/acpi_ibm.4 237509 2012-06-23 20:44:45Z joel $
27 .\"
28 .Dd October 19, 2014
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 hw.acpi.thinkpad.initialmask
163 (read-only)
164 Bitmask of ACPI events before the
165 .Nm
166 driver was loaded.
167 .It Va hw.acpi.thinkpad.availmask
168 (read-only)
169 Bitmask of all supported ACPI events.
170 .It Va hw.acpi.thinkpad.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 hw.acpi.thinkpad.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 hw.acpi.thinkpad.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 hw.acpi.thinkpad.lcd_brightness
272 Current brightness level of the display.
273 .It Va hw.acpi.thinkpad.volume
274 Speaker volume.
275 .It Va hw.acpi.thinkpad.mute
276 Indicates, whether the speakers are muted or not.
277 .It Va hw.acpi.thinkpad.thinklight
278 Indicates, whether the ThinkLight keyboard light is activated or not.
279 .It Va hw.acpi.thinkpad.bluetooth
280 Toggle Bluetooth chip activity.
281 .It Va hw.acpi.thinkpad.wlan
282 (read-only)
283 Indicates whether the WLAN chip is active or not.
284 .It Va hw.acpi.thinkpad.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 hw.acpi.thinkpad.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 hw.acpi.thinkpad.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 hw.acpi.thinkpad.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.acpi.thinkpad.handlerevents
340 .Xr devd 8
341 events handled by
342 .Nm
343 when
344 .Va events
345 is set to 1.
346 Events are specified as a whitespace-separated list of event code in
347 hexadecimal or decimal form.
348 Note that the event may be handled twice (eg. Brightness up/down) if ACPI BIOS
349 already handled the event.
350 .It Va hw.sensors.acpi_thinkpad0.tempX
351 Show the readings of up to eight different temperature sensors.
352 .It Va hw.sensors.acpi_thinkpad0.fan0
353 Fan speed in rounds per minute.
354 .\" A few older ThinkPads report the fan speed in levels ranging from 0 (off)
355 .\" to 7 (max).
356 .El
357 .Pp
358 Defaults for these sysctls can be set in
359 .Xr sysctl.conf 5 .
360 Sensors can be monitored by
361 .Xr sensorsd 8 .
362 .Sh FILES
363 .Bl -tag -width ".Pa /dev/led/thinklight"
364 .It Pa /dev/led/thinklight
365 ThinkLight
366 .Xr led 4
367 device node
368 .El
369 .Sh EXAMPLES
370 The following can be added to
371 .Xr devd.conf 5
372 in order to pass button events to a
373 .Pa /usr/local/sbin/acpi_oem_exec.sh
374 script:
375 .Bd -literal -offset indent
376 notify 10 {
377         match "system"          "ACPI";
378         match "subsystem"       "IBM";
379         action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
380 };
381 .Ed
382 .Pp
383 A possible
384 .Pa /usr/local/sbin/acpi_oem_exec.sh
385 script might look like:
386 .Bd -literal -offset indent
387 #!/bin/sh
388 #
389 if [ "$1" = "" -o "$2" = "" ]
390 then
391         echo "usage: $0 notify oem_name"
392         exit 1
393 fi
394 NOTIFY=`echo $1`
395 LOGGER="logger"
396 CALC="bc"
397 BC_PRECOMMANDS="scale=2"
398 ECHO="echo"
399 CUT="cut"
400 MAX_LCD_BRIGHTNESS=7
401 MAX_VOLUME=14
402 OEM=$2
403 DISPLAY_PIPE=/tmp/acpi_${OEM}_display
404
405 case ${NOTIFY} in
406         0x05)
407                 LEVEL=`sysctl -n hw.acpi.${OEM}.bluetooth`
408                 if [ "$LEVEL" = "1" ]
409                 then
410                         sysctl hw.acpi.${OEM}.bluetooth=0
411                         MESSAGE="bluetooth disabled"
412                 else
413                         sysctl hw.acpi.${OEM}.bluetooth=1
414                         MESSAGE="bluetooth enabled"
415                 fi
416                 ;;
417         0x10|0x11)
418                 LEVEL=`sysctl -n hw.acpi.${OEM}.lcd_brightness`
419                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
420                          ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
421                          ${CALC} | ${CUT} -d . -f 1`
422                 MESSAGE="brightness level ${PERCENT}%"
423                 ;;
424         0x12)
425                 LEVEL=`sysctl -n hw.acpi.${OEM}.thinklight`
426                 if [ "$LEVEL" = "1" ]
427                 then
428                         MESSAGE="thinklight enabled"
429                 else
430                         MESSAGE="thinklight disabled"
431                 fi
432                 ;;
433         0x15|0x16)
434                 LEVEL=`sysctl -n hw.acpi.${OEM}.volume`
435                 PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
436                         ${LEVEL} / ${MAX_VOLUME} * 100" | \\
437                          ${CALC} | ${CUT} -d . -f 1`
438                 MESSAGE="volume level ${PERCENT}%"
439                 ;;
440         0x17)
441                 LEVEL=`sysctl -n hw.acpi.${OEM}.mute`
442                 if [ "$LEVEL" = "1" ]
443                 then
444                         MESSAGE="volume muted"
445                 else
446                         MESSAGE="volume unmuted"
447                 fi
448                 ;;
449         *)
450                 ;;
451 esac
452 ${LOGGER} ${MESSAGE}
453 if [ -p ${DISPLAY_PIPE} ]
454 then
455         ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
456 fi
457 exit 0
458 .Ed
459 .Pp
460 The following example specify that event code 0x04 (Suspend to RAM),
461 0x10 (Brightness up) and 0x11 (Brightness down) are handled by
462 .Nm .
463 .Bd -literal -offset indent
464 sysctl hw.acpi.thinkpad.handlerevents='0x04 0x10 0x11'
465 .Ed
466 .Pp
467 in
468 .Xr sysctl.conf 5 :
469 .Bd -literal -offset indent
470 hw.acpi.thinkpad.handlerevents=0x04\\ 0x10\\ 0x11
471 .Ed
472 .Sh SEE ALSO
473 .Xr acpi 4 ,
474 .Xr led 4 ,
475 .Xr sysctl.conf 5 ,
476 .Xr devd 8 ,
477 .Xr sensorsd 8 ,
478 .Xr sysctl 8
479 .Sh HISTORY
480 The
481 .Nm
482 device driver first appeared in
483 .Fx 6.0
484 and was imported into
485 .Dx 2.1 .
486 .Sh AUTHORS
487 .An -nosplit
488 The
489 .Nm
490 driver was written by
491 .An Takanori Watanabe Aq Mt takawata@FreeBSD.org
492 and later mostly rewritten by
493 .An Markus Brueffer Aq Mt markus@FreeBSD.org .
494 This manual page was written by
495 .An Christian Brueffer Aq Mt brueffer@FreeBSD.org
496 and
497 .An Markus Brueffer Aq Mt markus@FreeBSD.org .