[ltp] [patch 07/11] ibm-acpi: document fan control

[Henrique de Moraes Holschuh]

This patch documents the ThinkPad fan control strategies.  Source of the data:
0. ibm-acpi source
1. DSDTs for various ThinkPads (770, X31, X40, T43)
2. http://thinkwiki.org/wiki/Embedded_Controller_Firmware#Firmware_Issues
3. http://thinkwiki.org/wiki/How_to_control_fan_speed
4. Various threads about windows fan control utilities in thinkpads.com

Signed-off-by: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
---
 drivers/acpi/ibm_acpi.c |   82 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

Index: 2.6.18/drivers/acpi/ibm_acpi.c
===================================================================
--- 2.6.18.orig/drivers/acpi/ibm_acpi.c
+++ 2.6.18/drivers/acpi/ibm_acpi.c
@@ -225,6 +225,82 @@ enum thermal_access_mode {
 	IBMACPI_THERMAL_TPEC_16,	/* Use ACPI EC regs, 16 sensors */
 };
 
+/*
+ * FAN ACCESS MODES
+ *
+ * IBMACPI_FAN_RD_ACPI_GFAN:
+ * 	ACPI GFAN method: returns fan level
+ *
+ * 	see IBMACPI_FAN_WR_ACPI_SFAN
+ * 	EC 0x2f not available if GFAN exists
+ *
+ * IBMACPI_FAN_WR_ACPI_SFAN:
+ * 	ACPI SFAN method: sets fan level, 0 (stop) to 7 (max)
+ *
+ * 	EC 0x2f might be available *for reading*, but never for
+ * 	writing.
+ *
+ * IBMACPI_FAN_WR_TPEC:
+ * 	ThinkPad EC register 0x2f (HFSP): fan control loop mode
+ * 	Supported on almost all ThinkPads
+ *
+ * 	Reading is not available if GFAN exists.
+ * 	Writing is not available if SFAN exists.
+ *
+ * 	Bits
+ *	 7	automatic mode engaged;
+ *  		(default operation mode of the ThinkPad)
+ * 		fan level is ignored in this mode.
+ *	 6	disengage mode (takes precedence over bit 7);
+ *		not available on all thinkpads.  Disables
+ *		tachometer, and speeds up fan to 100% duty-cycle,
+ *		which speeds it up FAR above the standard RPM
+ *		levels.  May damage the hardware.
+ *	5-3	either unused or fan level
+ *	2-0	fan level (0..7 usually)
+ *			0x00 = stop
+ * 			0x07 = max (set when temperatures critical)
+ * 		Some ThinkPads may have other levels, see
+ * 		IBMACPI_FAN_WR_ACPI_FANS (X31/X40)
+ *
+ *	FIRMWARE BUG: on some models, EC 0x2f might not be initialized
+ *	at boot. Apparently the EC does not intialize it, so unless ACPI
+ *	DSDT does so, its initial value is meaningless.
+ *
+ *	ThinkPad EC register 0x84 (LSB), 0x85 (MSB):
+ *	Main fan tachometer reading (in RPM)
+ *
+ *	FIRMWARE BUG: always read 0x84 first, otherwise incorrect
+ *	readings might result
+ *
+ *	FIRMWARE BUG: when EC 0x2f bit 6 is set, this register is not
+ *	invalidated.
+ *
+ *	For firmware bugs, refer to:
+ *	http://thinkwiki.org/wiki/Embedded_Controller_Firmware#Firmware_Issues
+ *
+ * IBMACPI_FAN_WR_ACPI_FANS:
+ *	ThinkPad X31, X40
+ *
+ *	FANS ACPI handle: takes three arguments:
+ *	low speed, medium speed, high speed.  ACPI DSDT seems to
+ *	map these three speeds to levels as follows:
+ *	STOP LOW LOW MED MED HIGH HIGH HIGH HIGH
+ *	(this map is stored on FAN0..FAN8 as "0,1,1,2,2,3,3,3,3")
+ *
+ * 	The speeds are stored on handles
+ * 	(FANA:FAN9), (FANC:FANB), (FANE:FAND).
+ *
+ * 	There are three default speed sets, acessible as handles:
+ * 	FS1L,FS1M,FS1H; FS2L,FS2M,FS2H; FS3L,FS3M,FS3H
+ *
+ * 	ACPI DSDT switches which set is in use depending on
+ * 	various factors.
+ *
+ * 	IBMACPI_FAN_WR_TPEC is also available and should be used
+ * 	to command the fan.  The X31/X40 seems to have 8 fan levels.
+ */
+
 enum fan_status_access_mode {
 	IBMACPI_FAN_NONE = 0,		/* No fan status or control */
 	IBMACPI_FAN_RD_ACPI_GFAN,	/* Use ACPI GFAN */
@@ -1689,6 +1765,9 @@ static int fan_read(char *p)
 	int len = 0;
 	u8 lo, hi, status;
 
+	/* TODO:
+	 * Add IBMACPI_FAN_RD_ACPI_FANS ? */
+
 	switch (fan_status_access_mode) {
 	case IBMACPI_FAN_RD_ACPI_GFAN:
 		/* 570, 600e/x, 770e, 770x */
@@ -1803,6 +1882,9 @@ static int fan_write_cmd_speed(const cha
 {
 	int speed;
 
+	/* TODO:
+	 * Support speed <low> <medium> <high> ? */
+
 	if (sscanf(cmd, "speed %d", &speed) != 1)
 		return 0;
 

--
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh