services/pm/api/index.html · services/pm/api/index.rst 공식 원문 ↗

Zephyr 3.7.0 · OS Services · PM API

Power Management APIs

System과 device의 power state를 정의하고 policy constraint, transition과 runtime usage를 제어합니다.

Official pathservices/pm/api/index.html
Source fileservices/pm/api/index.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

공식 렌더링에 확장된 102개 macro·enum·function·structure를 System, States, Policy, Hooks, Device, Runtime 그룹 순서로 설명합니다.

System

State · notifier · hooks

Policy

Locks · latency · events

Device

Actions · runtime usage

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 42BCBFCC908E4273FCFC3E18FFF746F63959C8D37ABC547FE6EB2BF41B409509
.. _pm_api:

Power Management APIs
#####################

System PM APIs
**************

.. doxygengroup:: subsys_pm_sys

States
======

.. doxygengroup:: subsys_pm_states

Policy
======

.. doxygengroup:: subsys_pm_sys_policy

Hooks
=====

.. doxygengroup:: subsys_pm_sys_hooks

Device PM APIs
**************

.. doxygengroup:: subsys_pm_device

.. _device_runtime_apis:

Device Runtime PM APIs
**********************

.. doxygengroup:: subsys_pm_device_runtime

Part 3

한국어 전문 번역

System PM APIs

subsys_pm_sys group은 Zephyr 1.2부터 제공되는 System Power Management API입니다.

pm_state_force(cpu, info)
다음 idle thread 진입에서 PM policy의 결정을 덮어쓰고 info state를 강제로 사용합니다. Thread context에서만 호출할 수 있으며 성공 여부를 bool로 반환합니다.
pm_notifier_register(notifier)
Power management notification list에 pm_notifier 객체를 등록합니다.
pm_notifier_unregister(notifier)
등록한 notifier를 제거해 이후 callback 호출을 중단합니다. 성공 시 0, 실패 시 음수 값을 반환합니다.
pm_state_next_get(cpu)
지정 CPU가 다음 suspend에서 사용할 pm_state_info를 반환합니다.
pm_system_resume()
Kernel idle에서 빠져나왔음을 알립니다. pm_system_suspend()가 PM_STATE_ACTIVE가 아닌 state를 처리했을 때 wake event ISR에서 호출합니다. x86 C1처럼 power-state 진입 중 interrupt를 켜야 하는 경우 CPU wait 뒤 코드보다 ISR이 먼저 실행되므로 필요합니다.
struct pm_notifier
Target이 power state에 들어가고 나올 때 호출할 callback 집합입니다. 현재는 ACTIVE에서 다른 state로 갈 때 state_entry, 비활성 state에서 ACTIVE로 돌아올 때 state_exit가 호출됩니다. Wake ISR context에서도 실행될 수 있고 내부 spin lock이 잡혀 있으므로 callback 안에서 notifier 등록·해제를 호출하면 안 됩니다.
pm_notifier.state_entry(state)
Power state 진입 때 target-specific 작업을 수행하는 application callback입니다.
pm_notifier.state_exit(state)
Power state 이탈 때 target-specific 작업을 수행하는 application callback입니다.

States

subsys_pm_states group은 system power state 정의와 devicetree 초기화 helper를 제공합니다.

PM_STATE_INFO_DT_INIT(node_id)
zephyr,power-state compatible node로 pm_state_info initializer를 만듭니다.
PM_STATE_DT_INIT(node_id)
같은 devicetree node에서 pm_state enum initializer를 만듭니다.
DT_NUM_CPU_POWER_STATES(node_id)
CPU node가 지원하고 활성화한 power state 수를 반환합니다.
PM_STATE_INFO_LIST_FROM_DT_CPU(node_id)
CPU의 cpu-power-states가 가리키는 활성 state를 pm_state_info array initializer로 만듭니다.
cpus {
   ...
   cpu0: cpu@0 {
           device_type = "cpu";
           ...
           cpu-power-states = <&state0 &state1>;
   };

   power-states {
           state0: state0 {
                   compatible = "zephyr,power-state";
                   power-state-name = "suspend-to-idle";
                   min-residency-us = <10000>;
                   exit-latency-us = <100>;
           };

           state1: state1 {
                   compatible = "zephyr,power-state";
                   power-state-name = "suspend-to-ram";
                   min-residency-us = <50000>;
                   exit-latency-us = <500>;
                   zephyr,pm-device-disabled;
           };
   };
};
const struct pm_state_info states[] =
     PM_STATE_INFO_LIST_FROM_DT_CPU(DT_NODELABEL(cpu0));
