* [PATCH v2 0/3] Translate opp into Chinese
@ 2021-12-28 2:14 Tang Yizhou
2021-12-28 2:14 ` [PATCH v2 1/3] docs/zh_CN: Cleanup index.rst Tang Yizhou
` (2 more replies)
0 siblings, 3 replies; 7+ messages in thread
From: Tang Yizhou @ 2021-12-28 2:14 UTC (permalink / raw)
To: siyanteng, siyanteng01, alexs, seakeel
Cc: linux-doc, corbet, zhengbin13, tangyeechou, Tang Yizhou
Translate power/index.rst and power/opp.rst into Chinese.
v2:
1. Split a cleanup patch for index.rst.
2. Pick Alex's Reviewed-by tags.
Tang Yizhou (3):
docs/zh_CN: Cleanup index.rst
docs/zh_CN: Add power/index Chinese translation
docs/zh_CN: Add opp Chinese translation
Documentation/translations/zh_CN/index.rst | 8 +-
.../translations/zh_CN/power/index.rst | 56 +++
.../translations/zh_CN/power/opp.rst | 341 ++++++++++++++++++
3 files changed, 401 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/zh_CN/power/index.rst
create mode 100644 Documentation/translations/zh_CN/power/opp.rst
--
2.17.1
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH v2 1/3] docs/zh_CN: Cleanup index.rst
2021-12-28 2:14 [PATCH v2 0/3] Translate opp into Chinese Tang Yizhou
@ 2021-12-28 2:14 ` Tang Yizhou
2021-12-28 7:11 ` yanteng si
2021-12-28 2:14 ` [PATCH v2 2/3] docs/zh_CN: Add power/index Chinese translation Tang Yizhou
2021-12-28 2:14 ` [PATCH v2 3/3] docs/zh_CN: Add opp " Tang Yizhou
2 siblings, 1 reply; 7+ messages in thread
From: Tang Yizhou @ 2021-12-28 2:14 UTC (permalink / raw)
To: siyanteng, siyanteng01, alexs, seakeel
Cc: linux-doc, corbet, zhengbin13, tangyeechou, Tang Yizhou
The Chinese version of many */index is not in the same order as the
English version. Put them to where they should be.
Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
---
Documentation/translations/zh_CN/index.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
index 46e14ec9963d..e7f5fa3e7502 100644
--- a/Documentation/translations/zh_CN/index.rst
+++ b/Documentation/translations/zh_CN/index.rst
@@ -104,13 +104,13 @@ TODOList:
:maxdepth: 2
core-api/index
+ accounting/index
cpu-freq/index
iio/index
+ infiniband/index
+ virt/index
sound/index
filesystems/index
- virt/index
- infiniband/index
- accounting/index
scheduler/index
TODOList:
--
2.17.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH v2 2/3] docs/zh_CN: Add power/index Chinese translation
2021-12-28 2:14 [PATCH v2 0/3] Translate opp into Chinese Tang Yizhou
2021-12-28 2:14 ` [PATCH v2 1/3] docs/zh_CN: Cleanup index.rst Tang Yizhou
@ 2021-12-28 2:14 ` Tang Yizhou
2021-12-28 7:11 ` yanteng si
2021-12-28 2:14 ` [PATCH v2 3/3] docs/zh_CN: Add opp " Tang Yizhou
2 siblings, 1 reply; 7+ messages in thread
From: Tang Yizhou @ 2021-12-28 2:14 UTC (permalink / raw)
To: siyanteng, siyanteng01, alexs, seakeel
Cc: linux-doc, corbet, zhengbin13, tangyeechou, Tang Yizhou
Translate power/index.rst into Chinese.
Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
Reviewed-by: Alex Shi <alexs@kernel.org>
---
Documentation/translations/zh_CN/index.rst | 2 +-
.../translations/zh_CN/power/index.rst | 55 +++++++++++++++++++
2 files changed, 56 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/power/index.rst
diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
index e7f5fa3e7502..08144252630c 100644
--- a/Documentation/translations/zh_CN/index.rst
+++ b/Documentation/translations/zh_CN/index.rst
@@ -108,6 +108,7 @@ TODOList:
cpu-freq/index
iio/index
infiniband/index
+ power/index
virt/index
sound/index
filesystems/index
@@ -129,7 +130,6 @@ TODOList:
* netlabel/index
* networking/index
* pcmcia/index
-* power/index
* target/index
* timers/index
* spi/index
diff --git a/Documentation/translations/zh_CN/power/index.rst b/Documentation/translations/zh_CN/power/index.rst
new file mode 100644
index 000000000000..fd379adfda8e
--- /dev/null
+++ b/Documentation/translations/zh_CN/power/index.rst
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/power/index.rst
+
+:翻译:
+
+ 唐艺舟 Tang Yizhou <tangyeechou@gmail.com>
+
+========
+电源管理
+========
+
+.. toctree::
+ :maxdepth: 1
+
+TODOList:
+
+ * apm-acpi
+ * basic-pm-debugging
+ * charger-manager
+ * drivers-testing
+ * energy-model
+ * freezing-of-tasks
+ * opp
+ * 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`
--
2.17.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH v2 3/3] docs/zh_CN: Add opp Chinese translation
2021-12-28 2:14 [PATCH v2 0/3] Translate opp into Chinese Tang Yizhou
2021-12-28 2:14 ` [PATCH v2 1/3] docs/zh_CN: Cleanup index.rst Tang Yizhou
2021-12-28 2:14 ` [PATCH v2 2/3] docs/zh_CN: Add power/index Chinese translation Tang Yizhou
@ 2021-12-28 2:14 ` Tang Yizhou
2021-12-28 8:00 ` yanteng si
2 siblings, 1 reply; 7+ messages in thread
From: Tang Yizhou @ 2021-12-28 2:14 UTC (permalink / raw)
To: siyanteng, siyanteng01, alexs, seakeel
Cc: linux-doc, corbet, zhengbin13, tangyeechou, Tang Yizhou
Translate power/opp.rst into Chinese.
Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
Reviewed-by: Alex Shi <alexs@kernel.org>
---
.../translations/zh_CN/power/index.rst | 3 +-
.../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 fd379adfda8e..ad80a9e80b7c 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 000000000000..0aa65b2774f4
--- /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 <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()
+ {
+ /* Do things */
+ 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;
+ }
+ /* Do cpufreq things */
+ no_cpufreq:
+ /* Do remaining things */
+ }
+
+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);
+ /* dont operate on the pointer.. just do a sanity check.. */
+ if (IS_ERR(opp)) {
+ pr_err("frequency not disabled!\n");
+ /* trigger appropriate actions.. */
+ } 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(..)
+ {
+ /* Do stuff like policy checks etc. */
+ /* Find the best frequency match for the req */
+ 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
+ /* do something when we can't satisfy the req */
+ /* do other stuff */
+ }
+
+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) {
+ /* Enable 1GHz if it was disabled */
+ opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
+ dev_pm_opp_put(opp);
+ /* just error check */
+ 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) {
+ /* Disable 1GHz if it was enabled */
+ opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
+ dev_pm_opp_put(opp);
+ /* just error check */
+ 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)
+ {
+ /* do things */
+ 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);
+ /* do other things */
+ }
+
+dev_pm_opp_get_freq
+ 检索OPP指针描述的频率。
+ 例子:比方说,SoC框架使用了几个辅助函数,通过这些函数,我们可以将OPP
+ 指针传入,而不是传入额外的参数,用来处理一系列数据参数::
+
+ soc_cpufreq_target(..)
+ {
+ /* do things.. */
+ 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);
+ /* do other things */
+ }
+ 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;
+ /* do things.. */
+ }
+
+dev_pm_opp_get_opp_count
+ 检索某个设备可用的OPP数量。
+ 例子:假设SoC中的一个协处理器需要知道某个表中的可用频率,主处理器可以
+ 按如下方式发出通知::
+
+ soc_notify_coproc_available_frequencies()
+ {
+ /* Do things */
+ num_available = dev_pm_opp_get_opp_count(dev);
+ speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
+ /* populate the table in increasing order */
+ 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);
+ /* Do other things */
+ }
+
+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框架。
+
+总体来说,以一个简化的视角看,对数据结构的操作可以描述为下图::
+
+ Initialization / modification:
+ +-----+ /- dev_pm_opp_enable
+ dev_pm_opp_add --> | opp | <-------
+ | +-----+ \- dev_pm_opp_disable
+ \-------> domain_info(device)
+
+ Search functions:
+ /-- dev_pm_opp_find_freq_ceil ---\ +-----+
+ domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
+ \-- dev_pm_opp_find_freq_floor ---/ +-----+
+
+ Retrieval functions:
+ +-----+ /- dev_pm_opp_get_voltage
+ | opp | <---
+ +-----+ \- dev_pm_opp_get_freq
+
+ domain_info <- dev_pm_opp_get_opp_count
--
2.17.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH v2 1/3] docs/zh_CN: Cleanup index.rst
2021-12-28 2:14 ` [PATCH v2 1/3] docs/zh_CN: Cleanup index.rst Tang Yizhou
@ 2021-12-28 7:11 ` yanteng si
0 siblings, 0 replies; 7+ messages in thread
From: yanteng si @ 2021-12-28 7:11 UTC (permalink / raw)
To: Tang Yizhou
Cc: Yanteng Si, Alex Shi, Alex Shi, Linux Doc Mailing List,
Jonathan Corbet, zhengbin13, Yeechou Tang
Tang Yizhou <tangyizhou@huawei.com> 于2021年12月28日周二 09:46写道:
>
> The Chinese version of many */index is not in the same order as the
> English version. Put them to where they should be.
>
> Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
> ---
> Documentation/translations/zh_CN/index.rst | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
> index 46e14ec9963d..e7f5fa3e7502 100644
> --- a/Documentation/translations/zh_CN/index.rst
> +++ b/Documentation/translations/zh_CN/index.rst
> @@ -104,13 +104,13 @@ TODOList:
> :maxdepth: 2
>
> core-api/index
> + accounting/index
> cpu-freq/index
> iio/index
> + infiniband/index
> + virt/index
> sound/index
> filesystems/index
> - virt/index
> - infiniband/index
> - accounting/index
> scheduler/index
>
> TODOList:
> --
> 2.17.1
>
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v2 2/3] docs/zh_CN: Add power/index Chinese translation
2021-12-28 2:14 ` [PATCH v2 2/3] docs/zh_CN: Add power/index Chinese translation Tang Yizhou
@ 2021-12-28 7:11 ` yanteng si
0 siblings, 0 replies; 7+ messages in thread
From: yanteng si @ 2021-12-28 7:11 UTC (permalink / raw)
To: Tang Yizhou
Cc: Yanteng Si, Alex Shi, Alex Shi, Linux Doc Mailing List,
Jonathan Corbet, zhengbin13, Yeechou Tang
Tang Yizhou <tangyizhou@huawei.com> 于2021年12月28日周二 09:46写道:
>
> Translate power/index.rst into Chinese.
>
> Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
> Reviewed-by: Alex Shi <alexs@kernel.org>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
> ---
> Documentation/translations/zh_CN/index.rst | 2 +-
> .../translations/zh_CN/power/index.rst | 55 +++++++++++++++++++
> 2 files changed, 56 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/power/index.rst
>
> diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
> index e7f5fa3e7502..08144252630c 100644
> --- a/Documentation/translations/zh_CN/index.rst
> +++ b/Documentation/translations/zh_CN/index.rst
> @@ -108,6 +108,7 @@ TODOList:
> cpu-freq/index
> iio/index
> infiniband/index
> + power/index
> virt/index
> sound/index
> filesystems/index
> @@ -129,7 +130,6 @@ TODOList:
> * netlabel/index
> * networking/index
> * pcmcia/index
> -* power/index
> * target/index
> * timers/index
> * spi/index
> diff --git a/Documentation/translations/zh_CN/power/index.rst b/Documentation/translations/zh_CN/power/index.rst
> new file mode 100644
> index 000000000000..fd379adfda8e
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/power/index.rst
> @@ -0,0 +1,55 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/power/index.rst
> +
> +:翻译:
> +
> + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com>
> +
> +========
> +电源管理
> +========
> +
> +.. toctree::
> + :maxdepth: 1
> +
> +TODOList:
> +
> + * apm-acpi
> + * basic-pm-debugging
> + * charger-manager
> + * drivers-testing
> + * energy-model
> + * freezing-of-tasks
> + * opp
> + * 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`
> --
> 2.17.1
>
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH v2 3/3] docs/zh_CN: Add opp Chinese translation
2021-12-28 2:14 ` [PATCH v2 3/3] docs/zh_CN: Add opp " Tang Yizhou
@ 2021-12-28 8:00 ` yanteng si
0 siblings, 0 replies; 7+ messages in thread
From: yanteng si @ 2021-12-28 8:00 UTC (permalink / raw)
To: Tang Yizhou
Cc: Yanteng Si, Alex Shi, Alex Shi, Linux Doc Mailing List,
Jonathan Corbet, zhengbin13, Yeechou Tang
Tang Yizhou <tangyizhou@huawei.com> 于2021年12月28日周二 09:46写道:
>
> Translate power/opp.rst into Chinese.
>
> Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
> Reviewed-by: Alex Shi <alexs@kernel.org>
> ---
> .../translations/zh_CN/power/index.rst | 3 +-
> .../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 fd379adfda8e..ad80a9e80b7c 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 000000000000..0aa65b2774f4
> --- /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 <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()
> + {
> + /* Do things */
> + 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;
> + }
> + /* Do cpufreq things */
comments need to be translated.
> + no_cpufreq:
> + /* Do remaining things */
> + }
> +
> +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);
> + /* dont operate on the pointer.. just do a sanity check.. */
> + if (IS_ERR(opp)) {
> + pr_err("frequency not disabled!\n");
> + /* trigger appropriate actions.. */
> + } 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(..)
> + {
> + /* Do stuff like policy checks etc. */
> + /* Find the best frequency match for the req */
> + 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
> + /* do something when we can't satisfy the req */
> + /* do other stuff */
> + }
> +
> +4. OPP可用性控制函数
> +=====================================
too long.
> +在OPP库中注册的默认OPP链表也许无法满足所有可能的场景。OPP库提供了一套函数来修改
> +OPP链表中的某个OPP的可用性。这使得SoC框架能够精细地动态控制哪一组OPP是可用于操作
> +的。设计这些函数的目的是在诸如考虑温度时 *暂时地* 删除某个OPP(例如,在温度下降
> +之前不要使用某OPP)。
> +
> +警告:
> + 不要在中断上下文使用这些函数。
> +
> +dev_pm_opp_enable
> + 使一个OPP可用于操作。
> + 例子:假设1GHz的OPP只有在SoC温度低于某个阈值时才可用。SoC框架的实现可能
> + 会选择做以下事情::
> +
> + if (cur_temp < temp_low_thresh) {
> + /* Enable 1GHz if it was disabled */
> + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
> + dev_pm_opp_put(opp);
> + /* just error check */
> + 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) {
> + /* Disable 1GHz if it was enabled */
> + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
> + dev_pm_opp_put(opp);
> + /* just error check */
> + 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)
> + {
> + /* do things */
> + 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);
> + /* do other things */
> + }
> +
> +dev_pm_opp_get_freq
> + 检索OPP指针描述的频率。
> + 例子:比方说,SoC框架使用了几个辅助函数,通过这些函数,我们可以将OPP
> + 指针传入,而不是传入额外的参数,用来处理一系列数据参数::
> +
> + soc_cpufreq_target(..)
> + {
> + /* do things.. */
> + 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);
> + /* do other things */
> + }
> + 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;
> + /* do things.. */
> + }
> +
> +dev_pm_opp_get_opp_count
> + 检索某个设备可用的OPP数量。
> + 例子:假设SoC中的一个协处理器需要知道某个表中的可用频率,主处理器可以
> + 按如下方式发出通知::
> +
> + soc_notify_coproc_available_frequencies()
> + {
> + /* Do things */
> + num_available = dev_pm_opp_get_opp_count(dev);
> + speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
> + /* populate the table in increasing order */
> + 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);
> + /* Do other things */
> + }
> +
> +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框架。
> +
> +总体来说,以一个简化的视角看,对数据结构的操作可以描述为下图::
> +
> + Initialization / modification:
> + +-----+ /- dev_pm_opp_enable
> + dev_pm_opp_add --> | opp | <-------
> + | +-----+ \- dev_pm_opp_disable
> + \-------> domain_info(device)
> +
> + Search functions:
need to be translated.
> + /-- dev_pm_opp_find_freq_ceil ---\ +-----+
> + domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
> + \-- dev_pm_opp_find_freq_floor ---/ +-----+
> +
> + Retrieval functions:
> + +-----+ /- dev_pm_opp_get_voltage
> + | opp | <---
> + +-----+ \- dev_pm_opp_get_freq
> +
> + domain_info <- dev_pm_opp_get_opp_count
> --
> 2.17.1
>
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2021-12-28 8:00 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-12-28 2:14 [PATCH v2 0/3] Translate opp into Chinese Tang Yizhou
2021-12-28 2:14 ` [PATCH v2 1/3] docs/zh_CN: Cleanup index.rst Tang Yizhou
2021-12-28 7:11 ` yanteng si
2021-12-28 2:14 ` [PATCH v2 2/3] docs/zh_CN: Add power/index Chinese translation Tang Yizhou
2021-12-28 7:11 ` yanteng si
2021-12-28 2:14 ` [PATCH v2 3/3] docs/zh_CN: Add opp " Tang Yizhou
2021-12-28 8:00 ` yanteng si
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).