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