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

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

[Binbin Zhou]

Hi all:

Sorry, it may have been a while since the V2 patchset. Thanks to Alex
for his comments.

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 section "Data structures and low-level utilities" of
the core-api has been translated completely.

Thanks.

Changes since V2:
- Take Alex's advices, thanks.

Details: 
https://lore.kernel.org/all/CAJy-Am=mtZxQv2AgH+PxVLsJ8FeW1NRQV2bkLD1RRLGQLxUPgQ@mail.gmail.com/

Changes since V1:
- Take Xiangcheng's advices, thanks.

Details: 
https://lore.kernel.org/all/Y0wsWoI+BXXCuRbF@bobwxc.mipc/
https://lore.kernel.org/all/Y02EcgD3E0%2FlML5H@bobwxc.mipc/

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    | 145 +++++++++
 .../translations/zh_CN/core-api/index.rst     |   5 -
 .../zh_CN/core-api/this_cpu_ops.rst           | 285 ++++++++++++++++++
 .../zh_CN/core-api/timekeeping.rst            | 177 +++++++++++
 4 files changed, 607 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 V3 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>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
---
 .../translations/zh_CN/core-api/index.rst     |   2 +-
 .../zh_CN/core-api/this_cpu_ops.rst           | 285 ++++++++++++++++++
 2 files changed, 286 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..bea5ee8eb8a0
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/this_cpu_ops.rst
@@ -0,0 +1,286 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/this_cpu_ops.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+:校译:
+
+ 吴想成 Wu Xiangcheng <bobwxc@email.cn>
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+
+============
+this_cpu操作
+============
+
+:作者: Christoph Lameter, 2014年8月4日
+:作者: Pranith Kumar, 2014年8月2日
+
+this_cpu操作是一种优化访问与当前执行处理器相关的每CPU变量的方法。这是通过使用段寄
+存器（或专用寄存器，cpu在其中永久存储特定处理器的每CPU区域的起始）来完成的。
+
+this_cpu操作将每CPU变量的偏移量添加到处理器特定的每CPU基址上，并将该操作编码到对
+每CPU变量进行操作的指令中。
+
+这意味着在偏移量的计算和对数据的操作之间不存在原子性问题。因此，没有必要禁用抢占
+或中断来确保处理器在计算地址和数据操作之间不被改变。
+
+读取-修改-写入操作特别值得关注。通常处理器具有特殊的低延迟指令，可以在没有典型同
+步开销的情况下运行，但仍提供某种宽松的原子性保证。例如，x86可以执行RMW（读取，
+修改，写入）指令，如同inc/dec/cmpxchg，而无需锁前缀和相关的延迟损失。
+
+对没有锁前缀的变量的访问是不同步的，也不需要同步，因为我们处理的是当前执行的处理
+器所特有的每CPU数据。只有当前的处理器可以访问该变量，因此系统中的其他处理器不存在
+并发性问题。
+
+请注意，远程处理器对每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:段寄存器包含每CPU区域的基址。这样就可以简单地使用段覆盖，将每CPU
+相对地址重定位到处理器适当的每CPU区域。所以对每CPU基址的重定位是通过段寄存器前缀
+在指令中编码完成的。
+
+例如::
+
+	DEFINE_PER_CPU(int, x);
+	int z;
+
+	z = this_cpu_read(x);
+
+产生的单指令为::
+
+	mov ax, gs:[x]
+
+而不是像每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();
+
+请注意，这些操作只能用于为特定处理器保留的每CPU数据。如果不在上下文代码中禁用抢占，
+``this_cpu_inc()`` 将仅保证每CPU的某一个计数器被正确地递增，但不能保证操作系统不
+会在this_cpu指令执行的前后直接移动该进程。一般来说，这意味着每个处理器的单个计数
+器的值是没有意义的。所有每CPU计数器的总和才是唯一有意义的值。
+
+每CPU变量的使用是出于性能的考虑。如果多个处理器同时处理相同的代码路径，可以避免缓
+存行跳转。每个处理器都有自己的每CPU变量，因此不会发生并发缓存行更新。为这种优化必
+须付出的代价是，当需要计数器的值时要将每CPU计数器相加。
+
+
+特殊的操作
+----------
+
+::
+
+	y = this_cpu_ptr(&x)
+
+使用每CPU变量的偏移量(&x!)，并返回属于当前执行处理器的每CPU变量的地址。
+``this_cpu_ptr`` 避免了通用 ``get_cpu``/``put_cpu`` 序列所需的多个步骤。没有可用
+的处理器编号。相反，本地每CPU区域的偏移量只是简单地添加到每CPU偏移量上。
+
+请注意，这个操作通常是在抢占被禁用后再在代码段中使用。然后该指针用来访问临界区中
+的本地每CPU数据。当重新启用抢占时，此指针通常不再有用，因为它可能不再指向当前处理
+器的每CPU数据。
+
+每CPU变量和偏移量
+-----------------
+
+每CPU变量相对于每CPU区域的起始点是有偏移的。它们没有地址，尽管代码里看起来像有一
+样。不能直接对偏移量解引用，必须用处理器每CPU区域基指针加上偏移量，以构成有效地址。
+
+因此，在每CPU操作的上下文之外使用x或&x是无效的，这种行为通常会被当作一个空指针的
+解引用来处理。
+
+::
+
+	DEFINE_PER_CPU(int, x);
+
+在每CPU操作的上下文中，上面表达式说明x是一个每CPU变量。大多数this_cpu操作都需要一
+个cpu变量。
+
+::
+
+	int __percpu *p = &x;
+
+&x和p是每CPU变量的偏移量。 ``this_cpu_ptr()`` 使用每CPU变量的偏移量，这让它看起来
+有点奇怪。
+
+
+每CPU结构体字段的操作
+---------------------
+
+假设我们有一个每CPU结构::
+
+	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的操作是中断安全的。一些架构不支持这些每CPU的本地操作。在这种情况下，该操
+作必须被禁用中断的代码所取代，然后做那些保证是原子的操作，再重新启用中断。当然这
+样做是很昂贵的。如果有其他原因导致调度器不能改变我们正在执行的处理器，那么就没有
+理由禁用中断了。为此，我们提供了以下__this_cpu操作。
+
+这些操作不能保证并发中断或抢占。如果在中断上下文中不使用每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()`` 和大家的使用方式一致。
+
+
+远程访问每CPU数据
+-----------------
+
+每CPU数据结构被设计为由一个CPU独占使用。如果您按预期使用变量，则 ``this_cpu_ops()``
+保证是 ``原子的`` ，因为没有其他CPU可以访问这些数据结构。
+
+在某些特殊情况下，您可能需要远程访问每CPU数据结构。通常情况下，进行远程读访问是安
+全的，这经常是为了统计计数器值。远程写访问可能会出现问题，因为this_cpu操作没有锁
+语义。远程写可能会干扰this_cpu RMW操作。
+
+除非绝对必要，否则强烈建议不要对每CPU数据结构进行远程写访问。请考虑使用IPI来唤醒
+远程CPU，并对其每CPU区域进行更新。
+
+要远程访问每CPU数据结构，通常使用 ``per_cpu_ptr()`` 函数::
+
+
+	DEFINE_PER_CPU(struct data, datap);
+
+	struct data *p = per_cpu_ptr(&datap, cpu);
+
+这清楚地表明，我们正准备远程访问每CPU区域。
+
+您还可以执行以下操作以将datap偏移量转换为地址::
+
+	struct data *p = this_cpu_ptr(&datap);
+
+但是，将通过this_cpu_ptr计算的指针传递给其他cpu是不寻常的，应该避免。
+
+远程访问通常只用于读取另一个cpu的每CPU数据状态。由于this_cpu操作宽松的同步要求，
+写访问可能会导致奇特的问题。
+
+下面的情况说明了写入操作的一些问题，由于两个每CPU变量共享一个缓存行，但宽松的同步
+仅应用于更新缓存行的一个进程。
+
+考虑以下示例::
+
+
+	struct test {
+		atomic_t a;
+		int b;
+	};
+
+	DEFINE_PER_CPU(struct test, onecacheline);
+
+如果一个处理器远程更新字段 ``a`` ，而本地处理器将使用this_cpu ops来更新字段 ``b`` ，
+会发生什么情况，这一点值得注意。应避免在同一缓存行内同时访问数据。此外，可能还需
+要进行代价高昂的同步。在这种情况下，通常建议使用IPI，而不是远程写入另一个处理器的
+每CPU区域。
+
+即使在远程写很少的情况下，请记住远程写将从最有可能访问它的处理器中逐出缓存行。如
+果处理器唤醒时发现每CPU区域缺少本地缓存行，其性能和唤醒时间将受到影响。
-- 
2.31.1

