[PATCH v3 0/7] docs/zh_CN: Add timers subsystem translation

[PATCH v3 0/7] docs/zh_CN: Add timers subsystem translation

[Xingqiu Xu]

This patch series translates the complete timers subsystem
documentation into Chinese, including:

- timers/index.rst: Main index with file structure
- timers/timekeeping.rst: Clock sources and events
- timers/hpet.rst: High Precision Event Timer driver
- timers/hrtimers.rst: High-resolution timer subsystem
- timers/highres.rst: High-resolution timers design notes
- timers/no_hz.rst: Reducing scheduling-clock ticks
- timers/delay_sleep_functions.rst: Delay and sleep mechanisms

Also updates subsystem-apis.rst to include timers/index.

All translations are based on the latest English documentation.

Changes in v3:
- Replace kernel-doc directives with :c:func: and :c:macro: references
  to avoid duplicate C declaration warnings as pointed out by Dongliang Mu

Changes in v2:
- Remove trailing blank lines at EOF in all translation files
  as pointed out by Dongliang Mu

Xingqiu Xu (7):
  docs/zh_CN: Add timers directory Chinese translation
  docs/zh_CN: Translate timers/timekeeping.rst
  docs/zh_CN: Translate timers/hpet.rst
  docs/zh_CN: Translate timers/hrtimers.rst
  docs/zh_CN: Translate timers/highres.rst
  docs/zh_CN: Translate timers/no_hz.rst
  docs/zh_CN: Translate timers delay_sleep_functions

 .../translations/zh_CN/subsystem-apis.rst     |   5 +-
 .../zh_CN/timers/delay_sleep_functions.rst    | 136 +++++++
 .../translations/zh_CN/timers/highres.rst     | 270 ++++++++++++++
 .../translations/zh_CN/timers/hpet.rst        |  43 +++
 .../translations/zh_CN/timers/hrtimers.rst    | 187 ++++++++++
 .../translations/zh_CN/timers/index.rst       |  30 ++
 .../translations/zh_CN/timers/no_hz.rst       | 337 ++++++++++++++++++
 .../translations/zh_CN/timers/timekeeping.rst | 202 +++++++++++
 8 files changed, 1206 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/timers/delay_sleep_functions.rst
 create mode 100644 Documentation/translations/zh_CN/timers/highres.rst
 create mode 100644 Documentation/translations/zh_CN/timers/hpet.rst
 create mode 100644 Documentation/translations/zh_CN/timers/hrtimers.rst
 create mode 100644 Documentation/translations/zh_CN/timers/index.rst
 create mode 100644 Documentation/translations/zh_CN/timers/no_hz.rst
 create mode 100644 Documentation/translations/zh_CN/timers/timekeeping.rst

-- 
2.34.1

[PATCH v3 1/7] docs/zh_CN: Add timers directory Chinese translation

[Xingqiu Xu]

Translate Documentation/timers/ into Chinese and update subsystem-apis.rst
translation.

Update the translation through commit 1f455f601e20
("timers/Documentation: Cleanup delay/sleep documentation")

Signed-off-by: Xingqiu Xu <hilbertanjou83@gmail.com>
---
 .../translations/zh_CN/subsystem-apis.rst     |  5 +--
 .../translations/zh_CN/timers/index.rst       | 32 +++++++++++++++++++
 2 files changed, 33 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/timers/index.rst

diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst
index 830217140fb6..f6445e256ee9 100644
--- a/Documentation/translations/zh_CN/subsystem-apis.rst
+++ b/Documentation/translations/zh_CN/subsystem-apis.rst
@@ -29,10 +29,7 @@
    power/index
    scheduler/index
    locking/index
-
-TODOList:
-
-* timers/index
+   timers/index
 
 人机接口
 --------
diff --git a/Documentation/translations/zh_CN/timers/index.rst b/Documentation/translations/zh_CN/timers/index.rst
new file mode 100644
index 000000000000..8dc5861445f9
--- /dev/null
+++ b/Documentation/translations/zh_CN/timers/index.rst
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/timers/index.rst
+
+:翻译:
+
+  徐兴球 Xingqiu Xu <hilbertanjou83@gmail.com>
+
+======
+定时器
+======
+
+.. toctree::
+    :maxdepth: 1
+
+TODOList:
+
+* highres
+* hpet
+* hrtimers
+* no_hz
+* timekeeping
+* delay_sleep_functions
+
+.. only::  subproject and html
+
+   索引
+   ====
+
+   * :ref:`genindex`
-- 
2.34.1

[PATCH v3 2/7] docs/zh_CN: Translate timers/timekeeping.rst

[Xingqiu Xu]

Translate .../timers/timekeeping.rst into Chinese.
Update timers/index.rst to include the translated file.

Update translation through commit 458f69ef3665
("docs: timers: convert docs to ReST and rename to *.rst")

Signed-off-by: Xingqiu Xu <hilbertanjou83@gmail.com>
---
 .../translations/zh_CN/timers/index.rst       |   3 +-
 .../translations/zh_CN/timers/timekeeping.rst | 202 ++++++++++++++++++
 2 files changed, 204 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/timers/timekeeping.rst

diff --git a/Documentation/translations/zh_CN/timers/index.rst b/Documentation/translations/zh_CN/timers/index.rst
index 8dc5861445f9..c1e178484f96 100644
--- a/Documentation/translations/zh_CN/timers/index.rst
+++ b/Documentation/translations/zh_CN/timers/index.rst
@@ -15,13 +15,14 @@
 .. toctree::
     :maxdepth: 1
 
+    timekeeping
+
 TODOList:
 
 * highres
 * hpet
 * hrtimers
 * no_hz
-* timekeeping
 * delay_sleep_functions
 
 .. only::  subproject and html
diff --git a/Documentation/translations/zh_CN/timers/timekeeping.rst b/Documentation/translations/zh_CN/timers/timekeeping.rst
new file mode 100644
index 000000000000..efd024f2e64c
--- /dev/null
+++ b/Documentation/translations/zh_CN/timers/timekeeping.rst
@@ -0,0 +1,202 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/timers/timekeeping.rst
+
+:翻译:
+
+  徐兴球 Xingqiu Xu <hilbertanjou83@gmail.com>
+
+===============================================
+时钟源、时钟事件、sched_clock() 和延迟定时器
+===============================================
+
+本文档试图简要解释一些基本的内核时间保持抽
+象。它部分涉及通常在内核树的
+drivers/clocksource 中找到的驱动程序，但
+代码可能分散在整个内核中。
+
+如果您通过 grep 浏览内核源代码，您会发现许
+多特定于架构的时钟源、时钟事件实现以及类似
+的几个特定于架构的 sched_clock() 函数覆盖
+和一些延迟定时器。
+
+为了为您的平台提供时间保持，时钟源提供基本
+时间线，而时钟事件在此时间线上的某些点触发
+中断，提供诸如高分辨率定时器之类的功能。
+sched_clock() 用于调度和时间戳，延迟定时器
+使用硬件计数器提供准确的延迟源。
+
+
+时钟源
+------
+
+时钟源的目的是为系统提供时间线，告诉系统当
+前的时间位置。例如，在 Linux 系统上发出
+"date" 命令最终将读取时钟源以确定确切的时
+间。
+
+通常，时钟源是一个单调的原子计数器，它将提
+供 n 位，从 0 计数到 (2^n)-1，然后回绕到 0
+并重新开始。只要系统运行，它理想地永远不会
+停止计时。它可能在系统挂起期间停止。
+
+时钟源应该具有尽可能高的分辨率，并且与实际
+的墙上时钟相比，频率应该尽可能稳定和正确。
+它不应该在时间上不可预测地来回移动或在这里
+和那里错过几个周期。
+
+它必须对硬件中发生的那种效果免疫，例如在总
+线上分两个阶段读取计数器寄存器：首先读取最
+低 16 位，然后在第二个总线周期中读取较高的
+16 位，而计数器位可能在两者之间更新，这会
+导致计数器产生非常奇怪的值。
+
+当时钟源的挂钟时间精度不令人满意时，时间保
+持代码中有各种特殊处理机制和层次，用于例如
+将用户可见时间同步到系统中的 RTC 时钟或使
+用 NTP 针对网络时间服务器，但它们所做的基
+本上是更新针对时钟源的偏移量，时钟源为系统
+提供基本时间线。这些措施不会影响时钟源本身，
+它们只是使系统适应时钟源的缺点。
+
+时钟源结构应提供将提供的计数器转换为纳秒值
+作为无符号 64 位整数的方法。由于此操作可能
+被非常频繁地调用，因此在严格的数学意义上这
+样做是不可取的：相反，使用仅算术操作乘法和
+移位将数字尽可能接近纳秒值，因此在
+clocksource_cyc2ns() 中您会发现：
+
+  ns ~= (clocksource * mult) >> shift
+
+您会在时钟源代码中找到许多辅助函数，旨在帮
+助提供这些 mult 和 shift 值，例如
+clocksource_khz2mult()、
+clocksource_hz2mult()，它们帮助从固定的
+shift 确定 mult 因子，以及
+clocksource_register_hz() 和
+clocksource_register_khz()，它们将使用时
+钟源的频率作为唯一输入来帮助分配 shift 和
+mult 因子。
+
+对于从单个 I/O 内存位置访问的真正简单的时
+钟源，现在甚至有 clocksource_mmio_init()，
+它将接受内存位置、位宽、一个参数告诉寄存器
+中的计数器是向上还是向下计数以及定时器时钟
+速率，然后生成所有必要的参数。
+
+由于 100 MHz 的 32 位计数器将在大约 43 秒
+后回绕到零，处理时钟源的代码将不得不对此进
+行补偿。这就是为什么时钟源结构还包含一个
+'mask' 成员，说明源的多少位是有效的。这样，
+时间保持代码就知道计数器何时会回绕，并可以
+在回绕点的两侧插入必要的补偿代码，以便系统
+时间线保持单调。
+
+
+时钟事件
+--------
+
+时钟事件在概念上是时钟源的反向操作：它们采
+用所需的时间规范值并计算要写入硬件定时器寄
+存器的值。
+
+时钟事件与时钟源正交。相同的硬件和寄存器范
+围可用于时钟事件，但它本质上是不同的东西。
+驱动时钟事件的硬件必须能够触发中断，以便在
+系统时间线上触发事件。在 SMP 系统上，理想
+（并且习惯）每个 CPU 核心有一个这样的事件
+驱动定时器，以便每个核心可以独立于任何其他
+核心触发事件。
+
+您会注意到时钟事件设备代码基于关于使用 mult
+和 shift 算术将计数器转换为纳秒的相同基本
+思想，并且您会再次找到用于分配这些值的相同
+辅助函数系列。但是，时钟事件驱动程序不需要
+'mask' 属性：系统不会尝试在时钟事件的时间
+范围之外规划事件。
+
+
+sched_clock()
+-------------
+
+除了时钟源和时钟事件之外，内核中还有一个特
+殊的弱函数，称为 sched_clock()。此函数应
+返回自系统启动以来的纳秒数。架构可能会也可
+能不会提供 sched_clock() 的自己的实现。如
+果不提供本地实现，系统 jiffy 计数器将用作
+sched_clock()。
+
+顾名思义，sched_clock() 用于调度系统，例
+如在 CFS 调度程序中确定某个进程的绝对时间
+片。它还用于 printk 时间戳，当您选择在
+printk 中包含时间信息以用于引导图表等事情
+时。
+
+与时钟源相比，sched_clock() 必须非常快：它
+被调用得更频繁，尤其是被调度程序调用。如果
+您必须在与时钟源相比的精度之间进行权衡，您
+可以在 sched_clock() 中牺牲精度以换取速度。
+但是，它需要与时钟源相同的一些基本特征，即
+它应该是单调的。
+
+sched_clock() 函数只能在无符号长整型边界上
+回绕，即 64 位之后。由于这是一个纳秒值，这
+意味着它在大约 585 年后回绕。（对于大多数
+实际系统，这意味着"永不"。）
+
+如果架构不提供此函数的自己实现，它将回退到
+使用 jiffies，使其最大分辨率为架构的 jiffy
+频率的 1/HZ。这将影响调度精度，并可能在系
+统基准测试中显示出来。
+
+驱动 sched_clock() 的时钟可能在系统挂起/
+睡眠期间停止或重置为零。这对它所服务的调度
+系统事件功能无关紧要。但是，它可能导致
+printk() 中出现有趣的时间戳。
+
+sched_clock() 函数应该在任何上下文中可调
+用，IRQ 和 NMI 安全，并在任何上下文中返回
+合理的值。
+
+某些架构可能具有有限的时间源集并且缺乏一个
+很好的计数器来派生 64 位纳秒值，因此例如在
+ARM 架构上，已经创建了特殊的辅助函数，以从
+16 位或 32 位计数器提供 sched_clock() 纳
+秒基数。有时，也用作时钟源的同一计数器也用
+于此目的。
+
+在 SMP 系统上，对于性能至关重要的是
+sched_clock() 可以在每个 CPU 上独立调用而
+不会产生任何同步性能损失。某些硬件（例如
+x86 TSC）将导致 sched_clock() 函数在系统
+上的 CPU 之间漂移。内核可以通过启用
+CONFIG_HAVE_UNSTABLE_SCHED_CLOCK 选项来解
+决此问题。这是使 sched_clock() 与普通时钟
+源不同的另一个方面。
+
+
+延迟定时器（仅某些架构）
+------------------------
+
+在具有可变 CPU 频率的系统上，各种内核
+delay() 函数有时会表现得很奇怪。基本上，这
+些延迟通常使用硬循环来延迟使用在引导时校准
+的"lpj"（每 jiffy 循环数）值的一定数量的
+jiffy 分数。
+
+让我们希望您的系统在校准此值时以最大频率运
+行：结果是当频率降至一半频率时，任何 delay()
+将是两倍长。通常这不会造成伤害，因为您通常
+要求至少那么多的延迟。但基本上，在此类系统
+上，语义是相当不可预测的。
+
+进入基于定时器的延迟。使用这些，可以使用定
+时器读取而不是硬编码循环来提供所需的延迟。
+
+这是通过声明一个 struct delay_timer 并为此
+延迟定时器分配适当的函数指针和速率设置来完
+成的。
+
+这在某些架构上可用，例如 OpenRISC 或 ARM。
-- 
2.34.1

