Device Energy Model

개요와 power 값의 단위

Energy Model(EM) framework는 여러 performance level에서 device가 소비하는 power를 아는 driver와, 그 정보를 이용해 energy-aware 결정을 내리려는 kernel subsystem 사이의 표준 interface입니다.

Device power 정보의 출처는 platform마다 크게 다릅니다. 어떤 시스템은 devicetree 데이터로 비용을 추정하고, 다른 시스템은 firmware가 더 정확한 값을 알며, userspace가 가장 적절한 출처일 수도 있습니다. 각 client subsystem이 모든 정보 출처를 따로 지원하는 중복을 피하도록 EM이 abstraction layer로 개입해 kernel의 power cost table 형식을 표준화합니다.

Power 값은 micro-Watts 또는 `abstract scale`로 표현할 수 있습니다. 여러 subsystem이 EM을 함께 사용할 수 있으므로 system integrator가 각 subsystem의 scale 요구 사항이 충족되는지 확인해야 합니다.

Energy-Aware Scheduler의 예는 `Documentation/scheduler/sched-energy.rst`에 있습니다. Thermal이나 powercap처럼 과거에 사용한 실제 power를 추정하려는 subsystem은 abstract scale에서 문제가 생길 수 있고 실제 micro-Watts가 필요할 수 있습니다. Intelligent Power Allocation의 요구 사항은 `Documentation/driver-api/thermal/power_allocator.rst`를 참조합니다.

Kernel subsystem은 EM 내부 flag를 바탕으로 등록된 device의 scale 불일치를 자동 감지할 수 있습니다. Power 값이 abstract scale이면 실제 energy를 micro-Joules로 유도할 수 없다는 점이 중요합니다.

.. SPDX-License-Identifier: GPL-2.0

=======================
Energy Model of devices
=======================

1. Overview
-----------

The Energy Model (EM) framework serves as an interface between drivers knowing
the power consumed by devices at various performance levels, and the kernel
subsystems willing to use that information to make energy-aware decisions.

The source of the information about the power consumed by devices can vary greatly
from one platform to another. These power costs can be estimated using
devicetree data in some cases. In others, the firmware will know better.
Alternatively, userspace might be best positioned. And so on. In order to avoid
each and every client subsystem to re-implement support for each and every
possible source of information on its own, the EM framework intervenes as an
abstraction layer which standardizes the format of power cost tables in the
kernel, hence enabling to avoid redundant work.

The power values might be expressed in micro-Watts or in an 'abstract scale'.
Multiple subsystems might use the EM and it is up to the system integrator to
check that the requirements for the power value scale types are met. An example
can be found in the Energy-Aware Scheduler documentation
Documentation/scheduler/sched-energy.rst. For some subsystems like thermal or
powercap power values expressed in an 'abstract scale' might cause issues.
These subsystems are more interested in estimation of power used in the past,
thus the real micro-Watts might be needed. An example of these requirements can
be found in the Intelligent Power Allocation in
Documentation/driver-api/thermal/power_allocator.rst.
Kernel subsystems might implement automatic detection to check whether EM
registered devices have inconsistent scale (based on EM internal flag).
Important thing to keep in mind is that when the power values are expressed in
an 'abstract scale' deriving real energy in micro-Joules would not be possible.

Provider·framework·consumer와 performance domain

그림은 Arm 예를 사용하지만 어떤 architecture에도 같은 접근을 적용할 수 있습니다. 아래쪽의 `cpufreq-dt`, `arm_scmi`와 다른 driver가 Device Tree, firmware 또는 다른 출처에서 power cost를 얻어 `em_dev_register_perf_domain()`으로 EM에 등록합니다. 위쪽의 Thermal IPA, Scheduler EAS와 다른 client는 `em_cpu_energy()`와 `em_cpu_get()` 등으로 이를 읽습니다.

CPU device의 경우 EM은 system의 performance domain마다 power cost table을 관리합니다. Performance domain은 performance가 함께 scaling되는 CPU 집합이며 보통 CPUFreq policy와 1:1로 대응합니다.

