Commit 0f089147 authored by Henrique de Moraes Holschuh's avatar Henrique de Moraes Holschuh Committed by Len Brown
Browse files

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: default avatarHenrique de Moraes Holschuh <hmh@hmh.eng.br>
Signed-off-by: default avatarLen Brown <len.brown@intel.com>
parent aa629992

drivers/misc/thinkpad_acpi.c

+63 −5
Original line number Diff line number Diff line
@@ -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,

CRA Git | Maintained and supported by SUSTech CRA and CCSE