[PATCH v3 3/7] docs/zh_CN: Translate timers/hpet.rst

[Xingqiu Xu]

Translate .../timers/hpet.rst into Chinese.
Update timers/index.rst to include the translated file.

Update translation through commit 458f69ef3665
("docs: timers: convert docs to ReST and rename to *.rst")

Signed-off-by: Xingqiu Xu <hilbertanjou83@gmail.com>
---
 .../translations/zh_CN/timers/hpet.rst        | 43 +++++++++++++++++++
 .../translations/zh_CN/timers/index.rst       |  2 +-
 2 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/timers/hpet.rst

diff --git a/Documentation/translations/zh_CN/timers/hpet.rst b/Documentation/translations/zh_CN/timers/hpet.rst
new file mode 100644
index 000000000000..6ed46220e12e
--- /dev/null
+++ b/Documentation/translations/zh_CN/timers/hpet.rst
@@ -0,0 +1,43 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/timers/hpet.rst
+
+:翻译:
+
+  徐兴球 Xingqiu Xu <hilbertanjou83@gmail.com>
+
+================================
+Linux 高精度事件定时器驱动程序
+================================
+
+高精度事件定时器（HPET）硬件遵循 Intel 和
+Microsoft 的规范，修订版 1。
+
+每个 HPET 有一个固定速率计数器（以 10 MHz
+以上运行，因此称为"高精度"）和最多 32 个比
+较器。通常提供三个或更多比较器，每个比较器
+都可以生成单次中断，并且至少其中一个具有支
+持周期中断的额外硬件。比较器也称为"定时器"，
+这可能引起混淆，因为通常定时器彼此独立……这
+些共享一个计数器，使重置变得复杂。
+
+HPET 设备可以支持两种中断路由模式。在一种
+模式下，比较器是没有特定系统角色的附加中断
+源。许多 x86 BIOS 编写者根本不路由 HPET
+中断，这导致该模式无法使用。它们支持另一种
+"传统替换"模式，其中前两个比较器替代 8254
+定时器和 RTC 的中断。
+
+该驱动程序支持在驱动程序 module_init 例程
+被调用之前检测 HPET 驱动分配并初始化
+HPET。这使得使用定时器 0 或 1 作为主定时器
+的平台代码能够拦截 HPET 初始化。可以在
+arch/x86/kernel/hpet.c 中找到此初始化的示
+例。
+
+该驱动程序提供了一个用户空间 API，类似于
+RTC 驱动程序框架中的 API。示例用户空间程
+序在 file:samples/timers/hpet_example.c
+中提供。
diff --git a/Documentation/translations/zh_CN/timers/index.rst b/Documentation/translations/zh_CN/timers/index.rst
index c1e178484f96..bf63a69ca71d 100644
--- a/Documentation/translations/zh_CN/timers/index.rst
+++ b/Documentation/translations/zh_CN/timers/index.rst
@@ -15,12 +15,12 @@
 .. toctree::
     :maxdepth: 1
 
+    hpet
     timekeeping
 
 TODOList:
 
 * highres
-* hpet
 * hrtimers
 * no_hz
 * delay_sleep_functions
-- 
2.34.1

[PATCH v3 4/7] docs/zh_CN: Translate timers/hrtimers.rst

[Xingqiu Xu]

Translate .../timers/hrtimers.rst into Chinese.
Update timers/index.rst to include the translated file.

Update translation through commit 4c093cbb89f3
("Documentation: timers: hrtimers: Make hybrid union historical")

Signed-off-by: Xingqiu Xu <hilbertanjou83@gmail.com>
---
 .../translations/zh_CN/timers/hrtimers.rst    | 187 ++++++++++++++++++
 .../translations/zh_CN/timers/index.rst       |   2 +-
 2 files changed, 188 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/timers/hrtimers.rst

