[PATCH 0/3] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 2)

[PATCH 0/3] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 2)

[Binbin Zhou]

Hi all:

As a continuation of the previous patchset
(https://lore.kernel.org/all/cover.1660881950.git.zhoubinbin@loongson.cn/),
this patchset contains the Chinese translations of the remaining three files.

As follows:

this_cpu_ops.rst
timekeeping.rst
errseq.rst

So far, the docs for the "Data structures and low-level utilities"
section of core-api has been fully translated.

Thanks.

Binbin Zhou (3):
  docs/zh_CN: core-api: Add this_cpu_ops Chinese translation
  docs/zh_CN: core-api: Add timekeeping Chinese translation
  docs/zh_CN: core-api: Add errseq Chinese translation

 .../translations/zh_CN/core-api/errseq.rst    | 141 +++++++++
 .../translations/zh_CN/core-api/index.rst     |   5 -
 .../zh_CN/core-api/this_cpu_ops.rst           | 281 ++++++++++++++++++
 .../zh_CN/core-api/timekeeping.rst            | 172 +++++++++++
 4 files changed, 594 insertions(+), 5 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/errseq.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/timekeeping.rst

-- 
2.31.1

[PATCH 1/3] docs/zh_CN: core-api: Add this_cpu_ops Chinese translation

[Binbin Zhou]

Translate core-api/this_cpu_ops.rst into Chinese.

Last English version used:

commit c9b54d6f362c ("docs: move other kAPI documents to core-api").

Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
---
 .../translations/zh_CN/core-api/index.rst     |   2 +-
 .../zh_CN/core-api/this_cpu_ops.rst           | 281 ++++++++++++++++++
 2 files changed, 282 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/this_cpu_ops.rst

diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 37756d240b5e..21d0b25bc580 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -48,12 +48,12 @@
    circular-buffers
    generic-radix-tree
    packing
+   this_cpu_ops
 
 Todolist:
 
 
 
-   this_cpu_ops
    timekeeping
    errseq
 
diff --git a/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
new file mode 100644
index 000000000000..45e2bcb844cb
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
@@ -0,0 +1,281 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/this_cpu_ops.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+============
+this_cpu操作
+============
+
+:作者: Christoph Lameter, 2014年8月4日
+:作者: Pranith Kumar, 2014年8月2日
+
+this_cpu操作是一种优化访问与当前执行处理器相关的per cpu变量的方法。这是通过使用段
+寄存器（或专用寄存器，cpu在其中永久存储特定处理器的per cpu区域的起始）来完成的。
+
+this_cpu操作将per cpu变量的偏移量添加到处理器特定的per cpu基址上，并将该操作编码
+到对per cpu变量进行操作的指令中。
+
+这意味着在偏移量的计算和对数据的操作之间不存在原子性问题。因此，没有必要禁用抢占
+或中断来确保处理器在计算地址和数据操作之间不被改变。
+
+读取-修改-写入操作特别值得关注。通常处理器具有特殊的低延迟指令，可以在没有典型同
+步开销的情况下运行，但仍提供某种宽松的原子性保证。例如，x86可以执行RMW（读取，
+修改，写入）指令，如inc/dec/cmpxchg，而无需锁前缀和相关的延迟损失。
+
+对没有锁前缀的变量的访问是不同步的，也不需要同步，因为我们处理的是当前执行的处理
+器所特有的per cpu数据。只有当前的处理器可以访问该变量，因此系统中的其他处理器不存
+在并发性问题。
+
+请注意，远程处理器对per cpu区域的访问是特殊情况，可能会影响通过this_cpu_*的本地
+RMW操作的性能和正确性（远程写操作）。
+
+this_cpu操作的主要用途是优化计数器操作。
+
+定义了以下具有隐含抢占保护的this_cpu()操作。可以使用这些操作而不用担心抢占和中断::
+
+	this_cpu_read(pcp)
+	this_cpu_write(pcp, val)
+	this_cpu_add(pcp, val)
+	this_cpu_and(pcp, val)
+	this_cpu_or(pcp, val)
+	this_cpu_add_return(pcp, val)
+	this_cpu_xchg(pcp, nval)
+	this_cpu_cmpxchg(pcp, oval, nval)
+	this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2)
+	this_cpu_sub(pcp, val)
+	this_cpu_inc(pcp)
+	this_cpu_dec(pcp)
+	this_cpu_sub_return(pcp, val)
+	this_cpu_inc_return(pcp)
+	this_cpu_dec_return(pcp)
+
+
+this_cpu操作的内部工作
+----------------------
+
+在x86上，fs:或gs:段寄存器包含per cpu区域的基址。这样就可以简单地使用段覆盖，
+将per cpu相对地址重定位到处理器适当的per cpu区域。所以对per cpu基址的重定位是通过
+段寄存器前缀在指令中编码完成的。
+
+例如::
+
+	DEFINE_PER_CPU(int, x);
+	int z;
+
+	z = this_cpu_read(x);
+
+单指令的结果::
+
+	mov ax, gs:[x]
+
+而不是像per cpu操作那样，先是一系列的地址计算，然后从该地址获取。在this_cpu_ops
+之前，这样的序列还需要先禁用/启用抢占功能，以防止内核在计算过程中将线程移动到不同
+的处理器上。
+
+请思考下面this_cpu操作::
+
+	this_cpu_inc(x)
+
+上面的结果是下面的单条指令（无锁前缀！）::
+
+	inc gs:[x]
+
+而不是在没有段寄存器的情况下所需要的以下操作::
+
+	int *y;
+	int cpu;
+
+	cpu = get_cpu();
+	y = per_cpu_ptr(&x, cpu);
+	(*y)++;
+	put_cpu();
+
+请注意，这些操作只能用于为特定处理器保留的per cpu数据。如果不在上下文代码中禁用抢
+占，this_cpu_inc()将仅保证per cpu的某一个计数器被正确地递增，但不能保证操作系统不
+会在this_cpu指令执行的前后直接移动该进程。一般来说，这意味着每个处理器的单个计数
+器的值是没有意义的。所有per cpu计数器的总和才是唯一有意义的值。
+
+per cpu变量的使用是出于性能的考虑。如果多个处理器同时处理相同的代码路径，可以避免
+缓存行跳转。由于每个处理器都有自己的per cpu变量，因此不会发生并发缓存行更新。为这
+种优化必须付出的代价是，当需要计数器的值时要将per cpu计数器相加。
+
+
+特殊的操作
+----------
+
+::
+
+	y = this_cpu_ptr(&x)
+
+使用per cpu变量的偏移量(&x!)，并返回属于当前执行处理器的per cpu变量的地址。
+this_cpu_ptr避免了通用get_cpu/put_cpu序列所需的多个步骤。没有可用的处理器编号。相
+反，本地per cpu区域的偏移量只是简单地添加到per cpu偏移量上。
+
+请注意，当抢占被禁用时，这个操作通常是在代码段中使用。然后该指针用来访问临界区中
+的本地per cpu数据。当重新启用抢占时，此指针通常不再有用，因为它可能不再指向当前处
+理器的per cpu数据。
+
+Per cpu变量和偏移量
+-------------------
+
+per cpu变量相对于per cpu区域的起始点是有偏移的。尽管它们在代码中看起来像那样，
+但它们没有地址。 不能直接取消引用偏移量。为了构成有效地址，必须将偏移量添加到处理
+器的per cpu区域的基指针。
+
+因此，在per cpu操作的上下文之外使用x或&x是无效的，这种行为通常会被当作一个空指针
+的解引用来处理。
+
+::
+
+	DEFINE_PER_CPU(int, x);
+
+在per cpu操作的上下文中，上面表达式说明x是一个per cpu变量。大多数this_cpu操作都需
+要一个cpu变量。
+
+::
+
+	int __percpu *p = &x;
+
+&x和p是per cpu变量的偏移量。this_cpu_ptr()使用per cpu变量的偏移量，这让它看起来有
+点奇怪。
+
+
+per cpu结构体字段的操作
+-----------------------
+
+假设我们有一个percpu结构::
+
+	struct s {
+		int n,m;
+	};
+
+	DEFINE_PER_CPU(struct s, p);
+
+
+这些字段的操作非常简单::
+
+	this_cpu_inc(p.m)
+
+	z = this_cpu_cmpxchg(p.m, 0, 1);
+
+
+如果我们有一个相对于结构体s的偏移量::
+
+	struct s __percpu *ps = &p;
+
+	this_cpu_dec(ps->m);
+
+	z = this_cpu_inc_return(ps->n);
+
+
+如果我们后面不使用this_cpu ops来操作字段，则指针的计算可能需要使用this_cpu_ptr()::
+
+	struct s *pp;
+
+	pp = this_cpu_ptr(&p);
+
+	pp->m--;
+
+	z = pp->n++;
+
+
+this_cpu ops的变体
+------------------
+
+this_cpu的操作是中断安全的。一些架构不支持这些per cpu的本地操作。在这种情况下，该
+操作必须被禁用中断的代码所取代，然后做那些保证是原子的操作，再重新启用中断。当然
+这样做是很昂贵的。如果有其他原因导致调度器不能改变我们正在执行的处理器，那么就没
+有理由禁用中断了。为此，我们提供了以下__this_cpu操作。
+
+这些操作不能保证并发中断或抢占。如果在中断上下文中不使用per cpu变量并且调度程序无
+法抢占，那么它们是安全的。如果在操作进行时仍有中断发生，并且中断也修改了变量，则
+无法保证RMW操作是安全的::
+
+	__this_cpu_read(pcp)
+	__this_cpu_write(pcp, val)
+	__this_cpu_add(pcp, val)
+	__this_cpu_and(pcp, val)
+	__this_cpu_or(pcp, val)
+	__this_cpu_add_return(pcp, val)
+	__this_cpu_xchg(pcp, nval)
+	__this_cpu_cmpxchg(pcp, oval, nval)
+	__this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2)
+	__this_cpu_sub(pcp, val)
+	__this_cpu_inc(pcp)
+	__this_cpu_dec(pcp)
+	__this_cpu_sub_return(pcp, val)
+	__this_cpu_inc_return(pcp)
+	__this_cpu_dec_return(pcp)
+
+
+将增加x，并且不会回退到在无法通过地址重定位和同一指令中的读取-修改-写入操作实现原
+子性的平台上禁用中断的代码。
+
+
+&this_cpu_ptr(pp)->n 对比 this_cpu_ptr(&pp->n)
+----------------------------------------------
+
+第一个操作使用偏移量并形成一个地址，然后再加上n字段的偏移量。这可能会导致编译器产
+生两条加法指令。
+
+第二个操作先加上两个偏移量，然后进行重定位。恕我直言，第二种形式看起来更干净，而
+且更容易与()结合。第二种形式也与this_cpu_read()和大家的使用方式一致。
+
+
+远程访问per cpu数据
+-------------------
+
+per cpu数据结构被设计为由一个CPU独占使用。如果您按预期使用变量，则this_cpu_ops()
+保证是“原子的”，因为没有其他CPU可以访问这些数据结构。
+
+在某些特殊情况下，您可能需要远程访问per cpu数据结构。通常情况下，进行远程读访问是
+安全的，这经常是为了统计计数器值。远程写访问可能会出现问题，因为this_cpu操作没有
+锁语义。远程写可能会干扰this_cpu RMW操作。
+
+除非绝对必要，否则强烈建议不要对percpu数据结构进行远程写访问。请考虑使用IPI来唤
+醒远程CPU，并对其per cpu区域进行更新。
+
+要远程访问per-cpu数据结构，通常使用per_cpu_ptr()函数::
+
+
+	DEFINE_PER_CPU(struct data, datap);
+
+	struct data *p = per_cpu_ptr(&datap, cpu);
+
+这清楚地表明，我们正准备远程访问percpu区域。
+
+您还可以执行以下操作以将datap偏移量转换为地址::
+
+	struct data *p = this_cpu_ptr(&datap);
+
+但是，将通过this_cpu_ptr计算的指针传递给其他cpu是不寻常的，应该避免。
+
+远程访问通常只用于读取另一个cpu的per cpu数据状态。由于this_cpu操作宽松的同步要求，
+写访问可能会导致独特的问题。
+
+下面的情况说明了写入操作的一些问题，由于两个per cpu变量共享一个缓存行，但宽松的同
+步仅应用于更新缓存行的一个进程。
+
+考虑以下示例::
+
+
+	struct test {
+		atomic_t a;
+		int b;
+	};
+
+	DEFINE_PER_CPU(struct test, onecacheline);
+
+如果一个处理器远程更新字段'a'，而本地处理器将使用this_cpu ops来更新字段b，会发生
+什么情况，这一点值得注意。应避免在同一缓存行内同时访问数据。此外，可能还需要进行
+代价高昂的同步。在这种情况下，通常建议使用IPI，而不是远程写入另一个处理器的
+per cpu区域。
+
+即使在远程写很少的情况下，请记住远程写将从最有可能访问它的处理器中逐出缓存行。如
+果处理器唤醒时发现per cpu区域缺少本地缓存行，其性能和唤醒时间将受到影响。
-- 
2.31.1

