This patch adds documentation on ACPICA release automation into the kernel Documentation/acpi folder. Signed-off-by: Lv Zheng <lv.zheng@xxxxxxxxx> --- Documentation/acpi/linuxized-acpica.txt | 253 +++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 Documentation/acpi/linuxized-acpica.txt diff --git a/Documentation/acpi/linuxized-acpica.txt b/Documentation/acpi/linuxized-acpica.txt new file mode 100644 index 0000000..74103c1 --- /dev/null +++ b/Documentation/acpi/linuxized-acpica.txt @@ -0,0 +1,253 @@ +Linuxized ACPICA - Introduction of ACPICA Release Automation + +Copyright (C) 2013-2016, Intel Corporation +Author: Lv Zheng <lv.zheng@xxxxxxxxx> + + +Abstract: + +This document describes the ACPICA project and the relationship between +ACPICA and Linux. It also includes the descriptions on how ACPICA code is +automatically released to the following Linux subdirectories: +drivers/acpi/acpica, include/acpi and tools/power/acpi. + + +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 dipicts the Linux ACPI subystem where the ACPICA + adaption 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 Functionalities - 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 Functionalities - Providing Linux specific ACPI + functionalities to the other Linux kernel subsystems and the 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 is out of + the scope of this document. + include/asm/acpi.h + include/asm/acpi*.h + arch/*/acpi + +2. ACPICA Release + + ACPICA project maintains a code base at the following repository URL: + https://github.com/acpica/acpica.git. It is released once a 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 + the Linux acceptable patches. The patches generated by this process are + known as "Linuxized ACPICA Patches". The release process is performed + against a local copy of the ACPICA git repository. Each commit in the + monthly release is converted into the linuxized ACPICA patch. They form + a montly ACPICA release patchset for Linux ACPI community. The + following figure dipicts the Linux upstream process of the ACPICA + commits: + + +-----------------------------+ + | 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 bunch 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>. + E. Linux ACPI Community - Reached at + <mailto:linux-acpi@xxxxxxxxxxxxxxx>. + + Before the linuxized ACPICA patches are sent to the Linux ACPI community + for review, there is a quality ensurance build test process performed to + reduce porting issues. Currently this build process only cares about + the following kernel configurations: + CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER + +3. ACPICA Divergence + + It's ideal that if all of the ACPICA commits are upstreamed + automatically without modifications, the "linux / master" tree should + contain the ACPICA code that is exactly same as the ACPICA code + contained in "new linuxized acpica" tree and the release process thus + could be performed automatically. + + But the facts are there are always source code differences between + Linux and ACPICA, such differences are known as "ACPICA Divergences". + + The various sources of the ACPICA divergences include: + 1. The existing divergences - Before the ACPICA release cycle is + fully running, there has already been divergences between Linux and + ACPICA. Over the past several years, the divergences are greatly + reduced, but there are still several ones and it takes time to figure + out the root cause of these old divergences. + 2. Manual modifications - Any manual modification (ex., coding style + fixes) done directly in the Linux side obviously hurts the ACPICA + release automation. Thus it is recommended to fix such issues in the + ACPICA upstream and generate the linuxized fix using the ACPICA + release utilities (please refer to the Chapter 4 for the details). + 3. Linux specific features - Sometime, it's impossible to use the + current ACPICA APIs to implement the features required by the Linux + kernel, the Linux developers have to hack ACPICA code directly. Such + hacks may not be acceptable from ACPICA's point of view, then they + are left as committed ACPICA divergences unless ACPICA side can + implement new mechanisms as replacements to clean these hacks up. + 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 not + to break the Linux bisection process, fixes are done directly to the + linuxized ACPICA patches during the release process. When the + release fixups are back ported to the ACPICA upstream, they must + follow the ACPICA upstream rules and thus risk further modifications. + These can all result in the new divergences. + 5. Quick path of the ACPICA commits - Some ACPICA commits are good + stable materials, they are upstreamed prior than the ACPICA release + process. If such commits are reverted or rebased in the ACPICA side + in order to offer better solutions, new ACPICA divergences are + generated. + +4. ACPICA Development + + This paragraph guides the Linux developers to use the ACPICA upstream + release utilities to obtain the ACPICA upstream commits before they + are released by the ACPICA release process. + + 1. Cherry-pick an ACPICA commit: + First you need to git clone the ACPICA repository and the ACPICA changes + 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 the recent ACPICA commits: + Sometimes you need to rebase your code on top of the recent ACPICA + changes that haven't been upstreamed to Linux yet. You can generate + the ACPICA release series on your own 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. + Normally it is a commit modifying ACPI_CA_VERSION. The modification can + be achieved by executing "git blame source/include/acpixf.h" and + referencing line that contains "ACPI_CA_VERSION". + + 3. Confirm the current divergences: + If you have local copies of both Linux and 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 -- 1.7.10 -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
