Documentation/driver-api/acpi/linuxized-acpica.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 ============================================================
   5 Linuxized 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
  13 Abstract
  14 ========
  15 This document describes the ACPICA project and the relationship between
  16 ACPICA and Linux.  It also describes how ACPICA code in drivers/acpi/acpica,
  17 include/acpi and tools/power/acpi is automatically updated to follow the
  18 upstream.
  19
  20 ACPICA Project
  21 ==============
  22
  23 The ACPI Component Architecture (ACPICA) project provides an operating
  24 system (OS)-independent reference implementation of the Advanced
  25 Configuration and Power Interface Specification (ACPI).  It has been
  26 adapted by various host OSes.  By directly integrating ACPICA, Linux can
  27 also benefit from the application experiences of ACPICA from other host
  28 OSes.
  29
  30 The homepage of ACPICA project is: www.acpica.org, it is maintained and
  31 supported by Intel Corporation.
  32
  33 The following figure depicts the Linux ACPI subsystem where the ACPICA
  34 adaptation 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
 116 ACPICA Release
 117 ==============
 118
 119 The ACPICA project maintains its code base at the following repository URL:
 120 https://github.com/acpica/acpica.git. As a rule, a release is made every
 121 month.
 122
 123 As the coding style adopted by the ACPICA project is not acceptable by
 124 Linux, there is a release process to convert the ACPICA git commits into
 125 Linux patches.  The patches generated by this process are referred to as
 126 "linuxized ACPICA patches".  The release process is carried out on a local
 127 copy the ACPICA git repository.  Each commit in the monthly release is
 128 converted into a linuxized ACPICA patch.  Together, they form the monthly
 129 ACPICA release patchset for the Linux ACPI community.  This process is
 130 illustrated 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
 188 ACPICA Divergences
 189 ==================
 190
 191 Ideally, all of the ACPICA commits should be converted into Linux patches
 192 automatically without manual modifications, the "linux / master" tree should
 193 contain the ACPICA code that exactly corresponds to the ACPICA code
 194 contained in "new linuxized acpica" tree and it should be possible to run
 195 the release process fully automatically.
 196
 197 As a matter of fact, however, there are source code differences between
 198 the ACPICA code in Linux and the upstream ACPICA code, referred to as
 199 "ACPICA Divergences".
 200
 201 The 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
 232 ACPICA Development
 233 ==================
 234
 235 This paragraph guides Linux developers to use the ACPICA upstream release
 236 utilities to obtain Linux patches corresponding to upstream ACPICA commits
 237 before 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