Re: [PATCH 1/3] docs/zh_CN: core-api: Add this_cpu_ops Chinese translation

[Wu XiangCheng]

> Translate core-api/this_cpu_ops.rst into Chinese.
> 
> Last English version used:
> 
> commit c9b54d6f362c ("docs: move other kAPI documents to core-api").
> 
> Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
> ---
>  .../translations/zh_CN/core-api/index.rst     |   2 +-
>  .../zh_CN/core-api/this_cpu_ops.rst           | 281 ++++++++++++++++++
>  2 files changed, 282 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
> 
> diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> index 37756d240b5e..21d0b25bc580 100644
> --- a/Documentation/translations/zh_CN/core-api/index.rst
> +++ b/Documentation/translations/zh_CN/core-api/index.rst
> @@ -48,12 +48,12 @@
>     circular-buffers
>     generic-radix-tree
>     packing
> +   this_cpu_ops
>  
>  Todolist:
>  
>  
>  
> -   this_cpu_ops
>     timekeeping
>     errseq
>  
> diff --git a/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
> new file mode 100644
> index 000000000000..45e2bcb844cb
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
> @@ -0,0 +1,281 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/core-api/this_cpu_ops.rst
> +
> +:翻译:
> +
> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
> +
> +============
> +this_cpu操作
> +============
> +
> +:作者: Christoph Lameter, 2014年8月4日
> +:作者: Pranith Kumar, 2014年8月2日
> +
> +this_cpu操作是一种优化访问与当前执行处理器相关的per cpu变量的方法。这是通过使用段

per cpu -> 逐cpu 或 每cpu
replace all per cpu/percpu/per-cpu...

see
loongarch/introduction.rst:51:    存每CPU变量基地址。该寄存器没有ABI命名，不


> +寄存器（或专用寄存器，cpu在其中永久存储特定处理器的per cpu区域的起始）来完成的。
> +
> +this_cpu操作将per cpu变量的偏移量添加到处理器特定的per cpu基址上，并将该操作编码
> +到对per cpu变量进行操作的指令中。
> +
> +这意味着在偏移量的计算和对数据的操作之间不存在原子性问题。因此，没有必要禁用抢占
> +或中断来确保处理器在计算地址和数据操作之间不被改变。
> +
> +读取-修改-写入操作特别值得关注。通常处理器具有特殊的低延迟指令，可以在没有典型同
> +步开销的情况下运行，但仍提供某种宽松的原子性保证。例如，x86可以执行RMW（读取，
> +修改，写入）指令，如inc/dec/cmpxchg，而无需锁前缀和相关的延迟损失。

如 -> 如同

> +
> +对没有锁前缀的变量的访问是不同步的，也不需要同步，因为我们处理的是当前执行的处理
> +器所特有的per cpu数据。只有当前的处理器可以访问该变量，因此系统中的其他处理器不存
> +在并发性问题。
> +
> +请注意，远程处理器对per cpu区域的访问是特殊情况，可能会影响通过this_cpu_*的本地
> +RMW操作的性能和正确性（远程写操作）。
> +
> +this_cpu操作的主要用途是优化计数器操作。
> +
> +定义了以下具有隐含抢占保护的this_cpu()操作。可以使用这些操作而不用担心抢占和中断::
> +
> +	this_cpu_read(pcp)
> +	this_cpu_write(pcp, val)
> +	this_cpu_add(pcp, val)
> +	this_cpu_and(pcp, val)
> +	this_cpu_or(pcp, val)
> +	this_cpu_add_return(pcp, val)
> +	this_cpu_xchg(pcp, nval)
> +	this_cpu_cmpxchg(pcp, oval, nval)
> +	this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2)
> +	this_cpu_sub(pcp, val)
> +	this_cpu_inc(pcp)
> +	this_cpu_dec(pcp)
> +	this_cpu_sub_return(pcp, val)
> +	this_cpu_inc_return(pcp)
> +	this_cpu_dec_return(pcp)
> +
> +
> +this_cpu操作的内部工作
> +----------------------
> +
> +在x86上，fs:或gs:段寄存器包含per cpu区域的基址。这样就可以简单地使用段覆盖，
> +将per cpu相对地址重定位到处理器适当的per cpu区域。所以对per cpu基址的重定位是通过
> +段寄存器前缀在指令中编码完成的。
> +
> +例如::
> +
> +	DEFINE_PER_CPU(int, x);
> +	int z;
> +
> +	z = this_cpu_read(x);
> +
> +单指令的结果::

