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