한 performance domain의 모든 CPU는 같은 micro-architecture여야 합니다. 서로 다른 performance domain끼리는 micro-architecture가 달라도 됩니다.

The figure below depicts an example of drivers (Arm-specific here, but the
approach is applicable to any architecture) providing power costs to the EM
framework, and interested clients reading the data from it::

       +---------------+  +-----------------+  +---------------+
       | Thermal (IPA) |  | Scheduler (EAS) |  |     Other     |
       +---------------+  +-----------------+  +---------------+
               |                   | em_cpu_energy()   |
               |                   | em_cpu_get()      |
               +---------+         |         +---------+
                         |         |         |
                         v         v         v
                        +---------------------+
                        |    Energy Model     |
                        |     Framework       |
                        +---------------------+
                           ^       ^       ^
                           |       |       | em_dev_register_perf_domain()
                +----------+       |       +---------+
                |                  |                 |
        +---------------+  +---------------+  +--------------+
        |  cpufreq-dt   |  |   arm_scmi    |  |    Other     |
        +---------------+  +---------------+  +--------------+
                ^                  ^                 ^
                |                  |                 |
        +--------------+   +---------------+  +--------------+
        | Device Tree  |   |   Firmware    |  |      ?       |
        +--------------+   +---------------+  +--------------+

In case of CPU devices the EM framework manages power cost tables per
'performance domain' in the system. A performance domain is a group of CPUs
whose performance is scaled together. Performance domains generally have a
1-to-1 mapping with CPUFreq policies. All CPUs in a performance domain are
required to have the same micro-architecture. CPUs in different performance
domains can have different micro-architectures.

Runtime에서 수정 가능한 EM

Static power, 즉 leakage에 따른 power 변화를 더 잘 반영하도록 EM은 runtime power 값 수정을 지원합니다. 수정 가능한 `em_perf_state` table memory는 RCU로 해제하며, 이 table을 읽는 task scheduler도 RCU를 사용합니다.

EM framework는 새 수정 table의 memory를 할당하고 해제하는 API를 제공합니다. 이전 runtime table 인스턴스의 owner가 없어지면 RCU callback으로 자동 해제되고, owner 수명은 kref로 추적합니다. Runtime EM을 제공한 device driver도 더 이상 필요하지 않을 때 EM API를 호출해 안전하게 참조를 내려야 하며, 가능한 시점의 실제 정리는 framework가 담당합니다.

EM 값을 수정하는 kernel code는 mutex로 동시 접근에서 보호됩니다. 따라서 EM을 수정하는 device driver code는 sleep 가능한 context에서 실행되어야 합니다.

이 설계는 system 전체 수명 동안 고정된 단일 EM에서, workload나 system property에 따라 runtime 중 바뀔 수 있는 단일 EM으로 확장됩니다. 각 performance state의 CPU performance 값도 수정할 수 있어 지수 곡선 형태의 전체 power·performance profile을 workload 또는 system 특성에 맞게 바꿀 수 있습니다.

To better reflect power variation due to static power (leakage) the EM
supports runtime modifications of the power values. The mechanism relies on
RCU to free the modifiable EM perf_state table memory. Its user, the task
scheduler, also uses RCU to access this memory. The EM framework provides
API for allocating/freeing the new memory for the modifiable EM table.
The old memory is freed automatically using RCU callback mechanism when there
are no owners anymore for the given EM runtime table instance. This is tracked
using kref mechanism. The device driver which provided the new EM at runtime,
should call EM API to free it safely when it's no longer needed. The EM
framework will handle the clean-up when it's possible.

The kernel code which want to modify the EM values is protected from concurrent
access using a mutex. Therefore, the device driver code must run in sleeping
context when it tries to modify the EM.

With the runtime modifiable EM we switch from a 'single and during the entire
runtime static EM' (system property) design to a 'single EM which can be
changed during runtime according e.g. to the workload' (system and workload
property) design.

It is possible also to modify the CPU performance values for each EM's
performance state. Thus, the full power and performance profile (which
is an exponential curve) can be changed according e.g. to the workload
or system property.

설정과 advanced EM 등록

EM framework를 사용하려면 `CONFIG_ENERGY_MODEL`을 enable해야 합니다.