产生的单指令为::

> +
> +	mov ax, gs:[x]
> +
> +而不是像per cpu操作那样，先是一系列的地址计算，然后从该地址获取。在this_cpu_ops
> +之前，这样的序列还需要先禁用/启用抢占功能，以防止内核在计算过程中将线程移动到不同
> +的处理器上。
> +
> +请思考下面this_cpu操作::
> +
> +	this_cpu_inc(x)
> +
> +上面的结果是下面的单条指令（无锁前缀！）::

这将产生如下单指令（无锁前缀！）::

> +
> +	inc gs:[x]
> +
> +而不是在没有段寄存器的情况下所需要的以下操作::
> +
> +	int *y;
> +	int cpu;
> +
> +	cpu = get_cpu();
> +	y = per_cpu_ptr(&x, cpu);
> +	(*y)++;
> +	put_cpu();
> +
> +请注意，这些操作只能用于为特定处理器保留的per cpu数据。如果不在上下文代码中禁用抢
> +占，this_cpu_inc()将仅保证per cpu的某一个计数器被正确地递增，但不能保证操作系统不
> +会在this_cpu指令执行的前后直接移动该进程。一般来说，这意味着每个处理器的单个计数
> +器的值是没有意义的。所有per cpu计数器的总和才是唯一有意义的值。
> +
> +per cpu变量的使用是出于性能的考虑。如果多个处理器同时处理相同的代码路径，可以避免
> +缓存行跳转。由于每个处理器都有自己的per cpu变量，因此不会发生并发缓存行更新。为这

remove 由于

> +种优化必须付出的代价是，当需要计数器的值时要将per cpu计数器相加。
> +
> +
> +特殊的操作
> +----------
> +
> +::
> +
> +	y = this_cpu_ptr(&x)
> +
> +使用per cpu变量的偏移量(&x!)，并返回属于当前执行处理器的per cpu变量的地址。
> +this_cpu_ptr避免了通用get_cpu/put_cpu序列所需的多个步骤。没有可用的处理器编号。相
> +反，本地per cpu区域的偏移量只是简单地添加到per cpu偏移量上。
> +
> +请注意，当抢占被禁用时，这个操作通常是在代码段中使用。然后该指针用来访问临界区中

这个操作通常是在抢占被禁用后再在代码段中使用
"has been disabled"

> +的本地per cpu数据。当重新启用抢占时，此指针通常不再有用，因为它可能不再指向当前处
> +理器的per cpu数据。
> +
> +Per cpu变量和偏移量
> +-------------------
> +
> +per cpu变量相对于per cpu区域的起始点是有偏移的。尽管它们在代码中看起来像那样，

它们没有地址，尽管代码里看起来像有一样。

> +但它们没有地址。 不能直接取消引用偏移量。为了构成有效地址，必须将偏移量添加到处理
> +器的per cpu区域的基指针。

不能直接对偏移量解引用。必须用处理器每cpu区域基指针加上偏移量，以构成有效地址。

> +
> +因此，在per cpu操作的上下文之外使用x或&x是无效的，这种行为通常会被当作一个空指针
> +的解引用来处理。
> +
> +::
> +
> +	DEFINE_PER_CPU(int, x);
> +
> +在per cpu操作的上下文中，上面表达式说明x是一个per cpu变量。大多数this_cpu操作都需
> +要一个cpu变量。
> +
> +::
> +
> +	int __percpu *p = &x;
> +
> +&x和p是per cpu变量的偏移量。this_cpu_ptr()使用per cpu变量的偏移量，这让它看起来有
> +点奇怪。
> +
> +
> +per cpu结构体字段的操作
> +-----------------------
> +
> +假设我们有一个percpu结构::
> +
> +	struct s {
> +		int n,m;
> +	};
> +
> +	DEFINE_PER_CPU(struct s, p);
> +
> +
> +这些字段的操作非常简单::
> +
> +	this_cpu_inc(p.m)
> +
> +	z = this_cpu_cmpxchg(p.m, 0, 1);
> +
> +
> +如果我们有一个相对于结构体s的偏移量::
> +
> +	struct s __percpu *ps = &p;
> +
> +	this_cpu_dec(ps->m);
> +
> +	z = this_cpu_inc_return(ps->n);
> +
> +
> +如果我们后面不使用this_cpu ops来操作字段，则指针的计算可能需要使用this_cpu_ptr()::
> +
> +	struct s *pp;
> +
> +	pp = this_cpu_ptr(&p);
> +
> +	pp->m--;
> +
> +	z = pp->n++;
> +
> +
> +this_cpu ops的变体
> +------------------
> +
> +this_cpu的操作是中断安全的。一些架构不支持这些per cpu的本地操作。在这种情况下，该
> +操作必须被禁用中断的代码所取代，然后做那些保证是原子的操作，再重新启用中断。当然
> +这样做是很昂贵的。如果有其他原因导致调度器不能改变我们正在执行的处理器，那么就没
> +有理由禁用中断了。为此，我们提供了以下__this_cpu操作。
> +
> +这些操作不能保证并发中断或抢占。如果在中断上下文中不使用per cpu变量并且调度程序无
> +法抢占，那么它们是安全的。如果在操作进行时仍有中断发生，并且中断也修改了变量，则
> +无法保证RMW操作是安全的::
> +
> +	__this_cpu_read(pcp)
> +	__this_cpu_write(pcp, val)
> +	__this_cpu_add(pcp, val)
> +	__this_cpu_and(pcp, val)
> +	__this_cpu_or(pcp, val)
> +	__this_cpu_add_return(pcp, val)
> +	__this_cpu_xchg(pcp, nval)
> +	__this_cpu_cmpxchg(pcp, oval, nval)
> +	__this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2)
> +	__this_cpu_sub(pcp, val)
> +	__this_cpu_inc(pcp)
> +	__this_cpu_dec(pcp)
> +	__this_cpu_sub_return(pcp, val)
> +	__this_cpu_inc_return(pcp)
> +	__this_cpu_dec_return(pcp)
> +
> +
> +将增加x，并且不会回退到在无法通过地址重定位和同一指令中的读取-修改-写入操作实现原
> +子性的平台上禁用中断的代码。
> +
> +
> +&this_cpu_ptr(pp)->n 对比 this_cpu_ptr(&pp->n)
> +----------------------------------------------
> +
> +第一个操作使用偏移量并形成一个地址，然后再加上n字段的偏移量。这可能会导致编译器产
> +生两条加法指令。
> +
> +第二个操作先加上两个偏移量，然后进行重定位。恕我直言，第二种形式看起来更干净，而
> +且更容易与()结合。第二种形式也与this_cpu_read()和大家的使用方式一致。
> +
> +
> +远程访问per cpu数据
> +-------------------
> +
> +per cpu数据结构被设计为由一个CPU独占使用。如果您按预期使用变量，则this_cpu_ops()
> +保证是“原子的”，因为没有其他CPU可以访问这些数据结构。
> +
> +在某些特殊情况下，您可能需要远程访问per cpu数据结构。通常情况下，进行远程读访问是
> +安全的，这经常是为了统计计数器值。远程写访问可能会出现问题，因为this_cpu操作没有
> +锁语义。远程写可能会干扰this_cpu RMW操作。
> +
> +除非绝对必要，否则强烈建议不要对percpu数据结构进行远程写访问。请考虑使用IPI来唤
> +醒远程CPU，并对其per cpu区域进行更新。
> +
> +要远程访问per-cpu数据结构，通常使用per_cpu_ptr()函数::
> +
> +
> +	DEFINE_PER_CPU(struct data, datap);
> +
> +	struct data *p = per_cpu_ptr(&datap, cpu);
> +
> +这清楚地表明，我们正准备远程访问percpu区域。
> +
> +您还可以执行以下操作以将datap偏移量转换为地址::
> +
> +	struct data *p = this_cpu_ptr(&datap);
> +
> +但是，将通过this_cpu_ptr计算的指针传递给其他cpu是不寻常的，应该避免。
> +
> +远程访问通常只用于读取另一个cpu的per cpu数据状态。由于this_cpu操作宽松的同步要求，
> +写访问可能会导致独特的问题。

奇特

> +
> +下面的情况说明了写入操作的一些问题，由于两个per cpu变量共享一个缓存行，但宽松的同
> +步仅应用于更新缓存行的一个进程。
> +
> +考虑以下示例::
> +
> +
> +	struct test {
> +		atomic_t a;
> +		int b;
> +	};
> +
> +	DEFINE_PER_CPU(struct test, onecacheline);
> +
> +如果一个处理器远程更新字段'a'，而本地处理器将使用this_cpu ops来更新字段b，会发生