[PATCH V3 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>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
---
 .../translations/zh_CN/core-api/index.rst     |   2 +-
 .../zh_CN/core-api/timekeeping.rst            | 177 ++++++++++++++++++
 2 files changed, 178 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..9af04a1d5e39
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/timekeeping.rst
@@ -0,0 +1,178 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/timekeeping.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+:校译:
+
+ 吴想成 Wu Xiangcheng <bobwxc@email.cn>
+ 司延腾 Yanteng Si <siyanteng@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

[PATCH V3 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>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
---
 .../translations/zh_CN/core-api/errseq.rst    | 145 ++++++++++++++++++
 .../translations/zh_CN/core-api/index.rst     |   5 -
 2 files changed, 145 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..8fdc8eab46c0
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/errseq.rst
@@ -0,0 +1,147 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/errseq.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+:校译:
+
+ 吴想成 Wu Xiangcheng <bobwxc@email.cn>
+ 司延腾 Yanteng Si <siyanteng@loongson.cn>
+ 时奎亮 Alex Shi <alexs@kernel.org>
+
+================
+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`` 变量（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 V3 0/3] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 2)

[Wu XiangCheng]

[-- Attachment #1: Type: text/plain, Size: 2088 bytes --]

2022-11-06 (日) 14:57:47 +0800 Binbin Zhou 曰：
> Hi all:
> 
> Sorry, it may have been a while since the V2 patchset. Thanks to Alex
> for his comments.
> 
> 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 section "Data structures and low-level utilities" of
> the core-api has been translated completely.
> 
> Thanks.
> 
> Changes since V2:
> - Take Alex's advices, thanks.
> 
> Details: 
> https://lore.kernel.org/all/CAJy-Am=mtZxQv2AgH+PxVLsJ8FeW1NRQV2bkLD1RRLGQLxUPgQ@mail.gmail.com/
> 
> Changes since V1:
> - Take Xiangcheng's advices, thanks.
> 
> Details: 
> https://lore.kernel.org/all/Y0wsWoI+BXXCuRbF@bobwxc.mipc/
> https://lore.kernel.org/all/Y02EcgD3E0%2FlML5H@bobwxc.mipc/
> 
> 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

v2 has been merged into jc/docs-next, see:

commit 4cbf848f07d85170bb78040e50762673ab799693
commit d24c911bd031a299de39863f67ae7290d450d56e
commit 797e75617b98e4c50d98372787427716cb532761

Please rebase on newest docs-next if any further modification.

Thanks,

> 
>  .../translations/zh_CN/core-api/errseq.rst    | 145 +++++++++
>  .../translations/zh_CN/core-api/index.rst     |   5 -
>  .../zh_CN/core-api/this_cpu_ops.rst           | 285 ++++++++++++++++++
>  .../zh_CN/core-api/timekeeping.rst            | 177 +++++++++++
>  4 files changed, 607 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
> 

-- 
Wu XiangCheng	0x32684A40BCA7AEA7


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

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

[Jonathan Corbet]

Binbin Zhou <zhoubinbin@loongson.cn> writes:

> Hi all:
>
> Sorry, it may have been a while since the V2 patchset. Thanks to Alex
> for his comments.
>
> 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 section "Data structures and low-level utilities" of
> the core-api has been translated completely.
>
> Thanks.
>
> Changes since V2:
> - Take Alex's advices, thanks.
>
> Details: 
> https://lore.kernel.org/all/CAJy-Am=mtZxQv2AgH+PxVLsJ8FeW1NRQV2bkLD1RRLGQLxUPgQ@mail.gmail.com/
>
> Changes since V1:
> - Take Xiangcheng's advices, thanks.
>
> Details: 
> https://lore.kernel.org/all/Y0wsWoI+BXXCuRbF@bobwxc.mipc/
> https://lore.kernel.org/all/Y02EcgD3E0%2FlML5H@bobwxc.mipc/
>
> 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    | 145 +++++++++
>  .../translations/zh_CN/core-api/index.rst     |   5 -
>  .../zh_CN/core-api/this_cpu_ops.rst           | 285 ++++++++++++++++++
>  .../zh_CN/core-api/timekeeping.rst            | 177 +++++++++++
>  4 files changed, 607 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

Applied, thanks.

jon

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

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> Binbin Zhou <zhoubinbin@loongson.cn> writes:
>
>> Hi all:
>>
>> Sorry, it may have been a while since the V2 patchset. Thanks to Alex
>> for his comments.
>>
>> 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 section "Data structures and low-level utilities" of
>> the core-api has been translated completely.
>>
>> Thanks.
>>
>> Changes since V2:
>> - Take Alex's advices, thanks.
>>
>> Details: 
>> https://lore.kernel.org/all/CAJy-Am=mtZxQv2AgH+PxVLsJ8FeW1NRQV2bkLD1RRLGQLxUPgQ@mail.gmail.com/
>>
>> Changes since V1:
>> - Take Xiangcheng's advices, thanks.
>>
>> Details: 
>> https://lore.kernel.org/all/Y0wsWoI+BXXCuRbF@bobwxc.mipc/
>> https://lore.kernel.org/all/Y02EcgD3E0%2FlML5H@bobwxc.mipc/
>>
>> 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    | 145 +++++++++
>>  .../translations/zh_CN/core-api/index.rst     |   5 -
>>  .../zh_CN/core-api/this_cpu_ops.rst           | 285 ++++++++++++++++++
>>  .../zh_CN/core-api/timekeeping.rst            | 177 +++++++++++
>>  4 files changed, 607 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
>
> Applied, thanks.

Actually, I take that back.  I applied these at the end of October, why
are you sending different versions now?

Thanks,

jon

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

[Binbin Zhou]

在 2022/11/10 04:43, Jonathan Corbet 写道:
> Jonathan Corbet <corbet@lwn.net> writes:
> 
>> Binbin Zhou <zhoubinbin@loongson.cn> writes:
>>
>>> Hi all:
>>>
>>> Sorry, it may have been a while since the V2 patchset. Thanks to Alex
>>> for his comments.
>>>
>>> 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 section "Data structures and low-level utilities" of
>>> the core-api has been translated completely.
>>>
>>> Thanks.
>>>
>>> Changes since V2:
>>> - Take Alex's advices, thanks.
>>>
>>> Details:
>>> https://lore.kernel.org/all/CAJy-Am=mtZxQv2AgH+PxVLsJ8FeW1NRQV2bkLD1RRLGQLxUPgQ@mail.gmail.com/
>>>
>>> Changes since V1:
>>> - Take Xiangcheng's advices, thanks.
>>>
>>> Details:
>>> https://lore.kernel.org/all/Y0wsWoI+BXXCuRbF@bobwxc.mipc/
>>> https://lore.kernel.org/all/Y02EcgD3E0%2FlML5H@bobwxc.mipc/
>>>
>>> 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    | 145 +++++++++
>>>   .../translations/zh_CN/core-api/index.rst     |   5 -
>>>   .../zh_CN/core-api/this_cpu_ops.rst           | 285 ++++++++++++++++++
>>>   .../zh_CN/core-api/timekeeping.rst            | 177 +++++++++++
>>>   4 files changed, 607 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
>>
>> Applied, thanks.
> 
> Actually, I take that back.  I applied these at the end of October, why
> are you sending different versions now?
> 
> Thanks,
> 
> jon

Hi jon:

Sorry, this is my mistake.

I didn't pull the latest docs-next before I sent the v3 patchset.

I didn't notice your apply email for the v2 patchset before, and Alex 
had some different opinions about my v2 patchset, so I reorganized the 
v3 patchset.

Also, the v3 patchset has been delayed for some reason on my part.

In that case, please ignore the v3 patchset, the only differences 
between v2 and v3 are two translations:

https://lore.kernel.org/all/CAJy-Am=mtZxQv2AgH+PxVLsJ8FeW1NRQV2bkLD1RRLGQLxUPgQ@mail.gmail.com/

I will try another fix patch later.

Sorry again, I'll pay more attention next time.

Thanks.

Binbin