xref: /freebsd/share/man/man4/acpi_ibm.4 (revision 5f31d14a92353b6b0acf6960511b3acf3911d163) 
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.\"
28.Dd March 13, 2022
29.Dt ACPI_IBM 4
30.Os
31.Sh NAME
32.Nm acpi_ibm
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_ibm"
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_ibm_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 IBM
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 IBM 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_ibm.0.initialmask
162(read-only)
163Bitmask of ACPI events before the
164.Nm
165driver was loaded.
166.It Va dev.acpi_ibm.0.availmask
167(read-only)
168Bitmask of all supported ACPI events.
169.It Va dev.acpi_ibm.0.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_ibm.0.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 IBM Button
237.El
238.It Va dev.acpi_ibm.0.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 IBM 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_ibm.0.lcd_brightness
271Current brightness level of the display.
272.It Va dev.acpi_ibm.0.volume
273Speaker volume.
274.It Va dev.acpi_ibm.0.mute
275Indicates, whether the speakers are muted or not.
276.It Va dev.acpi_ibm.0.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_ibm.0.thinklight
280Indicates, whether the ThinkLight keyboard light is activated or not.
281.It Va dev.acpi_ibm.0.bluetooth
282Toggle Bluetooth chip activity.
283.It Va dev.acpi_ibm.0.wlan
284(read-only)
285Indicates whether the WLAN chip is active or not.
286.It Va dev.acpi_ibm.0.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_ibm.0.fan_level
294Indicates at what speed the fan should run when being in manual mode.
295Valid values range from 0 (off) to 7 (max) and 8.
296Level 8 is used by the driver to set the fan in unthrottled mode.
297In this mode, the fan is set to spin freely and will quickly reach a very
298high speed.
299Use this mode only if absolutely necessary, e.g., if the system has reached its
300critical temperature and it is about to shut down.
301The resulting speed differs from model to model.
302On a T41p this is as follows:
303.Pp
304.Bl -tag -width indent-two -compact
305.It Li 0
306off
307.It Li 1, 2
308~3000 RPM
309.It Li 3, 4, 5
310~3600 RPM
311.It Li 6, 7
312~4300 RPM
313.It Li 8
314~6400 RPM (Full-speed, unthrottled)
315.El
316.It Va dev.acpi_ibm.0.fan_speed
317(read-only)
318Fan speed in rounds per minute.
319A few older ThinkPads report the fan speed in levels ranging from 0 (off)
320to 7 (max).
321.It Va dev.acpi_ibm.0.thermal
322(read-only)
323Shows the readings of up to eight different temperature sensors.
324Most ThinkPads include six or more temperature sensors but
325only expose the CPU temperature through
326.Xr acpi_thermal 4 .
327Some ThinkPads have the below sensor layout which might vary depending on the
328specific model:
329.Pp
330.Bl -enum -compact
331.It
332CPU
333.It
334Mini PCI Module
335.It
336HDD
337.It
338GPU
339.It
340Built-in battery
341.It
342UltraBay battery
343.It
344Built-in battery
345.It
346UltraBay battery
347.El
348.It Va dev.acpi_ibm.0.handlerevents
349.Xr devd 8
350events handled by
351.Nm
352when
353.Va events
354is set to 1.
355Events are specified as a whitespace-separated list of event code in
356hexadecimal or decimal form.
357Note that the event maybe handled twice (e.g., Brightness up/down) if ACPI BIOS
358already handled the event.
359.El
360.Pp
361Defaults for these sysctls can be set in
362.Xr sysctl.conf 5 .
363.Sh FILES
364.Bl -tag -width ".Pa /dev/led/thinklight"
365.It Pa /dev/led/thinklight
366ThinkLight
367.Xr led 4
368device node
369.El
370.Sh EXAMPLES
371The following can be added to
372.Xr devd.conf 5
373in order to pass button events to a
374.Pa /usr/local/sbin/acpi_oem_exec.sh
375script:
376.Bd -literal -offset indent
377notify 10 {
378        match "system"          "ACPI";
379        match "subsystem"       "IBM";
380        action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
381};
382.Ed
383.Pp
384A possible
385.Pa /usr/local/sbin/acpi_oem_exec.sh
386script might look like:
387.Bd -literal -offset indent
388#!/bin/sh
389#
390if [ "$1" = "" -o "$2" = "" ]
391then
392        echo "usage: $0 notify oem_name"
393        exit 1
394fi
395NOTIFY=`echo $1`
396LOGGER="logger"
397CALC="bc"
398BC_PRECOMMANDS="scale=2"
399ECHO="echo"
400CUT="cut"
401MAX_LCD_BRIGHTNESS=7
402MAX_VOLUME=14
403OEM=$2
404DISPLAY_PIPE=/tmp/acpi_${OEM}_display
405
406case ${NOTIFY} in
407        0x05)
408                LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
409                if [ "$LEVEL" = "1" ]
410                then
411                        sysctl dev.acpi_${OEM}.0.bluetooth=0
412                        MESSAGE="bluetooth disabled"
413                else
414                        sysctl dev.acpi_${OEM}.0.bluetooth=1
415                        MESSAGE="bluetooth enabled"
416                fi
417                ;;
418        0x10|0x11)
419                LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
420                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
421                         ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
422                         ${CALC} | ${CUT} -d . -f 1`
423                MESSAGE="brightness level ${PERCENT}%"
424                ;;
425        0x12)
426                LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
427                if [ "$LEVEL" = "1" ]
428                then
429                        MESSAGE="thinklight enabled"
430                else
431                        MESSAGE="thinklight disabled"
432                fi
433                ;;
434        0x15|0x16)
435                LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
436                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
437                        ${LEVEL} / ${MAX_VOLUME} * 100" | \\
438                         ${CALC} | ${CUT} -d . -f 1`
439                MESSAGE="volume level ${PERCENT}%"
440                ;;
441        0x17)
442                LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
443                if [ "$LEVEL" = "1" ]
444                then
445                        MESSAGE="volume muted"
446                else
447                        MESSAGE="volume unmuted"
448                fi
449                ;;
450	0x1b)
451		LEVEL=`sysctl -n dev.acpi_ibm.0.mic_led`
452		if [ $LEVEL -eq 0 ]; then
453			sysctl dev.acpi_ibm.0.mic_led=1
454			mixer rec.volume=0
455		fi
456		if [ $LEVEL -eq 1 ]; then
457			sysctl dev.acpi_ibm.0.mic_led=0
458			mixer rec.volume=30
459		fi
460		;;
461        *)
462                ;;
463esac
464${LOGGER} ${MESSAGE}
465if [ -p ${DISPLAY_PIPE} ]
466then
467        ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
468fi
469exit 0
470.Ed
471.Pp
472The following example specify that event code 0x04 (Suspend to RAM),
4730x10 (Brightness up) and 0x11 (Brightness down) are handled by
474.Nm .
475.Bd -literal -offset indent
476sysctl dev.acpi_ibm.0.handlerevents='0x04 0x10 0x11'
477.Ed
478.Pp
479in
480.Xr sysctl.conf 5 :
481.Bd -literal -offset indent
482dev.acpi_ibm.0.handlerevents=0x04\\ 0x10\\ 0x11
483.Ed
484.Sh SEE ALSO
485.Xr acpi 4 ,
486.Xr led 4 ,
487.Xr sysctl.conf 5 ,
488.Xr devd 8 ,
489.Xr sysctl 8
490.Sh HISTORY
491The
492.Nm
493device driver first appeared in
494.Fx 6.0 .
495.Sh AUTHORS
496.An -nosplit
497The
498.Nm
499driver was written by
500.An Takanori Watanabe Aq Mt takawata@FreeBSD.org
501and later mostly rewritten by
502.An Markus Brueffer Aq Mt markus@FreeBSD.org .
503This manual page was written by
504.An Christian Brueffer Aq Mt brueffer@FreeBSD.org
505and
506.An Markus Brueffer Aq Mt markus@FreeBSD.org .
507