요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0-only
.. Copyright 2024 Linaro Ltd.
====================
Power Sequencing API
====================
:Author: Bartosz Golaszewski
Introduction
============
This framework is designed to abstract complex power-up sequences that are
shared between multiple logical devices in the Linux kernel.
The intention is to allow consumers to obtain a power sequencing handle
exposed by the power sequence provider and delegate the actual requesting and
control of the underlying resources as well as to allow the provider to
mitigate any potential conflicts between multiple users behind the scenes.
Glossary
--------
The power sequencing API uses a number of terms specific to the subsystem:
Unit
A unit is a discrete chunk of a power sequence. For instance one unit may
enable a set of regulators, another may enable a specific GPIO. Units can
define dependencies in the form of other units that must be enabled before
it itself can be.
Target
A target is a set of units (composed of the "final" unit and its
dependencies) that a consumer selects by its name when requesting a handle
to the power sequencer. Via the dependency system, multiple targets may
share the same parts of a power sequence but ignore parts that are
irrelevant.
Descriptor
A handle passed by the pwrseq core to every consumer that serves as the
entry point to the provider layer. It ensures coherence between different
users and keeps reference counting consistent.
Consumer interface
==================
The consumer API is aimed to be as simple as possible. The driver interested in
getting a descriptor from the power sequencer should call pwrseq_get() and
specify the name of the target it wants to reach in the sequence after calling
pwrseq_power_up(). The descriptor can be released by calling pwrseq_put() and
the consumer can request the powering down of its target with
pwrseq_power_off(). Note that there is no guarantee that pwrseq_power_off()
will have any effect as there may be multiple users of the underlying resources
who may keep them active.
Provider interface
==================
The provider API is admittedly not nearly as straightforward as the one for
consumers but it makes up for it in flexibility.
Each provider can logically split the power-up sequence into discrete chunks
(units) and define their dependencies. They can then expose named targets that
consumers may use as the final point in the sequence that they wish to reach.
To that end the providers fill out a set of configuration structures and
register with the pwrseq subsystem by calling pwrseq_device_register().
Dynamic consumer matching
-------------------------
The main difference between pwrseq and other Linux kernel providers is the
mechanism for dynamic matching of consumers and providers. Every power sequence
provider driver must implement the `match()` callback and pass it to the pwrseq
core when registering with the subsystems.
When a client requests a sequencer handle, the core will call this callback for
every registered provider and let it flexibly figure out whether the proposed
client device is indeed its consumer. For example: if the provider binds to the
device-tree node representing a power management unit of a chipset and the
consumer driver controls one of its modules, the provider driver may parse the
relevant regulator supply properties in device tree and see if they lead from
the PMU to the consumer.
API reference
=============
.. kernel-doc:: include/linux/pwrseq/provider.h
:internal:
.. kernel-doc:: drivers/power/sequencing/core.c
:export:
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Power Sequencing API 문서 정보
1-9이 문서는 Linux kernel의 Power Sequencing API를 설명합니다. SPDX license는 `GPL-2.0-only`이며 2024년 Linaro Ltd. 저작물입니다. 저자는 Bartosz Golaszewski입니다.
.. SPDX-License-Identifier: GPL-2.0-only
.. Copyright 2024 Linaro Ltd.
====================
Power Sequencing API
====================
:Author: Bartosz Golaszewski
공유 power-up sequence 추상화
10-20Power sequencing framework는 Linux kernel에서 여러 logical device가 공유하는 복잡한 power-up sequence를 추상화하도록 설계되었습니다.
Consumer는 power sequence provider가 노출한 sequencing handle을 얻습니다. 실제 underlying resource의 요청과 제어는 provider에 위임하므로 consumer driver가 regulator, GPIO 같은 resource의 세부 순서를 직접 관리하지 않아도 됩니다.
Provider는 여러 사용자가 같은 resource를 공유할 때 생길 수 있는 conflict를 내부에서 완화합니다. 이 구조는 sequence 구현과 consumer 사용 방식을 분리하면서도 shared resource의 일관성을 유지합니다.
Consumer는 목표만 요청하고 provider가 실제 resource 순서와 공유 충돌을 처리합니다.
Introduction
============
This framework is designed to abstract complex power-up sequences that are
shared between multiple logical devices in the Linux kernel.
The intention is to allow consumers to obtain a power sequencing handle
exposed by the power sequence provider and delegate the actual requesting and
control of the underlying resources as well as to allow the provider to
mitigate any potential conflicts between multiple users behind the scenes.
Unit, Target, Descriptor
21-46Unit은 power sequence를 이루는 독립적인 조각입니다. 한 unit은 regulator 집합을 활성화하고 다른 unit은 특정 GPIO를 활성화할 수 있습니다. 각 unit은 자신보다 먼저 활성화되어야 하는 다른 unit을 dependency로 정의할 수 있습니다.
Target은 consumer가 power sequencer handle을 요청할 때 이름으로 선택하는 unit 집합입니다. 선택한 final unit과 그 dependency 전체가 target을 구성합니다. Dependency system을 사용하면 여러 target이 sequence의 공통 부분을 공유하면서 관련 없는 부분은 제외할 수 있습니다.
Descriptor는 pwrseq core가 각 consumer에 전달하는 handle이며 provider layer의 entry point입니다. 서로 다른 사용자 사이의 coherence를 보장하고 reference counting을 일관되게 유지합니다.
Dependency를 따라 unit 집합이 target을 이루고 descriptor가 consumer와 provider를 연결합니다.
Glossary
--------
The power sequencing API uses a number of terms specific to the subsystem:
Unit
A unit is a discrete chunk of a power sequence. For instance one unit may
enable a set of regulators, another may enable a specific GPIO. Units can
define dependencies in the form of other units that must be enabled before
it itself can be.
Target
A target is a set of units (composed of the "final" unit and its
dependencies) that a consumer selects by its name when requesting a handle
to the power sequencer. Via the dependency system, multiple targets may
share the same parts of a power sequence but ignore parts that are
irrelevant.
Descriptor
A handle passed by the pwrseq core to every consumer that serves as the
entry point to the provider layer. It ensures coherence between different
users and keeps reference counting consistent.
Consumer interface와 공유 resource
47-58Consumer API는 가능한 한 단순하게 설계되었습니다. Power sequencer descriptor가 필요한 driver는 `pwrseq_get()`을 호출하면서 도달하려는 target 이름을 지정하고, `pwrseq_power_up()`으로 그 target까지 sequence를 활성화합니다.
Descriptor는 `pwrseq_put()`으로 해제합니다. Consumer는 `pwrseq_power_off()`으로 자신의 target 전원 차단을 요청할 수 있습니다.
하지만 `pwrseq_power_off()`가 실제 resource를 비활성화한다고 보장되지는 않습니다. 같은 underlying resource를 사용하는 다른 consumer가 남아 있으면 reference counting과 coherence를 위해 resource가 계속 active 상태로 유지될 수 있습니다.
Target 요청과 descriptor 수명은 분리되며 power-off는 공유 reference에 따라 결정됩니다.
Consumer interface
==================
The consumer API is aimed to be as simple as possible. The driver interested in
getting a descriptor from the power sequencer should call pwrseq_get() and
specify the name of the target it wants to reach in the sequence after calling
pwrseq_power_up(). The descriptor can be released by calling pwrseq_put() and
the consumer can request the powering down of its target with
pwrseq_power_off(). Note that there is no guarantee that pwrseq_power_off()
will have any effect as there may be multiple users of the underlying resources
who may keep them active.
Provider interface와 sequence 구성
59-71Provider API는 consumer API보다 복잡하지만 그만큼 유연합니다. Provider는 power-up sequence를 discrete unit으로 논리적으로 나누고 unit 사이의 dependency를 정의합니다.
그다음 consumer가 sequence에서 도달할 final point로 사용할 named target을 노출합니다. 동일한 unit graph 위에서 여러 target을 제공할 수 있으므로 공통 resource와 target별 resource를 함께 표현할 수 있습니다.
Provider는 필요한 configuration structure 집합을 채우고 `pwrseq_device_register()`를 호출해 pwrseq subsystem에 등록합니다.
Unit graph와 named target을 configuration으로 기술한 뒤 subsystem에 등록합니다.
Provider interface
==================
The provider API is admittedly not nearly as straightforward as the one for
consumers but it makes up for it in flexibility.
Each provider can logically split the power-up sequence into discrete chunks
(units) and define their dependencies. They can then expose named targets that
consumers may use as the final point in the sequence that they wish to reach.
To that end the providers fill out a set of configuration structures and
register with the pwrseq subsystem by calling pwrseq_device_register().
Dynamic consumer-provider matching
72-87Pwrseq와 다른 Linux kernel provider framework의 핵심 차이는 consumer와 provider를 동적으로 matching하는 mechanism입니다. 모든 power sequence provider driver는 `match()` callback을 구현하고 subsystem 등록 시 pwrseq core에 전달해야 합니다.
Client가 sequencer handle을 요청하면 core는 등록된 모든 provider에 대해 이 callback을 호출합니다. 각 provider는 제안된 client device가 자신의 consumer인지 유연하게 판정합니다.
예를 들어 provider가 chipset의 power management unit을 나타내는 device-tree node에 bind되고 consumer driver가 chipset module 하나를 제어할 수 있습니다. Provider driver는 device tree의 관련 regulator supply property를 해석해 PMU에서 consumer로 이어지는지 확인할 수 있습니다.
Core가 모든 provider의 match callback을 호출하고 provider별 topology 지식으로 consumer를 판정합니다.
Dynamic consumer matching
-------------------------
The main difference between pwrseq and other Linux kernel providers is the
mechanism for dynamic matching of consumers and providers. Every power sequence
provider driver must implement the `match()` callback and pass it to the pwrseq
core when registering with the subsystems.
When a client requests a sequencer handle, the core will call this callback for
every registered provider and let it flexibly figure out whether the proposed
client device is indeed its consumer. For example: if the provider binds to the
device-tree node representing a power management unit of a chipset and the
consumer driver controls one of its modules, the provider driver may parse the
relevant regulator supply properties in device tree and see if they lead from
the PMU to the consumer.
Kernel API reference
88-95API reference는 kernel-doc directive 두 개로 구성됩니다. Provider 정의는 `include/linux/pwrseq/provider.h`에서 internal symbol까지 포함해 가져옵니다.
Core implementation의 exported API는 `drivers/power/sequencing/core.c`에서 가져옵니다. Header의 provider contract와 core의 consumer-facing export를 함께 확인할 수 있습니다.
API reference
=============
.. kernel-doc:: include/linux/pwrseq/provider.h
:internal:
.. kernel-doc:: drivers/power/sequencing/core.c
:export:
요약과 해설
pwrseq.rst:1-95Pwrseq framework는 여러 logical device가 공유하는 복잡한 power-up sequence를 dependency unit과 named target으로 표현합니다. Consumer는 descriptor를 통해 target만 요청하고 provider가 실제 resource 순서, reference counting과 conflict를 관리합니다. Provider 선택은 각 provider의 `match()` callback을 모든 후보에 적용하는 동적 방식입니다.