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