[PATCH v4 0/3] Add chinese translation for block

[PATCH v4 0/3] Add chinese translation for block

[ke zijie]

This patch set adds chinese translations for the BLOCK documentation.

Changes in v4:
 - Fix formatting and translation issues (reported by Yanteng Si)
 - Link to v3: https://lore.kernel.org/linux-doc/cover.1763366835.git.kezijie@leap-io-kernel.com/

Changes in v3:
 - Add Reviewed-by tag from Wang Yuli
 - Link to v2: https://lore.kernel.org/linux-doc/cover.1763350407.git.kezijie@leap-io-kernel.com/

Changes in v2:
 - Fix Chinese/English spacing issues (suggested by Wang Yuli)
 - Fix make htmldocs warning: "Duplicate C declaration"
 - Adjust blk-mq translation wording
 - Link to v1: https://lore.kernel.org/linux-doc/cover.1763105050.git.kezijie@leap-io-kernel.com/

ke zijie (3):
  docs/zh_CN: Add block/index.rst translation
  docs/zh_CN: Add blk-mq.rst translation
  docs/zh_CN: Add data-integrity.rst translation

 .../translations/zh_CN/block/blk-mq.rst       | 130 ++++++++++++
 .../zh_CN/block/data-integrity.rst            | 193 ++++++++++++++++++
 .../translations/zh_CN/block/index.rst        |  35 ++++
 .../translations/zh_CN/subsystem-apis.rst     |   1 -
 4 files changed, 358 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/block/blk-mq.rst
 create mode 100644 Documentation/translations/zh_CN/block/data-integrity.rst
 create mode 100644 Documentation/translations/zh_CN/block/index.rst

--
2.25.1

[PATCH v4 1/3] docs/zh_CN: Add block/index.rst translation

[ke zijie]

Translate .../block/index.rst into Chinese and update subsystem-apis.rst
translation.

Update the translation through commit 56cdea92ed91
("Documentation/block: drop the request.rst file")

Reviewed-by: WangYuli <wangyl5933@chinaunicom.cn>
Signed-off-by: ke zijie <kezijie@leap-io-kernel.com>
---
 .../translations/zh_CN/block/index.rst        | 34 +++++++++++++++++++
 .../translations/zh_CN/subsystem-apis.rst     |  1 -
 2 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/block/index.rst

diff --git a/Documentation/translations/zh_CN/block/index.rst b/Documentation/translations/zh_CN/block/index.rst
new file mode 100644
index 000000000000..1a5b214657dc
--- /dev/null
+++ b/Documentation/translations/zh_CN/block/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/block/index.rst
+
+:翻译:
+
+ 柯子杰 kezijie <kezijie@leap-io-kernel.com>
+
+:校译:
+
+=====
+Block
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+TODOList:
+* bfq-iosched
+* biovecs
+* blk-mq
+* cmdline-partition
+* data-integrity
+* deadline-iosched
+* inline-encryption
+* ioprio
+* kyber-iosched
+* null_blk
+* pr
+* stat
+* switching-sched
+* writeback_cache_control
+* ublk
diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst
index 0f121f9b0f70..830217140fb6 100644
--- a/Documentation/translations/zh_CN/subsystem-apis.rst
+++ b/Documentation/translations/zh_CN/subsystem-apis.rst
@@ -75,7 +75,6 @@ TODOList:

 TODOList:

-* block/index
 * cdrom/index
 * target/index

--
2.25.1

Re: [PATCH v4 1/3] docs/zh_CN: Add block/index.rst translation

[Yanteng Si]

在 2025/11/19 10:38, ke zijie 写道:
> Translate .../block/index.rst into Chinese and update subsystem-apis.rst
> translation.
>
> Update the translation through commit 56cdea92ed91
> ("Documentation/block: drop the request.rst file")
>
> Reviewed-by: WangYuli <wangyl5933@chinaunicom.cn>
> Signed-off-by: ke zijie <kezijie@leap-io-kernel.com>

Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>


Thanks,

Yanteng

> ---
>   .../translations/zh_CN/block/index.rst        | 34 +++++++++++++++++++
>   .../translations/zh_CN/subsystem-apis.rst     |  1 -
>   2 files changed, 34 insertions(+), 1 deletion(-)
>   create mode 100644 Documentation/translations/zh_CN/block/index.rst
>
> diff --git a/Documentation/translations/zh_CN/block/index.rst b/Documentation/translations/zh_CN/block/index.rst
> new file mode 100644
> index 000000000000..1a5b214657dc
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/block/index.rst
> @@ -0,0 +1,34 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/block/index.rst
> +
> +:翻译:
> +
> + 柯子杰 kezijie <kezijie@leap-io-kernel.com>
> +
> +:校译:
> +
> +=====
> +Block
> +=====
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +TODOList:
> +* bfq-iosched
> +* biovecs
> +* blk-mq
> +* cmdline-partition
> +* data-integrity
> +* deadline-iosched
> +* inline-encryption
> +* ioprio
> +* kyber-iosched
> +* null_blk
> +* pr
> +* stat
> +* switching-sched
> +* writeback_cache_control
> +* ublk
> diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst
> index 0f121f9b0f70..830217140fb6 100644
> --- a/Documentation/translations/zh_CN/subsystem-apis.rst
> +++ b/Documentation/translations/zh_CN/subsystem-apis.rst
> @@ -75,7 +75,6 @@ TODOList:
>
>   TODOList:
>
> -* block/index
>   * cdrom/index
>   * target/index
>
> --
> 2.25.1
>
>

[PATCH v4 2/3] docs/zh_CN: Add blk-mq.rst translation

[ke zijie]

Translate .../block/blk-mq.rst into Chinese.
Add blk-mq into .../block/index.rst.

Update the translation through commit 41bd33df4e18
("docs: block: blk-mq.rst: correct places -> place")

Reviewed-by: WangYuli <wangyl5933@chinaunicom.cn>
Signed-off-by: ke zijie <kezijie@leap-io-kernel.com>
---
 .../translations/zh_CN/block/blk-mq.rst       | 130 ++++++++++++++++++
 .../translations/zh_CN/block/index.rst        |   3 +-
 2 files changed, 132 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/zh_CN/block/blk-mq.rst

diff --git a/Documentation/translations/zh_CN/block/blk-mq.rst b/Documentation/translations/zh_CN/block/blk-mq.rst
new file mode 100644
index 000000000000..ccc08f76ff97
--- /dev/null
+++ b/Documentation/translations/zh_CN/block/blk-mq.rst
@@ -0,0 +1,130 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/block/blk-mq.rst
+
+:翻译:
+
+ 柯子杰 kezijie <kezijie@leap-io-kernel.com>
+
+:校译:
+
+
+
+================================================
+多队列块设备 I/O 排队机制 (blk-mq)
+================================================
+
+多队列块设备 I/O 排队机制提供了一组 API，使高速存储设备能够同时在多个队列中
+处理并发的 I/O 请求并将其提交到块设备，从而实现极高的每秒输入/输出操作次数
+(IOPS)，充分发挥现代存储设备的并行能力。
+
+介绍
+====
+
+背景
+----
+
+磁盘从 Linux 内核开发初期就已成为事实上的标准。块 I/O 子系统的目标是尽可能
+为此类设备提供最佳性能，因为它们在进行随机访问时代价极高，性能瓶颈主要在机械
+运动部件上，其速度远低于存储栈中其他任何层。其中一个软件优化例子是根据硬盘磁
+头当前的位置重新排序读/写请求。
+
+然而，随着固态硬盘和非易失性存储的发展，它们没有机械部件，也不存在随机访问代
+码，并能够进行高速并行访问，存储栈的瓶颈从存储设备转移到了操作系统。为了充分
+利用这些设备设计中的并行性，引入了多队列机制。
+
+原来的设计只有一个队列来存储块设备 I/O 请求，并且只使用一个锁。由于缓存中的
+脏数据和多处理器共享单锁的瓶颈，这种设计在 SMP 系统中扩展性不佳。当不同进程
+（或同一进程在不同 CPU 上）同时执行块设备 I/O 时，该单队列模型还会出现严重
+的拥塞问题。为了解决这些问题，blk-mq API 引入了多个队列，每个队列在本地 CPU
+上拥有独立的入口点，从而消除了对全局锁的需求。关于其具体工作机制的更深入说明，
+请参见下一节（ `工作原理`_ ）。
+
+工作原理
+--------
+
+当用户空间执行对块设备的 I/O（例如读写文件）时，blk-mq 便会介入：它将存储和
+管理发送到块设备的 I/O 请求，充当用户空间（文件系统，如果存在的话）与块设备驱
+动之间的中间层。
+
+blk-mq 由两组队列组成：软件暂存队列和硬件派发队列。当请求到达块层时，它会尝
+试最短路径：直接发送到硬件队列。然而，有两种情况下可能不会这样做：如果该层有
+IO 调度器或者是希望合并请求。在这两种情况下，请求将被发送到软件队列。
+
+随后，在软件队列中的请求被处理后，请求会被放置到硬件队列。硬件队列是第二阶段
+的队列，硬件可以直接访问并处理这些请求。然而，如果硬件没有足够的资源来接受更
+多请求，blk-mq 会将请求放置在临时队列中，待硬件资源充足时再发送。
+
+软件暂存队列
+~~~~~~~~~~~~
+
+在这些请求未直接发送到驱动时，块设备 I/O 子系统会将请求添加到软件暂存队列中
+（由 struct blk_mq_ctx 表示）。一个请求可能包含一个或多个 BIO。它们通过 struct bio
+数据结构到达块层。块层随后会基于这些 BIO 构建新的结构体 struct request，用于
+与设备驱动通信。每个队列都有自己的锁，队列数量由每个 CPU 和每个 node 为基础
+来决定。
+
+暂存队列可用于合并相邻扇区的请求。例如，对扇区3-6、6-7、7-9的请求可以合并
+为对扇区3-9的一个请求。即便 SSD 或 NVM 的随机访问和顺序访问响应时间相同，
+合并顺序访问的请求仍可减少单独请求的数量。这种合并请求的技术称为 plugging。
+
+此外，I/O 调度器还可以对请求进行重新排序以确保系统资源的公平性（例如防止某
+个应用出现“饥饿”现象）或是提高 I/O 性能。
+
+I/O 调度器
+^^^^^^^^^^
+
+块层实现了多种调度器，每种调度器都遵循一定启发式规则以提高 I/O 性能。它们是
+“可插拔”的(plug and play)，可在运行时通过 sysfs 选择。你可以在这里阅读更
+多关于 Linux IO 调度器知识 `here
+<https://www.kernel.org/doc/html/latest/block/index.html>`_。调度只发
+生在同一队列内的请求之间，因此无法合并不同队列的请求，否则会造成缓存冲突并需
+要为每个队列加锁。调度后，请求即可发送到硬件。可能选择的调度器之一是 NONE 调
+度器，这是最直接的调度器：它只将请求放到进程所在的软件队列，不进行重新排序。
+当设备开始处理硬件队列中的请求时（运行硬件队列），映射到该硬件队列的软件队列
+会按映射顺序依次清空。
+
+硬件派发队列
+~~~~~~~~~~~~~
+
+硬件队列（由 struct blk_mq_hw_ctx 表示）是设备驱动用来映射设备提交队列
+（或设备 DMA 环缓存）的结构体，它是块层提交路径在底层设备驱动接管请求之前的
+最后一个阶段。运行此队列时，块层会从相关软件队列中取出请求，并尝试派发到硬件。
+
+如果请求无法直接发送到硬件，它们会被加入到请求的链表(``hctx->dispatch``) 中。
+随后，当块层下次运行该队列时，会优先发送位于 ``dispatch`` 链表中的请求，
+以确保那些最早准备好发送的请求能够得到公平调度。硬件队列的数量取决于硬件及
+其设备驱动所支持的硬件上下文数，但不会超过系统的CPU核心数。在这个阶段不
+会发生重新排序，每个软件队列都有一组硬件队列来用于提交请求。
+
+.. note::
+
+        块层和设备协议都不保证请求完成顺序。此问题需由更高层处理，例如文件系统。
+
+基于标识的完成机制
+~~~~~~~~~~~~~~~~~~~
+
+为了指示哪一个请求已经完成，每个请求都会被分配一个整数标识，该标识的取值范围
+是从0到分发队列的大小。这个标识由块层生成，并在之后由设备驱动使用，从而避
+免了为每个请求再单独创建冗余的标识符。当请求在驱动中完成时，驱动会将该标识返
+回给块层，以通知该请求已完成。这样，块层就无需再进行线性搜索来确定是哪一个
+I/O 请求完成了。
+
+更多阅读
+--------
+
+- `Linux 块 I/O：多队列 SSD 并发访问简介 <http://kernel.dk/blk-mq.pdf>`_
+
+- `NOOP 调度器 <https://en.wikipedia.org/wiki/Noop_scheduler>`_
+
+- `Null 块设备驱动程序 <https://www.kernel.org/doc/html/latest/block/null_blk.html>`_
+
+源代码
+======
+
+该API在以下内核代码中:
+
+include/linux/blk-mq.h
+
+block/blk-mq.c
\ No newline at end of file
diff --git a/Documentation/translations/zh_CN/block/index.rst b/Documentation/translations/zh_CN/block/index.rst
index 1a5b214657dc..442ee1025b36 100644
--- a/Documentation/translations/zh_CN/block/index.rst
+++ b/Documentation/translations/zh_CN/block/index.rst
@@ -16,10 +16,11 @@ Block
 .. toctree::
    :maxdepth: 1