``a`` ``b`` or a b or ‘a’ ‘b’
just use a better style, depend on your mind.

> +什么情况，这一点值得注意。应避免在同一缓存行内同时访问数据。此外，可能还需要进行
> +代价高昂的同步。在这种情况下，通常建议使用IPI，而不是远程写入另一个处理器的
> +per cpu区域。
> +
> +即使在远程写很少的情况下，请记住远程写将从最有可能访问它的处理器中逐出缓存行。如
> +果处理器唤醒时发现per cpu区域缺少本地缓存行，其性能和唤醒时间将受到影响。
> -- 
> 2.31.1
> 
> 
Thanks,
	Wu

Re: [PATCH 1/3] docs/zh_CN: core-api: Add this_cpu_ops Chinese translation

[Binbin Zhou]

Hi XiangCheng:

On Mon, Oct 17, 2022 at 12:12 AM Wu XiangCheng <wu.xiangcheng@linux.dev> wrote:
>
> > Translate core-api/this_cpu_ops.rst into Chinese.
> >
> > Last English version used:
> >
> > commit c9b54d6f362c ("docs: move other kAPI documents to core-api").
> >
> > Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
> > ---
> >  .../translations/zh_CN/core-api/index.rst     |   2 +-
> >  .../zh_CN/core-api/this_cpu_ops.rst           | 281 ++++++++++++++++++
> >  2 files changed, 282 insertions(+), 1 deletion(-)
> >  create mode 100644 Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
> >
> > diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> > index 37756d240b5e..21d0b25bc580 100644
> > --- a/Documentation/translations/zh_CN/core-api/index.rst
> > +++ b/Documentation/translations/zh_CN/core-api/index.rst
> > @@ -48,12 +48,12 @@
> >     circular-buffers
> >     generic-radix-tree
> >     packing
> > +   this_cpu_ops
> >
> >  Todolist:
> >
> >
> >
> > -   this_cpu_ops
> >     timekeeping
> >     errseq
> >
> > diff --git a/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
> > new file mode 100644
> > index 000000000000..45e2bcb844cb
> > --- /dev/null
> > +++ b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
> > @@ -0,0 +1,281 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> > +.. include:: ../disclaimer-zh_CN.rst
> > +
> > +:Original: Documentation/core-api/this_cpu_ops.rst
> > +
> > +:翻译:
> > +
> > + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
> > +
> > +============
> > +this_cpu操作
> > +============
> > +
> > +:作者: Christoph Lameter, 2014年8月4日
> > +:作者: Pranith Kumar, 2014年8月2日
> > +
> > +this_cpu操作是一种优化访问与当前执行处理器相关的per cpu变量的方法。这是通过使用段
>
> per cpu -> 逐cpu 或 每cpu
> replace all per cpu/percpu/per-cpu...
>
> see
> loongarch/introduction.rst:51:    存每CPU变量基地址。该寄存器没有ABI命名，不

OK, I will do it.
>
>
> > +寄存器（或专用寄存器，cpu在其中永久存储特定处理器的per cpu区域的起始）来完成的。
> > +
> > +this_cpu操作将per cpu变量的偏移量添加到处理器特定的per cpu基址上，并将该操作编码
> > +到对per cpu变量进行操作的指令中。
> > +
> > +这意味着在偏移量的计算和对数据的操作之间不存在原子性问题。因此，没有必要禁用抢占
> > +或中断来确保处理器在计算地址和数据操作之间不被改变。
> > +
> > +读取-修改-写入操作特别值得关注。通常处理器具有特殊的低延迟指令，可以在没有典型同
> > +步开销的情况下运行，但仍提供某种宽松的原子性保证。例如，x86可以执行RMW（读取，
> > +修改，写入）指令，如inc/dec/cmpxchg，而无需锁前缀和相关的延迟损失。
>
> 如 -> 如同

