1.. SPDX-License-Identifier: GPL-2.0 2.. include:: <isonum.txt> 3 4============================================================ 5Linuxized ACPICA - Introduction to ACPICA Release Automation 6============================================================ 7 8:Copyright: |copy| 2013-2016, Intel Corporation 9 10:Author: Lv Zheng <lv.zheng@intel.com> 11 12 13Abstract 14======== 15This document describes the ACPICA project and the relationship between 16ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica, 17include/acpi and tools/power/acpi is automatically updated to follow the 18upstream. 19 20ACPICA Project 21============== 22 23The ACPI Component Architecture (ACPICA) project provides an operating 24system (OS)-independent reference implementation of the Advanced 25Configuration and Power Interface Specification (ACPI). It has been 26adapted by various host OSes. By directly integrating ACPICA, Linux can 27also benefit from the application experiences of ACPICA from other host 28OSes. 29 30The homepage of ACPICA project is: www.acpica.org, it is maintained and 31supported by Intel Corporation. 32 33The following figure depicts the Linux ACPI subsystem where the ACPICA 34adaptation is included:: 35 36 +---------------------------------------------------------+ 37 | | 38 | +---------------------------------------------------+ | 39 | | +------------------+ | | 40 | | | Table Management | | | 41 | | +------------------+ | | 42 | | +----------------------+ | | 43 | | | Namespace Management | | | 44 | | +----------------------+ | | 45 | | +------------------+ ACPICA Components | | 46 | | | Event Management | | | 47 | | +------------------+ | | 48 | | +---------------------+ | | 49 | | | Resource Management | | | 50 | | +---------------------+ | | 51 | | +---------------------+ | | 52 | | | Hardware Management | | | 53 | | +---------------------+ | | 54 | +---------------------------------------------------+ | | 55 | | | +------------------+ | | | 56 | | | | OS Service Layer | | | | 57 | | | +------------------+ | | | 58 | | +-------------------------------------------------|-+ | 59 | | +--------------------+ | | 60 | | | Device Enumeration | | | 61 | | +--------------------+ | | 62 | | +------------------+ | | 63 | | | Power Management | | | 64 | | +------------------+ Linux/ACPI Components | | 65 | | +--------------------+ | | 66 | | | Thermal Management | | | 67 | | +--------------------+ | | 68 | | +--------------------------+ | | 69 | | | Drivers for ACPI Devices | | | 70 | | +--------------------------+ | | 71 | | +--------+ | | 72 | | | ...... | | | 73 | | +--------+ | | 74 | +---------------------------------------------------+ | 75 | | 76 +---------------------------------------------------------+ 77 78 Figure 1. Linux ACPI Software Components 79 80.. note:: 81 A. OS Service Layer - Provided by Linux to offer OS dependent 82 implementation of the predefined ACPICA interfaces (acpi_os_*). 83 :: 84 85 include/acpi/acpiosxf.h 86 drivers/acpi/osl.c 87 include/acpi/platform 88 include/asm/acenv.h 89 B. ACPICA Functionality - Released from ACPICA code base to offer 90 OS independent implementation of the ACPICA interfaces (acpi_*). 91 :: 92 93 drivers/acpi/acpica 94 include/acpi/ac*.h 95 tools/power/acpi 96 C. Linux/ACPI Functionality - Providing Linux specific ACPI 97 functionality to the other Linux kernel subsystems and user space 98 programs. 99 :: 100 101 drivers/acpi 102 include/linux/acpi.h 103 include/linux/acpi*.h 104 include/acpi 105 tools/power/acpi 106 D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the 107 ACPI subsystem to offer architecture specific implementation of the 108 ACPI interfaces. They are Linux specific components and are out of 109 the scope of this document. 110 :: 111 112 include/asm/acpi.h 113 include/asm/acpi*.h 114 arch/*/acpi 115 116ACPICA Release 117============== 118 119The ACPICA project maintains its code base at the following repository URL: 120https://github.com/acpica/acpica.git. As a rule, a release is made every 121month. 122 123As the coding style adopted by the ACPICA project is not acceptable by 124Linux, there is a release process to convert the ACPICA git commits into 125Linux patches. The patches generated by this process are referred to as 126"linuxized ACPICA patches". The release process is carried out on a local 127copy the ACPICA git repository. Each commit in the monthly release is 128converted into a linuxized ACPICA patch. Together, they form the monthly 129ACPICA release patchset for the Linux ACPI community. This process is 130illustrated in the following figure:: 131 132 +-----------------------------+ 133 | acpica / master (-) commits | 134 +-----------------------------+ 135 /|\ | 136 | \|/ 137 | /---------------------\ +----------------------+ 138 | < Linuxize repo Utility >-->| old linuxized acpica |--+ 139 | \---------------------/ +----------------------+ | 140 | | 141 /---------\ | 142 < git reset > \ 143 \---------/ \ 144 /|\ /+-+ 145 | / | 146 +-----------------------------+ | | 147 | acpica / master (+) commits | | | 148 +-----------------------------+ | | 149 | | | 150 \|/ | | 151 /-----------------------\ +----------------------+ | | 152 < Linuxize repo Utilities >-->| new linuxized acpica |--+ | 153 \-----------------------/ +----------------------+ | 154 \|/ 155 +--------------------------+ /----------------------\ 156 | Linuxized ACPICA Patches |<----------------< Linuxize patch Utility > 157 +--------------------------+ \----------------------/ 158 | 159 \|/ 160 /---------------------------\ 161 < Linux ACPI Community Review > 162 \---------------------------/ 163 | 164 \|/ 165 +-----------------------+ /------------------\ +----------------+ 166 | linux-pm / linux-next |-->< Linux Merge Window >-->| linux / master | 167 +-----------------------+ \------------------/ +----------------+ 168 169 Figure 2. ACPICA -> Linux Upstream Process 170 171.. note:: 172 A. Linuxize Utilities - Provided by the ACPICA repository, including a 173 utility located in source/tools/acpisrc folder and a number of 174 scripts located in generate/linux folder. 175 B. acpica / master - "master" branch of the git repository at 176 <https://github.com/acpica/acpica.git>. 177 C. linux-pm / linux-next - "linux-next" branch of the git repository at 178 <https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>. 179 D. linux / master - "master" branch of the git repository at 180 <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>. 181 182 Before the linuxized ACPICA patches are sent to the Linux ACPI community 183 for review, there is a quality assurance build test process to reduce 184 porting issues. Currently this build process only takes care of the 185 following kernel configuration options: 186 CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER 187 188ACPICA Divergences 189================== 190 191Ideally, all of the ACPICA commits should be converted into Linux patches 192automatically without manual modifications, the "linux / master" tree should 193contain the ACPICA code that exactly corresponds to the ACPICA code 194contained in "new linuxized acpica" tree and it should be possible to run 195the release process fully automatically. 196 197As a matter of fact, however, there are source code differences between 198the ACPICA code in Linux and the upstream ACPICA code, referred to as 199"ACPICA Divergences". 200 201The various sources of ACPICA divergences include: 202 1. Legacy divergences - Before the current ACPICA release process was 203 established, there already had been divergences between Linux and 204 ACPICA. Over the past several years those divergences have been greatly 205 reduced, but there still are several ones and it takes time to figure 206 out the underlying reasons for their existence. 207 2. Manual modifications - Any manual modification (eg. coding style fixes) 208 made directly in the Linux sources obviously hurts the ACPICA release 209 automation. Thus it is recommended to fix such issues in the ACPICA 210 upstream source code and generate the linuxized fix using the ACPICA 211 release utilities (please refer to Section 4 below for the details). 212 3. Linux specific features - Sometimes it's impossible to use the 213 current ACPICA APIs to implement features required by the Linux kernel, 214 so Linux developers occasionally have to change ACPICA code directly. 215 Those changes may not be acceptable by ACPICA upstream and in such cases 216 they are left as committed ACPICA divergences unless the ACPICA side can 217 implement new mechanisms as replacements for them. 218 4. ACPICA release fixups - ACPICA only tests commits using a set of the 219 user space simulation utilities, thus the linuxized ACPICA patches may 220 break the Linux kernel, leaving us build/boot failures. In order to 221 avoid breaking Linux bisection, fixes are applied directly to the 222 linuxized ACPICA patches during the release process. When the release 223 fixups are backported to the upstream ACPICA sources, they must follow 224 the upstream ACPICA rules and so further modifications may appear. 225 That may result in the appearance of new divergences. 226 5. Fast tracking of ACPICA commits - Some ACPICA commits are regression 227 fixes or stable-candidate material, so they are applied in advance with 228 respect to the ACPICA release process. If such commits are reverted or 229 rebased on the ACPICA side in order to offer better solutions, new ACPICA 230 divergences are generated. 231 232ACPICA Development 233================== 234 235This paragraph guides Linux developers to use the ACPICA upstream release 236utilities to obtain Linux patches corresponding to upstream ACPICA commits 237before they become available from the ACPICA release process. 238 239 1. Cherry-pick an ACPICA commit 240 241 First you need to git clone the ACPICA repository and the ACPICA change 242 you want to cherry pick must be committed into the local repository. 243 244 Then the gen-patch.sh command can help to cherry-pick an ACPICA commit 245 from the ACPICA local repository:: 246 247 $ git clone https://github.com/acpica/acpica 248 $ cd acpica 249 $ generate/linux/gen-patch.sh -u [commit ID] 250 251 Here the commit ID is the ACPICA local repository commit ID you want to 252 cherry pick. It can be omitted if the commit is "HEAD". 253 254 2. Cherry-pick recent ACPICA commits 255 256 Sometimes you need to rebase your code on top of the most recent ACPICA 257 changes that haven't been applied to Linux yet. 258 259 You can generate the ACPICA release series yourself and rebase your code on 260 top of the generated ACPICA release patches:: 261 262 $ git clone https://github.com/acpica/acpica 263 $ cd acpica 264 $ generate/linux/make-patches.sh -u [commit ID] 265 266 The commit ID should be the last ACPICA commit accepted by Linux. Usually, 267 it is the commit modifying ACPI_CA_VERSION. It can be found by executing 268 "git blame source/include/acpixf.h" and referencing the line that contains 269 "ACPI_CA_VERSION". 270 271 3. Inspect the current divergences 272 273 If you have local copies of both Linux and upstream ACPICA, you can generate 274 a diff file indicating the state of the current divergences:: 275 276 # git clone https://github.com/acpica/acpica 277 # git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 278 # cd acpica 279 # generate/linux/divergences.sh -s ../linux 280