From dd774a07ddfcb4dfe15778ea30cd5bb592ffab29 Mon Sep 17 00:00:00 2001 From: Tang Yizhou Date: Wed, 29 Dec 2021 10:42:12 +0800 Subject: [PATCH] docs/zh_CN: Add opp Chinese translation Translate power/opp.rst into Chinese. Signed-off-by: Tang Yizhou Reviewed-by: Alex Shi Reviewed-by: Yanteng Si Link: https://lore.kernel.org/r/20211229024212.32752-4-tangyizhou@huawei.com Signed-off-by: Jonathan Corbet --- Documentation/translations/zh_CN/power/index.rst | 3 +- Documentation/translations/zh_CN/power/opp.rst | 341 +++++++++++++++++++++++ 2 files changed, 343 insertions(+), 1 deletion(-) create mode 100644 Documentation/translations/zh_CN/power/opp.rst diff --git a/Documentation/translations/zh_CN/power/index.rst b/Documentation/translations/zh_CN/power/index.rst index fd379ad..ad80a9e 100644 --- a/Documentation/translations/zh_CN/power/index.rst +++ b/Documentation/translations/zh_CN/power/index.rst @@ -14,6 +14,8 @@ .. toctree:: :maxdepth: 1 + opp + TODOList: * apm-acpi @@ -22,7 +24,6 @@ TODOList: * drivers-testing * energy-model * freezing-of-tasks - * opp * pci * pm_qos_interface * power_supply_class diff --git a/Documentation/translations/zh_CN/power/opp.rst b/Documentation/translations/zh_CN/power/opp.rst new file mode 100644 index 0000000..8d6e3f6 --- /dev/null +++ b/Documentation/translations/zh_CN/power/opp.rst @@ -0,0 +1,341 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/power/opp.rst + +:翻译: + + 唐艺舟 Tang Yizhou + +====================== +操作性能值（OPP）库 +====================== + +(C) 2009-2010 Nishanth Menon , 德州仪器公司 + +.. 目录 + + 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 = kzalloc(sizeof(u32) * num_available, 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 -- 2.7.4