+   blk-mq
+
 TODOList:
 * bfq-iosched
 * biovecs
-* blk-mq
 * cmdline-partition
 * data-integrity
 * deadline-iosched
--
2.25.1

Re: [PATCH v4 2/3] docs/zh_CN: Add blk-mq.rst translation

[Yanteng Si]

在 2025/11/19 10:38, ke zijie 写道:
> Translate .../block/blk-mq.rst into Chinese.
> Add blk-mq into .../block/index.rst.
>
> Update the translation through commit 41bd33df4e18
> ("docs: block: blk-mq.rst: correct places -> place")
>
> Reviewed-by: WangYuli <wangyl5933@chinaunicom.cn>
> Signed-off-by: ke zijie <kezijie@leap-io-kernel.com>
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>


Thanks,

Yanteng
> ---
>   .../translations/zh_CN/block/blk-mq.rst       | 130 ++++++++++++++++++
>   .../translations/zh_CN/block/index.rst        |   3 +-
>   2 files changed, 132 insertions(+), 1 deletion(-)
>   create mode 100644 Documentation/translations/zh_CN/block/blk-mq.rst
>
> diff --git a/Documentation/translations/zh_CN/block/blk-mq.rst b/Documentation/translations/zh_CN/block/blk-mq.rst
> new file mode 100644
> index 000000000000..ccc08f76ff97
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/block/blk-mq.rst
> @@ -0,0 +1,130 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/block/blk-mq.rst
> +
> +:翻译:
> +
> + 柯子杰 kezijie <kezijie@leap-io-kernel.com>
> +
> +:校译:
> +
> +
> +
> +================================================
> +多队列块设备 I/O 排队机制 (blk-mq)
> +================================================
> +
> +多队列块设备 I/O 排队机制提供了一组 API，使高速存储设备能够同时在多个队列中
> +处理并发的 I/O 请求并将其提交到块设备，从而实现极高的每秒输入/输出操作次数
> +(IOPS)，充分发挥现代存储设备的并行能力。
> +
> +介绍
> +====
> +
> +背景
> +----
> +
> +磁盘从 Linux 内核开发初期就已成为事实上的标准。块 I/O 子系统的目标是尽可能
> +为此类设备提供最佳性能，因为它们在进行随机访问时代价极高，性能瓶颈主要在机械
> +运动部件上，其速度远低于存储栈中其他任何层。其中一个软件优化例子是根据硬盘磁
> +头当前的位置重新排序读/写请求。
> +
> +然而，随着固态硬盘和非易失性存储的发展，它们没有机械部件，也不存在随机访问代
> +码，并能够进行高速并行访问，存储栈的瓶颈从存储设备转移到了操作系统。为了充分
> +利用这些设备设计中的并行性，引入了多队列机制。
> +
> +原来的设计只有一个队列来存储块设备 I/O 请求，并且只使用一个锁。由于缓存中的
> +脏数据和多处理器共享单锁的瓶颈，这种设计在 SMP 系统中扩展性不佳。当不同进程
> +（或同一进程在不同 CPU 上）同时执行块设备 I/O 时，该单队列模型还会出现严重
> +的拥塞问题。为了解决这些问题，blk-mq API 引入了多个队列，每个队列在本地 CPU
> +上拥有独立的入口点，从而消除了对全局锁的需求。关于其具体工作机制的更深入说明，
> +请参见下一节（ `工作原理`_ ）。
> +
> +工作原理
> +--------
> +
> +当用户空间执行对块设备的 I/O（例如读写文件）时，blk-mq 便会介入：它将存储和
> +管理发送到块设备的 I/O 请求，充当用户空间（文件系统，如果存在的话）与块设备驱
> +动之间的中间层。
> +
> +blk-mq 由两组队列组成：软件暂存队列和硬件派发队列。当请求到达块层时，它会尝
> +试最短路径：直接发送到硬件队列。然而，有两种情况下可能不会这样做：如果该层有
> +IO 调度器或者是希望合并请求。在这两种情况下，请求将被发送到软件队列。
> +
> +随后，在软件队列中的请求被处理后，请求会被放置到硬件队列。硬件队列是第二阶段
> +的队列，硬件可以直接访问并处理这些请求。然而，如果硬件没有足够的资源来接受更
> +多请求，blk-mq 会将请求放置在临时队列中，待硬件资源充足时再发送。
> +
> +软件暂存队列
> +~~~~~~~~~~~~
> +
> +在这些请求未直接发送到驱动时，块设备 I/O 子系统会将请求添加到软件暂存队列中
> +（由 struct blk_mq_ctx 表示）。一个请求可能包含一个或多个 BIO。它们通过 struct bio
> +数据结构到达块层。块层随后会基于这些 BIO 构建新的结构体 struct request，用于
> +与设备驱动通信。每个队列都有自己的锁，队列数量由每个 CPU 和每个 node 为基础
> +来决定。
> +
> +暂存队列可用于合并相邻扇区的请求。例如，对扇区3-6、6-7、7-9的请求可以合并
> +为对扇区3-9的一个请求。即便 SSD 或 NVM 的随机访问和顺序访问响应时间相同，
> +合并顺序访问的请求仍可减少单独请求的数量。这种合并请求的技术称为 plugging。
> +
> +此外，I/O 调度器还可以对请求进行重新排序以确保系统资源的公平性（例如防止某
> +个应用出现“饥饿”现象）或是提高 I/O 性能。
> +
> +I/O 调度器
> +^^^^^^^^^^
> +
> +块层实现了多种调度器，每种调度器都遵循一定启发式规则以提高 I/O 性能。它们是
> +“可插拔”的(plug and play)，可在运行时通过 sysfs 选择。你可以在这里阅读更
> +多关于 Linux IO 调度器知识 `here
> +<https://www.kernel.org/doc/html/latest/block/index.html>`_。调度只发
> +生在同一队列内的请求之间，因此无法合并不同队列的请求，否则会造成缓存冲突并需
> +要为每个队列加锁。调度后，请求即可发送到硬件。可能选择的调度器之一是 NONE 调
> +度器，这是最直接的调度器：它只将请求放到进程所在的软件队列，不进行重新排序。
> +当设备开始处理硬件队列中的请求时（运行硬件队列），映射到该硬件队列的软件队列
> +会按映射顺序依次清空。
> +
> +硬件派发队列
> +~~~~~~~~~~~~~
> +
> +硬件队列（由 struct blk_mq_hw_ctx 表示）是设备驱动用来映射设备提交队列
> +（或设备 DMA 环缓存）的结构体，它是块层提交路径在底层设备驱动接管请求之前的
> +最后一个阶段。运行此队列时，块层会从相关软件队列中取出请求，并尝试派发到硬件。
> +
> +如果请求无法直接发送到硬件，它们会被加入到请求的链表(``hctx->dispatch``) 中。
> +随后，当块层下次运行该队列时，会优先发送位于 ``dispatch`` 链表中的请求，
> +以确保那些最早准备好发送的请求能够得到公平调度。硬件队列的数量取决于硬件及
> +其设备驱动所支持的硬件上下文数，但不会超过系统的CPU核心数。在这个阶段不
> +会发生重新排序，每个软件队列都有一组硬件队列来用于提交请求。
> +
> +.. note::
> +
> +        块层和设备协议都不保证请求完成顺序。此问题需由更高层处理，例如文件系统。
> +
> +基于标识的完成机制
> +~~~~~~~~~~~~~~~~~~~
> +
> +为了指示哪一个请求已经完成，每个请求都会被分配一个整数标识，该标识的取值范围
> +是从0到分发队列的大小。这个标识由块层生成，并在之后由设备驱动使用，从而避
> +免了为每个请求再单独创建冗余的标识符。当请求在驱动中完成时，驱动会将该标识返
> +回给块层，以通知该请求已完成。这样，块层就无需再进行线性搜索来确定是哪一个
> +I/O 请求完成了。
> +
> +更多阅读
> +--------
> +
> +- `Linux 块 I/O：多队列 SSD 并发访问简介 <http://kernel.dk/blk-mq.pdf>`_
> +
> +- `NOOP 调度器 <https://en.wikipedia.org/wiki/Noop_scheduler>`_
> +
> +- `Null 块设备驱动程序 <https://www.kernel.org/doc/html/latest/block/null_blk.html>`_
> +
> +源代码
> +======
> +
> +该API在以下内核代码中:
> +
> +include/linux/blk-mq.h
> +
> +block/blk-mq.c
> \ No newline at end of file
> diff --git a/Documentation/translations/zh_CN/block/index.rst b/Documentation/translations/zh_CN/block/index.rst
> index 1a5b214657dc..442ee1025b36 100644
> --- a/Documentation/translations/zh_CN/block/index.rst
> +++ b/Documentation/translations/zh_CN/block/index.rst
> @@ -16,10 +16,11 @@ Block
>   .. toctree::
>      :maxdepth: 1
>
> +   blk-mq
> +
>   TODOList:
>   * bfq-iosched
>   * biovecs
> -* blk-mq
>   * cmdline-partition
>   * data-integrity
>   * deadline-iosched
> --
> 2.25.1
>
>

