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

Zephyr 3.7.0 · OS Services · Runtime PM

Device Runtime Power Management

Device별 reference count로 실제 사용 기간만 active 상태를 유지하고 마지막 user 뒤 suspend합니다.

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

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

Part 1

요약·해설

초기 suspended state, get/put transition, dependency 제한, 자동 활성화와 동기·비동기 sequence를 설명합니다.

Reference

get · put

States

ACTIVE · SUSPENDING · SUSPENDED

Async

System work queue

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 2002C31BEB9A03AA8FE4C2A5A74A3B4BE09D8079485E54E2EB209494CE878A40
.. _pm-device-runtime:

Device Runtime Power Management
###############################

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

The device runtime power management (PM) framework is an active power management
mechanism which reduces the overall system power consumption by suspending the
devices which are idle or not used independently of the system state. It can be
enabled by setting :kconfig:option:`CONFIG_PM_DEVICE_RUNTIME`. In this model the device
driver is responsible to indicate when it needs the device and when it does not.
This information is used to determine when to suspend or resume a device based
on usage count.

When device runtime power management is enabled on a device, its state will be
initially set to a :c:enumerator:`PM_DEVICE_STATE_SUSPENDED` indicating it is
not used. On the first device request, it will be resumed and so put into the
:c:enumerator:`PM_DEVICE_STATE_ACTIVE` state. The device will remain in this
state until it is no longer used. At this point, the device will be suspended
until the next device request. If the suspension is performed synchronously the
device will be immediately put into the
:c:enumerator:`PM_DEVICE_STATE_SUSPENDED` state, whereas if it is performed
asynchronously, it will be put into the
:c:enumerator:`PM_DEVICE_STATE_SUSPENDING` state first and then into the
:c:enumerator:`PM_DEVICE_STATE_SUSPENDED` state when the action is run.

For devices on a power domain (via the devicetree 'power-domain' property), device runtime
power management automatically attempts to request and release the dependent domain
in response to :c:func:`pm_device_runtime_get` and :c:func:`pm_device_runtime_put`
calls on the child device.

For the previous to automatically control the power domain state, device runtime PM must be enabled
on the power domain device (either through the `zephyr,pm-device-runtime-auto` devicetree property
or :c:func:`pm_device_runtime_enable`).

.. graphviz::
   :caption: Device states and transitions

    digraph {
        node [shape=box];
        init [shape=point];

        SUSPENDED [label=PM_DEVICE_STATE_SUSPENDED];
        ACTIVE [label=PM_DEVICE_STATE_ACTIVE];
        SUSPENDING [label=PM_DEVICE_STATE_SUSPENDING];

        init -> SUSPENDED;
        SUSPENDED -> ACTIVE;
        ACTIVE -> SUSPENDED;
        ACTIVE -> SUSPENDING [constraint=false]
        SUSPENDING -> SUSPENDED [constraint=false];
        SUSPENDED -> SUSPENDING [style=invis];
        SUSPENDING -> ACTIVE [style=invis];
    }

The device runtime power management framework has been designed to minimize
devices power consumption with minimal application work. Device drivers are
responsible for indicating when they need the device to be operational and
when they do not. Therefore, applications can not manually suspend or resume a
device. An application can, however, decide when to disable or enable runtime
power management for a device. This can be useful, for example, if an
application wants a particular device to be always active.

Design principles
*****************

When runtime PM is enabled on a device it will no longer be resumed or suspended
during system power transitions. Instead, the device is fully responsible to
indicate when it needs a device and when it does not. The device runtime PM API
uses reference counting to keep track of device's usage. This allows the API to
determine when a device needs to be resumed or suspended. The API uses the *get*
and *put* terminology to indicate when a device is needed or not, respectively.
This mechanism plays a key role when we account for device dependencies. For
example, if a bus device is used by multiple sensors, we can keep the bus active
until the last sensor has finished using it.

.. note::

    As of today, the device runtime power management API does not manage device
    dependencies. This effectively means that, if a device depends on other
    devices to operate (e.g. a sensor may depend on a bus device), the bus will
    be resumed and suspended on every transaction. In general, it is more
    efficient to keep parent devices active when their children are used, since
    the children may perform multiple transactions in a short period of time.
    Until this feature is added, devices can manually *get* or *put* their
    dependencies.

The :c:func:`pm_device_runtime_get` function can be used by a device driver to
indicate it *needs* the device to be active or operational. This function will
increase device usage count and resume the device if necessary. Similarly, the
:c:func:`pm_device_runtime_put` function can be used to indicate that the device
is no longer needed. This function will decrease the device usage count and
suspend the device if necessary. It is worth to note that in both cases, the
operation is carried out synchronously. The sequence diagram shown below
illustrates how a device can use this API and the expected sequence of events.

