v4.19.13 snapshot.
diff --git a/Documentation/acpi/DSD-properties-rules.txt b/Documentation/acpi/DSD-properties-rules.txt
new file mode 100644
index 0000000..3e4862b
--- /dev/null
+++ b/Documentation/acpi/DSD-properties-rules.txt
@@ -0,0 +1,97 @@
+_DSD Device Properties Usage Rules
+----------------------------------
+
+Properties, Property Sets and Property Subsets
+----------------------------------------------
+
+The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
+allows any type of device configuration data to be provided via the ACPI
+namespace. In principle, the format of the data may be arbitrary, but it has to
+be identified by a UUID which must be recognized by the driver processing the
+_DSD output. However, there are generic UUIDs defined for _DSD recognized by
+the ACPI subsystem in the Linux kernel which automatically processes the data
+packages associated with them and makes those data available to device drivers
+as "device properties".
+
+A device property is a data item consisting of a string key and a value (of a
+specific type) associated with it.
+
+In the ACPI _DSD context it is an element of the sub-package following the
+generic Device Properties UUID in the _DSD return package as specified in the
+Device Properties UUID definition document [1].
+
+It also may be regarded as the definition of a key and the associated data type
+that can be returned by _DSD in the Device Properties UUID sub-package for a
+given device.
+
+A property set is a collection of properties applicable to a hardware entity
+like a device. In the ACPI _DSD context it is the set of all properties that
+can be returned in the Device Properties UUID sub-package for the device in
+question.
+
+Property subsets are nested collections of properties. Each of them is
+associated with an additional key (name) allowing the subset to be referred
+to as a whole (and to be treated as a separate entity). The canonical
+representation of property subsets is via the mechanism specified in the
+Hierarchical Properties Extension UUID definition document [2].
+
+Property sets may be hierarchical. That is, a property set may contain
+multiple property subsets that each may contain property subsets of its
+own and so on.
+
+General Validity Rule for Property Sets
+---------------------------------------
+
+Valid property sets must follow the guidance given by the Device Properties UUID
+definition document [1].
+
+_DSD properties are intended to be used in addition to, and not instead of, the
+existing mechanisms defined by the ACPI specification. Therefore, as a rule,
+they should only be used if the ACPI specification does not make direct
+provisions for handling the underlying use case. It generally is invalid to
+return property sets which do not follow that rule from _DSD in data packages
+associated with the Device Properties UUID.
+
+Additional Considerations
+-------------------------
+
+There are cases in which, even if the general rule given above is followed in
+principle, the property set may still not be regarded as a valid one.
+
+For example, that applies to device properties which may cause kernel code
+(either a device driver or a library/subsystem) to access hardware in a way
+possibly leading to a conflict with AML methods in the ACPI namespace. In
+particular, that may happen if the kernel code uses device properties to
+manipulate hardware normally controlled by ACPI methods related to power
+management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power
+resource objects), or by ACPI device disabling/enabling methods, like _DIS and
+_SRS.
+
+In all cases in which kernel code may do something that will confuse AML as a
+result of using device properties, the device properties in question are not
+suitable for the ACPI environment and consequently they cannot belong to a valid
+property set.
+
+Property Sets and Device Tree Bindings
+--------------------------------------
+
+It often is useful to make _DSD return property sets that follow Device Tree
+bindings.
+
+In those cases, however, the above validity considerations must be taken into
+account in the first place and returning invalid property sets from _DSD must be
+avoided. For this reason, it may not be possible to make _DSD return a property
+set following the given DT binding literally and completely. Still, for the
+sake of code re-use, it may make sense to provide as much of the configuration
+data as possible in the form of device properties and complement that with an
+ACPI-specific mechanism suitable for the use case at hand.
+
+In any case, property sets following DT bindings literally should not be
+expected to automatically work in the ACPI environment regardless of their
+contents.
+
+References
+----------
+
+[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+[2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/acpi/acpi-lid.txt
new file mode 100644
index 0000000..effe7af
--- /dev/null
+++ b/Documentation/acpi/acpi-lid.txt
@@ -0,0 +1,96 @@
+Special Usage Model of the ACPI Control Method Lid Device
+
+Copyright (C) 2016, Intel Corporation
+Author: Lv Zheng <lv.zheng@intel.com>
+
+
+Abstract:
+
+Platforms containing lids convey lid state (open/close) to OSPMs using a
+control method lid device. To implement this, the AML tables issue
+Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
+changed. The _LID control method for the lid device must be implemented to
+report the "current" state of the lid as either "opened" or "closed".
+
+For most platforms, both the _LID method and the lid notifications are
+reliable. However, there are exceptions. In order to work with these
+exceptional buggy platforms, special restrictions and expections should be
+taken into account. This document describes the restrictions and the
+expections of the Linux ACPI lid device driver.
+
+
+1. Restrictions of the returning value of the _LID control method
+
+The _LID control method is described to return the "current" lid state.
+However the word of "current" has ambiguity, some buggy AML tables return
+the lid state upon the last lid notification instead of returning the lid
+state upon the last _LID evaluation. There won't be difference when the
+_LID control method is evaluated during the runtime, the problem is its
+initial returning value. When the AML tables implement this control method
+with cached value, the initial returning value is likely not reliable.
+There are platforms always retun "closed" as initial lid state.
+
+2. Restrictions of the lid state change notifications
+
+There are buggy AML tables never notifying when the lid device state is
+changed to "opened". Thus the "opened" notification is not guaranteed. But
+it is guaranteed that the AML tables always notify "closed" when the lid
+state is changed to "closed". The "closed" notification is normally used to
+trigger some system power saving operations on Windows. Since it is fully
+tested, it is reliable from all AML tables.
+
+3. Expections for the userspace users of the ACPI lid device driver
+
+The ACPI button driver exports the lid state to the userspace via the
+following file:
+ /proc/acpi/button/lid/LID0/state
+This file actually calls the _LID control method described above. And given
+the previous explanation, it is not reliable enough on some platforms. So
+it is advised for the userspace program to not to solely rely on this file
+to determine the actual lid state.
+
+The ACPI button driver emits the following input event to the userspace:
+ SW_LID
+The ACPI lid device driver is implemented to try to deliver the platform
+triggered events to the userspace. However, given the fact that the buggy
+firmware cannot make sure "opened"/"closed" events are paired, the ACPI
+button driver uses the following 3 modes in order not to trigger issues.
+
+If the userspace hasn't been prepared to ignore the unreliable "opened"
+events and the unreliable initial state notification, Linux users can use
+the following kernel parameters to handle the possible issues:
+A. button.lid_init_state=method:
+ When this option is specified, the ACPI button driver reports the
+ initial lid state using the returning value of the _LID control method
+ and whether the "opened"/"closed" events are paired fully relies on the
+ firmware implementation.
+ This option can be used to fix some platforms where the returning value
+ of the _LID control method is reliable but the initial lid state
+ notification is missing.
+ This option is the default behavior during the period the userspace
+ isn't ready to handle the buggy AML tables.
+B. button.lid_init_state=open:
+ When this option is specified, the ACPI button driver always reports the
+ initial lid state as "opened" and whether the "opened"/"closed" events
+ are paired fully relies on the firmware implementation.
+ This may fix some platforms where the returning value of the _LID
+ control method is not reliable and the initial lid state notification is
+ missing.
+
+If the userspace has been prepared to ignore the unreliable "opened" events
+and the unreliable initial state notification, Linux users should always
+use the following kernel parameter:
+C. button.lid_init_state=ignore:
+ When this option is specified, the ACPI button driver never reports the
+ initial lid state and there is a compensation mechanism implemented to
+ ensure that the reliable "closed" notifications can always be delievered
+ to the userspace by always pairing "closed" input events with complement
+ "opened" input events. But there is still no guarantee that the "opened"
+ notifications can be delivered to the userspace when the lid is actually
+ opens given that some AML tables do not send "opened" notifications
+ reliably.
+ In this mode, if everything is correctly implemented by the platform
+ firmware, the old userspace programs should still work. Otherwise, the
+ new userspace programs are required to work with the ACPI button driver.
+ This option will be the default behavior after the userspace is ready to
+ handle the buggy AML tables.
diff --git a/Documentation/acpi/aml-debugger.txt b/Documentation/acpi/aml-debugger.txt
new file mode 100644
index 0000000..e851cc5
--- /dev/null
+++ b/Documentation/acpi/aml-debugger.txt
@@ -0,0 +1,66 @@
+The AML Debugger
+
+Copyright (C) 2016, Intel Corporation
+Author: Lv Zheng <lv.zheng@intel.com>
+
+
+This document describes the usage of the AML debugger embedded in the Linux
+kernel.
+
+1. Build the debugger
+
+ The following kernel configuration items are required to enable the AML
+ debugger interface from the Linux kernel:
+
+ CONFIG_ACPI_DEBUGGER=y
+ CONFIG_ACPI_DEBUGGER_USER=m
+
+ The userspace utilities can be built from the kernel source tree using
+ the following commands:
+
+ $ cd tools
+ $ make acpi
+
+ The resultant userspace tool binary is then located at:
+
+ tools/acpi/power/acpi/acpidbg/acpidbg
+
+ It can be installed to system directories by running "make install" (as a
+ sufficiently privileged user).
+
+2. Start the userspace debugger interface
+
+ After booting the kernel with the debugger built-in, the debugger can be
+ started by using the following commands:
+
+ # mount -t debugfs none /sys/kernel/debug
+ # modprobe acpi_dbg
+ # tools/acpi/power/acpi/acpidbg/acpidbg
+
+ That spawns the interactive AML debugger environment where you can execute
+ debugger commands.
+
+ The commands are documented in the "ACPICA Overview and Programmer Reference"
+ that can be downloaded from
+
+ https://acpica.org/documentation
+
+ The detailed debugger commands reference is located in Chapter 12 "ACPICA
+ Debugger Reference". The "help" command can be used for a quick reference.
+
+3. Stop the userspace debugger interface
+
+ The interactive debugger interface can be closed by pressing Ctrl+C or using
+ the "quit" or "exit" commands. When finished, unload the module with:
+
+ # rmmod acpi_dbg
+
+ The module unloading may fail if there is an acpidbg instance running.
+
+4. Run the debugger in a script
+
+ It may be useful to run the AML debugger in a test script. "acpidbg" supports
+ this in a special "batch" mode. For example, the following command outputs
+ the entire ACPI namespace:
+
+ # acpidbg -b "namespace"
diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/acpi/apei/einj.txt
new file mode 100644
index 0000000..e550c8b
--- /dev/null
+++ b/Documentation/acpi/apei/einj.txt
@@ -0,0 +1,177 @@
+ APEI Error INJection
+ ~~~~~~~~~~~~~~~~~~~~
+
+EINJ provides a hardware error injection mechanism. It is very useful
+for debugging and testing APEI and RAS features in general.
+
+You need to check whether your BIOS supports EINJ first. For that, look
+for early boot messages similar to this one:
+
+ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
+
+which shows that the BIOS is exposing an EINJ table - it is the
+mechanism through which the injection is done.
+
+Alternatively, look in /sys/firmware/acpi/tables for an "EINJ" file,
+which is a different representation of the same thing.
+
+It doesn't necessarily mean that EINJ is not supported if those above
+don't exist: before you give up, go into BIOS setup to see if the BIOS
+has an option to enable error injection. Look for something called WHEA
+or similar. Often, you need to enable an ACPI5 support option prior, in
+order to see the APEI,EINJ,... functionality supported and exposed by
+the BIOS menu.
+
+To use EINJ, make sure the following are options enabled in your kernel
+configuration:
+
+CONFIG_DEBUG_FS
+CONFIG_ACPI_APEI
+CONFIG_ACPI_APEI_EINJ
+
+The EINJ user interface is in <debugfs mount point>/apei/einj.
+
+The following files belong to it:
+
+- available_error_type
+
+ This file shows which error types are supported:
+
+ Error Type Value Error Description
+ ================ =================
+ 0x00000001 Processor Correctable
+ 0x00000002 Processor Uncorrectable non-fatal
+ 0x00000004 Processor Uncorrectable fatal
+ 0x00000008 Memory Correctable
+ 0x00000010 Memory Uncorrectable non-fatal
+ 0x00000020 Memory Uncorrectable fatal
+ 0x00000040 PCI Express Correctable
+ 0x00000080 PCI Express Uncorrectable fatal
+ 0x00000100 PCI Express Uncorrectable non-fatal
+ 0x00000200 Platform Correctable
+ 0x00000400 Platform Uncorrectable non-fatal
+ 0x00000800 Platform Uncorrectable fatal
+
+ The format of the file contents are as above, except present are only
+ the available error types.
+
+- error_type
+
+ Set the value of the error type being injected. Possible error types
+ are defined in the file available_error_type above.
+
+- error_inject
+
+ Write any integer to this file to trigger the error injection. Make
+ sure you have specified all necessary error parameters, i.e. this
+ write should be the last step when injecting errors.
+
+- flags
+
+ Present for kernel versions 3.13 and above. Used to specify which
+ of param{1..4} are valid and should be used by the firmware during
+ injection. Value is a bitmask as specified in ACPI5.0 spec for the
+ SET_ERROR_TYPE_WITH_ADDRESS data structure:
+
+ Bit 0 - Processor APIC field valid (see param3 below).
+ Bit 1 - Memory address and mask valid (param1 and param2).
+ Bit 2 - PCIe (seg,bus,dev,fn) valid (see param4 below).
+
+ If set to zero, legacy behavior is mimicked where the type of
+ injection specifies just one bit set, and param1 is multiplexed.
+
+- param1
+
+ This file is used to set the first error parameter value. Its effect
+ depends on the error type specified in error_type. For example, if
+ error type is memory related type, the param1 should be a valid
+ physical memory address. [Unless "flag" is set - see above]
+
+- param2
+
+ Same use as param1 above. For example, if error type is of memory
+ related type, then param2 should be a physical memory address mask.
+ Linux requires page or narrower granularity, say, 0xfffffffffffff000.
+
+- param3
+
+ Used when the 0x1 bit is set in "flags" to specify the APIC id
+
+- param4
+ Used when the 0x4 bit is set in "flags" to specify target PCIe device
+
+- notrigger
+
+ The error injection mechanism is a two-step process. First inject the
+ error, then perform some actions to trigger it. Setting "notrigger"
+ to 1 skips the trigger phase, which *may* allow the user to cause the
+ error in some other context by a simple access to the CPU, memory
+ location, or device that is the target of the error injection. Whether
+ this actually works depends on what operations the BIOS actually
+ includes in the trigger phase.
+
+BIOS versions based on the ACPI 4.0 specification have limited options
+in controlling where the errors are injected. Your BIOS may support an
+extension (enabled with the param_extension=1 module parameter, or boot
+command line einj.param_extension=1). This allows the address and mask
+for memory injections to be specified by the param1 and param2 files in
+apei/einj.
+
+BIOS versions based on the ACPI 5.0 specification have more control over
+the target of the injection. For processor-related errors (type 0x1, 0x2
+and 0x4), you can set flags to 0x3 (param3 for bit 0, and param1 and
+param2 for bit 1) so that you have more information added to the error
+signature being injected. The actual data passed is this:
+
+ memory_address = param1;
+ memory_address_range = param2;
+ apicid = param3;
+ pcie_sbdf = param4;
+
+For memory errors (type 0x8, 0x10 and 0x20) the address is set using
+param1 with a mask in param2 (0x0 is equivalent to all ones). For PCI
+express errors (type 0x40, 0x80 and 0x100) the segment, bus, device and
+function are specified using param1:
+
+ 31 24 23 16 15 11 10 8 7 0
+ +-------------------------------------------------+
+ | segment | bus | device | function | reserved |
+ +-------------------------------------------------+
+
+Anyway, you get the idea, if there's doubt just take a look at the code
+in drivers/acpi/apei/einj.c.
+
+An ACPI 5.0 BIOS may also allow vendor-specific errors to be injected.
+In this case a file named vendor will contain identifying information
+from the BIOS that hopefully will allow an application wishing to use
+the vendor-specific extension to tell that they are running on a BIOS
+that supports it. All vendor extensions have the 0x80000000 bit set in
+error_type. A file vendor_flags controls the interpretation of param1
+and param2 (1 = PROCESSOR, 2 = MEMORY, 4 = PCI). See your BIOS vendor
+documentation for details (and expect changes to this API if vendors
+creativity in using this feature expands beyond our expectations).
+
+
+An error injection example:
+
+# cd /sys/kernel/debug/apei/einj
+# cat available_error_type # See which errors can be injected
+0x00000002 Processor Uncorrectable non-fatal
+0x00000008 Memory Correctable
+0x00000010 Memory Uncorrectable non-fatal
+# echo 0x12345000 > param1 # Set memory address for injection
+# echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
+# echo 0x8 > error_type # Choose correctable memory error
+# echo 1 > error_inject # Inject now
+
+You should see something like this in dmesg:
+
+[22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
+[22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
+[22715.834759] EDAC sbridge MC3: TSC 0
+[22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
+[22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
+[22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
+
+For more information about EINJ, please refer to ACPI specification
+version 4.0, section 17.5 and ACPI 5.0, section 18.6.
diff --git a/Documentation/acpi/apei/output_format.txt b/Documentation/acpi/apei/output_format.txt
new file mode 100644
index 0000000..0c49c19
--- /dev/null
+++ b/Documentation/acpi/apei/output_format.txt
@@ -0,0 +1,147 @@
+ APEI output format
+ ~~~~~~~~~~~~~~~~~~
+
+APEI uses printk as hardware error reporting interface, the output
+format is as follow.
+
+<error record> :=
+APEI generic hardware error status
+severity: <integer>, <severity string>
+section: <integer>, severity: <integer>, <severity string>
+flags: <integer>
+<section flags strings>
+fru_id: <uuid string>
+fru_text: <string>
+section_type: <section type string>
+<section data>
+
+<severity string>* := recoverable | fatal | corrected | info
+
+<section flags strings># :=
+[primary][, containment warning][, reset][, threshold exceeded]\
+[, resource not accessible][, latent error]
+
+<section type string> := generic processor error | memory error | \
+PCIe error | unknown, <uuid string>
+
+<section data> :=
+<generic processor section data> | <memory section data> | \
+<pcie section data> | <null>
+
+<generic processor section data> :=
+[processor_type: <integer>, <proc type string>]
+[processor_isa: <integer>, <proc isa string>]
+[error_type: <integer>
+<proc error type strings>]
+[operation: <integer>, <proc operation string>]
+[flags: <integer>
+<proc flags strings>]
+[level: <integer>]
+[version_info: <integer>]
+[processor_id: <integer>]
+[target_address: <integer>]
+[requestor_id: <integer>]
+[responder_id: <integer>]
+[IP: <integer>]
+
+<proc type string>* := IA32/X64 | IA64
+
+<proc isa string>* := IA32 | IA64 | X64
+
+<processor error type strings># :=
+[cache error][, TLB error][, bus error][, micro-architectural error]
+
+<proc operation string>* := unknown or generic | data read | data write | \
+instruction execution
+
+<proc flags strings># :=
+[restartable][, precise IP][, overflow][, corrected]
+
+<memory section data> :=
+[error_status: <integer>]
+[physical_address: <integer>]
+[physical_address_mask: <integer>]
+[node: <integer>]
+[card: <integer>]
+[module: <integer>]
+[bank: <integer>]
+[device: <integer>]
+[row: <integer>]
+[column: <integer>]
+[bit_position: <integer>]
+[requestor_id: <integer>]
+[responder_id: <integer>]
+[target_id: <integer>]
+[error_type: <integer>, <mem error type string>]
+
+<mem error type string>* :=
+unknown | no error | single-bit ECC | multi-bit ECC | \
+single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
+target abort | parity error | watchdog timeout | invalid address | \
+mirror Broken | memory sparing | scrub corrected error | \
+scrub uncorrected error
+
+<pcie section data> :=
+[port_type: <integer>, <pcie port type string>]
+[version: <integer>.<integer>]
+[command: <integer>, status: <integer>]
+[device_id: <integer>:<integer>:<integer>.<integer>
+slot: <integer>
+secondary_bus: <integer>
+vendor_id: <integer>, device_id: <integer>
+class_code: <integer>]
+[serial number: <integer>, <integer>]
+[bridge: secondary_status: <integer>, control: <integer>]
+[aer_status: <integer>, aer_mask: <integer>
+<aer status string>
+[aer_uncor_severity: <integer>]
+aer_layer=<aer layer string>, aer_agent=<aer agent string>
+aer_tlp_header: <integer> <integer> <integer> <integer>]
+
+<pcie port type string>* := PCIe end point | legacy PCI end point | \
+unknown | unknown | root port | upstream switch port | \
+downstream switch port | PCIe to PCI/PCI-X bridge | \
+PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
+root complex event collector
+
+if section severity is fatal or recoverable
+<aer status string># :=
+unknown | unknown | unknown | unknown | Data Link Protocol | \
+unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
+Poisoned TLP | Flow Control Protocol | Completion Timeout | \
+Completer Abort | Unexpected Completion | Receiver Overflow | \
+Malformed TLP | ECRC | Unsupported Request
+else
+<aer status string># :=
+Receiver Error | unknown | unknown | unknown | unknown | unknown | \
+Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
+Replay Timer Timeout | Advisory Non-Fatal
+fi
+
+<aer layer string> :=
+Physical Layer | Data Link Layer | Transaction Layer
+
+<aer agent string> :=
+Receiver ID | Requester ID | Completer ID | Transmitter ID
+
+Where, [] designate corresponding content is optional
+
+All <field string> description with * has the following format:
+
+field: <integer>, <field string>
+
+Where value of <integer> should be the position of "string" in <field
+string> description. Otherwise, <field string> will be "unknown".
+
+All <field strings> description with # has the following format:
+
+field: <integer>
+<field strings>
+
+Where each string in <fields strings> corresponding to one set bit of
+<integer>. The bit position is the position of "string" in <field
+strings> description.
+
+For more detailed explanation of every field, please refer to UEFI
+specification version 2.3 or later, section Appendix N: Common
+Platform Error Record.
diff --git a/Documentation/acpi/cppc_sysfs.txt b/Documentation/acpi/cppc_sysfs.txt
new file mode 100644
index 0000000..f20fb44
--- /dev/null
+++ b/Documentation/acpi/cppc_sysfs.txt
@@ -0,0 +1,69 @@
+
+ Collaborative Processor Performance Control (CPPC)
+
+CPPC defined in the ACPI spec describes a mechanism for the OS to manage the
+performance of a logical processor on a contigious and abstract performance
+scale. CPPC exposes a set of registers to describe abstract performance scale,
+to request performance levels and to measure per-cpu delivered performance.
+
+For more details on CPPC please refer to the ACPI specification at:
+
+http://uefi.org/specifications
+
+Some of the CPPC registers are exposed via sysfs under:
+
+/sys/devices/system/cpu/cpuX/acpi_cppc/
+
+for each cpu X
+
+--------------------------------------------------------------------------------
+
+$ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
+/sys/devices/system/cpu/cpu0/acpi_cppc/:
+total 0
+-r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
+-r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
+-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
+-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
+-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
+-r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
+-r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
+-r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
+-r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
+
+--------------------------------------------------------------------------------
+
+* highest_perf : Highest performance of this processor (abstract scale).
+* nominal_perf : Highest sustained performance of this processor (abstract scale).
+* lowest_nonlinear_perf : Lowest performance of this processor with nonlinear
+ power savings (abstract scale).
+* lowest_perf : Lowest performance of this processor (abstract scale).
+
+* lowest_freq : CPU frequency corresponding to lowest_perf (in MHz).
+* nominal_freq : CPU frequency corresponding to nominal_perf (in MHz).
+ The above frequencies should only be used to report processor performance in
+ freqency instead of abstract scale. These values should not be used for any
+ functional decisions.
+
+* feedback_ctrs : Includes both Reference and delivered performance counter.
+ Reference counter ticks up proportional to processor's reference performance.
+ Delivered counter ticks up proportional to processor's delivered performance.
+* wraparound_time: Minimum time for the feedback counters to wraparound (seconds).
+* reference_perf : Performance level at which reference performance counter
+ accumulates (abstract scale).
+
+--------------------------------------------------------------------------------
+
+ Computing Average Delivered Performance
+
+Below describes the steps to compute the average performance delivered by taking
+two different snapshots of feedback counters at time T1 and T2.
+
+T1: Read feedback_ctrs as fbc_t1
+ Wait or run some workload
+T2: Read feedback_ctrs as fbc_t2
+
+delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
+reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
+
+delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
diff --git a/Documentation/acpi/debug.txt b/Documentation/acpi/debug.txt
new file mode 100644
index 0000000..65bf47c
--- /dev/null
+++ b/Documentation/acpi/debug.txt
@@ -0,0 +1,148 @@
+ ACPI Debug Output
+
+
+The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
+output. This document describes how to use this facility.
+
+Compile-time configuration
+--------------------------
+
+ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config
+option is turned off, the debug messages are not even built into the
+kernel.
+
+Boot- and run-time configuration
+--------------------------------
+
+When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages
+you're interested in. At boot-time, use the acpi.debug_layer and
+acpi.debug_level kernel command line options. After boot, you can use the
+debug_layer and debug_level files in /sys/module/acpi/parameters/ to control
+the debug messages.
+
+debug_layer (component)
+-----------------------
+
+The "debug_layer" is a mask that selects components of interest, e.g., a
+specific driver or part of the ACPI interpreter. To build the debug_layer
+bitmask, look for the "#define _COMPONENT" in an ACPI source file.
+
+You can set the debug_layer mask at boot-time using the acpi.debug_layer
+command line argument, and you can change it after boot by writing values
+to /sys/module/acpi/parameters/debug_layer.
+
+The possible components are defined in include/acpi/acoutput.h and
+include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer
+shows the supported mask values, currently these:
+
+ ACPI_UTILITIES 0x00000001
+ ACPI_HARDWARE 0x00000002
+ ACPI_EVENTS 0x00000004
+ ACPI_TABLES 0x00000008
+ ACPI_NAMESPACE 0x00000010
+ ACPI_PARSER 0x00000020
+ ACPI_DISPATCHER 0x00000040
+ ACPI_EXECUTER 0x00000080
+ ACPI_RESOURCES 0x00000100
+ ACPI_CA_DEBUGGER 0x00000200
+ ACPI_OS_SERVICES 0x00000400
+ ACPI_CA_DISASSEMBLER 0x00000800
+ ACPI_COMPILER 0x00001000
+ ACPI_TOOLS 0x00002000
+ ACPI_BUS_COMPONENT 0x00010000
+ ACPI_AC_COMPONENT 0x00020000
+ ACPI_BATTERY_COMPONENT 0x00040000
+ ACPI_BUTTON_COMPONENT 0x00080000
+ ACPI_SBS_COMPONENT 0x00100000
+ ACPI_FAN_COMPONENT 0x00200000
+ ACPI_PCI_COMPONENT 0x00400000
+ ACPI_POWER_COMPONENT 0x00800000
+ ACPI_CONTAINER_COMPONENT 0x01000000
+ ACPI_SYSTEM_COMPONENT 0x02000000
+ ACPI_THERMAL_COMPONENT 0x04000000
+ ACPI_MEMORY_DEVICE_COMPONENT 0x08000000
+ ACPI_VIDEO_COMPONENT 0x10000000
+ ACPI_PROCESSOR_COMPONENT 0x20000000
+
+debug_level
+-----------
+
+The "debug_level" is a mask that selects different types of messages, e.g.,
+those related to initialization, method execution, informational messages, etc.
+To build debug_level, look at the level specified in an ACPI_DEBUG_PRINT()
+statement.
+
+The ACPI interpreter uses several different levels, but the Linux
+ACPI core and ACPI drivers generally only use ACPI_LV_INFO.
+
+You can set the debug_level mask at boot-time using the acpi.debug_level
+command line argument, and you can change it after boot by writing values
+to /sys/module/acpi/parameters/debug_level.
+
+The possible levels are defined in include/acpi/acoutput.h. Reading
+/sys/module/acpi/parameters/debug_level shows the supported mask values,
+currently these:
+
+ ACPI_LV_INIT 0x00000001
+ ACPI_LV_DEBUG_OBJECT 0x00000002
+ ACPI_LV_INFO 0x00000004
+ ACPI_LV_INIT_NAMES 0x00000020
+ ACPI_LV_PARSE 0x00000040
+ ACPI_LV_LOAD 0x00000080
+ ACPI_LV_DISPATCH 0x00000100
+ ACPI_LV_EXEC 0x00000200
+ ACPI_LV_NAMES 0x00000400
+ ACPI_LV_OPREGION 0x00000800
+ ACPI_LV_BFIELD 0x00001000
+ ACPI_LV_TABLES 0x00002000
+ ACPI_LV_VALUES 0x00004000
+ ACPI_LV_OBJECTS 0x00008000
+ ACPI_LV_RESOURCES 0x00010000
+ ACPI_LV_USER_REQUESTS 0x00020000
+ ACPI_LV_PACKAGE 0x00040000
+ ACPI_LV_ALLOCATIONS 0x00100000
+ ACPI_LV_FUNCTIONS 0x00200000
+ ACPI_LV_OPTIMIZATIONS 0x00400000
+ ACPI_LV_MUTEX 0x01000000
+ ACPI_LV_THREADS 0x02000000
+ ACPI_LV_IO 0x04000000
+ ACPI_LV_INTERRUPTS 0x08000000
+ ACPI_LV_AML_DISASSEMBLE 0x10000000
+ ACPI_LV_VERBOSE_INFO 0x20000000
+ ACPI_LV_FULL_TABLES 0x40000000
+ ACPI_LV_EVENTS 0x80000000
+
+Examples
+--------
+
+For example, drivers/acpi/bus.c contains this:
+
+ #define _COMPONENT ACPI_BUS_COMPONENT
+ ...
+ ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Device insertion detected\n"));
+
+To turn on this message, set the ACPI_BUS_COMPONENT bit in acpi.debug_layer
+and the ACPI_LV_INFO bit in acpi.debug_level. (The ACPI_DEBUG_PRINT
+statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO
+definition.)
+
+Enable all AML "Debug" output (stores to the Debug object while interpreting
+AML) during boot:
+
+ acpi.debug_layer=0xffffffff acpi.debug_level=0x2
+
+Enable PCI and PCI interrupt routing debug messages:
+
+ acpi.debug_layer=0x400000 acpi.debug_level=0x4
+
+Enable all ACPI hardware-related messages:
+
+ acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
+
+Enable all ACPI_DB_INFO messages after boot:
+
+ # echo 0x4 > /sys/module/acpi/parameters/debug_level
+
+Show all valid component values:
+
+ # cat /sys/module/acpi/parameters/debug_layer
diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt
new file mode 100644
index 0000000..c387156
--- /dev/null
+++ b/Documentation/acpi/dsd/data-node-references.txt
@@ -0,0 +1,89 @@
+Copyright (C) 2018 Intel Corporation
+Author: Sakari Ailus <sakari.ailus@linux.intel.com>
+
+
+Referencing hierarchical data nodes
+-----------------------------------
+
+ACPI in general allows referring to device objects in the tree only.
+Hierarchical data extension nodes may not be referred to directly, hence this
+document defines a scheme to implement such references.
+
+A reference consist of the device object name followed by one or more
+hierarchical data extension [1] keys. Specifically, the hierarchical data
+extension node which is referred to by the key shall lie directly under the
+parent object i.e. either the device object or another hierarchical data
+extension node.
+
+The keys in the hierarchical data nodes shall consist of the name of the node,
+"@" character and the number of the node in hexadecimal notation (without pre-
+or postfixes). The same ACPI object shall include the _DSD property extension
+with a property "reg" that shall have the same numerical value as the number of
+the node.
+
+In case a hierarchical data extensions node has no numerical value, then the
+"reg" property shall be omitted from the ACPI object's _DSD properties and the
+"@" character and the number shall be omitted from the hierarchical data
+extension key.
+
+
+Example
+-------
+
+ In the ASL snippet below, the "reference" _DSD property [2] contains a
+ device object reference to DEV0 and under that device object, a
+ hierarchical data extension key "node@1" referring to the NOD1 object
+ and lastly, a hierarchical data extension key "anothernode" referring to
+ the ANOD object which is also the final target node of the reference.
+
+ Device (DEV0)
+ {
+ Name (_DSD, Package () {
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "node@0", NOD0 },
+ Package () { "node@1", NOD1 },
+ }
+ })
+ Name (NOD0, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "random-property", 3 },
+ }
+ })
+ Name (NOD1, Package() {
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "anothernode", ANOD },
+ }
+ })
+ Name (ANOD, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "random-property", 0 },
+ }
+ })
+ }
+
+ Device (DEV1)
+ {
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reference", ^DEV0, "node@1", "anothernode" },
+ }
+ })
+ }
+
+Please also see a graph example in graph.txt .
+
+References
+----------
+
+[1] Hierarchical Data Extension UUID For _DSD.
+ <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+ referenced 2018-07-17.
+
+[2] Device Properties UUID For _DSD.
+ <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+ referenced 2016-10-04.
diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt
new file mode 100644
index 0000000..b9ce910
--- /dev/null
+++ b/Documentation/acpi/dsd/graph.txt
@@ -0,0 +1,174 @@
+Graphs
+
+
+_DSD
+----
+
+_DSD (Device Specific Data) [7] is a predefined ACPI device
+configuration object that can be used to convey information on
+hardware features which are not specifically covered by the ACPI
+specification [1][6]. There are two _DSD extensions that are relevant
+for graphs: property [4] and hierarchical data extensions [5]. The
+property extension provides generic key-value pairs whereas the
+hierarchical data extension supports nodes with references to other
+nodes, forming a tree. The nodes in the tree may contain properties as
+defined by the property extension. The two extensions together provide
+a tree-like structure with zero or more properties (key-value pairs)
+in each node of the tree.
+
+The data structure may be accessed at runtime by using the device_*
+and fwnode_* functions defined in include/linux/fwnode.h .
+
+Fwnode represents a generic firmware node object. It is independent on
+the firmware type. In ACPI, fwnodes are _DSD hierarchical data
+extensions objects. A device's _DSD object is represented by an
+fwnode.
+
+The data structure may be referenced to elsewhere in the ACPI tables
+by using a hard reference to the device itself and an index to the
+hierarchical data extension array on each depth.
+
+
+Ports and endpoints
+-------------------
+
+The port and endpoint concepts are very similar to those in Devicetree
+[3]. A port represents an interface in a device, and an endpoint
+represents a connection to that interface.
+
+All port nodes are located under the device's "_DSD" node in the hierarchical
+data extension tree. The data extension related to each port node must begin
+with "port" and must be followed by the "@" character and the number of the port
+as its key. The target object it refers to should be called "PRTX", where "X" is
+the number of the port. An example of such a package would be:
+
+ Package() { "port@4", PRT4 }
+
+Further on, endpoints are located under the port nodes. The hierarchical
+data extension key of the endpoint nodes must begin with
+"endpoint" and must be followed by the "@" character and the number of the
+endpoint. The object it refers to should be called "EPXY", where "X" is the
+number of the port and "Y" is the number of the endpoint. An example of such a
+package would be:
+
+ Package() { "endpoint@0", EP40 }
+
+Each port node contains a property extension key "port", the value of which is
+the number of the port. Each endpoint is similarly numbered with a property
+extension key "reg", the value of which is the number of the endpoint. Port
+numbers must be unique within a device and endpoint numbers must be unique
+within a port. If a device object may only has a single port, then the number
+of that port shall be zero. Similarly, if a port may only have a single
+endpoint, the number of that endpoint shall be zero.
+
+The endpoint reference uses property extension with "remote-endpoint" property
+name followed by a reference in the same package. Such references consist of the
+the remote device reference, the first package entry of the port data extension
+reference under the device and finally the first package entry of the endpoint
+data extension reference under the port. Individual references thus appear as:
+
+ Package() { device, "port@X", "endpoint@Y" }
+
+In the above example, "X" is the number of the port and "Y" is the number of the
+endpoint.
+
+The references to endpoints must be always done both ways, to the
+remote endpoint and back from the referred remote endpoint node.
+
+A simple example of this is show below:
+
+ Scope (\_SB.PCI0.I2C2)
+ {
+ Device (CAM0)
+ {
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "compatible", Package () { "nokia,smia" } },
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "port@0", PRT0 },
+ }
+ })
+ Name (PRT0, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "endpoint@0", EP00 },
+ }
+ })
+ Name (EP00, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
+ }
+ })
+ }
+ }
+
+ Scope (\_SB.PCI0)
+ {
+ Device (ISP)
+ {
+ Name (_DSD, Package () {
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "port@4", PRT4 },
+ }
+ })
+
+ Name (PRT4, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 4 }, /* CSI-2 port number */
+ },
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () { "endpoint@0", EP40 },
+ }
+ })
+
+ Name (EP40, Package() {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "reg", 0 },
+ Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
+ }
+ })
+ }
+ }
+
+Here, the port 0 of the "CAM0" device is connected to the port 4 of
+the "ISP" device and vice versa.
+
+
+References
+----------
+
+[1] _DSD (Device Specific Data) Implementation Guide.
+ <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>,
+ referenced 2016-10-03.
+
+[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03.
+
+[3] Documentation/devicetree/bindings/graph.txt
+
+[4] Device Properties UUID For _DSD.
+ <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+ referenced 2016-10-04.
+
+[5] Hierarchical Data Extension UUID For _DSD.
+ <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+ referenced 2016-10-04.
+
+[6] Advanced Configuration and Power Interface Specification.
+ <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>,
+ referenced 2016-10-04.
+
+[7] _DSD Device Properties Usage Rules.
+ Documentation/acpi/DSD-properties-rules.txt
diff --git a/Documentation/acpi/dsdt-override.txt b/Documentation/acpi/dsdt-override.txt
new file mode 100644
index 0000000..784841c
--- /dev/null
+++ b/Documentation/acpi/dsdt-override.txt
@@ -0,0 +1,7 @@
+Linux supports a method of overriding the BIOS DSDT:
+
+CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel.
+
+When to use this method is described in detail on the
+Linux/ACPI home page:
+https://01.org/linux-acpi/documentation/overriding-dsdt
diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt
new file mode 100644
index 0000000..7bcf9c3
--- /dev/null
+++ b/Documentation/acpi/enumeration.txt
@@ -0,0 +1,426 @@
+ACPI based device enumeration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
+SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
+devices behind serial bus controllers.
+
+In addition we are starting to see peripherals integrated in the
+SoC/Chipset to appear only in ACPI namespace. These are typically devices
+that are accessed through memory-mapped registers.
+
+In order to support this and re-use the existing drivers as much as
+possible we decided to do following:
+
+ o Devices that have no bus connector resource are represented as
+ platform devices.
+
+ o Devices behind real busses where there is a connector resource
+ are represented as struct spi_device or struct i2c_device
+ (standard UARTs are not busses so there is no struct uart_device).
+
+As both ACPI and Device Tree represent a tree of devices (and their
+resources) this implementation follows the Device Tree way as much as
+possible.
+
+The ACPI implementation enumerates devices behind busses (platform, SPI and
+I2C), creates the physical devices and binds them to their ACPI handle in
+the ACPI namespace.
+
+This means that when ACPI_HANDLE(dev) returns non-NULL the device was
+enumerated from ACPI namespace. This handle can be used to extract other
+device-specific configuration. There is an example of this below.
+
+Platform bus support
+~~~~~~~~~~~~~~~~~~~~
+Since we are using platform devices to represent devices that are not
+connected to any physical bus we only need to implement a platform driver
+for the device and add supported ACPI IDs. If this same IP-block is used on
+some other non-ACPI platform, the driver might work out of the box or needs
+some minor changes.
+
+Adding ACPI support for an existing driver should be pretty
+straightforward. Here is the simplest example:
+
+ #ifdef CONFIG_ACPI
+ static const struct acpi_device_id mydrv_acpi_match[] = {
+ /* ACPI IDs here */
+ { }
+ };
+ MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
+ #endif
+
+ static struct platform_driver my_driver = {
+ ...
+ .driver = {
+ .acpi_match_table = ACPI_PTR(mydrv_acpi_match),
+ },
+ };
+
+If the driver needs to perform more complex initialization like getting and
+configuring GPIOs it can get its ACPI handle and extract this information
+from ACPI tables.
+
+DMA support
+~~~~~~~~~~~
+DMA controllers enumerated via ACPI should be registered in the system to
+provide generic access to their resources. For example, a driver that would
+like to be accessible to slave devices via generic API call
+dma_request_slave_channel() must register itself at the end of the probe
+function like this:
+
+ err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
+ /* Handle the error if it's not a case of !CONFIG_ACPI */
+
+and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
+is enough) which converts the FixedDMA resource provided by struct
+acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
+could look like:
+
+ #ifdef CONFIG_ACPI
+ struct filter_args {
+ /* Provide necessary information for the filter_func */
+ ...
+ };
+
+ static bool filter_func(struct dma_chan *chan, void *param)
+ {
+ /* Choose the proper channel */
+ ...
+ }
+
+ static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
+ struct acpi_dma *adma)
+ {
+ dma_cap_mask_t cap;
+ struct filter_args args;
+
+ /* Prepare arguments for filter_func */
+ ...
+ return dma_request_channel(cap, filter_func, &args);
+ }
+ #else
+ static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
+ struct acpi_dma *adma)
+ {
+ return NULL;
+ }
+ #endif
+
+dma_request_slave_channel() will call xlate_func() for each registered DMA
+controller. In the xlate function the proper channel must be chosen based on
+information in struct acpi_dma_spec and the properties of the controller
+provided by struct acpi_dma.
+
+Clients must call dma_request_slave_channel() with the string parameter that
+corresponds to a specific FixedDMA resource. By default "tx" means the first
+entry of the FixedDMA resource array, "rx" means the second entry. The table
+below shows a layout:
+
+ Device (I2C0)
+ {
+ ...
+ Method (_CRS, 0, NotSerialized)
+ {
+ Name (DBUF, ResourceTemplate ()
+ {
+ FixedDMA (0x0018, 0x0004, Width32bit, _Y48)
+ FixedDMA (0x0019, 0x0005, Width32bit, )
+ })
+ ...
+ }
+ }
+
+So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in
+this example.
+
+In robust cases the client unfortunately needs to call
+acpi_dma_request_slave_chan_by_index() directly and therefore choose the
+specific FixedDMA resource by its index.
+
+SPI serial bus support
+~~~~~~~~~~~~~~~~~~~~~~
+Slave devices behind SPI bus have SpiSerialBus resource attached to them.
+This is extracted automatically by the SPI core and the slave devices are
+enumerated once spi_register_master() is called by the bus driver.
+
+Here is what the ACPI namespace for a SPI slave might look like:
+
+ Device (EEP0)
+ {
+ Name (_ADR, 1)
+ Name (_CID, Package() {
+ "ATML0025",
+ "AT25",
+ })
+ ...
+ Method (_CRS, 0, NotSerialized)
+ {
+ SPISerialBus(1, PolarityLow, FourWireMode, 8,
+ ControllerInitiated, 1000000, ClockPolarityLow,
+ ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
+ }
+ ...
+
+The SPI device drivers only need to add ACPI IDs in a similar way than with
+the platform device drivers. Below is an example where we add ACPI support
+to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
+
+ #ifdef CONFIG_ACPI
+ static const struct acpi_device_id at25_acpi_match[] = {
+ { "AT25", 0 },
+ { },
+ };
+ MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
+ #endif
+
+ static struct spi_driver at25_driver = {
+ .driver = {
+ ...
+ .acpi_match_table = ACPI_PTR(at25_acpi_match),
+ },
+ };
+
+Note that this driver actually needs more information like page size of the
+eeprom etc. but at the time writing this there is no standard way of
+passing those. One idea is to return this in _DSM method like:
+
+ Device (EEP0)
+ {
+ ...
+ Method (_DSM, 4, NotSerialized)
+ {
+ Store (Package (6)
+ {
+ "byte-len", 1024,
+ "addr-mode", 2,
+ "page-size, 32
+ }, Local0)
+
+ // Check UUIDs etc.
+
+ Return (Local0)
+ }
+
+Then the at25 SPI driver can get this configuration by calling _DSM on its
+ACPI handle like:
+
+ struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
+ struct acpi_object_list input;
+ acpi_status status;
+
+ /* Fill in the input buffer */
+
+ status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
+ &input, &output);
+ if (ACPI_FAILURE(status))
+ /* Handle the error */
+
+ /* Extract the data here */
+
+ kfree(output.pointer);
+
+I2C serial bus support
+~~~~~~~~~~~~~~~~~~~~~~
+The slaves behind I2C bus controller only need to add the ACPI IDs like
+with the platform and SPI drivers. The I2C core automatically enumerates
+any slave devices behind the controller device once the adapter is
+registered.
+
+Below is an example of how to add ACPI support to the existing mpu3050
+input driver:
+
+ #ifdef CONFIG_ACPI
+ static const struct acpi_device_id mpu3050_acpi_match[] = {
+ { "MPU3050", 0 },
+ { },
+ };
+ MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
+ #endif
+
+ static struct i2c_driver mpu3050_i2c_driver = {
+ .driver = {
+ .name = "mpu3050",
+ .owner = THIS_MODULE,
+ .pm = &mpu3050_pm,
+ .of_match_table = mpu3050_of_match,
+ .acpi_match_table = ACPI_PTR(mpu3050_acpi_match),
+ },
+ .probe = mpu3050_probe,
+ .remove = mpu3050_remove,
+ .id_table = mpu3050_ids,
+ };
+
+GPIO support
+~~~~~~~~~~~~
+ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
+and GpioInt. These resources can be used to pass GPIO numbers used by
+the device to the driver. ACPI 5.1 extended this with _DSD (Device
+Specific Data) which made it possible to name the GPIOs among other things.
+
+For example:
+
+Device (DEV)
+{
+ Method (_CRS, 0, NotSerialized)
+ {
+ Name (SBUF, ResourceTemplate()
+ {
+ ...
+ // Used to power on/off the device
+ GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
+ IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
+ 0x00, ResourceConsumer,,)
+ {
+ // Pin List
+ 0x0055
+ }
+
+ // Interrupt for the device
+ GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
+ 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
+ {
+ // Pin list
+ 0x0058
+ }
+
+ ...
+
+ }
+
+ Return (SBUF)
+ }
+
+ // ACPI 5.1 _DSD used for naming the GPIOs
+ Name (_DSD, Package ()
+ {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package ()
+ {
+ Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
+ Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
+ }
+ })
+ ...
+
+These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
+specifies the path to the controller. In order to use these GPIOs in Linux
+we need to translate them to the corresponding Linux GPIO descriptors.
+
+There is a standard GPIO API for that and is documented in
+Documentation/gpio/.
+
+In the above example we can get the corresponding two GPIO descriptors with
+a code like this:
+
+ #include <linux/gpio/consumer.h>
+ ...
+
+ struct gpio_desc *irq_desc, *power_desc;
+
+ irq_desc = gpiod_get(dev, "irq");
+ if (IS_ERR(irq_desc))
+ /* handle error */
+
+ power_desc = gpiod_get(dev, "power");
+ if (IS_ERR(power_desc))
+ /* handle error */
+
+ /* Now we can use the GPIO descriptors */
+
+There are also devm_* versions of these functions which release the
+descriptors once the device is released.
+
+See Documentation/acpi/gpio-properties.txt for more information about the
+_DSD binding related to GPIOs.
+
+MFD devices
+~~~~~~~~~~~
+The MFD devices register their children as platform devices. For the child
+devices there needs to be an ACPI handle that they can use to reference
+parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
+we provide two ways:
+
+ o The children share the parent ACPI handle.
+ o The MFD cell can specify the ACPI id of the device.
+
+For the first case, the MFD drivers do not need to do anything. The
+resulting child platform device will have its ACPI_COMPANION() set to point
+to the parent device.
+
+If the ACPI namespace has a device that we can match using an ACPI id or ACPI
+adr, the cell should be set like:
+
+ static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {
+ .pnpid = "XYZ0001",
+ .adr = 0,
+ };
+
+ static struct mfd_cell my_subdevice_cell = {
+ .name = "my_subdevice",
+ /* set the resources relative to the parent */
+ .acpi_match = &my_subdevice_cell_acpi_match,
+ };
+
+The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under
+the MFD device and if found, that ACPI companion device is bound to the
+resulting child platform device.
+
+Device Tree namespace link device ID
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Device Tree protocol uses device identification based on the "compatible"
+property whose value is a string or an array of strings recognized as device
+identifiers by drivers and the driver core. The set of all those strings may be
+regarded as a device identification namespace analogous to the ACPI/PNP device
+ID namespace. Consequently, in principle it should not be necessary to allocate
+a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing
+identification string in the Device Tree (DT) namespace, especially if that ID
+is only needed to indicate that a given device is compatible with another one,
+presumably having a matching driver in the kernel already.
+
+In ACPI, the device identification object called _CID (Compatible ID) is used to
+list the IDs of devices the given one is compatible with, but those IDs must
+belong to one of the namespaces prescribed by the ACPI specification (see
+Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them.
+Moreover, the specification mandates that either a _HID or an _ADR identification
+object be present for all ACPI objects representing devices (Section 6.1 of ACPI
+6.0). For non-enumerable bus types that object must be _HID and its value must
+be a device ID from one of the namespaces prescribed by the specification too.
+
+The special DT namespace link device ID, PRP0001, provides a means to use the
+existing DT-compatible device identification in ACPI and to satisfy the above
+requirements following from the ACPI specification at the same time. Namely,
+if PRP0001 is returned by _HID, the ACPI subsystem will look for the
+"compatible" property in the device object's _DSD and will use the value of that
+property to identify the corresponding device in analogy with the original DT
+device identification algorithm. If the "compatible" property is not present
+or its value is not valid, the device will not be enumerated by the ACPI
+subsystem. Otherwise, it will be enumerated automatically as a platform device
+(except when an I2C or SPI link from the device to its parent is present, in
+which case the ACPI core will leave the device enumeration to the parent's
+driver) and the identification strings from the "compatible" property value will
+be used to find a driver for the device along with the device IDs listed by _CID
+(if present).
+
+Analogously, if PRP0001 is present in the list of device IDs returned by _CID,
+the identification strings listed by the "compatible" property value (if present
+and valid) will be used to look for a driver matching the device, but in that
+case their relative priority with respect to the other device IDs listed by
+_HID and _CID depends on the position of PRP0001 in the _CID return package.
+Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID
+return package will be checked first. Also in that case the bus type the device
+will be enumerated to depends on the device ID returned by _HID.
+
+It is valid to define device objects with a _HID returning PRP0001 and without
+the "compatible" property in the _DSD or a _CID as long as one of their
+ancestors provides a _DSD with a valid "compatible" property. Such device
+objects are then simply regarded as additional "blocks" providing hierarchical
+configuration information to the driver of the composite ancestor device.
+
+However, PRP0001 can only be returned from either _HID or _CID of a device
+object if all of the properties returned by the _DSD associated with it (either
+the _DSD of the device object itself or the _DSD of its ancestor in the
+"composite device" case described above) can be used in the ACPI environment.
+Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
+property returned by it is meaningless.
+
+Refer to DSD-properties-rules.txt for more information.
diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt
new file mode 100644
index 0000000..88c65cb
--- /dev/null
+++ b/Documentation/acpi/gpio-properties.txt
@@ -0,0 +1,223 @@
+_DSD Device Properties Related to GPIO
+--------------------------------------
+
+With the release of ACPI 5.1, the _DSD configuration object finally
+allows names to be given to GPIOs (and other things as well) returned
+by _CRS. Previously, we were only able to use an integer index to find
+the corresponding GPIO, which is pretty error prone (it depends on
+the _CRS output ordering, for example).
+
+With _DSD we can now query GPIOs using a name instead of an integer
+index, like the ASL example below shows:
+
+ // Bluetooth device with reset and shutdown GPIOs
+ Device (BTH)
+ {
+ Name (_HID, ...)
+
+ Name (_CRS, ResourceTemplate ()
+ {
+ GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly,
+ "\\_SB.GPO0", 0, ResourceConsumer) {15}
+ GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly,
+ "\\_SB.GPO0", 0, ResourceConsumer) {27, 31}
+ })
+
+ Name (_DSD, Package ()
+ {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package ()
+ {
+ Package () {"reset-gpios", Package() {^BTH, 1, 1, 0 }},
+ Package () {"shutdown-gpios", Package() {^BTH, 0, 0, 0 }},
+ }
+ })
+ }
+
+The format of the supported GPIO property is:
+
+ Package () { "name", Package () { ref, index, pin, active_low }}
+
+ ref - The device that has _CRS containing GpioIo()/GpioInt() resources,
+ typically this is the device itself (BTH in our case).
+ index - Index of the GpioIo()/GpioInt() resource in _CRS starting from zero.
+ pin - Pin in the GpioIo()/GpioInt() resource. Typically this is zero.
+ active_low - If 1 the GPIO is marked as active_low.
+
+Since ACPI GpioIo() resource does not have a field saying whether it is
+active low or high, the "active_low" argument can be used here. Setting
+it to 1 marks the GPIO as active low.
+
+In our Bluetooth example the "reset-gpios" refers to the second GpioIo()
+resource, second pin in that resource with the GPIO number of 31.
+
+It is possible to leave holes in the array of GPIOs. This is useful in
+cases like with SPI host controllers where some chip selects may be
+implemented as GPIOs and some as native signals. For example a SPI host
+controller can have chip selects 0 and 2 implemented as GPIOs and 1 as
+native:
+
+ Package () {
+ "cs-gpios",
+ Package () {
+ ^GPIO, 19, 0, 0, // chip select 0: GPIO
+ 0, // chip select 1: native signal
+ ^GPIO, 20, 0, 0, // chip select 2: GPIO
+ }
+ }
+
+Other supported properties
+--------------------------
+
+Following Device Tree compatible device properties are also supported by
+_DSD device properties for GPIO controllers:
+
+- gpio-hog
+- output-high
+- output-low
+- input
+- line-name
+
+Example:
+
+ Name (_DSD, Package () {
+ // _DSD Hierarchical Properties Extension UUID
+ ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+ Package () {
+ Package () {"hog-gpio8", "G8PU"}
+ }
+ })
+
+ Name (G8PU, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () {"gpio-hog", 1},
+ Package () {"gpios", Package () {8, 0}},
+ Package () {"output-high", 1},
+ Package () {"line-name", "gpio8-pullup"},
+ }
+ })
+
+- gpio-line-names
+
+Example:
+
+ Package () {
+ "gpio-line-names",
+ Package () {
+ "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", "MUX7_IO",
+ "LVL_C_A1", "MUX0_IO", "SPI1_MISO"
+ }
+ }
+
+See Documentation/devicetree/bindings/gpio/gpio.txt for more information
+about these properties.
+
+ACPI GPIO Mappings Provided by Drivers
+--------------------------------------
+
+There are systems in which the ACPI tables do not contain _DSD but provide _CRS
+with GpioIo()/GpioInt() resources and device drivers still need to work with
+them.
+
+In those cases ACPI device identification objects, _HID, _CID, _CLS, _SUB, _HRV,
+available to the driver can be used to identify the device and that is supposed
+to be sufficient to determine the meaning and purpose of all of the GPIO lines
+listed by the GpioIo()/GpioInt() resources returned by _CRS. In other words,
+the driver is supposed to know what to use the GpioIo()/GpioInt() resources for
+once it has identified the device. Having done that, it can simply assign names
+to the GPIO lines it is going to use and provide the GPIO subsystem with a
+mapping between those names and the ACPI GPIO resources corresponding to them.
+
+To do that, the driver needs to define a mapping table as a NULL-terminated
+array of struct acpi_gpio_mapping objects that each contain a name, a pointer
+to an array of line data (struct acpi_gpio_params) objects and the size of that
+array. Each struct acpi_gpio_params object consists of three fields,
+crs_entry_index, line_index, active_low, representing the index of the target
+GpioIo()/GpioInt() resource in _CRS starting from zero, the index of the target
+line in that resource starting from zero, and the active-low flag for that line,
+respectively, in analogy with the _DSD GPIO property format specified above.
+
+For the example Bluetooth device discussed previously the data structures in
+question would look like this:
+
+static const struct acpi_gpio_params reset_gpio = { 1, 1, false };
+static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false };
+
+static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
+ { "reset-gpios", &reset_gpio, 1 },
+ { "shutdown-gpios", &shutdown_gpio, 1 },
+ { },
+};
+
+Next, the mapping table needs to be passed as the second argument to
+acpi_dev_add_driver_gpios() that will register it with the ACPI device object
+pointed to by its first argument. That should be done in the driver's .probe()
+routine. On removal, the driver should unregister its GPIO mapping table by
+calling acpi_dev_remove_driver_gpios() on the ACPI device object where that
+table was previously registered.
+
+Using the _CRS fallback
+-----------------------
+
+If a device does not have _DSD or the driver does not create ACPI GPIO
+mapping, the Linux GPIO framework refuses to return any GPIOs. This is
+because the driver does not know what it actually gets. For example if we
+have a device like below:
+
+ Device (BTH)
+ {
+ Name (_HID, ...)
+
+ Name (_CRS, ResourceTemplate () {
+ GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone,
+ "\\_SB.GPO0", 0, ResourceConsumer) {15}
+ GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone,
+ "\\_SB.GPO0", 0, ResourceConsumer) {27}
+ })
+ }
+
+The driver might expect to get the right GPIO when it does:
+
+ desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW);
+
+but since there is no way to know the mapping between "reset" and
+the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT).
+
+The driver author can solve this by passing the mapping explictly
+(the recommended way and documented in the above chapter).
+
+The ACPI GPIO mapping tables should not contaminate drivers that are not
+knowing about which exact device they are servicing on. It implies that
+the ACPI GPIO mapping tables are hardly linked to ACPI ID and certain
+objects, as listed in the above chapter, of the device in question.
+
+Getting GPIO descriptor
+-----------------------
+
+There are two main approaches to get GPIO resource from ACPI:
+ desc = gpiod_get(dev, connection_id, flags);
+ desc = gpiod_get_index(dev, connection_id, index, flags);
+
+We may consider two different cases here, i.e. when connection ID is
+provided and otherwise.
+
+Case 1:
+ desc = gpiod_get(dev, "non-null-connection-id", flags);
+ desc = gpiod_get_index(dev, "non-null-connection-id", index, flags);
+
+Case 2:
+ desc = gpiod_get(dev, NULL, flags);
+ desc = gpiod_get_index(dev, NULL, index, flags);
+
+Case 1 assumes that corresponding ACPI device description must have
+defined device properties and will prevent to getting any GPIO resources
+otherwise.
+
+Case 2 explicitly tells GPIO core to look for resources in _CRS.
+
+Be aware that gpiod_get_index() in cases 1 and 2, assuming that there
+are two versions of ACPI device description provided and no mapping is
+present in the driver, will return different resources. That's why a
+certain driver has to handle them carefully as explained in previous
+chapter.
diff --git a/Documentation/acpi/i2c-muxes.txt b/Documentation/acpi/i2c-muxes.txt
new file mode 100644
index 0000000..9fcc4f0
--- /dev/null
+++ b/Documentation/acpi/i2c-muxes.txt
@@ -0,0 +1,58 @@
+ACPI I2C Muxes
+--------------
+
+Describing an I2C device hierarchy that includes I2C muxes requires an ACPI
+Device () scope per mux channel.
+
+Consider this topology:
+
++------+ +------+
+| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
+| | | 0x70 |--CH01--> i2c client B (0x50)
++------+ +------+
+
+which corresponds to the following ASL:
+
+Device (SMB1)
+{
+ Name (_HID, ...)
+ Device (MUX0)
+ {
+ Name (_HID, ...)
+ Name (_CRS, ResourceTemplate () {
+ I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED,
+ AddressingMode7Bit, "^SMB1", 0x00,
+ ResourceConsumer,,)
+ }
+
+ Device (CH00)
+ {
+ Name (_ADR, 0)
+
+ Device (CLIA)
+ {
+ Name (_HID, ...)
+ Name (_CRS, ResourceTemplate () {
+ I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
+ AddressingMode7Bit, "^CH00", 0x00,
+ ResourceConsumer,,)
+ }
+ }
+ }
+
+ Device (CH01)
+ {
+ Name (_ADR, 1)
+
+ Device (CLIB)
+ {
+ Name (_HID, ...)
+ Name (_CRS, ResourceTemplate () {
+ I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
+ AddressingMode7Bit, "^CH01", 0x00,
+ ResourceConsumer,,)
+ }
+ }
+ }
+ }
+}
diff --git a/Documentation/acpi/initrd_table_override.txt b/Documentation/acpi/initrd_table_override.txt
new file mode 100644
index 0000000..eb651a6
--- /dev/null
+++ b/Documentation/acpi/initrd_table_override.txt
@@ -0,0 +1,107 @@
+Upgrading ACPI tables via initrd
+================================
+
+1) Introduction (What is this about)
+2) What is this for
+3) How does it work
+4) References (Where to retrieve userspace tools)
+
+1) What is this about
+---------------------
+
+If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
+upgrade the ACPI execution environment that is defined by the ACPI tables
+via upgrading the ACPI tables provided by the BIOS with an instrumented,
+modified, more recent version one, or installing brand new ACPI tables.
+
+For a full list of ACPI tables that can be upgraded/installed, take a look
+at the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in
+drivers/acpi/tables.c.
+All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
+be overridable, except:
+ - ACPI_SIG_RSDP (has a signature of 6 bytes)
+ - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
+Both could get implemented as well.
+
+
+2) What is this for
+-------------------
+
+Complain to your platform/BIOS vendor if you find a bug which is so severe
+that a workaround is not accepted in the Linux kernel. And this facility
+allows you to upgrade the buggy tables before your platform/BIOS vendor
+releases an upgraded BIOS binary.
+
+This facility can be used by platform/BIOS vendors to provide a Linux
+compatible environment without modifying the underlying platform firmware.
+
+This facility also provides a powerful feature to easily debug and test
+ACPI BIOS table compatibility with the Linux kernel by modifying old
+platform provided ACPI tables or inserting new ACPI tables.
+
+It can and should be enabled in any kernel because there is no functional
+change with not instrumented initrds.
+
+
+3) How does it work
+-------------------
+
+# Extract the machine's ACPI tables:
+cd /tmp
+acpidump >acpidump
+acpixtract -a acpidump
+# Disassemble, modify and recompile them:
+iasl -d *.dat
+# For example add this statement into a _PRT (PCI Routing Table) function
+# of the DSDT:
+Store("HELLO WORLD", debug)
+# And increase the OEM Revision. For example, before modification:
+DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
+# After modification:
+DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
+iasl -sa dsdt.dsl
+# Add the raw ACPI tables to an uncompressed cpio archive.
+# They must be put into a /kernel/firmware/acpi directory inside the cpio
+# archive. Note that if the table put here matches a platform table
+# (similar Table Signature, and similar OEMID, and similar OEM Table ID)
+# with a more recent OEM Revision, the platform table will be upgraded by
+# this table. If the table put here doesn't match a platform table
+# (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
+# ID), this table will be appended.
+mkdir -p kernel/firmware/acpi
+cp dsdt.aml kernel/firmware/acpi
+# A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
+# (see osl.c):
+iasl -sa facp.dsl
+iasl -sa ssdt1.dsl
+cp facp.aml kernel/firmware/acpi
+cp ssdt1.aml kernel/firmware/acpi
+# The uncompressed cpio archive must be the first. Other, typically
+# compressed cpio archives, must be concatenated on top of the uncompressed
+# one. Following command creates the uncompressed cpio archive and
+# concatenates the original initrd on top:
+find kernel | cpio -H newc --create > /boot/instrumented_initrd
+cat /boot/initrd >>/boot/instrumented_initrd
+# reboot with increased acpi debug level, e.g. boot params:
+acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
+# and check your syslog:
+[ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
+[ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
+
+iasl is able to disassemble and recompile quite a lot different,
+also static ACPI tables.
+
+
+4) Where to retrieve userspace tools
+------------------------------------
+
+iasl and acpixtract are part of Intel's ACPICA project:
+http://acpica.org/
+and should be packaged by distributions (for example in the acpica package
+on SUSE).
+
+acpidump can be found in Len Browns pmtools:
+ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
+This tool is also part of the acpica package on SUSE.
+Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
+/sys/firmware/acpi/tables
diff --git a/Documentation/acpi/linuxized-acpica.txt b/Documentation/acpi/linuxized-acpica.txt
new file mode 100644
index 0000000..3ad7b0d
--- /dev/null
+++ b/Documentation/acpi/linuxized-acpica.txt
@@ -0,0 +1,262 @@
+Linuxized ACPICA - Introduction to ACPICA Release Automation
+
+Copyright (C) 2013-2016, Intel Corporation
+Author: Lv Zheng <lv.zheng@intel.com>
+
+
+Abstract:
+
+This document describes the ACPICA project and the relationship between
+ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica,
+include/acpi and tools/power/acpi is automatically updated to follow the
+upstream.
+
+
+1. ACPICA Project
+
+ The ACPI Component Architecture (ACPICA) project provides an operating
+ system (OS)-independent reference implementation of the Advanced
+ Configuration and Power Interface Specification (ACPI). It has been
+ adapted by various host OSes. By directly integrating ACPICA, Linux can
+ also benefit from the application experiences of ACPICA from other host
+ OSes.
+
+ The homepage of ACPICA project is: www.acpica.org, it is maintained and
+ supported by Intel Corporation.
+
+ The following figure depicts the Linux ACPI subsystem where the ACPICA
+ adaptation is included:
+
+ +---------------------------------------------------------+
+ | |
+ | +---------------------------------------------------+ |
+ | | +------------------+ | |
+ | | | Table Management | | |
+ | | +------------------+ | |
+ | | +----------------------+ | |
+ | | | Namespace Management | | |
+ | | +----------------------+ | |
+ | | +------------------+ ACPICA Components | |
+ | | | Event Management | | |
+ | | +------------------+ | |
+ | | +---------------------+ | |
+ | | | Resource Management | | |
+ | | +---------------------+ | |
+ | | +---------------------+ | |
+ | | | Hardware Management | | |
+ | | +---------------------+ | |
+ | +---------------------------------------------------+ | |
+ | | | +------------------+ | | |
+ | | | | OS Service Layer | | | |
+ | | | +------------------+ | | |
+ | | +-------------------------------------------------|-+ |
+ | | +--------------------+ | |
+ | | | Device Enumeration | | |
+ | | +--------------------+ | |
+ | | +------------------+ | |
+ | | | Power Management | | |
+ | | +------------------+ Linux/ACPI Components | |
+ | | +--------------------+ | |
+ | | | Thermal Management | | |
+ | | +--------------------+ | |
+ | | +--------------------------+ | |
+ | | | Drivers for ACPI Devices | | |
+ | | +--------------------------+ | |
+ | | +--------+ | |
+ | | | ...... | | |
+ | | +--------+ | |
+ | +---------------------------------------------------+ |
+ | |
+ +---------------------------------------------------------+
+
+ Figure 1. Linux ACPI Software Components
+
+ NOTE:
+ A. OS Service Layer - Provided by Linux to offer OS dependent
+ implementation of the predefined ACPICA interfaces (acpi_os_*).
+ include/acpi/acpiosxf.h
+ drivers/acpi/osl.c
+ include/acpi/platform
+ include/asm/acenv.h
+ B. ACPICA Functionality - Released from ACPICA code base to offer
+ OS independent implementation of the ACPICA interfaces (acpi_*).
+ drivers/acpi/acpica
+ include/acpi/ac*.h
+ tools/power/acpi
+ C. Linux/ACPI Functionality - Providing Linux specific ACPI
+ functionality to the other Linux kernel subsystems and user space
+ programs.
+ drivers/acpi
+ include/linux/acpi.h
+ include/linux/acpi*.h
+ include/acpi
+ tools/power/acpi
+ D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the
+ ACPI subsystem to offer architecture specific implementation of the
+ ACPI interfaces. They are Linux specific components and are out of
+ the scope of this document.
+ include/asm/acpi.h
+ include/asm/acpi*.h
+ arch/*/acpi
+
+2. ACPICA Release
+
+ The ACPICA project maintains its code base at the following repository URL:
+ https://github.com/acpica/acpica.git. As a rule, a release is made every
+ month.
+
+ As the coding style adopted by the ACPICA project is not acceptable by
+ Linux, there is a release process to convert the ACPICA git commits into
+ Linux patches. The patches generated by this process are referred to as
+ "linuxized ACPICA patches". The release process is carried out on a local
+ copy the ACPICA git repository. Each commit in the monthly release is
+ converted into a linuxized ACPICA patch. Together, they form the monthly
+ ACPICA release patchset for the Linux ACPI community. This process is
+ illustrated in the following figure:
+
+ +-----------------------------+
+ | acpica / master (-) commits |
+ +-----------------------------+
+ /|\ |
+ | \|/
+ | /---------------------\ +----------------------+
+ | < Linuxize repo Utility >-->| old linuxized acpica |--+
+ | \---------------------/ +----------------------+ |
+ | |
+ /---------\ |
+ < git reset > \
+ \---------/ \
+ /|\ /+-+
+ | / |
+ +-----------------------------+ | |
+ | acpica / master (+) commits | | |
+ +-----------------------------+ | |
+ | | |
+ \|/ | |
+ /-----------------------\ +----------------------+ | |
+ < Linuxize repo Utilities >-->| new linuxized acpica |--+ |
+ \-----------------------/ +----------------------+ |
+ \|/
+ +--------------------------+ /----------------------\
+ | Linuxized ACPICA Patches |<----------------< Linuxize patch Utility >
+ +--------------------------+ \----------------------/
+ |
+ \|/
+ /---------------------------\
+ < Linux ACPI Community Review >
+ \---------------------------/
+ |
+ \|/
+ +-----------------------+ /------------------\ +----------------+
+ | linux-pm / linux-next |-->< Linux Merge Window >-->| linux / master |
+ +-----------------------+ \------------------/ +----------------+
+
+ Figure 2. ACPICA -> Linux Upstream Process
+
+ NOTE:
+ A. Linuxize Utilities - Provided by the ACPICA repository, including a
+ utility located in source/tools/acpisrc folder and a number of
+ scripts located in generate/linux folder.
+ B. acpica / master - "master" branch of the git repository at
+ <https://github.com/acpica/acpica.git>.
+ C. linux-pm / linux-next - "linux-next" branch of the git repository at
+ <http://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
+ D. linux / master - "master" branch of the git repository at
+ <http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.
+
+ Before the linuxized ACPICA patches are sent to the Linux ACPI community
+ for review, there is a quality assurance build test process to reduce
+ porting issues. Currently this build process only takes care of the
+ following kernel configuration options:
+ CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
+
+3. ACPICA Divergences
+
+ Ideally, all of the ACPICA commits should be converted into Linux patches
+ automatically without manual modifications, the "linux / master" tree should
+ contain the ACPICA code that exactly corresponds to the ACPICA code
+ contained in "new linuxized acpica" tree and it should be possible to run
+ the release process fully automatically.
+
+ As a matter of fact, however, there are source code differences between
+ the ACPICA code in Linux and the upstream ACPICA code, referred to as
+ "ACPICA Divergences".
+
+ The various sources of ACPICA divergences include:
+ 1. Legacy divergences - Before the current ACPICA release process was
+ established, there already had been divergences between Linux and
+ ACPICA. Over the past several years those divergences have been greatly
+ reduced, but there still are several ones and it takes time to figure
+ out the underlying reasons for their existence.
+ 2. Manual modifications - Any manual modification (eg. coding style fixes)
+ made directly in the Linux sources obviously hurts the ACPICA release
+ automation. Thus it is recommended to fix such issues in the ACPICA
+ upstream source code and generate the linuxized fix using the ACPICA
+ release utilities (please refer to Section 4 below for the details).
+ 3. Linux specific features - Sometimes it's impossible to use the
+ current ACPICA APIs to implement features required by the Linux kernel,
+ so Linux developers occasionally have to change ACPICA code directly.
+ Those changes may not be acceptable by ACPICA upstream and in such cases
+ they are left as committed ACPICA divergences unless the ACPICA side can
+ implement new mechanisms as replacements for them.
+ 4. ACPICA release fixups - ACPICA only tests commits using a set of the
+ user space simulation utilities, thus the linuxized ACPICA patches may
+ break the Linux kernel, leaving us build/boot failures. In order to
+ avoid breaking Linux bisection, fixes are applied directly to the
+ linuxized ACPICA patches during the release process. When the release
+ fixups are backported to the upstream ACPICA sources, they must follow
+ the upstream ACPICA rules and so further modifications may appear.
+ That may result in the appearance of new divergences.
+ 5. Fast tracking of ACPICA commits - Some ACPICA commits are regression
+ fixes or stable-candidate material, so they are applied in advance with
+ respect to the ACPICA release process. If such commits are reverted or
+ rebased on the ACPICA side in order to offer better solutions, new ACPICA
+ divergences are generated.
+
+4. ACPICA Development
+
+ This paragraph guides Linux developers to use the ACPICA upstream release
+ utilities to obtain Linux patches corresponding to upstream ACPICA commits
+ before they become available from the ACPICA release process.
+
+ 1. Cherry-pick an ACPICA commit
+
+ First you need to git clone the ACPICA repository and the ACPICA change
+ you want to cherry pick must be committed into the local repository.
+
+ Then the gen-patch.sh command can help to cherry-pick an ACPICA commit
+ from the ACPICA local repository:
+
+ $ git clone https://github.com/acpica/acpica
+ $ cd acpica
+ $ generate/linux/gen-patch.sh -u [commit ID]
+
+ Here the commit ID is the ACPICA local repository commit ID you want to
+ cherry pick. It can be omitted if the commit is "HEAD".
+
+ 2. Cherry-pick recent ACPICA commits
+
+ Sometimes you need to rebase your code on top of the most recent ACPICA
+ changes that haven't been applied to Linux yet.
+
+ You can generate the ACPICA release series yourself and rebase your code on
+ top of the generated ACPICA release patches:
+
+ $ git clone https://github.com/acpica/acpica
+ $ cd acpica
+ $ generate/linux/make-patches.sh -u [commit ID]
+
+ The commit ID should be the last ACPICA commit accepted by Linux. Usually,
+ it is the commit modifying ACPI_CA_VERSION. It can be found by executing
+ "git blame source/include/acpixf.h" and referencing the line that contains
+ "ACPI_CA_VERSION".
+
+ 3. Inspect the current divergences
+
+ If you have local copies of both Linux and upstream ACPICA, you can generate
+ a diff file indicating the state of the current divergences:
+
+ # git clone https://github.com/acpica/acpica
+ # git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+ # cd acpica
+ # generate/linux/divergences.sh -s ../linux
diff --git a/Documentation/acpi/lpit.txt b/Documentation/acpi/lpit.txt
new file mode 100644
index 0000000..b426398
--- /dev/null
+++ b/Documentation/acpi/lpit.txt
@@ -0,0 +1,25 @@
+To enumerate platform Low Power Idle states, Intel platforms are using
+“Low Power Idle Table” (LPIT). More details about this table can be
+downloaded from:
+http://www.uefi.org/sites/default/files/resources/Intel_ACPI_Low_Power_S0_Idle.pdf
+
+Residencies for each low power state can be read via FFH
+(Function fixed hardware) or a memory mapped interface.
+
+On platforms supporting S0ix sleep states, there can be two types of
+residencies:
+- CPU PKG C10 (Read via FFH interface)
+- Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface)
+
+The following attributes are added dynamically to the cpuidle
+sysfs attribute group:
+ /sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us
+ /sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us
+
+The "low_power_idle_cpu_residency_us" attribute shows time spent
+by the CPU package in PKG C10
+
+The "low_power_idle_system_residency_us" attribute shows SLP_S0
+residency, or system time spent with the SLP_S0# signal asserted.
+This is the lowest possible system power state, achieved only when CPU is in
+PKG C10 and all functional blocks in PCH are in a low power state.
diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt
new file mode 100644
index 0000000..7235da9
--- /dev/null
+++ b/Documentation/acpi/method-customizing.txt
@@ -0,0 +1,73 @@
+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. Methods
+ declared inside scope operators are also not supported.
+Note: The same ACPI control method can be overridden for many times,
+ and it's always the latest one that used by Linux/kernel.
+Note: To get the ACPI debug object output (Store (AAAA, Debug)),
+ please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output".
+
+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)
+ {
+ 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.
+ e) assemble the file to generate the AML code of the method.
+ e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result)
+ If parameter "-vw 6084" is not supported by your iASL compiler,
+ please try a newer version.
+ 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 overridden 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.
+
+Note: Be aware that root can mis-use this driver to modify arbitrary
+ memory and gain additional rights, if root's privileges got
+ restricted (for example if root is not allowed to load additional
+ modules after boot).
diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt
new file mode 100644
index 0000000..0aba14c
--- /dev/null
+++ b/Documentation/acpi/method-tracing.txt
@@ -0,0 +1,192 @@
+ACPICA Trace Facility
+
+Copyright (C) 2015, Intel Corporation
+Author: Lv Zheng <lv.zheng@intel.com>
+
+
+Abstract:
+
+This document describes the functions and the interfaces of the method
+tracing facility.
+
+1. Functionalities and usage examples:
+
+ ACPICA provides method tracing capability. And two functions are
+ currently implemented using this capability.
+
+ A. Log reducer
+ ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
+ enabled. The debugging messages which are deployed via
+ ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
+ level (known as debug layer, configured via
+ /sys/module/acpi/parameters/debug_layer) and per-type level (known as
+ debug level, configured via /sys/module/acpi/parameters/debug_level).
+
+ But when the particular layer/level is applied to the control method
+ evaluations, the quantity of the debugging outputs may still be too
+ large to be put into the kernel log buffer. The idea thus is worked out
+ to only enable the particular debug layer/level (normally more detailed)
+ logs when the control method evaluation is started, and disable the
+ detailed logging when the control method evaluation is stopped.
+
+ The following command examples illustrate the usage of the "log reducer"
+ functionality:
+ a. Filter out the debug layer/level matched logs when control methods
+ are being evaluated:
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "enable" > trace_state
+ b. Filter out the debug layer/level matched logs when the specified
+ control method is being evaluated:
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method" > /sys/module/acpi/parameters/trace_state
+ c. Filter out the debug layer/level matched logs when the specified
+ control method is being evaluated for the first time:
+ # cd /sys/module/acpi/parameters
+ # echo "0xXXXXXXXX" > trace_debug_layer
+ # echo "0xYYYYYYYY" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method-once" > /sys/module/acpi/parameters/trace_state
+ Where:
+ 0xXXXXXXXX/0xYYYYYYYY: Refer to Documentation/acpi/debug.txt for
+ possible debug layer/level masking values.
+ \PPPP.AAAA.TTTT.HHHH: Full path of a control method that can be found
+ in the ACPI namespace. It needn't be an entry
+ of a control method evaluation.
+
+ B. AML tracer
+
+ There are special log entries added by the method tracing facility at
+ the "trace points" the AML interpreter starts/stops to execute a control
+ method, or an AML opcode. Note that the format of the log entries are
+ subject to change:
+ [ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
+ [ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution.
+ [ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution.
+ [ 0.187010] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905a20:-NamePath-] execution.
+ [ 0.187214] exdebug-0398 ex_trace_point : Opcode End [0xf5905a20:-NamePath-] execution.
+ [ 0.187407] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
+ [ 0.187594] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
+ [ 0.187789] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:LEqual] execution.
+ [ 0.187980] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:Return] execution.
+ [ 0.188146] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
+ [ 0.188334] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
+ [ 0.188524] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:Return] execution.
+ [ 0.188712] exdebug-0398 ex_trace_point : Opcode End [0xf5905c88:If] execution.
+ [ 0.188903] exdebug-0398 ex_trace_point : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
+
+ Developers can utilize these special log entries to track the AML
+ interpretion, thus can aid issue debugging and performance tuning. Note
+ that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
+ macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
+ "AML tracer" logs.
+
+ The following command examples illustrate the usage of the "AML tracer"
+ functionality:
+ a. Filter out the method start/stop "AML tracer" logs when control
+ methods are being evaluated:
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "enable" > trace_state
+ b. Filter out the method start/stop "AML tracer" when the specified
+ control method is being evaluated:
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method" > trace_state
+ c. Filter out the method start/stop "AML tracer" logs when the specified
+ control method is being evaluated for the first time:
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "method-once" > trace_state
+ d. Filter out the method/opcode start/stop "AML tracer" when the
+ specified control method is being evaluated:
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "opcode" > trace_state
+ e. Filter out the method/opcode start/stop "AML tracer" when the
+ specified control method is being evaluated for the first time:
+ # cd /sys/module/acpi/parameters
+ # echo "0x80" > trace_debug_layer
+ # echo "0x10" > trace_debug_level
+ # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
+ # echo "opcode-opcode" > trace_state
+
+ Note that all above method tracing facility related module parameters can
+ be used as the boot parameters, for example:
+ acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
+ acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
+
+2. Interface descriptions:
+
+ All method tracing functions can be configured via ACPI module
+ parameters that are accessible at /sys/module/acpi/parameters/:
+
+ trace_method_name
+ The full path of the AML method that the user wants to trace.
+ Note that the full path shouldn't contain the trailing "_"s in its
+ name segments but may contain "\" to form an absolute path.
+
+ trace_debug_layer
+ The temporary debug_layer used when the tracing feature is enabled.
+ Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
+ used to match all "AML tracer" logs.
+
+ trace_debug_level
+ The temporary debug_level used when the tracing feature is enabled.
+ Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
+ debug_level used to match all "AML tracer" logs.
+
+ trace_state
+ The status of the tracing feature.
+ Users can enable/disable this debug tracing feature by executing
+ the following command:
+ # echo string > /sys/module/acpi/parameters/trace_state
+ Where "string" should be one of the following:
+ "disable"
+ Disable the method tracing feature.
+ "enable"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during any method
+ execution will be logged.
+ "method"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during method execution
+ of "trace_method_name" will be logged.
+ "method-once"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during method execution
+ of "trace_method_name" will be logged only once.
+ "opcode"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during method/opcode
+ execution of "trace_method_name" will be logged.
+ "opcode-once"
+ Enable the method tracing feature.
+ ACPICA debugging messages matching
+ "trace_debug_layer/trace_debug_level" during method/opcode
+ execution of "trace_method_name" will be logged only once.
+ Note that, the difference between the "enable" and other feature
+ enabling options are:
+ 1. When "enable" is specified, since
+ "trace_debug_layer/trace_debug_level" shall apply to all control
+ method evaluations, after configuring "trace_state" to "enable",
+ "trace_method_name" will be reset to NULL.
+ 2. When "method/opcode" is specified, if
+ "trace_method_name" is NULL when "trace_state" is configured to
+ these options, the "trace_debug_layer/trace_debug_level" will
+ apply to all control method evaluations.
diff --git a/Documentation/acpi/namespace.txt b/Documentation/acpi/namespace.txt
new file mode 100644
index 0000000..1860cb3
--- /dev/null
+++ b/Documentation/acpi/namespace.txt
@@ -0,0 +1,388 @@
+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.
+ 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.
diff --git a/Documentation/acpi/osi.txt b/Documentation/acpi/osi.txt
new file mode 100644
index 0000000..50cde0c
--- /dev/null
+++ b/Documentation/acpi/osi.txt
@@ -0,0 +1,187 @@
+ACPI _OSI and _REV methods
+--------------------------
+
+An ACPI BIOS can use the "Operating System Interfaces" method (_OSI)
+to find out what the operating system supports. Eg. If BIOS
+AML code includes _OSI("XYZ"), the kernel's AML interpreter
+can evaluate that method, look to see if it supports 'XYZ'
+and answer YES or NO to the BIOS.
+
+The ACPI _REV method returns the "Revision of the ACPI specification
+that OSPM supports"
+
+This document explains how and why the BIOS and Linux should use these methods.
+It also explains how and why they are widely misused.
+
+How to use _OSI
+---------------
+
+Linux runs on two groups of machines -- those that are tested by the OEM
+to be compatible with Linux, and those that were never tested with Linux,
+but where Linux was installed to replace the original OS (Windows or OSX).
+
+The larger group is the systems tested to run only Windows. Not only that,
+but many were tested to run with just one specific version of Windows.
+So even though the BIOS may use _OSI to query what version of Windows is running,
+only a single path through the BIOS has actually been tested.
+Experience shows that taking untested paths through the BIOS
+exposes Linux to an entire category of BIOS bugs.
+For this reason, Linux _OSI defaults must continue to claim compatibility
+with all versions of Windows.
+
+But Linux isn't actually compatible with Windows, and the Linux community
+has also been hurt with regressions when Linux adds the latest version of
+Windows to its list of _OSI strings. So it is possible that additional strings
+will be more thoroughly vetted before shipping upstream in the future.
+But it is likely that they will all eventually be added.
+
+What should an OEM do if they want to support Linux and Windows
+using the same BIOS image? Often they need to do something different
+for Linux to deal with how Linux is different from Windows.
+Here the BIOS should ask exactly what it wants to know:
+
+_OSI("Linux-OEM-my_interface_name")
+where 'OEM' is needed if this is an OEM-specific hook,
+and 'my_interface_name' describes the hook, which could be a
+quirk, a bug, or a bug-fix.
+
+In addition, the OEM should send a patch to upstream Linux
+via the linux-acpi@vger.kernel.org mailing list. When that patch
+is checked into Linux, the OS will answer "YES" when the BIOS
+on the OEM's system uses _OSI to ask if the interface is supported
+by the OS. Linux distributors can back-port that patch for Linux
+pre-installs, and it will be included by all distributions that
+re-base to upstream. If the distribution can not update the kernel binary,
+they can also add an acpi_osi=Linux-OEM-my_interface_name
+cmdline parameter to the boot loader, as needed.
+
+If the string refers to a feature where the upstream kernel
+eventually grows support, a patch should be sent to remove
+the string when that support is added to the kernel.
+
+That was easy. Read on, to find out how to do it wrong.
+
+Before _OSI, there was _OS
+--------------------------
+
+ACPI 1.0 specified "_OS" as an
+"object that evaluates to a string that identifies the operating system."
+
+The ACPI BIOS flow would include an evaluation of _OS, and the AML
+interpreter in the kernel would return to it a string identifying the OS:
+
+Windows 98, SE: "Microsoft Windows"
+Windows ME: "Microsoft WindowsME:Millenium Edition"
+Windows NT: "Microsoft Windows NT"
+
+The idea was on a platform tasked with running multiple OS's,
+the BIOS could use _OS to enable devices that an OS
+might support, or enable quirks or bug workarounds
+necessary to make the platform compatible with that pre-existing OS.
+
+But _OS had fundamental problems. First, the BIOS needed to know the name
+of every possible version of the OS that would run on it, and needed to know
+all the quirks of those OS's. Certainly it would make more sense
+for the BIOS to ask *specific* things of the OS, such
+"do you support a specific interface", and thus in ACPI 3.0,
+_OSI was born to replace _OS.
+
+_OS was abandoned, though even today, many BIOS look for
+_OS "Microsoft Windows NT", though it seems somewhat far-fetched
+that anybody would install those old operating systems
+over what came with the machine.
+
+Linux answers "Microsoft Windows NT" to please that BIOS idiom.
+That is the *only* viable strategy, as that is what modern Windows does,
+and so doing otherwise could steer the BIOS down an untested path.
+
+_OSI is born, and immediately misused
+--------------------------------------
+
+With _OSI, the *BIOS* provides the string describing an interface,
+and asks the OS: "YES/NO, are you compatible with this interface?"
+
+eg. _OSI("3.0 Thermal Model") would return TRUE if the OS knows how
+to deal with the thermal extensions made to the ACPI 3.0 specification.
+An old OS that doesn't know about those extensions would answer FALSE,
+and a new OS may be able to return TRUE.
+
+For an OS-specific interface, the ACPI spec said that the BIOS and the OS
+were to agree on a string of the form such as "Windows-interface_name".
+
+But two bad things happened. First, the Windows ecosystem used _OSI
+not as designed, but as a direct replacement for _OS -- identifying
+the OS version, rather than an OS supported interface. Indeed, right
+from the start, the ACPI 3.0 spec itself codified this misuse
+in example code using _OSI("Windows 2001").
+
+This misuse was adopted and continues today.
+
+Linux had no choice but to also return TRUE to _OSI("Windows 2001")
+and its successors. To do otherwise would virtually guarantee breaking
+a BIOS that has been tested only with that _OSI returning TRUE.
+
+This strategy is problematic, as Linux is never completely compatible with
+the latest version of Windows, and sometimes it takes more than a year
+to iron out incompatibilities.
+
+Not to be out-done, the Linux community made things worse by returning TRUE
+to _OSI("Linux"). Doing so is even worse than the Windows misuse
+of _OSI, as "Linux" does not even contain any version information.
+_OSI("Linux") led to some BIOS' malfunctioning due to BIOS writer's
+using it in untested BIOS flows. But some OEM's used _OSI("Linux")
+in tested flows to support real Linux features. In 2009, Linux
+removed _OSI("Linux"), and added a cmdline parameter to restore it
+for legacy systems still needed it. Further a BIOS_BUG warning prints
+for all BIOS's that invoke it.
+
+No BIOS should use _OSI("Linux").
+
+The result is a strategy for Linux to maximize compatibility with
+ACPI BIOS that are tested on Windows machines. There is a real risk
+of over-stating that compatibility; but the alternative has often been
+catastrophic failure resulting from the BIOS taking paths that
+were never validated under *any* OS.
+
+Do not use _REV
+---------------
+
+Since _OSI("Linux") went away, some BIOS writers used _REV
+to support Linux and Windows differences in the same BIOS.
+
+_REV was defined in ACPI 1.0 to return the version of ACPI
+supported by the OS and the OS AML interpreter.
+
+Modern Windows returns _REV = 2. Linux used ACPI_CA_SUPPORT_LEVEL,
+which would increment, based on the version of the spec supported.
+
+Unfortunately, _REV was also misused. eg. some BIOS would check
+for _REV = 3, and do something for Linux, but when Linux returned
+_REV = 4, that support broke.
+
+In response to this problem, Linux returns _REV = 2 always,
+from mid-2015 onward. The ACPI specification will also be updated
+to reflect that _REV is deprecated, and always returns 2.
+
+Apple Mac and _OSI("Darwin")
+----------------------------
+
+On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin")
+to determine if the machine is running Apple OSX.
+
+Like Linux's _OSI("*Windows*") strategy, Linux defaults to
+answering YES to _OSI("Darwin") to enable full access
+to the hardware and validated BIOS paths seen by OSX.
+Just like on Windows-tested platforms, this strategy has risks.
+
+Starting in Linux-3.18, the kernel answered YES to _OSI("Darwin")
+for the purpose of enabling Mac Thunderbolt support. Further,
+if the kernel noticed _OSI("Darwin") being invoked, it additionally
+disabled all _OSI("*Windows*") to keep poorly written Mac BIOS
+from going down untested combinations of paths.
+
+The Linux-3.18 change in default caused power regressions on Mac
+laptops, and the 3.18 implementation did not allow changing
+the default via cmdline "acpi_osi=!Darwin". Linux-4.7 fixed
+the ability to use acpi_osi=!Darwin as a workaround, and
+we hope to see Mac Thunderbolt power management support in Linux-4.11.
diff --git a/Documentation/acpi/scan_handlers.txt b/Documentation/acpi/scan_handlers.txt
new file mode 100644
index 0000000..3246ccf
--- /dev/null
+++ b/Documentation/acpi/scan_handlers.txt
@@ -0,0 +1,77 @@
+ACPI Scan Handlers
+
+Copyright (C) 2012, Intel Corporation
+Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+
+During system initialization and ACPI-based device hot-add, the ACPI namespace
+is scanned in search of device objects that generally represent various pieces
+of hardware. This causes a struct acpi_device object to be created and
+registered with the driver core for every device object in the ACPI namespace
+and the hierarchy of those struct acpi_device objects reflects the namespace
+layout (i.e. parent device objects in the namespace are represented by parent
+struct acpi_device objects and analogously for their children). Those struct
+acpi_device objects are referred to as "device nodes" in what follows, but they
+should not be confused with struct device_node objects used by the Device Trees
+parsing code (although their role is analogous to the role of those objects).
+
+During ACPI-based device hot-remove device nodes representing pieces of hardware
+being removed are unregistered and deleted.
+
+The core ACPI namespace scanning code in drivers/acpi/scan.c carries out basic
+initialization of device nodes, such as retrieving common configuration
+information from the device objects represented by them and populating them with
+appropriate data, but some of them require additional handling after they have
+been registered. For example, if the given device node represents a PCI host
+bridge, its registration should cause the PCI bus under that bridge to be
+enumerated and PCI devices on that bus to be registered with the driver core.
+Similarly, if the device node represents a PCI interrupt link, it is necessary
+to configure that link so that the kernel can use it.
+
+Those additional configuration tasks usually depend on the type of the hardware
+component represented by the given device node which can be determined on the
+basis of the device node's hardware ID (HID). They are performed by objects
+called ACPI scan handlers represented by the following structure:
+
+struct acpi_scan_handler {
+ const struct acpi_device_id *ids;
+ struct list_head list_node;
+ int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
+ void (*detach)(struct acpi_device *dev);
+};
+
+where ids is the list of IDs of device nodes the given handler is supposed to
+take care of, list_node is the hook to the global list of ACPI scan handlers
+maintained by the ACPI core and the .attach() and .detach() callbacks are
+executed, respectively, after registration of new device nodes and before
+unregistration of device nodes the handler attached to previously.
+
+The namespace scanning function, acpi_bus_scan(), first registers all of the
+device nodes in the given namespace scope with the driver core. Then, it tries
+to match a scan handler against each of them using the ids arrays of the
+available scan handlers. If a matching scan handler is found, its .attach()
+callback is executed for the given device node. If that callback returns 1,
+that means that the handler has claimed the device node and is now responsible
+for carrying out any additional configuration tasks related to it. It also will
+be responsible for preparing the device node for unregistration in that case.
+The device node's handler field is then populated with the address of the scan
+handler that has claimed it.
+
+If the .attach() callback returns 0, it means that the device node is not
+interesting to the given scan handler and may be matched against the next scan
+handler in the list. If it returns a (negative) error code, that means that
+the namespace scan should be terminated due to a serious error. The error code
+returned should then reflect the type of the error.
+
+The namespace trimming function, acpi_bus_trim(), first executes .detach()
+callbacks from the scan handlers of all device nodes in the given namespace
+scope (if they have scan handlers). Next, it unregisters all of the device
+nodes in that scope.
+
+ACPI scan handlers can be added to the list maintained by the ACPI core with the
+help of the acpi_scan_add_handler() function taking a pointer to the new scan
+handler as an argument. The order in which scan handlers are added to the list
+is the order in which they are matched against device nodes during namespace
+scans.
+
+All scan handles must be added to the list before acpi_bus_scan() is run for the
+first time and they cannot be removed from it.
diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt
new file mode 100644
index 0000000..5ae13f1
--- /dev/null
+++ b/Documentation/acpi/ssdt-overlays.txt
@@ -0,0 +1,172 @@
+
+In order to support ACPI open-ended hardware configurations (e.g. development
+boards) we need a way to augment the ACPI configuration provided by the firmware
+image. A common example is connecting sensors on I2C / SPI buses on development
+boards.
+
+Although this can be accomplished by creating a kernel platform driver or
+recompiling the firmware image with updated ACPI tables, neither is practical:
+the former proliferates board specific kernel code while the latter requires
+access to firmware tools which are often not publicly available.
+
+Because ACPI supports external references in AML code a more practical
+way to augment firmware ACPI configuration is by dynamically loading
+user defined SSDT tables that contain the board specific information.
+
+For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
+Minnowboard MAX development board exposed via the LSE connector [1], the
+following ASL code can be used:
+
+DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
+{
+ External (\_SB.I2C6, DeviceObj)
+
+ Scope (\_SB.I2C6)
+ {
+ Device (STAC)
+ {
+ Name (_ADR, Zero)
+ Name (_HID, "BMA222E")
+
+ Method (_CRS, 0, Serialized)
+ {
+ Name (RBUF, ResourceTemplate ()
+ {
+ I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
+ AddressingMode7Bit, "\\_SB.I2C6", 0x00,
+ ResourceConsumer, ,)
+ GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
+ "\\_SB.GPO2", 0x00, ResourceConsumer, , )
+ { // Pin list
+ 0
+ }
+ })
+ Return (RBUF)
+ }
+ }
+ }
+}
+
+which can then be compiled to AML binary format:
+
+$ iasl minnowmax.asl
+
+Intel ACPI Component Architecture
+ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
+Copyright (c) 2000 - 2014 Intel Corporation
+
+ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
+AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
+
+[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
+
+The resulting AML code can then be loaded by the kernel using one of the methods
+below.
+
+== Loading ACPI SSDTs from initrd ==
+
+This option allows loading of user defined SSDTs from initrd and it is useful
+when the system does not support EFI or when there is not enough EFI storage.
+
+It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
+aml code must be placed in the first, uncompressed, initrd under the
+"kernel/firmware/acpi" path. Multiple files can be used and this will translate
+in loading multiple tables. Only SSDT and OEM tables are allowed. See
+initrd_table_override.txt for more details.
+
+Here is an example:
+
+# Add the raw ACPI tables to an uncompressed cpio archive.
+# They must be put into a /kernel/firmware/acpi directory inside the
+# cpio archive.
+# The uncompressed cpio archive must be the first.
+# Other, typically compressed cpio archives, must be
+# concatenated on top of the uncompressed one.
+mkdir -p kernel/firmware/acpi
+cp ssdt.aml kernel/firmware/acpi
+
+# Create the uncompressed cpio archive and concatenate the original initrd
+# on top:
+find kernel | cpio -H newc --create > /boot/instrumented_initrd
+cat /boot/initrd >>/boot/instrumented_initrd
+
+== Loading ACPI SSDTs from EFI variables ==
+
+This is the preferred method, when EFI is supported on the platform, because it
+allows a persistent, OS independent way of storing the user defined SSDTs. There
+is also work underway to implement EFI support for loading user defined SSDTs
+and using this method will make it easier to convert to the EFI loading
+mechanism when that will arrive.
+
+In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
+parameter can be used. The argument for the option is the variable name to
+use. If there are multiple variables with the same name but with different
+vendor GUIDs, all of them will be loaded.
+
+In order to store the AML code in an EFI variable the efivarfs filesystem can be
+used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
+recent distribution.
+
+Creating a new file in /sys/firmware/efi/efivars will automatically create a new
+EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
+variable. Please note that the file name needs to be specially formatted as
+"Name-GUID" and that the first 4 bytes in the file (little-endian format)
+represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
+include/linux/efi.h). Writing to the file must also be done with one write
+operation.
+
+For example, you can use the following bash script to create/update an EFI
+variable with the content from a given file:
+
+#!/bin/sh -e
+
+while ! [ -z "$1" ]; do
+ case "$1" in
+ "-f") filename="$2"; shift;;
+ "-g") guid="$2"; shift;;
+ *) name="$1";;
+ esac
+ shift
+done
+
+usage()
+{
+ echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
+ exit 1
+}
+
+[ -n "$name" -a -f "$filename" ] || usage
+
+EFIVARFS="/sys/firmware/efi/efivars"
+
+[ -d "$EFIVARFS" ] || exit 2
+
+if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
+ mount -t efivarfs none $EFIVARFS
+fi
+
+# try to pick up an existing GUID
+[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
+
+# use a randomly generated GUID
+[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
+
+# efivarfs expects all of the data in one write
+tmp=$(mktemp)
+/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
+dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
+rm $tmp
+
+== Loading ACPI SSDTs from configfs ==
+
+This option allows loading of user defined SSDTs from userspace via the configfs
+interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
+mounted. In the following examples, we assume that configfs has been mounted in
+/config.
+
+New tables can be loading by creating new directories in /config/acpi/table/ and
+writing the SSDT aml code in the aml attribute:
+
+cd /config/acpi/table
+mkdir my_ssdt
+cat ~/ssdt.aml > my_ssdt/aml
diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt
new file mode 100644
index 0000000..79bf6a4
--- /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 admin-guide/kernel-parameters.rst. It is recommended to
+disable this behaviour once a GUI environment starts up and wants to have full
+control of the backlight level.