요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. Copyright 2007-2008 Wolfson Microelectronics
.. This documentation is free software; you can redistribute
.. it and/or modify it under the terms of the GNU General Public
.. License version 2 as published by the Free Software Foundation.
=================================
Voltage and current regulator API
=================================
:Author: Liam Girdwood
:Author: Mark Brown
Introduction
============
This framework is designed to provide a standard kernel interface to
control voltage and current regulators.
The intention is to allow systems to dynamically control regulator power
output in order to save power and prolong battery life. This applies to
both voltage regulators (where voltage output is controllable) and
current sinks (where current limit is controllable).
Note that additional (and currently more complete) documentation is
available in the Linux kernel source under
``Documentation/power/regulator``.
Glossary
--------
The regulator API uses a number of terms which may not be familiar:
Regulator
Electronic device that supplies power to other devices. Most regulators
can enable and disable their output and some can also control their
output voltage or current.
Consumer
Electronic device which consumes power provided by a regulator. These
may either be static, requiring only a fixed supply, or dynamic,
requiring active management of the regulator at runtime.
Power Domain
The electronic circuit supplied by a given regulator, including the
regulator and all consumer devices. The configuration of the regulator
is shared between all the components in the circuit.
Power Management Integrated Circuit (PMIC)
An IC which contains numerous regulators and often also other
subsystems. In an embedded system the primary PMIC is often equivalent
to a combination of the PSU and southbridge in a desktop system.
Consumer driver interface
=========================
This offers a similar API to the kernel clock framework. Consumer
drivers use `get <#API-regulator-get>`__ and
`put <#API-regulator-put>`__ operations to acquire and release
regulators. Functions are provided to `enable <#API-regulator-enable>`__
and `disable <#API-regulator-disable>`__ the regulator and to get and
set the runtime parameters of the regulator.
When requesting regulators consumers use symbolic names for their
supplies, such as "Vcc", which are mapped into actual regulator devices
by the machine interface.
A stub version of this API is provided when the regulator framework is
not in use in order to minimise the need to use ifdefs.
Enabling and disabling
----------------------
The regulator API provides reference counted enabling and disabling of
regulators. Consumer devices use the :c:func:`regulator_enable()` and
:c:func:`regulator_disable()` functions to enable and disable
regulators. Calls to the two functions must be balanced.
Note that since multiple consumers may be using a regulator and machine
constraints may not allow the regulator to be disabled there is no
guarantee that calling :c:func:`regulator_disable()` will actually
cause the supply provided by the regulator to be disabled. Consumer
drivers should assume that the regulator may be enabled at all times.
Configuration
-------------
Some consumer devices may need to be able to dynamically configure their
supplies. For example, MMC drivers may need to select the correct
operating voltage for their cards. This may be done while the regulator
is enabled or disabled.
The :c:func:`regulator_set_voltage()` and
:c:func:`regulator_set_current_limit()` functions provide the primary
interface for this. Both take ranges of voltages and currents, supporting
drivers that do not require a specific value (eg, CPU frequency scaling
normally permits the CPU to use a wider range of supply voltages at lower
frequencies but does not require that the supply voltage be lowered). Where
an exact value is required both minimum and maximum values should be
identical.
Callbacks
---------
Callbacks may also be registered for events such as regulation failures.
Regulator driver interface
==========================
Drivers for regulator chips register the regulators with the regulator
core, providing operations structures to the core. A notifier interface
allows error conditions to be reported to the core.
Registration should be triggered by explicit setup done by the platform,
supplying a struct regulator_init_data for the regulator
containing constraint and supply information.
Machine interface
=================
This interface provides a way to define how regulators are connected to
consumers on a given system and what the valid operating parameters are
for the system.
Supplies
--------
Regulator supplies are specified using struct
:c:type:`regulator_consumer_supply`. This is done at driver registration
time as part of the machine constraints.
Constraints
-----------
As well as defining the connections the machine interface also provides
constraints defining the operations that clients are allowed to perform
and the parameters that may be set. This is required since generally
regulator devices will offer more flexibility than it is safe to use on
a given system, for example supporting higher supply voltages than the
consumers are rated for.
This is done at driver registration time` by providing a
struct regulation_constraints.
The constraints may also specify an initial configuration for the
regulator in the constraints, which is particularly useful for use with
static consumers.
API reference
=============
Due to limitations of the kernel documentation framework and the
existing layout of the source code the entire regulator API is
documented here.
.. kernel-doc:: include/linux/regulator/consumer.h
:internal:
.. kernel-doc:: include/linux/regulator/machine.h
:internal:
.. kernel-doc:: include/linux/regulator/driver.h
:internal:
.. kernel-doc:: drivers/regulator/core.c
:export:
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Voltage·current regulator API 문서 정보
1-13이 문서는 2007–2008 Wolfson Microelectronics 저작물이며 GNU General Public License version 2 조건으로 재배포하거나 수정할 수 있습니다.
Voltage and current regulator API 문서의 저자는 Liam Girdwood와 Mark Brown입니다.
.. Copyright 2007-2008 Wolfson Microelectronics
.. This documentation is free software; you can redistribute
.. it and/or modify it under the terms of the GNU General Public
.. License version 2 as published by the Free Software Foundation.
=================================
Voltage and current regulator API
=================================
:Author: Liam Girdwood
:Author: Mark Brown
Framework 목적
14-28Regulator framework는 voltage regulator와 current regulator를 제어하는 표준 kernel interface를 제공합니다.
System이 regulator power output을 동적으로 제어해 전력을 절약하고 battery life를 연장하는 것이 목적입니다. Voltage regulator에서는 output voltage를, current sink에서는 current limit을 제어합니다.
추가로 더 완전한 문서는 Linux kernel source의 `Documentation/power/regulator` 아래에 있습니다.
Consumer 요구를 표준 API로 변환해 voltage 또는 current output을 동적으로 제어합니다.
Introduction
============
This framework is designed to provide a standard kernel interface to
control voltage and current regulators.
The intention is to allow systems to dynamically control regulator power
output in order to save power and prolong battery life. This applies to
both voltage regulators (where voltage output is controllable) and
current sinks (where current limit is controllable).
Note that additional (and currently more complete) documentation is
available in the Linux kernel source under
``Documentation/power/regulator``.
Regulator subsystem 용어
29-57Regulator는 다른 device에 power를 공급하는 electronic device입니다. 대부분 output을 enable·disable할 수 있고 일부는 output voltage 또는 current도 제어합니다.
Consumer는 regulator가 제공하는 power를 사용하는 electronic device입니다. 고정 supply만 필요한 static consumer와 runtime에서 regulator를 적극 관리해야 하는 dynamic consumer가 있습니다.
Power Domain은 특정 regulator가 공급하는 electronic circuit 전체이며 regulator와 모든 consumer device를 포함합니다. Regulator configuration은 회로의 모든 component가 공유합니다.
Power Management Integrated Circuit(PMIC)은 여러 regulator와 종종 다른 subsystem까지 포함하는 IC입니다. Embedded system의 primary PMIC는 desktop system의 PSU와 southbridge를 합친 역할에 가까운 경우가 많습니다.
Glossary
--------
The regulator API uses a number of terms which may not be familiar:
Regulator
Electronic device that supplies power to other devices. Most regulators
can enable and disable their output and some can also control their
output voltage or current.
Consumer
Electronic device which consumes power provided by a regulator. These
may either be static, requiring only a fixed supply, or dynamic,
requiring active management of the regulator at runtime.
Power Domain
The electronic circuit supplied by a given regulator, including the
regulator and all consumer devices. The configuration of the regulator
is shared between all the components in the circuit.
Power Management Integrated Circuit (PMIC)
An IC which contains numerous regulators and often also other
subsystems. In an embedded system the primary PMIC is often equivalent
to a combination of the PSU and southbridge in a desktop system.
Consumer driver interface
58-74Consumer interface는 kernel clock framework와 유사합니다. Consumer driver는 `regulator_get()`과 `regulator_put()` operation으로 regulator를 획득하고 해제하며, `regulator_enable()`·`regulator_disable()`과 runtime parameter 조회·설정 function을 사용합니다.
Consumer가 regulator를 요청할 때 `Vcc` 같은 symbolic supply name을 사용합니다. Machine interface가 이 name을 실제 regulator device에 mapping합니다.
Regulator framework를 사용하지 않는 configuration에서도 ifdef 사용을 최소화하도록 stub API가 제공됩니다.
Symbolic supply name을 machine mapping으로 실제 regulator에 연결합니다.
Consumer driver interface
=========================
This offers a similar API to the kernel clock framework. Consumer
drivers use `get <#API-regulator-get>`__ and
`put <#API-regulator-put>`__ operations to acquire and release
regulators. Functions are provided to `enable <#API-regulator-enable>`__
and `disable <#API-regulator-disable>`__ the regulator and to get and
set the runtime parameters of the regulator.
When requesting regulators consumers use symbolic names for their
supplies, such as "Vcc", which are mapped into actual regulator devices
by the machine interface.
A stub version of this API is provided when the regulator framework is
not in use in order to minimise the need to use ifdefs.
Reference-counted enable·disable
75-88Regulator API의 enable과 disable은 reference counted입니다. Consumer는 `regulator_enable()`과 `regulator_disable()`을 사용하며 두 function의 호출 수는 균형을 맞춰야 합니다.
여러 consumer가 regulator를 함께 사용하거나 machine constraint가 disable을 허용하지 않을 수 있으므로 `regulator_disable()` 호출이 실제 supply 차단으로 이어진다는 보장은 없습니다.
Consumer driver는 regulator가 항상 enable 상태일 수 있다고 가정해야 합니다.
한 consumer의 disable 요청만으로 shared supply가 꺼지지 않을 수 있습니다.
Enabling and disabling
----------------------
The regulator API provides reference counted enabling and disabling of
regulators. Consumer devices use the :c:func:`regulator_enable()` and
:c:func:`regulator_disable()` functions to enable and disable
regulators. Calls to the two functions must be balanced.
Note that since multiple consumers may be using a regulator and machine
constraints may not allow the regulator to be disabled there is no
guarantee that calling :c:func:`regulator_disable()` will actually
cause the supply provided by the regulator to be disabled. Consumer
drivers should assume that the regulator may be enabled at all times.
Dynamic voltage·current configuration
89-105일부 consumer는 supply를 동적으로 설정해야 합니다. 예를 들어 MMC driver는 card에 맞는 operating voltage를 선택해야 하며 regulator가 enable 또는 disable 상태일 때 모두 설정할 수 있습니다.
주요 interface는 `regulator_set_voltage()`와 `regulator_set_current_limit()`입니다. 두 function 모두 voltage 또는 current의 허용 range를 받으므로 정확한 단일 값을 요구하지 않는 driver를 지원합니다.
예를 들어 CPU frequency scaling은 낮은 frequency에서 더 넓은 supply voltage range를 허용할 수 있지만 반드시 voltage를 낮추라고 요구하지는 않습니다. 정확한 값이 필요하면 minimum과 maximum을 동일하게 지정합니다.
Configuration
-------------
Some consumer devices may need to be able to dynamically configure their
supplies. For example, MMC drivers may need to select the correct
operating voltage for their cards. This may be done while the regulator
is enabled or disabled.
The :c:func:`regulator_set_voltage()` and
:c:func:`regulator_set_current_limit()` functions provide the primary
interface for this. Both take ranges of voltages and currents, supporting
drivers that do not require a specific value (eg, CPU frequency scaling
normally permits the CPU to use a wider range of supply voltages at lower
frequencies but does not require that the supply voltage be lowered). Where
an exact value is required both minimum and maximum values should be
identical.
Event callback
106-110Regulation failure 같은 event를 받기 위한 callback을 등록할 수 있습니다.
Callbacks
---------
Callbacks may also be registered for events such as regulation failures.
Regulator driver interface
111-121Regulator chip driver는 regulator를 regulator core에 등록하고 operation structure를 제공합니다. Notifier interface는 error condition을 core에 보고합니다.
Registration은 platform의 explicit setup으로 시작해야 합니다. Platform은 regulator의 constraint와 supply information을 담은 `struct regulator_init_data`를 제공합니다.
Platform data가 constraint와 supply를 제공하고 chip driver가 operation을 core에 등록합니다.
Regulator driver interface
==========================
Drivers for regulator chips register the regulators with the regulator
core, providing operations structures to the core. A notifier interface
allows error conditions to be reported to the core.
Registration should be triggered by explicit setup done by the platform,
supplying a struct regulator_init_data for the regulator
containing constraint and supply information.
Machine interface
122-128Machine interface는 특정 system에서 regulator가 consumer에 어떻게 연결되는지와 system에 유효한 operating parameter를 정의합니다.
Machine interface
=================
This interface provides a way to define how regulators are connected to
consumers on a given system and what the valid operating parameters are
for the system.
Consumer supply mapping
129-135Regulator supply는 `struct regulator_consumer_supply`로 지정합니다. Driver registration 시 machine constraint의 일부로 제공합니다.
Supplies
--------
Regulator supplies are specified using struct
:c:type:`regulator_consumer_supply`. This is done at driver registration
time as part of the machine constraints.
Machine constraint와 초기 configuration
136-152Machine interface는 연결 관계뿐 아니라 client가 수행할 수 있는 operation과 설정 가능한 parameter의 constraint도 정의합니다.
Regulator device는 특정 system에서 안전하게 사용할 수 있는 범위보다 더 큰 flexibility를 제공하는 경우가 많습니다. 예를 들어 consumer rating보다 높은 supply voltage를 지원할 수 있으므로 machine-specific constraint가 필요합니다.
Driver registration 시 `struct regulation_constraints`를 제공해 이를 설정합니다. Constraint 안에 regulator의 initial configuration도 지정할 수 있으며 static consumer에 특히 유용합니다.
Machine constraint가 넓은 hardware 범위를 consumer에게 안전한 범위로 제한합니다.
Constraints
-----------
As well as defining the connections the machine interface also provides
constraints defining the operations that clients are allowed to perform
and the parameters that may be set. This is required since generally
regulator devices will offer more flexibility than it is safe to use on
a given system, for example supporting higher supply voltages than the
consumers are rated for.
This is done at driver registration time` by providing a
struct regulation_constraints.
The constraints may also specify an initial configuration for the
regulator in the constraints, which is particularly useful for use with
static consumers.
Regulator API reference source
153-170Kernel documentation framework의 제한과 기존 source layout 때문에 regulator API 전체를 이 페이지에 문서화합니다.
Consumer, machine, driver header의 internal API와 regulator core implementation의 exported API를 kernel-doc으로 가져옵니다.
API reference
=============
Due to limitations of the kernel documentation framework and the
existing layout of the source code the entire regulator API is
documented here.
.. kernel-doc:: include/linux/regulator/consumer.h
:internal:
.. kernel-doc:: include/linux/regulator/machine.h
:internal:
.. kernel-doc:: include/linux/regulator/driver.h
:internal:
.. kernel-doc:: drivers/regulator/core.c
:export:
요약과 해설
regulator.rst:1-170Regulator framework는 consumer의 symbolic supply를 machine mapping으로 실제 regulator에 연결하고 shared reference count로 enable state를 관리합니다. Consumer는 voltage·current range를 요청하며, platform은 `regulator_init_data`와 machine constraint로 안전한 operation·parameter·initial state를 제한합니다.