.. figure:: ../../../../services/pm/images/devr-sync-ops.svg

    Synchronous operation on a single device

The synchronous model is as simple as it gets. However, it may introduce
unnecessary delays since the application will not get the operation result until
the device is suspended (in case device is no longer used). It will likely not
be a problem if the operation is fast, e.g. a register toggle. However, the
situation will not be the same if suspension involves sending packets through a
slow bus. For this reason the device drivers can also make use of the
:c:func:`pm_device_runtime_put_async` function. This function will schedule
the suspend operation, again, if device is no longer used. The suspension will
then be carried out when the system work queue gets the chance to run. The
sequence diagram shown below illustrates this scenario.

.. figure:: ../../../../services/pm/images/devr-async-ops.svg

    Asynchronous operation on a single device

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

In a first place, a device driver needs to implement the PM action callback used
by the PM subsystem to suspend or resume devices.

.. 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;
        default:
            return -ENOTSUP;
        }

        return 0;
    }

The PM action callback calls are serialized by the PM subsystem, therefore, no
special synchronization is required.

To enable device runtime power management on a device, the driver needs to call
:c:func:`pm_device_runtime_enable` at initialization time. Note that this
function will suspend the device if its state is
:c:enumerator:`PM_DEVICE_STATE_ACTIVE`. In case the device is physically
suspended, the init function should call
:c:func:`pm_device_init_suspended` before calling
:c:func:`pm_device_runtime_enable`.

.. code-block:: c

    /* device driver initialization function */
    static int mydev_init(const struct device *dev)
    {
        int ret;
        ...

        /* OPTIONAL: mark device as suspended if it is physically suspended */
        pm_device_init_suspended(dev);

        /* enable device runtime power management */
        ret = pm_device_runtime_enable(dev);
        if ((ret < 0) && (ret != -ENOSYS)) {
            return ret;
        }
    }

Device runtime power management can also be automatically enabled on a device
instance by adding the ``zephyr,pm-device-runtime-auto`` flag onto the corresponding
devicetree node. If enabled, :c:func:`pm_device_runtime_enable` is called immediately
after the ``init`` function of the device runs and returns successfully.

.. code-block:: dts

    foo {
        /* ... */
        zephyr,pm-device-runtime-auto;
    };

Assuming an example device driver that implements an ``operation`` API call, the
*get* and *put* operations could be carried out as follows:

.. code-block:: c

    static int mydev_operation(const struct device *dev)
    {
        int ret;

        /* "get" device (increases usage count, resumes device if suspended) */
        ret = pm_device_runtime_get(dev);
        if (ret < 0) {
            return ret;
        }

        /* do something with the device */
        ...

        /* "put" device (decreases usage count, suspends device if no more users) */
        return pm_device_runtime_put(dev);
    }

In case the suspend operation is *slow*, the device driver can use the
asynchronous API:

.. code-block:: c

    static int mydev_operation(const struct device *dev)
    {
        int ret;

        /* "get" device (increases usage count, resumes device if suspended) */
        ret = pm_device_runtime_get(dev);
        if (ret < 0) {
            return ret;
        }

        /* do something with the device */
        ...

        /* "put" device (decreases usage count, schedule suspend if no more users) */
        return pm_device_runtime_put_async(dev, K_NO_WAIT);
    }

Examples
********

Some helpful examples showing device runtime power management features:

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

Part 3

한국어 전문 번역

Introduction

Device Runtime PM framework는 system state와 독립적으로 idle이거나 사용하지 않는 device를 suspend해 전체 소비 전력을 줄이는 active power-management mechanism입니다. CONFIG_PM_DEVICE_RUNTIME으로 활성화하며 driver가 device를 언제 필요로 하고 언제 놓는지 표시합니다. Usage count가 resume와 suspend 시점을 결정합니다.

Runtime PM이 켜진 device의 초기 state는 사용하지 않음을 나타내는 PM_DEVICE_STATE_SUSPENDED입니다. 첫 request에서 PM_DEVICE_STATE_ACTIVE로 resume되고, 마지막 user가 사라지면 다시 suspend됩니다. 동기 suspend는 곧바로 SUSPENDED가 되고 비동기 suspend는 PM_DEVICE_STATE_SUSPENDING을 거쳐 work가 실행된 뒤 SUSPENDED가 됩니다.

Devicetree power-domain property로 domain에 연결된 child에 pm_device_runtime_get()과 put()을 호출하면 dependent domain도 자동으로 request·release합니다. 자동 제어를 위해 domain device 자체의 runtime PM도 zephyr,pm-device-runtime-auto 또는 pm_device_runtime_enable()로 켜야 합니다.