diff --git a/Documentation/translations/zh_CN/timers/hrtimers.rst b/Documentation/translations/zh_CN/timers/hrtimers.rst
new file mode 100644
index 000000000000..3dd73808b4b6
--- /dev/null
+++ b/Documentation/translations/zh_CN/timers/hrtimers.rst
@@ -0,0 +1,187 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/timers/hrtimers.rst
+
+:翻译:
+
+  徐兴球 Xingqiu Xu <hilbertanjou83@gmail.com>
+
+==========================================
+hrtimers - 高分辨率内核定时器子系统
+==========================================
+
+本补丁引入了一个新的高分辨率内核定时器子系统。
+
+有人可能会问：我们已经有了一个定时器子系统
+（kernel/timers.c），为什么需要两个定时器
+子系统？在经过大量的反复尝试将高分辨率和高
+精度功能集成到现有定时器框架中，并在实践中
+测试了各种此类高分辨率定时器实现后，我们得
+出结论：定时器轮代码从根本上不适合这种方法。
+我们最初不相信这一点（"一定有办法解决这个
+问题"），并花费了相当大的努力尝试将东西集
+成到定时器轮中，但我们失败了。事后看来，这
+种集成困难/不可能有几个原因：
+
+- 以相同方式强制处理低分辨率和高分辨率定时
+  器导致大量妥协、宏魔法和 #ifdef 混乱。
+  timers.c 代码围绕 jiffies 和 32 位假设
+  进行了非常"紧密的编码"，并且多年来针对相
+  对狭窄的用例（相对狭窄的 HZ 范围内的
+  jiffies）进行了磨练和微优化——因此即使对
+  它的小扩展也容易破坏轮概念，导致更糟糕的
+  妥协。定时器轮代码是非常好和紧凑的代码，
+  在其当前使用中没有任何问题——但它根本不适
+  合扩展为高分辨率定时器。
+
+- 级联的不可预测的 [O(N)] 开销导致延迟，这
+  需要更复杂地处理高分辨率定时器，这反过来
+  又降低了鲁棒性。这种设计仍然导致相当大的
+  定时不准确性。级联是定时器轮概念的基本属
+  性，如果不以不可接受的方式不可避免地降低
+  timers.c 代码的其他部分，就无法"设计出"
+  它。
+
+- 在定时器轮之上实现当前 posix-timer 子系
+  统已经引入了相当复杂的处理，用于在
+  settimeofday 或 NTP 时间调整绝对
+  CLOCK_REALTIME 定时器——通过示例进一步证
+  实了我们的经验：定时器轮数据结构对于高分
+  辨率定时器来说太僵化了。
+
+- 定时器轮代码最适合可以识别为"超时"的用例。
+  此类超时通常被设置为覆盖各种 I/O 路径中
+  的错误条件，例如网络和块 I/O。这些定时器
+  中的绝大多数从不过期，并且很少重新级联，
+  因为预期的正确事件及时到达，因此可以在对
+  它们进行任何进一步处理之前将它们从定时器
+  轮中移除。因此，这些超时的用户可以接受定
+  时器轮的粒度和精度权衡，并且很大程度上期
+  望定时器子系统具有接近零的开销。对他们来
+  说，准确的定时不是核心目的——事实上，使用
+  的大多数超时值都是临时的。对他们来说，这
+  充其量只是保证处理实际超时完成的必要之恶
+  （因为大多数超时在完成前被删除），因此应
+  该尽可能便宜和不显眼。
+
+精确定时器的主要用户是利用 nanosleep、
+posix-timers 和 itimer 接口的用户空间应用
+程序。此外，需要精确定时事件的内核用户（如
+驱动程序和子系统）（例如多媒体）也可以从单
+独的高分辨率定时器子系统的可用性中受益。
+
+虽然该子系统尚未提供高分辨率时钟源，但
+hrtimer 子系统可以很容易地扩展为具有高分
+辨率时钟能力，并且相关补丁已经存在并且正在
+快速成熟。对实时和多媒体应用程序以及精确定
+时器的其他潜在用户的日益增长的需求为分离
+"超时"和"精确定时器"子系统提供了另一个理由。
+
+另一个潜在的好处是，这样的分离允许对现有定
+时器轮进行更特殊目的的优化，以用于低分辨率
+和低精度用例——一旦精度敏感的 API 从定时器
+轮中分离出来并迁移到 hrtimers。例如，我们
+可以将超时子系统的频率从 250 Hz 降低到
+100 HZ（甚至更小）。
+
+hrtimer 子系统实现细节
+----------------------
+
+基本设计考虑是：
+
+- 简单性
+
+- 数据结构不绑定到 jiffies 或任何其他粒度。
+  所有内核逻辑都以 64 位纳秒分辨率工作——没
+  有妥协。
+
+- 简化现有的、与定时相关的内核代码
+
+另一个基本要求是在激活时立即排队和排序定时
+器。在查看了几种可能的解决方案（如基数树和
+散列）之后，我们选择红黑树作为基本数据结构。
+红黑树在内核中作为库可用，并用于各种性能关
+键领域，例如内存管理和文件系统。红黑树仅用
+于时间排序，而单独的列表用于为到期代码提供
+对排队定时器的快速访问，而无需遍历红黑树。
+
+（当我们稍后引入高分辨率时钟时，这个单独的
+列表也很有用，在那里我们需要单独的挂起和过
+期队列，同时保持时间顺序完整。）
+
+但是，时间排序的排队不仅仅是为了高分辨率时
+钟，它还简化了基于低分辨率 CLOCK_REALTIME
+的绝对定时器的处理。现有实现需要保留所有武
+装的绝对 CLOCK_REALTIME 定时器的额外列表以
+及复杂的锁定。在 settimeofday 和 NTP 的情
+况下，所有定时器（！）都必须出队，时间更改
+代码必须逐个修复它们，然后所有这些都必须重
+新排队。时间排序的排队和以绝对时间单位存储
+到期时间从 posix-timer 实现中删除了所有这
+些复杂且可扩展性差的代码——时钟可以简单地设
+置而无需触及红黑树。这也使得 posix-timers
+的处理总体上更简单。
+
+hrtimers 的锁定和每 CPU 行为主要取自现有
+定时器轮代码，因为它已经成熟且非常适合。共
+享代码并不是真正的胜利，因为数据结构不同。
+此外，hrtimer 函数现在具有更清晰的行为和更
+清晰的名称——例如 hrtimer_try_to_cancel()
+和 hrtimer_cancel() [大致相当于
+timer_delete() 和 timer_delete_sync()]
+——因此在算法级别上它们之间没有直接的 1:1
+映射，因此也没有真正的代码共享潜力。
+
+基本数据类型：每个时间值，无论是绝对的还是
+相对的，都采用特殊的纳秒分辨率 64 位类型：
+ktime_t。（最初，ktime_t 值和操作的内核内
+部表示是通过宏和内联函数实现的，可以在"混
+合联合"类型和普通"标量" 64 位纳秒表示之间
+切换（在编译时）。这在 Y2038 工作的背景下
+被放弃了。）
+
+hrtimers - 定时器值的舍入
+-------------------------
+
+hrtimer 代码会将定时器事件舍入到较低分辨
+率的时钟，因为它必须这样做。否则它不会进行
+任何人为舍入。
+
+一个问题是，clock_getres() 接口应该向用户
+返回什么分辨率值。这将返回给定时钟具有的任
+何实际分辨率——无论是低分辨率、高分辨率还是
+人为低分辨率。
+
+hrtimers - 测试和验证
+---------------------
+
+我们在 hrtimers 之上使用了高分辨率时钟子
+系统来在实践中验证 hrtimer 实现的细节，我
+们还运行了 posix 定时器测试以确保规范合规
+性。我们还在低分辨率时钟上运行了测试。
+
+hrtimer 补丁转换了以下内核功能以使用
+hrtimers：
+
+ - nanosleep
+ - itimers
+ - posix-timers
+
+nanosleep 和 posix-timers 的转换使得
+nanosleep 和 clock_nanosleep 的统一成为可能。
+
+该代码已成功为以下平台编译：
+
+ i386, x86_64, ARM, PPC, PPC64, IA64
+
+该代码在以下平台上进行了运行测试：
+
+ i386(UP/SMP), x86_64(UP/SMP), ARM, PPC
+
+hrtimers 也被集成到 -rt 树中，连同基于
+hrtimers 的高分辨率时钟实现，因此 hrtimers
+代码在实践中得到了大量的测试和使用。
+
+	Thomas Gleixner, Ingo Molnar
diff --git a/Documentation/translations/zh_CN/timers/index.rst b/Documentation/translations/zh_CN/timers/index.rst
index bf63a69ca71d..cd0187d83719 100644
--- a/Documentation/translations/zh_CN/timers/index.rst
+++ b/Documentation/translations/zh_CN/timers/index.rst
@@ -16,12 +16,12 @@
     :maxdepth: 1
 
     hpet
+    hrtimers
     timekeeping
 
 TODOList:
 
 * highres
-* hrtimers
 * no_hz
 * delay_sleep_functions
 
-- 
2.34.1

[PATCH v3 5/7] docs/zh_CN: Translate timers/highres.rst

[Xingqiu Xu]

Translate .../timers/highres.rst into Chinese.
Update timers/index.rst to include the translated file.

Update translation through commit 458f69ef3665
("docs: timers: convert docs to ReST and rename to *.rst")

Signed-off-by: Xingqiu Xu <hilbertanjou83@gmail.com>
---
 .../translations/zh_CN/timers/highres.rst     | 270 ++++++++++++++++++
 .../translations/zh_CN/timers/index.rst       |   2 +-
 2 files changed, 271 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/timers/highres.rst