PM_STATE_LIST_FROM_DT_CPU(node_id)
CPU의 활성 power-state node를 pm_state enum array initializer로 변환합니다.
cpus {
   ...
   cpu0: cpu@0 {
           device_type = "cpu";
           ...
           cpu-power-states = <&state0 &state1>;
   };

   power-states {
           state0: state0 {
                   compatible = "zephyr,power-state";
                   power-state-name = "suspend-to-idle";
                   min-residency-us = <10000>;
                   exit-latency-us = <100>;
           };

           state1: state1 {
                   compatible = "zephyr,power-state";
                   power-state-name = "suspend-to-ram";
                   min-residency-us = <50000>;
                   exit-latency-us = <500>;
           };
   };
};
const enum pm_state states[] = PM_STATE_LIST_FROM_DT_CPU(DT_NODELABEL(cpu0));
enum pm_state
System PM state 집합입니다. 일반적으로 뒤쪽 state일수록 전력 절감은 커지고 wake latency도 늘어납니다.
PM_STATE_ACTIVE
System이 runtime active 상태이며 ACPI S0에 대응합니다.
PM_STATE_RUNTIME_IDLE
CPU를 clock-gate할 수 있지만 system context는 보존되는 runtime idle이며 ACPI S0ix에 대응합니다.
PM_STATE_SUSPEND_TO_IDLE
Device와 CPU context를 보존하면서 가능한 component를 low-power mode로 두는 suspend-to-idle이며 ACPI S1과 연결됩니다.
PM_STATE_STANDBY
CPU와 일부 system context를 잃을 수 있지만 memory는 유지하는 standby이며 ACPI S2에 대응합니다.
PM_STATE_SUSPEND_TO_RAM
Memory를 self-refresh로 유지하고 CPU·device state를 RAM에 저장한 뒤 대부분의 system을 끄는 state이며 ACPI S3에 대응합니다.
PM_STATE_SUSPEND_TO_DISK
Memory 내용까지 non-volatile storage에 기록하고 system 대부분을 끈 뒤 bootstrap code로 복원하는 state이며 ACPI S4에 대응합니다.
PM_STATE_SOFT_OFF
CPU와 memory context를 보존하지 않고 다음 시작 때 처음부터 boot하는 최소 전력 state이며 ACPI G2/S5에 대응합니다.
PM_STATE_COUNT
내부에서 사용하는 power-state 개수입니다.
pm_state_cpu_get_all(cpu, states)
CPU가 지원하는 모든 state 정보를 states에 돌려주고 그 개수를 반환합니다.
struct pm_state_info
Platform의 power state 하나를 설명합니다. 하나의 Zephyr state에 여러 platform substate가 대응할 수 있습니다.
pm_state_info.substate_id
같은 pm_state에 매핑되는 platform-specific substate를 구분합니다.
power-states {
   state0: state0 {
           compatible = "zephyr,power-state";
           power-state-name = "suspend-to-idle";
           substate-id = <1>;
           min-residency-us = <10000>;
           exit-latency-us = <100>;
   };
   state1: state1 {
           compatible = "zephyr,power-state";
           power-state-name = "suspend-to-idle";
           substate-id = <2>;
           min-residency-us = <20000>;
           exit-latency-us = <200>;
           zephyr,pm-device-disabled;
   };
};
pm_state_info.pm_device_disabled
이 state가 device PM을 유발하는지 나타냅니다. 값이 false이면 진입 전에 device를 suspend하고 이탈 때 resume합니다.
pm_state_info.min_residency_us
Energy 관점에서 state 진입이 이득이 되기 위한 최소 체류 시간입니다. 0은 정보가 없음을 뜻합니다.
pm_state_info.exit_latency_us
Idle state에서 빠져나오는 worst-case latency입니다. 0은 정보가 없음을 뜻합니다.
struct pm_state_constraint
Power state lock에 필요한 state와 substate 정보를 담습니다.
pm_state_constraint.state
차단하거나 허용할 pm_state입니다.
pm_state_constraint.substate_id
대상 power substate ID입니다.

Policy

subsys_pm_sys_policy는 state lock, latency requirement와 timed event를 policy manager에 전달합니다.

PM_ALL_SUBSTATES
지정 state의 모든 substate를 뜻하는 특수 값입니다.
pm_policy_latency_changed_cb_t(latency)
최대 허용 latency가 바뀔 때 호출됩니다. 양수는 microsecond, SYS_FOREVER_US는 constraint 해제를 뜻하며 다른 값은 허용되지 않습니다.
pm_policy_state_lock_get(state, substate_id)
해당 state lock reference count를 늘립니다. 첫 호출부터 state가 금지되고 같은 횟수의 put 뒤 다시 허용됩니다. PM_STATE_ACTIVE에는 효과가 없습니다.
pm_policy_state_lock_put(state, substate_id)
State lock count를 줄입니다. 마지막 reference가 해제되면 state를 다시 선택할 수 있습니다.
pm_policy_state_lock_is_active(state, substate_id)
State 또는 substate가 현재 lock되어 사용할 수 없는지 확인합니다.
pm_policy_latency_request_add(req, value_us)
새 maximum wake-up latency requirement를 등록합니다. ISR-safe이며 value_us는 microsecond 단위입니다.
pm_policy_latency_request_update(req, value_us)
등록된 latency requirement 값을 갱신합니다.
pm_policy_latency_request_remove(req)
Latency requirement를 제거합니다.
pm_policy_latency_changed_subscribe(sub)
Maximum latency 변경 notification을 구독합니다.
pm_policy_latency_changed_unsubscribe(sub)
Latency 변경 구독을 해제합니다.
pm_policy_event_register(event, ticks)
미래 event를 등록해 policy가 다음 deadline을 고려하게 합니다.
pm_policy_event_update(event, ticks)
등록된 event의 예상 시간을 갱신합니다.
pm_policy_event_unregister(event)
Policy event를 제거합니다.
pm_policy_device_power_lock_get(dev)
Device의 zephyr,disabling-power-states가 지정한 모든 state lock count를 늘립니다.
pm_policy_device_power_lock_put(dev)
Device가 잡은 power-loss state lock을 해제합니다.
struct pm_policy_latency_subscription
Latency 변경 callback과 내부 list node를 보관하는 subscription 객체입니다.
struct pm_policy_latency_request
Policy에 등록할 maximum latency requirement 값과 내부 list node를 보관합니다.
struct pm_policy_event
Policy가 고려할 미래 timed event의 tick deadline과 내부 관리 정보를 보관합니다.

Hooks

pm_state_set(state, substate_id)
Processor를 지정 power state로 전환하는 SoC/architecture hook입니다. Interrupt가 잠긴 상태에서 호출되며 구현이 실제 low-power 진입을 담당합니다.
pm_state_exit_post_ops(state, substate_id)
Sleep에서 나온 뒤 SoC/architecture-specific 복구 작업을 수행합니다. 일반적으로 interrupt 상태 복구도 여기에서 처리합니다.

Device PM APIs

subsys_pm_device group은 device PM resource 정의, state/action 전환, busy·wakeup·power-domain 관리 API를 제공합니다.