Advanced EM은 framework에 내장된 수식에 제한되지 않고 driver가 더 정밀한 power model을 제공할 수 있어서 붙은 이름입니다. Performance state마다 측정한 실제 power를 더 잘 반영하므로 static power(leakage)가 중요할 때 이 등록 방식을 우선해야 합니다.

Driver는 다음 API로 performance domain을 등록합니다.

int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states,
        struct em_data_callback *cb, cpumask_t *cpus, bool microwatts);

Driver callback은 각 performance state의 `<frequency, power>` tuple을 반환해야 합니다. Callback은 DT, firmware 등 필요한 어떤 위치와 방법으로도 데이터를 가져올 수 있습니다.

CPU device만 `cpumask`로 performance domain의 CPU를 지정합니다. CPU가 아닌 device에서는 `cpus` 인자를 `NULL`로 설정해야 합니다.

마지막 `microwatts` 인자는 정확해야 합니다. EM을 사용하는 subsystem은 모든 device가 같은 scale인지 이 flag로 검사할 수 있으며, scale이 다르면 warning/error를 반환하거나 동작을 중단하거나 panic할 수도 있습니다. Callback 구현 예는 Section 3, API 상세는 Section 2.4를 참조합니다.

2. Core APIs
------------

2.1 Config options
^^^^^^^^^^^^^^^^^^

CONFIG_ENERGY_MODEL must be enabled to use the EM framework.


2.2 Registration of performance domains
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Registration of 'advanced' EM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The 'advanced' EM gets its name due to the fact that the driver is allowed
to provide more precised power model. It's not limited to some implemented math
formula in the framework (like it is in 'simple' EM case). It can better reflect
the real power measurements performed for each performance state. Thus, this
registration method should be preferred in case considering EM static power
(leakage) is important.

Drivers are expected to register performance domains into the EM framework by
calling the following API::

  int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states,
                struct em_data_callback *cb, cpumask_t *cpus, bool microwatts);

Drivers must provide a callback function returning <frequency, power> tuples
for each performance state. The callback function provided by the driver is free
to fetch data from any relevant location (DT, firmware, ...), and by any mean
deemed necessary. Only for CPU devices, drivers must specify the CPUs of the
performance domains using cpumask. For other devices than CPUs the last
argument must be set to NULL.
The last argument 'microwatts' is important to set with correct value. Kernel
subsystems which use EM might rely on this flag to check if all EM devices use
the same scale. If there are different scales, these subsystems might decide
to return warning/error, stop working or panic.
See Section 3. for an example of driver implementing this
callback, or Section 2.4 for further documentation on this API

DT·artificial·simple EM

OPP framework와 DT의 `operating-points-v2`로도 EM을 등록할 수 있습니다. 각 OPP 항목에 micro-Watts power 값을 담는 `opp-microwatt` property를 추가하면, 실험과 측정에서 얻은 static + dynamic total power를 platform이 등록할 수 있습니다.

Performance state별 상세 power 값을 모르는 driver는 custom callback으로 artificial EM을 만들 수 있습니다. 선택적인 `.get_cost()`는 EAS가 사용할 cost를 제공하며, CPU type 사이의 상대 효율만 아는 platform에서 abstract power model을 구성할 때 유용합니다.

Abstract power 값 크기 제약 때문에 모델을 맞추기 어려운 경우에도 `.get_cost()`로 CPU 효율 관계를 직접 표현할 수 있습니다. 이 관계는 EM 내부 수식이 강제하는 cost 관계와 달라도 됩니다.

Artificial EM을 등록하려면 `microwatts`를 0으로 설정하고 `.get_power()`와 `.get_cost()` callback을 모두 제공해야 합니다. Framework는 등록 시 `EM_PERF_DOMAIN_ARTIFICIAL` flag를 설정하며, EM을 쓰는 다른 framework는 이 flag를 검사해 적절히 다뤄야 합니다.

Simple EM은 `cpufreq_register_em_with_opp()` helper로 등록하며 `Power = C * V^2 * f` 수식에 묶인 모델입니다. Static power(leakage)가 중요하면 실제 device physics를 정확히 반영하지 못할 수 있습니다.