diff --git a/Documentation/translations/zh_CN/timers/highres.rst b/Documentation/translations/zh_CN/timers/highres.rst
new file mode 100644
index 000000000000..64fd62e3da68
--- /dev/null
+++ b/Documentation/translations/zh_CN/timers/highres.rst
@@ -0,0 +1,270 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/timers/highres.rst
+
+:翻译:
+
+  徐兴球 Xingqiu Xu <hilbertanjou83@gmail.com>
+
+==========================================
+高分辨率定时器和动态时钟刻度设计笔记
+==========================================
+
+可以在 OLS 2006 演讲"hrtimers 及其超越"的
+论文中找到更多信息。该论文是 OLS 2006 论文
+集第 1 卷的一部分，可以在 OLS 网站上找到：
+https://www.kernel.org/doc/ols/2006/ols2006v1-pages-333-346.pdf
+
+该演讲的幻灯片可从以下网址获得：
+http://www.cs.columbia.edu/~nahum/w6998/papers/ols2006-hrtimers-slides.pdf
+
+幻灯片包含五个图（第 2、15、18、20、22 页），
+说明了 Linux 时间(r)相关子系统的变化。图 #1
+（第 2 页）显示了在 hrtimers 和其他构建块合
+并到主线之前 Linux 时间(r)系统的设计。
+
+注意：论文和幻灯片讨论的是"时钟事件源"，而我
+们同时切换到了名称"时钟事件设备"。
+
+该设计包含以下基本构建块：
+
+- hrtimer 基础设施
+- 时间日期和时钟源管理
+- 时钟事件管理
+- 高分辨率定时器功能
+- 动态时钟刻度
+
+
+hrtimer 基础设施
+----------------
+
+hrtimer 基础设施已合并到 2.6.16 内核中。基
+本实现的详细信息包含在
+Documentation/timers/hrtimers.rst 中。另请
+参见图 #2（OLS 幻灯片第 15 页）
+
+与保存已武装的 timer_list 类型定时器的定时
+器轮的主要区别是：
+
+       - 按时间顺序入队到红黑树中
+       - 独立于时钟节拍（处理基于纳秒）
+
+
+时间日期和时钟源管理
+--------------------
+
+John Stultz 的通用时间日期（GTOD）框架将
+大部分代码从特定于架构的区域移动到通用管理
+框架中，如图 #3（OLS 幻灯片第 18 页）所示。
+特定于架构的部分被简化为时钟源的低级硬件细
+节，这些时钟源在框架中注册并根据基于质量的
+决策进行选择。低级代码提供硬件设置和读出例
+程，并初始化数据结构，通用时间保持代码使用
+这些数据结构将时钟刻度转换为基于纳秒的时间
+值。所有其他与时间保持相关的功能都移到了通
+用代码中。GTOD 基础补丁已合并到 2.6.18 内
+核中。
+
+有关通用时间日期框架的更多信息，请参见 OLS
+2005 论文集第 1 卷：
+
+	http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
+
+论文"We Are Not Getting Any Younger: A New
+Approach to Time and Timers"由 J. Stultz、
+D.V. Hart 和 N. Aravamudan 撰写。
+
+图 #3（OLS 幻灯片第 18 页）说明了这一转变。
+
+
+时钟事件管理
+------------
+
+虽然时钟源提供对单调递增时间值的读访问，但
+时钟事件设备用于调度下一个事件中断。下一个
+事件当前定义为周期性的，其周期在编译时定义。
+事件设备的设置和选择用于各种事件驱动功能被
+硬编码到依赖于架构的代码中。这导致所有架构
+都有重复代码，并且使得更改系统配置以使用除
+已内置到架构中的事件中断设备之外的其他设备
+变得极其困难。当前设计的另一个含义是，为了
+提供诸如高分辨率定时器或动态时钟刻度之类的
+新功能，必须触及所有特定于架构的实现。
+
+时钟事件子系统试图通过提供通用解决方案来管
+理时钟事件设备及其用于各种时钟事件驱动的内
+核功能来解决此问题。时钟事件子系统的目标是
+将时钟事件相关的依赖于架构的代码最小化为纯
+硬件相关的处理，并允许轻松添加和利用新的时
+钟事件设备。它还最小化了跨架构的重复代码，
+因为它提供了从中断服务处理程序向下的通用功
+能，这几乎本质上是硬件依赖的。
+
+时钟事件设备由依赖于架构的引导代码或在模块
+插入时注册。每个时钟事件设备填充一个数据结
+构，其中包含时钟特定的属性参数和回调函数。
+时钟事件管理通过使用指定的属性参数决定时钟
+事件设备将用于支持的系统功能集。这包括区分
+每 CPU 和每系统全局事件设备。
+
+系统级全局事件设备用于 Linux 周期时钟刻度。
+每 CPU 事件设备用于提供本地 CPU 功能，例如
+进程记账、分析和高分辨率定时器。
+
+管理层为时钟事件设备分配以下一个或多个功能：
+
+      - 系统全局周期时钟刻度（jiffies 更新）
+      - cpu 本地 update_process_times
+      - cpu 本地分析
+      - cpu 本地下一个事件中断（非周期模式）
+
+时钟事件设备将这些定时器中断相关功能的选择
+完全委托给管理层。时钟管理层在设备描述结构
+中存储一个函数指针，必须从硬件级处理程序调
+用该指针。这从特定于架构的定时器中断处理程
+序中删除了大量重复代码，并将对时钟事件设备
+的控制以及定时器中断相关功能的分配交给核心
+代码。
+
+时钟事件层 API 相当小。除了时钟事件设备注
+册接口外，它还提供用于调度下一个事件中断、
+时钟事件设备通知服务以及对挂起和恢复的支持
+的函数。
+
+该框架添加了大约 700 行代码，这导致内核二
+进制大小增加 2KB。i386 的转换删除了大约
+100 行代码。二进制大小减少约 400 字节。我
+们认为，灵活性的增加和跨架构的重复代码的避
+免证明了二进制大小的轻微增加是合理的。
+
+架构的转换没有功能影响，但允许在不更改时钟
+事件设备和定时器中断代码的情况下利用高分辨
+率和动态时钟刻度功能。转换后，只需将
+kernel/time/Kconfig 文件添加到特定于架构
+的 Kconfig 并将动态时钟刻度特定调用添加到
+空闲例程（总共向空闲函数和 Kconfig 文件添
+加 3 行）即可简单地提供高分辨率定时器和动
+态时钟刻度的启用。
+
+图 #4（OLS 幻灯片第 20 页）说明了这一转变。
+
+
+高分辨率定时器功能
+------------------
+
+在系统引导期间无法使用高分辨率定时器功能，
+虽然实现这一功能会很困难且没有实际用途。必
+须完成时钟事件设备框架、时钟源框架（GTOD）
+和 hrtimers 本身的初始化，并且必须注册适当
+的时钟源和时钟事件设备，然后高分辨率功能才
+能工作。直到 hrtimers 初始化完成之前，系统
+以通常的低分辨率周期模式工作。
+时钟源和时钟事件设备层提供通知功能，通知
+hrtimers 有关新硬件的可用性。hrtimers 在
+切换到高分辨率模式之前验证已注册时钟源和时
+钟事件设备的可用性。这也确保了配置为高分辨
+率定时器的内核可以在缺乏必要硬件支持的系统
+上运行。
+
+高分辨率定时器代码不支持仅具有全局时钟事件
+设备的 SMP 机器。对此类硬件的支持将涉及中
+断发生时的 IPI 调用。开销将远大于收益。这
+就是为什么我们目前在 i386 SMP 系统上禁用
+高分辨率和动态时钟刻度，这些系统在 C3 电
+源状态下停止本地 APIC。解决方法作为想法可
+用，但尚未解决该问题。
+
+定时器的时间排序插入提供了所有基础设施，以
+在添加定时器时决定是否必须重新编程事件设备。
+该决定是按定时器基础做出的，并在支持函数中
+跨每 CPU 定时器基础同步。该设计允许系统为
+每 CPU 定时器基础使用单独的每 CPU 时钟事
+件设备，但当前每个 CPU 仅使用一个可重新编
+程的时钟事件设备。
+
+当定时器中断发生时，从时钟事件分发代码调用
+下一个事件中断处理函数，并将过期的定时器从
+红黑树移动到单独的双向链表，并调用软中断处
+理函数。hrtimer 结构中的额外模式字段允许
+系统直接从下一个事件中断处理函数执行回调函
+数。这仅限于可以在硬中断上下文中安全执行的
+代码。例如，这适用于 nanosleep 使用的唤醒
+函数的常见情况。在中断上下文中执行处理函数
+的优点是避免了多达两次上下文切换——从中断的
+上下文到软中断以及到被过期定时器唤醒的任务。
+
+一旦系统切换到高分辨率模式，周期时钟节拍就
+会关闭。这会禁用系统级全局周期时钟事件设备
+——例如 i386 SMP 系统上的 PIT。
+
+周期时钟节拍功能由每 CPU hrtimer 提供。回
+调函数在下一个事件中断上下文中执行，并更新
+jiffies 并调用 update_process_times 和分
+析。基于 hrtimer 的周期时钟节拍的实现旨在
+扩展动态时钟节拍功能。这允许使用单个时钟事
+件设备在 UP 系统上调度高分辨率定时器和周期
+事件（jiffies 时钟节拍、分析、进程记账）。
+这已被证明可以在 i386 上的 PIT 和 PPC 上
+的增量器上工作。
+
+用于运行 hrtimer 队列和执行回调的软中断已
+从时钟节拍绑定的定时器软中断中分离出来，以
+允许准确传递 itimer 和 POSIX 间隔定时器使
+用的高分辨率定时器信号。此软中断的执行仍可
+能被其他软中断延迟，但这种分离已显著改善了
+总体延迟。
+
+图 #5（OLS 幻灯片第 22 页）说明了这一转变。
+
+
+动态时钟节拍
+------------
+
+动态时钟节拍是基于 hrtimer 的周期时钟节拍
+替换（sched_tick）的逻辑结果。sched_tick
+hrtimer 的功能由三个函数扩展：
+
+- hrtimer_stop_sched_tick
+- hrtimer_restart_sched_tick
+- hrtimer_update_jiffies
+
+当 CPU 进入空闲状态时调用
+hrtimer_stop_sched_tick()。该代码评估下一
+个预定的定时器事件（来自 hrtimers 和定时
+器轮），如果下一个事件比下一个时钟节拍更远，
+它会将 sched_tick 重新编程到这个未来事件，
+以允许更长的空闲睡眠，而不会受到周期时钟节
+拍的无用中断。当空闲期间发生中断但不会导致
+重新调度时，也会调用该函数。该调用是必要的，
+因为中断处理函数可能已经启动了一个新定时器，
+其到期时间早于在上一次调用
+hrtimer_stop_sched_tick 时识别的最近事件
+的时间。
+
+当 CPU 在调用 schedule() 之前离开空闲状态
+时，调用 hrtimer_restart_sched_tick()。
+hrtimer_restart_sched_tick() 恢复周期时
+钟节拍，该节拍保持活动状态直到下次调用
+hrtimer_stop_sched_tick()。
+
+从 irq_enter() 调用 hrtimer_update_jiffies()
+当空闲期间发生中断时，以确保 jiffies 是最
+新的，并且中断处理函数不必处理可能过时的
+jiffy 值。
+
+动态时钟节拍功能提供统计值，这些值通过
+/proc/stat 导出到用户空间，并可用于增强的
+电源管理控制。
+
+该实现为进一步开发留下了空间，例如完全无节
+拍系统，其中时间片由调度程序控制、可变频率
+分析以及将来完全删除 jiffies。
+
+
+除了当前 i386 支持的初始提交外，补丁集已经
+扩展到 x86_64 和 ARM。MIPS 和 PowerPC 的
+初始（正在进行的工作）支持也可用。
+
+	  Thomas, Ingo
diff --git a/Documentation/translations/zh_CN/timers/index.rst b/Documentation/translations/zh_CN/timers/index.rst
index cd0187d83719..485e6a95c600 100644
--- a/Documentation/translations/zh_CN/timers/index.rst
+++ b/Documentation/translations/zh_CN/timers/index.rst
@@ -15,13 +15,13 @@
 .. toctree::
     :maxdepth: 1
 
+    highres
     hpet
     hrtimers
     timekeeping
 
 TODOList:
 
-* highres
 * no_hz
 * delay_sleep_functions
 
-- 
2.34.1

Re: [PATCH v3 5/7] docs/zh_CN: Translate timers/highres.rst

[Dongliang Mu]

