Merge branch 'release' of git://git.kernel.org/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6

Linux ACPI Custom Control Method How To

=======================================

Written by Zhang Rui <rui.zhang@intel.com>

Linux supports customizing ACPI control methods at runtime.

Users can use this to

1. override an existing method which may not work correctly,

   or just for debugging purposes.

2. insert a completely new method in order to create a missing

   method such as _OFF, _ON, _STA, _INI, etc.

For these cases, it is far simpler to dynamically install a single

control method rather than override the entire DSDT, because kernel

rebuild/reboot is not needed and test result can be got in minutes.

Note: Only ACPI METHOD can be overridden, any other object types like

      "Device", "OperationRegion", are not recognized.

Note: The same ACPI control method can be overridden for many times,

      and it's always the latest one that used by Linux/kernel.

1. override an existing method

   a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,

      just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"

   b) disassemble the table by running "iasl -d dsdt.dat".

   c) rewrite the ASL code of the method and save it in a new file,

   d) package the new file (psr.asl) to an ACPI table format.

      Here is an example of a customized \_SB._AC._PSR method,

      DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)

      {

	External (ACON)

	Method (\_SB_.AC._PSR, 0, NotSerialized)

	{

		Store ("In AC _PSR", Debug)

		Return (ACON)

	}

      }

      Note that the full pathname of the method in ACPI namespace

      should be used.

      And remember to use "External" to declare external objects.

   e) assemble the file to generate the AML code of the method.

      e.g. "iasl psr.asl" (psr.aml is generated as a result)

   f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"

   g) override the old method via the debugfs by running

      "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"

2. insert a new method

   This is easier than overriding an existing method.

   We just need to create the ASL code of the method we want to

   insert and then follow the step c) ~ g) in section 1.

3. undo your changes

   The "undo" operation is not supported for a new inserted method

   right now, i.e. we can not remove a method currently.

   For an overrided method, in order to undo your changes, please

   save a copy of the method original ASL code in step c) section 1,

   and redo step c) ~ g) to override the method with the original one.

Note: We can use a kernel with multiple custom ACPI method running,

      But each individual write to debugfs can implement a SINGLE

      method override. i.e. if we want to insert/override multiple

      ACPI methods, we need to redo step c) ~ g) for multiple times.

Who:	Jean Delvare <khali@linux-fr.org>

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

What:	Support for lcd_switch and display_get in asus-laptop driver

When:	March 2010

Why:	These two features use non-standard interfaces. There are the

	only features that really need multiple path to guess what's

	the right method name on a specific laptop.

	Removing them will allow to remove a lot of code an significantly

	clean the drivers.

	This will affect the backlight code which won't be able to know

	if the backlight is on or off. The platform display file will also be

	write only (like the one in eeepc-laptop).

	This should'nt affect a lot of user because they usually know

	when their display is on or off.

Who:	Corentin Chary <corentin.chary@gmail.com>

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

		     ThinkPad ACPI Extras Driver

                            Version 0.23

                          April 10th, 2009

                            Version 0.24

                        December 11th,  2009

               Borislav Deianov <borislav@users.sf.net>

             Henrique de Moraes Holschuh <hmh@hmh.eng.br>

				For Lenovo ThinkPads with a new

				BIOS, it has to be handled either

				by the ACPI OSI, or by userspace.

				The driver does the right thing,

				never mess with this.

0x1011	0x10	FN+END		Brightness down.  See brightness

				up for details.

Brightness hotkey notes:

These are the current sane choices for brightness key mapping in

thinkpad-acpi:

Don't mess with the brightness hotkeys in a Thinkpad.  If you want

notifications for OSD, use the sysfs backlight class event support.

For IBM and Lenovo models *without* ACPI backlight control (the ones on

which thinkpad-acpi will autoload its backlight interface by default,

and on which ACPI video does not export a backlight interface):

1. Don't enable or map the brightness hotkeys in thinkpad-acpi, as

   these older firmware versions unfortunately won't respect the hotkey

   mask for brightness keys anyway, and always reacts to them.  This

   usually work fine, unless X.org drivers are doing something to block

   the BIOS.  In that case, use (3) below.  This is the default mode of

   operation.

2. Enable the hotkeys, but map them to something else that is NOT

   KEY_BRIGHTNESS_UP/DOWN or any other keycode that would cause

   userspace to try to change the backlight level, and use that as an

   on-screen-display hint.

3. IF AND ONLY IF X.org drivers find a way to block the firmware from

   automatically changing the brightness, enable the hotkeys and map

   them to KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN, and feed that to

   something that calls xbacklight.  thinkpad-acpi will not be able to

   change brightness in that case either, so you should disable its

   backlight interface.

For Lenovo models *with* ACPI backlight control:

1. Load up ACPI video and use that.  ACPI video will report ACPI

   events for brightness change keys.  Do not mess with thinkpad-acpi

   defaults in this case.  thinkpad-acpi should not have anything to do

   with backlight events in a scenario where ACPI video is loaded:

   brightness hotkeys must be disabled, and the backlight interface is

   to be kept disabled as well.  This is the default mode of operation.

2. Do *NOT* load up ACPI video, enable the hotkeys in thinkpad-acpi,

   and map them to KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN.  Process

   these keys on userspace somehow (e.g. by calling xbacklight).

   The driver will do this automatically if it detects that ACPI video

   has been disabled.

The driver will issue KEY_BRIGHTNESS_UP and KEY_BRIGHTNESS_DOWN events

automatically for the cases were userspace has to do something to

implement brightness changes.  When you override these events, you will

either fail to handle properly the ThinkPads that require explicit

action to change backlight brightness, or the ThinkPads that require

that no action be taken to work properly.

Bluetooth

    its level up and down at every change.

Volume control -- /proc/acpi/ibm/volume

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

Volume control

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

procfs: /proc/acpi/ibm/volume

ALSA: "ThinkPad Console Audio Control", default ID: "ThinkPadEC"

NOTE: by default, the volume control interface operates in read-only

mode, as it is supposed to be used for on-screen-display purposes.

The read/write mode can be enabled through the use of the

"volume_control=1" module parameter.

This feature allows volume control on ThinkPad models which don't have

a hardware volume knob. The available commands are:

NOTE: distros are urged to not enable volume_control by default, this

should be done by the local admin only.  The ThinkPad UI is for the

console audio control to be done through the volume keys only, and for

the desktop environment to just provide on-screen-display feedback.

Software volume control should be done only in the main AC97/HDA

mixer.

This feature allows volume control on ThinkPad models with a digital

volume knob (when available, not all models have it), as well as

mute/unmute control.  The available commands are:

	echo up   >/proc/acpi/ibm/volume

	echo down >/proc/acpi/ibm/volume

	echo mute >/proc/acpi/ibm/volume

	echo unmute >/proc/acpi/ibm/volume

	echo 'level <level>' >/proc/acpi/ibm/volume

The <level> number range is 0 to 15 although not all of them may be

The <level> number range is 0 to 14 although not all of them may be

distinct. The unmute the volume after the mute command, use either the

up or down command (the level command will not unmute the volume).

up or down command (the level command will not unmute the volume), or

the unmute command.

The current volume level and mute state is shown in the file.

The ALSA mixer interface to this feature is still missing, but patches

to add it exist.  That problem should be addressed in the not so

distant future.

You can use the volume_capabilities parameter to tell the driver

whether your thinkpad has volume control or mute-only control:

volume_capabilities=1 for mixers with mute and volume control,

volume_capabilities=2 for mixers with only mute control.

If the driver misdetects the capabilities for your ThinkPad model,

please report this to ibm-acpi-devel@lists.sourceforge.net, so that we

can update the driver.

There are two strategies for volume control.  To select which one

should be used, use the volume_mode module parameter: volume_mode=1

selects EC mode, and volume_mode=3 selects EC mode with NVRAM backing

(so that volume/mute changes are remembered across shutdown/reboot).

The driver will operate in volume_mode=3 by default. If that does not

work well on your ThinkPad model, please report this to

ibm-acpi-devel@lists.sourceforge.net.

The driver supports the standard ALSA module parameters.  If the ALSA

mixer is disabled, the driver will disable all volume functionality.

Fan control and monitoring: fan speed, fan enable/disable

	0x0008			HKEY event interface, hotkeys

	0x0010			Fan control

	0x0020			Backlight brightness

	0x0040			Audio mixer/volume control

There is also a kernel build option to enable more debugging

information, which may be necessary to debug driver problems.

		and it is always able to disable hot keys.  Very old

		thinkpads are properly supported.  hotkey_bios_mask

		is deprecated and marked for removal.

0x020600:	Marker for backlight change event support.

0x020700:	Support for mute-only mixers.

		Volume control in read-only mode by default.

		Marker for ALSA mixer support.

	passive trip point for the zone. Activation is done by polling with

	an interval of 1 second.

	Unit: millidegrees Celsius

	Valid values: 0 (disabled) or greater than 1000

	RW, Optional

*****************************

	 * P4, Core and beyond CPUs

	 */

	if (c->x86_vendor == X86_VENDOR_INTEL &&

	    (c->x86 > 0xf || (c->x86 == 6 && c->x86_model >= 14)))

	    (c->x86 > 0xf || (c->x86 == 6 && c->x86_model >= 0x0f)))

			flags->bm_control = 0;

}

EXPORT_SYMBOL(acpi_processor_power_init_bm_check);