Registration of EM using DT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The  EM can also be registered using OPP framework and information in DT
"operating-points-v2". Each OPP entry in DT can be extended with a property
"opp-microwatt" containing micro-Watts power value. This OPP DT property
allows a platform to register EM power values which are reflecting total power
(static + dynamic). These power values might be coming directly from
experiments and measurements.

Registration of 'artificial' EM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There is an option to provide a custom callback for drivers missing detailed
knowledge about power value for each performance state. The callback
.get_cost() is optional and provides the 'cost' values used by the EAS.
This is useful for platforms that only provide information on relative
efficiency between CPU types, where one could use the information to
create an abstract power model. But even an abstract power model can
sometimes be hard to fit in, given the input power value size restrictions.
The .get_cost() allows to provide the 'cost' values which reflect the
efficiency of the CPUs. This would allow to provide EAS information which
has different relation than what would be forced by the EM internal
formulas calculating 'cost' values. To register an EM for such platform, the
driver must set the flag 'microwatts' to 0, provide .get_power() callback
and provide .get_cost() callback. The EM framework would handle such platform
properly during registration. A flag EM_PERF_DOMAIN_ARTIFICIAL is set for such
platform. Special care should be taken by other frameworks which are using EM
to test and treat this flag properly.

Registration of 'simple' EM
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The 'simple' EM is registered using the framework helper function
cpufreq_register_em_with_opp(). It implements a power model which is tight to
math formula::

        Power = C * V^2 * f

The EM which is registered using this method might not reflect correctly the
physics of a real device, e.g. when static power (leakage) is important.

Performance domain 조회와 energy 추정

Energy Model에 접근하는 API는 CPU id를 받는 `em_cpu_get()`과 device pointer를 받는 `em_pd_get()` 두 가지입니다. Subsystem이 상황에 맞는 interface를 선택하며, CPU device에서는 두 함수가 같은 performance domain을 반환합니다.

CPU EM에 관심 있는 subsystem은 `em_cpu_get()`으로 가져옵니다. Performance domain 생성 때 한 번 할당된 EM table은 memory에 그대로 유지됩니다.

Performance domain의 소비 energy는 `em_cpu_energy()`로 추정할 수 있습니다. CPU device에서 `schedutil` CPUFreq governor를 사용한다고 가정하는 계산이며, 현재 다른 device type에는 이 계산이 제공되지 않습니다.

자세한 API는 `<linux/energy_model.h>` 또는 Section 2.5에 있습니다.

2.3 Accessing performance domains
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are two API functions which provide the access to the energy model:
em_cpu_get() which takes CPU id as an argument and em_pd_get() with device
pointer as an argument. It depends on the subsystem which interface it is
going to use, but in case of CPU devices both functions return the same
performance domain.

Subsystems interested in the energy model of a CPU can retrieve it using the
em_cpu_get() API. The energy model tables are allocated once upon creation of
the performance domains, and kept in memory untouched.

The energy consumed by a performance domain can be estimated using the
em_cpu_energy() API. The estimation is performed assuming that the schedutil
CPUfreq governor is in use in case of CPU device. Currently this calculation is
not provided for other type of devices.

More details about the above APIs can be found in ``<linux/energy_model.h>``
or in Section 2.5

Runtime table 할당·교체·해제·읽기

Runtime에서 EM을 갱신하려는 driver는 `em_table_alloc(struct em_perf_domain *pd)`로 수정된 EM의 새 인스턴스를 할당합니다. 반환된 `struct em_perf_table`에는 EM이 필요로 하는 RCU와 kref 정보, 그리고 frequency 오름차순의 `struct em_perf_state state[]` 배열이 들어 있습니다.

Driver는 boot 때 만든 기존 EM에서 frequency 목록을 가져올 수 있으며 새 `state[]`의 모든 내용을 채워야 합니다.

struct em_perf_table __rcu *em_table_alloc(struct em_perf_domain *pd);

`em_dev_update_perf_domain()`은 준비한 새 table로 RCU pointer를 교체합니다. Driver는 할당하고 초기화한 `struct em_perf_table` pointer를 전달해야 합니다. 새 EM은 framework 내부와 thermal·powercap 같은 다른 subsystem에 안전하게 공개됩니다.