On 1/7/26 3:47 AM, Xingqiu Xu wrote:
> Translate .../timers/highres.rst into Chinese.
> Update timers/index.rst to include the translated file.
>
> Update translation through commit 458f69ef3665
> ("docs: timers: convert docs to ReST and rename to *.rst")
>
> Signed-off-by: Xingqiu Xu <hilbertanjou83@gmail.com>

1) In the how-to.rst, it requires "每行长度最多不超过 40 个字符"。It means 
40 Chinese characters.

Each line in the following translation is too small. You can make it longer.

2) If you use AI to translate kernel documentation, that's fine. But 
please proofread and double check

all the translation results.

> ---
>   .../translations/zh_CN/timers/highres.rst     | 270 ++++++++++++++++++
>   .../translations/zh_CN/timers/index.rst       |   2 +-
>   2 files changed, 271 insertions(+), 1 deletion(-)
>   create mode 100644 Documentation/translations/zh_CN/timers/highres.rst
>
> diff --git a/Documentation/translations/zh_CN/timers/highres.rst b/Documentation/translations/zh_CN/timers/highres.rst
> new file mode 100644
> index 000000000000..64fd62e3da68
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/timers/highres.rst
> @@ -0,0 +1,270 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/timers/highres.rst
> +
> +:翻译:
> +
> +  徐兴球 Xingqiu Xu <hilbertanjou83@gmail.com>
> +
> +==========================================
> +高分辨率定时器和动态时钟刻度设计笔记
> +==========================================
> +
> +可以在 OLS 2006 演讲"hrtimers 及其超越"的
> +论文中找到更多信息。该论文是 OLS 2006 论文

The first sentence is missing a subject, please change to the following 
style:

“更多相关信息可参阅 XXX”

> +集第 1 卷的一部分，可以在 OLS 网站上找到：
Change to "该论文收录于 OLS 2006 年 论文集第一卷，可在 OLS 官网网查阅："
> +https://www.kernel.org/doc/ols/2006/ols2006v1-pages-333-346.pdf
> +
> +该演讲的幻灯片可从以下网址获得：
> +http://www.cs.columbia.edu/~nahum/w6998/papers/ols2006-hrtimers-slides.pdf
> +
> +幻灯片包含五个图（第 2、15、18、20、22 页），
> +说明了 Linux 时间(r)相关子系统的变化。图 #1

Linux 时间(r)？If you use AI for translation, please proofread the translation results.

"图 #1" change to Chinese style - "图一"
> +（第 2 页）显示了在 hrtimers 和其他构建块合
> +并到主线之前 Linux 时间(r)系统的设计。
> +
> +注意：论文和幻灯片讨论的是"时钟事件源"，而我
> +们同时切换到了名称"时钟事件设备"。
> +
> +该设计包含以下基本构建块：
> +
> +- hrtimer 基础设施
> +- 时间日期和时钟源管理
> +- 时钟事件管理
> +- 高分辨率定时器功能
> +- 动态时钟刻度
> +
> +
> +hrtimer 基础设施
> +----------------
> +
> +hrtimer 基础设施已合并到 2.6.16 内核中。基
> +本实现的详细信息包含在
> +Documentation/timers/hrtimers.rst 中。另请
> +参见图 #2（OLS 幻灯片第 15 页）

图 #2 -> “图二”

> +
> +与保存已武装的 timer_list 类型定时器的定时
> +器轮的主要区别是：
> +
> +       - 按时间顺序入队到红黑树中
> +       - 独立于时钟节拍（处理基于纳秒）
> +
> +
> +时间日期和时钟源管理
> +--------------------
> +
> +John Stultz 的通用时间日期（GTOD）框架将
> +大部分代码从特定于架构的区域移动到通用管理
> +框架中，如图 #3（OLS 幻灯片第 18 页）所示。
ditto
> +特定于架构的部分被简化为时钟源的低级硬件细
> +节，这些时钟源在框架中注册并根据基于质量的
> +决策进行选择。低级代码提供硬件设置和读出例
> +程，并初始化数据结构，通用时间保持代码使用
> +这些数据结构将时钟刻度转换为基于纳秒的时间
> +值。所有其他与时间保持相关的功能都移到了通
> +用代码中。GTOD 基础补丁已合并到 2.6.18 内
> +核中。
> +
> +有关通用时间日期框架的更多信息，请参见 OLS
> +2005 论文集第 1 卷：
> +
> +	http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
> +
> +论文"We Are Not Getting Any Younger: A New
> +Approach to Time and Timers"由 J. Stultz、
> +D.V. Hart 和 N. Aravamudan 撰写。
> +
> +图 #3（OLS 幻灯片第 18 页）说明了这一转变。
ditto
> +
> +
> +时钟事件管理
> +------------
> +
> +虽然时钟源提供对单调递增时间值的读访问，但
> +时钟事件设备用于调度下一个事件中断。下一个
> +事件当前定义为周期性的，其周期在编译时定义。
> +事件设备的设置和选择用于各种事件驱动功能被
> +硬编码到依赖于架构的代码中。这导致所有架构
> +都有重复代码，并且使得更改系统配置以使用除
> +已内置到架构中的事件中断设备之外的其他设备
> +变得极其困难。当前设计的另一个含义是，为了
> +提供诸如高分辨率定时器或动态时钟刻度之类的
> +新功能，必须触及所有特定于架构的实现。
> +
> +时钟事件子系统试图通过提供通用解决方案来管
> +理时钟事件设备及其用于各种时钟事件驱动的内
> +核功能来解决此问题。时钟事件子系统的目标是
> +将时钟事件相关的依赖于架构的代码最小化为纯
> +硬件相关的处理，并允许轻松添加和利用新的时
> +钟事件设备。它还最小化了跨架构的重复代码，
> +因为它提供了从中断服务处理程序向下的通用功
> +能，这几乎本质上是硬件依赖的。
> +
> +时钟事件设备由依赖于架构的引导代码或在模块
> +插入时注册。每个时钟事件设备填充一个数据结
> +构，其中包含时钟特定的属性参数和回调函数。
> +时钟事件管理通过使用指定的属性参数决定时钟
> +事件设备将用于支持的系统功能集。这包括区分
> +每 CPU 和每系统全局事件设备。
> +
> +系统级全局事件设备用于 Linux 周期时钟刻度。
> +每 CPU 事件设备用于提供本地 CPU 功能，例如
> +进程记账、分析和高分辨率定时器。
> +
> +管理层为时钟事件设备分配以下一个或多个功能：
> +
> +      - 系统全局周期时钟刻度（jiffies 更新）
> +      - cpu 本地 update_process_times
> +      - cpu 本地分析
> +      - cpu 本地下一个事件中断（非周期模式）
> +
> +时钟事件设备将这些定时器中断相关功能的选择
> +完全委托给管理层。时钟管理层在设备描述结构
> +中存储一个函数指针，必须从硬件级处理程序调
> +用该指针。这从特定于架构的定时器中断处理程
> +序中删除了大量重复代码，并将对时钟事件设备
> +的控制以及定时器中断相关功能的分配交给核心
> +代码。
> +
> +时钟事件层 API 相当小。除了时钟事件设备注
> +册接口外，它还提供用于调度下一个事件中断、
> +时钟事件设备通知服务以及对挂起和恢复的支持
> +的函数。
> +
> +该框架添加了大约 700 行代码，这导致内核二
> +进制大小增加 2KB。i386 的转换删除了大约
> +100 行代码。二进制大小减少约 400 字节。我
> +们认为，灵活性的增加和跨架构的重复代码的避
> +免证明了二进制大小的轻微增加是合理的。
> +
> +架构的转换没有功能影响，但允许在不更改时钟
> +事件设备和定时器中断代码的情况下利用高分辨
> +率和动态时钟刻度功能。转换后，只需将
> +kernel/time/Kconfig 文件添加到特定于架构
> +的 Kconfig 并将动态时钟刻度特定调用添加到
> +空闲例程（总共向空闲函数和 Kconfig 文件添
> +加 3 行）即可简单地提供高分辨率定时器和动
> +态时钟刻度的启用。
> +
> +图 #4（OLS 幻灯片第 20 页）说明了这一转变。
ditto
> +
> +
> +高分辨率定时器功能
> +------------------
> +
> +在系统引导期间无法使用高分辨率定时器功能，
> +虽然实现这一功能会很困难且没有实际用途。必
> +须完成时钟事件设备框架、时钟源框架（GTOD）
> +和 hrtimers 本身的初始化，并且必须注册适当
> +的时钟源和时钟事件设备，然后高分辨率功能才
> +能工作。直到 hrtimers 初始化完成之前，系统
> +以通常的低分辨率周期模式工作。
> +时钟源和时钟事件设备层提供通知功能，通知
> +hrtimers 有关新硬件的可用性。hrtimers 在
> +切换到高分辨率模式之前验证已注册时钟源和时
> +钟事件设备的可用性。这也确保了配置为高分辨
> +率定时器的内核可以在缺乏必要硬件支持的系统
> +上运行。
> +
> +高分辨率定时器代码不支持仅具有全局时钟事件
> +设备的 SMP 机器。对此类硬件的支持将涉及中
> +断发生时的 IPI 调用。开销将远大于收益。这
> +就是为什么我们目前在 i386 SMP 系统上禁用
> +高分辨率和动态时钟刻度，这些系统在 C3 电
> +源状态下停止本地 APIC。解决方法作为想法可
> +用，但尚未解决该问题。
> +
> +定时器的时间排序插入提供了所有基础设施，以
> +在添加定时器时决定是否必须重新编程事件设备。
> +该决定是按定时器基础做出的，并在支持函数中
> +跨每 CPU 定时器基础同步。该设计允许系统为
> +每 CPU 定时器基础使用单独的每 CPU 时钟事
> +件设备，但当前每个 CPU 仅使用一个可重新编
> +程的时钟事件设备。
> +
> +当定时器中断发生时，从时钟事件分发代码调用
> +下一个事件中断处理函数，并将过期的定时器从
> +红黑树移动到单独的双向链表，并调用软中断处
> +理函数。hrtimer 结构中的额外模式字段允许
> +系统直接从下一个事件中断处理函数执行回调函
> +数。这仅限于可以在硬中断上下文中安全执行的
> +代码。例如，这适用于 nanosleep 使用的唤醒
> +函数的常见情况。在中断上下文中执行处理函数
> +的优点是避免了多达两次上下文切换——从中断的
> +上下文到软中断以及到被过期定时器唤醒的任务。
> +
> +一旦系统切换到高分辨率模式，周期时钟节拍就
> +会关闭。这会禁用系统级全局周期时钟事件设备
> +——例如 i386 SMP 系统上的 PIT。
> +
> +周期时钟节拍功能由每 CPU hrtimer 提供。回
> +调函数在下一个事件中断上下文中执行，并更新
> +jiffies 并调用 update_process_times 和分
> +析。基于 hrtimer 的周期时钟节拍的实现旨在
> +扩展动态时钟节拍功能。这允许使用单个时钟事
> +件设备在 UP 系统上调度高分辨率定时器和周期
> +事件（jiffies 时钟节拍、分析、进程记账）。
> +这已被证明可以在 i386 上的 PIT 和 PPC 上
> +的增量器上工作。
> +
> +用于运行 hrtimer 队列和执行回调的软中断已
> +从时钟节拍绑定的定时器软中断中分离出来，以
> +允许准确传递 itimer 和 POSIX 间隔定时器使
> +用的高分辨率定时器信号。此软中断的执行仍可
> +能被其他软中断延迟，但这种分离已显著改善了
> +总体延迟。
> +
> +图 #5（OLS 幻灯片第 22 页）说明了这一转变。
ditto
> +
> +
> +动态时钟节拍
> +------------
> +
> +动态时钟节拍是基于 hrtimer 的周期时钟节拍
> +替换（sched_tick）的逻辑结果。sched_tick
> +hrtimer 的功能由三个函数扩展：
> +
> +- hrtimer_stop_sched_tick
> +- hrtimer_restart_sched_tick
> +- hrtimer_update_jiffies
> +
> +当 CPU 进入空闲状态时调用
> +hrtimer_stop_sched_tick()。该代码评估下一
> +个预定的定时器事件（来自 hrtimers 和定时
> +器轮），如果下一个事件比下一个时钟节拍更远，
> +它会将 sched_tick 重新编程到这个未来事件，
> +以允许更长的空闲睡眠，而不会受到周期时钟节
> +拍的无用中断。当空闲期间发生中断但不会导致
> +重新调度时，也会调用该函数。该调用是必要的，
> +因为中断处理函数可能已经启动了一个新定时器，
> +其到期时间早于在上一次调用
> +hrtimer_stop_sched_tick 时识别的最近事件
> +的时间。
> +
> +当 CPU 在调用 schedule() 之前离开空闲状态
> +时，调用 hrtimer_restart_sched_tick()。
> +hrtimer_restart_sched_tick() 恢复周期时
> +钟节拍，该节拍保持活动状态直到下次调用
> +hrtimer_stop_sched_tick()。
> +
> +从 irq_enter() 调用 hrtimer_update_jiffies()
> +当空闲期间发生中断时，以确保 jiffies 是最
> +新的，并且中断处理函数不必处理可能过时的
> +jiffy 值。
> +
> +动态时钟节拍功能提供统计值，这些值通过
> +/proc/stat 导出到用户空间，并可用于增强的
> +电源管理控制。
> +
> +该实现为进一步开发留下了空间，例如完全无节
> +拍系统，其中时间片由调度程序控制、可变频率
> +分析以及将来完全删除 jiffies。
> +
> +
> +除了当前 i386 支持的初始提交外，补丁集已经
> +扩展到 x86_64 和 ARM。MIPS 和 PowerPC 的
> +初始（正在进行的工作）支持也可用。
> +
> +	  Thomas, Ingo
> diff --git a/Documentation/translations/zh_CN/timers/index.rst b/Documentation/translations/zh_CN/timers/index.rst
> index cd0187d83719..485e6a95c600 100644
> --- a/Documentation/translations/zh_CN/timers/index.rst
> +++ b/Documentation/translations/zh_CN/timers/index.rst
> @@ -15,13 +15,13 @@
>   .. toctree::
>       :maxdepth: 1
>   
> +    highres
>       hpet
>       hrtimers
>       timekeeping
>   
>   TODOList:
>   
> -* highres
>   * no_hz
>   * delay_sleep_functions
>   