OK..
>
> > +
> > +对没有锁前缀的变量的访问是不同步的，也不需要同步，因为我们处理的是当前执行的处理
> > +器所特有的per cpu数据。只有当前的处理器可以访问该变量，因此系统中的其他处理器不存
> > +在并发性问题。
> > +
> > +请注意，远程处理器对per cpu区域的访问是特殊情况，可能会影响通过this_cpu_*的本地
> > +RMW操作的性能和正确性（远程写操作）。
> > +
> > +this_cpu操作的主要用途是优化计数器操作。
> > +
> > +定义了以下具有隐含抢占保护的this_cpu()操作。可以使用这些操作而不用担心抢占和中断::
> > +
> > +     this_cpu_read(pcp)
> > +     this_cpu_write(pcp, val)
> > +     this_cpu_add(pcp, val)
> > +     this_cpu_and(pcp, val)
> > +     this_cpu_or(pcp, val)
> > +     this_cpu_add_return(pcp, val)
> > +     this_cpu_xchg(pcp, nval)
> > +     this_cpu_cmpxchg(pcp, oval, nval)
> > +     this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2)
> > +     this_cpu_sub(pcp, val)
> > +     this_cpu_inc(pcp)
> > +     this_cpu_dec(pcp)
> > +     this_cpu_sub_return(pcp, val)
> > +     this_cpu_inc_return(pcp)
> > +     this_cpu_dec_return(pcp)
> > +
> > +
> > +this_cpu操作的内部工作
> > +----------------------
> > +
> > +在x86上，fs:或gs:段寄存器包含per cpu区域的基址。这样就可以简单地使用段覆盖，
> > +将per cpu相对地址重定位到处理器适当的per cpu区域。所以对per cpu基址的重定位是通过
> > +段寄存器前缀在指令中编码完成的。
> > +
> > +例如::
> > +
> > +     DEFINE_PER_CPU(int, x);
> > +     int z;
> > +
> > +     z = this_cpu_read(x);
> > +
> > +单指令的结果::
>
> 产生的单指令为::
OK..
>
> > +
> > +     mov ax, gs:[x]
> > +
> > +而不是像per cpu操作那样，先是一系列的地址计算，然后从该地址获取。在this_cpu_ops
> > +之前，这样的序列还需要先禁用/启用抢占功能，以防止内核在计算过程中将线程移动到不同
> > +的处理器上。
> > +
> > +请思考下面this_cpu操作::
> > +
> > +     this_cpu_inc(x)
> > +
> > +上面的结果是下面的单条指令（无锁前缀！）::
>
> 这将产生如下单指令（无锁前缀！）::
OK..
>
> > +
> > +     inc gs:[x]
> > +
> > +而不是在没有段寄存器的情况下所需要的以下操作::
> > +
> > +     int *y;
> > +     int cpu;
> > +
> > +     cpu = get_cpu();
> > +     y = per_cpu_ptr(&x, cpu);
> > +     (*y)++;
> > +     put_cpu();
> > +
> > +请注意，这些操作只能用于为特定处理器保留的per cpu数据。如果不在上下文代码中禁用抢
> > +占，this_cpu_inc()将仅保证per cpu的某一个计数器被正确地递增，但不能保证操作系统不
> > +会在this_cpu指令执行的前后直接移动该进程。一般来说，这意味着每个处理器的单个计数
> > +器的值是没有意义的。所有per cpu计数器的总和才是唯一有意义的值。
> > +
> > +per cpu变量的使用是出于性能的考虑。如果多个处理器同时处理相同的代码路径，可以避免
> > +缓存行跳转。由于每个处理器都有自己的per cpu变量，因此不会发生并发缓存行更新。为这
>
> remove 由于
OK..
>
> > +种优化必须付出的代价是，当需要计数器的值时要将per cpu计数器相加。
> > +
> > +
> > +特殊的操作
> > +----------
> > +
> > +::
> > +
> > +     y = this_cpu_ptr(&x)
> > +
> > +使用per cpu变量的偏移量(&x!)，并返回属于当前执行处理器的per cpu变量的地址。
> > +this_cpu_ptr避免了通用get_cpu/put_cpu序列所需的多个步骤。没有可用的处理器编号。相
> > +反，本地per cpu区域的偏移量只是简单地添加到per cpu偏移量上。
> > +
> > +请注意，当抢占被禁用时，这个操作通常是在代码段中使用。然后该指针用来访问临界区中
>
> 这个操作通常是在抢占被禁用后再在代码段中使用
> "has been disabled"
>
> > +的本地per cpu数据。当重新启用抢占时，此指针通常不再有用，因为它可能不再指向当前处
> > +理器的per cpu数据。
> > +
> > +Per cpu变量和偏移量
> > +-------------------
> > +
> > +per cpu变量相对于per cpu区域的起始点是有偏移的。尽管它们在代码中看起来像那样，
>
> 它们没有地址，尽管代码里看起来像有一样。
OK..
>
> > +但它们没有地址。 不能直接取消引用偏移量。为了构成有效地址，必须将偏移量添加到处理
> > +器的per cpu区域的基指针。
>
> 不能直接对偏移量解引用。必须用处理器每cpu区域基指针加上偏移量，以构成有效地址。
OK,
I will reorganize the translation of this part.
>
> > +
> > +因此，在per cpu操作的上下文之外使用x或&x是无效的，这种行为通常会被当作一个空指针
> > +的解引用来处理。
> > +
> > +::
> > +
> > +     DEFINE_PER_CPU(int, x);
> > +
> > +在per cpu操作的上下文中，上面表达式说明x是一个per cpu变量。大多数this_cpu操作都需
> > +要一个cpu变量。
> > +
> > +::
> > +
> > +     int __percpu *p = &x;
> > +
> > +&x和p是per cpu变量的偏移量。this_cpu_ptr()使用per cpu变量的偏移量，这让它看起来有
> > +点奇怪。
> > +
> > +
> > +per cpu结构体字段的操作
> > +-----------------------
> > +
> > +假设我们有一个percpu结构::
> > +
> > +     struct s {
> > +             int n,m;
> > +     };
> > +
> > +     DEFINE_PER_CPU(struct s, p);
> > +
> > +
> > +这些字段的操作非常简单::
> > +
> > +     this_cpu_inc(p.m)
> > +
> > +     z = this_cpu_cmpxchg(p.m, 0, 1);
> > +
> > +
> > +如果我们有一个相对于结构体s的偏移量::
> > +
> > +     struct s __percpu *ps = &p;
> > +
> > +     this_cpu_dec(ps->m);
> > +
> > +     z = this_cpu_inc_return(ps->n);
> > +
> > +
> > +如果我们后面不使用this_cpu ops来操作字段，则指针的计算可能需要使用this_cpu_ptr()::
> > +
> > +     struct s *pp;
> > +
> > +     pp = this_cpu_ptr(&p);
> > +
> > +     pp->m--;
> > +
> > +     z = pp->n++;
> > +
> > +
> > +this_cpu ops的变体
> > +------------------
> > +
> > +this_cpu的操作是中断安全的。一些架构不支持这些per cpu的本地操作。在这种情况下，该
> > +操作必须被禁用中断的代码所取代，然后做那些保证是原子的操作，再重新启用中断。当然
> > +这样做是很昂贵的。如果有其他原因导致调度器不能改变我们正在执行的处理器，那么就没
> > +有理由禁用中断了。为此，我们提供了以下__this_cpu操作。
> > +
> > +这些操作不能保证并发中断或抢占。如果在中断上下文中不使用per cpu变量并且调度程序无
> > +法抢占，那么它们是安全的。如果在操作进行时仍有中断发生，并且中断也修改了变量，则
> > +无法保证RMW操作是安全的::
> > +
> > +     __this_cpu_read(pcp)
> > +     __this_cpu_write(pcp, val)
> > +     __this_cpu_add(pcp, val)
> > +     __this_cpu_and(pcp, val)
> > +     __this_cpu_or(pcp, val)
> > +     __this_cpu_add_return(pcp, val)
> > +     __this_cpu_xchg(pcp, nval)
> > +     __this_cpu_cmpxchg(pcp, oval, nval)
> > +     __this_cpu_cmpxchg_double(pcp1, pcp2, oval1, oval2, nval1, nval2)
> > +     __this_cpu_sub(pcp, val)
> > +     __this_cpu_inc(pcp)
> > +     __this_cpu_dec(pcp)
> > +     __this_cpu_sub_return(pcp, val)
> > +     __this_cpu_inc_return(pcp)
> > +     __this_cpu_dec_return(pcp)
> > +
> > +
> > +将增加x，并且不会回退到在无法通过地址重定位和同一指令中的读取-修改-写入操作实现原
> > +子性的平台上禁用中断的代码。
> > +
> > +
> > +&this_cpu_ptr(pp)->n 对比 this_cpu_ptr(&pp->n)
> > +----------------------------------------------
> > +
> > +第一个操作使用偏移量并形成一个地址，然后再加上n字段的偏移量。这可能会导致编译器产
> > +生两条加法指令。
> > +
> > +第二个操作先加上两个偏移量，然后进行重定位。恕我直言，第二种形式看起来更干净，而
> > +且更容易与()结合。第二种形式也与this_cpu_read()和大家的使用方式一致。
> > +
> > +
> > +远程访问per cpu数据
> > +-------------------
> > +
> > +per cpu数据结构被设计为由一个CPU独占使用。如果您按预期使用变量，则this_cpu_ops()
> > +保证是“原子的”，因为没有其他CPU可以访问这些数据结构。
> > +
> > +在某些特殊情况下，您可能需要远程访问per cpu数据结构。通常情况下，进行远程读访问是
> > +安全的，这经常是为了统计计数器值。远程写访问可能会出现问题，因为this_cpu操作没有
> > +锁语义。远程写可能会干扰this_cpu RMW操作。
> > +
> > +除非绝对必要，否则强烈建议不要对percpu数据结构进行远程写访问。请考虑使用IPI来唤
> > +醒远程CPU，并对其per cpu区域进行更新。
> > +
> > +要远程访问per-cpu数据结构，通常使用per_cpu_ptr()函数::
> > +
> > +
> > +     DEFINE_PER_CPU(struct data, datap);
> > +
> > +     struct data *p = per_cpu_ptr(&datap, cpu);
> > +
> > +这清楚地表明，我们正准备远程访问percpu区域。
> > +
> > +您还可以执行以下操作以将datap偏移量转换为地址::
> > +
> > +     struct data *p = this_cpu_ptr(&datap);
> > +
> > +但是，将通过this_cpu_ptr计算的指针传递给其他cpu是不寻常的，应该避免。
> > +
> > +远程访问通常只用于读取另一个cpu的per cpu数据状态。由于this_cpu操作宽松的同步要求，
> > +写访问可能会导致独特的问题。
>
> 奇特

OK..
>
> > +
> > +下面的情况说明了写入操作的一些问题，由于两个per cpu变量共享一个缓存行，但宽松的同
> > +步仅应用于更新缓存行的一个进程。
> > +
> > +考虑以下示例::
> > +
> > +
> > +     struct test {
> > +             atomic_t a;
> > +             int b;
> > +     };
> > +
> > +     DEFINE_PER_CPU(struct test, onecacheline);
> > +
> > +如果一个处理器远程更新字段'a'，而本地处理器将使用this_cpu ops来更新字段b，会发生
>
> ``a`` ``b`` or a b or ‘a’ ‘b’
> just use a better style, depend on your mind.

For me, ``a`` is probably a better choice, I'll unify the format.

Thanks for your review.

Binbin

>
> > +什么情况，这一点值得注意。应避免在同一缓存行内同时访问数据。此外，可能还需要进行
> > +代价高昂的同步。在这种情况下，通常建议使用IPI，而不是远程写入另一个处理器的
> > +per cpu区域。
> > +
> > +即使在远程写很少的情况下，请记住远程写将从最有可能访问它的处理器中逐出缓存行。如
> > +果处理器唤醒时发现per cpu区域缺少本地缓存行，其性能和唤醒时间将受到影响。
> > --
> > 2.31.1
> >
> >
> Thanks,
>         Wu
>

[PATCH 2/3] docs/zh_CN: core-api: Add timekeeping Chinese translation

[Binbin Zhou]

Translate core-api/timekeeping.rst into Chinese.

Last English version used:

commit 3dc6ffae2da2 ("timekeeping: Introduce fast accessor to clock tai").

Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
---
 .../translations/zh_CN/core-api/index.rst     |   2 +-
 .../zh_CN/core-api/timekeeping.rst            | 172 ++++++++++++++++++
 2 files changed, 173 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/timekeeping.rst

diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 21d0b25bc580..d08091036066 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -49,12 +49,12 @@
    generic-radix-tree
    packing
    this_cpu_ops
+   timekeeping
 
 Todolist:
 
 
 
-   timekeeping
    errseq
 
 并发原语
