* [PATCH 1/4] docs/zh_CN: core-api: Add idr Chinese translation
2022-07-14 13:05 [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1) Binbin Zhou
@ 2022-07-14 13:06 ` Binbin Zhou
2022-07-16 8:41 ` YanTeng Si
2022-07-16 12:45 ` Wu XiangCheng
2022-07-14 13:06 ` [PATCH 2/4] docs/zh_CN: core-api: Add circular-buffers " Binbin Zhou
` (3 subsequent siblings)
4 siblings, 2 replies; 11+ messages in thread
From: Binbin Zhou @ 2022-07-14 13:06 UTC (permalink / raw)
To: alexs, siyanteng
Cc: corbet, chenhuacai, bobwxc, zhoubb.aaron, linux-doc, Binbin Zhou
Translate core-api/idr.rst into Chinese.
Last English version used:
commit 85656ec193e9 ("IDR: Note that the IDR API is deprecated").
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
---
.../translations/zh_CN/core-api/idr.rst | 74 +++++++++++++++++++
.../translations/zh_CN/core-api/index.rst | 2 +-
2 files changed, 75 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/core-api/idr.rst
diff --git a/Documentation/translations/zh_CN/core-api/idr.rst b/Documentation/translations/zh_CN/core-api/idr.rst
new file mode 100644
index 000000000000..73458247deb7
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/idr.rst
@@ -0,0 +1,74 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/idr.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+======
+ID分配
+======
+
+:作者: Matthew Wilcox
+
+概述
+====
+
+要解决的一个常见问题是分配标识符（IDs）；它通常是标识事物的数字。比如包括文件描述
+符、进程ID、网络协议中的数据包标识符、SCSI标记和设备实例编号。IDR和IDA为这个问题
+提供了一个合理的解决方案，以避免每个人都自创。IDR提供将ID映射到指针的能力，而IDA
+仅提供ID分配，因此内存效率更高。
+
+IDR接口已经被废弃，请使用 `XArray <xarray>` 代替。
+
+IDR的用法
+=========
+
+首先初始化一个IDR，对于静态分配的IDR使用DEFINE_IDR()，或者对于动态分配的IDR使用
+idr_init()。
+
+您可以调用idr_alloc()来分配一个未使用的ID。通过调用idr_find()查询与该ID相关的指针，
+并通过调用idr_remove()释放该ID。
+
+如果需要更改与一个ID相关联的指针，可以调用idr_replace()。这样做的一个常见原因是通
+过将 ``NULL`` 指针传递给分配函数来保留ID；用保留的ID初始化对象，最后将初始化的对
+象插入IDR。
+
+一些用户需要分配大于 ``INT_MAX`` 的ID。到目前为止，所有这些用户都满足于 ``UINT_MAX``
+限制，他们使用idr_alloc_u32()。如果您需要的ID不适合在u32中使用，我们将与您合作以
+满足您的需求。
+
+如果需要按顺序分配ID，可以使用idr_alloc_cyclic()。处理较大数量的ID时，IDR的效率会
+降低，所以使用这个函数会有一点代价。
+
+要对IDR使用的所有指针进行操作，您可以使用基于回调的idr_for_each()或迭代器样式的
+idr_for_each_entry()。您可能需要使用idr_for_each_entry_continue()来继续迭代。如果
+迭代器不符合您的需求，您也可以使用idr_get_next()。
+
+当使用完IDR后，您可以调用idr_destroy()来释放IDR占用的内存。这并不会释放IDR指向的
+对象；如果您想这样做，请使用其中一个迭代器来执行此操作。
+
+您可以使用idr_is_empty()来查看当前是否分配了任何ID。
+
+如果在从IDR分配一个新ID时需要带锁，您可能需要传递一组限制性的GFP标志，但这可能导
+致IDR无法分配内存。为了解决该问题，您可以在获取锁之前调用idr_preload()，然后在分
+配之后调用idr_preload_end()。
+
+IDR同步的相关内容请见include/linux/idr.h文件中的“DOC: idr sync”。
+
+IDA的用法
+=========
+
+IDA的用法的相关内容请见lib/idr.c文件中的“DOC: IDA description”。
+
+函数和数据结构
+==============
+
+相关API请见以下内核文件：
+
+include/linux/idr.h
+
+lib/idr.c
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 080643bac459..f7210018d7f9 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -43,12 +43,12 @@
assoc_array
xarray
rbtree
+ idr
Todolist:
- idr
circular-buffers
generic-radix-tree
packing
--
2.20.1
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH 1/4] docs/zh_CN: core-api: Add idr Chinese translation
2022-07-14 13:06 ` [PATCH 1/4] docs/zh_CN: core-api: Add idr Chinese translation Binbin Zhou
@ 2022-07-16 8:41 ` YanTeng Si
2022-07-16 12:45 ` Wu XiangCheng
1 sibling, 0 replies; 11+ messages in thread
From: YanTeng Si @ 2022-07-16 8:41 UTC (permalink / raw)
To: Binbin Zhou, alexs; +Cc: corbet, chenhuacai, bobwxc, zhoubb.aaron, linux-doc
在 2022/7/14 21:06, Binbin Zhou 写道:
> Translate core-api/idr.rst into Chinese.
>
> Last English version used:
>
> commit 85656ec193e9 ("IDR: Note that the IDR API is deprecated").
>
> Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
> ---
> .../translations/zh_CN/core-api/idr.rst | 74 +++++++++++++++++++
> .../translations/zh_CN/core-api/index.rst | 2 +-
> 2 files changed, 75 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/core-api/idr.rst
>
> diff --git a/Documentation/translations/zh_CN/core-api/idr.rst b/Documentation/translations/zh_CN/core-api/idr.rst
> new file mode 100644
> index 000000000000..73458247deb7
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/idr.rst
> @@ -0,0 +1,74 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/core-api/idr.rst
> +
> +:翻译:
> +
> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
> +
> +======
> +ID分配
> +======
> +
> +:作者: Matthew Wilcox
> +
> +概述
> +====
> +
> +要解决的一个常见问题是分配标识符（IDs）；它通常是标识事物的数字。比如包括文件描述
> +符、进程ID、网络协议中的数据包标识符、SCSI标记和设备实例编号。IDR和IDA为这个问题
> +提供了一个合理的解决方案，以避免每个人都自创。IDR提供将ID映射到指针的能力，而IDA
> +仅提供ID分配，因此内存效率更高。
> +
> +IDR接口已经被废弃，请使用 `XArray <xarray>` 代替。
> +
> +IDR的用法
> +=========
> +
> +首先初始化一个IDR，对于静态分配的IDR使用DEFINE_IDR()，或者对于动态分配的IDR使用
> +idr_init()。
> +
> +您可以调用idr_alloc()来分配一个未使用的ID。通过调用idr_find()查询与该ID相关的指针，
> +并通过调用idr_remove()释放该ID。
> +
> +如果需要更改与一个ID相关联的指针，可以调用idr_replace()。这样做的一个常见原因是通
> +过将 ``NULL`` 指针传递给分配函数来保留ID；用保留的ID初始化对象，最后将初始化的对
> +象插入IDR。
> +
> +一些用户需要分配大于 ``INT_MAX`` 的ID。到目前为止，所有这些用户都满足于 ``UINT_MAX``
> +限制，他们使用idr_alloc_u32()。如果您需要的ID不适合在u32中使用，我们将与您合作以
> +满足您的需求。
> +
> +如果需要按顺序分配ID，可以使用idr_alloc_cyclic()。处理较大数量的ID时，IDR的效率会
> +降低，所以使用这个函数会有一点代价。
> +
> +要对IDR使用的所有指针进行操作，您可以使用基于回调的idr_for_each()或迭代器样式的
> +idr_for_each_entry()。您可能需要使用idr_for_each_entry_continue()来继续迭代。如果
> +迭代器不符合您的需求，您也可以使用idr_get_next()。
> +
> +当使用完IDR后，您可以调用idr_destroy()来释放IDR占用的内存。这并不会释放IDR指向的
> +对象；如果您想这样做，请使用其中一个迭代器来执行此操作。
> +
> +您可以使用idr_is_empty()来查看当前是否分配了任何ID。
> +
> +如果在从IDR分配一个新ID时需要带锁，您可能需要传递一组限制性的GFP标志，但这可能导
> +致IDR无法分配内存。为了解决该问题，您可以在获取锁之前调用idr_preload()，然后在分
> +配之后调用idr_preload_end()。
> +
> +IDR同步的相关内容请见include/linux/idr.h文件中的“DOC: idr sync”。
> +
> +IDA的用法
> +=========
> +
> +IDA的用法的相关内容请见lib/idr.c文件中的“DOC: IDA description”。
> +
> +函数和数据结构
> +==============
> +
> +相关API请见以下内核文件：
该API在以下内核代码中:
see .../zh_CN/core-api/kernel-api.rst
Thanks,
Yanteng
> +
> +include/linux/idr.h
> +
> +lib/idr.c
> diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> index 080643bac459..f7210018d7f9 100644
> --- a/Documentation/translations/zh_CN/core-api/index.rst
> +++ b/Documentation/translations/zh_CN/core-api/index.rst
> @@ -43,12 +43,12 @@
> assoc_array
> xarray
> rbtree
> + idr
>
> Todolist:
>
>
>
> - idr
> circular-buffers
> generic-radix-tree
> packing
^ permalink raw reply [flat|nested] 11+ messages in thread* Re: [PATCH 1/4] docs/zh_CN: core-api: Add idr Chinese translation
2022-07-14 13:06 ` [PATCH 1/4] docs/zh_CN: core-api: Add idr Chinese translation Binbin Zhou
2022-07-16 8:41 ` YanTeng Si
@ 2022-07-16 12:45 ` Wu XiangCheng
1 sibling, 0 replies; 11+ messages in thread
From: Wu XiangCheng @ 2022-07-16 12:45 UTC (permalink / raw)
To: Binbin Zhou; +Cc: alexs, siyanteng, corbet, chenhuacai, zhoubb.aaron, linux-doc
Hi Binbin,
On Thu, Jul 14, 2022 at 09:06:00PM +0800, Binbin Zhou wrote:
> Translate core-api/idr.rst into Chinese.
>
> Last English version used:
>
> commit 85656ec193e9 ("IDR: Note that the IDR API is deprecated").
>
> Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
> ---
> .../translations/zh_CN/core-api/idr.rst | 74 +++++++++++++++++++
> .../translations/zh_CN/core-api/index.rst | 2 +-
> 2 files changed, 75 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/core-api/idr.rst
>
> diff --git a/Documentation/translations/zh_CN/core-api/idr.rst b/Documentation/translations/zh_CN/core-api/idr.rst
> new file mode 100644
> index 000000000000..73458247deb7
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/idr.rst
> @@ -0,0 +1,74 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/core-api/idr.rst
> +
> +:翻译:
> +
> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
> +
> +======
> +ID分配
> +======
> +
> +:作者: Matthew Wilcox
> +
> +概述
> +====
> +
> +要解决的一个常见问题是分配标识符（IDs）；它通常是标识事物的数字。比如包括文件描述
> +符、进程ID、网络协议中的数据包标识符、SCSI标记和设备实例编号。IDR和IDA为这个问题
> +提供了一个合理的解决方案，以避免每个人都自创。IDR提供将ID映射到指针的能力，而IDA
> +仅提供ID分配，因此内存效率更高。
> +
> +IDR接口已经被废弃，请使用 `XArray <xarray>` 代替。
> +
> +IDR的用法
> +=========
> +
> +首先初始化一个IDR，对于静态分配的IDR使用DEFINE_IDR()，或者对于动态分配的IDR使用
> +idr_init()。
> +
> +您可以调用idr_alloc()来分配一个未使用的ID。通过调用idr_find()查询与该ID相关的指针，
> +并通过调用idr_remove()释放该ID。
> +
> +如果需要更改与一个ID相关联的指针，可以调用idr_replace()。这样做的一个常见原因是通
> +过将 ``NULL`` 指针传递给分配函数来保留ID；用保留的ID初始化对象，最后将初始化的对
> +象插入IDR。
> +
> +一些用户需要分配大于 ``INT_MAX`` 的ID。到目前为止，所有这些用户都满足于 ``UINT_MAX``
满足于 -> 满足
> +限制，他们使用idr_alloc_u32()。如果您需要的ID不适合在u32中使用，我们将与您合作以
不符合u32 or 超出u32
> +满足您的需求。
> +
> +如果需要按顺序分配ID，可以使用idr_alloc_cyclic()。处理较大数量的ID时，IDR的效率会
> +降低，所以使用这个函数会有一点代价。
> +
Thanks,
Wu
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 2/4] docs/zh_CN: core-api: Add circular-buffers Chinese translation
2022-07-14 13:05 [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1) Binbin Zhou
2022-07-14 13:06 ` [PATCH 1/4] docs/zh_CN: core-api: Add idr Chinese translation Binbin Zhou
@ 2022-07-14 13:06 ` Binbin Zhou
2022-07-16 9:04 ` YanTeng Si
2022-07-14 13:06 ` [PATCH 3/4] docs/zh_CN: core-api: Add generic-radix-tree " Binbin Zhou
` (2 subsequent siblings)
4 siblings, 1 reply; 11+ messages in thread
From: Binbin Zhou @ 2022-07-14 13:06 UTC (permalink / raw)
To: alexs, siyanteng
Cc: corbet, chenhuacai, bobwxc, zhoubb.aaron, linux-doc, Binbin Zhou
Translate core-api/circular-buffers.rst into Chinese.
Last English version used:
commit 714b6904e23e ("doc: Remove ".vnet" from paulmck email addresses").
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
---
.../zh_CN/core-api/circular-buffers.rst | 205 ++++++++++++++++++
.../translations/zh_CN/core-api/index.rst | 2 +-
2 files changed, 206 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/core-api/circular-buffers.rst
diff --git a/Documentation/translations/zh_CN/core-api/circular-buffers.rst b/Documentation/translations/zh_CN/core-api/circular-buffers.rst
new file mode 100644
index 000000000000..4e7aff66c2fb
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/circular-buffers.rst
@@ -0,0 +1,205 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/circular-buffers.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+==========
+循环缓冲区
+==========
+
+:作者: David Howells <dhowells@redhat.com>
+:作者: Paul E. McKenney <paulmck@linux.ibm.com>
+
+
+Linux 提供了许多可用于实现循环缓冲的特性。有两组这样的特性：
+
+ (1) 用于确定2次方大小的缓冲区信息的便利函数。
+
+ (2) 当缓冲区中对象的生产者和消费者不想共享一个锁时的内存障碍。
+
+如下所述，要使用这些设施，只需要一个生产者和一个消费者。可以通过序列化来处理多个
+生产者，并通过序列化来处理多个消费者。
+
+.. Contents:
+
+ (*) 什么是循环缓冲区？
+
+ (*) 测量2次幂缓冲区
+
+ (*) 内存屏障与循环缓冲区的结合使用
+ - 生产者
+ - 消费者
+
+ (*) 延伸阅读
+
+
+
+什么是循环缓冲区？
+==================
+
+首先，什么是循环缓冲区？循环缓冲区是具有固定的有限大小的缓冲区，它有两个索引：
+
+ (1) 'head'索引 - 生产者将元素插入缓冲区的位置。
+
+ (2) 'tail'索引 - 消费者在缓冲区中找到下一个元素的位置。
+
+通常，当tail指针等于head指针时，表明缓冲区是空的；而当head指针比tail指针少一个时，
+表明缓冲区是满的。
+
+添加元素时，递增head索引；删除元素时，递增tail索引。tail索引不应该跳过head索引，
+两个索引在到达缓冲区末端时都应该被赋值为0，从而允许无限量的数据流过缓冲区。
+
+通常情况下，元素都有相同的单元大小，但这并不是使用以下技术的严格要求。如果要在缓
+冲区中包含多个元素或可变大小的元素，则索引可以增加超过1，前提是两个索引都没有超
+过另一个。然而，实现者必须小心，因为超过一个单位大小的区域可能会包裹缓冲区的末端
+并被分成两段。
+
+测量2次幂缓冲区
+===============
+
+计算任意大小的循环缓冲区的占用或剩余容量通常是一个费时的操作，需要使用模（除法）
+指令。但是如果缓冲区的大小为2次幂，则可以使用更快的按位与指令代替。
+
+Linux提供了一组用于处理2次幂循环缓冲区的宏。可以通过以下方式使用::
+
+ #include <linux/circ_buf.h>
+
+这些宏包括：
+
+ (#) 测量缓冲区的剩余容量::
+
+ CIRC_SPACE(head_index, tail_index, buffer_size);
+
+ 返回缓冲区[1]中可插入元素的剩余空间大小。
+
+
+ (#) 测量缓冲区中的最大连续即时空间::
+
+ CIRC_SPACE_TO_END(head_index, tail_index, buffer_size);
+
+ 返回缓冲区[1]中剩余的连续空间的大小，元素可以立即插入其中，而不必折回到缓冲
+ 区的开头。
+
+
+ (#) 测量缓冲区的占用率::
+
+ CIRC_CNT(head_index, tail_index, buffer_size);
+
+ 返回当前占用缓冲区[2]的元素数量。
+
+
+ (#) 测量缓冲区的非包装占用::
+
+ CIRC_CNT_TO_END(head_index, tail_index, buffer_size);
+
+ 返回可以从缓冲区中提取的连续元素[2]的数量，而不必回绕到缓冲区的开头。
+
+这里的每一个宏名义上都会返回一个介于0和buffer_size-1之间的值，但是：
+
+ (1) CIRC_SPACE*()是为了在生产者中使用。对生产者来说，它们将返回一个下限，因为生
+ 产者控制着head索引，但消费者可能仍然在另一个CPU上耗尽缓冲区并移动tail索引。
+
+ 对消费者来说，它将显示一个上限，因为生产者可能正忙于耗尽空间。
+
+ (2) CIRC_CNT*()是为了在消费者中使用。对消费者来说，它们将返回一个下限，因为消费
+ 者控制着tail索引，但生产者可能仍然在另一个CPU上填充缓冲区并移动head索引。
+
+ 对于生产者，它将显示一个上限，因为消费者可能正忙于清空缓冲区。
+
+ (3) 对于第三方来说，生产者和消费者对索引的写入顺序是无法保证的，因为它们是独立的，
+ 而且可能是在不同的CPU上进行的，所以在这种情况下的结果只是一种猜测，甚至可能
+ 是错误的。
+
+内存屏障与循环缓冲区的结合使用
+==============================
+
+通过将内存屏障与循环缓冲区结合使用，可以避免以下需求：
+
+ (1) 使用单个锁来控制对缓冲区两端的访问，从而允许同时填充和清空缓冲区；以及
+
+ (2) 使用原子计数器操作。
+
+这有两个方面：填充缓冲区的生产者和清空缓冲区的消费者。在任何时候，只应有一个生产
+者在填充缓冲区，同样的也只应有一个消费者在清空缓冲区，但双方可以同时操作。
+
+
+生产者
+------
+
+生产者看起来像这样::
+
+ spin_lock(&producer_lock);
+
+ unsigned long head = buffer->head;
+ /* The spin_unlock() and next spin_lock() provide needed ordering. */
+ unsigned long tail = READ_ONCE(buffer->tail);
+
+ if (CIRC_SPACE(head, tail, buffer->size) >= 1) {
+ /* insert one item into the buffer */
+ struct item *item = buffer[head];
+
+ produce_item(item);
+
+ smp_store_release(buffer->head,
+ (head + 1) & (buffer->size - 1));
+
+ /* wake_up() will make sure that the head is committed before
+ * waking anyone up */
+ wake_up(consumer);
+ }
+
+ spin_unlock(&producer_lock);
+
+这将表明CPU必须在head索引使其对消费者可用之前写入新项目的内容，同时CPU必须在唤醒
+消费者之前写入修改后的head索引。
+
+请注意，wake_up()并不保证任何形式的屏障，除非确实唤醒了某些东西。因此我们不能依靠
+它来进行排序。但是数组中始终有一个元素留空，因此生产者必须产生两个元素，然后才可
+能破坏消费者当前正在读取的元素。同时，消费者连续调用之间成对的解锁-加锁提供了索引
+读取（指示消费者已清空给定元素）和生产者对该相同元素的写入之间的必要顺序。
+
+
+消费者
+------
+
+消费者看起来像这样::
+
+ spin_lock(&consumer_lock);
+
+ /* Read index before reading contents at that index. */
+ unsigned long head = smp_load_acquire(buffer->head);
+ unsigned long tail = buffer->tail;
+
+ if (CIRC_CNT(head, tail, buffer->size) >= 1) {
+
+ /* extract one item from the buffer */
+ struct item *item = buffer[tail];
+
+ consume_item(item);
+
+ /* Finish reading descriptor before incrementing tail. */
+ smp_store_release(buffer->tail,
+ (tail + 1) & (buffer->size - 1));
+ }
+
+ spin_unlock(&consumer_lock);
+
+这表明CPU在读取新元素之前确保索引是最新的，然后在写入新的尾指针之前应确保CPU已完
+成读取该元素，这将擦除该元素。
+
+请注意，使用READ_ONCE()和smp_load_acquire()来读取反向索引。这可以防止编译器丢弃并
+重新加载其缓存值。如果您能确定反向索引将仅使用一次，则这不是严格需要的。
+smp_load_acquire()还可以强制CPU对后续的内存引用进行排序。类似地，两种算法都使用
+smp_store_release()来写入线程的索引。这记录了我们正在写入可以并发读取的内容的事实，
+防止编译器破坏存储，并强制对以前的访问进行排序。
+
+
+延伸阅读
+========
+
+关于Linux的内存屏障设施的描述，请查看Documentation/memory-barriers.txt。
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index f7210018d7f9..136bac5eb18c 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -44,12 +44,12 @@
xarray
rbtree
idr
+ circular-buffers
Todolist:
- circular-buffers
generic-radix-tree
packing
this_cpu_ops
--
2.20.1
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH 2/4] docs/zh_CN: core-api: Add circular-buffers Chinese translation
2022-07-14 13:06 ` [PATCH 2/4] docs/zh_CN: core-api: Add circular-buffers " Binbin Zhou
@ 2022-07-16 9:04 ` YanTeng Si
0 siblings, 0 replies; 11+ messages in thread
From: YanTeng Si @ 2022-07-16 9:04 UTC (permalink / raw)
To: Binbin Zhou, alexs; +Cc: corbet, chenhuacai, bobwxc, zhoubb.aaron, linux-doc
在 2022/7/14 21:06, Binbin Zhou 写道:
> Translate core-api/circular-buffers.rst into Chinese.
>
> Last English version used:
>
> commit 714b6904e23e ("doc: Remove ".vnet" from paulmck email addresses").
>
> Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
> ---
> .../zh_CN/core-api/circular-buffers.rst | 205 ++++++++++++++++++
> .../translations/zh_CN/core-api/index.rst | 2 +-
> 2 files changed, 206 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/core-api/circular-buffers.rst
>
> diff --git a/Documentation/translations/zh_CN/core-api/circular-buffers.rst b/Documentation/translations/zh_CN/core-api/circular-buffers.rst
> new file mode 100644
> index 000000000000..4e7aff66c2fb
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/circular-buffers.rst
> @@ -0,0 +1,205 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/core-api/circular-buffers.rst
> +
> +:翻译:
> +
> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
> +
> +==========
> +循环缓冲区
How about 环形缓冲区？
> +==========
> +
> +:作者: David Howells <dhowells@redhat.com>
> +:作者: Paul E. McKenney <paulmck@linux.ibm.com>
> +
> +
> +Linux 提供了许多可用于实现循环缓冲的特性。有两组这样的特性：
> +
> + (1) 用于确定2次方大小的缓冲区信息的便利函数。
> +
> + (2) 当缓冲区中对象的生产者和消费者不想共享一个锁时的内存障碍。
内存屏障
> +
> +如下所述，要使用这些设施，只需要一个生产者和一个消费者。可以通过序列化来处理多个
> +生产者，并通过序列化来处理多个消费者。
> +
> +.. Contents:
> +
> + (*) 什么是循环缓冲区？
> +
> + (*) 测量2次幂缓冲区
> +
> + (*) 内存屏障与循环缓冲区的结合使用
> + - 生产者
> + - 消费者
> +
> + (*) 延伸阅读
> +
> +
> +
> +什么是循环缓冲区？
> +==================
> +
> +首先，什么是循环缓冲区？循环缓冲区是具有固定的有限大小的缓冲区，它有两个索引：
> +
> + (1) 'head'索引 - 生产者将元素插入缓冲区的位置。
> +
> + (2) 'tail'索引 - 消费者在缓冲区中找到下一个元素的位置。
> +
> +通常，当tail指针等于head指针时，表明缓冲区是空的；而当head指针比tail指针少一个时，
> +表明缓冲区是满的。
> +
> +添加元素时，递增head索引；删除元素时，递增tail索引。tail索引不应该跳过head索引，
> +两个索引在到达缓冲区末端时都应该被赋值为0，从而允许无限量的数据流过缓冲区。
how about 海量的数据流？
> +
> +通常情况下，元素都有相同的单元大小，但这并不是使用以下技术的严格要求。如果要在缓
> +冲区中包含多个元素或可变大小的元素，则索引可以增加超过1，前提是两个索引都没有超
> +过另一个。然而，实现者必须小心，因为超过一个单位大小的区域可能会包裹缓冲区的末端
包裹 -> 覆盖
> +并被分成两段。
并且缓冲区会被分成两段
> +
> +测量2次幂缓冲区
> +===============
> +
> +计算任意大小的循环缓冲区的占用或剩余容量通常是一个费时的操作，需要使用模（除法）
> +指令。但是如果缓冲区的大小为2次幂，则可以使用更快的按位与指令代替。
> +
> +Linux提供了一组用于处理2次幂循环缓冲区的宏。可以通过以下方式使用::
> +
> + #include <linux/circ_buf.h>
> +
> +这些宏包括：
> +
> + (#) 测量缓冲区的剩余容量::
> +
> + CIRC_SPACE(head_index, tail_index, buffer_size);
> +
> + 返回缓冲区[1]中可插入元素的剩余空间大小。
> +
> +
> + (#) 测量缓冲区中的最大连续即时空间::
> +
> + CIRC_SPACE_TO_END(head_index, tail_index, buffer_size);
> +
> + 返回缓冲区[1]中剩余的连续空间的大小，元素可以立即插入其中，而不必折回到缓冲
折回 -> 绕回
> + 区的开头。
> +
> +
> + (#) 测量缓冲区的占用率::
> +
> + CIRC_CNT(head_index, tail_index, buffer_size);
> +
> + 返回当前占用缓冲区[2]的元素数量。
> +
> +
> + (#) 测量缓冲区的非包装占用::
测量一个缓冲区的非覆盖占用率
> +
> + CIRC_CNT_TO_END(head_index, tail_index, buffer_size);
> +
> + 返回可以从缓冲区中提取的连续元素[2]的数量，而不必回绕到缓冲区的开头。
> +
> +这里的每一个宏名义上都会返回一个介于0和buffer_size-1之间的值，但是：
> +
> + (1) CIRC_SPACE*()是为了在生产者中使用。对生产者来说，它们将返回一个下限，因为生
> + 产者控制着head索引，但消费者可能仍然在另一个CPU上耗尽缓冲区并移动tail索引。
> +
> + 对消费者来说，它将显示一个上限，因为生产者可能正忙于耗尽空间。
> +
> + (2) CIRC_CNT*()是为了在消费者中使用。对消费者来说，它们将返回一个下限，因为消费
> + 者控制着tail索引，但生产者可能仍然在另一个CPU上填充缓冲区并移动head索引。
> +
> + 对于生产者，它将显示一个上限，因为消费者可能正忙于清空缓冲区。
> +
> + (3) 对于第三方来说，生产者和消费者对索引的写入顺序是无法保证的，因为它们是独立的，
> + 而且可能是在不同的CPU上进行的，所以在这种情况下的结果只是一种猜测，甚至可能
> + 是错误的。
> +
> +内存屏障与循环缓冲区的结合使用
> +==============================
> +
> +通过将内存屏障与循环缓冲区结合使用，可以避免以下需求：
> +
> + (1) 使用单个锁来控制对缓冲区两端的访问，从而允许同时填充和清空缓冲区；以及
> +
> + (2) 使用原子计数器操作。
> +
> +这有两个方面：填充缓冲区的生产者和清空缓冲区的消费者。在任何时候，只应有一个生产
> +者在填充缓冲区，同样的也只应有一个消费者在清空缓冲区，但双方可以同时操作。
> +
> +
> +生产者
> +------
> +
> +生产者看起来像这样::
> +
> + spin_lock(&producer_lock);
> +
> + unsigned long head = buffer->head;
> + /* The spin_unlock() and next spin_lock() provide needed ordering. */
Need to be translated.
> + unsigned long tail = READ_ONCE(buffer->tail);
> +
> + if (CIRC_SPACE(head, tail, buffer->size) >= 1) {
> + /* insert one item into the buffer */
> + struct item *item = buffer[head];
> +
> + produce_item(item);
> +
> + smp_store_release(buffer->head,
> + (head + 1) & (buffer->size - 1));
> +
> + /* wake_up() will make sure that the head is committed before
> + * waking anyone up */
ditto
> + wake_up(consumer);
> + }
> +
> + spin_unlock(&producer_lock);
> +
> +这将表明CPU必须在head索引使其对消费者可用之前写入新项目的内容，同时CPU必须在唤醒
> +消费者之前写入修改后的head索引。
> +
> +请注意，wake_up()并不保证任何形式的屏障，除非确实唤醒了某些东西。因此我们不能依靠
> +它来进行排序。但是数组中始终有一个元素留空，因此生产者必须产生两个元素，然后才可
> +能破坏消费者当前正在读取的元素。同时，消费者连续调用之间成对的解锁-加锁提供了索引
> +读取（指示消费者已清空给定元素）和生产者对该相同元素的写入之间的必要顺序。
> +
> +
> +消费者
> +------
> +
> +消费者看起来像这样::
> +
> + spin_lock(&consumer_lock);
> +
> + /* Read index before reading contents at that index. */
ditto
> + unsigned long head = smp_load_acquire(buffer->head);
> + unsigned long tail = buffer->tail;
> +
> + if (CIRC_CNT(head, tail, buffer->size) >= 1) {
> +
> + /* extract one item from the buffer */
ditto
> + struct item *item = buffer[tail];
> +
> + consume_item(item);
> +
> + /* Finish reading descriptor before incrementing tail. */
ditto
> + smp_store_release(buffer->tail,
> + (tail + 1) & (buffer->size - 1));
> + }
> +
> + spin_unlock(&consumer_lock);
> +
> +这表明CPU在读取新元素之前确保索引是最新的，然后在写入新的尾指针之前应确保CPU已完
> +成读取该元素，这将擦除该元素。
> +
> +请注意，使用READ_ONCE()和smp_load_acquire()来读取反向索引。这可以防止编译器丢弃并
> +重新加载其缓存值。如果您能确定反向索引将仅使用一次，则这不是严格需要的。
> +smp_load_acquire()还可以强制CPU对后续的内存引用进行排序。类似地，两种算法都使用
> +smp_store_release()来写入线程的索引。这记录了我们正在写入可以并发读取的内容的事实，
> +防止编译器破坏存储，并强制对以前的访问进行排序。
以防止编译器……
Thanks
Yanteng
> +
> +
> +延伸阅读
> +========
> +
> +关于Linux的内存屏障设施的描述，请查看Documentation/memory-barriers.txt。
> diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> index f7210018d7f9..136bac5eb18c 100644
> --- a/Documentation/translations/zh_CN/core-api/index.rst
> +++ b/Documentation/translations/zh_CN/core-api/index.rst
> @@ -44,12 +44,12 @@
> xarray
> rbtree
> idr
> + circular-buffers
>
> Todolist:
>
>
>
> - circular-buffers
> generic-radix-tree
> packing
> this_cpu_ops
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 3/4] docs/zh_CN: core-api: Add generic-radix-tree Chinese translation
2022-07-14 13:05 [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1) Binbin Zhou
2022-07-14 13:06 ` [PATCH 1/4] docs/zh_CN: core-api: Add idr Chinese translation Binbin Zhou
2022-07-14 13:06 ` [PATCH 2/4] docs/zh_CN: core-api: Add circular-buffers " Binbin Zhou
@ 2022-07-14 13:06 ` Binbin Zhou
2022-07-14 13:06 ` [PATCH 4/4] docs/zh_CN: core-api: Add packing " Binbin Zhou
2022-07-16 14:06 ` [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1) Wu XiangCheng
4 siblings, 0 replies; 11+ messages in thread
From: Binbin Zhou @ 2022-07-14 13:06 UTC (permalink / raw)
To: alexs, siyanteng
Cc: corbet, chenhuacai, bobwxc, zhoubb.aaron, linux-doc, Binbin Zhou
Translate core-api/generic-radix-tree.rst into Chinese.
Last English version used:
commit ba20ba2e3743 ("generic radix trees").
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
---
.../zh_CN/core-api/generic-radix-tree.rst | 23 +++++++++++++++++++
.../translations/zh_CN/core-api/index.rst | 2 +-
2 files changed, 24 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/core-api/generic-radix-tree.rst
diff --git a/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst b/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst
new file mode 100644
index 000000000000..585c14b7634a
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/generic-radix-tree.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+===================
+通用基数树/稀疏数组
+===================
+
+通用基数树/稀疏数组的相关内容请见include/linux/generic-radix-tree.h文件中的
+“DOC: Generic radix trees/sparse arrays”。
+
+通用基数树函数
+--------------
+
+相关API请见以下内核文件：
+
+include/linux/generic-radix-tree.h
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 136bac5eb18c..aa376da1800e 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -45,12 +45,12 @@
rbtree
idr
circular-buffers
+ generic-radix-tree
Todolist:
- generic-radix-tree
packing
this_cpu_ops
timekeeping
--
2.20.1
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH 4/4] docs/zh_CN: core-api: Add packing Chinese translation
2022-07-14 13:05 [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1) Binbin Zhou
` (2 preceding siblings ...)
2022-07-14 13:06 ` [PATCH 3/4] docs/zh_CN: core-api: Add generic-radix-tree " Binbin Zhou
@ 2022-07-14 13:06 ` Binbin Zhou
2022-07-16 9:18 ` YanTeng Si
2022-07-16 14:06 ` [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1) Wu XiangCheng
4 siblings, 1 reply; 11+ messages in thread
From: Binbin Zhou @ 2022-07-14 13:06 UTC (permalink / raw)
To: alexs, siyanteng
Cc: corbet, chenhuacai, bobwxc, zhoubb.aaron, linux-doc, Binbin Zhou
Translate core-api/packing.rst into Chinese.
Last English version used:
commit 1ec779b9fabc ("docs: packing: move it to core-api book
and adjust markups").
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
---
.../translations/zh_CN/core-api/index.rst | 2 +-
.../translations/zh_CN/core-api/packing.rst | 154 ++++++++++++++++++
2 files changed, 155 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/core-api/packing.rst
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index aa376da1800e..2f00210a12b8 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -46,12 +46,12 @@
idr
circular-buffers
generic-radix-tree
+ packing
Todolist:
- packing
this_cpu_ops
timekeeping
errseq
diff --git a/Documentation/translations/zh_CN/core-api/packing.rst b/Documentation/translations/zh_CN/core-api/packing.rst
new file mode 100644
index 000000000000..6d606c41709e
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/packing.rst
@@ -0,0 +1,154 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/packing.rst
+
+:翻译:
+
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+========================
+通用的位域打包和解包函数
+========================
+
+问题陈述
+--------
+
+使用硬件时，必须在几种与其交互的方法之间进行选择。
+
+可以将指针映射到在硬件设备的内存区域上精心设计的结构，并将其字段作为结构成员（可
+能声明为位域）访问。但是由于CPU和硬件设备之间潜在的字节顺序不匹配，以这种方式编
+写代码会降低其可移植性。
+
+此外，必须密切注意将硬件文档中的寄存器定义转换为结构的位域索引。此外，一些硬件
+（通常是网络设备）倾向于以违反任何合理字边界（有时甚至是64位）的方式对其寄存器字
+段进行分组。这就造成了不得不在结构中定义寄存器字段的“高”和“低”部分的不便。
+
+结构域定义的更可靠的替代方法是通过移动适当数量的位来提取所需的字段。但这仍然不能
+防止字节顺序不匹配，除非所有内存访问都是逐字节执行的。此外，代码很容易变得杂乱无
+章，同时可能会在所需的许多位移操作中丢失一些高层次的想法。
+
+许多驱动程序采用了位移的方法，然后试图用定制的宏来减少杂乱无章的东西，但更多的时
+候，这些宏所采用的捷径依旧妨碍了代码真正的可移植性。
+
+解决方案
+--------
+
+该API涉及2个基本操作：
+
+ - 将一个CPU可使用的数字打包到内存缓冲区中（具有硬件约束/特殊性）。
+ - 将内存缓冲区（具有硬件约束/特殊性）解压缩为一个CPU可使用的数字。
+
+该API提供了对所述硬件约束和特殊性以及CPU字节序的抽象，因此这两者之间可能不匹配。
+
+这些API函数的基本单元是u64。从CPU的角度来看，位63总是意味着字节7的位偏移量7，尽管
+只是逻辑上的。问题是：我们将这个位放在什么内存的位置？
+
+以下示例介绍了打包u64字段的内存布局。打包缓冲区中的字节偏移量始终默认为0，1...7。
+示例显示的是逻辑字节和位所在的位置。
+
+1. 通常情况下（无特殊性），我们会这样做：
+
+::
+
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
+
+也就是说，CPU可使用的u64的MSByte(7)位于内存偏移量0处，而u64的LSByte(0)位于内存偏移量7处。
+
+这对应于大多数人认为的“大端”，其中位i对应于数字2^i。这在代码注释中也称为“逻辑”符号。
+
+
+2. 如果设置了QUIRK_MSB_ON_THE_RIGHT，我们按如下方式操作：
+
+::
+
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
+
+也就是说，QUIRK_MSB_ON_THE_RIGHT不会影响字节定位，但会反转字节内的位偏移量。
+
+
+3. 如果设置了QUIRK_LITTLE_ENDIAN，我们按如下方式操作：
+
+::
+
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
+
+因此，QUIRK_LITTLE_ENDIAN意味着在内存区域内，每个4字节的字的每个字节都被放置在与
+该字的边界相比的镜像位置。
+
+
+4. 如果设置了QUIRK_MSB_ON_THE_RIGHT和QUIRK_LITTLE_ENDIAN，我们这样做：
+
+::
+
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
+
+
+5. 如果只设置了QUIRK_LSW32_IS_FIRST，我们这样做：
+
+::
+
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
+
+在这种情况下，8字节内存区域解释如下：前4字节对应最不重要的4字节的字，后4字节对应
+更重要的4字节的字。
+
+6. 如果设置了QUIRK_LSW32_IS_FIRST和QUIRK_MSB_ON_THE_RIGHT，我们这样做：
+
+::
+
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
+
+
+7. 如果设置了QUIRK_LSW32_IS_FIRST和QUIRK_LITTLE_ENDIAN，则如下所示：
+
+::
+
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
+
+
+8. 如果设置了QUIRK_LSW32_IS_FIRST，QUIRK_LITTLE_ENDIAN和QUIRK_MSB_ON_THE_RIGHT，
+ 则如下所示：
+
+::
+
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
+
+
+我们总是认为我们的偏移量好像没有特殊性，然后在访问内存区域之前翻译它们。
+
+预期用途
+--------
+
+选择使用该API的驱动程序首先需要确定上述3种quirk组合（共8种）中的哪一种与硬件文档
+中描述的相匹配。然后，他们应该封装packing()函数，创建一个新的xxx_packing()，使用
+适当的QUIRK_* one-hot 位集合来调用它。
+
+packing()函数返回一个int类型的错误码，以防止程序员使用不正确的API。这些错误预计不
+会在运行时发生，因此xxx_packing()返回void并简单地接受这些错误是合理的。它可以选择
+转储堆栈或打印错误描述。
--
2.20.1
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH 4/4] docs/zh_CN: core-api: Add packing Chinese translation
2022-07-14 13:06 ` [PATCH 4/4] docs/zh_CN: core-api: Add packing " Binbin Zhou
@ 2022-07-16 9:18 ` YanTeng Si
0 siblings, 0 replies; 11+ messages in thread
From: YanTeng Si @ 2022-07-16 9:18 UTC (permalink / raw)
To: Binbin Zhou, alexs; +Cc: corbet, chenhuacai, bobwxc, zhoubb.aaron, linux-doc
在 2022/7/14 21:06, Binbin Zhou 写道:
> Translate core-api/packing.rst into Chinese.
>
> Last English version used:
>
> commit 1ec779b9fabc ("docs: packing: move it to core-api book
> and adjust markups").
>
> Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
> ---
> .../translations/zh_CN/core-api/index.rst | 2 +-
> .../translations/zh_CN/core-api/packing.rst | 154 ++++++++++++++++++
> 2 files changed, 155 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/core-api/packing.rst
>
> diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> index aa376da1800e..2f00210a12b8 100644
> --- a/Documentation/translations/zh_CN/core-api/index.rst
> +++ b/Documentation/translations/zh_CN/core-api/index.rst
> @@ -46,12 +46,12 @@
> idr
> circular-buffers
> generic-radix-tree
> + packing
>
> Todolist:
>
>
>
> - packing
> this_cpu_ops
> timekeeping
> errseq
> diff --git a/Documentation/translations/zh_CN/core-api/packing.rst b/Documentation/translations/zh_CN/core-api/packing.rst
> new file mode 100644
> index 000000000000..6d606c41709e
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/packing.rst
> @@ -0,0 +1,154 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/core-api/packing.rst
> +
> +:翻译:
> +
> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
> +
> +========================
> +通用的位域打包和解包函数
> +========================
> +
> +问题陈述
> +--------
> +
> +使用硬件时，必须在几种与其交互的方法之间进行选择。
> +
> +可以将指针映射到在硬件设备的内存区域上精心设计的结构，并将其字段作为结构成员（可
结构 -> 结构体
内存区域 -> 内存区 （just like 缓冲区）
> +能声明为位域）访问。但是由于CPU和硬件设备之间潜在的字节顺序不匹配，以这种方式编
> +写代码会降低其可移植性。
> +
> +此外，必须密切注意将硬件文档中的寄存器定义转换为结构的位域索引。此外，一些硬件
> +（通常是网络设备）倾向于以违反任何合理字边界（有时甚至是64位）的方式对其寄存器字
> +段进行分组。这就造成了不得不在结构中定义寄存器字段的“高”和“低”部分的不便。
> +
> +结构域定义的更可靠的替代方法是通过移动适当数量的位来提取所需的字段。但这仍然不能
> +防止字节顺序不匹配，除非所有内存访问都是逐字节执行的。此外，代码很容易变得杂乱无
> +章，同时可能会在所需的许多位移操作中丢失一些高层次的想法。
> +
> +许多驱动程序采用了位移的方法，然后试图用定制的宏来减少杂乱无章的东西，但更多的时
> +候，这些宏所采用的捷径依旧妨碍了代码真正的可移植性。
> +
> +解决方案
> +--------
> +
> +该API涉及2个基本操作：
> +
> + - 将一个CPU可使用的数字打包到内存缓冲区中（具有硬件约束/特殊性）。
> + - 将内存缓冲区（具有硬件约束/特殊性）解压缩为一个CPU可使用的数字。
> +
> +该API提供了对所述硬件约束和特殊性以及CPU字节序的抽象，因此这两者之间可能不匹配。
> +
> +这些API函数的基本单元是u64。从CPU的角度来看，位63总是意味着字节7的位偏移量7，尽管
> +只是逻辑上的。问题是：我们将这个位放在什么内存的位置？
我们在内存中把这个比特放在哪里？
> +
> +以下示例介绍了打包u64字段的内存布局。打包缓冲区中的字节偏移量始终默认为0，1...7。
> +示例显示的是逻辑字节和位所在的位置。
> +
> +1. 通常情况下（无特殊性），我们会这样做：
> +
> +::
> +
> + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> + 7 6 5 4
> + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> + 3 2 1 0
> +
> +也就是说，CPU可使用的u64的MSByte(7)位于内存偏移量0处，而u64的LSByte(0)位于内存偏移量7处。
> +
> +这对应于大多数人认为的“大端”，其中位i对应于数字2^i。这在代码注释中也称为“逻辑”符号。
> +
> +
> +2. 如果设置了QUIRK_MSB_ON_THE_RIGHT，我们按如下方式操作：
> +
> +::
> +
> + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> + 7 6 5 4
> + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> + 3 2 1 0
> +
> +也就是说，QUIRK_MSB_ON_THE_RIGHT不会影响字节定位，但会反转字节内的位偏移量。
> +
> +
> +3. 如果设置了QUIRK_LITTLE_ENDIAN，我们按如下方式操作：
> +
> +::
> +
> + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> + 4 5 6 7
> + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> + 0 1 2 3
> +
> +因此，QUIRK_LITTLE_ENDIAN意味着在内存区域内，每个4字节的字的每个字节都被放置在与
> +该字的边界相比的镜像位置。
> +
> +
> +4. 如果设置了QUIRK_MSB_ON_THE_RIGHT和QUIRK_LITTLE_ENDIAN，我们这样做：
> +
> +::
> +
> + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> + 4 5 6 7
> + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> + 0 1 2 3
> +
> +
> +5. 如果只设置了QUIRK_LSW32_IS_FIRST，我们这样做：
> +
> +::
> +
> + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> + 3 2 1 0
> + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> + 7 6 5 4
> +
> +在这种情况下，8字节内存区域解释如下：前4字节对应最不重要的4字节的字，后4字节对应
> +更重要的4字节的字。
> +
> +6. 如果设置了QUIRK_LSW32_IS_FIRST和QUIRK_MSB_ON_THE_RIGHT，我们这样做：
> +
> +::
> +
> + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> + 3 2 1 0
> + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> + 7 6 5 4
> +
> +
> +7. 如果设置了QUIRK_LSW32_IS_FIRST和QUIRK_LITTLE_ENDIAN，则如下所示：
> +
> +::
> +
> + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> + 0 1 2 3
> + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> + 4 5 6 7
> +
> +
> +8. 如果设置了QUIRK_LSW32_IS_FIRST，QUIRK_LITTLE_ENDIAN和QUIRK_MSB_ON_THE_RIGHT，
> + 则如下所示：
> +
> +::
> +
> + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> + 0 1 2 3
> + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> + 4 5 6 7
> +
> +
> +我们总是认为我们的偏移量好像没有特殊性，然后在访问内存区域之前翻译它们。
> +
> +预期用途
> +--------
> +
> +选择使用该API的驱动程序首先需要确定上述3种quirk组合（共8种）中的哪一种与硬件文档
> +中描述的相匹配。然后，他们应该封装packing()函数，创建一个新的xxx_packing()，使用
> +适当的QUIRK_* one-hot 位集合来调用它。
> +
> +packing()函数返回一个int类型的错误码，以防止程序员使用不正确的API。这些错误预计不
> +会在运行时发生，因此xxx_packing()返回void并简单地接受这些错误是合理的。它可以选择
> +转储堆栈或打印错误描述。
堆栈 -> 栈
Thanks,
Yanteng
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1)
2022-07-14 13:05 [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1) Binbin Zhou
` (3 preceding siblings ...)
2022-07-14 13:06 ` [PATCH 4/4] docs/zh_CN: core-api: Add packing " Binbin Zhou
@ 2022-07-16 14:06 ` Wu XiangCheng
2022-07-16 15:27 ` Binbin Zhou
4 siblings, 1 reply; 11+ messages in thread
From: Wu XiangCheng @ 2022-07-16 14:06 UTC (permalink / raw)
To: Binbin Zhou; +Cc: alexs, siyanteng, corbet, chenhuacai, zhoubb.aaron, linux-doc
[-- Attachment #1: Type: text/plain, Size: 2674 bytes --]
On Thu, Jul 14, 2022 at 09:05:59PM +0800, Binbin Zhou wrote:
> Hi all:
>
> I have translated all the docs for section "Data structures and low-level utilities"
> of the core-api, and I plan to split them into two patchset submissions.
>
> This patchset contains the following files:
>
> idr.rst
> circular-buffers.rst
> generic-radix-tree.rst
> packing.rst
>
> For more details, please see TODOLIST in core-api/index.rst.
>
> Thanks.
>
> Binbin Zhou (4):
> docs/zh_CN: core-api: Add idr Chinese translation
> docs/zh_CN: core-api: Add circular-buffers Chinese translation
> docs/zh_CN: core-api: Add generic-radix-tree Chinese translation
> docs/zh_CN: core-api: Add packing Chinese translation
$ git am ~/Desktop/20220714_zhoubinbin_docs_zh_cn_core_api_add_some_translations_for_the_data_structures_section_part_1.mbx
应用：docs/zh_CN: core-api: Add idr Chinese translation
应用：docs/zh_CN: core-api: Add circular-buffers Chinese translation
error: 打补丁失败：Documentation/translations/zh_CN/core-api/index.rst:44
error: Documentation/translations/zh_CN/core-api/index.rst：补丁未应用
打补丁失败于 0002 docs/zh_CN: core-api: Add circular-buffers Chinese translation
Since your patches are based on linux-next, 2-4 couldn't be applied to
docs-next now.
commit 4313a24985f00340eeb591fd66aa2b257b9e0a69 from linux-next have changed
core-api/index.rst
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 26d9913fc8b60..c52175fc1b610 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -52,7 +52,6 @@ Todolist:
circular-buffers
generic-radix-tree
packing
- bus-virt-phys-mapping
this_cpu_ops
timekeeping
errseq
So please rebase your patch set on jc/docs-next.
Thanks,
Wu
>
> .../zh_CN/core-api/circular-buffers.rst | 205 ++++++++++++++++++
> .../zh_CN/core-api/generic-radix-tree.rst | 23 ++
> .../translations/zh_CN/core-api/idr.rst | 74 +++++++
> .../translations/zh_CN/core-api/index.rst | 8 +-
> .../translations/zh_CN/core-api/packing.rst | 154 +++++++++++++
> 5 files changed, 460 insertions(+), 4 deletions(-)
> create mode 100644 Documentation/translations/zh_CN/core-api/circular-buffers.rst
> create mode 100644 Documentation/translations/zh_CN/core-api/generic-radix-tree.rst
> create mode 100644 Documentation/translations/zh_CN/core-api/idr.rst
> create mode 100644 Documentation/translations/zh_CN/core-api/packing.rst
>
> --
> 2.20.1
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1)
2022-07-16 14:06 ` [PATCH 0/4] docs/zh_CN: core-api: Add some translations for the "Data structures" section(Part 1) Wu XiangCheng
@ 2022-07-16 15:27 ` Binbin Zhou
0 siblings, 0 replies; 11+ messages in thread
From: Binbin Zhou @ 2022-07-16 15:27 UTC (permalink / raw)
To: Wu XiangCheng
Cc: alexs, siyanteng, corbet, chenhuacai, zhoubb.aaron, linux-doc
在 2022/7/16 22:06, Wu XiangCheng 写道:
> On Thu, Jul 14, 2022 at 09:05:59PM +0800, Binbin Zhou wrote:
>> Hi all:
>>
>> I have translated all the docs for section "Data structures and low-level utilities"
>> of the core-api, and I plan to split them into two patchset submissions.
>>
>> This patchset contains the following files:
>>
>> idr.rst
>> circular-buffers.rst
>> generic-radix-tree.rst
>> packing.rst
>>
>> For more details, please see TODOLIST in core-api/index.rst.
>>
>> Thanks.
>>
>> Binbin Zhou (4):
>> docs/zh_CN: core-api: Add idr Chinese translation
>> docs/zh_CN: core-api: Add circular-buffers Chinese translation
>> docs/zh_CN: core-api: Add generic-radix-tree Chinese translation
>> docs/zh_CN: core-api: Add packing Chinese translation
> $ git am ~/Desktop/20220714_zhoubinbin_docs_zh_cn_core_api_add_some_translations_for_the_data_structures_section_part_1.mbx
> 应用：docs/zh_CN: core-api: Add idr Chinese translation
> 应用：docs/zh_CN: core-api: Add circular-buffers Chinese translation
> error: 打补丁失败：Documentation/translations/zh_CN/core-api/index.rst:44
> error: Documentation/translations/zh_CN/core-api/index.rst：补丁未应用
> 打补丁失败于 0002 docs/zh_CN: core-api: Add circular-buffers Chinese translation
>
> Since your patches are based on linux-next, 2-4 couldn't be applied to
> docs-next now.
>
> commit 4313a24985f00340eeb591fd66aa2b257b9e0a69 from linux-next have changed
> core-api/index.rst
>
> diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
> index 26d9913fc8b60..c52175fc1b610 100644
> --- a/Documentation/translations/zh_CN/core-api/index.rst
> +++ b/Documentation/translations/zh_CN/core-api/index.rst
> @@ -52,7 +52,6 @@ Todolist:
> circular-buffers
> generic-radix-tree
> packing
> - bus-virt-phys-mapping
> this_cpu_ops
> timekeeping
> errseq
>
> So please rebase your patch set on jc/docs-next.
Hi XiangCheng:
ok, I will rebase my patch set later...
Thanks,
Binbin
>
> Thanks,
> Wu
>
>> .../zh_CN/core-api/circular-buffers.rst | 205 ++++++++++++++++++
>> .../zh_CN/core-api/generic-radix-tree.rst | 23 ++
>> .../translations/zh_CN/core-api/idr.rst | 74 +++++++
>> .../translations/zh_CN/core-api/index.rst | 8 +-
>> .../translations/zh_CN/core-api/packing.rst | 154 +++++++++++++
>> 5 files changed, 460 insertions(+), 4 deletions(-)
>> create mode 100644 Documentation/translations/zh_CN/core-api/circular-buffers.rst
>> create mode 100644 Documentation/translations/zh_CN/core-api/generic-radix-tree.rst
>> create mode 100644 Documentation/translations/zh_CN/core-api/idr.rst
>> create mode 100644 Documentation/translations/zh_CN/core-api/packing.rst
>>
>> --
>> 2.20.1
^ permalink raw reply [flat|nested] 11+ messages in thread