[PATCH v3 6/7] docs/zh_CN: Translate timers/no_hz.rst

[Xingqiu Xu]

Translate .../timers/no_hz.rst into Chinese.
Update timers/index.rst to include the translated file.

Update translation through commit 5097cbcb38e6
("sched/isolation: Prevent boot crash when the boot CPU is nohz_full")

Signed-off-by: Xingqiu Xu <hilbertanjou83@gmail.com>
---
 .../translations/zh_CN/timers/index.rst       |   2 +-
 .../translations/zh_CN/timers/no_hz.rst       | 337 ++++++++++++++++++
 2 files changed, 338 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/timers/no_hz.rst

diff --git a/Documentation/translations/zh_CN/timers/index.rst b/Documentation/translations/zh_CN/timers/index.rst
index 485e6a95c600..17f35d87645a 100644
--- a/Documentation/translations/zh_CN/timers/index.rst
+++ b/Documentation/translations/zh_CN/timers/index.rst
@@ -18,11 +18,11 @@
     highres
     hpet
     hrtimers
+    no_hz
     timekeeping
 
 TODOList:
 
-* no_hz
 * delay_sleep_functions
 
 .. only::  subproject and html
diff --git a/Documentation/translations/zh_CN/timers/no_hz.rst b/Documentation/translations/zh_CN/timers/no_hz.rst
new file mode 100644
index 000000000000..b1d43169ece0
--- /dev/null
+++ b/Documentation/translations/zh_CN/timers/no_hz.rst
@@ -0,0 +1,337 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/timers/no_hz.rst
+
+:翻译:
+
+  徐兴球 Xingqiu Xu <hilbertanjou83@gmail.com>
+
+============================
+NO_HZ：减少调度时钟刻度
+============================
+
+
+本文档描述了可以减少调度时钟中断数量的
+Kconfig 选项和引导参数，从而提高能效并减
+少操作系统抖动。减少操作系统抖动对于某些类
+型的计算密集型高性能计算（HPC）应用程序以
+及实时应用程序非常重要。
+
+管理调度时钟中断（也称为"调度时钟刻度"或简
+称"刻度"）有三种主要方式：
+
+1.	从不省略调度时钟刻度（CONFIG_HZ_PERIODIC=y
+	或对于旧内核为 CONFIG_NO_HZ=n）。您通常
+	不会想要选择此选项。
+
+2.	在空闲 CPU 上省略调度时钟刻度
+	（CONFIG_NO_HZ_IDLE=y 或对于旧内核为
+	CONFIG_NO_HZ=y）。这是最常见的方法，应
+	该是默认值。
+
+3.	在空闲或只有一个可运行任务的 CPU 上省
+	略调度时钟刻度（CONFIG_NO_HZ_FULL=y）。
+	除非您正在运行实时应用程序或某些类型的
+	HPC 工作负载，否则您通常不会想要此选项。
+
+这三种情况将在以下三节中描述，然后是关于
+RCU 特定考虑的第三节，讨论测试的第四节，以
+及列出已知问题的第五节和最后一节。
+
+
+从不省略调度时钟刻度
+====================
+
+来自 1990 年代和 21 世纪初期的非常旧版本
+的 Linux 无法省略调度时钟刻度。事实证明，
+在某些情况下，这种老派方法仍然是正确的方法，
+例如，在具有大量使用短暂 CPU 突发的任务的
+繁重工作负载中，其中有非常频繁的空闲期，但
+这些空闲期也非常短（数十或数百微秒）。对于
+这些类型的工作负载，调度时钟中断通常无论如
+何都会传递，因为每个 CPU 经常会有多个可运
+行的任务。在这些情况下，尝试关闭调度时钟中
+断除了增加进出空闲以及在用户和内核执行之间
+转换的开销外没有任何效果。
+
+可以使用 CONFIG_HZ_PERIODIC=y（或对于旧内
+核为 CONFIG_NO_HZ=n）选择此操作模式。
+
+但是，如果您正在运行具有较长空闲期的轻量级
+工作负载，则无法省略调度时钟中断将导致过度
+的功耗。这在电池供电的设备上尤其糟糕，它会
+导致电池寿命极短。如果您正在运行轻量级工作
+负载，因此应该阅读以下部分。
+
+此外，如果您正在运行实时工作负载或具有短迭
+代的 HPC 工作负载，调度时钟中断可能会降低
+您的应用程序性能。如果这描述了您的工作负载，
+您应该阅读以下两节。
+
+
+为空闲 CPU 省略调度时钟刻度
+===========================
+
+如果 CPU 处于空闲状态，向其发送调度时钟中
+断意义不大。毕竟，调度时钟中断的主要目的是
+强制繁忙的 CPU 在多个任务之间转移其注意力，
+而空闲 CPU 没有需要转移注意力的任务。
+
+不接收调度时钟中断的空闲 CPU 被称为
+"dyntick-idle"、"处于 dyntick-idle 模式"、
+"处于 nohz 模式"或"无刻度运行"。本文档的其
+余部分将使用"dyntick-idle 模式"。
+
+CONFIG_NO_HZ_IDLE=y Kconfig 选项使内核避
+免向空闲 CPU 发送调度时钟中断，这对于电池
+供电的设备和高度虚拟化的大型机都至关重要。
+运行 CONFIG_HZ_PERIODIC=y 内核的电池供电设
+备将非常快速地耗尽其电池，轻松地比运行
+CONFIG_NO_HZ_IDLE=y 内核的同一设备快 2-3
+倍。运行 1,500 个操作系统实例的大型机可能
+会发现其一半的 CPU 时间被不必要的调度时钟
+中断消耗。在这些情况下，有强烈的动机避免向
+空闲 CPU 发送调度时钟中断。也就是说，
+dyntick-idle 模式不是免费的：
+
+1.	它增加了进出空闲循环的路径上执行的指令
+	数量。
+
+2.	在许多架构上，dyntick-idle 模式还会增
+	加昂贵的时钟重新编程操作的数量。
+
+因此，具有激进实时响应约束的系统通常运行
+CONFIG_HZ_PERIODIC=y 内核（或对于旧内核为
+CONFIG_NO_HZ=n），以避免降低从空闲转换延迟。
+
+还有一个引导参数"nohz="，可用于通过指定
+"nohz=off"在 CONFIG_NO_HZ_IDLE=y 内核中禁
+用 dyntick-idle 模式。默认情况下，
+CONFIG_NO_HZ_IDLE=y 内核使用"nohz=on"引导，
+启用 dyntick-idle 模式。
+
+
+为只有一个可运行任务的 CPU 省略调度时钟刻度
+=============================================
+
+如果 CPU 只有一个可运行任务，向其发送调度
+时钟中断意义不大，因为没有其他任务可以切换
+到。请注意，为只有一个可运行任务的 CPU 省
+略调度时钟刻度也意味着为空闲 CPU 省略它们。
+
+CONFIG_NO_HZ_FULL=y Kconfig 选项使内核避
+免向具有单个可运行任务的 CPU 发送调度时钟
+中断，此类 CPU 被称为"自适应刻度 CPU"。这
+对于具有激进实时响应约束的应用程序非常重要，
+因为它允许它们通过调度时钟中断的最大持续时
+间来改善其最坏情况响应时间。对于计算密集型
+短迭代工作负载也很重要：如果在给定迭代期间
+任何 CPU 被延迟，所有其他 CPU 将被迫在延迟
+的 CPU 完成时空闲等待。因此，延迟乘以比
+CPU 数量少一的数量。在这些情况下，再次有强
+烈的动机避免发送调度时钟中断。
+
+默认情况下，没有 CPU 将是自适应刻度 CPU。
+"nohz_full=" 引导参数指定自适应刻度 CPU。
+例如，"nohz_full=1,6-8" 表示 CPU 1、6、7
+和 8 是自适应刻度 CPU。请注意，您被禁止将
+所有 CPU 标记为自适应刻度 CPU：至少必须保
+留一个非自适应刻度 CPU 在线以处理时间保持
+任务，以确保在自适应刻度 CPU 上像
+gettimeofday() 这样的系统调用返回准确的值。
+（这对于 CONFIG_NO_HZ_IDLE=y 不是问题，因
+为没有运行中的用户进程来观察时钟速率的轻微
+漂移。）请注意，这意味着您的系统必须至少有
+两个 CPU，CONFIG_NO_HZ_FULL=y 才能为您做
+任何事情。
+
+最后，自适应刻度 CPU 必须卸载其 RCU 回调。
+这在下面的"RCU 影响"部分中介绍。
+
+通常，CPU 尽可能长时间保持在自适应刻度模
+式下。特别是，转换到内核模式不会自动更改模
+式。相反，CPU 只有在需要时才会退出自适应刻
+度模式，例如，如果该 CPU 将 RCU 回调排入
+队列。
+
+就像 dyntick-idle 模式一样，自适应刻度模
+式的好处不是免费的：
+
+1.	CONFIG_NO_HZ_FULL 选择 CONFIG_NO_HZ_COMMON，
+	因此您不能在没有 dyntick idle 的情况下
+	运行自适应刻度。这种依赖关系延伸到实现
+	中，因此 CONFIG_NO_HZ_IDLE 的所有成本
+	也由 CONFIG_NO_HZ_FULL 承担。
+
+2.	由于需要通知内核子系统（例如 RCU）有关
+	模式更改，用户/内核转换稍微昂贵一些。
+
+3.	POSIX CPU 定时器阻止 CPU 进入自适应刻
+	度模式。需要基于 CPU 时间消耗采取行动
+	的实时应用程序需要使用其他方法来实现。
+
+4.	如果待处理的 perf 事件多于硬件可以容纳
+	的，它们通常会轮转，以便随着时间的推移
+	收集所有事件。自适应刻度模式可能会阻止
+	这种轮转发生。这可能会通过阻止具有大量
+	待处理 perf 事件的 CPU 进入自适应刻度
+	模式来修复。
+
+5.	自适应刻度 CPU 的调度程序统计信息可能
+	与非自适应刻度 CPU 的统计信息计算方式
+	略有不同。这可能反过来扰乱实时任务的负
+	载平衡。
+
+尽管预计随着时间的推移会有所改进，但自适应
+刻度对于许多类型的实时和计算密集型应用程序
+非常有用。但是，上面列出的缺点意味着自适应
+刻度不应该（还）默认启用。
+
+
+RCU 影响
+========
+
+在某些情况下，不能允许空闲 CPU 进入
+dyntick-idle 模式或自适应刻度模式，最常见
+的是当该 CPU 有 RCU 回调挂起时。
+
+通过使用 CONFIG_RCU_NOCB_CPU=y Kconfig 选
+项将 RCU 回调处理卸载到"rcuo"内核线程来避
+免这种情况。可以使用"rcu_nocbs=" 内核引导
+参数选择要卸载的特定 CPU，该参数接受逗号分
+隔的 CPU 和 CPU 范围列表，例如，"1,3-5"选
+择 CPU 1、3、4 和 5。请注意，由"nohz_full"
+内核引导参数指定的 CPU 也会被卸载。
+
+卸载的 CPU 将永远不会排队 RCU 回调，因此
+RCU 永远不会阻止卸载的 CPU 进入
+dyntick-idle 模式或自适应刻度模式。也就是
+说，请注意，如果需要，将"rcuo"内核线程固定
+到特定 CPU 取决于用户空间。否则，调度程序
+将决定在哪里运行它们，这可能是也可能不是您
+希望它们运行的地方。
+
+
+测试
+====
+
+因此，您启用了本文档中描述的所有操作系统抖
+动功能，但在工作负载的行为中看不到任何变化。
+这是因为您的工作负载受操作系统抖动的影响不
+大，还是因为其他东西挡在了路上？本节通过提
+供一个简单的操作系统抖动测试套件来帮助回答
+这个问题，该套件可在以下 git 存档的 master
+分支上获得：
+
+git://git.kernel.org/pub/scm/linux/kernel/git/frederic/dynticks-testing.git
+
+克隆此存档并按照 README 文件中的说明进行
+操作。此测试过程将产生一个跟踪，允许您评估
+是否成功从系统中删除了操作系统抖动。如果此
+跟踪显示您已尽可能多地删除了操作系统抖动，
+那么您可以得出结论，您的工作负载对操作系统
+抖动不是那么敏感。
+
+注意：此测试要求您的系统至少有两个 CPU。我
+们目前没有从单 CPU 系统中删除操作系统抖动
+的好方法。
+
+
+已知问题
+========
+
+*	Dyntick-idle 会稍微减慢进出空闲的转换。
+	在实践中，除了最激进的实时工作负载外，
+	这不是问题，它们可以选择禁用
+	dyntick-idle 模式，大多数工作负载都采
+	用了这个选项。但是，一些工作负载无疑会
+	希望使用自适应刻度来消除调度时钟中断延
+	迟。以下是这些工作负载的一些选项：
+
+	a.	使用用户空间的 PMQOS 通知内核您的
+		延迟要求（首选）。
+
+	b.	在 x86 系统上，使用"idle=mwait"引导
+		参数。
+
+	c.	在 x86 系统上，使用"intel_idle.max_cstate="
+		来限制最大 C 状态深度。
+
+	d.	在 x86 系统上，使用"idle=poll"引导
+		参数。但是，请注意，使用此参数可能
+		会导致 CPU 过热，这可能会导致热节
+		流降低您的延迟——而且这种降低可能比
+		dyntick-idle 更糟糕。此外，此参数
+		有效地禁用了 Intel CPU 上的 Turbo
+		Mode，这会显著降低最大性能。
+
+*	自适应刻度会稍微减慢用户/内核转换。对于
+	计算密集型工作负载，这不会成为问题，因
+	为它们很少有此类转换。需要仔细的基准测
+	试来确定其他工作负载是否受到此效果的显
+	著影响。
+
+*	除非给定 CPU 只有一个可运行任务，否则自
+	适应刻度不会执行任何操作，即使还有许多
+	其他情况不需要调度时钟刻度。举一个例子，
+	考虑一个 CPU，它有一个可运行的高优先级
+	SCHED_FIFO 任务和任意数量的低优先级
+	SCHED_OTHER 任务。在这种情况下，需要
+	CPU 运行 SCHED_FIFO 任务，直到它阻塞或
+	某个其他更高优先级的任务在此 CPU 上唤醒
+	（或被分配给此 CPU），因此向此 CPU 发
+	送调度时钟中断是没有意义的。但是，当前
+	实现仍然向具有单个可运行 SCHED_FIFO 任
+	务和多个可运行 SCHED_OTHER 任务的 CPU
+	发送调度时钟中断，即使这些中断是不必要的。
+
+	即使在给定 CPU 上有多个可运行任务时，在
+	当前运行任务的时间片到期之前中断该 CPU
+	也意义不大，这几乎总是比下一个调度时钟
+	中断的时间长得多。
+
+	更好地处理这些情况是未来的工作。
+
+*	需要重新启动才能重新配置自适应空闲和
+	RCU 回调卸载。如果需要，可以提供运行时
+	重新配置，但是，由于在运行时重新配置
+	RCU 的复杂性，需要有一个非常好的理由。
+	特别是考虑到您有简单的选项，即从所有
+	CPU 卸载 RCU 回调，并在您想要固定它们时
+	将它们固定到您想要的位置。
+
+*	需要额外的配置来处理操作系统抖动的其他
+	来源，包括中断和系统实用程序任务和进程。
+	此配置通常涉及将中断和任务绑定到特定
+	CPU。
+
+*	某些操作系统抖动源目前只能通过约束工作
+	负载来消除。例如，消除由于全局 TLB
+	shootdown 引起的操作系统抖动的唯一方法
+	是避免导致这些 shootdown 的取消映射操
+	作（例如内核模块卸载操作）。再举一个例
+	子，通过使用巨页并通过约束应用程序使用
+	的内存量，可以减少（在某些情况下消除）
+	页面错误和 TLB 未命中。预先发生工作集
+	也可能有帮助，尤其是与 mlock() 和
+	mlockall() 系统调用结合使用时。
+
+*	除非所有 CPU 都处于空闲状态，否则至少一
+	个 CPU 必须保持调度时钟中断运行以支持准
+	确的时间保持。
+
+*	如果可能有一些自适应刻度 CPU，即使所有
+	CPU 都处于空闲状态，也将至少有一个 CPU
+	保持调度时钟中断运行。
+
+	更好地处理这种情况是正在进行的工作。
+
+*	某些进程处理操作仍然需要偶尔的调度时钟
+	刻度。这些操作包括计算 CPU 负载、维护
+	sched average、计算 CFS 实体 vruntime、
+	计算 avenrun 以及执行负载平衡。它们当前
+	通过每秒左右的调度时钟刻度来容纳。正在
+	进行的工作将消除对这些不频繁的调度时钟
+	刻度的需求。
-- 
2.34.1