PM_DEVICE_ISR_SAFE
해당 device의 runtime PM API를 ISR을 포함한 모든 context에서 호출할 수 있음을 표시합니다.
PM_DEVICE_DEFINE(dev_name, pm_action_cb)
Device name과 action callback으로 PM resource를 정의합니다.
PM_DEVICE_DT_DEFINE(node_id, pm_action_cb)
Devicetree node ID에 대한 PM resource를 정의합니다.
PM_DEVICE_DT_INST_DEFINE(inst, pm_action_cb)
현재 driver의 devicetree instance에 PM resource를 정의합니다.
PM_DEVICE_GET(dev_name)
Name으로 정의된 device PM resource pointer를 얻습니다.
PM_DEVICE_DT_GET(node_id)
Devicetree node의 PM resource pointer를 얻습니다.
PM_DEVICE_DT_INST_GET(inst)
Driver instance의 PM resource pointer를 얻습니다.
pm_device_action_cb_t(dev, action)
Driver가 suspend, resume, turn-off, turn-on hardware 작업을 수행하는 callback type입니다.
pm_device_action_failed_cb_t(dev, action, ret, arg)
Child action 실행 중 실패한 device, action과 error를 보고받는 callback type입니다.
enum pm_device_state
Device의 현재 PM state 집합입니다.
PM_DEVICE_STATE_ACTIVE
Device가 일반 active 상태입니다.
PM_DEVICE_STATE_SUSPENDED
Device가 suspend 완료 상태입니다.
PM_DEVICE_STATE_SUSPENDING
Async suspend가 예약돼 진행 중인 상태입니다.
PM_DEVICE_STATE_OFF
Power가 제거돼 device가 꺼진 상태입니다.
enum pm_device_action
Driver callback에 전달되는 PM action 집합입니다.
PM_DEVICE_ACTION_SUSPEND
Device를 suspend합니다.
PM_DEVICE_ACTION_RESUME
Suspended device를 active로 복귀시킵니다.
PM_DEVICE_ACTION_TURN_OFF
Power domain이 내려가기 전에 device를 off 준비 상태로 만듭니다.
PM_DEVICE_ACTION_TURN_ON
Power domain이 올라온 뒤 device를 다시 사용할 준비를 합니다.
pm_device_state_str(state)
Device PM state의 이름 문자열을 반환합니다.
pm_device_action_run(dev, action)
하나의 device에서 PM action을 실행하고 subsystem state를 갱신합니다.
pm_device_children_action_run(dev, action, failure_cb)
Parent device의 모든 child에 action을 실행하며 실패 시 선택적 callback을 호출합니다.
pm_device_state_get(dev, state)
현재 device power state를 읽습니다.
pm_device_init_suspended(dev)
실제 hardware가 이미 suspend 상태일 때 초기 subsystem state를 SUSPENDED로 맞춥니다.
pm_device_init_off(dev)
실제 hardware가 꺼져 있을 때 초기 state를 OFF로 설정합니다.
pm_device_busy_set(dev)
중단할 수 없는 transaction 중임을 표시해 system-managed PM이 device를 suspend하지 못하게 합니다.
pm_device_busy_clear(dev)
Transaction이 끝난 뒤 busy 표시를 지웁니다.
pm_device_is_any_busy()
PM을 지원하는 device 중 하나라도 busy인지 확인합니다.
pm_device_is_busy(dev)
지정 device의 busy 상태를 확인합니다.
pm_device_wakeup_enable(dev, enable)
Wake-up capable device의 system wake source 기능을 동적으로 켜거나 끕니다.
pm_device_wakeup_is_enabled(dev)
Wake-up source 기능이 현재 활성화됐는지 확인합니다.
pm_device_wakeup_is_capable(dev)
Devicetree wakeup-source 등으로 wake capability가 선언됐는지 확인합니다.
pm_device_on_power_domain(dev)
Device가 switchable power domain에 연결됐는지 확인합니다.
pm_device_power_domain_add(dev, domain)
Runtime에 device를 power domain child로 추가합니다.
pm_device_power_domain_remove(dev, domain)
Power domain과 device의 연결을 제거합니다.
pm_device_is_powered(dev)
Device와 상위 power domain이 현재 전력을 공급받는지 확인합니다.
pm_device_driver_init(dev, cb)
Driver initialization에서 유효한 가장 낮은 power mode로 상태를 맞춥니다.
struct pm_device_base
일반 device와 ISR-safe device가 공유하는 state, flags, action callback, usage count를 보관합니다.
pm_device_base.flags
Runtime enabled, wakeup capable/enabled, power-domain membership 같은 device PM status flag를 보관합니다.
pm_device_base.state
현재 device power state입니다.
pm_device_base.action_cb
Driver PM action callback입니다.
pm_device_base.usage
Runtime PM reference count입니다.
struct pm_device
Thread-context runtime PM device의 base 정보와 동기화 자원입니다.
pm_device.base
공통 pm_device_base 정보입니다.
pm_device.dev
연결된 device pointer입니다.
pm_device.lock
Get/put operation을 serialize하는 lock입니다.
pm_device.event
동기 request 완료를 기다리는 event 변수입니다.
pm_device.work
비동기 suspend 호출에 사용하는 work object입니다.
struct pm_device_isr
ISR-safe runtime PM device의 base 정보와 spin lock을 보관합니다.
pm_device_isr.base
ISR-safe variant가 공유하는 pm_device_base 정보입니다.
pm_device_isr.lock
ISR-safe synchronous get/put을 보호하는 lock입니다.

Device Runtime PM APIs

subsys_pm_device_runtime group은 usage count를 기준으로 device를 독립적으로 resume·suspend합니다.

pm_device_runtime_auto_enable(dev)
Devicetree의 zephyr,pm-device-runtime-auto property에 따라 runtime PM을 자동 활성화합니다.
pm_device_runtime_enable(dev)
Runtime PM을 활성화합니다. Active device는 enable 과정에서 suspend할 수 있으며 이미 활성화됐거나 unsupported인 경우 상태에 맞는 error를 반환합니다.
pm_device_runtime_disable(dev)
Runtime PM을 비활성화하고 device를 active 상태로 유지합니다. 사용 중이거나 전환 중이면 실패할 수 있습니다.
pm_device_runtime_get(dev)
Usage count를 늘리고 첫 user라면 device를 동기적으로 resume합니다.
pm_device_runtime_put(dev)
Usage count를 줄이고 마지막 user가 사라지면 동기적으로 suspend합니다.
pm_device_runtime_put_async(dev, delay)
마지막 user 뒤 suspend를 system work queue에 예약합니다. delay로 실행 시점을 늦출 수 있습니다.
pm_device_runtime_is_enabled(dev)
지정 device의 runtime PM 활성 여부를 확인합니다.
pm_device_runtime_usage(dev)
현재 runtime usage counter를 반환합니다.

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.