[PATCH v2 1/4] ACPI: Add documentation describing ACPICA release automation

[Lv Zheng <lv.zheng@intel.com>]

This patch adds documentation on ACPICA release automation into the kernel
Documentation/acpi folder.

Signed-off-by: Lv Zheng <lv.zheng@intel.com>
---
 Documentation/acpi/linuxized-acpica.txt |  253 +++++++++++++++++++++++++++++++
 1 file changed, 253 insertions(+)
 create mode 100644 Documentation/acpi/linuxized-acpica.txt

diff --git a/Documentation/acpi/linuxized-acpica.txt b/Documentation/acpi/linuxized-acpica.txt
new file mode 100644
index 0000000..74103c1
--- /dev/null
+++ b/Documentation/acpi/linuxized-acpica.txt
@@ -0,0 +1,253 @@
+Linuxized ACPICA - Introduction of ACPICA Release Automation
+
+Copyright (C) 2013-2016, Intel Corporation
+Author: Lv Zheng <lv.zheng@intel.com>
+
+
+Abstract:
+
+This document describes the ACPICA project and the relationship between
+ACPICA and Linux.  It also includes the descriptions on how ACPICA code is
+automatically released to the following Linux subdirectories:
+drivers/acpi/acpica, include/acpi and tools/power/acpi.
+
+
+1. ACPICA Project
+
+   The ACPI Component Architecture (ACPICA) project provides an operating
+   system (OS)-independent reference implementation of the Advanced
+   Configuration and Power Interface Specification (ACPI).  It has been
+   adapted by various host OSes.  By directly integrating ACPICA, Linux can
+   also benefit from the application experiences of ACPICA from other host
+   OSes.
+
+   The homepage of ACPICA project is: www.acpica.org, it is maintained and
+   supported by Intel Corporation.
+
+   The following figure dipicts the Linux ACPI subystem where the ACPICA
+   adaption is included:
+
+      +---------------------------------------------------------+
+      |                                                         |
+      |   +---------------------------------------------------+ |
+      |   | +------------------+                              | |
+      |   | | Table Management |                              | |
+      |   | +------------------+                              | |
+      |   | +----------------------+                          | |
+      |   | | Namespace Management |                          | |
+      |   | +----------------------+                          | |
+      |   | +------------------+       ACPICA Components      | |
+      |   | | Event Management |                              | |
+      |   | +------------------+                              | |
+      |   | +---------------------+                           | |
+      |   | | Resource Management |                           | |
+      |   | +---------------------+                           | |
+      |   | +---------------------+                           | |
+      |   | | Hardware Management |                           | |
+      |   | +---------------------+                           | |
+      | +---------------------------------------------------+ | |
+      | | |                            +------------------+ | | |
+      | | |                            | OS Service Layer | | | |
+      | | |                            +------------------+ | | |
+      | | +-------------------------------------------------|-+ |
+      | |   +--------------------+                          |   |
+      | |   | Device Enumeration |                          |   |
+      | |   +--------------------+                          |   |
+      | |   +------------------+                            |   |
+      | |   | Power Management |                            |   |
+      | |   +------------------+     Linux/ACPI Components  |   |
+      | |   +--------------------+                          |   |
+      | |   | Thermal Management |                          |   |
+      | |   +--------------------+                          |   |
+      | |   +--------------------------+                    |   |
+      | |   | Drivers for ACPI Devices |                    |   |
+      | |   +--------------------------+                    |   |
+      | |   +--------+                                      |   |
+      | |   | ...... |                                      |   |
+      | |   +--------+                                      |   |
+      | +---------------------------------------------------+   |
+      |                                                         |
+      +---------------------------------------------------------+
+
+                 Figure 1. Linux ACPI Software Components
+
+   NOTE:
+    A. OS Service Layer - Provided by Linux to offer OS dependent
+       implementation of the predefined ACPICA interfaces (acpi_os_*).
+         include/acpi/acpiosxf.h
+         drivers/acpi/osl.c
+         include/acpi/platform
+         include/asm/acenv.h
+    B. ACPICA Functionalities - Released from ACPICA code base to offer
+       OS independent implementation of the ACPICA interfaces (acpi_*).
+         drivers/acpi/acpica
+         include/acpi/ac*.h
+         tools/power/acpi
+    C. Linux/ACPI Functionalities - Providing Linux specific ACPI
+       functionalities to the other Linux kernel subsystems and the user
+       space programs.
+         drivers/acpi
+         include/linux/acpi.h
+         include/linux/acpi*.h
+         include/acpi
+         tools/power/acpi
+    D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the
+       ACPI subsystem to offer architecture specific implementation of the
+       ACPI interfaces.  They are Linux specific components, and is out of
+       the scope of this document.
+         include/asm/acpi.h
+         include/asm/acpi*.h
+         arch/*/acpi
+
+2. ACPICA Release
+
+   ACPICA project maintains a code base at the following repository URL:
+   https://github.com/acpica/acpica.git.  It is released once a month.
+
+   As the coding style adopted by the ACPICA project is not acceptable by
+   Linux, there is a release process to convert the ACPICA GIT commits into
+   the Linux acceptable patches.  The patches generated by this process are
+   known as "Linuxized ACPICA Patches".  The release process is performed
+   against a local copy of the ACPICA git repository.  Each commit in the
+   monthly release is converted into the linuxized ACPICA patch.  They form
+   a montly ACPICA release patchset for Linux ACPI community.  The
+   following figure dipicts the Linux upstream process of the ACPICA
+   commits:
+
+    +-----------------------------+
+    | acpica / master (-) commits |
+    +-----------------------------+
+       /|\         |
+        |         \|/
+        |  /---------------------\    +----------------------+
+        | < Linuxize repo Utility >-->| old linuxized acpica |--+
+        |  \---------------------/    +----------------------+  |
+        |                                                       |
+     /---------\                                                |
+    < git reset >                                                \
+     \---------/                                                  \
+       /|\                                                        /+-+
+        |                                                        /   |
+    +-----------------------------+                             |    |
+    | acpica / master (+) commits |                             |    |
+    +-----------------------------+                             |    |
+                   |                                            |    |
+                  \|/                                           |    |
+         /-----------------------\    +----------------------+  |    |
+        < Linuxize repo Utilities >-->| new linuxized acpica |--+    |
+         \-----------------------/    +----------------------+       |
+                                                                    \|/
+    +--------------------------+                  /----------------------\
+    | Linuxized ACPICA Patches |<----------------< Linuxize patch Utility >
+    +--------------------------+                  \----------------------/
+                   |
+                  \|/
+     /---------------------------\
+    < Linux ACPI Community Review >
+     \---------------------------/
+                   |
+                  \|/
+    +-----------------------+   /------------------\    +----------------+
+    | linux-pm / linux-next |--< Linux Merge Window >-->| linux / master |
+    +-----------------------+   \------------------/    +----------------+
+
+                Figure 2. ACPICA -> Linux Upstream Process
+
+   NOTE:
+    A. Linuxize Utilities - Provided by the ACPICA repository, including a
+       utility located in source/tools/acpisrc folder and a bunch of
+       scripts located in generate/linux folder.
+    B. acpica / master - "master" branch of the git repository at
+       <https://github.com/acpica/acpica.git>.
+    C. linux-pm / linux-next - "linux-next" branch of the git repository at
+       <http://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
+    D. linux / master - "master" branch of the git repository at
+       <http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.
+    E. Linux ACPI Community - Reached at
+       <mailto:linux-acpi@vger.kernel.org>.
+
+   Before the linuxized ACPICA patches are sent to the Linux ACPI community
+   for review, there is a quality ensurance build test process performed to
+   reduce porting issues.  Currently this build process only cares about
+   the following kernel configurations:
+   CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
+
+3. ACPICA Divergence
+
+   It's ideal that if all of the ACPICA commits are upstreamed
+   automatically without modifications, the "linux / master" tree should
+   contain the ACPICA code that is exactly same as the ACPICA code
+   contained in "new linuxized acpica" tree and the release process thus
+   could be performed automatically.
+
+   But the facts are there are always source code differences between
+   Linux and ACPICA, such differences are known as "ACPICA Divergences".
+
+   The various sources of the ACPICA divergences include:
+   1. The existing divergences - Before the ACPICA release cycle is
+      fully running, there has already been divergences between Linux and
+      ACPICA. Over the past several years, the divergences are greatly
+      reduced, but there are still several ones and it takes time to figure
+      out the root cause of these old divergences.
+   2. Manual modifications - Any manual modification (ex., coding style
+      fixes) done directly in the Linux side obviously hurts the ACPICA
+      release automation.  Thus it is recommended to fix such issues in the
+      ACPICA upstream and generate the linuxized fix using the ACPICA
+      release utilities (please refer to the Chapter 4 for the details).
+   3. Linux specific features - Sometime, it's impossible to use the
+      current ACPICA APIs to implement the features required by the Linux
+      kernel, the Linux developers have to hack ACPICA code directly.  Such
+      hacks may not be acceptable from ACPICA's point of view, then they
+      are left as committed ACPICA divergences unless ACPICA side can
+      implement new mechanisms as replacements to clean these hacks up.
+   4. ACPICA release fixups - ACPICA only tests commits using a set of the
+      user space simulation utilies, thus the linuxized ACPICA patches may
+      break the Linux kernel, leaving us build/boot failures.  In order not
+      to break the Linux bisection process, fixes are done directly to the
+      linuxized ACPICA patches during the release process.  When the
+      release fixups are back ported to the ACPICA upstream, they must
+      follow the ACPICA upstream rules and thus risk further modifications.
+      These can all result in the new divergences.
+   5. Quick path of the ACPICA commits - Some ACPICA commits are good
+      stable materials, they are upstreamed prior than the ACPICA release
+      process.  If such commits are reverted or rebased in the ACPICA side
+      in order to offer better solutions, new ACPICA divergences are
+      generated.
+
+4. ACPICA Development
+
+   This paragraph guides the Linux developers to use the ACPICA upstream
+   release utilities to obtain the ACPICA upstream commits before they
+   are released by the ACPICA release process.
+
+   1. Cherry-pick an ACPICA commit:
+   First you need to git clone the ACPICA repository and the ACPICA changes
+   you want to cherry pick must be committed into the local repository.
+   Then the gen-patch.sh command can help to cherry-pick an ACPICA commit
+   from the ACPICA local repository.
+   # git clone https://github.com/acpica/acpica
+   # cd acpica
+   # generate/linux/gen-patch.sh -u [commit ID]
+   Here the commit ID is the ACPICA local repository commit ID you want to
+   cherry pick.  It can be omitted if the commit is "HEAD".
+
+   2. Cherry-pick the recent ACPICA commits:
+   Sometimes you need to rebase your code on top of the recent ACPICA
+   changes that haven't been upstreamed to Linux yet.  You can generate
+   the ACPICA release series on your own and rebase your code on top of
+   the generated ACPICA release patches.
+   # git clone https://github.com/acpica/acpica
+   # cd acpica
+   # generate/linux/make-patches.sh -u [commit ID]
+   The commit ID should be the last ACPICA commit accepted by Linux.
+   Normally it is a commit modifying ACPI_CA_VERSION.  The modification can
+   be achieved by executing "git blame source/include/acpixf.h" and
+   referencing line that contains "ACPI_CA_VERSION".
+
+   3. Confirm the current divergences:
+   If you have local copies of both Linux and ACPICA, you can generate a
+   diff file indicating the state of the current divergences:
+   # git clone https://github.com/acpica/acpica
+   # git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+   # cd acpica
+   # generate/linux/divergences.sh -s ../linux
-- 
1.7.10