int em_dev_update_perf_domain(struct device *dev,
        struct em_perf_table __rcu *new_table);

이 API는 runtime 추가 계산과 memory allocation을 피하도록 빠르게 설계되었습니다. Driver가 미리 계산한 여러 EM을 가지고 있다면 낮은 overhead로 재사용할 수 있습니다.

Module unload 등으로 driver가 제공한 EM 참조를 놓으려면 `em_table_free()`를 호출합니다. EAS 같은 다른 subsystem이 더 이상 사용하지 않을 때 framework가 memory를 안전하게 제거할 수 있게 합니다.

void em_table_free(struct em_perf_table __rcu *table);

Thermal·powercap 같은 다른 subsystem이 power 값을 읽을 때는 `em_perf_state_from_pd()`로 일관된 table data를 얻습니다. 반환값은 frequency 오름차순의 `struct em_perf_state` 배열입니다.

struct em_perf_state *em_perf_state_from_pd(struct em_perf_domain *pd);

이 함수는 `rcu_read_lock()` 뒤의 RCU read-side critical section에서 호출해야 합니다. Table 사용이 끝나면 원문 표기인 `rcu_real_unlock()`을 호출한다고 설명하지만, 뒤의 예제 코드는 `rcu_read_unlock()`을 사용합니다. 이 보호로 reader를 안전하게 유지하면서 framework가 이전 memory를 관리·해제할 수 있습니다. 사용 예는 Section 3.2에 있습니다.

2.4 Runtime modifications
^^^^^^^^^^^^^^^^^^^^^^^^^

Drivers willing to update the EM at runtime should use the following dedicated
function to allocate a new instance of the modified EM. The API is listed
below::

  struct em_perf_table __rcu *em_table_alloc(struct em_perf_domain *pd);

This allows to allocate a structure which contains the new EM table with
also RCU and kref needed by the EM framework. The 'struct em_perf_table'
contains array 'struct em_perf_state state[]' which is a list of performance
states in ascending order. That list must be populated by the device driver
which wants to update the EM. The list of frequencies can be taken from
existing EM (created during boot). The content in the 'struct em_perf_state'
must be populated by the driver as well.

This is the API which does the EM update, using RCU pointers swap::

  int em_dev_update_perf_domain(struct device *dev,
                        struct em_perf_table __rcu *new_table);

Drivers must provide a pointer to the allocated and initialized new EM
'struct em_perf_table'. That new EM will be safely used inside the EM framework
and will be visible to other sub-systems in the kernel (thermal, powercap).
The main design goal for this API is to be fast and avoid extra calculations
or memory allocations at runtime. When pre-computed EMs are available in the
device driver, then it should be possible to simply reuse them with low
performance overhead.

In order to free the EM, provided earlier by the driver (e.g. when the module
is unloaded), there is a need to call the API::

  void em_table_free(struct em_perf_table __rcu *table);

It will allow the EM framework to safely remove the memory, when there is
no other sub-system using it, e.g. EAS.

To use the power values in other sub-systems (like thermal, powercap) there is
a need to call API which protects the reader and provide consistency of the EM
table data::

  struct em_perf_state *em_perf_state_from_pd(struct em_perf_domain *pd);

It returns the 'struct em_perf_state' pointer which is an array of performance
states in ascending order.
This function must be called in the RCU read lock section (after the
rcu_read_lock()). When the EM table is not needed anymore there is a need to
call rcu_real_unlock(). In this way the EM safely uses the RCU read section
and protects the users. It also allows the EM framework to manage the memory
and free it. More details how to use it can be found in Section 3.2 in the
example driver.

EAS cost 계산과 kernel-doc

Device driver는 `em_dev_compute_costs()`로 `em_perf_state::cost` 값을 계산할 수 있습니다.

int em_dev_compute_costs(struct device *dev, struct em_perf_state *table,
                         int nr_states);

EAS는 이 cost 값을 사용합니다. 새 EM table, 항목 수, device pointer를 전달하며 계산에 성공하면 0을 반환합니다.

