|
| 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 |
0 commit comments