| .. SPDX-License-Identifier: GPL-2.0 | |
| .. include:: <isonum.txt> | |
| ============================================================ | |
| Linuxized ACPICA - Introduction to ACPICA Release Automation | |
| ============================================================ | |
| :Copyright: |copy| 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. | |
| 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 | |
| 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 | |
| <https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>. | |
| D. linux / master - "master" branch of the git repository at | |
| <https://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 | |
| 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. | |
| 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 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git | |
| # cd acpica | |
| # generate/linux/divergence.sh -s ../linux |