0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 ============================================================
0005 Linuxized ACPICA - Introduction to ACPICA Release Automation
0006 ============================================================
0007
0008 :Copyright: |copy| 2013-2016, Intel Corporation
0009
0010 :Author: Lv Zheng <lv.zheng@intel.com>
0011
0012
0013 Abstract
0014 ========
0015 This document describes the ACPICA project and the relationship between
0016 ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica,
0017 include/acpi and tools/power/acpi is automatically updated to follow the
0018 upstream.
0019
0020 ACPICA Project
0021 ==============
0022
0023 The ACPI Component Architecture (ACPICA) project provides an operating
0024 system (OS)-independent reference implementation of the Advanced
0025 Configuration and Power Interface Specification (ACPI). It has been
0026 adapted by various host OSes. By directly integrating ACPICA, Linux can
0027 also benefit from the application experiences of ACPICA from other host
0028 OSes.
0029
0030 The homepage of ACPICA project is: www.acpica.org, it is maintained and
0031 supported by Intel Corporation.
0032
0033 The following figure depicts the Linux ACPI subsystem where the ACPICA
0034 adaptation is included::
0035
0036 +---------------------------------------------------------+
0037 | |
0038 | +---------------------------------------------------+ |
0039 | | +------------------+ | |
0040 | | | Table Management | | |
0041 | | +------------------+ | |
0042 | | +----------------------+ | |
0043 | | | Namespace Management | | |
0044 | | +----------------------+ | |
0045 | | +------------------+ ACPICA Components | |
0046 | | | Event Management | | |
0047 | | +------------------+ | |
0048 | | +---------------------+ | |
0049 | | | Resource Management | | |
0050 | | +---------------------+ | |
0051 | | +---------------------+ | |
0052 | | | Hardware Management | | |
0053 | | +---------------------+ | |
0054 | +---------------------------------------------------+ | |
0055 | | | +------------------+ | | |
0056 | | | | OS Service Layer | | | |
0057 | | | +------------------+ | | |
0058 | | +-------------------------------------------------|-+ |
0059 | | +--------------------+ | |
0060 | | | Device Enumeration | | |
0061 | | +--------------------+ | |
0062 | | +------------------+ | |
0063 | | | Power Management | | |
0064 | | +------------------+ Linux/ACPI Components | |
0065 | | +--------------------+ | |
0066 | | | Thermal Management | | |
0067 | | +--------------------+ | |
0068 | | +--------------------------+ | |
0069 | | | Drivers for ACPI Devices | | |
0070 | | +--------------------------+ | |
0071 | | +--------+ | |
0072 | | | ...... | | |
0073 | | +--------+ | |
0074 | +---------------------------------------------------+ |
0075 | |
0076 +---------------------------------------------------------+
0077
0078 Figure 1. Linux ACPI Software Components
0079
0080 .. note::
0081 A. OS Service Layer - Provided by Linux to offer OS dependent
0082 implementation of the predefined ACPICA interfaces (acpi_os_*).
0083 ::
0084
0085 include/acpi/acpiosxf.h
0086 drivers/acpi/osl.c
0087 include/acpi/platform
0088 include/asm/acenv.h
0089 B. ACPICA Functionality - Released from ACPICA code base to offer
0090 OS independent implementation of the ACPICA interfaces (acpi_*).
0091 ::
0092
0093 drivers/acpi/acpica
0094 include/acpi/ac*.h
0095 tools/power/acpi
0096 C. Linux/ACPI Functionality - Providing Linux specific ACPI
0097 functionality to the other Linux kernel subsystems and user space
0098 programs.
0099 ::
0100
0101 drivers/acpi
0102 include/linux/acpi.h
0103 include/linux/acpi*.h
0104 include/acpi
0105 tools/power/acpi
0106 D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the
0107 ACPI subsystem to offer architecture specific implementation of the
0108 ACPI interfaces. They are Linux specific components and are out of
0109 the scope of this document.
0110 ::
0111
0112 include/asm/acpi.h
0113 include/asm/acpi*.h
0114 arch/*/acpi
0115
0116 ACPICA Release
0117 ==============
0118
0119 The ACPICA project maintains its code base at the following repository URL:
0120 https://github.com/acpica/acpica.git. As a rule, a release is made every
0121 month.
0122
0123 As the coding style adopted by the ACPICA project is not acceptable by
0124 Linux, there is a release process to convert the ACPICA git commits into
0125 Linux patches. The patches generated by this process are referred to as
0126 "linuxized ACPICA patches". The release process is carried out on a local
0127 copy the ACPICA git repository. Each commit in the monthly release is
0128 converted into a linuxized ACPICA patch. Together, they form the monthly
0129 ACPICA release patchset for the Linux ACPI community. This process is
0130 illustrated in the following figure::
0131
0132 +-----------------------------+
0133 | acpica / master (-) commits |
0134 +-----------------------------+
0135 /|\ |
0136 | \|/
0137 | /---------------------\ +----------------------+
0138 | < Linuxize repo Utility >-->| old linuxized acpica |--+
0139 | \---------------------/ +----------------------+ |
0140 | |
0141 /---------\ |
0142 < git reset > \
0143 \---------/ \
0144 /|\ /+-+
0145 | / |
0146 +-----------------------------+ | |
0147 | acpica / master (+) commits | | |
0148 +-----------------------------+ | |
0149 | | |
0150 \|/ | |
0151 /-----------------------\ +----------------------+ | |
0152 < Linuxize repo Utilities >-->| new linuxized acpica |--+ |
0153 \-----------------------/ +----------------------+ |
0154 \|/
0155 +--------------------------+ /----------------------\
0156 | Linuxized ACPICA Patches |<----------------< Linuxize patch Utility >
0157 +--------------------------+ \----------------------/
0158 |
0159 \|/
0160 /---------------------------\
0161 < Linux ACPI Community Review >
0162 \---------------------------/
0163 |
0164 \|/
0165 +-----------------------+ /------------------\ +----------------+
0166 | linux-pm / linux-next |-->< Linux Merge Window >-->| linux / master |
0167 +-----------------------+ \------------------/ +----------------+
0168
0169 Figure 2. ACPICA -> Linux Upstream Process
0170
0171 .. note::
0172 A. Linuxize Utilities - Provided by the ACPICA repository, including a
0173 utility located in source/tools/acpisrc folder and a number of
0174 scripts located in generate/linux folder.
0175 B. acpica / master - "master" branch of the git repository at
0176 <https://github.com/acpica/acpica.git>.
0177 C. linux-pm / linux-next - "linux-next" branch of the git repository at
0178 <https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
0179 D. linux / master - "master" branch of the git repository at
0180 <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.
0181
0182 Before the linuxized ACPICA patches are sent to the Linux ACPI community
0183 for review, there is a quality assurance build test process to reduce
0184 porting issues. Currently this build process only takes care of the
0185 following kernel configuration options:
0186 CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
0187
0188 ACPICA Divergences
0189 ==================
0190
0191 Ideally, all of the ACPICA commits should be converted into Linux patches
0192 automatically without manual modifications, the "linux / master" tree should
0193 contain the ACPICA code that exactly corresponds to the ACPICA code
0194 contained in "new linuxized acpica" tree and it should be possible to run
0195 the release process fully automatically.
0196
0197 As a matter of fact, however, there are source code differences between
0198 the ACPICA code in Linux and the upstream ACPICA code, referred to as
0199 "ACPICA Divergences".
0200
0201 The various sources of ACPICA divergences include:
0202 1. Legacy divergences - Before the current ACPICA release process was
0203 established, there already had been divergences between Linux and
0204 ACPICA. Over the past several years those divergences have been greatly
0205 reduced, but there still are several ones and it takes time to figure
0206 out the underlying reasons for their existence.
0207 2. Manual modifications - Any manual modification (eg. coding style fixes)
0208 made directly in the Linux sources obviously hurts the ACPICA release
0209 automation. Thus it is recommended to fix such issues in the ACPICA
0210 upstream source code and generate the linuxized fix using the ACPICA
0211 release utilities (please refer to Section 4 below for the details).
0212 3. Linux specific features - Sometimes it's impossible to use the
0213 current ACPICA APIs to implement features required by the Linux kernel,
0214 so Linux developers occasionally have to change ACPICA code directly.
0215 Those changes may not be acceptable by ACPICA upstream and in such cases
0216 they are left as committed ACPICA divergences unless the ACPICA side can
0217 implement new mechanisms as replacements for them.
0218 4. ACPICA release fixups - ACPICA only tests commits using a set of the
0219 user space simulation utilities, thus the linuxized ACPICA patches may
0220 break the Linux kernel, leaving us build/boot failures. In order to
0221 avoid breaking Linux bisection, fixes are applied directly to the
0222 linuxized ACPICA patches during the release process. When the release
0223 fixups are backported to the upstream ACPICA sources, they must follow
0224 the upstream ACPICA rules and so further modifications may appear.
0225 That may result in the appearance of new divergences.
0226 5. Fast tracking of ACPICA commits - Some ACPICA commits are regression
0227 fixes or stable-candidate material, so they are applied in advance with
0228 respect to the ACPICA release process. If such commits are reverted or
0229 rebased on the ACPICA side in order to offer better solutions, new ACPICA
0230 divergences are generated.
0231
0232 ACPICA Development
0233 ==================
0234
0235 This paragraph guides Linux developers to use the ACPICA upstream release
0236 utilities to obtain Linux patches corresponding to upstream ACPICA commits
0237 before they become available from the ACPICA release process.
0238
0239 1. Cherry-pick an ACPICA commit
0240
0241 First you need to git clone the ACPICA repository and the ACPICA change
0242 you want to cherry pick must be committed into the local repository.
0243
0244 Then the gen-patch.sh command can help to cherry-pick an ACPICA commit
0245 from the ACPICA local repository::
0246
0247 $ git clone https://github.com/acpica/acpica
0248 $ cd acpica
0249 $ generate/linux/gen-patch.sh -u [commit ID]
0250
0251 Here the commit ID is the ACPICA local repository commit ID you want to
0252 cherry pick. It can be omitted if the commit is "HEAD".
0253
0254 2. Cherry-pick recent ACPICA commits
0255
0256 Sometimes you need to rebase your code on top of the most recent ACPICA
0257 changes that haven't been applied to Linux yet.
0258
0259 You can generate the ACPICA release series yourself and rebase your code on
0260 top of the generated ACPICA release patches::
0261
0262 $ git clone https://github.com/acpica/acpica
0263 $ cd acpica
0264 $ generate/linux/make-patches.sh -u [commit ID]
0265
0266 The commit ID should be the last ACPICA commit accepted by Linux. Usually,
0267 it is the commit modifying ACPI_CA_VERSION. It can be found by executing
0268 "git blame source/include/acpixf.h" and referencing the line that contains
0269 "ACPI_CA_VERSION".
0270
0271 3. Inspect the current divergences
0272
0273 If you have local copies of both Linux and upstream ACPICA, you can generate
0274 a diff file indicating the state of the current divergences::
0275
0276 # git clone https://github.com/acpica/acpica
0277 # git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
0278 # cd acpica
0279 # generate/linux/divergence.sh -s ../linux