diff --git a/Documentation/translations/zh_CN/core-api/timekeeping.rst b/Documentation/translations/zh_CN/core-api/timekeeping.rst
new file mode 100644
index 000000000000..e7f9adf2525c
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/timekeeping.rst
@@ -0,0 +1,172 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/timekeeping.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+ktime访问器
+===========
+
+设备驱动程序可以使用ktime_get()和linux/timekeeping.h中声明的许多相关函数读取当前
+时间。根据经验，如果两者都同样适合特定用例，则使用名称较短的访问器优于名称较长的
+访问器。
+
+基于ktime_t的基础接口
+---------------------
+
+推荐的最简单形式返回不透明的ktime_t，其变体返回不同时钟参考的时间：
+
+.. c:function:: ktime_t ktime_get( void )
+
+	CLOCK_MONOTONIC
+
+        对可靠的时间戳和准确测量短的时间间隔很有用。在系统启动时启动，但在挂起时
+        停止。
+
+.. c:function:: ktime_t ktime_get_boottime( void )
+
+	CLOCK_BOOTTIME
+
+        与ktime_get()类似，但在挂起时不会停止。这可以用于例如需要在挂起操作中与其
+        他计算机同步的密钥过期时间。
+
+.. c:function:: ktime_t ktime_get_real( void )
+
+	CLOCK_REALTIME
+
+        使用协调世界时(UTC)返回相对于1970年开始的UNIX纪元的时间，与用户空间的
+        gettimeofday()相同。该函数用于所有需要在重启时持续存在的时间戳，比如
+        inode时间，但应避免在内部使用，因为它可能由于闰秒更新和来自用户空间的NTP
+        调整settimeofday()操作而向后跳转。
+
+.. c:function:: ktime_t ktime_get_clocktai( void )
+
+	 CLOCK_TAI
+
+        与ktime_get_real()类似，但使用国际原子时(TAI)作为参考而不是UTC，以避免在
+        闰秒更新时跳转。这在内核中很少有用。
+
+.. c:function:: ktime_t ktime_get_raw( void )
+
+	CLOCK_MONOTONIC_RAW
+
+        与ktime_get()类似，但以与硬件时钟源相同的速率运行，无需针对时钟漂移进行调
+        整(NTP)。这在内核中也很少需要。
+
+纳秒，timespec64和秒钟的输出
+----------------------------
+
+对于上述所有情况，以下函数变体会根据用户的要求以不同的格式返回时间：
+
+.. c:function:: u64 ktime_get_ns( void )
+		u64 ktime_get_boottime_ns( void )
+		u64 ktime_get_real_ns( void )
+		u64 ktime_get_clocktai_ns( void )
+		u64 ktime_get_raw_ns( void )
+
+        与普通的ktime_get函数相同，但返回各自时钟参考中的u64纳秒数，这对某些调用
+        者来说可能更方便。
+
+.. c:function:: void ktime_get_ts64( struct timespec64 * )
+		void ktime_get_boottime_ts64( struct timespec64 * )
+		void ktime_get_real_ts64( struct timespec64 * )
+		void ktime_get_clocktai_ts64( struct timespec64 * )
+		void ktime_get_raw_ts64( struct timespec64 * )
+
+        同上，但返回的是'struct timespec64'中的时间，分为秒和纳秒。这可以避免在打
+        印时间时，或在将其传递到期望有'timespec'或'timeval'结构的外部接口时，进行
+        额外的划分。
+
+.. c:function:: time64_t ktime_get_seconds( void )
+		time64_t ktime_get_boottime_seconds( void )
+		time64_t ktime_get_real_seconds( void )
+		time64_t ktime_get_clocktai_seconds( void )
+		time64_t ktime_get_raw_seconds( void )
+
+        将时间的粗粒度版本作为标量time64_t返回。 这避免了访问时钟硬件，并使用相应
+        的参考将秒数舍入到最后一个计时器滴答的完整秒数。
+
+粗略的和fast_ns访问
+-------------------
+
+对于更专业的情况，存在一些额外的变体：
+
+.. c:function:: ktime_t ktime_get_coarse( void )
+		ktime_t ktime_get_coarse_boottime( void )
+		ktime_t ktime_get_coarse_real( void )
+		ktime_t ktime_get_coarse_clocktai( void )
+
+.. c:function:: u64 ktime_get_coarse_ns( void )
+		u64 ktime_get_coarse_boottime_ns( void )
+		u64 ktime_get_coarse_real_ns( void )
+		u64 ktime_get_coarse_clocktai_ns( void )
+
+.. c:function:: void ktime_get_coarse_ts64( struct timespec64 * )
+		void ktime_get_coarse_boottime_ts64( struct timespec64 * )
+		void ktime_get_coarse_real_ts64( struct timespec64 * )
+		void ktime_get_coarse_clocktai_ts64( struct timespec64 * )
+
+        他们比非粗略版本更快，但精度较低，对应于用户空间中的CLOCK_MONOTONIC_COARSE
+        和CLOCK_REALTIME_COARSE，以及用户空间不可用的等效boottime/tai/raw的时间基准。
+
+        此处返回的时间对应于最后一个计时器滴答，过去可能高达10毫秒（对于CONFIG_HZ=100），
+        与读取'jiffies'变量相同。 这些只有在快速路径中调用时才有用，并且人们仍然
+        期望精度优于秒，但不能轻易使用'jiffies'，例如用于inode时间戳。在大多数具
+        有可靠周期计数器的现代机器上，跳过硬件时钟访问可以节省大约100个CPU周期，
+        但在具有外部时钟源的旧硬件上，最多可以节省几微秒。
+
+.. c:function:: u64 ktime_get_mono_fast_ns( void )
+		u64 ktime_get_raw_fast_ns( void )
+		u64 ktime_get_boot_fast_ns( void )
+		u64 ktime_get_tai_fast_ns( void )
+		u64 ktime_get_real_fast_ns( void )
+
+        这些变体可以安全地从任何上下文中调用，包括在计时器更新期间从不屏蔽中断（NMI）
+        调用，以及当我们在时钟源断电的情况下进入挂起状态时。这在某些跟踪或调试代
+        码以及机器检查报告中很有用，但大多数驱动程序不应调用它们，因为在某些情况
+        下时间是允许跳跃的
+
+已废弃的时钟接口
+----------------
+
+较早的内核使用了一些其他接口，这些接口现在正在逐步被淘汰，但可能会出现在被移植到
+的第三方驱动中。特别是，所有返回"struct timeval"或"struct timespec"的接口都已被替
+换，因为在32位架构上，tv_sec成员会在2038年溢出。下面是推荐的替换函数:
+
+.. c:function:: void ktime_get_ts( struct timespec * )
+
+        用ktime_get()或者ktime_get_ts64()替换。
+
+.. c:function:: void do_gettimeofday( struct timeval * )
+		void getnstimeofday( struct timespec * )
+		void getnstimeofday64( struct timespec64 * )
+		void ktime_get_real_ts( struct timespec * )
+
+        ktime_get_real_ts64()可以直接替代，但可以考虑使用单调的时间（ktime_get_ts64()）
+        和/或基于ktime_t的接口（ktime_get()/ktime_get_real()）。
+
+.. c:function:: struct timespec current_kernel_time( void )
+		struct timespec64 current_kernel_time64( void )
+		struct timespec get_monotonic_coarse( void )
+		struct timespec64 get_monotonic_coarse64( void )
+
+        这些被ktime_get_coarse_real_ts64()和ktime_get_coarse_ts64()取代。然而，许
+        多需要粗粒度时间的代码可以使用简单的“jiffies”来代替，而现在一些驱动程序实
+        际上可能需要更高分辨率的访问器。
+
+.. c:function:: struct timespec getrawmonotonic( void )
+		struct timespec64 getrawmonotonic64( void )
+		struct timespec timekeeping_clocktai( void )
+		struct timespec64 timekeeping_clocktai64( void )
+		struct timespec get_monotonic_boottime( void )
+		struct timespec64 get_monotonic_boottime64( void )
+
+        这些被ktime_get_raw()/ktime_get_raw_ts64()，
+        ktime_get_clocktai()/ktime_get_clocktai_ts64()
+        以及ktime_get_boottime()/ktime_get_boottime_ts64()取代。但是，如果时钟源
+        的特定选择对用户来说并不重要，请考虑转换为ktime_get()/ktime_get_ts64()以
+        保持一致性。
-- 
2.31.1

Re: [PATCH 2/3] docs/zh_CN: core-api: Add timekeeping Chinese translation

[Wu XiangCheng]