[PATCH v4 3/3] docs/zh_CN: Add data-integrity.rst translation

[ke zijie]

Translate .../block/data-integrity.rst into Chinese.
Add data-integrity into .../block/index.rst.

Update the translation through commit c6e56cf6b2e7
("block: move integrity information into queue_limits")

Reviewed-by: WangYuli <wangyl5933@chinaunicom.cn>
Signed-off-by: ke zijie <kezijie@leap-io-kernel.com>
---
 .../zh_CN/block/data-integrity.rst            | 193 ++++++++++++++++++
 1 file changed, 193 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/block/data-integrity.rst

diff --git a/Documentation/translations/zh_CN/block/data-integrity.rst b/Documentation/translations/zh_CN/block/data-integrity.rst
new file mode 100644
index 000000000000..4d7768cd7e98
--- /dev/null
+++ b/Documentation/translations/zh_CN/block/data-integrity.rst
@@ -0,0 +1,193 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/block/data-integrity.rst
+
+:翻译:
+
+ 柯子杰 kezijie <kezijie@leap-io-kernel.com>
+
+:校译:
+
+
+==========
+数据完整性
+==========
+
+1. 引言
+=======
+
+现代文件系统对数据和元数据都进行了校验和保护以防止数据损坏。然而，这种损坏的
+检测是在读取时才进行，这可能发生在数据写入数月之后。到那时，应用程序尝试写入
+的原始数据很可能已经丢失。
+
+解决方案是确保磁盘实际存储的内容就是应用程序想存储的。SCSI 协议族（如 SBC
+数据完整性字段、SCC 保护提案）以及 SATA/T13（外部路径保护）最近新增的功能，
+通过在 I/O 中附加完整性元数据的方式，试图解决这一问题。完整性元数据（在
+SCSI 术语中称为保护信息）包括每个扇区的校验和，以及一个递增计数器，用于确保
+各扇区按正确顺序被写入盘。在某些保护方案中，还能保证 I/O 写入磁盘的正确位置。
+
+当前的存储控制器和设备实现了多种保护措施，例如校验和和数据清理。但这些技术通
+常只在各自的独立域内工作，或最多仅在 I/O 路径的相邻节点之间发挥作用。DIF 及
+其它数据完整性拓展有意思的点在于保护格式定义明确，I/O 路径上的每个节点都可以
+验证 I/O 的完整性，如检测到损坏可直接拒绝。这不仅可以防止数据损坏，还能够隔
+离故障点。
+
+2. 数据完整性拓展
+=================
+
+如上所述，这些协议扩展只保护控制器与存储设备之间的路径。然而，许多控制器实际
+上允许操作系统与完整性元数据(IMD)交互。我们一直与多家 FC/SAS HBA 厂商合作，
+使保护信息能够在其控制器与操作系统之间传输。
+
+SCSI 数据完整性字段通过在每个扇区后附加8字节的保护信息来实现。数据 + 完整
+性元数据存储在磁盘的520字节扇区中。数据 + IMD 在控制器与目标设备之间传输
+时是交错组合在一起的。T13 提案的方式类似。
+
+由于操作系统处理520字节（甚至 4104 字节）扇区非常不便，我们联系了多家 HBA
+厂商，并鼓励它们分离数据与完整性元数据的 scatter-gather lists。
+
+控制器在写入时会将数据缓冲区和完整性元数据缓冲区的数据交错在一起，并在读取时
+会拆分它们。这样，Linux 就能直接通过 DMA 将数据缓冲区传输到主机内存或从主机
+内存读取，而无需修改页缓存。
+
+此外，SCSI 与 SATA 规范要求的16位 CRC 校验在软件中计算代价较高。基准测试发
+现，计算此校验在高负载情形下显著影响系统性能。一些控制器允许在操作系统接口处
+使用轻量级校验。例如 Emulex 支持 TCP/IP 校验。操作系统提供的 IP 校验在写入
+时会转换为16位 CRC，读取时则相反。这允许 Linux 或应用程序以极低的开销生成
+完整性元数据（与软件 RAID5 相当）。
+
+IP 校验在检测位错误方面比 CRC 弱，但关键在于数据缓冲区与完整性元数据缓冲区
+的分离。只有这两个不同的缓冲区匹配，I/O 才能完成。
+
+数据与完整性元数据缓冲区的分离以及校验选择被称为数据完整性扩展。由于这些扩展
+超出了协议主体(T10、T13)的范围，Oracle 及其合作伙伴正尝试在存储网络行业协
+会内对其进行标准化。
+
+3. 内核变更
+===========
+
+Linux 中的数据完整性框架允许将保护信息固定到 I/O 上，并在支持该功能的控制器
+之间发送和接收。
+
+SCSI 和 SATA 中完整性扩展的优势在于，它们能够保护从应用程序到存储设备的整个
+路径。然而，这同时也是最大的劣势。这意味着保护信息必须采用磁盘可以理解的格式。
+
+通常，Linux/POSIX 应用程序并不关心所访问存储设备的具体细节。虚拟文件系统层
+和块层会让硬件扇区大小和传输协议对应用程序完全透明。
+
+然而，在准备发送到磁盘的保护信息时，就需要这种细节。因此，端到端保护方案的概
+念实际上违反了层次结构。应用程序完全不应该知道它访问的是 SCSI 还是 SATA 磁盘。
+
+Linux 中实现的数据完整性支持尝试将这些细节对应用程序隐藏。就应用程序（以及在
+某种程度上内核）而言，完整性元数据是附加在 I/O 上的不透明信息。
+
+当前实现允许块层自动为任何 I/O 生成保护信息。最终目标是将用户数据的完整性元
+数据计算移至用户空间。内核中产生的元数据和其他 I/O 仍将使用自动生成接口。
+
+一些存储设备允许为每个硬件扇区附加一个16位的标识值。这个标识空间的所有者是
+块设备的所有者，也就是在多数情况下由文件系统掌控。文件系统可以利用这额外空间
+按需为扇区附加标识。由于标识空间有限，块接口允许通过交错方式对更大的数据块标
+识。这样，8*16位的信息可以附加到典型的 4KB 文件系统块上。
+
+这也意味着诸如 fsck 和 mkfs 等应用程序需要能够从用户空间访问并操作这些标记。
+为此，正在开发一个透传接口。
+
+4. 块层实现细节
+===============
+
+4.1 Bio
+--------
+
+当启用 CONFIG_BLK_DEV_INTEGRITY 时，数据完整性补丁会在 struct bio 中添加
+一个新字段。调用 bio_integrity(bio) 会返回一个指向 struct bip 的指针，该
+结构体包含了该 bio 的完整性负载。本质上，bip 是一个精简版的 struct bio，其
+中包含一个 bio_vec，用于保存完整性元数据以及所需的维护信息（bvec 池、向量计
+数等）。
+
+内核子系统可以通过调用 bio_integrity_alloc(bio) 来为某个 bio 启用数据完整
+性保护。该函数会分配并附加一个 bip 到该 bio 上。
+
+随后使用 bio_integrity_add_page() 将包含完整性元数据的单独页面附加到该 bio。
+
+调用 bio_free() 会自动释放bip。
+
+4.2 块设备
+-----------
+
+块设备可以在 queue_limits 结构中的 integrity 子结构中设置完整性信息。
+
+对于分层块设备，需要选择一个适用于所有子设备的完整性配置文件。可以使用
+queue_limits_stack_integrity() 来协助完成该操作。目前，DM 和 MD linear、
+RAID0 和 RAID1 已受支持。而RAID4/5/6因涉及应用标签仍需额外的开发工作。
+
+5.0 块层完整性API
+==================
+
+5.1 普通文件系统
+-----------------
+
+    普通文件系统并不知道其下层块设备具备发送或接收完整性元数据的能力。
+    在执行写操作时，块层会在调用 submit_bio() 时自动生成完整性元数据。
+    在执行读操作时，I/O 完成后会触发完整性验证。
+
+    IMD 的生成与验证行为可以通过以下开关控制::
+
+      /sys/block/<bdev>/integrity/write_generate
+
+    and::
+
+      /sys/block/<bdev>/integrity/read_verify
+
+    flags.
+
+5.2 具备完整性感知的文件系统
+----------------------------
+
+    具备完整性感知能力的文件系统可以在准备 I/O 时附加完整性元数据，
+    并且如果底层块设备支持应用标签空间，也可以加以利用。
+
+
+    `bool bio_integrity_prep(bio);`
+
+      要为写操作生成完整性元数据或为读操作设置缓冲区，文件系统必须调用
+      bio_integrity_prep(bio)。
+
+      在调用此函数之前，必须先设置好 bio 的数据方向和起始扇区，并确
+      保该 bio 已经添加完所有的数据页。调用者需要自行保证，在 I/O 进行
+      期间 bio 不会被修改。如果由于某种原因准备失败，则应当以错误状态
+      完成该 bio。
+
+5.3 传递已有的完整性元数据
+--------------------------
+
+    能够自行生成完整性元数据或可以从用户空间传输完整性元数据的文件系统，
+    可以使用如下接口：
+
+
+    `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`
+
+      为 bio 分配完整性负载并挂载到 bio 上。nr_pages 表示需要在
+      integrity bio_vec list 中存储多少页保护数据（类似 bio_alloc）。
+
+      完整性负载将在 bio_free() 被调用时释放。
+
+
+    `int bio_integrity_add_page(bio, page, len, offset);`
+
+      将包含完整性元数据的一页附加到已有的 bio 上。该 bio 必须已有 bip，
+      即必须先调用 bio_integrity_alloc()。对于写操作，页中的完整
+      性元数据必须采用目标设备可识别的格式，但有一个例外，当请求在 I/O 栈
+      中传递时，扇区号会被重新映射。这意味着通过此接口添加的页在 I/O 过程
+      中可能会被修改！完整性元数据中的第一个引用标签必须等于 bip->bip_sector。
+
+      只要 bip bio_vec array（nr_pages）有空间，就可以继续通过
+      bio_integrity_add_page()添加页。
+
+      当读操作完成后，附加的页将包含从存储设备接收到的完整性元数据。
+      接收方需要处理这些元数据，并在操作完成时验证数据完整性
+
+
+----------------------------------------------------------------------
+
+2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>
\ No newline at end of file
--
2.25.1

