Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 69df49eb authored by Henrique de Moraes Holschuh's avatar Henrique de Moraes Holschuh
Browse files

thinkpad-acpi: update HKEY and hotkey subdriver documentation (v2) 



Update the hotkey driver documentation to match the behaviour
of the fixed NVRAM polling code.

This also documents some HKEY events such as the alarms,
which is very important information.

Signed-off-by: default avatarHenrique de Moraes Holschuh <hmh@hmh.eng.br>
parent 28999022

Documentation/laptops/thinkpad-acpi.txt

+49 −17
Original line number Original line Diff line number Diff line
@@ -292,13 +292,13 @@ sysfs notes: 




		Warning: when in NVRAM mode, the volume up/down/mute

		Warning: when in NVRAM mode, the volume up/down/mute

		keys are synthesized according to changes in the mixer,

		keys are synthesized according to changes in the mixer,

		so you have to use volume up or volume down to unmute,

		which uses a single volume up or volume down hotkey

		as per the ThinkPad volume mixer user interface.  When

		press to unmute, as per the ThinkPad volume mixer user

		in ACPI event mode, volume up/down/mute are reported as

		interface.  When in ACPI event mode, volume up/down/mute

		separate events, but this behaviour may be corrected in

		events are reported by the firmware and can behave

		future releases of this driver, in which case the

		differently (and that behaviour changes with firmware

		ThinkPad volume mixer user interface semantics will be

		version -- not just with firmware models -- as well as

		enforced.

		OSI(Linux) state).





	hotkey_poll_freq:

	hotkey_poll_freq:

		frequency in Hz for hot key polling. It must be between

		frequency in Hz for hot key polling. It must be between
@@ -309,7 +309,7 @@ sysfs notes: 
		will cause hot key presses that require NVRAM polling

		will cause hot key presses that require NVRAM polling

		to never be reported.

		to never be reported.





		Setting hotkey_poll_freq too low will cause repeated

		Setting hotkey_poll_freq too low may cause repeated

		pressings of the same hot key to be misreported as a

		pressings of the same hot key to be misreported as a

		single key press, or to not even be detected at all.

		single key press, or to not even be detected at all.

		The recommended polling frequency is 10Hz.

		The recommended polling frequency is 10Hz.
@@ -397,6 +397,7 @@ ACPI Scan 
event	code	Key		Notes

event	code	Key		Notes





0x1001	0x00	FN+F1		-

0x1001	0x00	FN+F1		-



0x1002	0x01	FN+F2		IBM: battery (rare)

0x1002	0x01	FN+F2		IBM: battery (rare)

				Lenovo: Screen lock

				Lenovo: Screen lock
@@ -404,7 +405,8 @@ event code Key Notes 
				this hot key, even with hot keys

				this hot key, even with hot keys

				disabled or with Fn+F3 masked

				disabled or with Fn+F3 masked

				off

				off

				IBM: screen lock

				IBM: screen lock, often turns

				off the ThinkLight as side-effect

				Lenovo: battery

				Lenovo: battery





0x1004	0x03	FN+F4		Sleep button (ACPI sleep button

0x1004	0x03	FN+F4		Sleep button (ACPI sleep button
@@ -433,7 +435,8 @@ event code Key Notes 
				Do you feel lucky today?

				Do you feel lucky today?





0x1008	0x07	FN+F8		IBM: toggle screen expand

0x1008	0x07	FN+F8		IBM: toggle screen expand

				Lenovo: configure UltraNav

				Lenovo: configure UltraNav,

				or toggle screen expand





0x1009	0x08	FN+F9		-

0x1009	0x08	FN+F9		-

	..	..		..

	..	..		..
@@ -444,7 +447,7 @@ event code Key Notes 
				either through the ACPI event,

				either through the ACPI event,

				or through a hotkey event.

				or through a hotkey event.

				The firmware may refuse to

				The firmware may refuse to

				generate further FN+F4 key

				generate further FN+F12 key

				press events until a S3 or S4

				press events until a S3 or S4

				ACPI sleep cycle is performed,

				ACPI sleep cycle is performed,

				or some time passes.

				or some time passes.
@@ -512,15 +515,19 @@ events for switches: 
SW_RFKILL_ALL	T60 and later hardware rfkill rocker switch

SW_RFKILL_ALL	T60 and later hardware rfkill rocker switch

SW_TABLET_MODE	Tablet ThinkPads HKEY events 0x5009 and 0x500A

SW_TABLET_MODE	Tablet ThinkPads HKEY events 0x5009 and 0x500A





Non hot-key ACPI HKEY event map:

Non hotkey ACPI HKEY event map:

-------------------------------



Events that are not propagated by the driver, except for legacy

compatibility purposes when hotkey_report_mode is set to 1:



0x5001		Lid closed

0x5001		Lid closed

0x5002		Lid opened

0x5002		Lid opened

0x5009		Tablet swivel: switched to tablet mode

0x5009		Tablet swivel: switched to tablet mode

0x500A		Tablet swivel: switched to normal mode

0x500A		Tablet swivel: switched to normal mode

0x7000		Radio Switch may have changed state

0x7000		Radio Switch may have changed state





The above events are not propagated by the driver, except for legacy

Events that are never propagated by the driver:

compatibility purposes when hotkey_report_mode is set to 1.





0x2304		System is waking up from suspend to undock

0x2304		System is waking up from suspend to undock

0x2305		System is waking up from suspend to eject bay

0x2305		System is waking up from suspend to eject bay
@@ -528,14 +535,39 @@ compatibility purposes when hotkey_report_mode is set to 1. 
0x2405		System is waking up from hibernation to eject bay

0x2405		System is waking up from hibernation to eject bay

0x5010		Brightness level changed/control event

0x5010		Brightness level changed/control event





The above events are never propagated by the driver.

Events that are propagated by the driver to userspace:





0x2313		ALARM: System is waking up from suspend because

		the battery is nearly empty

0x2413		ALARM: System is waking up from hibernation because

		the battery is nearly empty

0x3003		Bay ejection (see 0x2x05) complete, can sleep again

0x3003		Bay ejection (see 0x2x05) complete, can sleep again

0x3006		Bay hotplug request (hint to power up SATA link when

		the optical drive tray is ejected)

0x4003		Undocked (see 0x2x04), can sleep again

0x4003		Undocked (see 0x2x04), can sleep again

0x500B		Tablet pen inserted into its storage bay

0x500B		Tablet pen inserted into its storage bay

0x500C		Tablet pen removed from its storage bay

0x500C		Tablet pen removed from its storage bay



0x6011		ALARM: battery is too hot

The above events are propagated by the driver.

0x6012		ALARM: battery is extremely hot

0x6021		ALARM: a sensor is too hot

0x6022		ALARM: a sensor is extremely hot

0x6030		System thermal table changed



Battery nearly empty alarms are a last resort attempt to get the

operating system to hibernate or shutdown cleanly (0x2313), or shutdown

cleanly (0x2413) before power is lost.  They must be acted upon, as the

wake up caused by the firmware will have negated most safety nets...



When any of the "too hot" alarms happen, according to Lenovo the user

should suspend or hibernate the laptop (and in the case of battery

alarms, unplug the AC adapter) to let it cool down.  These alarms do

signal that something is wrong, they should never happen on normal

operating conditions.



The "extremely hot" alarms are emergencies.  According to Lenovo, the

operating system is to force either an immediate suspend or hibernate

cycle, or a system shutdown.  Obviously, something is very wrong if this

happens.





Compatibility notes:

Compatibility notes: