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

Zephyr 3.7.0 · OS Services · Device PM

Power Domain

전원 공급원을 공유하는 device group을 하나의 domain으로 관리하고 상태 변화를 child에 전달합니다.

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

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

Part 1

요약·해설

Internal leakage 차단, external regulator group, domain hierarchy와 TURN_ON·TURN_OFF callback 순서를 설명합니다.

Grouping

Shared source

Actions

TURN_ON · TURN_OFF

Topology

Hierarchical domains

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 F83C7A96F233C6BCCA8A4EC1ED0F3EC494064AC130F5D9753BF4D62CD191EE45
.. _pm-power-domain:

Power Domain
############

Introduction
************

The Zephyr power domain abstraction is designed to support groupings of devices
powered by a common source to be notified of power source state changes in a
generic fashion. Application code that is using device A does not need to know
that device B is on the same power domain and should also be configured into a
low power state.

Power domains are optional on Zephyr, to enable this feature the
option :kconfig:option:`CONFIG_PM_DEVICE_POWER_DOMAIN` has to be set.

When a power domain turns itself on or off, it is the responsibility of the
power domain to notify all devices using it through their power management
callback called with
:c:enumerator:`PM_DEVICE_ACTION_TURN_ON` or
:c:enumerator:`PM_DEVICE_ACTION_TURN_OFF` respectively. This
work flow is illustrated in the diagram below.

.. _pm-domain-work-flow:

.. graphviz::
   :caption: Power domain work flow

   digraph {
       rankdir="TB";

       action [style=invis]
       {
           rank = same;
           rankdir="LR"
           devA [label="gpio0"]
           devB [label="gpio1"]
       }
       domain [label="gpio_domain"]

      action -> devA [label="pm_device_get()"]
      devA:se -> domain:n [label="pm_device_get()"]

      domain -> devB [label="action_cb(PM_DEVICE_ACTION_TURN_ON)"]
      domain:sw -> devA:sw [label="action_cb(PM_DEVICE_ACTION_TURN_ON)"]
   }

Internal Power Domains
----------------------

Most of the devices in an SoC have independent power control that can
be turned on or off to reduce power consumption. But there is a
significant amount of static current leakage that can't be controlled
only using device power management. To solve this problem, SoCs
normally are divided into several regions grouping devices that
are generally used together, so that an unused region can be
completely powered off to eliminate this leakage. These regions are
called "power domains", can be present in a hierarchy and can be
nested.

External Power Domains
----------------------

Devices external to a SoC can be powered from sources other than the main power
source of the SoC. These external sources are typically a switch, a regulator,
or a dedicated power IC. Multiple devices can be powered from the same source,
and this grouping of devices is typically called a "power domain".

Placing devices on power domains can be done for a variety of reasons,
including to enable devices with high power consumption in low power mode to be
completely turned off when not in use.

Implementation guidelines
*************************

In a first place, a device that acts as a power domain needs to
declare compatible with ``power-domain``. Taking
:ref:`pm-domain-work-flow` as example, the following code defines a
domain called ``gpio_domain``.

.. code-block:: devicetree

	gpio_domain: gpio_domain@4 {
		compatible = "power-domain";
		...
	};

A power domain needs to implement the PM action callback used by the
PM subsystem to turn devices on and off.

.. code-block:: c

    static int mydomain_pm_action(const struct device *dev,
                               enum pm_device_action *action)
    {
        switch (action) {
        case PM_DEVICE_ACTION_RESUME:
            /* resume the domain */
            ...
            /* notify children domain is now powered */
            pm_device_children_action_run(dev, PM_DEVICE_ACTION_TURN_ON, NULL);
            break;
        case PM_DEVICE_ACTION_SUSPEND:
            /* notify children domain is going down */
            pm_device_children_action_run(dev, PM_DEVICE_ACTION_TURN_OFF, NULL);
            /* suspend the domain */
            ...
            break;
        case PM_DEVICE_ACTION_TURN_ON:
            /* turn on the domain (e.g. setup control pins to disabled) */
            ...
            break;
        case PM_DEVICE_ACTION_TURN_OFF:
            /* turn off the domain (e.g. reset control pins to default state) */
            ...
            break;
        default:
            return -ENOTSUP;
        }

        return 0;
    }

Devices belonging to this device can be declared referring it in the
``power-domain`` node's property. The example below declares devices
``gpio0`` and ``gpio1`` belonging to domain ``gpio_domain```.

.. code-block:: devicetree

        &gpio0 {
                compatible = "zephyr,gpio-emul";
                gpio-controller;
                power-domain = <&gpio_domain>;
        };

        &gpio1 {
                compatible = "zephyr,gpio-emul";
                gpio-controller;
                power-domain = <&gpio_domain>;
        };

All devices under a domain will be notified when the domain changes
state. These notifications are sent as actions in the device PM action
callback and can be used by them to do any additional work required.
They can safely be ignored though.

.. code-block:: c

    static int mydev_pm_action(const struct device *dev,
                               enum pm_device_action *action)
    {
        switch (action) {
        case PM_DEVICE_ACTION_SUSPEND:
            /* suspend the device */
            ...
            break;
        case PM_DEVICE_ACTION_RESUME:
            /* resume the device */
            ...
            break;
        case PM_DEVICE_ACTION_TURN_ON:
            /* configure the device into low power mode */
            ...
            break;
        case PM_DEVICE_ACTION_TURN_OFF:
            /* prepare the device for power down */
            ...
            break;
        default:
            return -ENOTSUP;
        }

        return 0;
    }

.. note::

   It is responsibility of driver or the application to set the domain as
   "wakeup" source if a device depending on it is used as "wakeup" source.

Examples
********

Some helpful examples showing power domain features:

* :zephyr_file:`tests/subsys/pm/device_power_domains/`
* :zephyr_file:`tests/subsys/pm/power_domain/`

Part 3

한국어 전문 번역

Introduction

Zephyr power domain abstraction은 하나의 power source를 공유하는 device group에 source state 변화를 공통 방식으로 알리기 위한 기능입니다. Application이 device A를 쓸 때 같은 domain의 device B도 low-power state로 준비해야 한다는 사실까지 알 필요는 없습니다.

Power domain은 optional 기능이며 CONFIG_PM_DEVICE_POWER_DOMAIN을 설정해야 합니다. Domain이 켜지거나 꺼질 때 domain driver는 자신을 사용하는 모든 device의 PM callback을 각각 PM_DEVICE_ACTION_TURN_ON 또는 PM_DEVICE_ACTION_TURN_OFF로 호출해 알려야 합니다.

Power domain 동작 흐름
gpio0 사용 요청pm_device_get(gpio0)
부모 domain 참조 획득
gpio_domain 켜기pm_device_get(gpio_domain)
모든 child에 상태 통지
gpio0action_cb(PM_DEVICE_ACTION_TURN_ON)
gpio1action_cb(PM_DEVICE_ACTION_TURN_ON)

Internal Power Domains

SoC 내부 device는 개별 power control로 dynamic consumption을 줄일 수 있지만, device 단위 제어만으로 제거하기 어려운 static leakage가 있습니다. SoC를 함께 쓰이는 device group 단위 region으로 나누고 사용하지 않는 region 전체를 끄면 이 leakage를 줄일 수 있습니다. 이런 region이 internal power domain이며 계층 구조와 nesting을 가질 수 있습니다.

External Power Domains

SoC 외부 device는 main SoC supply가 아닌 switch, regulator 또는 전용 power IC에서 전력을 받을 수 있습니다. 같은 source를 공유하는 device 묶음도 power domain이라 부릅니다. 특히 low-power mode에서도 소비가 큰 외부 device를 사용하지 않을 때 완전히 끄기 위해 domain으로 구성할 수 있습니다.

Implementation guidelines

Power domain 역할을 하는 device는 power-domain compatible을 선언합니다. 다음 예는 gpio_domain이라는 domain을 정의합니다.

gpio_domain: gpio_domain@4 {
        compatible = "power-domain";
        ...
};

Domain driver는 device를 켜고 끄는 PM action callback을 구현해야 합니다. Resume 시 domain을 먼저 복구한 뒤 child에 TURN_ON을 알리고, suspend 시 child에 TURN_OFF를 먼저 알린 뒤 domain을 끕니다. Domain 자체가 상위 domain의 child라면 TURN_ON과 TURN_OFF도 처리합니다.

static int mydomain_pm_action(const struct device *dev,
                           enum pm_device_action *action)
{
    switch (action) {
    case PM_DEVICE_ACTION_RESUME:
        /* resume the domain */
        ...
        /* notify children domain is now powered */
        pm_device_children_action_run(dev, PM_DEVICE_ACTION_TURN_ON, NULL);
        break;
    case PM_DEVICE_ACTION_SUSPEND:
        /* notify children domain is going down */
        pm_device_children_action_run(dev, PM_DEVICE_ACTION_TURN_OFF, NULL);
        /* suspend the domain */
        ...
        break;
    case PM_DEVICE_ACTION_TURN_ON:
        /* turn on the domain (e.g. setup control pins to disabled) */
        ...
        break;
    case PM_DEVICE_ACTION_TURN_OFF:
        /* turn off the domain (e.g. reset control pins to default state) */
        ...
        break;
    default:
        return -ENOTSUP;
    }

    return 0;
}

Domain에 속하는 device는 devicetree의 power-domain property로 domain phandle을 참조합니다. 다음은 gpio0과 gpio1을 gpio_domain에 연결합니다.

&gpio0 {
        compatible = "zephyr,gpio-emul";
        gpio-controller;
        power-domain = <&gpio_domain>;
};

&gpio1 {
        compatible = "zephyr,gpio-emul";
        gpio-controller;
        power-domain = <&gpio_domain>;
};

Domain 아래의 모든 device는 domain state가 바뀔 때 PM action callback으로 통지를 받습니다. Driver는 필요한 준비 작업을 수행할 수 있으며, 별도 작업이 없다면 이 action을 안전하게 무시할 수 있습니다.

static int mydev_pm_action(const struct device *dev,
                           enum pm_device_action *action)
{
    switch (action) {
    case PM_DEVICE_ACTION_SUSPEND:
        /* suspend the device */
        ...
        break;
    case PM_DEVICE_ACTION_RESUME:
        /* resume the device */
        ...
        break;
    case PM_DEVICE_ACTION_TURN_ON:
        /* configure the device into low power mode */
        ...
        break;
    case PM_DEVICE_ACTION_TURN_OFF:
        /* prepare the device for power down */
        ...
        break;
    default:
        return -ENOTSUP;
    }

    return 0;
}

Examples

Power domain 구현과 검증 예제는 tests/subsys/pm/device_power_domains/와 tests/subsys/pm/power_domain/에 있습니다.

Source

출처

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