From a3e2acc5e37b22b6808a0b8e46887c3577de9c9e Mon Sep 17 00:00:00 2001 From: Huang Ying Date: Wed, 29 Jun 2016 13:04:29 -0700 Subject: ACPI / APEI: Add Boot Error Record Table (BERT) support ACPI/APEI is designed to verifiy/report H/W errors, like Corrected Error(CE) and Uncorrected Error(UC). It contains four tables: HEST, ERST, EINJ and BERT. The first three tables have been merged for a long time, but because of lacking BIOS support for BERT, the support for BERT is pending until now. Recently on ARM 64 platform it is has been supported. So here we come. Under normal circumstances, when a hardware error occurs, kernel will be notified via NMI, MCE or some other method, then kernel will process the error condition, report it, and recover it if possible. But sometime, the situation is so bad, so that firmware may choose to reset directly without notifying Linux kernel. Linux kernel can use the Boot Error Record Table (BERT) to get the un-notified hardware errors that occurred in a previous boot. In this patch, the error information is reported via printk. For more information about BERT, please refer to ACPI Specification version 6.0, section 18.3.1: http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf The following log is a BERT record after system reboot because of hitting a fatal memory error: BERT: Error records from previous boot: [Hardware Error]: It has been corrected by h/w and requires no further action [Hardware Error]: event severity: corrected [Hardware Error]: Error 0, type: recoverable [Hardware Error]: section_type: memory error [Hardware Error]: error_status: 0x0000000000000400 [Hardware Error]: physical_address: 0xffffffffffffffff [Hardware Error]: card: 1 module: 2 bank: 3 row: 1 column: 2 bit_position: 5 [Hardware Error]: error_type: 2, single-bit ECC [Tomasz Nowicki: Clear error status at the end of error handling] [Tony: Applied some cleanups suggested by Fu Wei] [Fu Wei: delete EXPORT_SYMBOL_GPL(bert_disable), improve the code] Signed-off-by: Huang Ying Signed-off-by: Tomasz Nowicki Signed-off-by: Chen, Gong Tested-by: Jonathan (Zhixiong) Zhang Signed-off-by: Fu Wei Tested-by: Tyler Baicar Reviewed-by: Borislav Petkov Signed-off-by: Tony Luck Signed-off-by: Rafael J. Wysocki --- Documentation/kernel-parameters.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 82b42c958d1c..f565259167d7 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -582,6 +582,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. bootmem_debug [KNL] Enable bootmem allocator debug messages. + bert_disable [ACPI] + Disable BERT OS support on buggy BIOSes. + bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards) bttv.radio= Most important insmod options are available as kernel args too. -- cgit v1.2.3 From 14d24c39e7f4de1bd3aa3a0379ad3c0d8129a155 Mon Sep 17 00:00:00 2001 From: Octavian Purdila Date: Fri, 8 Jul 2016 19:13:07 +0300 Subject: ACPI / documentation: add SSDT overlays documentation Signed-off-by: Octavian Purdila Reviewed-by: Mika Westerberg Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/ssdt-overlays.txt | 91 ++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 Documentation/acpi/ssdt-overlays.txt (limited to 'Documentation') diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt new file mode 100644 index 000000000000..805025940248 --- /dev/null +++ b/Documentation/acpi/ssdt-overlays.txt @@ -0,0 +1,91 @@ + +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 -- cgit v1.2.3 From 475fb4e8b2f4444d1d7b406ff3a7d21bc89a1e6f Mon Sep 17 00:00:00 2001 From: Octavian Purdila Date: Fri, 8 Jul 2016 19:13:12 +0300 Subject: efi / ACPI: load SSTDs from EFI variables This patch allows SSDTs to be loaded from EFI variables. It works by specifying the EFI variable name containing the SSDT to be loaded. All variables with the same name (regardless of the vendor GUID) will be loaded. Note that we can't use acpi_install_table and we must rely on the dynamic ACPI table loading and bus re-scanning mechanisms. That is because I2C/SPI controllers are initialized earlier then the EFI subsystems and all I2C/SPI ACPI devices are enumerated when the I2C/SPI controllers are initialized. Signed-off-by: Octavian Purdila Reviewed-by: Matt Fleming Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/ssdt-overlays.txt | 67 ++++++++++++++++++++++++++++++++++++ Documentation/kernel-parameters.txt | 7 ++++ 2 files changed, 74 insertions(+) (limited to 'Documentation') diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt index 805025940248..c4b57badd0b7 100644 --- a/Documentation/acpi/ssdt-overlays.txt +++ b/Documentation/acpi/ssdt-overlays.txt @@ -89,3 +89,70 @@ cp ssdt.aml kernel/firmware/acpi # 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 diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 82b42c958d1c..bbfb56fe7b92 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1185,6 +1185,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Address Range Mirroring feature even if your box doesn't support it. + efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT + that is to be dynamically loaded by Linux. If there are + multiple variables with the same name but with different + vendor GUIDs, all of them will be loaded. See + Documentation/acpi/ssdt-overlays.txt for details. + + eisa_irq_edge= [PARISC,HW] See header of drivers/parisc/eisa.c. -- cgit v1.2.3 From 0bf54fcd95042bd178cb25368422cf4474fc8492 Mon Sep 17 00:00:00 2001 From: Octavian Purdila Date: Fri, 8 Jul 2016 19:13:13 +0300 Subject: ACPI: add support for configfs Register the ACPI subsystem with configfs. Signed-off-by: Octavian Purdila Reviewed-by: Mika Westerberg Signed-off-by: Rafael J. Wysocki --- Documentation/ABI/testing/configfs-acpi | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 Documentation/ABI/testing/configfs-acpi (limited to 'Documentation') diff --git a/Documentation/ABI/testing/configfs-acpi b/Documentation/ABI/testing/configfs-acpi new file mode 100644 index 000000000000..17b19dc2822d --- /dev/null +++ b/Documentation/ABI/testing/configfs-acpi @@ -0,0 +1,7 @@ +What: /config/acpi +Date: July 2016 +KernelVersion: 4.8 +Contact: linux-acpi@vger.kernel.org +Description: + This represents the ACPI subsystem entry point directory. It + contains sub-groups corresponding to ACPI configurable options. -- cgit v1.2.3 From 612bd01fc6e04c3ce9eb59587b4a7e4ebd6aff35 Mon Sep 17 00:00:00 2001 From: Octavian Purdila Date: Fri, 8 Jul 2016 19:13:14 +0300 Subject: ACPI: add support for loading SSDTs via configfs New tables can be loaded by creating directories under /config/table/ and writing the AML code into the aml table attribute. Various table attributes will be readable once the table is successfully loaded. Unloading tables is not supported at the moment, but it can be easily implemented once ACPI loading functions provide a table handle to be used for unloading. Signed-off-by: Octavian Purdila Reviewed-by: Mika Westerberg Signed-off-by: Rafael J. Wysocki --- Documentation/ABI/testing/configfs-acpi | 29 +++++++++++++++++++++++++++++ Documentation/acpi/ssdt-overlays.txt | 14 ++++++++++++++ 2 files changed, 43 insertions(+) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/configfs-acpi b/Documentation/ABI/testing/configfs-acpi index 17b19dc2822d..4ab4e99aa863 100644 --- a/Documentation/ABI/testing/configfs-acpi +++ b/Documentation/ABI/testing/configfs-acpi @@ -5,3 +5,32 @@ Contact: linux-acpi@vger.kernel.org Description: This represents the ACPI subsystem entry point directory. It contains sub-groups corresponding to ACPI configurable options. + +What: /config/acpi/table +Date: July 2016 +KernelVersion: 4.8 +Description: + + This group contains the configuration for user defined ACPI + tables. The attributes of a user define table are: + + aml - a binary attribute that the user can use to + fill in the ACPI aml definitions. Once the aml + data is written to this file and the file is + closed the table will be loaded and ACPI devices + will be enumerated. To check if the operation is + successful the user must check the error code + for close(). If the operation is successful, + subsequent writes to this attribute will fail. + + The rest of the attributes are read-only and are valid only + after the table has been loaded by filling the aml entry: + + signature - ASCII table signature + length - length of table in bytes, including the header + revision - ACPI Specification minor version number + oem_id - ASCII OEM identification + oem_table_id - ASCII OEM table identification + oem_revision - OEM revision number + asl_compiler_id - ASCII ASL compiler vendor ID + asl_compiler_revision - ASL compiler version diff --git a/Documentation/acpi/ssdt-overlays.txt b/Documentation/acpi/ssdt-overlays.txt index c4b57badd0b7..5ae13f161ea2 100644 --- a/Documentation/acpi/ssdt-overlays.txt +++ b/Documentation/acpi/ssdt-overlays.txt @@ -156,3 +156,17 @@ 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 -- cgit v1.2.3 From 9305aa6fe9069970e5cb8428ca4817b4aeaee271 Mon Sep 17 00:00:00 2001 From: Lv Zheng Date: Thu, 7 Jul 2016 15:10:36 +0800 Subject: ACPI: Add documentation describing ACPICA release automation This patch documents the ACPICA release automation. Signed-off-by: Lv Zheng [ rjw: Editorial changes ] Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/linuxized-acpica.txt | 262 ++++++++++++++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 Documentation/acpi/linuxized-acpica.txt (limited to 'Documentation') diff --git a/Documentation/acpi/linuxized-acpica.txt b/Documentation/acpi/linuxized-acpica.txt new file mode 100644 index 000000000000..defe2eec5331 --- /dev/null +++ b/Documentation/acpi/linuxized-acpica.txt @@ -0,0 +1,262 @@ +Linuxized ACPICA - Introduction to ACPICA Release Automation + +Copyright (C) 2013-2016, Intel Corporation +Author: Lv Zheng + + +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 subystem 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 montly + 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 + . + C. linux-pm / linux-next - "linux-next" branch of the git repository at + . + D. linux / master - "master" branch of the git repository at + . + + Before the linuxized ACPICA patches are sent to the Linux ACPI community + for review, there is a quality ensurance 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 occasionaly 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 utilies, 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 -- cgit v1.2.3 From 1461d8a5a0e4dad98a38a0932950293692e555d3 Mon Sep 17 00:00:00 2001 From: Lv Zheng Date: Thu, 7 Jul 2016 15:10:45 +0800 Subject: ACPI / debugger: Add AML debugger documentation This patch documents the AML debugger. Signed-off-by: Lv Zheng [ rjw: Editorial changes ] Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/aml-debugger.txt | 66 +++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Documentation/acpi/aml-debugger.txt (limited to 'Documentation') diff --git a/Documentation/acpi/aml-debugger.txt b/Documentation/acpi/aml-debugger.txt new file mode 100644 index 000000000000..5f62aa4a493b --- /dev/null +++ b/Documentation/acpi/aml-debugger.txt @@ -0,0 +1,66 @@ +The AML Debugger + +Copyright (C) 2016, Intel Corporation +Author: Lv Zheng + + +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 utlities can be built from the kernel source tree using + the following commands: + + $ cd tools + $ make acpi + + The resultant userspace tool binary is then located at: + + tools/acpi/power/acpi/acpidbg/acpidbg + + It can be installed to system directories by running "make install" (as a + sufficiently privileged user). + +2. Start the userspace debugger interface + + After booting the kernel with the debugger built-in, the debugger can be + started by using the following commands: + + # mount -t debugfs none /sys/kernel/debug + # modprobe acpi_dbg + # tools/acpi/power/acpi/acpidbg/acpidbg + + That spawns the interactive AML debugger environment where you can execute + debugger commands. + + The commands are documented in the "ACPICA Overview and Programmer Reference" + that can be downloaded from + + https://acpica.org/documentation + + The detailed debugger commands reference is located in Chapter 12 "ACPICA + Debugger Reference". The "help" command can be used for a quick reference. + +3. Stop the userspace debugger interface + + The interactive debugger interface can be closed by pressing Ctrl+C or using + the "quit" or "exit" commands. When finished, unload the module with: + + # rmmod acpi_dbg + + The module unloading may fail if there is an acpidbg instance running. + +4. Run the debugger in a script + + It may be useful to run the AML debugger in a test script. "acpidbg" supports + this in a special "batch" mode. For example, the following command outputs + the entire ACPI namespace: + + # acpidbg -b "namespace" -- cgit v1.2.3