요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
SoC별 maintainer와 main SoC maintainer
maintainer-soc.rst:55-92먼저 MAINTAINERS의 platform submaintainer와 list에 patch를 보내 review·queue한다. 여러 platform을 걸치거나 common SoC layer를 바꾸는 patch, submaintainer가 없는 platform은 main SoC maintainer와 조정한다.
새 submaintainer는 public review, stable branch 관리, regression 대응과 주기적인 pull request를 책임진다. 단순 patch 전달이 아니라 tree quality와 contributor feedback을 유지한다.
Devicetree ABI 안정성
maintainer-soc.rst:93-106Released DTB가 새 kernel에서도 동작해야 하므로 binding과 property semantics는 ABI다. Driver와 DTS를 동시에 바꿀 수 있다는 가정으로 incompatible property를 재정의하지 않고 새 optional property와 fallback으로 확장한다.
Driver branch dependency를 최소화
maintainer-soc.rst:107-139DTS가 아직 mainline에 없는 driver symbol이나 binding에 hard dependency를 만들면 tree merge 순서가 꼬인다. 가능한 경우 DTS와 driver를 독립적으로 merge 가능하게 설계하고 반드시 필요한 dependency는 immutable branch와 maintainer agreement로 해결한다.
DTS file naming과 validation
maintainer-soc.rst:140-172DTS·DTSI file은 vendor, SoC와 board를 일관된 lowercase naming으로 표현해 검색과 build target을 예측할 수 있게 한다. Compatible, node name, unit-address와 property를 binding schema에 맞추고 dtbs_check를 실행한다.
Branch와 pull request
maintainer-soc.rst:173-210Fix, DT, driver·soc와 defconfig 성격을 branch로 분리해 upstream merge와 stable backport가 명확하게 한다. Pull request는 signed tag, base, high-level summary, noteworthy dependency와 test status를 포함하고 merge window 전에 충분한 integration 시간을 둔다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
=============
SoC Subsystem
=============
Overview
--------
The SoC subsystem is a place of aggregation for SoC-specific code.
The main components of the subsystem are:
* devicetrees (DTS) for 32- & 64-bit ARM and RISC-V
* 32-bit ARM board files (arch/arm/mach*)
* 32- & 64-bit ARM defconfigs
* SoC-specific drivers across architectures, in particular for 32- & 64-bit
ARM, RISC-V and Loongarch
These "SoC-specific drivers" do not include clock, GPIO etc drivers that have
other top-level maintainers. The drivers/soc/ directory is generally meant
for kernel-internal drivers that are used by other drivers to provide SoC-
specific functionality like identifying an SoC revision or interfacing with
power domains.
The SoC subsystem also serves as an intermediate location for changes to
drivers/bus, drivers/firmware, drivers/reset and drivers/memory. The addition
of new platforms, or the removal of existing ones, often go through the SoC
tree as a dedicated branch covering multiple subsystems.
The main SoC tree is housed on git.kernel.org:
https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/
Maintainers
-----------
Clearly this is quite a wide range of topics, which no one person, or even
small group of people are capable of maintaining. Instead, the SoC subsystem
is comprised of many submaintainers (platform maintainers), each taking care of
individual platforms and driver subdirectories.
In this regard, "platform" usually refers to a series of SoCs from a given
vendor, for example, Nvidia's series of Tegra SoCs. Many submaintainers operate
on a vendor level, responsible for multiple product lines. For several reasons,
including acquisitions/different business units in a company, things vary
significantly here. The various submaintainers are documented in the
MAINTAINERS file.
Most of these submaintainers have their own trees where they stage patches,
sending pull requests to the main SoC tree. These trees are usually, but not
always, listed in MAINTAINERS.
What the SoC tree is not, however, is a location for architecture-specific code
changes. Each architecture has its own maintainers that are responsible for
architectural details, CPU errata and the like.
Submitting Patches for Given SoC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All typical platform related patches should be sent via SoC submaintainers
(platform-specific maintainers). This includes also changes to per-platform or
shared defconfigs (scripts/get_maintainer.pl might not provide correct
addresses in such case).
Submitting Patches to the Main SoC Maintainers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The main SoC maintainers can be reached via the alias soc@kernel.org only in
following cases:
1. There are no platform-specific maintainers.
2. Platform-specific maintainers are unresponsive.
3. Introducing a completely new SoC platform. Such new SoC work should be sent
first to common mailing lists, pointed out by scripts/get_maintainer.pl, for
community review. After positive community review, work should be sent to
soc@kernel.org in one patchset containing new arch/foo/Kconfig entry, DTS
files, MAINTAINERS file entry and optionally initial drivers with their
Devicetree bindings. The MAINTAINERS file entry should list new
platform-specific maintainers, who are going to be responsible for handling
patches for the platform from now on.
Note that the soc@kernel.org is usually not the place to discuss the patches,
thus work sent to this address should be already considered as acceptable by
the community.
Information for (new) Submaintainers
------------------------------------
As new platforms spring up, they often bring with them new submaintainers,
many of whom work for the silicon vendor, and may not be familiar with the
process.
Devicetree ABI Stability
~~~~~~~~~~~~~~~~~~~~~~~~
Perhaps one of the most important things to highlight is that dt-bindings
document the ABI between the devicetree and the kernel.
Please read Documentation/devicetree/bindings/ABI.rst.
If changes are being made to a DTS that are incompatible with old
kernels, the DTS patch should not be applied until the driver is, or an
appropriate time later. Most importantly, any incompatible changes should be
clearly pointed out in the patch description and pull request, along with the
expected impact on existing users, such as bootloaders or other operating
systems.
Driver Branch Dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~
A common problem is synchronizing changes between device drivers and devicetree
files. Even if a change is compatible in both directions, this may require
coordinating how the changes get merged through different maintainer trees.
Usually the branch that includes a driver change will also include the
corresponding change to the devicetree binding description, to ensure they are
in fact compatible. This means that the devicetree branch can end up causing
warnings in the "make dtbs_check" step. If a devicetree change depends on
missing additions to a header file in include/dt-bindings/, it will fail the
"make dtbs" step and not get merged.
There are multiple ways to deal with this:
* Avoid defining custom macros in include/dt-bindings/ for hardware constants
that can be derived from a datasheet -- binding macros in header files should
only be used as a last resort if there is no natural way to define a binding
* Use literal values in the devicetree file in place of macros even when a
header is required, and change them to the named representation in a
following release
* Defer the devicetree changes to a release after the binding and driver have
already been merged
* Change the bindings in a shared immutable branch that is used as the base for
both the driver change and the devicetree changes
* Add duplicate defines in the devicetree file guarded by an #ifndef section,
removing them in a later release
Devicetree Naming Convention
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The general naming scheme for devicetree files is as follows. The aspects of a
platform that are set at the SoC level, like CPU cores, are contained in a file
named $soc.dtsi, for example, jh7100.dtsi. Integration details, that will vary
from board to board, are described in $soc-$board.dts. An example of this is
jh7100-beaglev-starlight.dts. Often many boards are variations on a theme, and
frequently there are intermediate files, such as jh7100-common.dtsi, which sit
between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of
common hardware.
Some platforms also have System on Modules, containing an SoC, which are then
integrated into several different boards. For these platforms, $soc-$som.dtsi
and $soc-$som-$board.dts are typical.
Directories are usually named after the vendor of the SoC at the time of its
inclusion, leading to some historical directory names in the tree.
Validating Devicetree Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~
``make dtbs_check`` can be used to validate that devicetree files are compliant
with the dt-bindings that describe the ABI. Please read the section
"Running checks" of Documentation/devicetree/bindings/writing-schema.rst for
more information on the validation of devicetrees.
For new platforms, or additions to existing ones, ``make dtbs_check`` should not
add any new warnings. For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is
required to not add any new warnings.
If in any doubt about a devicetree change, reach out to the devicetree
maintainers.
Branches and Pull Requests
~~~~~~~~~~~~~~~~~~~~~~~~~~
Just as the main SoC tree has several branches, it is expected that
submaintainers will do the same. Driver, defconfig and devicetree changes should
all be split into separate branches and appear in separate pull requests to the
SoC maintainers. Each branch should be usable by itself and avoid
regressions that originate from dependencies on other branches.
Small sets of patches can also be sent as separate emails to soc@kernel.org,
grouped into the same categories.
If changes do not fit into the normal patterns, there can be additional
top-level branches, e.g. for a treewide rework, or the addition of new SoC
platforms including dts files and drivers.
Branches with a lot of changes can benefit from getting split up into separate
topics branches, even if they end up getting merged into the same branch of the
SoC tree. An example here would be one branch for devicetree warning fixes, one
for a rework and one for newly added boards.
Another common way to split up changes is to send an early pull request with the
majority of the changes at some point between rc1 and rc4, following up with one
or more smaller pull requests towards the end of the cycle that can add late
changes or address problems identified while testing the first set.
While there is no cut-off time for late pull requests, it helps to only send
small branches as time gets closer to the merge window.
Pull requests for bugfixes for the current release can be sent at any time, but
again having multiple smaller branches is better than trying to combine too many
patches into one pull request.
The subject line of a pull request should begin with "[GIT PULL]" and made using
a signed tag, rather than a branch. This tag should contain a short description
summarising the changes in the pull request. For more detail on sending pull
requests, please see Documentation/maintainer/pull-requests.rst.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
SoC subsystem의 범위
1-31SoC subsystem은 SoC-specific code를 모으는 통합 지점이다. Main tree는 https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/ 에 있다.
- 32-bit와 64-bit ARM 및 RISC-V devicetree(DTS)
- 32-bit ARM board file인 arch/arm/mach*
- 32-bit와 64-bit ARM defconfig
- 특히 ARM, RISC-V, LoongArch를 포함한 architecture별 SoC-specific driver
Clock, GPIO처럼 별도 top-level maintainer가 있는 driver는 여기서 말하는 SoC-specific driver에 포함하지 않는다. drivers/soc/는 SoC revision 식별이나 power domain interface처럼 다른 driver에 SoC-specific 기능을 제공하는 kernel 내부 driver를 위한 곳이다.
drivers/bus, drivers/firmware, drivers/reset, drivers/memory 변경도 SoC subsystem을 중간 통합 지점으로 사용할 수 있다. 새 platform 추가나 기존 platform 제거는 여러 subsystem을 묶는 전용 SoC branch로 진행되는 경우가 많다.
Platform submaintainer 구조
33-53범위가 넓어 한 사람이나 작은 집단이 모두 관리할 수 없으므로 SoC subsystem은 platform별 또는 driver subdirectory별 submaintainer로 구성된다. Platform은 보통 Nvidia Tegra처럼 한 vendor의 SoC series를 뜻하지만 인수합병과 business unit 차이 때문에 실제 경계는 다양하다.
Submaintainer 목록은 MAINTAINERS file에 기록한다. 대부분은 patch를 staging하는 자체 tree를 갖고 main SoC tree로 pull request를 보내며, 이 tree도 보통 MAINTAINERS에 기록된다.
SoC tree는 architecture-specific code 변경을 모으는 곳이 아니다. Architecture detail과 CPU errata는 각 architecture maintainer가 담당한다.
기존 platform patch 제출
55-61일반적인 platform patch는 platform-specific SoC submaintainer를 통해 제출한다. Platform별 또는 여러 platform이 공유하는 defconfig 변경도 포함한다. 이 경우 scripts/get_maintainer.pl이 올바른 주소를 모두 찾지 못할 수 있으므로 MAINTAINERS를 직접 확인한다.
soc@kernel.org로 직접 보낼 수 있는 경우
63-84- Platform-specific maintainer가 없다.
- Platform-specific maintainer가 응답하지 않는다.
- 완전히 새로운 SoC platform을 도입한다.
새 platform은 scripts/get_maintainer.pl이 안내하는 공통 mailing list에 먼저 보내 community review를 받는다. 긍정적인 review 뒤 arch/foo/Kconfig entry, DTS file, MAINTAINERS entry, 필요하면 초기 driver와 Devicetree binding을 하나의 patchset으로 묶어 soc@kernel.org로 보낸다.
MAINTAINERS entry에는 이후 platform patch를 담당할 새 platform-specific maintainer를 적는다. soc@kernel.org는 보통 patch를 처음 논의하는 장소가 아니므로 이 주소로 보낼 때는 community가 이미 받아들일 수 있다고 판단한 상태여야 한다.
Devicetree ABI 안정성
86-105새 platform과 함께 silicon vendor 소속 submaintainer가 처음 참여하는 경우가 많다. 특히 중요한 원칙은 dt-binding이 Devicetree와 kernel 사이 ABI를 문서화한다는 점이다. Documentation/devicetree/bindings/ABI.rst를 읽어야 한다.
옛 kernel과 호환되지 않는 DTS 변경은 대응 driver가 merge되기 전에는 적용하지 않고 필요하면 그보다 더 늦춘다. Incompatible change는 patch description과 pull request에 명확히 밝히고 bootloader와 다른 운영체제를 포함한 기존 user에게 미칠 영향을 설명한다.
Driver branch와 Devicetree dependency
107-139Device driver와 Devicetree file 변경을 서로 다른 maintainer tree에서 merge할 때 동기화가 자주 문제 된다. 양방향 호환 변경이어도 merge 순서를 조정해야 할 수 있다.
Driver 변경 branch에는 실제 호환성을 보장하기 위해 대응 binding description 변경도 함께 넣는 경우가 많다. 그러면 binding이 없는 Devicetree branch는 make dtbs_check warning을 낼 수 있다. include/dt-bindings/의 header 추가가 없으면 make dtbs 자체가 실패해 merge되지 않는다.
- Datasheet에서 얻을 수 있는 hardware constant는 include/dt-bindings/ custom macro로 정의하지 않는다. Natural binding 표현이 없을 때만 마지막 수단으로 header macro를 쓴다.
- Header가 필요해도 Devicetree file에서는 먼저 literal value를 쓰고 다음 release에서 named macro로 바꾼다.
- Binding과 driver가 merge된 다음 release까지 Devicetree 변경을 미룬다.
- Binding 변경을 shared immutable branch에 두고 driver branch와 Devicetree branch가 모두 이를 base로 사용한다.
- Devicetree file에 #ifndef로 보호한 duplicate define을 임시로 추가하고 다음 release에서 제거한다.
Devicetree file naming convention
140-157CPU core처럼 SoC 수준에서 정해지는 내용은 $soc.dtsi에 둔다. 예는 jh7100.dtsi다. Board마다 달라지는 integration detail은 $soc-$board.dts에 두며 jh7100-beaglev-starlight.dts가 예다.
비슷한 board가 여러 개면 $soc.dtsi와 $soc-$board.dts 사이에 jh7100-common.dtsi 같은 intermediate file을 두어 공통 hardware를 설명한다.
SoC를 포함한 System on Module을 여러 board에 결합하는 platform은 보통 $soc-$som.dtsi와 $soc-$som-$board.dts 이름을 사용한다. Directory 이름은 platform이 처음 포함된 시점의 SoC vendor를 따르므로 historical name이 남을 수 있다.
Devicetree validation
159-171make dtbs_check로 Devicetree file이 ABI를 설명하는 dt-binding을 준수하는지 검사한다. 자세한 절차는 Documentation/devicetree/bindings/writing-schema.rst의 Running checks 절을 참고한다.
새 platform과 기존 platform 추가는 make dtbs_check에서 새 warning을 만들지 않아야 한다. RISC-V와 Samsung SoC는 make dtbs_check W=1 기준으로도 새 warning이 없어야 한다. 확신이 없으면 Devicetree maintainer에게 문의한다.
Branch와 pull request 분리
173-200Main SoC tree와 마찬가지로 submaintainer도 여러 branch를 사용한다. Driver, defconfig, Devicetree 변경은 각각 별도 branch와 별도 pull request로 SoC maintainer에게 보낸다. 각 branch는 다른 branch dependency 때문에 regression을 만들지 않고 독립적으로 사용할 수 있어야 한다.
작은 patch 묶음은 같은 category로 모아 soc@kernel.org에 별도 email로 보낼 수 있다. Treewide rework나 DTS와 driver를 함께 포함하는 새 SoC platform처럼 일반 category에 맞지 않는 변경에는 추가 top-level branch를 만들 수 있다.
변경이 많으면 최종적으로 같은 SoC branch에 merge되더라도 topic branch로 나누는 것이 좋다. 예를 들어 Devicetree warning fix, 구조 개편, 새 board를 각각 분리한다.
rc1과 rc4 사이에 대부분의 변경을 담은 early pull request를 보내고 cycle 후반에 late change나 test에서 발견한 문제를 고치는 작은 follow-up pull request를 보내는 방식도 흔하다. Late pull request의 절대 cut-off는 없지만 merge window가 가까울수록 작은 branch만 보내는 것이 좋다.
Bugfix와 signed-tag pull request
202-209Current release bugfix pull request는 언제든 보낼 수 있지만 너무 많은 patch를 하나에 묶기보다 여러 작은 branch로 나누는 편이 낫다.
Pull request subject는 [GIT PULL]로 시작하고 branch가 아니라 signed tag를 사용한다. Tag message에는 pull request 변경을 짧게 요약한다. 자세한 내용은 Documentation/maintainer/pull-requests.rst를 참고한다.
SoC tree가 다루는 변경
maintainer-soc.rst:4-54SoC subsystem은 architecture platform code, Devicetree, defconfig와 cross-platform SoC 변경을 architecture maintainer와 arm-soc 계층을 통해 통합한다. 개별 driver subsystem이 명확한 변경은 해당 driver maintainer로 보내고 SoC tree가 불필요하게 중계하지 않는다.