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