Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) .. include:: <isonum.txt>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) ============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) Linuxized ACPICA - Introduction to ACPICA Release Automation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) ============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) :Copyright: |copy| 2013-2016, Intel Corporation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) :Author: Lv Zheng <lv.zheng@intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) Abstract
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) This document describes the ACPICA project and the relationship between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) ACPICA and Linux.  It also describes how ACPICA code in drivers/acpi/acpica,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) include/acpi and tools/power/acpi is automatically updated to follow the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) upstream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) ACPICA Project
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) The ACPI Component Architecture (ACPICA) project provides an operating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) system (OS)-independent reference implementation of the Advanced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) Configuration and Power Interface Specification (ACPI).  It has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) adapted by various host OSes.  By directly integrating ACPICA, Linux can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) also benefit from the application experiences of ACPICA from other host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) OSes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) The homepage of ACPICA project is: www.acpica.org, it is maintained and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) supported by Intel Corporation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) The following figure depicts the Linux ACPI subsystem where the ACPICA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) adaptation is included::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36)       +---------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37)       |                                                         |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38)       |   +---------------------------------------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39)       |   | +------------------+                              | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40)       |   | | Table Management |                              | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41)       |   | +------------------+                              | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42)       |   | +----------------------+                          | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43)       |   | | Namespace Management |                          | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44)       |   | +----------------------+                          | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45)       |   | +------------------+       ACPICA Components      | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46)       |   | | Event Management |                              | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47)       |   | +------------------+                              | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48)       |   | +---------------------+                           | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49)       |   | | Resource Management |                           | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50)       |   | +---------------------+                           | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51)       |   | +---------------------+                           | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52)       |   | | Hardware Management |                           | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53)       |   | +---------------------+                           | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54)       | +---------------------------------------------------+ | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55)       | | |                            +------------------+ | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56)       | | |                            | OS Service Layer | | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57)       | | |                            +------------------+ | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58)       | | +-------------------------------------------------|-+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59)       | |   +--------------------+                          |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60)       | |   | Device Enumeration |                          |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61)       | |   +--------------------+                          |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62)       | |   +------------------+                            |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63)       | |   | Power Management |                            |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64)       | |   +------------------+     Linux/ACPI Components  |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65)       | |   +--------------------+                          |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66)       | |   | Thermal Management |                          |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67)       | |   +--------------------+                          |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68)       | |   +--------------------------+                    |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69)       | |   | Drivers for ACPI Devices |                    |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70)       | |   +--------------------------+                    |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71)       | |   +--------+                                      |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72)       | |   | ...... |                                      |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73)       | |   +--------+                                      |   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74)       | +---------------------------------------------------+   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75)       |                                                         |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76)       +---------------------------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78)                  Figure 1. Linux ACPI Software Components
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81)     A. OS Service Layer - Provided by Linux to offer OS dependent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82)        implementation of the predefined ACPICA interfaces (acpi_os_*).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83)        ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85)          include/acpi/acpiosxf.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86)          drivers/acpi/osl.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87)          include/acpi/platform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88)          include/asm/acenv.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89)     B. ACPICA Functionality - Released from ACPICA code base to offer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90)        OS independent implementation of the ACPICA interfaces (acpi_*).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91)        ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93)          drivers/acpi/acpica
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94)          include/acpi/ac*.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95)          tools/power/acpi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96)     C. Linux/ACPI Functionality - Providing Linux specific ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97)        functionality to the other Linux kernel subsystems and user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98)        programs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99)        ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)          drivers/acpi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)          include/linux/acpi.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)          include/linux/acpi*.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)          include/acpi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)          tools/power/acpi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)     D. Architecture Specific ACPICA/ACPI Functionalities - Provided by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)        ACPI subsystem to offer architecture specific implementation of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)        ACPI interfaces.  They are Linux specific components and are out of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)        the scope of this document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)        ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)          include/asm/acpi.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)          include/asm/acpi*.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)          arch/*/acpi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) ACPICA Release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) The ACPICA project maintains its code base at the following repository URL:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) https://github.com/acpica/acpica.git. As a rule, a release is made every
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) month.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) As the coding style adopted by the ACPICA project is not acceptable by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) Linux, there is a release process to convert the ACPICA git commits into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) Linux patches.  The patches generated by this process are referred to as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) "linuxized ACPICA patches".  The release process is carried out on a local
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) copy the ACPICA git repository.  Each commit in the monthly release is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) converted into a linuxized ACPICA patch.  Together, they form the monthly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) ACPICA release patchset for the Linux ACPI community.  This process is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) illustrated in the following figure::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)     +-----------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)     | acpica / master (-) commits |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)     +-----------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)        /|\         |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)         |         \|/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)         |  /---------------------\    +----------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)         | < Linuxize repo Utility >-->| old linuxized acpica |--+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)         |  \---------------------/    +----------------------+  |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)         |                                                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)      /---------\                                                |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)     < git reset >                                                \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)      \---------/                                                  \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)        /|\                                                        /+-+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)         |                                                        /   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)     +-----------------------------+                             |    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)     | acpica / master (+) commits |                             |    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)     +-----------------------------+                             |    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)                    |                                            |    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)                   \|/                                           |    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)          /-----------------------\    +----------------------+  |    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)         < Linuxize repo Utilities >-->| new linuxized acpica |--+    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)          \-----------------------/    +----------------------+       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)                                                                     \|/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)     +--------------------------+                  /----------------------\
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)     | Linuxized ACPICA Patches |<----------------< Linuxize patch Utility >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)     +--------------------------+                  \----------------------/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)                    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)                   \|/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)      /---------------------------\
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)     < Linux ACPI Community Review >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)      \---------------------------/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)                    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)                   \|/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)     +-----------------------+    /------------------\    +----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)     | linux-pm / linux-next |-->< Linux Merge Window >-->| linux / master |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)     +-----------------------+    \------------------/    +----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)                 Figure 2. ACPICA -> Linux Upstream Process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)     A. Linuxize Utilities - Provided by the ACPICA repository, including a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)        utility located in source/tools/acpisrc folder and a number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)        scripts located in generate/linux folder.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)     B. acpica / master - "master" branch of the git repository at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)        <https://github.com/acpica/acpica.git>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)     C. linux-pm / linux-next - "linux-next" branch of the git repository at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)        <https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)     D. linux / master - "master" branch of the git repository at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)        <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)    Before the linuxized ACPICA patches are sent to the Linux ACPI community
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)    for review, there is a quality assurance build test process to reduce
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)    porting issues.  Currently this build process only takes care of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)    following kernel configuration options:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)    CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) ACPICA Divergences
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) Ideally, all of the ACPICA commits should be converted into Linux patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) automatically without manual modifications, the "linux / master" tree should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) contain the ACPICA code that exactly corresponds to the ACPICA code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) contained in "new linuxized acpica" tree and it should be possible to run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) the release process fully automatically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) As a matter of fact, however, there are source code differences between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) the ACPICA code in Linux and the upstream ACPICA code, referred to as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) "ACPICA Divergences".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) The various sources of ACPICA divergences include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)    1. Legacy divergences - Before the current ACPICA release process was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)       established, there already had been divergences between Linux and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)       ACPICA. Over the past several years those divergences have been greatly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)       reduced, but there still are several ones and it takes time to figure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)       out the underlying reasons for their existence.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)    2. Manual modifications - Any manual modification (eg. coding style fixes)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)       made directly in the Linux sources obviously hurts the ACPICA release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)       automation.  Thus it is recommended to fix such issues in the ACPICA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)       upstream source code and generate the linuxized fix using the ACPICA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)       release utilities (please refer to Section 4 below for the details).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)    3. Linux specific features - Sometimes it's impossible to use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)       current ACPICA APIs to implement features required by the Linux kernel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)       so Linux developers occasionally have to change ACPICA code directly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)       Those changes may not be acceptable by ACPICA upstream and in such cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)       they are left as committed ACPICA divergences unless the ACPICA side can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)       implement new mechanisms as replacements for them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)    4. ACPICA release fixups - ACPICA only tests commits using a set of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)       user space simulation utilities, thus the linuxized ACPICA patches may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)       break the Linux kernel, leaving us build/boot failures.  In order to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)       avoid breaking Linux bisection, fixes are applied directly to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)       linuxized ACPICA patches during the release process.  When the release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)       fixups are backported to the upstream ACPICA sources, they must follow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)       the upstream ACPICA rules and so further modifications may appear.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)       That may result in the appearance of new divergences.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)    5. Fast tracking of ACPICA commits - Some ACPICA commits are regression
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)       fixes or stable-candidate material, so they are applied in advance with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)       respect to the ACPICA release process.  If such commits are reverted or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)       rebased on the ACPICA side in order to offer better solutions, new ACPICA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)       divergences are generated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) ACPICA Development
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) This paragraph guides Linux developers to use the ACPICA upstream release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) utilities to obtain Linux patches corresponding to upstream ACPICA commits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) before they become available from the ACPICA release process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)    1. Cherry-pick an ACPICA commit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)    First you need to git clone the ACPICA repository and the ACPICA change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)    you want to cherry pick must be committed into the local repository.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)    Then the gen-patch.sh command can help to cherry-pick an ACPICA commit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)    from the ACPICA local repository::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)    $ git clone https://github.com/acpica/acpica
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)    $ cd acpica
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)    $ generate/linux/gen-patch.sh -u [commit ID]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)    Here the commit ID is the ACPICA local repository commit ID you want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)    cherry pick.  It can be omitted if the commit is "HEAD".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)    2. Cherry-pick recent ACPICA commits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)    Sometimes you need to rebase your code on top of the most recent ACPICA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)    changes that haven't been applied to Linux yet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)    You can generate the ACPICA release series yourself and rebase your code on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)    top of the generated ACPICA release patches::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)    $ git clone https://github.com/acpica/acpica
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)    $ cd acpica
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)    $ generate/linux/make-patches.sh -u [commit ID]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)    The commit ID should be the last ACPICA commit accepted by Linux.  Usually,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)    it is the commit modifying ACPI_CA_VERSION.  It can be found by executing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)    "git blame source/include/acpixf.h" and referencing the line that contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)    "ACPI_CA_VERSION".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)    3. Inspect the current divergences
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)    If you have local copies of both Linux and upstream ACPICA, you can generate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)    a diff file indicating the state of the current divergences::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)    # git clone https://github.com/acpica/acpica
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)    # git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)    # cd acpica
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)    # generate/linux/divergences.sh -s ../linux