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/divergence.sh -s ../linux
280