함수는 각 performance state의 inefficiency 설정도 처리하고 `em_perf_state::flags`를 갱신합니다. 이렇게 준비한 새 EM을 `em_dev_update_perf_domain()`에 전달하면 사용할 수 있습니다.

상세 API는 `<linux/energy_model.h>`와 Section 3.2의 간단한 update 예제를 참조합니다. 문서는 `include/linux/energy_model.h`의 internal kernel-doc과 `kernel/power/energy_model.c`의 exported kernel-doc을 포함합니다.

There is dedicated API for device drivers to calculate em_perf_state::cost
values::

  int em_dev_compute_costs(struct device *dev, struct em_perf_state *table,
                           int nr_states);

These 'cost' values from EM are used in EAS. The new EM table should be passed
together with the number of entries and device pointer. When the computation
of the cost values is done properly the return value from the function is 0.
The function takes care for right setting of inefficiency for each performance
state as well. It updates em_perf_state::flags accordingly.
Then such prepared new EM can be passed to the em_dev_update_perf_domain()
function, which will allow to use it.

More details about the above APIs can be found in ``<linux/energy_model.h>``
or in Section 3.2 with an example code showing simple implementation of the
updating mechanism in a device driver.


2.5 Description details of this API
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/linux/energy_model.h
   :internal:

.. kernel-doc:: kernel/power/energy_model.c
   :export:

CPUFreq driver 등록 예제

CPUFreq framework는 CPU policy의 EM을 등록하는 전용 callback `cpufreq_driver::register_em()`을 지원합니다. Framework가 setup 중 올바른 시점에 호출하므로 각 driver가 이를 구현해야 합니다.

예제 `drivers/cpufreq/foo_cpufreq.c`의 `est_power()`는 가상의 `foo` protocol로 요청 KHz 이상의 지원 frequency를 고르고 해당 frequency의 power를 추정합니다. 오류는 그대로 반환하고, 성공하면 `*mW`와 `*KHz`를 EM framework에 돌려줍니다.

`foo_cpufreq_register_em()`은 policy cpumask의 첫 CPU device를 얻고 OPP 수를 센 뒤 `em_dev_register_perf_domain(cpu_dev, nr_opp, &em_cb, policy->cpus, true)`로 micro-Watts domain을 등록합니다. 마지막으로 이 함수를 `foo_cpufreq_driver.register_em`에 연결합니다.

3. Examples
-----------

3.1 Example driver with EM registration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The CPUFreq framework supports dedicated callback for registering
the EM for a given CPU(s) 'policy' object: cpufreq_driver::register_em().
That callback has to be implemented properly for a given driver,
because the framework would call it at the right time during setup.
This section provides a simple example of a CPUFreq driver registering a
performance domain in the Energy Model framework using the (fake) 'foo'
protocol. The driver implements an est_power() function to be provided to the
EM framework::

  -> drivers/cpufreq/foo_cpufreq.c

  01        static int est_power(struct device *dev, unsigned long *mW,
  02                        unsigned long *KHz)
  03        {
  04                long freq, power;
  05
  06                /* Use the 'foo' protocol to ceil the frequency */
  07                freq = foo_get_freq_ceil(dev, *KHz);
  08                if (freq < 0);
  09                        return freq;
  10
  11                /* Estimate the power cost for the dev at the relevant freq. */
  12                power = foo_estimate_power(dev, freq);
  13                if (power < 0);
  14                        return power;
  15
  16                /* Return the values to the EM framework */
  17                *mW = power;
  18                *KHz = freq;
  19
  20                return 0;
  21        }
  22
  23        static void foo_cpufreq_register_em(struct cpufreq_policy *policy)
  24        {
  25                struct em_data_callback em_cb = EM_DATA_CB(est_power);
  26                struct device *cpu_dev;
  27                int nr_opp;
  28
  29                cpu_dev = get_cpu_device(cpumask_first(policy->cpus));
  30
  31             /* Find the number of OPPs for this policy */
  32             nr_opp = foo_get_nr_opp(policy);
  33
  34             /* And register the new performance domain */
  35             em_dev_register_perf_domain(cpu_dev, nr_opp, &em_cb, policy->cpus,
  36                                            true);
  37        }
  38
  39        static struct cpufreq_driver foo_cpufreq_driver = {
  40                .register_em = foo_cpufreq_register_em,
  41        };