[PATCH v3 7/7] docs/zh_CN: Translate timers delay_sleep_functions

[Xingqiu Xu]

Translate .../timers/delay_sleep_functions.rst into Chinese.
Update timers/index.rst to include the translated file and
remove the TODO list as all translations are completed.

Update translation through commit 1f455f601e20
("timers/Documentation: Cleanup delay/sleep documentation")

Signed-off-by: Xingqiu Xu <hilbertanjou83@gmail.com>
---
 .../zh_CN/timers/delay_sleep_functions.rst    | 136 ++++++++++++++++++
 .../translations/zh_CN/timers/index.rst       |   5 +-
 2 files changed, 137 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/timers/delay_sleep_functions.rst

diff --git a/Documentation/translations/zh_CN/timers/delay_sleep_functions.rst b/Documentation/translations/zh_CN/timers/delay_sleep_functions.rst
new file mode 100644
index 000000000000..3ae2d3c43687
--- /dev/null
+++ b/Documentation/translations/zh_CN/timers/delay_sleep_functions.rst
@@ -0,0 +1,136 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/timers/delay_sleep_functions.rst
+
+:翻译:
+
+  徐兴球 Xingqiu Xu <hilbertanjou83@gmail.com>
+
+==============
+延迟和睡眠机制
+==============
+
+本文档旨在回答一个常见问题："插入延迟的正
+确方法(TM)是什么？"
+
+驱动程序开发者最常面对这个问题，他们必须处
+理硬件延迟，但可能对Linux内核的内部工作机
+制不是特别熟悉。
+
+下表粗略概述了现有函数"系列"及其局限性。
+此概述表格不能替代使用前阅读函数描述！
+
+.. list-table::
+   :widths: 20 20 20 20 20
+   :header-rows: 2
+
+   * -
+     - `*delay()`
+     - `usleep_range*()`
+     - `*sleep()`
+     - `fsleep()`
+   * -
+     - 忙等待循环
+     - 基于 hrtimers
+     - 基于 timer list timers
+     - 结合其他方法
+   * - 原子上下文中的使用
+     - 是
+     - 否
+     - 否
+     - 否
+   * - "短间隔"上精确
+     - 是
+     - 是
+     - 视情况而定
+     - 是
+   * - "长间隔"上精确
+     - 不要使用！
+     - 是
+     - 最大 12.5% 误差
+     - 是
+   * - 可中断变体
+     - 否
+     - 是
+     - 是
+     - 否
+
+对于非原子上下文的通用建议可能是：
+
+#. 当不确定时使用 `fsleep()` （因为它结合
+   了其他方法的所有优点）
+#. 尽可能使用 `*sleep()`
+#. 当 `*sleep()` 的精度不够时使用
+   `usleep_range*()`
+#. 对于非常非常短的延迟使用 `*delay()`
+
+在接下来的章节中可以找到有关函数"系列"的更
+详细信息。
+
+`*delay()` 函数系列
+-------------------
+
+这些函数使用基于时钟速度的 jiffy 估算，并
+忙等待足够的循环周期以实现所需的延迟。
+udelay() 是基本实现，ndelay() 和 mdelay()
+是变体。
+
+这些函数主要用于在原子上下文中添加延迟。请
+确保在原子上下文中添加延迟之前问自己：这真
+的需要吗？
+
+相关函数请参考：
+
+- :c:func:`udelay`
+- :c:func:`ndelay`
+- :c:macro:`mdelay`
+
+
+`usleep_range*()` 和 `*sleep()` 函数系列
+-----------------------------------------
+
+这些函数使用 hrtimers 或 timer list 定
+时器来提供所请求的睡眠持续时间。为了决定使
+用哪个函数是正确的，请考虑一些基本信息：
+
+#. hrtimers 更昂贵，因为它们使用红黑树
+   （而不是散列表）
+#. 当请求的睡眠时间是最早的定时器时，
+   hrtimers 更昂贵，这意味着必须对真实硬
+   件进行编程
+#. timer list 定时器总会存在一定误差，
+   因为它们基于 jiffy
+
+通用建议在此重复：
+
+#. 当不确定时使用 `fsleep()` （因为它结合
+   了其他方法的所有优点）
+#. 尽可能使用 `*sleep()`
+#. 当 `*sleep()` 的精度不够时使用
+   `usleep_range*()`
+
+首先检查 fsleep() 函数描述，要了解更多关于
+精度的信息，请检查 msleep() 函数描述。
+
+
+`usleep_range*()`
+~~~~~~~~~~~~~~~~~
+
+相关函数请参考：
+
+- :c:func:`usleep_range`
+- :c:func:`usleep_range_idle`
+- :c:func:`usleep_range_state`
+
+
+`*sleep()`
+~~~~~~~~~~
+
+相关函数请参考：
+
+- :c:func:`msleep`
+- :c:func:`msleep_interruptible`
+- :c:func:`ssleep`
+- :c:func:`fsleep`
diff --git a/Documentation/translations/zh_CN/timers/index.rst b/Documentation/translations/zh_CN/timers/index.rst
index 17f35d87645a..a939d54fd539 100644
--- a/Documentation/translations/zh_CN/timers/index.rst
+++ b/Documentation/translations/zh_CN/timers/index.rst
@@ -15,16 +15,13 @@
 .. toctree::
     :maxdepth: 1
 
