lastdragon/linux-kernel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Resguardo inicial

Browse Source
This commit is contained in:
lastdragon
2026-09-06 12:53:21 -06:00
parent 662efe3c2a
commit ad2088d178
94853 changed files with 43200404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
linux-7.2.3/Documentation/translations/zh_CN/power/energy-model.rst
+210
View File
@@ -0,0 +1,210 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
:Original: Documentation/power/energy-model.rst
:翻译:
唐艺舟 Tang Yizhou <tangyeechou@gmail.com>
============
设备能量模型
============
1. 概述
-------
能量模型（EM）框架是一种驱动程序与内核子系统之间的接口。其中驱动程序了解不同
性能层级的设备所消耗的功率，而内核子系统愿意使用该信息做出能量感知决策。
设备所消耗的功率的信息来源在不同的平台上可能有很大的不同。这些功率成本在某些
情况下可以使用设备树数据来估算。在其它情况下，固件会更清楚。或者，用户空间可能
是最清楚的。以此类推。为了避免每一个客户端子系统对每一种可能的信息源自己重新
实现支持，EM框架作为一个抽象层介入，它在内核中对功率成本表的格式进行标准化，
因此能够避免多余的工作。
功率值可以用微瓦或“抽象刻度”表示。多个子系统可能使用EM，由系统集成商来检查
功率值刻度类型的要求是否满足。可以在能量感知调度器的文档中找到一个例子
Documentation/scheduler/sched-energy.rst。对于一些子系统，比如热能或
powercap，用“抽象刻度”描述功率值可能会导致问题。这些子系统对过去使用的功率的
估算值更感兴趣，因此可能需要真实的微瓦。这些要求的一个例子可以在智能功率分配
Documentation/driver-api/thermal/power_allocator.rst文档中找到。
内核子系统可能（基于EM内部标志位）实现了对EM注册设备是否具有不一致刻度的自动
检查。要记住的重要事情是，当功率值以“抽象刻度”表示时，从中推导以微焦耳为单位
的真实能量消耗是不可能的。
下图描述了一个驱动的例子（这里是针对Arm的，但该方法适用于任何体系结构），它
向EM框架提供了功率成本，感兴趣的客户端可从中读取数据::
+---------------+ +-----------------+ +---------------+
| 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 | | ? |
+--------------+ +---------------+ +--------------+
对于CPU设备，EM框架管理着系统中每个“性能域”的功率成本表。一个性能域是一组
性能一起伸缩的CPU。性能域通常与CPUFreq策略具有1对1映射。一个性能域中的
所有CPU要求具有相同的微架构。不同性能域中的CPU可以有不同的微架构。
2. 核心API
----------
2.1 配置选项
^^^^^^^^^^^^
必须使能CONFIG_ENERGY_MODEL才能使用EM框架。
2.2 性能域的注册
^^^^^^^^^^^^^^^^
“高级”EM的注册
~~~~~~~~~~~~~~~~
“高级”EM因它允许驱动提供更精确的功率模型而得名。它并不受限于框架中的一些已
实现的数学公式（就像“简单”EM那样）。它可以更好地反映每个性能状态的实际功率
测量。因此，在EM静态功率（漏电流功率）是重要的情况下，应该首选这种注册方式。
驱动程序应通过以下API将性能域注册到EM框架中::
int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states,
struct em_data_callback *cb, cpumask_t *cpus, bool microwatts);
驱动程序必须提供一个回调函数，为每个性能状态返回<频率,功率>元组。驱动程序
提供的回调函数可以自由地从任何相关位置（DT、固件......）以及以任何被认为是
必要的方式获取数据。只有对于CPU设备，驱动程序必须使用cpumask指定性能域的CPU。
对于CPU以外的其他设备，最后一个参数必须被设置为NULL。
最后一个参数“microwatts”（微瓦）设置成正确的值是很重要的，使用EM的内核
子系统可能会依赖这个标志来检查所有的EM设备是否使用相同的刻度。如果有不同的
刻度，这些子系统可能决定返回警告/错误，停止工作或崩溃（panic）。
关于实现这个回调函数的驱动程序的例子，参见第3节。或者在第2.4节阅读这个API
的更多文档。
使用DT的EM注册
==============
EM也可以使用OPP框架和DT "操作点-v2 "中的信息注册。DT中的每个OPP条目都可
以用一个包含微瓦特功率值的属性 "op-microwatt "来扩展。这个OPP DT属性允
许平台注册反映总功率（静态+动态）的EM功率值。这些功率值可能直接来自实验和
测量。
“人工”EM的注册
==============
有一个选项可以为缺少关于每个性能状态的功率值的详细知识的驱动程序提供一个自
定义回调。回调.get_cost()是可选的，它提供EAS使用的“成本”值。这对那些只提
供CPU类型之间相对效率信息的平台很有用，人们可以利用这些信息来创建一个抽象的
功率模型。但是，考虑到输入功率值的大小限制，即使是抽象的功率模型有时也很难装
进去。.get_cost()允许提供反映CPU效率的“成本”值。这将允许提供EAS信息，它
与EM内部计算'成本'值的公式有不同的关系。要为这样的平台注册EM，驱动程序必须
将标志“microwatts”设置为0，提供.get_power()回调和.get_cost()回调。EM
框架会在注册过程中正确处理这样的平台。这种平台会被设置EM_PERF_DOMAIN_ARTIFICIAL
标志。其他使用EM的框架应该特别注意测试和正确对待这个标志。
“简单”EM的注册
~~~~~~~~~~~~~~~~
“简单”EM是用框架的辅助函数cpufreq_register_em_with_opp()注册的。它实现了
一个和以下数学公式紧密相关的功率模型::
Power = C * V^2 * f
使用这种方法注册的EM可能无法正确反映真实设备的物理特性，例如当静态功率
（漏电流功率）很重要时。
2.3 访问性能域
^^^^^^^^^^^^^^
有两个API函数提供对能量模型的访问。em_cpu_get()以CPU id为参数，em_pd_get()
以设备指针为参数。使用哪个接口取决于子系统，但对于CPU设备来说，这两个函数都返
回相同的性能域。
对CPU的能量模型感兴趣的子系统可以通过em_cpu_get() API检索它。在创建性能域时
分配一次能量模型表，它保存在内存中不被修改。
一个性能域所消耗的能量可以使用em_cpu_energy() API来估算。该估算假定CPU设备
使用的CPUfreq监管器是schedutil。当前该计算不能提供给其它类型的设备。
关于上述API的更多细节可以在 ``<linux/energy_model.h>`` 或第2.4节中找到。
2.4 API的细节描述
^^^^^^^^^^^^^^^^^
参见 include/linux/energy_model.h 和 kernel/power/energy_model.c 的kernel doc。
3. 驱动示例
-----------
CPUFreq框架支持专用的回调函数，用于为指定的CPU（们）注册EM：
cpufreq_driver::register_em()。这个回调必须为每个特定的驱动程序正确实现，
因为框架会在设置过程中适时地调用它。本节提供了一个简单的例子，展示CPUFreq驱动
在能量模型框架中使用（假的）“foo”协议注册性能域。该驱动实现了一个est_power()
函数提供给EM框架::
-> 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 /* 使用“foo”协议设置频率上限 */
07 freq = foo_get_freq_ceil(dev, *KHz);
08 if (freq < 0);
09 return freq;
10
11 /* 估算相关频率下设备的功率成本 */
12 power = foo_estimate_power(dev, freq);
13 if (power < 0);
14 return power;
15
16 /* 将这些值返回给EM框架 */
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 /* 查找该策略支持的OPP数量 */
32 nr_opp = foo_get_nr_opp(policy);
33
34 /* 并注册新的性能域 */
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 };
linux-7.2.3/Documentation/translations/zh_CN/power/index.rst
+56
View File
@@ -0,0 +1,56 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
:Original: Documentation/power/index.rst
:翻译:
唐艺舟 Tang Yizhou <tangyeechou@gmail.com>
========
电源管理
========
.. toctree::
:maxdepth: 1
energy-model
opp
TODOList:
* apm-acpi
* basic-pm-debugging
* charger-manager
* drivers-testing
* freezing-of-tasks
* pci
* pm_qos_interface
* power_supply_class
* runtime_pm
* s2ram
* suspend-and-cpuhotplug
* suspend-and-interrupts
* swsusp-and-swap-files
* swsusp-dmcrypt
* swsusp
* video
* tricks
* userland-swsusp
* powercap/powercap
* powercap/dtpm
* regulator/consumer
* regulator/design
* regulator/machine
* regulator/overview
* regulator/regulator
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
linux-7.2.3/Documentation/translations/zh_CN/power/opp.rst
+341
View File
@@ -0,0 +1,341 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
:Original: Documentation/power/opp.rst
:翻译:
唐艺舟 Tang Yizhou <tangyeechou@gmail.com>
======================
操作性能值（OPP）库
======================
(C) 2009-2010 Nishanth Menon <nm@ti.com>, 德州仪器公司
.. 目录
1. 简介
2. OPP链表初始注册
3. OPP搜索函数
4. OPP可用性控制函数
5. OPP数据检索函数
6. 数据结构
1. 简介
=======
1.1 何为操作性能值（OPP）？
------------------------------
当今复杂的单片系统（SoC）由多个子模块组成，这些子模块会联合工作。在一个执行不同用例
的操作系统中，并不是SoC中的所有模块都需要一直以最高频率工作。为了促成这一点，SoC中
的子模块被分组为不同域，允许一些域以较低的电压和频率运行，而其它域则以较高的“电压/
频率对”运行。
设备按域支持的由频率电压对组成的离散的元组的集合，被称为操作性能值（组），或OPPs。
举例来说：
让我们考虑一个支持下述频率、电压值的内存保护单元（MPU）设备：
{300MHz，最低电压为1V}, {800MHz，最低电压为1.2V}, {1GHz，最低电压为1.3V}
我们能将它们表示为3个OPP，如下述{Hz, uV}元组（译注：频率的单位是赫兹，电压的单位是
微伏）。
- {300000000, 1000000}
- {800000000, 1200000}
- {1000000000, 1300000}
1.2 操作性能值库
----------------
OPP库提供了一组辅助函数来组织和查询OPP信息。该库位于drivers/opp/目录下，其头文件
位于include/linux/pm_opp.h中。OPP库可以通过开启CONFIG_PM_OPP来启用。某些SoC，
如德州仪器的OMAP框架允许在不需要cpufreq的情况下可选地在某一OPP下启动。
OPP库的典型用法如下::
（用户） -> 注册一个默认的OPP集合 -> （库）
（SoC框架） -> 在必要的情况下，对某些OPP进行修改 -> OPP layer
-> 搜索/检索信息的查询 ->
OPP层期望每个域由一个唯一的设备指针来表示。SoC框架在OPP层为每个设备注册了一组初始
OPP。这个链表的长度被期望是一个最优化的小数字，通常每个设备大约5个。初始链表包含了
一个OPP集合，这个集合被期望能在系统中安全使能。
关于OPP可用性的说明
^^^^^^^^^^^^^^^^^^^
随着系统的运行，SoC框架可能会基于各种外部因素选择让某些OPP在每个设备上可用或不可用，
示例：温度管理或其它异常场景中，SoC框架可能会选择禁用一个较高频率的OPP以安全地继续
运行，直到该OPP被重新启用（如果可能）。
OPP库在它的实现中达成了这个概念。以下操作函数只能对可用的OPP使用：
dev_pm_opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage,
dev_pm_opp_get_freq, dev_pm_opp_get_opp_count。
dev_pm_opp_find_freq_exact是用来查找OPP指针的，该指针可被用在dev_pm_opp_enable/
disable函数，使一个OPP在被需要时变为可用。
警告：如果对一个设备调用dev_pm_opp_enable/disable函数，OPP库的用户应该使用
dev_pm_opp_get_opp_count来刷新OPP的可用性计数。触发这些的具体机制，或者对有依赖的
子系统（比如cpufreq）的通知机制，都是由使用OPP库的SoC特定框架酌情处理的。在这些操作
中，同样需要注意刷新cpufreq表。
2. OPP链表初始注册
==================
SoC的实现会迭代调用dev_pm_opp_add函数来增加每个设备的OPP。预期SoC框架将以最优的
方式注册OPP条目 - 典型的数字范围小于5。通过注册OPP生成的OPP链表，在整个设备运行过程
中由OPP库维护。SoC框架随后可以使用dev_pm_opp_enable / disable函数动态地
控制OPP的可用性。
dev_pm_opp_add
为设备指针所指向的特定域添加一个新的OPP。OPP是用频率和电压定义的。一旦完成
添加，OPP被认为是可用的，可以用dev_pm_opp_enable/disable函数来控制其可用性。
OPP库内部用dev_pm_opp结构体存储并管理这些信息。这个函数可以被SoC框架根据SoC
的使用环境的需求来定义一个最优链表。
警告：
不要在中断上下文使用这个函数。
示例::
soc_pm_init()
{
/* 做一些事情 */
r = dev_pm_opp_add(mpu_dev, 1000000, 900000);
if (!r) {
pr_err("%s: unable to register mpu opp(%d)\n", r);
goto no_cpufreq;
}
/* 做一些和cpufreq相关的事情 */
no_cpufreq:
/* 做剩余的事情 */
}
3. OPP搜索函数
==============
cpufreq等高层框架对频率进行操作，为了将频率映射到相应的OPP，OPP库提供了便利的函数
来搜索OPP库内部管理的OPP链表。这些搜索函数如果找到匹配的OPP，将返回指向该OPP的指针，
否则返回错误。这些错误预计由标准的错误检查，如IS_ERR()来处理，并由调用者采取适当的
行动。
这些函数的调用者应在使用完OPP后调用dev_pm_opp_put()。否则，OPP的内存将永远不会
被释放，并导致内存泄露。
dev_pm_opp_find_freq_exact
根据 *精确的* 频率和可用性来搜索OPP。这个函数对默认不可用的OPP特别有用。
例子：在SoC框架检测到更高频率可用的情况下，它可以使用这个函数在调用
dev_pm_opp_enable之前找到OPP::
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
dev_pm_opp_put(opp);
/* 不要操作指针.. 只是做有效性检查.. */
if (IS_ERR(opp)) {
pr_err("frequency not disabled!\n");
/* 触发合适的操作.. */
} else {
dev_pm_opp_enable(dev,1000000000);
}
注意：
这是唯一一个可以搜索不可用OPP的函数。
dev_pm_opp_find_freq_floor
搜索一个 *最多* 提供指定频率的可用OPP。这个函数在搜索较小的匹配或按频率
递减的顺序操作OPP信息时很有用。
例子：要找的一个设备的最高OPP::
freq = ULONG_MAX;
opp = dev_pm_opp_find_freq_floor(dev, &freq);
dev_pm_opp_put(opp);
dev_pm_opp_find_freq_ceil
搜索一个 *最少* 提供指定频率的可用OPP。这个函数在搜索较大的匹配或按频率
递增的顺序操作OPP信息时很有用。
例1：找到一个设备最小的OPP::
freq = 0;
opp = dev_pm_opp_find_freq_ceil(dev, &freq);
dev_pm_opp_put(opp);
例: 一个SoC的cpufreq_driver->target的简易实现::
soc_cpufreq_target(..)
{
/* 做策略检查等操作 */
/* 找到和请求最接近的频率 */
opp = dev_pm_opp_find_freq_ceil(dev, &freq);
dev_pm_opp_put(opp);
if (!IS_ERR(opp))
soc_switch_to_freq_voltage(freq);
else
/* 当不能满足请求时，要做的事 */
/* 做其它事 */
}
4. OPP可用性控制函数
====================
在OPP库中注册的默认OPP链表也许无法满足所有可能的场景。OPP库提供了一套函数来修改
OPP链表中的某个OPP的可用性。这使得SoC框架能够精细地动态控制哪一组OPP是可用于操作
的。设计这些函数的目的是在诸如考虑温度时 *暂时地* 删除某个OPP（例如，在温度下降
之前不要使用某OPP）。
警告：
不要在中断上下文使用这些函数。
dev_pm_opp_enable
使一个OPP可用于操作。
例子：假设1GHz的OPP只有在SoC温度低于某个阈值时才可用。SoC框架的实现可能
会选择做以下事情::
if (cur_temp < temp_low_thresh) {
/* 若1GHz未使能，则使能 */
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
dev_pm_opp_put(opp);
/* 仅仅是错误检查 */
if (!IS_ERR(opp))
ret = dev_pm_opp_enable(dev, 1000000000);
else
goto try_something_else;
}
dev_pm_opp_disable
使一个OPP不可用于操作。
例子：假设1GHz的OPP只有在SoC温度高于某个阈值时才可用。SoC框架的实现可能
会选择做以下事情::
if (cur_temp > temp_high_thresh) {
/* 若1GHz已使能，则关闭 */
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
dev_pm_opp_put(opp);
/* 仅仅是错误检查 */
if (!IS_ERR(opp))
ret = dev_pm_opp_disable(dev, 1000000000);
else
goto try_something_else;
}
5. OPP数据检索函数
==================
由于OPP库对OPP信息进行了抽象化处理，因此需要一组函数来从dev_pm_opp结构体中提取
信息。一旦使用搜索函数检索到一个OPP指针，以下函数就可以被SoC框架用来检索OPP层
内部描述的信息。
dev_pm_opp_get_voltage
检索OPP指针描述的电压。
例子: 当cpufreq切换到到不同频率时，SoC框架需要用稳压器框架将OPP描述
的电压设置到提供电压的电源管理芯片中::
soc_switch_to_freq_voltage(freq)
{
/* 做一些事情 */
opp = dev_pm_opp_find_freq_ceil(dev, &freq);
v = dev_pm_opp_get_voltage(opp);
dev_pm_opp_put(opp);
if (v)
regulator_set_voltage(.., v);
/* 做其它事 */
}
dev_pm_opp_get_freq
检索OPP指针描述的频率。
例子：比方说，SoC框架使用了几个辅助函数，通过这些函数，我们可以将OPP
指针传入，而不是传入额外的参数，用来处理一系列数据参数::
soc_cpufreq_target(..)
{
/* 做一些事情.. */
max_freq = ULONG_MAX;
max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq);
requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq);
if (!IS_ERR(max_opp) && !IS_ERR(requested_opp))
r = soc_test_validity(max_opp, requested_opp);
dev_pm_opp_put(max_opp);
dev_pm_opp_put(requested_opp);
/* 做其它事 */
}
soc_test_validity(..)
{
if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp))
return -EINVAL;
if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp))
return -EINVAL;
/* 做一些事情.. */
}
dev_pm_opp_get_opp_count
检索某个设备可用的OPP数量。
例子：假设SoC中的一个协处理器需要知道某个表中的可用频率，主处理器可以
按如下方式发出通知::
soc_notify_coproc_available_frequencies()
{
/* 做一些事情 */
num_available = dev_pm_opp_get_opp_count(dev);
speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL);
/* 按升序填充表 */
freq = 0;
while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
speeds[i] = freq;
freq++;
i++;
dev_pm_opp_put(opp);
}
soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available);
/* 做其它事 */
}
6. 数据结构
===========
通常，一个SoC包含多个可变电压域。每个域由一个设备指针描述。和OPP之间的关系可以
按以下方式描述::
SoC
|- device 1
| |- opp 1 (availability, freq, voltage)
| |- opp 2 ..
... ...
| `- opp n ..
|- device 2
...
`- device m
OPP库维护着一个内部链表，SoC框架使用上文描述的各个函数来填充和访问。然而，描述
真实OPP和域的结构体是OPP库自身的内部组成，以允许合适的抽象在不同系统中得到复用。
struct dev_pm_opp
OPP库的内部数据结构，用于表示一个OPP。除了频率、电压、可用性信息外，
它还包含OPP库运行所需的内部统计信息。指向这个结构体的指针被提供给
用户（比如SoC框架）使用，在与OPP层的交互中作为OPP的标识符。
警告：
结构体dev_pm_opp的指针不应该由用户解析或修改。一个实例的默认值由
dev_pm_opp_add填充，但OPP的可用性由dev_pm_opp_enable/disable函数
修改。
struct device
这用于向OPP层标识一个域。设备的性质和它的实现是由OPP库的用户决定的，
如SoC框架。
总体来说，以一个简化的视角看，对数据结构的操作可以描述为下面各图::
初始化 / 修改:
+-----+ /- dev_pm_opp_enable
dev_pm_opp_add --> | opp | <-------
| +-----+ \- dev_pm_opp_disable
\-------> domain_info(device)
搜索函数:
/-- dev_pm_opp_find_freq_ceil ---\ +-----+
domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
\-- dev_pm_opp_find_freq_floor ---/ +-----+
检索函数:
+-----+ /- dev_pm_opp_get_voltage
| opp | <---
+-----+ \- dev_pm_opp_get_freq
domain_info <- dev_pm_opp_get_opp_count