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