+    delay_sleep_functions
     highres
     hpet
     hrtimers
     no_hz
     timekeeping
 
-TODOList:
-
-* delay_sleep_functions
-
 .. only::  subproject and html
 
    索引
-- 
2.34.1

Re: [PATCH v3 0/7] docs/zh_CN: Add timers subsystem translation

[Dongliang Mu]

On 1/7/26 3:47 AM, Xingqiu Xu wrote:
> This patch series translates the complete timers subsystem
> documentation into Chinese, including:
>
> - timers/index.rst: Main index with file structure
> - timers/timekeeping.rst: Clock sources and events
> - timers/hpet.rst: High Precision Event Timer driver
> - timers/hrtimers.rst: High-resolution timer subsystem
> - timers/highres.rst: High-resolution timers design notes
> - timers/no_hz.rst: Reducing scheduling-clock ticks
> - timers/delay_sleep_functions.rst: Delay and sleep mechanisms
>
> Also updates subsystem-apis.rst to include timers/index.

After applying this patchset, timers/index.rst has different orders from 
the one in English, like

======
定时器
======

.. toctree::
     :maxdepth: 1

     delay_sleep_functions
     highres
     hpet
     hrtimers
     no_hz
     timekeeping

I suggest the order in patchset can be exactly the same with the one 
in timers/index.rst.


Besides, after reviewing the first file - timers/highres.rst: 
High-resolution timers design notes,

I found some common issues, also found in other files.


1) In the how-to.rst, it requires "每行长度最多不超过 40 个字符"。It means 
40 Chinese characters.

Each line in the translation is too small. You can make it longer.

2) If you use AI to translate kernel documentation, that's fine. But 
please proofread and double check

all the translation results.

> All translations are based on the latest English documentation.
>
> Changes in v3:
> - Replace kernel-doc directives with :c:func: and :c:macro: references
>    to avoid duplicate C declaration warnings as pointed out by Dongliang Mu
>
> Changes in v2:
> - Remove trailing blank lines at EOF in all translation files
>    as pointed out by Dongliang Mu
>
> Xingqiu Xu (7):
>    docs/zh_CN: Add timers directory Chinese translation
>    docs/zh_CN: Translate timers/timekeeping.rst
>    docs/zh_CN: Translate timers/hpet.rst
>    docs/zh_CN: Translate timers/hrtimers.rst
>    docs/zh_CN: Translate timers/highres.rst
>    docs/zh_CN: Translate timers/no_hz.rst
>    docs/zh_CN: Translate timers delay_sleep_functions
>
>   .../translations/zh_CN/subsystem-apis.rst     |   5 +-
>   .../zh_CN/timers/delay_sleep_functions.rst    | 136 +++++++
>   .../translations/zh_CN/timers/highres.rst     | 270 ++++++++++++++
>   .../translations/zh_CN/timers/hpet.rst        |  43 +++
>   .../translations/zh_CN/timers/hrtimers.rst    | 187 ++++++++++
>   .../translations/zh_CN/timers/index.rst       |  30 ++
>   .../translations/zh_CN/timers/no_hz.rst       | 337 ++++++++++++++++++
>   .../translations/zh_CN/timers/timekeeping.rst | 202 +++++++++++
>   8 files changed, 1206 insertions(+), 4 deletions(-)
>   create mode 100644 Documentation/translations/zh_CN/timers/delay_sleep_functions.rst
>   create mode 100644 Documentation/translations/zh_CN/timers/highres.rst
>   create mode 100644 Documentation/translations/zh_CN/timers/hpet.rst
>   create mode 100644 Documentation/translations/zh_CN/timers/hrtimers.rst
>   create mode 100644 Documentation/translations/zh_CN/timers/index.rst
>   create mode 100644 Documentation/translations/zh_CN/timers/no_hz.rst
>   create mode 100644 Documentation/translations/zh_CN/timers/timekeeping.rst
>