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