Thermal driver 수정 예제

예제 `drivers/soc/example/example_em_mod.c`는 주기적으로 깨어 온도를 확인하고 필요하면 EM을 수정하는 thermal driver를 보여 줍니다.

`foo_get_new_em()`은 `em_pd_get(dev)`로 domain을 얻고 `em_table_alloc(pd)`로 새 table을 할당합니다. RCU read lock 안에서 기존 table의 frequency를 순회하며 `foo_get_power_perf_values()`로 새 state의 power·performance 값을 채웁니다.

그다음 `em_dev_compute_costs()`로 EAS cost를 계산합니다. 실패하면 warning을 기록하고 `em_table_free()`로 table을 놓습니다. 성공하면 `em_dev_update_perf_domain()`으로 교체하고, 이 단계가 실패해도 같은 방식으로 정리합니다.

Update가 성공한 뒤에도 one-time update를 제공한 driver의 usage counter를 내리기 위해 `em_table_free(em_table)`을 호출합니다. 실제 table memory는 다른 사용자가 사라진 뒤 EM framework가 해제합니다.

주기적으로 호출되는 `foo_thermal_em_update()`는 현재 temperature를 읽고 `FOO_EM_UPDATE_TEMP_THRESHOLD`보다 낮으면 반환합니다. Threshold 이상이면 `foo_get_new_em(ctx)`로 새 temperature 조건의 EM을 계산해 설치합니다.

3.2 Example driver with EM modification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This section provides a simple example of a thermal driver modifying the EM.
The driver implements a foo_thermal_em_update() function. The driver is woken
up periodically to check the temperature and modify the EM data::

  -> drivers/soc/example/example_em_mod.c

  01        static void foo_get_new_em(struct foo_context *ctx)
  02        {
  03                struct em_perf_table __rcu *em_table;
  04                struct em_perf_state *table, *new_table;
  05                struct device *dev = ctx->dev;
  06                struct em_perf_domain *pd;
  07                unsigned long freq;
  08                int i, ret;
  09
  10                pd = em_pd_get(dev);
  11                if (!pd)
  12                        return;
  13
  14                em_table = em_table_alloc(pd);
  15                if (!em_table)
  16                        return;
  17
  18                new_table = em_table->state;
  19
  20                rcu_read_lock();
  21                table = em_perf_state_from_pd(pd);
  22                for (i = 0; i < pd->nr_perf_states; i++) {
  23                        freq = table[i].frequency;
  24                        foo_get_power_perf_values(dev, freq, &new_table[i]);
  25                }
  26                rcu_read_unlock();
  27
  28                /* Calculate 'cost' values for EAS */
  29                ret = em_dev_compute_costs(dev, new_table, pd->nr_perf_states);
  30                if (ret) {
  31                        dev_warn(dev, "EM: compute costs failed %d\n", ret);
  32                        em_table_free(em_table);
  33                        return;
  34                }
  35
  36                ret = em_dev_update_perf_domain(dev, em_table);
  37                if (ret) {
  38                        dev_warn(dev, "EM: update failed %d\n", ret);
  39                        em_table_free(em_table);
  40                        return;
  41                }
  42
  43                /*
  44                 * Since it's one-time-update drop the usage counter.
  45                 * The EM framework will later free the table when needed.
  46                 */
  47                em_table_free(em_table);
  48        }
  49
  50        /*
  51         * Function called periodically to check the temperature and
  52         * update the EM if needed
  53         */
  54        static void foo_thermal_em_update(struct foo_context *ctx)
  55        {
  56                struct device *dev = ctx->dev;
  57                int cpu;
  58
  59                ctx->temperature = foo_get_temp(dev, ctx);
  60                if (ctx->temperature < FOO_EM_UPDATE_TEMP_THRESHOLD)
  61                        return;
  62
  63                foo_get_new_em(ctx);
  64        }