Documentation/acpi/linuxized-acpica.txt

   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 subsystem 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 monthly
 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 assurance 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 occasionally 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 utilities, 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