> Translate core-api/timekeeping.rst into Chinese.
> 
> Last English version used:
> 
> commit 3dc6ffae2da2 ("timekeeping: Introduce fast accessor to clock tai").
> 
> Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
> ---
>  .../translations/zh_CN/core-api/index.rst     |   2 +-
>  .../zh_CN/core-api/timekeeping.rst            | 172 ++++++++++++++++++
>  2 files changed, 173 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/translations/zh_CN/core-api/timekeeping.rst
> 
> diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> index 21d0b25bc580..d08091036066 100644
> --- a/Documentation/translations/zh_CN/core-api/index.rst
> +++ b/Documentation/translations/zh_CN/core-api/index.rst
> @@ -49,12 +49,12 @@
>     generic-radix-tree
>     packing
>     this_cpu_ops
> +   timekeeping
>  
>  Todolist:
>  
>  
>  
> -   timekeeping
>     errseq
>  
>  并发原语
> diff --git a/Documentation/translations/zh_CN/core-api/timekeeping.rst b/Documentation/translations/zh_CN/core-api/timekeeping.rst
> new file mode 100644
> index 000000000000..e7f9adf2525c
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/timekeeping.rst
> @@ -0,0 +1,172 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/core-api/timekeeping.rst
> +
> +:翻译:
> +
> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
> +
> +ktime访问器
> +===========
> +
> +设备驱动程序可以使用ktime_get()和linux/timekeeping.h中声明的许多相关函数读取当前
> +时间。根据经验，如果两者都同样适合特定用例，则使用名称较短的访问器优于名称较长的
> +访问器。

如果两个访问器都适用于某一用例，则使用名称较短的那个。

> +
> +基于ktime_t的基础接口
> +---------------------
> +
> +推荐的最简单形式返回不透明的ktime_t，其变体返回不同时钟参考的时间：
> +
> +.. c:function:: ktime_t ktime_get( void )
> +
> +	CLOCK_MONOTONIC
 ^
 tab

> +
> +        对可靠的时间戳和准确测量短的时间间隔很有用。在系统启动时启动，但在挂起时
> +        停止。
 ^^^^^^^^
 spaces
 check all of them

> +
> +.. c:function:: ktime_t ktime_get_boottime( void )
> +
> +	CLOCK_BOOTTIME
> +
> +        与ktime_get()类似，但在挂起时不会停止。这可以用于例如需要在挂起操作中与其
> +        他计算机同步的密钥过期时间。
> +
> +.. c:function:: ktime_t ktime_get_real( void )
> +
> +	CLOCK_REALTIME
> +
> +        使用协调世界时(UTC)返回相对于1970年开始的UNIX纪元的时间，与用户空间的
> +        gettimeofday()相同。该函数用于所有需要在重启时持续存在的时间戳，比如
> +        inode时间，但应避免在内部使用，因为它可能由于闰秒更新和来自用户空间的NTP
> +        调整settimeofday()操作而向后跳转。
> +
> +.. c:function:: ktime_t ktime_get_clocktai( void )
> +
> +	 CLOCK_TAI
> +
> +        与ktime_get_real()类似，但使用国际原子时(TAI)作为参考而不是UTC，以避免在
> +        闰秒更新时跳转。这在内核中很少有用。
> +
> +.. c:function:: ktime_t ktime_get_raw( void )
> +
> +	CLOCK_MONOTONIC_RAW
> +
> +        与ktime_get()类似，但以与硬件时钟源相同的速率运行，无需针对时钟漂移进行调
> +        整(NTP)。这在内核中也很少需要。

没有针对时钟漂移进行的调整(NTP)。

> +
> +纳秒，timespec64和秒钟的输出
> +----------------------------
> +
> +对于上述所有情况，以下函数变体会根据用户的要求以不同的格式返回时间：
> +
> +.. c:function:: u64 ktime_get_ns( void )
> +		u64 ktime_get_boottime_ns( void )
> +		u64 ktime_get_real_ns( void )
> +		u64 ktime_get_clocktai_ns( void )
> +		u64 ktime_get_raw_ns( void )
> +
> +        与普通的ktime_get函数相同，但返回各自时钟参考中的u64纳秒数，这对某些调用
> +        者来说可能更方便。
> +
> +.. c:function:: void ktime_get_ts64( struct timespec64 * )
> +		void ktime_get_boottime_ts64( struct timespec64 * )
> +		void ktime_get_real_ts64( struct timespec64 * )
> +		void ktime_get_clocktai_ts64( struct timespec64 * )
> +		void ktime_get_raw_ts64( struct timespec64 * )
> +
> +        同上，但返回的是'struct timespec64'中的时间，分为秒和纳秒。这可以避免在打
> +        印时间时，或在将其传递到期望有'timespec'或'timeval'结构的外部接口时，进行

结构 -> 结构体

Thanks,
	Wu

Re: [PATCH 2/3] docs/zh_CN: core-api: Add timekeeping Chinese translation

[Binbin Zhou]

Hi XiangCheng:

On Tue, Oct 18, 2022 at 12:38 AM Wu XiangCheng <wu.xiangcheng@linux.dev> wrote:
>
> > Translate core-api/timekeeping.rst into Chinese.
> >
> > Last English version used:
> >
> > commit 3dc6ffae2da2 ("timekeeping: Introduce fast accessor to clock tai").
> >
> > Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
> > ---
> >  .../translations/zh_CN/core-api/index.rst     |   2 +-
> >  .../zh_CN/core-api/timekeeping.rst            | 172 ++++++++++++++++++
> >  2 files changed, 173 insertions(+), 1 deletion(-)
> >  create mode 100644 Documentation/translations/zh_CN/core-api/timekeeping.rst
> >
> > diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> > index 21d0b25bc580..d08091036066 100644
> > --- a/Documentation/translations/zh_CN/core-api/index.rst
> > +++ b/Documentation/translations/zh_CN/core-api/index.rst
> > @@ -49,12 +49,12 @@
> >     generic-radix-tree
> >     packing
> >     this_cpu_ops
> > +   timekeeping
> >
> >  Todolist:
> >
> >
> >
> > -   timekeeping
> >     errseq
> >
> >  并发原语
> > diff --git a/Documentation/translations/zh_CN/core-api/timekeeping.rst b/Documentation/translations/zh_CN/core-api/timekeeping.rst
> > new file mode 100644
> > index 000000000000..e7f9adf2525c
> > --- /dev/null
> > +++ b/Documentation/translations/zh_CN/core-api/timekeeping.rst
> > @@ -0,0 +1,172 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> > +.. include:: ../disclaimer-zh_CN.rst
> > +
> > +:Original: Documentation/core-api/timekeeping.rst
> > +
> > +:翻译:
> > +
> > + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
> > +
> > +ktime访问器
> > +===========
> > +
> > +设备驱动程序可以使用ktime_get()和linux/timekeeping.h中声明的许多相关函数读取当前
> > +时间。根据经验，如果两者都同样适合特定用例，则使用名称较短的访问器优于名称较长的
> > +访问器。
>
> 如果两个访问器都适用于某一用例，则使用名称较短的那个。
Ok....
>
> > +
> > +基于ktime_t的基础接口
> > +---------------------
> > +
> > +推荐的最简单形式返回不透明的ktime_t，其变体返回不同时钟参考的时间：
> > +
> > +.. c:function:: ktime_t ktime_get( void )
> > +
> > +     CLOCK_MONOTONIC
>  ^
>  tab
>
> > +
> > +        对可靠的时间戳和准确测量短的时间间隔很有用。在系统启动时启动，但在挂起时
> > +        停止。
>  ^^^^^^^^
>  spaces
>  check all of them

I will check all of them and replace spaces with tabs.
>
> > +
> > +.. c:function:: ktime_t ktime_get_boottime( void )
> > +
> > +     CLOCK_BOOTTIME
> > +
> > +        与ktime_get()类似，但在挂起时不会停止。这可以用于例如需要在挂起操作中与其
> > +        他计算机同步的密钥过期时间。
> > +
> > +.. c:function:: ktime_t ktime_get_real( void )
> > +
> > +     CLOCK_REALTIME
> > +
> > +        使用协调世界时(UTC)返回相对于1970年开始的UNIX纪元的时间，与用户空间的
> > +        gettimeofday()相同。该函数用于所有需要在重启时持续存在的时间戳，比如
> > +        inode时间，但应避免在内部使用，因为它可能由于闰秒更新和来自用户空间的NTP
> > +        调整settimeofday()操作而向后跳转。
> > +
> > +.. c:function:: ktime_t ktime_get_clocktai( void )
> > +
> > +      CLOCK_TAI
> > +
> > +        与ktime_get_real()类似，但使用国际原子时(TAI)作为参考而不是UTC，以避免在
> > +        闰秒更新时跳转。这在内核中很少有用。
> > +
> > +.. c:function:: ktime_t ktime_get_raw( void )
> > +
> > +     CLOCK_MONOTONIC_RAW
> > +
> > +        与ktime_get()类似，但以与硬件时钟源相同的速率运行，无需针对时钟漂移进行调
> > +        整(NTP)。这在内核中也很少需要。
>
> 没有针对时钟漂移进行的调整(NTP)。

