diff options
Diffstat (limited to 'Documentation/acpi')
24 files changed, 99 insertions, 3370 deletions
diff --git a/Documentation/acpi/DSD-properties-rules.txt b/Documentation/acpi/DSD-properties-rules.txt deleted file mode 100644 index 3e4862bdad98..000000000000 --- a/Documentation/acpi/DSD-properties-rules.txt +++ /dev/null @@ -1,97 +0,0 @@ -_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 deleted file mode 100644 index effe7af3a5af..000000000000 --- a/Documentation/acpi/acpi-lid.txt +++ /dev/null @@ -1,96 +0,0 @@ -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 deleted file mode 100644 index 75ebeb64ab29..000000000000 --- a/Documentation/acpi/aml-debugger.txt +++ /dev/null @@ -1,66 +0,0 @@ -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/power/acpi/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/power/acpi/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 deleted file mode 100644 index e550c8b98139..000000000000 --- a/Documentation/acpi/apei/einj.txt +++ /dev/null @@ -1,177 +0,0 @@ - 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 deleted file mode 100644 index 0c49c197c47a..000000000000 --- a/Documentation/acpi/apei/output_format.txt +++ /dev/null @@ -1,147 +0,0 @@ - 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 deleted file mode 100644 index f20fb445135d..000000000000 --- a/Documentation/acpi/cppc_sysfs.txt +++ /dev/null @@ -1,69 +0,0 @@ - - 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 deleted file mode 100644 index 65bf47c46b6d..000000000000 --- a/Documentation/acpi/debug.txt +++ /dev/null @@ -1,148 +0,0 @@ - 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 deleted file mode 100644 index c3871565c8cf..000000000000 --- a/Documentation/acpi/dsd/data-node-references.txt +++ /dev/null @@ -1,89 +0,0 @@ -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 deleted file mode 100644 index b9ce910781dc..000000000000 --- a/Documentation/acpi/dsd/graph.txt +++ /dev/null @@ -1,174 +0,0 @@ -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/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt new file mode 100644 index 000000000000..81a63af42ed2 --- /dev/null +++ b/Documentation/acpi/dsd/leds.txt @@ -0,0 +1,99 @@ +Describing and referring to LEDs in ACPI + +Individual LEDs are described by hierarchical data extension [6] nodes under the +device node, the LED driver chip. The "reg" property in the LED specific nodes +tells the numerical ID of each individual LED output to which the LEDs are +connected. [3] The hierarchical data nodes are named "led@X", where X is the +number of the LED output. + +Referring to LEDs in Device tree is documented in [4], in "flash-leds" property +documentation. In short, LEDs are directly referred to by using phandles. + +While Device tree allows referring to any node in the tree[1], in ACPI +references are limited to device nodes only [2]. For this reason using the same +mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes +is documented in [7]. + +ACPI allows (as does DT) using integer arguments after the reference. A +combination of the LED driver device reference and an integer argument, +referring to the "reg" property of the relevant LED, is used to identify +individual LEDs. The value of the "reg" property is a contract between the +firmware and software, it uniquely identifies the LED driver outputs. + +Under the LED driver device, The first hierarchical data extension package list +entry shall contain the string "led@" followed by the number of the LED, +followed by the referred object name. That object shall be named "LED" followed +by the number of the LED. + +An ASL example of a camera sensor device and a LED driver device for two LEDs. +Objects not relevant for LEDs or the references to them have been omitted. + + Device (LED) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "led@0", LED0 }, + Package () { "led@1", LED1 }, + } + }) + Name (LED0, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "flash-max-microamp", 1000000 }, + Package () { "flash-timeout-us", 200000 }, + Package () { "led-max-microamp", 100000 }, + Package () { "label", "white:flash" }, + } + }) + Name (LED1, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 1 }, + Package () { "led-max-microamp", 10000 }, + Package () { "label", "red:indicator" }, + } + }) + } + + Device (SEN) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { + "flash-leds", + Package () { ^LED, "led@0", ^LED, "led@1" }, + } + } + }) + } + +where + + LED LED driver device + LED0 First LED + LED1 Second LED + SEN Camera sensor device (or another device the LED is + related to) + +[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21. + +[2] Advanced Configuration and Power Interface Specification. + <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>, + referenced 2019-02-21. + +[3] Documentation/devicetree/bindings/leds/common.txt + +[4] Documentation/devicetree/bindings/media/video-interfaces.txt + +[5] Device Properties UUID For _DSD. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, + referenced 2019-02-21. + +[6] Hierarchical Data Extension UUID For _DSD. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, + referenced 2019-02-21. + +[7] Documentation/acpi/dsd/data-node-reference.txt diff --git a/Documentation/acpi/dsdt-override.txt b/Documentation/acpi/dsdt-override.txt deleted file mode 100644 index 784841caa6e6..000000000000 --- a/Documentation/acpi/dsdt-override.txt +++ /dev/null @@ -1,7 +0,0 @@ -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 deleted file mode 100644 index 7bcf9c3d9fbe..000000000000 --- a/Documentation/acpi/enumeration.txt +++ /dev/null @@ -1,426 +0,0 @@ -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 deleted file mode 100644 index 88c65cb5bf0a..000000000000 --- a/Documentation/acpi/gpio-properties.txt +++ /dev/null @@ -1,223 +0,0 @@ -_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 deleted file mode 100644 index 9fcc4f0b885e..000000000000 --- a/Documentation/acpi/i2c-muxes.txt +++ /dev/null @@ -1,58 +0,0 @@ -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 deleted file mode 100644 index 30437a6db373..000000000000 --- a/Documentation/acpi/initrd_table_override.txt +++ /dev/null @@ -1,111 +0,0 @@ -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. - -When building initrd with kernel in a single image, option -ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this -feature to work. - -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 deleted file mode 100644 index 3ad7b0dfb083..000000000000 --- a/Documentation/acpi/linuxized-acpica.txt +++ /dev/null @@ -1,262 +0,0 @@ -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 deleted file mode 100644 index b426398d2e97..000000000000 --- a/Documentation/acpi/lpit.txt +++ /dev/null @@ -1,25 +0,0 @@ -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 deleted file mode 100644 index 7235da975f23..000000000000 --- a/Documentation/acpi/method-customizing.txt +++ /dev/null @@ -1,73 +0,0 @@ -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 deleted file mode 100644 index 0aba14c8f459..000000000000 --- a/Documentation/acpi/method-tracing.txt +++ /dev/null @@ -1,192 +0,0 @@ -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 deleted file mode 100644 index 1860cb3865c6..000000000000 --- a/Documentation/acpi/namespace.txt +++ /dev/null @@ -1,388 +0,0 @@ -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 deleted file mode 100644 index 50cde0ceb9b0..000000000000 --- a/Documentation/acpi/osi.txt +++ /dev/null @@ -1,187 +0,0 @@ -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 deleted file mode 100644 index 3246ccf15992..000000000000 --- a/Documentation/acpi/scan_handlers.txt +++ /dev/null @@ -1,77 +0,0 @@ -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 deleted file mode 100644 index 5ae13f161ea2..000000000000 --- a/Documentation/acpi/ssdt-overlays.txt +++ /dev/null @@ -1,172 +0,0 @@ - -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 deleted file mode 100644 index 79bf6a4921be..000000000000 --- a/Documentation/acpi/video_extension.txt +++ /dev/null @@ -1,106 +0,0 @@ -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. |