- Clarify how events are used and how the different event sysctl correlate

- Document how an event looks like that is received by devd(8) from acpi_ibm(4)
- Document the event codes as they occur on a T41p
- Add a note about sysctl.conf and an Xref to it
- Add an example section providing an example script and an entry for
  devd.conf. This is an adapted version of the one in acpi_fujitsu(4).
- s/Fn-F4/Fn+F4/ for consistency sake
- Add a button description where refering to a T41p, remove it otherwise,
  since it might vary from model to model
- Bump .Dd

Thanks for improvements to: brueffer, ru

Approved by:	brueffer

1 files changed, 193 insertions, 12 deletions

diff --git a/share/man/man4/man4.i386/acpi_ibm.4 b/share/man/man4/man4.i386/acpi_ibm.4
index 3035c63..0dccf38 100644
--- a/share/man/man4/man4.i386/acpi_ibm.4
+++ b/share/man/man4/man4.i386/acpi_ibm.4
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 9, 2005
+.Dd August 11, 2005
 .Dt ACPI_IBM 4 i386
 .Os
 .Sh NAME
@@ -44,6 +44,94 @@ and
 .Xr devd 8 ,
 through which applications can determine the status of
 various laptop components.
+.Pp
+While the
+.Xr sysctl 8
+interface is enabled automatically after loading the driver, the
+.Xr devd 8
+interface has to be enabled explicitly, as it may alter the default action of
+certain keys.
+This is done by setting the
+.Va events
+sysctl as described below.
+Specifying which keys should generate events is done by setting a bitmask,
+whereas each bit represents one key or key combination.
+This bitmask, accessible via the
+.Va eventmask
+sysctl, is set to
+.Va availmask
+by default, a value representing all possible keypress events on the specific
+ThinkPad model.
+.Ss Xr devd 8 Ss Events
+Hotkey events received by
+.Xr devd 8
+provide the following information:
+.Pp
+.Bl -tag -width "subsystem" -offset indent -compact
+.It system
+.Qq Li ACPI
+.It subsystem
+.Qq Li IBM
+.It type
+The source of the event in the ACPI namespace.
+The value depends on the model.
+.It notify
+Event code (see below).
+.El
+.Pp
+Depending on the ThinkPad model, event codes may vary.
+On a ThinkPad T41p these are as follows:
+.Pp
+.Bl -tag -width "subsystem" -offset indent -compact
+.It Li 0x01
+Fn + F1
+.It Li 0x02
+Fn + F2
+.It Li 0x03
+Fn + F3 (LCD backlight)
+.It Li 0x04
+Fn + F4 (Suspend to RAM)
+.It Li 0x05
+Fn + F5 (Bluetooth)
+.It Li 0x06
+Fn + F6
+.It Li 0x07
+Fn + F7 (Screen expand)
+.It Li 0x08
+Fn + F8
+.It Li 0x09
+Fn + F9
+.It Li 0x0a
+Fn + F10
+.It Li 0x0b
+Fn + F11
+.It Li 0x0c
+Fn + F12 (Suspend to disk)
+.It Li 0x0d
+Fn + Backspace
+.It Li 0x0e
+Fn + Insert
+.It Li 0x0f
+Fn + Delete
+.It Li 0x10
+Fn + Home (Brightness up)
+.It Li 0x11
+Fn + End (Brightness down)
+.It Li 0x12
+Fn + PageUp (ThinkLight)
+.It Li 0x13
+Fn + PageDown
+.It Li 0x14
+Fn + Space (Zoom)
+.It Li 0x15
+Volume Up
+.It Li 0x16
+Volume Down
+.It Li 0x17
+Mute
+.It Li 0x18
+Access IBM Button
+.El
 .Sh SYSCTL VARIABLES
 The following sysctls are currently implemented:
 .Bl -tag -width indent
@@ -62,7 +150,7 @@ to
 .Va availmask .
 Without the
 .Nm
-driver being loaded, only the Fn-F4 button generates an ACPI event.
+driver being loaded, only the Fn+F4 button generates an ACPI event.
 .It Va dev.acpi_ibm.0.eventmask
 Sets the ACPI events which are reported to
 .Xr devd 8 .
@@ -80,15 +168,15 @@ Fn + F1
 .It Li 2
 Fn + F2
 .It Li 4
-Fn + F3
+Fn + F3 (LCD backlight)
 .It Li 8
-Fn + F4
+Fn + F4 (Suspend to RAM)
 .It Li 16
