Part 1
요약·해설
공식 렌더링에 확장된 102개 macro·enum·function·structure를 System, States, Policy, Hooks, Device, Runtime 그룹 순서로 설명합니다.
State · notifier · hooks
Locks · latency · events
Actions · runtime usage
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
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의 결정을 덮어쓰고
infostate를 강제로 사용합니다. 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-statecompatible node로pm_state_infoinitializer를 만듭니다.PM_STATE_DT_INIT(node_id)- 같은 devicetree node에서
pm_stateenum 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_infoarray 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_stateenum 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- 연결된
devicepointer입니다. 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-autoproperty에 따라 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
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.