OK....
>
> > +
> > +纳秒，timespec64和秒钟的输出
> > +----------------------------
> > +
> > +对于上述所有情况，以下函数变体会根据用户的要求以不同的格式返回时间：
> > +
> > +.. c:function:: u64 ktime_get_ns( void )
> > +             u64 ktime_get_boottime_ns( void )
> > +             u64 ktime_get_real_ns( void )
> > +             u64 ktime_get_clocktai_ns( void )
> > +             u64 ktime_get_raw_ns( void )
> > +
> > +        与普通的ktime_get函数相同，但返回各自时钟参考中的u64纳秒数，这对某些调用
> > +        者来说可能更方便。
> > +
> > +.. c:function:: void ktime_get_ts64( struct timespec64 * )
> > +             void ktime_get_boottime_ts64( struct timespec64 * )
> > +             void ktime_get_real_ts64( struct timespec64 * )
> > +             void ktime_get_clocktai_ts64( struct timespec64 * )
> > +             void ktime_get_raw_ts64( struct timespec64 * )
> > +
> > +        同上，但返回的是'struct timespec64'中的时间，分为秒和纳秒。这可以避免在打
> > +        印时间时，或在将其传递到期望有'timespec'或'timeval'结构的外部接口时，进行
>
> 结构 -> 结构体
OK...

Thanks for your review.

Binbin
>
> Thanks,
>         Wu

[PATCH 3/3] docs/zh_CN: core-api: Add errseq Chinese translation

[Binbin Zhou]

Translate core-api/errseq.rst into Chinese.

Last English version used:

commit 14ebc28e07e6 ("errseq: Add to documentation tree").

Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
---
 .../translations/zh_CN/core-api/errseq.rst    | 141 ++++++++++++++++++
 .../translations/zh_CN/core-api/index.rst     |   5 -
 2 files changed, 141 insertions(+), 5 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/core-api/errseq.rst

diff --git a/Documentation/translations/zh_CN/core-api/errseq.rst b/Documentation/translations/zh_CN/core-api/errseq.rst
new file mode 100644
index 000000000000..1f8d3aef4bbf
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/errseq.rst
@@ -0,0 +1,141 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/errseq.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+================
+errseq_t数据类型
+================
+
+errseq_t是一种在一个地方记录错误的方法，并允许任意数量的“订阅者”判断自上次采样点
+以来是否发生了变化。
+
+最初的用例是跟踪文件同步系统调用（fsync, fdatasync, msync和sync_file_range）的错
+误，但它也可以用于其他情况。
+
+它被实现为一个无符号的32位值。低位被指定保存错误代码（在1和MAX_ERRNO之间）。高位
+用作计数器。这里是用原子操作而不是锁来完成的，因此可以从任何上下文中调用这些函数。
+
+请注意，如果频繁记录新错误，则存在冲突风险，因为我们用作计数器的位很少。
+
+为了缓解这种情况，错误值和计数器之间的位被用作一个标志，以判断自记录新值以来是否
+对该值进行了采样。这使我们能够避免在上次记录错误后没有人取样的情况下碰撞计数器。
+
+因此，我们得到了一个类似这样的值：
+
++--------------------------------------+------+------------------------+
+| 31..13                               |  12  | 11..0                  |
++--------------------------------------+------+------------------------+
+| 计数器                               | 标志 | 错误值                 |
++--------------------------------------+------+------------------------+
+
+总体思路是让“观察者”对errseq_t值进行采样，并将其保留为运行游标。该值稍后可用于判
+断自采样完成后是否发生了任何新错误，并原子地记录检查时的状态。这使得我们能在一个
+地方记录错误，然后有许多“观察者”可以判断自上次检查以来该值是否发生了变化。
+
+新的errseq_t应始终清零。全零的errseq_t值是从未出现错误的特殊（但常见）情况。因此，
+如果您希望知道自首次初始化以来是否曾经有过错误集，则全零值被用作“纪元”。
+
+API的使用方法
+=============
+
+让我给你们讲一个关于员工drone的故事。现在，他总体上是个好员工，但公司有点...管理
+繁重。他今天必须向77名主管汇报，明天“大老板”要从外地赶来，他肯定也会考验这个可怜
+的家伙。
+
+他们都把工作交给他去做---多到他都记不住谁交给他什么了，但这并不是什么大问题。主管
+们只想知道他什么时候完成他们迄今为止交给他的所有工作，以及自从他们上次询问以来他
+是否犯了任何错误。
+
+他可能在他们实际上并没有交给他的工作上犯了错误，但他无法在那么详细的层面上记录事
+情，他所能记得的只是他最近犯的错误。
+
+下面是我们worker_drone的表达式::
+
+        struct worker_drone {
+                errseq_t        wd_err; /* 用来记录错误 */
+        };
+
+每天，worker_drone都是以一张白纸开始的::
+
+        struct worker_drone wd;
+
+        wd.wd_err = (errseq_t)0;
+
+主管们进来后对当天的工作进行初步了解。他们并不关心在他们观察开始之前发生的任何事
+情::
+
+        struct supervisor {
+                errseq_t        s_wd_err; /* wd_err的私有“游标” */
+                spinlock_t      s_wd_err_lock; /* 保护s_wd_err */
+        }
+
+        struct supervisor       su;
+
+        su.s_wd_err = errseq_sample(&wd.wd_err);
+        spin_lock_init(&su.s_wd_err_lock);
+
+现在他们开始给他布置任务。每隔几分钟，他们就要求他完成迄今为止交给他的所有工作。
+然后问他是否有犯任何错误::
+
+        spin_lock(&su.su_wd_err_lock);
+        err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err);
+        spin_unlock(&su.su_wd_err_lock);
+
+到目前为止，它只是不断返回0。
+
+现在，这家公司的老板非常吝啬，给了他不合格的设备来完成他的工作。偶尔设备会出现故
+障，导致他犯错。他重重地叹了一口气，并把它记录下来::
+
+        errseq_set(&wd.wd_err, -EIO);
+
+...然后继续工作。主管们最终会再次检查，他们在下次检查时都会发现这个错误。后续的调
+用将返回0，直到记录下另一个错误，此时将向每个调用报告一次。
+
+请注意，主管们无法知道他们犯了多少错误，只能知道自上次检查以来是否犯了一个错误，
+以及记录的最新值。
+
+偶尔，大老板会来抽查，要求员工为他做一次性的工作。他并不像主管们那样全职观察员工，
+但他确实需要知道在他的工作处理过程中是否发生了错误。
+
+他只需对员工当前的errseq_t进行采样，然后用它来判断后来是否发生了错误::
+
+        errseq_t since = errseq_sample(&wd.wd_err);
+        /* 提交一些工作，等待完成 */
+        err = errseq_check(&wd.wd_err, since);
+
+由于他只是要在那个点之后丢弃“since”，所以他不需要在这里推进它。同时他也不需要任何
+锁，因为它不能被其他人使用。
+
+序列化更新errseq_t游标
+======================
+
+请注意，errseq_t API在check_and_advance_operation期间不保护errseq_t游标。只有典型
+的错误代码是被原子化处理的。在多任务同时使用同一个errseq_t游标的情况下，对该游标
+的更新进行序列化是很重要的。
+
+如果不这样做，那么游标就有可能向后移动。在这种情况下，同一个错误可能被报告多次。
+
+因此，通常先执行errseq_check检查是否有任何变化，然后在获取锁后才执行
+errseq_check_and_advance。例如::
+
+        if (errseq_check(&wd.wd_err, READ_ONCE(su.s_wd_err)) {
+                /* su.s_wd_err被s_wd_err_lock保护 */
+                spin_lock(&su.s_wd_err_lock);
+                err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err);
+                spin_unlock(&su.s_wd_err_lock);
+        }
+
+这就避免了自上次检查以来没有任何变化的常见情况下的自旋锁。
+
+函数
+====
+
+该API在以下内核代码中:
+
+lib/errseq.c
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index d08091036066..8b19c6ae9704 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -50,11 +50,6 @@
    packing
    this_cpu_ops
    timekeeping
-
-Todolist:
-
-
-
    errseq
 
 并发原语
-- 
2.31.1

Re: [PATCH 3/3] docs/zh_CN: core-api: Add errseq Chinese translation

[Wu XiangCheng]

> Translate core-api/errseq.rst into Chinese.
> 
> Last English version used:
> 
> commit 14ebc28e07e6 ("errseq: Add to documentation tree").
> 
> Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>

Reviewed-by: Wu XiangCheng <bobwxc@email.cn>

Thanks

> ---
>  .../translations/zh_CN/core-api/errseq.rst    | 141 ++++++++++++++++++
>  .../translations/zh_CN/core-api/index.rst     |   5 -
>  2 files changed, 141 insertions(+), 5 deletions(-)
>  create mode 100644 Documentation/translations/zh_CN/core-api/errseq.rst