-Fn + F5
+Fn + F5 (Bluetooth)
 .It Li 32
 Fn + F6
 .It Li 64
-Fn + F7
+Fn + F7 (Screen expand)
 .It Li 128
 Fn + F8
 .It Li 256
@@ -98,7 +186,7 @@ Fn + F10
 .It Li 1024
 Fn + F11
 .It Li 2048
-Fn + F12
+Fn + F12 (Suspend to disk)
 .It Li 4096
 Fn + Backspace
 .It Li 8192
@@ -106,11 +194,11 @@ Fn + Insert
 .It Li 16384
 Fn + Delete
 .It Li 32768
-Fn + Home (Brightness Up)
+Fn + Home (Brightness up)
 .It Li 65536
-Fn + End (Brightness Down)
+Fn + End (Brightness down)
 .It Li 131072
-Fn + PageUp
+Fn + PageUp (ThinkLight)
 .It Li 262144
 Fn + PageDown
 .It Li 524288
@@ -140,7 +228,7 @@ Mail Button
 .It Li 8
 Access IBM Button
 .It Li 16
-Zoom (Fn + Space)
+Zoom
 .It Li 32
 Wireless LAN Button
 .It Li 64
@@ -150,7 +238,7 @@ Hibernate Button
 .It Li 256
 ThinkLight Button
 .It Li 512
-Screen Expand (Fn + F8)
+Screen Expand
 .It Li 1024
 Brightness Up/Down Button
 .It Li 2048
@@ -205,8 +293,101 @@ Built-in battery
 UltraBay battery
 .El
 .El
+.Pp
+Defaults for these sysctls can be set in
+.Xr sysctl.conf 5 .
+.Sh EXAMPLES
+The following can be added to
+.Xr devd.conf 5
+in order to pass button events to a
+.Pa /usr/local/sbin/acpi_oem_exec.sh
+script:
+.Bd -literal -offset indent
+notify 10 {
+        match "system"          "ACPI";
+        match "subsystem"       "IBM";
+        action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm";
+};
+.Ed
+.Pp
+A possible
+.Pa /usr/local/sbin/acpi_oem_exec.sh
+script might look like:
+.Bd -literal -offset indent
+#!/bin/sh
+#
+if [ "$1" = "" -o "$2" = "" ]
+then
+        echo "usage: $0 notify oem_name"
+        exit 1
+fi
+NOTIFY=`echo $1`
+LOGGER="logger"
+CALC="bc"
+BC_PRECOMMANDS="scale=2"
+ECHO="echo"
+CUT="cut"
+MAX_LCD_BRIGHTNESS=7
+MAX_VOLUME=14
+OEM=$2
+DISPLAY_PIPE=/tmp/acpi_${OEM}_display
+
+case ${NOTIFY} in
+        0x05)
+                LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth`
+                if [ "$LEVEL" = "1" ]
+                then
+                        sysctl dev.acpi_${OEM}.0.bluetooth=0
+                        MESSAGE="bluetooth disabled"
+                else
+                        sysctl dev.acpi_${OEM}.0.bluetooth=1
+                        MESSAGE="bluetooth enabled"
+                fi
+        0x10|0x11)
+                LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness`
+                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
+                         ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\
+                         ${CALC} | ${CUT} -d . -f 1`
+                MESSAGE="brightness level ${PERCENT}%"
+                ;;
+        0x12)
+                LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight`
+                if [ "$LEVEL" = "1" ]
+                then
+                        MESSAGE="thinklight enabled"
+                else
+                        MESSAGE="thinklight disabled"
+                fi
+                ;;
+        0x15|0x16)
+                LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume`
+                PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\
+                        ${LEVEL} / ${MAX_VOLUME} * 100" | \\
+                         ${CALC} | ${CUT} -d . -f 1`
+                MESSAGE="volume level ${PERCENT}%"
+                ;;
+        0x17)
+                LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute`
+                if [ "$LEVEL" = "1" ]
+                then
+                        MESSAGE="volume muted"
+                else
+                        MESSAGE="volume unmuted"
+                fi
+                ;;
+        *)
+                ;;
+esac
+${LOGGER} ${MESSAGE}
+if [ -p ${DISPLAY_PIPE} ]
+then
+        ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} &
+fi
+exit 0
+.Ed
 .Sh SEE ALSO
 .Xr acpi 4 ,
+.Xr sysctl.conf 5 ,
 .Xr devd 8 ,
 .Xr sysctl 8
 .Sh HISTORY