ACPI: thinkpad-acpi: document keymap gotcha's (v2)

Publish the requirements for keymap changes.  This is a documentation
change, only.

Currently, people look at the thinkpad-acpi default keymaps, and think:
"modifying this is a trivial thing, it can't break systems, and there are
keys defined for foo and bar, but the driver has them as KEY_RESERVED.
Must have been an oversight, let me change it."

And since they never get to see the bug reports, because they are not
really a part of the Linux ThinkPad users community (linux-thinkpad
mailinglist, thinkwiki wiki, thinkpad forums) and laptop users are slow
to complain to distros about any breakages...

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
Signed-off-by: Len Brown <len.brown@intel.com>
This commit is contained in:
Henrique de Moraes Holschuh 2008-01-08 13:02:38 -02:00 committed by Len Brown
parent aa62999269
commit 0f089147e6

View file

@ -954,26 +954,67 @@ static struct attribute *hotkey_mask_attributes[] __initdata = {
static int __init hotkey_init(struct ibm_init_struct *iibm)
{
/* Requirements for changing the default keymaps:
*
* 1. Many of the keys are mapped to KEY_RESERVED for very
* good reasons. Do not change them unless you have deep
* knowledge on the IBM and Lenovo ThinkPad firmware for
* the various ThinkPad models. The driver behaves
* differently for KEY_RESERVED: such keys have their
* hot key mask *unset* in mask_recommended, and also
* in the initial hot key mask programmed into the
* firmware at driver load time, which means the firm-
* ware may react very differently if you change them to
* something else;
*
* 2. You must be subscribed to the linux-thinkpad and
* ibm-acpi-devel mailing lists, and you should read the
* list archives since 2007 if you want to change the
* keymaps. This requirement exists so that you will
* know the past history of problems with the thinkpad-
* acpi driver keymaps, and also that you will be
* listening to any bug reports;
*
* 3. Do not send thinkpad-acpi specific patches directly to
* for merging, *ever*. Send them to the linux-acpi
* mailinglist for comments. Merging is to be done only
* through acpi-test and the ACPI maintainer.
*
* If the above is too much to ask, don't change the keymap.
* Ask the thinkpad-acpi maintainer to do it, instead.
*/
static u16 ibm_keycode_map[] __initdata = {
/* Scan Codes 0x00 to 0x0B: ACPI HKEY FN+F1..F12 */
KEY_FN_F1, KEY_FN_F2, KEY_COFFEE, KEY_SLEEP,
KEY_WLAN, KEY_FN_F6, KEY_SWITCHVIDEOMODE, KEY_FN_F8,
KEY_FN_F9, KEY_FN_F10, KEY_FN_F11, KEY_SUSPEND,
/* Scan codes 0x0C to 0x0F: Other ACPI HKEY hot keys */
/* Scan codes 0x0C to 0x1F: Other ACPI HKEY hot keys */
KEY_UNKNOWN, /* 0x0C: FN+BACKSPACE */
KEY_UNKNOWN, /* 0x0D: FN+INSERT */
KEY_UNKNOWN, /* 0x0E: FN+DELETE */
/* brightness: firmware always reacts to them, unless
* X.org did some tricks in the radeon BIOS scratch
* registers of *some* models */
KEY_RESERVED, /* 0x0F: FN+HOME (brightness up) */
/* Scan codes 0x10 to 0x1F: Extended ACPI HKEY hot keys */
KEY_RESERVED, /* 0x10: FN+END (brightness down) */
/* Thinklight: firmware always react to it */
KEY_RESERVED, /* 0x11: FN+PGUP (thinklight toggle) */
KEY_UNKNOWN, /* 0x12: FN+PGDOWN */
KEY_ZOOM, /* 0x13: FN+SPACE (zoom) */
/* Volume: firmware always react to it and reprograms
* the built-in *extra* mixer. Never map it to control
* another mixer by default. */
KEY_RESERVED, /* 0x14: VOLUME UP */
KEY_RESERVED, /* 0x15: VOLUME DOWN */
KEY_RESERVED, /* 0x16: MUTE */
KEY_VENDOR, /* 0x17: Thinkpad/AccessIBM/Lenovo */
/* (assignments unknown, please report if found) */
KEY_UNKNOWN, KEY_UNKNOWN, KEY_UNKNOWN, KEY_UNKNOWN,
KEY_UNKNOWN, KEY_UNKNOWN, KEY_UNKNOWN, KEY_UNKNOWN,
@ -983,20 +1024,37 @@ static int __init hotkey_init(struct ibm_init_struct *iibm)
KEY_FN_F1, KEY_COFFEE, KEY_BATTERY, KEY_SLEEP,
KEY_WLAN, KEY_FN_F6, KEY_SWITCHVIDEOMODE, KEY_FN_F8,
KEY_FN_F9, KEY_FN_F10, KEY_FN_F11, KEY_SUSPEND,
/* Scan codes 0x0C to 0x0F: Other ACPI HKEY hot keys */
/* Scan codes 0x0C to 0x1F: Other ACPI HKEY hot keys */
KEY_UNKNOWN, /* 0x0C: FN+BACKSPACE */
KEY_UNKNOWN, /* 0x0D: FN+INSERT */
KEY_UNKNOWN, /* 0x0E: FN+DELETE */
KEY_RESERVED, /* 0x0F: FN+HOME (brightness up) */
/* Scan codes 0x10 to 0x1F: Extended ACPI HKEY hot keys */
KEY_RESERVED, /* 0x10: FN+END (brightness down) */
KEY_RESERVED, /* 0x11: FN+PGUP (thinklight toggle) */
KEY_UNKNOWN, /* 0x12: FN+PGDOWN */
KEY_ZOOM, /* 0x13: FN+SPACE (zoom) */
/* Volume: z60/z61, T60 (BIOS version?): firmware always
* react to it and reprograms the built-in *extra* mixer.
* Never map it to control another mixer by default.
*
* T60?, T61, R60?, R61: firmware and EC tries to send
* these over the regular keyboard, so these are no-ops,
* but there are still weird bugs re. MUTE, so do not
* change unless you get test reports from all Lenovo
* models. May cause the BIOS to interfere with the
* HDA mixer.
*/
KEY_RESERVED, /* 0x14: VOLUME UP */
KEY_RESERVED, /* 0x15: VOLUME DOWN */
KEY_RESERVED, /* 0x16: MUTE */
KEY_VENDOR, /* 0x17: Thinkpad/AccessIBM/Lenovo */
/* (assignments unknown, please report if found) */
KEY_UNKNOWN, KEY_UNKNOWN, KEY_UNKNOWN, KEY_UNKNOWN,
KEY_UNKNOWN, KEY_UNKNOWN, KEY_UNKNOWN, KEY_UNKNOWN,