summaryrefslogtreecommitdiffstats
path: root/Documentation/acpi
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2013-07-03 14:35:40 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2013-07-03 14:35:40 -0700
commitf991fae5c6d42dfc5029150b05a78cf3f6c18cc9 (patch)
treed140deb437bde0631778b4984eeb72c1f4ee0c1d /Documentation/acpi
parentd4141531f63a29bb2a980092b6f2828c385e6edd (diff)
parent2c843bd92ec276ecb68504b3b5ffa7066183f032 (diff)
downloadop-kernel-dev-f991fae5c6d42dfc5029150b05a78cf3f6c18cc9.zip
op-kernel-dev-f991fae5c6d42dfc5029150b05a78cf3f6c18cc9.tar.gz
Merge tag 'pm+acpi-3.11-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm
Pull power management and ACPI updates from Rafael Wysocki: "This time the total number of ACPI commits is slightly greater than the number of cpufreq commits, but Viresh Kumar (who works on cpufreq) remains the most active patch submitter. To me, the most significant change is the addition of offline/online device operations to the driver core (with the Greg's blessing) and the related modifications of the ACPI core hotplug code. Next are the freezer updates from Colin Cross that should make the freezing of tasks a bit less heavy weight. We also have a couple of regression fixes, a number of fixes for issues that have not been identified as regressions, two new drivers and a bunch of cleanups all over. Highlights: - Hotplug changes to support graceful hot-removal failures. It sometimes is necessary to fail device hot-removal operations gracefully if they cannot be carried out completely. For example, if memory from a memory module being hot-removed has been allocated for the kernel's own use and cannot be moved elsewhere, it's desirable to fail the hot-removal operation in a graceful way rather than to crash the kernel, but currenty a success or a kernel crash are the only possible outcomes of an attempted memory hot-removal. Needless to say, that is not a very attractive alternative and it had to be addressed. However, in order to make it work for memory, I first had to make it work for CPUs and for this purpose I needed to modify the ACPI processor driver. It's been split into two parts, a resident one handling the low-level initialization/cleanup and a modular one playing the actual driver's role (but it binds to the CPU system device objects rather than to the ACPI device objects representing processors). That's been sort of like a live brain surgery on a patient who's riding a bike. So this is a little scary, but since we found and fixed a couple of regressions it caused to happen during the early linux-next testing (a month ago), nobody has complained. As a bonus we remove some duplicated ACPI hotplug code, because the ACPI-based CPU hotplug is now going to use the common ACPI hotplug code. - Lighter weight freezing of tasks. These changes from Colin Cross and Mandeep Singh Baines are targeted at making the freezing of tasks a bit less heavy weight operation. They reduce the number of tasks woken up every time during the freezing, by using the observation that the freezer simply doesn't need to wake up some of them and wait for them all to call refrigerator(). The time needed for the freezer to decide to report a failure is reduced too. Also reintroduced is the check causing a lockdep warining to trigger when try_to_freeze() is called with locks held (which is generally unsafe and shouldn't happen). - cpufreq updates First off, a commit from Srivatsa S Bhat fixes a resume regression introduced during the 3.10 cycle causing some cpufreq sysfs attributes to return wrong values to user space after resume. The fix is kind of fresh, but also it's pretty obvious once Srivatsa has identified the root cause. Second, we have a new freqdomain_cpus sysfs attribute for the acpi-cpufreq driver to provide information previously available via related_cpus. From Lan Tianyu. Finally, we fix a number of issues, mostly related to the CPUFREQ_POSTCHANGE notifier and cpufreq Kconfig options and clean up some code. The majority of changes from Viresh Kumar with bits from Jacob Shin, Heiko Stübner, Xiaoguang Chen, Ezequiel Garcia, Arnd Bergmann, and Tang Yuantian. - ACPICA update A usual bunch of updates from the ACPICA upstream. During the 3.4 cycle we introduced support for ACPI 5 extended sleep registers, but they are only supposed to be used if the HW-reduced mode bit is set in the FADT flags and the code attempted to use them without checking that bit. That caused suspend/resume regressions to happen on some systems. Fix from Lv Zheng causes those registers to be used only if the HW-reduced mode bit is set. Apart from this some other ACPICA bugs are fixed and code cleanups are made by Bob Moore, Tomasz Nowicki, Lv Zheng, Chao Guan, and Zhang Rui. - cpuidle updates New driver for Xilinx Zynq processors is added by Michal Simek. Multidriver support simplification, addition of some missing kerneldoc comments and Kconfig-related fixes come from Daniel Lezcano. - ACPI power management updates Changes to make suspend/resume work correctly in Xen guests from Konrad Rzeszutek Wilk, sparse warning fix from Fengguang Wu and cleanups and fixes of the ACPI device power state selection routine. - ACPI documentation updates Some previously missing pieces of ACPI documentation are added by Lv Zheng and Aaron Lu (hopefully, that will help people to uderstand how the ACPI subsystem works) and one outdated doc is updated by Hanjun Guo. - Assorted ACPI updates We finally nailed down the IA-64 issue that was the reason for reverting commit 9f29ab11ddbf ("ACPI / scan: do not match drivers against objects having scan handlers"), so we can fix it and move the ACPI scan handler check added to the ACPI video driver back to the core. A mechanism for adding CMOS RTC address space handlers is introduced by Lan Tianyu to allow some EC-related breakage to be fixed on some systems. A spec-compliant implementation of acpi_os_get_timer() is added by Mika Westerberg. The evaluation of _STA is added to do_acpi_find_child() to avoid situations in which a pointer to a disabled device object is returned instead of an enabled one with the same _ADR value. From Jeff Wu. Intel BayTrail PCH (Platform Controller Hub) support is added to the ACPI driver for Intel Low-Power Subsystems (LPSS) and that driver is modified to work around a couple of known BIOS issues. Changes from Mika Westerberg and Heikki Krogerus. The EC driver is fixed by Vasiliy Kulikov to use get_user() and put_user() instead of dereferencing user space pointers blindly. Code cleanups are made by Bjorn Helgaas, Nicholas Mazzuca and Toshi Kani. - Assorted power management updates The "runtime idle" helper routine is changed to take the return values of the callbacks executed by it into account and to call rpm_suspend() if they return 0, which allows us to reduce the overall code bloat a bit (by dropping some code that's not necessary any more after that modification). The runtime PM documentation is updated by Alan Stern (to reflect the "runtime idle" behavior change). New trace points for PM QoS are added by Sahara (<keun-o.park@windriver.com>). PM QoS documentation is updated by Lan Tianyu. Code cleanups are made and minor issues are addressed by Bernie Thompson, Bjorn Helgaas, Julius Werner, and Shuah Khan. - devfreq updates New driver for the Exynos5-bus device from Abhilash Kesavan. Minor cleanups, fixes and MAINTAINERS update from MyungJoo Ham, Abhilash Kesavan, Paul Bolle, Rajagopal Venkat, and Wei Yongjun. - OMAP power management updates Adaptive Voltage Scaling (AVS) SmartReflex voltage control driver updates from Andrii Tseglytskyi and Nishanth Menon." * tag 'pm+acpi-3.11-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm: (162 commits) cpufreq: Fix cpufreq regression after suspend/resume ACPI / PM: Fix possible NULL pointer deref in acpi_pm_device_sleep_state() PM / Sleep: Warn about system time after resume with pm_trace cpufreq: don't leave stale policy pointer in cdbs->cur_policy acpi-cpufreq: Add new sysfs attribute freqdomain_cpus cpufreq: make sure frequency transitions are serialized ACPI: implement acpi_os_get_timer() according the spec ACPI / EC: Add HP Folio 13 to ec_dmi_table in order to skip DSDT scan ACPI: Add CMOS RTC Operation Region handler support ACPI / processor: Drop unused variable from processor_perflib.c cpufreq: tegra: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: s3c64xx: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: omap: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: imx6q: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: exynos: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: dbx500: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: davinci: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: arm-big-little: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: powernow-k8: call CPUFREQ_POSTCHANGE notfier in error cases cpufreq: pcc: call CPUFREQ_POSTCHANGE notfier in error cases ...
Diffstat (limited to 'Documentation/acpi')
-rw-r--r--Documentation/acpi/namespace.txt395
-rw-r--r--Documentation/acpi/video_extension.txt106
2 files changed, 501 insertions, 0 deletions
diff --git a/Documentation/acpi/namespace.txt b/Documentation/acpi/namespace.txt
new file mode 100644
index 0000000..260f6a3
--- /dev/null
+++ b/Documentation/acpi/namespace.txt
@@ -0,0 +1,395 @@
+ACPI Device Tree - Representation of ACPI Namespace
+
+Copyright (C) 2013, Intel Corporation
+Author: Lv Zheng <lv.zheng@intel.com>
+
+
+Abstract:
+
+The Linux ACPI subsystem converts ACPI namespace objects into a Linux
+device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
+receiving ACPI hotplug notification events. For each device object in this
+hierarchy there is a corresponding symbolic link in the
+/sys/bus/acpi/devices.
+This document illustrates the structure of the ACPI device tree.
+
+
+Credit:
+
+Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J.
+Wysocki <rafael.j.wysocki@intel.com>.
+
+
+1. ACPI Definition Blocks
+
+ The ACPI firmware sets up RSDP (Root System Description Pointer) in the
+ system memory address space pointing to the XSDT (Extended System
+ Description Table). The XSDT always points to the FADT (Fixed ACPI
+ Description Table) using its first entry, the data within the FADT
+ includes various fixed-length entries that describe fixed ACPI features
+ of the hardware. The FADT contains a pointer to the DSDT
+ (Differentiated System Descripition Table). The XSDT also contains
+ entries pointing to possibly multiple SSDTs (Secondary System
+ Description Table).
+
+ The DSDT and SSDT data is organized in data structures called definition
+ blocks that contain definitions of various objects, including ACPI
+ control methods, encoded in AML (ACPI Machine Language). The data block
+ of the DSDT along with the contents of SSDTs represents a hierarchical
+ data structure called the ACPI namespace whose topology reflects the
+ structure of the underlying hardware platform.
+
+ The relationships between ACPI System Definition Tables described above
+ are illustrated in the following diagram.
+
+ +---------+ +-------+ +--------+ +------------------------+
+ | RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
+ +---------+ | +-------+ | +--------+ +-|->| DSDT | |
+ | Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
+ +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
+ | Pointer |-+ | ..... | | ...... | | +-------------------+ |
+ +---------+ +-------+ +--------+ | +-------------------+ |
+ | Entry |------------------|->| SSDT | |
+ +- - - -+ | +-------------------| |
+ | Entry | - - - - - - - -+ | | Definition Blocks | |
+ +- - - -+ | | +-------------------+ |
+ | | +- - - - - - - - - -+ |
+ +-|->| SSDT | |
+ | +-------------------+ |
+ | | Definition Blocks | |
+ | +- - - - - - - - - -+ |
+ +------------------------+
+ |
+ OSPM Loading |
+ \|/
+ +----------------+
+ | ACPI Namespace |
+ +----------------+
+
+ Figure 1. ACPI Definition Blocks
+
+ NOTE: RSDP can also contain a pointer to the RSDT (Root System
+ Description Table). Platforms provide RSDT to enable
+ compatibility with ACPI 1.0 operating systems. The OS is expected
+ to use XSDT, if present.
+
+
+2. Example ACPI Namespace
+
+ All definition blocks are loaded into a single namespace. The namespace
+ is a hierarchy of objects identified by names and paths.
+ The following naming conventions apply to object names in the ACPI
+ namespace:
+ 1. All names are 32 bits long.
+ 2. The first byte of a name must be one of 'A' - 'Z', '_'.
+ 3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
+ - '9', '_'.
+ 4. Names starting with '_' are reserved by the ACPI specification.
+ 5. The '\' symbol represents the root of the namespace (i.e. names
+ prepended with '\' are relative to the namespace root).
+ 6. The '^' symbol represents the parent of the current namespace node
+ (i.e. names prepended with '^' are relative to the parent of the
+ current namespace node).
+
+ The figure below shows an example ACPI namespace.
+
+ +------+
+ | \ | Root
+ +------+
+ |
+ | +------+
+ +-| _PR | Scope(_PR): the processor namespace
+ | +------+
+ | |
+ | | +------+
+ | +-| CPU0 | Processor(CPU0): the first processor
+ | +------+
+ |
+ | +------+
+ +-| _SB | Scope(_SB): the system bus namespace
+ | +------+
+ | |
+ | | +------+
+ | +-| LID0 | Device(LID0); the lid device
+ | | +------+
+ | | |
+ | | | +------+
+ | | +-| _HID | Name(_HID, "PNP0C0D"): the hardware ID
+ | | | +------+
+ | | |
+ | | | +------+
+ | | +-| _STA | Method(_STA): the status control method
+ | | +------+
+ | |
+ | | +------+
+ | +-| PCI0 | Device(PCI0); the PCI root bridge
+ | +------+
+ | |
+ | | +------+
+ | +-| _HID | Name(_HID, "PNP0A08"): the hardware ID
+ | | +------+
+ | |
+ | | +------+
+ | +-| _CID | Name(_CID, "PNP0A03"): the compatible ID
+ | | +------+
+ | |
+ | | +------+
+ | +-| RP03 | Scope(RP03): the PCI0 power scope
+ | | +------+
+ | | |
+ | | | +------+
+ | | +-| PXP3 | PowerResource(PXP3): the PCI0 power resource
+ | | +------+
+ | |
+ | | +------+
+ | +-| GFX0 | Device(GFX0): the graphics adapter
+ | +------+
+ | |
+ | | +------+
+ | +-| _ADR | Name(_ADR, 0x00020000): the PCI bus address
+ | | +------+
+ | |
+ | | +------+
+ | +-| DD01 | Device(DD01): the LCD output device
+ | +------+
+ | |
+ | | +------+
+ | +-| _BCL | Method(_BCL): the backlight control method
+ | +------+
+ |
+ | +------+
+ +-| _TZ | Scope(_TZ): the thermal zone namespace
+ | +------+
+ | |
+ | | +------+
+ | +-| FN00 | PowerResource(FN00): the FAN0 power resource
+ | | +------+
+ | |
+ | | +------+
+ | +-| FAN0 | Device(FAN0): the FAN0 cooling device
+ | | +------+
+ | | |
+ | | | +------+
+ | | +-| _HID | Name(_HID, "PNP0A0B"): the hardware ID
+ | | +------+
+ | |
+ | | +------+
+ | +-| TZ00 | ThermalZone(TZ00); the FAN thermal zone
+ | +------+
+ |
+ | +------+
+ +-| _GPE | Scope(_GPE): the GPE namespace
+ +------+
+
+ Figure 2. Example ACPI Namespace
+
+
+3. Linux ACPI Device Objects
+
+ The Linux kernel's core ACPI subsystem creates struct acpi_device
+ objects for ACPI namespace objects representing devices, power resources
+ processors, thermal zones. Those objects are exported to user space via
+ sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
+ format of their names is <bus_id:instance>, where 'bus_id' refers to the
+ ACPI namespace representation of the given object and 'instance' is used
+ for distinguishing different object of the same 'bus_id' (it is
+ two-digit decimal representation of an unsigned integer).
+
+ The value of 'bus_id' depends on the type of the object whose name it is
+ part of as listed in the table below.
+
+ +---+-----------------+-------+----------+
+ | | Object/Feature | Table | bus_id |
+ +---+-----------------+-------+----------+
+ | N | Root | xSDT | LNXSYSTM |
+ +---+-----------------+-------+----------+
+ | N | Device | xSDT | _HID |
+ +---+-----------------+-------+----------+
+ | N | Processor | xSDT | LNXCPU |
+ +---+-----------------+-------+----------+
+ | N | ThermalZone | xSDT | LNXTHERM |
+ +---+-----------------+-------+----------+
+ | N | PowerResource | xSDT | LNXPOWER |
+ +---+-----------------+-------+----------+
+ | N | Other Devices | xSDT | device |
+ +---+-----------------+-------+----------+
+ | F | PWR_BUTTON | FADT | LNXPWRBN |
+ +---+-----------------+-------+----------+
+ | F | SLP_BUTTON | FADT | LNXSLPBN |
+ +---+-----------------+-------+----------+
+ | M | Video Extension | xSDT | LNXVIDEO |
+ +---+-----------------+-------+----------+
+ | M | ATA Controller | xSDT | LNXIOBAY |
+ +---+-----------------+-------+----------+
+ | M | Docking Station | xSDT | LNXDOCK |
+ +---+-----------------+-------+----------+
+
+ Table 1. ACPI Namespace Objects Mapping
+
+ The following rules apply when creating struct acpi_device objects on
+ the basis of the contents of ACPI System Description Tables (as
+ indicated by the letter in the first column and the notation in the
+ second column of the table above):
+ N:
+ The object's source is an ACPI namespace node (as indicated by the
+ named object's type in the second column). In that case the object's
+ directory in sysfs will contain the 'path' attribute whose value is
+ the full path to the node from the namespace root.
+ struct acpi_device objects are created for the ACPI namespace nodes
+ whose _STA control methods return PRESENT or FUNCTIONING. The power
+ resource nodes or nodes without _STA are assumed to be both PRESENT
+ and FUNCTIONING.
+ F:
+ The struct acpi_device object is created for a fixed hardware
+ feature (as indicated by the fixed feature flag's name in the second
+ column), so its sysfs directory will not contain the 'path'
+ attribute.
+ M:
+ The struct acpi_device object is created for an ACPI namespace node
+ with specific control methods (as indicated by the ACPI defined
+ device's type in the second column). The 'path' attribute containing
+ its namespace path will be present in its sysfs directory. For
+ example, if the _BCL method is present for an ACPI namespace node, a
+ struct acpi_device object with LNXVIDEO 'bus_id' will be created for
+ it.
+
+ The third column of the above table indicates which ACPI System
+ Description Tables contain information used for the creation of the
+ struct acpi_device objects represented by the given row (xSDT means DSDT
+ or SSDT).
+
+ The forth column of the above table indicates the 'bus_id' generation
+ rule of the struct acpi_device object:
+ _HID:
+ _HID in the last column of the table means that the object's bus_id
+ is derived from the _HID/_CID identification objects present under
+ the corresponding ACPI namespace node. The object's sysfs directory
+ will then contain the 'hid' and 'modalias' attributes that can be
+ used to retrieve the _HID and _CIDs of that object.
+ LNXxxxxx:
+ The 'modalias' attribute is also present for struct acpi_device
+ objects having bus_id of the "LNXxxxxx" form (pseudo devices), in
+ which cases it contains the bus_id string itself.
+ device:
+ 'device' in the last column of the table indicates that the object's
+ bus_id cannot be determined from _HID/_CID of the corresponding
+ ACPI namespace node, although that object represents a device (for
+ example, it may be a PCI device with _ADR defined and without _HID
+ or _CID). In that case the string 'device' will be used as the
+ object's bus_id.
+
+
+4. Linux ACPI Physical Device Glue
+
+ ACPI device (i.e. struct acpi_device) objects may be linked to other
+ objects in the Linux' device hierarchy that represent "physical" devices
+ (for example, devices on the PCI bus). If that happens, it means that
+ the ACPI device object is a "companion" of a device otherwise
+ represented in a different way and is used (1) to provide configuration
+ information on that device which cannot be obtained by other means and
+ (2) to do specific things to the device with the help of its ACPI
+ control methods. One ACPI device object may be linked this way to
+ multiple "physical" devices.
+
+ If an ACPI device object is linked to a "physical" device, its sysfs
+ directory contains the "physical_node" symbolic link to the sysfs
+ directory of the target device object. In turn, the target device's
+ sysfs directory will then contain the "firmware_node" symbolic link to
+ the sysfs directory of the companion ACPI device object.
+ The linking mechanism relies on device identification provided by the
+ ACPI namespace. For example, if there's an ACPI namespace object
+ representing a PCI device (i.e. a device object under an ACPI namespace
+ object representing a PCI bridge) whose _ADR returns 0x00020000 and the
+ bus number of the parent PCI bridge is 0, the sysfs directory
+ representing the struct acpi_device object created for that ACPI
+ namespace object will contain the 'physical_node' symbolic link to the
+ /sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
+ corresponding PCI device.
+
+ The linking mechanism is generally bus-specific. The core of its
+ implementation is located in the drivers/acpi/glue.c file, but there are
+ complementary parts depending on the bus types in question located
+ elsewhere. For example, the PCI-specific part of it is located in
+ drivers/pci/pci-acpi.c.
+
+
+5. Example Linux ACPI Device Tree
+
+ The sysfs hierarchy of struct acpi_device objects corresponding to the
+ example ACPI namespace illustrated in Figure 2 with the addition of
+ fixed PWR_BUTTON/SLP_BUTTON devices is shown below.
+
+ +--------------+---+-----------------+
+ | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
+ +--------------+---+-----------------+
+ |
+ | +-------------+-----+----------------+
+ +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: |
+ | +-------------+-----+----------------+
+ |
+ | +-------------+-----+----------------+
+ +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: |
+ | +-------------+-----+----------------+
+ |
+ | +-----------+------------+--------------+
+ +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: |
+ | +-----------+------------+--------------+
+ |
+ | +-------------+-------+----------------+
+ +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: |
+ | +-------------+-------+----------------+
+ | |
+ | | +- - - - - - - +- - - - - - +- - - - - - - -+
+ | +-| * PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: |
+ | | +- - - - - - - +- - - - - - +- - - - - - - -+
+ | |
+ | | +------------+------------+-----------------------+
+ | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: |
+ | +------------+------------+-----------------------+
+ | |
+ | | +-----------+-----------------+-----+
+ | +-| device:00 | \_SB_.PCI0.RP03 | N/A |
+ | | +-----------+-----------------+-----+
+ | | |
+ | | | +-------------+----------------------+----------------+
+ | | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: |
+ | | +-------------+----------------------+----------------+
+ | |
+ | | +-------------+-----------------+----------------+
+ | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: |
+ | +-------------+-----------------+----------------+
+ | |
+ | | +-----------+-----------------+-----+
+ | +-| device:01 | \_SB_.PCI0.DD01 | N/A |
+ | +-----------+-----------------+-----+
+ |
+ | +-------------+-------+----------------+
+ +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: |
+ +-------------+-------+----------------+
+ |
+ | +-------------+------------+----------------+
+ +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: |
+ | +-------------+------------+----------------+
+ |
+ | +------------+------------+---------------+
+ +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: |
+ | +------------+------------+---------------+
+ |
+ | +-------------+------------+----------------+
+ +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: |
+ +-------------+------------+----------------+
+
+ Figure 3. Example Linux ACPI Device Tree
+
+ NOTE: Each node is represented as "object/path/modalias", where:
+ 1. 'object' is the name of the object's directory in sysfs.
+ 2. 'path' is the ACPI namespace path of the corresponding
+ ACPI namespace object, as returned by the object's 'path'
+ sysfs attribute.
+ 3. 'modalias' is the value of the object's 'modalias' sysfs
+ attribute (as described earlier in this document).
+ NOTE: N/A indicates the device object does not have the 'path' or the
+ 'modalias' attribute.
+ NOTE: The PNP0C0D device listed above is highlighted (marked by "*")
+ to indicate it will be created only when its _STA methods return
+ PRESENT or FUNCTIONING.
diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt
new file mode 100644
index 0000000..78b32ac
--- /dev/null
+++ b/Documentation/acpi/video_extension.txt
@@ -0,0 +1,106 @@
+ACPI video extensions
+~~~~~~~~~~~~~~~~~~~~~
+
+This driver implement the ACPI Extensions For Display Adapters for
+integrated graphics devices on motherboard, as specified in ACPI 2.0
+Specification, Appendix B, allowing to perform some basic control like
+defining the video POST device, retrieving EDID information or to
+setup a video output, etc. Note that this is an ref. implementation
+only. It may or may not work for your integrated video device.
+
+The ACPI video driver does 3 things regarding backlight control:
+
+1 Export a sysfs interface for user space to control backlight level
+
+If the ACPI table has a video device, and acpi_backlight=vendor kernel
+command line is not present, the driver will register a backlight device
+and set the required backlight operation structure for it for the sysfs
+interface control. For every registered class device, there will be a
+directory named acpi_videoX under /sys/class/backlight.
+
+The backlight sysfs interface has a standard definition here:
+Documentation/ABI/stable/sysfs-class-backlight.
+
+And what ACPI video driver does is:
+actual_brightness: on read, control method _BQC will be evaluated to
+get the brightness level the firmware thinks it is at;
+bl_power: not implemented, will set the current brightness instead;
+brightness: on write, control method _BCM will run to set the requested
+brightness level;
+max_brightness: Derived from the _BCL package(see below);
+type: firmware
+
+Note that ACPI video backlight driver will always use index for
+brightness, actual_brightness and max_brightness. So if we have
+the following _BCL package:
+
+Method (_BCL, 0, NotSerialized)
+{
+ Return (Package (0x0C)
+ {
+ 0x64,
+ 0x32,
+ 0x0A,
+ 0x14,
+ 0x1E,
+ 0x28,
+ 0x32,
+ 0x3C,
+ 0x46,
+ 0x50,
+ 0x5A,
+ 0x64
+ })
+}
+
+The first two levels are for when laptop are on AC or on battery and are
+not used by Linux currently. The remaining 10 levels are supported levels
+that we can choose from. The applicable index values are from 0 (that
+corresponds to the 0x0A brightness value) to 9 (that corresponds to the
+0x64 brightness value) inclusive. Each of those index values is regarded
+as a "brightness level" indicator. Thus from the user space perspective
+the range of available brightness levels is from 0 to 9 (max_brightness)
+inclusive.
+
+2 Notify user space about hotkey event
+
+There are generally two cases for hotkey event reporting:
+i) For some laptops, when user presses the hotkey, a scancode will be
+ generated and sent to user space through the input device created by
+ the keyboard driver as a key type input event, with proper remap, the
+ following key code will appear to user space:
+
+ EV_KEY, KEY_BRIGHTNESSUP
+ EV_KEY, KEY_BRIGHTNESSDOWN
+ etc.
+
+For this case, ACPI video driver does not need to do anything(actually,
+it doesn't even know this happened).
+
+ii) For some laptops, the press of the hotkey will not generate the
+ scancode, instead, firmware will notify the video device ACPI node
+ about the event. The event value is defined in the ACPI spec. ACPI
+ video driver will generate an key type input event according to the
+ notify value it received and send the event to user space through the
+ input device it created:
+
+ event keycode
+ 0x86 KEY_BRIGHTNESSUP
+ 0x87 KEY_BRIGHTNESSDOWN
+ etc.
+
+so this would lead to the same effect as case i) now.
+
+Once user space tool receives this event, it can modify the backlight
+level through the sysfs interface.
+
+3 Change backlight level in the kernel
+
+This works for machines covered by case ii) in Section 2. Once the driver
+received a notification, it will set the backlight level accordingly. This does
+not affect the sending of event to user space, they are always sent to user
+space regardless of whether or not the video module controls the backlight level
+directly. This behaviour can be controlled through the brightness_switch_enabled
+module parameter as documented in kernel-parameters.txt. It is recommended to
+disable this behaviour once a GUI environment starts up and wants to have full
+control of the backlight level.
OpenPOWER on IntegriCloud