Skip to contentSkip to conversation

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

PATCH Applied Binbin Zhou 5 participants 15 messages Oct 19, 2022 – Oct 28, 2022

Subsystems (2)

v2 of 3 Applied Latest is v3 →

lore
Share & tools
lore
#0 lore raw

v2 cover docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 2)

Hi all:

As a continuation of the previous patchset
(https://lore.kernel.org/all/[email protected]/),
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 V1:
- Take Xiangcheng's advices, thanks.

Details:
https://lore.kernel.org/all/[email protected]/
https://lore.kernel.org/all/Y02EcgD3E0%[email protected]/

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
Signature · 1 line
2.31.1
#4 lore raw

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

Translate core-api/timekeeping.rst into Chinese.

Last English version used:

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

---
 .../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
Documentation/translations/zh_CN/core-api/index.rst +1 -1
index 21d0b25bc580..d08091036066 100644
@@ -49,12 +49,12 @@
    generic-radix-tree
    packing
    this_cpu_ops
+   timekeeping
 
 Todolist:
 
 
 
-   timekeeping
    errseq
 
 并发原语
Documentation/translations/zh_CN/core-api/timekeeping.rst new file +177 -0

177 lines not on this page · raw message

Signature · 1 line
2.31.1
Reviewed-by on v2 1/3
#2 lore raw

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

In reply to Binbin Zhou
Quoted 7 lines · 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").

Thanks,

Yanteng

Quoted 315 lines
---
  .../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

Documentation/translations/zh_CN/core-api/index.rst +1 -1
index 37756d240b5e..21d0b25bc580 100644
@@ -48,12 +48,12 @@
     circular-buffers
     generic-radix-tree
     packing
+   this_cpu_ops
 
  Todolist:
 
 
 
-   this_cpu_ops
     timekeeping
     errseq
 
Documentation/translations/zh_CN/core-api/this_cpu_ops.rst new file +285 -0
new file mode 100644
index 000000000000..bea5ee8eb8a0
@@ -0,0 +1,285 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/this_cpu_ops.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <[email protected]>
+
+:校译:
+
+ 吴想成 Wu Xiangcheng <[email protected]>
+
+============
+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区域缺少本地缓存行,其性能和唤醒时间将受到影响。
#6 lore raw
In reply to Binbin Zhou
Quoted 20 lines · Binbin Zhou

Hi all:

As a continuation of the previous patchset
(https://lore.kernel.org/all/[email protected]/),
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 V1:
- Take Xiangcheng's advices, thanks.

Quoted 8 lines

Details:
https://lore.kernel.org/all/[email protected]/
https://lore.kernel.org/all/Y02EcgD3E0%[email protected]/

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

Hi Binbin,

When I apply your patch set, git says:

git am ./v2_20221019_zhoubinbin_docs_zh_cn_core_api_add_some_translations_for_the_data_structures_section_par.mbx
Applying: docs/zh_CN: core-api: Add timekeeping Chinese translation
error: patch failed: Documentation/translations/zh_CN/core-api/index.rst:49
error: Documentation/translations/zh_CN/core-api/index.rst: patch does not apply
Patch failed at 0001 docs/zh_CN: core-api: Add timekeeping Chinese translation
hint: Use 'git am --show-current-patch=diff' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".

Thanks,

Yanteng

Quoted 10 lines
  .../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

#7 lore raw

Hi Yanteng:

Quoted 37 lines · Yanteng Si
Quoted 20 lines · Binbin Zhou

Hi all:

As a continuation of the previous patchset
(https://lore.kernel.org/all/[email protected]/),
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 V1:
- Take Xiangcheng's advices, thanks.

Quoted 8 lines

Details:
https://lore.kernel.org/all/[email protected]/
https://lore.kernel.org/all/Y02EcgD3E0%[email protected]/

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

Hi Binbin,

When I apply your patch set, git says:

Quoted 9 lines

git am ./v2_20221019_zhoubinbin_docs_zh_cn_core_api_add_some_translations_for_the_data_structures_section_par.mbx
Applying: docs/zh_CN: core-api: Add timekeeping Chinese translation
error: patch failed: Documentation/translations/zh_CN/core-api/index.rst:49
error: Documentation/translations/zh_CN/core-api/index.rst: patch does not apply
Patch failed at 0001 docs/zh_CN: core-api: Add timekeeping Chinese translation
hint: Use 'git am --show-current-patch=diff' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".

Sorry, the patch delivery was incomplete due to some reasons with my email. I will check and resend this series of patches.

Thanks.

Binbin

Quoted 16 lines

Thanks,

Yanteng

Quoted 10 lines

  .../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

#1 lore raw

PATCH RESEND v2 1/3 docs/zh_CN: core-api: Add this_cpu_ops Chinese translation

In reply to 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").

---
 .../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
Documentation/translations/zh_CN/core-api/index.rst +1 -1
index 37756d240b5e..21d0b25bc580 100644
@@ -48,12 +48,12 @@
    circular-buffers
    generic-radix-tree
    packing
+   this_cpu_ops
 
 Todolist:
 
 
 
-   this_cpu_ops
    timekeeping
    errseq
 
Documentation/translations/zh_CN/core-api/this_cpu_ops.rst new file +285 -0

285 lines not on this page · raw message

Signature · 1 line
2.31.1
#8 lore raw

PATCH RESEND v2 3/3 docs/zh_CN: core-api: Add errseq Chinese translation

In reply to Binbin Zhou

Translate core-api/errseq.rst into Chinese.

Last English version used:

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

---
 .../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
Documentation/translations/zh_CN/core-api/errseq.rst new file +145 -0
new file mode 100644
index 000000000000..815fb303ea2f
@@ -0,0 +1,145 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/errseq.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <[email protected]>
+
+:校译:
+
+ 吴想成 Wu Xiangcheng <[email protected]>
+
+================
+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
Documentation/translations/zh_CN/core-api/index.rst +0 -5
index d08091036066..8b19c6ae9704 100644
@@ -50,11 +50,6 @@
    packing
    this_cpu_ops
    timekeeping
-
-Todolist:
-
-
-
    errseq
 
 并发原语
Signature · 1 line
2.31.1
Reviewed-by on v2 1/3
#3 lore raw

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

In reply to Binbin Zhou

2022-10-21 (五) 09:58:07 +0800 Binbin Zhou 曰:

Quoted 7 lines

Translate core-api/this_cpu_ops.rst into Chinese.

Last English version used:

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

Quoted 5 lines
---
 .../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
Signature · 1 line
Wu XiangCheng	0x32684A40BCA7AEA7
Reviewed-by on v2 2/3
#5 lore raw

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

In reply to Binbin Zhou

2022-10-21 (五) 09:58:08 +0800 Binbin Zhou 曰:

Quoted 7 lines

Translate core-api/timekeeping.rst into Chinese.

Last English version used:

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

Short note for Jon:
Due to email system problem, this series looks a little messy. But I have tested it with b4, still works well.
$ b4 am [email protected] Got the three patches correctly.

Quoted 5 lines
---
 .../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
Signature · 1 line
Wu XiangCheng	0x32684A40BCA7AEA7
Reviewed-by on v2 3/3
#9 lore raw

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

In reply to Binbin Zhou
Quoted 8 lines · Binbin Zhou

Translate core-api/errseq.rst into Chinese.

Last English version used:

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

Thanks,

Yanteng

Quoted 173 lines
---
  .../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

Documentation/translations/zh_CN/core-api/errseq.rst new file +145 -0
new file mode 100644
index 000000000000..815fb303ea2f
@@ -0,0 +1,145 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/errseq.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <[email protected]>
+
+:校译:
+
+ 吴想成 Wu Xiangcheng <[email protected]>
+
+================
+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
Documentation/translations/zh_CN/core-api/index.rst +0 -5
index d08091036066..8b19c6ae9704 100644
@@ -50,11 +50,6 @@
     packing
     this_cpu_ops
     timekeeping
-
-Todolist:
-
-
-
     errseq
 
  并发原语
#10 lore raw

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

In reply to Binbin Zhou
Quoted 57 lines · Binbin Zhou

Translate core-api/errseq.rst into Chinese.

Last English version used:

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

---
 .../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
Documentation/translations/zh_CN/core-api/errseq.rst new file +36 -0
new file mode 100644
index 000000000000..815fb303ea2f
@@ -0,0 +1,145 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/errseq.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <[email protected]>
+
+:校译:
+
+ 吴想成 Wu Xiangcheng <[email protected]>
+
+================
+errseq_t数据类型
+================
+
+``errseq_t`` 是一种在一个地方记录错误的方法,并允许任意数量的 ``订阅者`` 判断自上
+次采样点以来是否发生了变化。
+
+最初的用例是跟踪文件同步系统调用( ``fsync``, ``fdatasync``, ``msync`` 和
+``sync_file_range`` )的错误,但它也可以用于其他情况。
+
+它被实现为一个无符号的32位值。低位被指定保存错误代码(在1和MAX_ERRNO之间)。高位
+用作计数器。这里是用原子操作而不是锁来完成的,因此可以从任何上下文中调用这些函数。
+
+请注意,如果频繁记录新错误,则存在冲突风险,因为我们用作计数器的位很少。
+
+为了缓解这种情况,错误值和计数器之间的位被用作一个标志,以判断自记录新值以来是否
+对该值进行了采样。这使我们能够避免在上次记录错误后没有人取样的情况下碰撞计数器。
+
+因此,我们得到了一个类似这样的值:
+
++--------------------------------------+------+------------------------+
+| 31..13                               |  12  | 11..0                  |

Documentation/translations/zh_CN/core-api/errseq.rst line 46

Quoted 10 lines
Documentation/translations/zh_CN/core-api/errseq.rst new file +10 -0
++--------------------------------------+------+------------------------+
+| 计数器                               | 标志 | 错误值                 |
++--------------------------------------+------+------------------------+
+
+总体思路是让 ``观察者`` 对errseq_t值进行采样,并将其保留为运行游标。该值稍后可用
+于判断自采样完成后是否发生了任何新错误,并原子地记录检查时的状态。这使得我们能在
+一个地方记录错误,然后有许多 ``观察者`` 可以判断自上次检查以来该值是否发生了变化。
+
+新的errseq_t应始终清零。全零的errseq_t值是从未出现错误的特殊(但常见)情况。因此,
+如果您希望知道自首次初始化以来是否曾经有过错误集,则全零值被用作 ``纪元`` 。

新纪元 会不会更好一些?

Quoted 61 lines
Documentation/translations/zh_CN/core-api/errseq.rst new file +61 -0
+
+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,直到记录下另一个错误,此时将向每个调用报告一次。
+
+请注意,主管们无法知道他们犯了多少错误,只能知道自上次检查以来是否犯了一个错误,
+以及记录的最新值。
+
+偶尔,大老板会来抽查,要求员工为他做一次性的工作。他并不像主管们那样全职观察员工,

Documentation/translations/zh_CN/core-api/errseq.rst line 117

Quoted 10 lines
Documentation/translations/zh_CN/core-api/errseq.rst new file +10 -0
+但他确实需要知道在他的工作处理过程中是否发生了错误。
+
+他只需对员工当前的errseq_t进行采样,然后用它来判断后来是否发生了错误::
+
+        errseq_t since = errseq_sample(&wd.wd_err);
+        /* 提交一些工作,等待完成 */
+        err = errseq_check(&wd.wd_err, since);
+
+由于他只是要在那个点之后丢弃 ``since`` ,所以他不需要在这里推进它。同时他也不需要
+任何锁,因为它不能被其他人使用。

Honstly, I don't understand the meaning of this words. :/

For other LGTM.

Thanks
Alex

Quoted 47 lines
Documentation/translations/zh_CN/core-api/errseq.rst new file +28 -0
+
+序列化更新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
Documentation/translations/zh_CN/core-api/index.rst +0 -6
index d08091036066..8b19c6ae9704 100644
@@ -50,11 +50,6 @@
    packing
    this_cpu_ops
    timekeeping
-
-Todolist:
-
-
-
    errseq
 
 并发原语
--

2.31.1

#11 lore raw

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

Hi Alex:

Sorry for late reply.

Quoted 62 lines · Alex Shi
Quoted 61 lines · Binbin Zhou

Translate core-api/errseq.rst into Chinese.

Last English version used:

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

---
  .../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

Documentation/translations/zh_CN/core-api/errseq.rst new file +40 -0
new file mode 100644
index 000000000000..815fb303ea2f
@@ -0,0 +1,145 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/errseq.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <[email protected]>
+
+:校译:
+
+ 吴想成 Wu Xiangcheng <[email protected]>
+
+================
+errseq_t数据类型
+================
+
+``errseq_t`` 是一种在一个地方记录错误的方法,并允许任意数量的 ``订阅者`` 判断自上
+次采样点以来是否发生了变化。
+
+最初的用例是跟踪文件同步系统调用( ``fsync``, ``fdatasync``, ``msync`` 和
+``sync_file_range`` )的错误,但它也可以用于其他情况。
+
+它被实现为一个无符号的32位值。低位被指定保存错误代码(在1和MAX_ERRNO之间)。高位
+用作计数器。这里是用原子操作而不是锁来完成的,因此可以从任何上下文中调用这些函数。
+
+请注意,如果频繁记录新错误,则存在冲突风险,因为我们用作计数器的位很少。
+
+为了缓解这种情况,错误值和计数器之间的位被用作一个标志,以判断自记录新值以来是否
+对该值进行了采样。这使我们能够避免在上次记录错误后没有人取样的情况下碰撞计数器。
+
+因此,我们得到了一个类似这样的值:
+
++--------------------------------------+------+------------------------+
+| 31..13                               |  12  | 11..0                  |
++--------------------------------------+------+------------------------+
+| 计数器                               | 标志 | 错误值                 |
++--------------------------------------+------+------------------------+
+
Quoted 8 lines

Documentation/translations/zh_CN/core-api/errseq.rst line 46

Quoted 6 lines
Documentation/translations/zh_CN/core-api/errseq.rst new file +6 -0
+总体思路是让 ``观察者`` 对errseq_t值进行采样,并将其保留为运行游标。该值稍后可用
+于判断自采样完成后是否发生了任何新错误,并原子地记录检查时的状态。这使得我们能在
+一个地方记录错误,然后有许多 ``观察者`` 可以判断自上次检查以来该值是否发生了变化。
+
+新的errseq_t应始终清零。全零的errseq_t值是从未出现错误的特殊(但常见)情况。因此,
+如果您希望知道自首次初始化以来是否曾经有过错误集,则全零值被用作 ``纪元`` 。

新纪元 会不会更好一些?

OK, I get it.

Quoted 66 lines
Quoted 66 lines
Documentation/translations/zh_CN/core-api/errseq.rst new file +65 -0
+
+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进行采样,然后用它来判断后来是否发生了错误::
+
Quoted 8 lines

Documentation/translations/zh_CN/core-api/errseq.rst line 117

Quoted 6 lines
Documentation/translations/zh_CN/core-api/errseq.rst new file +6 -0
+        errseq_t since = errseq_sample(&wd.wd_err);
+        /* 提交一些工作,等待完成 */
+        err = errseq_check(&wd.wd_err, since);
+
+由于他只是要在那个点之后丢弃 ``since`` ,所以他不需要在这里推进它。同时他也不需要
+任何锁,因为它不能被其他人使用。

Honstly, I don't understand the meaning of this words. :/

According to the specific implementation of the function, what we want to track is the error after the sampling point ``since`` , so the ``since`` variable is only used for comparison and will be discarded later.

How about:
由于他只是在采样点后丢弃 ``since`` 变量,所以不需要在这里保存更新它。

Thanks
Binbin

Quoted 53 lines

For other LGTM.

Thanks
Alex

Quoted 47 lines
Documentation/translations/zh_CN/core-api/errseq.rst new file +28 -0
+
+序列化更新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
Documentation/translations/zh_CN/core-api/index.rst +0 -6
index d08091036066..8b19c6ae9704 100644
@@ -50,11 +50,6 @@
     packing
     this_cpu_ops
     timekeeping
-
-Todolist:
-
-
-
     errseq
 
  并发原语
--

2.31.1

#12 lore raw

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

Quoted 9 lines · Binbin Zhou
Quoted 1 line

Honstly, I don't understand the meaning of this words. :/

According to the specific implementation of the function, what we want to track is the error after the sampling point ``since`` , so the ``since`` variable is only used for comparison and will be discarded later.

How about:
由于他只是在采样点后丢弃 ``since`` 变量,所以不需要在这里保存更新它。

Get it. if so, could we give a bit more info? like:
由于他只是在采样点后丢弃 ``since`` 变量(since 既是采样点),所以不需要在这里保存更新它。

Thanks
Alex

author
#13 lore raw

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

Quoted 19 lines

-----原始邮件-----
发件人: "Alex Shi" <[email protected]>
发送时间:2022-10-24 16:37:00 (星期一)
收件人: "Binbin Zhou" <[email protected]>
抄送: "Jonathan Corbet" <[email protected]>, "Alex Shi" <[email protected]>, "Yanteng Si" <[email protected]>, "Wu XiangCheng" <[email protected]>, "Huacai Chen" <[email protected]>, [email protected] 主题: Re: [PATCH RESEND V2 3/3] docs/zh_CN: core-api: Add errseq Chinese translation

Quoted 6 lines · Binbin Zhou
Quoted 1 line

Honstly, I don't understand the meaning of this words. :/

According to the specific implementation of the function, what we want to track is the error after the sampling point ``since`` , so the ``since`` variable is only used for comparison and will be discarded later.

Quoted 6 lines
Quoted 3 lines

How about:
由于他只是在采样点后丢弃 ``since`` 变量,所以不需要在这里保存更新它。

Get it. if so, could we give a bit more info? like:
由于他只是在采样点后丢弃 ``since`` 变量(since 既是采样点),所以不需要在这里保存更新它。

OK. I get it, and I will send the V3 patchset.

Thanks.

Binbin

Quoted 3 lines

Thanks
Alex

本邮件及其附件含有龙芯中科的商业秘密信息,仅限于发送给上面地址中列出的个人或群组。禁止任何其他人以任何形式使用(包括但不限于全部或部分地泄露、复制或散发)本邮件及其附件中的信息。如果您错收本邮件,请您立即电话或邮件通知发件人并删除本邮件。
This email and its attachments contain confidential information from Loongson Technology , which is intended only for the person or entity whose address is listed above. Any use of the information contained herein in any way (including, but not limited to, total or partial disclosure, reproduction or dissemination) by persons other than the intended recipient(s) is prohibited. If you receive this email in error, please notify the sender by phone or email immediately and delete it.

maintainer Applied
#14 lore raw
In reply to Binbin Zhou
Quoted 29 lines · Binbin Zhou

Hi all:

As a continuation of the previous patchset
(https://lore.kernel.org/all/[email protected]/),
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 V1:
- Take Xiangcheng's advices, thanks.

Details:
https://lore.kernel.org/all/[email protected]/
https://lore.kernel.org/all/Y02EcgD3E0%[email protected]/

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

Quoted 8 lines
 .../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