Re: [PATCH v4 3/3] docs/zh_CN: Add data-integrity.rst translation

[Yanteng Si]

在 2025/11/19 10:38, ke zijie 写道:
> Translate .../block/data-integrity.rst into Chinese.
> Add data-integrity into .../block/index.rst.
>
> Update the translation through commit c6e56cf6b2e7
> ("block: move integrity information into queue_limits")
>
> Reviewed-by: WangYuli <wangyl5933@chinaunicom.cn>
> Signed-off-by: ke zijie <kezijie@leap-io-kernel.com>
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn>


Thanks,

Yanteng
> ---
>   .../zh_CN/block/data-integrity.rst            | 193 ++++++++++++++++++
>   1 file changed, 193 insertions(+)
>   create mode 100644 Documentation/translations/zh_CN/block/data-integrity.rst
>
> diff --git a/Documentation/translations/zh_CN/block/data-integrity.rst b/Documentation/translations/zh_CN/block/data-integrity.rst
> new file mode 100644
> index 000000000000..4d7768cd7e98
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/block/data-integrity.rst
> @@ -0,0 +1,193 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/block/data-integrity.rst
> +
> +:翻译:
> +
> + 柯子杰 kezijie <kezijie@leap-io-kernel.com>
> +
> +:校译:
> +
> +
> +==========
> +数据完整性
> +==========
> +
> +1. 引言
> +=======
> +
> +现代文件系统对数据和元数据都进行了校验和保护以防止数据损坏。然而，这种损坏的
> +检测是在读取时才进行，这可能发生在数据写入数月之后。到那时，应用程序尝试写入
> +的原始数据很可能已经丢失。
> +
> +解决方案是确保磁盘实际存储的内容就是应用程序想存储的。SCSI 协议族（如 SBC
> +数据完整性字段、SCC 保护提案）以及 SATA/T13（外部路径保护）最近新增的功能，
> +通过在 I/O 中附加完整性元数据的方式，试图解决这一问题。完整性元数据（在
> +SCSI 术语中称为保护信息）包括每个扇区的校验和，以及一个递增计数器，用于确保
> +各扇区按正确顺序被写入盘。在某些保护方案中，还能保证 I/O 写入磁盘的正确位置。
> +
> +当前的存储控制器和设备实现了多种保护措施，例如校验和和数据清理。但这些技术通
> +常只在各自的独立域内工作，或最多仅在 I/O 路径的相邻节点之间发挥作用。DIF 及
> +其它数据完整性拓展有意思的点在于保护格式定义明确，I/O 路径上的每个节点都可以
> +验证 I/O 的完整性，如检测到损坏可直接拒绝。这不仅可以防止数据损坏，还能够隔
> +离故障点。
> +
> +2. 数据完整性拓展
> +=================
> +
> +如上所述，这些协议扩展只保护控制器与存储设备之间的路径。然而，许多控制器实际
> +上允许操作系统与完整性元数据(IMD)交互。我们一直与多家 FC/SAS HBA 厂商合作，
> +使保护信息能够在其控制器与操作系统之间传输。
> +
> +SCSI 数据完整性字段通过在每个扇区后附加8字节的保护信息来实现。数据 + 完整
> +性元数据存储在磁盘的520字节扇区中。数据 + IMD 在控制器与目标设备之间传输
> +时是交错组合在一起的。T13 提案的方式类似。
> +
> +由于操作系统处理520字节（甚至 4104 字节）扇区非常不便，我们联系了多家 HBA
> +厂商，并鼓励它们分离数据与完整性元数据的 scatter-gather lists。
> +
> +控制器在写入时会将数据缓冲区和完整性元数据缓冲区的数据交错在一起，并在读取时
> +会拆分它们。这样，Linux 就能直接通过 DMA 将数据缓冲区传输到主机内存或从主机
> +内存读取，而无需修改页缓存。
> +
> +此外，SCSI 与 SATA 规范要求的16位 CRC 校验在软件中计算代价较高。基准测试发
> +现，计算此校验在高负载情形下显著影响系统性能。一些控制器允许在操作系统接口处
> +使用轻量级校验。例如 Emulex 支持 TCP/IP 校验。操作系统提供的 IP 校验在写入
> +时会转换为16位 CRC，读取时则相反。这允许 Linux 或应用程序以极低的开销生成
> +完整性元数据（与软件 RAID5 相当）。
> +
> +IP 校验在检测位错误方面比 CRC 弱，但关键在于数据缓冲区与完整性元数据缓冲区
> +的分离。只有这两个不同的缓冲区匹配，I/O 才能完成。
> +
> +数据与完整性元数据缓冲区的分离以及校验选择被称为数据完整性扩展。由于这些扩展
> +超出了协议主体(T10、T13)的范围，Oracle 及其合作伙伴正尝试在存储网络行业协
> +会内对其进行标准化。
> +
> +3. 内核变更
> +===========
> +
> +Linux 中的数据完整性框架允许将保护信息固定到 I/O 上，并在支持该功能的控制器
> +之间发送和接收。
> +
> +SCSI 和 SATA 中完整性扩展的优势在于，它们能够保护从应用程序到存储设备的整个
> +路径。然而，这同时也是最大的劣势。这意味着保护信息必须采用磁盘可以理解的格式。
> +
> +通常，Linux/POSIX 应用程序并不关心所访问存储设备的具体细节。虚拟文件系统层
> +和块层会让硬件扇区大小和传输协议对应用程序完全透明。
> +
> +然而，在准备发送到磁盘的保护信息时，就需要这种细节。因此，端到端保护方案的概
> +念实际上违反了层次结构。应用程序完全不应该知道它访问的是 SCSI 还是 SATA 磁盘。
> +
> +Linux 中实现的数据完整性支持尝试将这些细节对应用程序隐藏。就应用程序（以及在
> +某种程度上内核）而言，完整性元数据是附加在 I/O 上的不透明信息。
> +
> +当前实现允许块层自动为任何 I/O 生成保护信息。最终目标是将用户数据的完整性元
> +数据计算移至用户空间。内核中产生的元数据和其他 I/O 仍将使用自动生成接口。
> +
> +一些存储设备允许为每个硬件扇区附加一个16位的标识值。这个标识空间的所有者是
> +块设备的所有者，也就是在多数情况下由文件系统掌控。文件系统可以利用这额外空间
> +按需为扇区附加标识。由于标识空间有限，块接口允许通过交错方式对更大的数据块标
> +识。这样，8*16位的信息可以附加到典型的 4KB 文件系统块上。
> +
> +这也意味着诸如 fsck 和 mkfs 等应用程序需要能够从用户空间访问并操作这些标记。
> +为此，正在开发一个透传接口。
> +
> +4. 块层实现细节
> +===============
> +
> +4.1 Bio
> +--------
> +
> +当启用 CONFIG_BLK_DEV_INTEGRITY 时，数据完整性补丁会在 struct bio 中添加
> +一个新字段。调用 bio_integrity(bio) 会返回一个指向 struct bip 的指针，该
> +结构体包含了该 bio 的完整性负载。本质上，bip 是一个精简版的 struct bio，其
> +中包含一个 bio_vec，用于保存完整性元数据以及所需的维护信息（bvec 池、向量计
> +数等）。
> +
> +内核子系统可以通过调用 bio_integrity_alloc(bio) 来为某个 bio 启用数据完整
> +性保护。该函数会分配并附加一个 bip 到该 bio 上。
> +
> +随后使用 bio_integrity_add_page() 将包含完整性元数据的单独页面附加到该 bio。
> +
> +调用 bio_free() 会自动释放bip。
> +
> +4.2 块设备
> +-----------
> +
> +块设备可以在 queue_limits 结构中的 integrity 子结构中设置完整性信息。
> +
> +对于分层块设备，需要选择一个适用于所有子设备的完整性配置文件。可以使用
> +queue_limits_stack_integrity() 来协助完成该操作。目前，DM 和 MD linear、
> +RAID0 和 RAID1 已受支持。而RAID4/5/6因涉及应用标签仍需额外的开发工作。
> +
> +5.0 块层完整性API
> +==================
> +
> +5.1 普通文件系统
> +-----------------
> +
> +    普通文件系统并不知道其下层块设备具备发送或接收完整性元数据的能力。
> +    在执行写操作时，块层会在调用 submit_bio() 时自动生成完整性元数据。
> +    在执行读操作时，I/O 完成后会触发完整性验证。
> +
> +    IMD 的生成与验证行为可以通过以下开关控制::
> +
> +      /sys/block/<bdev>/integrity/write_generate
> +
> +    and::
> +
> +      /sys/block/<bdev>/integrity/read_verify
> +
> +    flags.
> +
> +5.2 具备完整性感知的文件系统
> +----------------------------
> +
> +    具备完整性感知能力的文件系统可以在准备 I/O 时附加完整性元数据，
> +    并且如果底层块设备支持应用标签空间，也可以加以利用。
> +
> +
> +    `bool bio_integrity_prep(bio);`
> +
> +      要为写操作生成完整性元数据或为读操作设置缓冲区，文件系统必须调用
> +      bio_integrity_prep(bio)。
> +
> +      在调用此函数之前，必须先设置好 bio 的数据方向和起始扇区，并确
> +      保该 bio 已经添加完所有的数据页。调用者需要自行保证，在 I/O 进行
> +      期间 bio 不会被修改。如果由于某种原因准备失败，则应当以错误状态
> +      完成该 bio。
> +
> +5.3 传递已有的完整性元数据
> +--------------------------
> +
> +    能够自行生成完整性元数据或可以从用户空间传输完整性元数据的文件系统，
> +    可以使用如下接口：
> +
> +
> +    `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);`
> +
> +      为 bio 分配完整性负载并挂载到 bio 上。nr_pages 表示需要在
> +      integrity bio_vec list 中存储多少页保护数据（类似 bio_alloc）。
> +
> +      完整性负载将在 bio_free() 被调用时释放。
> +
> +
> +    `int bio_integrity_add_page(bio, page, len, offset);`
> +
> +      将包含完整性元数据的一页附加到已有的 bio 上。该 bio 必须已有 bip，
> +      即必须先调用 bio_integrity_alloc()。对于写操作，页中的完整
> +      性元数据必须采用目标设备可识别的格式，但有一个例外，当请求在 I/O 栈
> +      中传递时，扇区号会被重新映射。这意味着通过此接口添加的页在 I/O 过程
> +      中可能会被修改！完整性元数据中的第一个引用标签必须等于 bip->bip_sector。
> +
> +      只要 bip bio_vec array（nr_pages）有空间，就可以继续通过
> +      bio_integrity_add_page()添加页。
> +
> +      当读操作完成后，附加的页将包含从存储设备接收到的完整性元数据。
> +      接收方需要处理这些元数据，并在操作完成时验证数据完整性
> +
> +
> +----------------------------------------------------------------------
> +
> +2007-12-24 Martin K. Petersen <martin.petersen@oracle.com>
> \ No newline at end of file
> --
> 2.25.1
>