요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
============================================================
Linuxized ACPICA - Introduction to ACPICA Release Automation
============================================================
:Copyright: |copy| 2013-2016, Intel Corporation
:Author: Lv Zheng <[email protected]>
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.
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 depicts the Linux ACPI subsystem where the ACPICA
adaptation 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 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
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 are out of
the scope of this document.
::
include/asm/acpi.h
include/asm/acpi*.h
arch/*/acpi
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
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
Linux patches. The patches generated by this process are referred to as
"linuxized ACPICA patches". The release process is carried out on a local
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::
+-----------------------------+
| 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 number 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
<https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
D. linux / master - "master" branch of the git repository at
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.
Before the linuxized ACPICA patches are sent to the Linux ACPI community
for review, there is a quality assurance build test process to reduce
porting issues. Currently this build process only takes care of the
following kernel configuration options:
CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
ACPICA Divergences
==================
Ideally, all of the ACPICA commits should be converted into Linux patches
automatically without manual modifications, the "linux / master" tree should
contain the ACPICA code that exactly corresponds to the ACPICA code
contained in "new linuxized acpica" tree and it should be possible to run
the release process fully automatically.
As a matter of fact, however, there are source code differences between
the ACPICA code in Linux and the upstream ACPICA code, referred to as
"ACPICA Divergences".
The various sources of ACPICA divergences include:
1. Legacy divergences - Before the current ACPICA release process was
established, there already had been divergences between Linux and
ACPICA. Over the past several years those divergences have been greatly
reduced, but there still are several ones and it takes time to figure
out the underlying reasons for their existence.
2. Manual modifications - Any manual modification (eg. coding style fixes)
made directly in the Linux sources obviously hurts the ACPICA release
automation. Thus it is recommended to fix such issues in the ACPICA
upstream source code and generate the linuxized fix using the ACPICA
release utilities (please refer to Section 4 below for the details).
3. Linux specific features - Sometimes it's impossible to use the
current ACPICA APIs to implement features required by the Linux kernel,
so Linux developers occasionally have to change ACPICA code directly.
Those changes may not be acceptable by ACPICA upstream and in such cases
they are left as committed ACPICA divergences unless the ACPICA side can
implement new mechanisms as replacements for them.
4. ACPICA release fixups - ACPICA only tests commits using a set of the
user space simulation utilities, thus the linuxized ACPICA patches may
break the Linux kernel, leaving us build/boot failures. In order to
avoid breaking Linux bisection, fixes are applied directly to the
linuxized ACPICA patches during the release process. When the release
fixups are backported to the upstream ACPICA sources, they must follow
the upstream ACPICA rules and so further modifications may appear.
That may result in the appearance of new divergences.
5. Fast tracking of ACPICA commits - Some ACPICA commits are regression
fixes or stable-candidate material, so they are applied in advance with
respect to the ACPICA release process. If such commits are reverted or
rebased on the ACPICA side in order to offer better solutions, new ACPICA
divergences are generated.
ACPICA Development
==================
This paragraph guides Linux developers to use the ACPICA upstream release
utilities to obtain Linux patches corresponding to upstream ACPICA commits
before they become available from the ACPICA release process.
1. Cherry-pick an ACPICA commit
First you need to git clone the ACPICA repository and the ACPICA change
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 recent ACPICA commits
Sometimes you need to rebase your code on top of the most recent ACPICA
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::
$ 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. Usually,
it is the commit modifying ACPI_CA_VERSION. It can be found by executing
"git blame source/include/acpixf.h" and referencing the line that contains
"ACPI_CA_VERSION".
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::
# git clone https://github.com/acpica/acpica
# git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
# cd acpica
# generate/linux/divergence.sh -s ../linux
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Linuxized ACPICA와 릴리스 자동화 개요
1-19.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>이 문서는 `GPL-2.0` 라이선스를 따르며, 저작권은 2013-2016 Intel Corporation에 있습니다. 저자는 Lv Zheng `<[email protected]>`입니다.
이 문서는 ACPICA 프로젝트와 ACPICA 및 Linux 사이의 관계를 설명합니다. 또한 `drivers/acpi/acpica`, `include/acpi`, `tools/power/acpi`의 ACPICA 코드를 업스트림에 맞춰 자동으로 갱신하는 방법을 설명합니다.
ACPICA 프로젝트와 Linux ACPI 구성
20-79ACPI Component Architecture(ACPICA) 프로젝트는 Advanced Configuration and Power Interface Specification(ACPI)의 운영체제 독립적 참조 구현을 제공합니다. 여러 호스트 운영체제가 이를 채택했으며, Linux도 ACPICA를 직접 통합하여 다른 운영체제에서 축적된 적용 경험의 이점을 얻을 수 있습니다.
ACPICA 프로젝트 홈페이지는 `www.acpica.org`이며 Intel Corporation이 유지보수하고 지원합니다.
원문의 첫 번째 그림은 ACPICA 적응 계층이 포함된 Linux ACPI 서브시스템을 보여 줍니다. ACPICA의 운영체제 독립 구성 요소가 Linux가 제공하는 OS Service Layer를 거쳐 Linux 고유 ACPI 기능과 연결됩니다.
ACPICA 공통 기능, Linux OS Service Layer, Linux/ACPI 고유 기능의 계층 관계를 재구성했습니다.
ACPICA와 Linux 계층별 역할
80-115A. OS Service Layer는 Linux가 제공하며 미리 정의된 ACPICA 인터페이스인 `acpi_os_*`의 운영체제 종속 구현을 담당합니다. 관련 경로는 다음과 같습니다.
include/acpi/acpiosxf.h
drivers/acpi/osl.c
include/acpi/platform
include/asm/acenv.hB. ACPICA 기능은 ACPICA 코드베이스에서 릴리스되며 `acpi_*` 인터페이스의 운영체제 독립 구현을 제공합니다. 관련 경로는 다음과 같습니다.
drivers/acpi/acpica
include/acpi/ac*.h
tools/power/acpiC. Linux/ACPI 기능은 다른 Linux 커널 서브시스템과 사용자 공간 프로그램에 Linux 고유 ACPI 기능을 제공합니다. 관련 경로는 다음과 같습니다.
drivers/acpi
include/linux/acpi.h
include/linux/acpi*.h
include/acpi
tools/power/acpiD. 아키텍처별 ACPICA 및 ACPI 기능은 ACPI 서브시스템이 아키텍처 종속 ACPI 인터페이스 구현을 제공하는 부분입니다. Linux 고유 구성 요소이며 이 문서의 범위를 벗어납니다. 관련 경로는 다음과 같습니다.
include/asm/acpi.h
include/asm/acpi*.h
arch/*/acpiACPICA 월간 릴리스의 Linux 변환 과정
116-170ACPICA 프로젝트는 `https://github.com/acpica/acpica.git` 저장소에서 코드베이스를 관리하며 원칙적으로 매월 릴리스합니다.
ACPICA 프로젝트의 코딩 스타일은 Linux에서 그대로 받아들일 수 없으므로 ACPICA Git 커밋을 Linux 패치로 변환하는 릴리스 과정이 있습니다. 이 과정에서 만든 패치를 `linuxized ACPICA patches`라고 부릅니다.
릴리스 과정은 ACPICA Git 저장소의 로컬 복사본에서 수행됩니다. 월간 릴리스의 각 커밋을 linuxized ACPICA 패치로 변환하고, 이들을 모아 Linux ACPI 커뮤니티용 월간 ACPICA 릴리스 패치 세트를 구성합니다.
기준 트리와 새 트리를 각각 Linux 형식으로 변환해 차이를 패치로 만들고, 검토와 병합 창을 거쳐 Linux master에 반영합니다.
릴리스 도구, 저장소와 품질 보증
171-187A. Linuxize 유틸리티는 ACPICA 저장소가 제공합니다. `source/tools/acpisrc` 폴더의 유틸리티와 `generate/linux` 폴더의 여러 스크립트가 포함됩니다.
B. `acpica / master`는 `https://github.com/acpica/acpica.git` 저장소의 `master` 브랜치입니다.
C. `linux-pm / linux-next`는 `https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git` 저장소의 `linux-next` 브랜치입니다.
D. `linux / master`는 `https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git` 저장소의 `master` 브랜치입니다.
linuxized ACPICA 패치를 Linux ACPI 커뮤니티 검토에 보내기 전에는 이식 문제를 줄이기 위한 품질 보증 빌드 테스트를 수행합니다. 현재 이 빌드는 `CONFIG_ACPI`, `CONFIG_ACPI_DEBUG`, `CONFIG_ACPI_DEBUGGER` 커널 구성 옵션만 검사합니다.
ACPICA 차이점의 원인
188-231이상적으로는 모든 ACPICA 커밋을 수동 수정 없이 자동으로 Linux 패치로 변환해야 합니다. `linux/master` 트리는 `new linuxized acpica` 트리의 ACPICA 코드와 정확히 대응해야 하며 릴리스 과정 전체를 자동화할 수 있어야 합니다.
그러나 실제로는 Linux의 ACPICA 코드와 업스트림 ACPICA 코드 사이에 소스 차이가 존재하며, 이를 `ACPICA Divergences`라고 부릅니다.
1. 레거시 차이점: 현재 릴리스 과정이 확립되기 전부터 Linux와 ACPICA 사이에 차이가 있었습니다. 지난 여러 해 동안 크게 줄었지만 일부는 여전히 남아 있으며 존재 이유를 파악하는 데 시간이 필요합니다.
2. 수동 수정: Linux 소스에 코딩 스타일 수정 같은 변경을 직접 적용하면 ACPICA 릴리스 자동화가 훼손됩니다. 이런 문제는 ACPICA 업스트림 소스에서 고치고 ACPICA 릴리스 유틸리티로 linuxized 수정 패치를 생성하는 것이 좋습니다. 자세한 내용은 아래 4절을 참조하십시오.
3. Linux 고유 기능: Linux 커널이 요구하는 기능을 현재 ACPICA API로 구현할 수 없는 경우 Linux 개발자가 ACPICA 코드를 직접 변경하기도 합니다. ACPICA 업스트림이 받아들이지 않는 변경은 ACPICA 측에서 대체 메커니즘을 구현할 때까지 의도적으로 유지되는 차이점으로 남습니다.
4. ACPICA 릴리스 보정: ACPICA는 사용자 공간 시뮬레이션 유틸리티 집합으로만 커밋을 테스트하므로 linuxized 패치가 Linux 커널의 빌드나 부팅을 깨뜨릴 수 있습니다. Linux 이분 탐색을 보호하기 위해 릴리스 과정에서 linuxized 패치를 직접 고칩니다. 이 수정이 ACPICA 업스트림으로 역이식될 때는 업스트림 규칙을 따라야 하므로 추가 변경과 새로운 차이점이 생길 수 있습니다.
5. ACPICA 커밋의 빠른 반영: 일부 커밋은 회귀 수정이거나 stable 후보이므로 정규 ACPICA 릴리스보다 먼저 적용합니다. ACPICA 측에서 더 나은 해법을 제공하려고 해당 커밋을 되돌리거나 리베이스하면 새로운 차이점이 생깁니다.
개별 ACPICA 커밋 가져오기
232-253이 절은 Linux 개발자가 ACPICA 정규 릴리스 전에 업스트림 커밋에 대응하는 Linux 패치를 얻도록 ACPICA 업스트림 릴리스 유틸리티를 사용하는 방법을 안내합니다.
1. ACPICA 커밋 하나를 cherry-pick하려면 먼저 ACPICA 저장소를 복제하고, 가져올 ACPICA 변경이 로컬 저장소에 커밋되어 있어야 합니다. 그런 다음 `gen-patch.sh`로 해당 로컬 커밋을 변환합니다.
$ git clone https://github.com/acpica/acpica
$ cd acpica
$ generate/linux/gen-patch.sh -u [commit ID]`[commit ID]`는 가져올 ACPICA 로컬 저장소 커밋 ID입니다. 커밋이 `HEAD`라면 생략할 수 있습니다.
최근 ACPICA 커밋 묶음 가져오기
254-2702. 아직 Linux에 적용되지 않은 최신 ACPICA 변경 위에 코드를 리베이스해야 할 때는 ACPICA 릴리스 시리즈를 직접 생성하고 그 패치 위에 코드를 리베이스할 수 있습니다.
$ git clone https://github.com/acpica/acpica
$ cd acpica
$ generate/linux/make-patches.sh -u [commit ID]`[commit ID]`는 Linux가 마지막으로 수용한 ACPICA 커밋이어야 합니다. 보통 `ACPI_CA_VERSION`을 수정한 커밋이며, `git blame source/include/acpixf.h`를 실행해 `ACPI_CA_VERSION`이 있는 줄을 확인하면 찾을 수 있습니다.
현재 ACPICA 차이점 검사
271-2793. Linux와 업스트림 ACPICA의 로컬 복사본을 모두 갖고 있다면 다음 명령으로 현재 차이점 상태를 나타내는 diff 파일을 만들 수 있습니다.
# git clone https://github.com/acpica/acpica
# git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
# cd acpica
# generate/linux/divergence.sh -s ../linux
요약과 해설
linuxized-acpica.rst:1-279ACPICA와 Linux의 관계, linuxized 패치 생성 과정, 차이점의 원인과 업스트림 커밋 변환 절차를 설명합니다. 영어 원문 전체와 한국어 전문 번역을 함께 제공하며, directive, 명령, 심볼, 저장소 URL, 소스 경로와 원문 줄 좌표를 보존합니다.