Runtime PM state와 transition
초기 상태PM_DEVICE_STATE_SUSPENDED
첫 get
ACTIVEUsage count가 1 이상인 동작 상태
동기 put마지막 user면 즉시 SUSPENDED
비동기 putSUSPENDING을 거쳐 SUSPENDED

Runtime PM은 최소한의 application 작업으로 device 전력을 줄이도록 설계됐습니다. Driver가 operational state 필요 여부를 표시하므로 application은 device를 직접 suspend/resume할 수 없습니다. 다만 특정 device를 항상 active로 유지하려면 runtime PM 자체를 disable하거나 enable할 수 있습니다.

Design principles

Runtime PM이 활성화된 device는 system power transition에서 별도로 suspend/resume되지 않습니다. Get은 device가 필요함을, put은 더는 필요하지 않음을 뜻하고 reference count가 0과 1 사이를 오갈 때 실제 transition이 발생합니다. 여러 sensor가 하나의 bus를 쓴다면 마지막 sensor가 끝날 때까지 bus를 active로 유지하는 방식입니다.

pm_device_runtime_get()은 usage count를 늘리고 필요하면 동기 resume합니다. pm_device_runtime_put()은 count를 줄이고 마지막 user라면 동기 suspend합니다.

하나의 device에서 runtime PM get, operation, 동기 put과 suspend가 이어지는 sequence
Synchronous operation on a single device

동기 model은 단순하지만 suspend가 느린 bus packet 전송 등을 포함하면 caller가 완료될 때까지 기다려야 합니다. pm_device_runtime_put_async()은 마지막 user 뒤 suspend를 system work queue에 예약해 caller delay를 줄입니다.

하나의 device에서 runtime PM put이 비동기 work queue suspend로 이어지는 sequence
Asynchronous operation on a single device

Implementation guidelines

Driver는 먼저 subsystem이 suspend/resume에 사용할 PM action callback을 구현합니다.

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;
    default:
        return -ENOTSUP;
    }

    return 0;
}

PM subsystem이 callback 호출을 serialize하므로 callback 자체를 위한 별도 synchronization은 필요하지 않습니다.

Driver initialization에서 pm_device_runtime_enable()을 호출합니다. 이 함수는 현재 ACTIVE인 device를 suspend합니다. Hardware가 물리적으로 이미 suspend돼 있다면 먼저 pm_device_init_suspended()로 subsystem state를 맞춰야 합니다.

/* device driver initialization function */
static int mydev_init(const struct device *dev)
{
    int ret;
    ...

    /* OPTIONAL: mark device as suspended if it is physically suspended */
    pm_device_init_suspended(dev);

    /* enable device runtime power management */
    ret = pm_device_runtime_enable(dev);
    if ((ret < 0) && (ret != -ENOSYS)) {
        return ret;
    }
}

Device node에 zephyr,pm-device-runtime-auto flag를 넣으면 init function이 성공한 직후 runtime PM이 자동 활성화됩니다.

foo {
    /* ... */
    zephyr,pm-device-runtime-auto;
};

Driver operation은 작업 전에 get하고, 실패를 확인한 뒤 hardware operation을 수행하며, 끝에서 put합니다. 마지막 user라면 put이 suspend를 실행합니다.

static int mydev_operation(const struct device *dev)
{
    int ret;

    /* "get" device (increases usage count, resumes device if suspended) */
    ret = pm_device_runtime_get(dev);
    if (ret < 0) {
        return ret;
    }

    /* do something with the device */
    ...

    /* "put" device (decreases usage count, suspends device if no more users) */
    return pm_device_runtime_put(dev);
}

Suspend operation이 느리면 같은 pattern에서 마지막 put을 pm_device_runtime_put_async(dev, K_NO_WAIT)으로 바꿔 suspend를 work queue에 예약합니다.

static int mydev_operation(const struct device *dev)
{
    int ret;

    /* "get" device (increases usage count, resumes device if suspended) */
    ret = pm_device_runtime_get(dev);
    if (ret < 0) {
        return ret;
    }

    /* do something with the device */
    ...

    /* "put" device (decreases usage count, schedule suspend if no more users) */
    return pm_device_runtime_put_async(dev, K_NO_WAIT);
}

Examples

Runtime PM과 power-domain 연동 test는 다음 source tree에 있습니다.

  • tests/subsys/pm/device_runtime_api/
  • tests/subsys/pm/device_power_domains/
  • tests/subsys/pm/power_domain/

Source

출처

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