Commit | Line | Data |
---|---|---|
9305aa6f LZ |
1 | Linuxized ACPICA - Introduction to ACPICA Release Automation |
2 | ||
3 | Copyright (C) 2013-2016, Intel Corporation | |
4 | Author: Lv Zheng <lv.zheng@intel.com> | |
5 | ||
6 | ||
7 | Abstract: | |
8 | ||
9 | This document describes the ACPICA project and the relationship between | |
10 | ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica, | |
11 | include/acpi and tools/power/acpi is automatically updated to follow the | |
12 | upstream. | |
13 | ||
14 | ||
15 | 1. 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 | ||
102 | 2. 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 | ||
173 | 3. 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 | ||
216 | 4. 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 |