Commit 25710e23 authored by Changbin Du's avatar Changbin Du Committed by Rafael J. Wysocki
Browse files

Documentation: ACPI: move linuxized-acpica.txt to driver-api/acpi and convert to reST 



This converts the plain text documentation to reStructuredText format
and adds it to Sphinx TOC tree.

No essential content change.

Signed-off-by: default avatarChangbin Du <changbin.du@gmail.com>
Reviewed-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
parent 1cf70ae6

Documentation/driver-api/acpi/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -5,3 +5,4 @@ ACPI Support 
.. toctree::

   :maxdepth: 2



   linuxized-acpica

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

+63 −46
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>



============================================================

Linuxized ACPICA - Introduction to ACPICA Release Automation

============================================================



Copyright (C) 2013-2016, Intel Corporation

Author: Lv Zheng <lv.zheng@intel.com>

:Copyright: |copy| 2013-2016, Intel Corporation



:Author: Lv Zheng <lv.zheng@intel.com>



Abstract:



Abstract

========

This document describes the ACPICA project and the relationship between

ACPICA and Linux.  It also describes how ACPICA code in drivers/acpi/acpica,

include/acpi and tools/power/acpi is automatically updated to follow the

upstream.





1. ACPICA Project

ACPICA Project

==============



The ACPI Component Architecture (ACPICA) project provides an operating

system (OS)-independent reference implementation of the Advanced
@@ -25,7 +31,7 @@ upstream. 
supported by Intel Corporation.



The following figure depicts the Linux ACPI subsystem where the ACPICA

   adaptation is included:

adaptation is included::



      +---------------------------------------------------------+

      |                                                         |
@@ -71,21 +77,27 @@ upstream. 


                 Figure 1. Linux ACPI Software Components



   NOTE:

.. 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 Functionality - 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 Functionality - Providing Linux specific ACPI

       functionality to the other Linux kernel subsystems and user space

       programs.

       ::



         drivers/acpi

         include/linux/acpi.h

         include/linux/acpi*.h
@@ -95,11 +107,14 @@ upstream. 
       ACPI subsystem to offer architecture specific implementation of the

       ACPI interfaces.  They are Linux specific components and are out of

       the scope of this document.

       ::



         include/asm/acpi.h

         include/asm/acpi*.h

         arch/*/acpi



2. ACPICA Release

ACPICA Release

==============



The ACPICA project maintains its code base at the following repository URL:

https://github.com/acpica/acpica.git. As a rule, a release is made every
@@ -112,7 +127,7 @@ upstream. 
copy the ACPICA git repository.  Each commit in the monthly release is

converted into a linuxized ACPICA patch.  Together, they form the monthly

ACPICA release patchset for the Linux ACPI community.  This process is

   illustrated in the following figure:

illustrated in the following figure::



    +-----------------------------+

    | acpica / master (-) commits |
@@ -153,7 +168,7 @@ upstream. 


                Figure 2. ACPICA -> Linux Upstream Process



   NOTE:

.. note::

    A. Linuxize Utilities - Provided by the ACPICA repository, including a

       utility located in source/tools/acpisrc folder and a number of

       scripts located in generate/linux folder.
@@ -170,7 +185,8 @@ upstream. 
   following kernel configuration options:

   CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER



3. ACPICA Divergences

ACPICA Divergences

==================



Ideally, all of the ACPICA commits should be converted into Linux patches

automatically without manual modifications, the "linux / master" tree should
@@ -213,7 +229,8 @@ upstream. 
      rebased on the ACPICA side in order to offer better solutions, new ACPICA

      divergences are generated.



4. ACPICA Development

ACPICA Development

==================



This paragraph guides Linux developers to use the ACPICA upstream release

utilities to obtain Linux patches corresponding to upstream ACPICA commits
@@ -225,7 +242,7 @@ upstream. 
   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:

   from the ACPICA local repository::



   $ git clone https://github.com/acpica/acpica

   $ cd acpica
@@ -240,7 +257,7 @@ upstream. 
   changes that haven't been applied to Linux yet.



   You can generate the ACPICA release series yourself and rebase your code on

   top of the generated ACPICA release patches:

   top of the generated ACPICA release patches::



   $ git clone https://github.com/acpica/acpica

   $ cd acpica
@@ -254,7 +271,7 @@ upstream. 
   3. Inspect the current divergences



   If you have local copies of both Linux and upstream ACPICA, you can generate

   a diff file indicating the state of the current divergences:

   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

CRA Git | Maintained and supported by SUSTech CRA and CCSE