* [PATCH v5 1/7] Docs/zh_CN: Translate ubifs.rst to Simplified Chinese
2025-09-17 3:50 [PATCH v5 0/7] Docs/zh_CN: Translate filesystems docs to Simplified Chinese shao.mingyin
@ 2025-09-17 3:53 ` shao.mingyin
2025-09-17 3:54 ` [PATCH v5 2/7] Docs/zh_CN: Translate ubifs-authentication.rst " shao.mingyin
` (5 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: shao.mingyin @ 2025-09-17 3:53 UTC (permalink / raw)
To: shao.mingyin
Cc: alexs, si.yanteng, dzm91, corbet, linux-doc, linux-kernel,
yang.yang29, xu.xin16, yang.tao172, wang.longjie1
From: Shao Mingyin <shao.mingyin@zte.com.cn>
translate the "ubifs.rst" into Simplified Chinese.
Update to commit 5f5cae9b0e81("Documentation: ubifs: Fix
compression idiom")
Signed-off-by: Shao Mingyin <shao.mingyin@zte.com.cn>
Signed-off-by: yang tao <yang.tao172@zte.com.cn>
---
v4->v5
fix some format issues.
.../translations/zh_CN/filesystems/index.rst | 2 +-
.../translations/zh_CN/filesystems/ubifs.rst | 114 ++++++++++++++++++
2 files changed, 115 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/filesystems/ubifs.rst
diff --git a/Documentation/translations/zh_CN/filesystems/index.rst b/Documentation/translations/zh_CN/filesystems/index.rst
index 9f2a8b003778..6049b599dec8 100644
--- a/Documentation/translations/zh_CN/filesystems/index.rst
+++ b/Documentation/translations/zh_CN/filesystems/index.rst
@@ -26,4 +26,4 @@ Linux Kernel中的文件系统
virtiofs
debugfs
tmpfs
-
+ ubifs
diff --git a/Documentation/translations/zh_CN/filesystems/ubifs.rst b/Documentation/translations/zh_CN/filesystems/ubifs.rst
new file mode 100644
index 000000000000..16c28bfd6fc3
--- /dev/null
+++ b/Documentation/translations/zh_CN/filesystems/ubifs.rst
@@ -0,0 +1,114 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/filesystems/ubifs.rst
+
+:翻译:
+
+ 邵明寅 Shao Mingyin <shao.mingyin@zte.com.cn>
+
+:校译:
+
+ - 杨涛 yang tao <yang.tao172@zte.com.cn>
+
+============
+UBI 文件系统
+============
+
+简介
+====
+
+UBIFS 文件系统全称为 UBI 文件系统（UBI File System）。UBI 代表无序块镜
+像（Unsorted Block Images）。UBIFS 是一种闪存文件系统，这意味着它专为闪
+存设备设计。需要理解的是，UBIFS与 Linux 中任何传统文件系统（如 Ext2、
+XFS、JFS 等）完全不同。UBIFS 代表一类特殊的文件系统，它们工作在 MTD 设备
+而非块设备上。该类别的另一个 Linux 文件系统是 JFFS2。
+
+为更清晰说明，以下是 MTD 设备与块设备的简要比较：
+
+1. MTD 设备代表闪存设备，由较大尺寸的擦除块组成，通常约 128KiB。块设备由
+ 小块组成，通常 512 字节。
+2. MTD 设备支持 3 种主要操作：在擦除块内偏移位置读取、在擦除块内偏移位置写
+ 入、以及擦除整个擦除块。块设备支持 2 种主要操作：读取整个块和写入整个块。
+3. 整个擦除块必须先擦除才能重写内容。块可直接重写。
+4. 擦除块在经历一定次数的擦写周期后会磨损，通常 SLC NAND 和 NOR 闪存为
+ 100K-1G 次，MLC NAND 闪存为 1K-10K 次。块设备不具备磨损特性。
+5. 擦除块可能损坏（仅限 NAND 闪存），软件需处理此问题。硬盘上的块通常不会损
+ 坏，因为硬件有坏块替换机制（至少现代 LBA 硬盘如此）。
+
+这充分说明了 UBIFS 与传统文件系统的本质差异。
+
+UBIFS 工作在 UBI 层之上。UBI 是一个独立的软件层（位于 drivers/mtd/ubi），
+本质上是卷管理和磨损均衡层。它提供称为 UBI 卷的高级抽象，比 MTD 设备更上层。
+UBI 设备的编程模型与 MTD 设备非常相似，仍由大容量擦除块组成，支持读/写/擦
+除操作，但 UBI 设备消除了磨损和坏块限制（上述列表的第 4 和第 5 项）。
+
+某种意义上，UBIFS 是 JFFS2 文件系统的下一代产品，但它与 JFFS2 差异巨大且
+不兼容。主要区别如下：
+
+* JFFS2 工作在 MTD 设备之上，UBIFS 依赖于 UBI 并工作在 UBI 卷之上。
+* JFFS2 没有介质索引，需在挂载时构建索引，这要求全介质扫描。UBIFS 在闪存
+ 介质上维护文件系统索引信息，无需全介质扫描，因此挂载速度远快于 JFFS2。
+* JFFS2 是直写（write-through）文件系统，而 UBIFS 支持回写
+ （write-back），这使得 UBIFS 写入速度快得多。
+
+与 JFFS2 类似，UBIFS 支持实时压缩，可将大量数据存入闪存。
+
+与 JFFS2 类似，UBIFS 能容忍异常重启和断电。它不需要类似 fsck.ext2 的工
+具。UBIFS 会自动重放日志并从崩溃中恢复，确保闪存数据结构的一致性。
+
+UBIFS 具有对数级扩展性（其使用的数据结构多为树形），因此挂载时间和内存消耗不
+像 JFFS2 那样线性依赖于闪存容量。这是因为 UBIFS 在闪存介质上维护文件系统
+索引。但 UBIFS 依赖于线性扩展的 UBI 层，因此整体 UBI/UBIFS 栈仍是线性扩
+展。尽管如此，UBIFS/UBI 的扩展性仍显著优于 JFFS2。
+
+UBIFS 开发者认为，未来可开发同样具备对数级扩展性的 UBI2。UBI2 将支持与
+UBI 相同的 API，但二进制不兼容。因此 UBIFS 无需修改即可使用 UBI2。
+
+挂载选项
+========
+
+(*) 表示默认选项。
+
+==================== =======================================================
+bulk_read 批量读取以利用闪存介质的顺序读取加速特性
+no_bulk_read (*) 禁用批量读取
+no_chk_data_crc (*) 跳过数据节点的 CRC 校验以提高读取性能。 仅在闪存
+ 介质高度可靠时使用此选项。 此选项可能导致文件内容损坏无法被
+ 察觉。
+chk_data_crc 强制校验数据节点的 CRC
+compr=none 覆盖默认压缩器，设置为"none"
+compr=lzo 覆盖默认压缩器，设置为"LZO"
+compr=zlib 覆盖默认压缩器，设置为"zlib"
+auth_key= 指定用于文件系统身份验证的密钥。
+ 使用此选项将强制启用身份验证。
+ 传入的密钥必须存在于内核密钥环中， 且类型必须是'logon'
+auth_hash_name= 用于身份验证的哈希算法。同时用于哈希计算和 HMAC
+ 生成。典型值包括"sha256"或"sha512"
+==================== =======================================================
+
+快速使用指南
+============
+
+挂载的 UBI 卷通过 "ubiX_Y" 或 "ubiX:NAME" 语法指定，其中 "X" 是 UBI
+设备编号，"Y" 是 UBI 卷编号，"NAME" 是 UBI 卷名称。
+
+将 UBI 设备 0 的卷 0 挂载到 /mnt/ubifs::
+
+ $ mount -t ubifs ubi0_0 /mnt/ubifs
+
+将 UBI 设备 0 的 "rootfs" 卷挂载到 /mnt/ubifs（"rootfs" 是卷名）::
+
+ $ mount -t ubifs ubi0:rootfs /mnt/ubifs
+
+以下是内核启动参数的示例，用于将 mtd0 附加到 UBI 并挂载 "rootfs" 卷：
+ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs
+
+参考资料
+========
+
+UBIFS 文档及常见问题解答/操作指南请访问 MTD 官网：
+
+- http://www.linux-mtd.infradead.org/doc/ubifs.html
+- http://www.linux-mtd.infradead.org/faq/ubifs.html
--
2.27.0
^ permalink raw reply [flat|nested] 8+ messages in thread* [PATCH v5 2/7] Docs/zh_CN: Translate ubifs-authentication.rst to Simplified Chinese
2025-09-17 3:50 [PATCH v5 0/7] Docs/zh_CN: Translate filesystems docs to Simplified Chinese shao.mingyin
2025-09-17 3:53 ` [PATCH v5 1/7] Docs/zh_CN: Translate ubifs.rst " shao.mingyin
@ 2025-09-17 3:54 ` shao.mingyin
2025-09-17 3:55 ` [PATCH v5 3/7] Docs/zh_CN: Translate gfs2.rst " shao.mingyin
` (4 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: shao.mingyin @ 2025-09-17 3:54 UTC (permalink / raw)
To: shao.mingyin
Cc: alexs, si.yanteng, dzm91, corbet, linux-doc, linux-kernel,
yang.yang29, xu.xin16, yang.tao172, wang.longjie1
From: Shao Mingyin <shao.mingyin@zte.com.cn>
translate the "ubifs-authentication.rst" into Simplified Chinese.
Update to commit d56b699d76d1("Documentation: Fix typos")
Signed-off-by: Shao Mingyin <shao.mingyin@zte.com.cn>
Signed-off-by: yang tao <yang.tao172@zte.com.cn>
---
v4->v5
fix some format issues.
.../translations/zh_CN/filesystems/index.rst | 1 +
.../filesystems/ubifs-authentication.rst | 356 ++++++++++++++++++
2 files changed, 357 insertions(+)
create mode 100644 Documentation/translations/zh_CN/filesystems/ubifs-authentication.rst
diff --git a/Documentation/translations/zh_CN/filesystems/index.rst b/Documentation/translations/zh_CN/filesystems/index.rst
index 6049b599dec8..2fbaadba77a7 100644
--- a/Documentation/translations/zh_CN/filesystems/index.rst
+++ b/Documentation/translations/zh_CN/filesystems/index.rst
@@ -27,3 +27,4 @@ Linux Kernel中的文件系统
debugfs
tmpfs
ubifs
+ ubifs-authentication
diff --git a/Documentation/translations/zh_CN/filesystems/ubifs-authentication.rst b/Documentation/translations/zh_CN/filesystems/ubifs-authentication.rst
new file mode 100644
index 000000000000..1ceb632525c3
--- /dev/null
+++ b/Documentation/translations/zh_CN/filesystems/ubifs-authentication.rst
@@ -0,0 +1,356 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/filesystems/ubifs-authentication.rst
+
+:翻译:
+
+ 邵明寅 Shao Mingyin <shao.mingyin@zte.com.cn>
+
+:校译:
+
+ - 杨涛 yang tao <yang.tao172@zte.com.cn>
+
+=============
+UBIFS认证支持
+=============
+
+引言
+====
+
+UBIFS 利用 fscrypt 框架为文件内容及文件名提供保密性。这能防止攻击者在单一
+时间点读取文件系统内容的攻击行为。典型案例是智能手机丢失时，攻击者若没有文件
+系统解密密钥则无法读取设备上的个人数据。
+
+在现阶段，UBIFS 加密尚不能防止攻击者篡改文件系统内容后用户继续使用设备的攻
+击场景。这种情况下，攻击者可任意修改文件系统内容而不被用户察觉。例如修改二
+进制文件使其执行时触发恶意行为 [DMC-CBC-ATTACK]。由于 UBIFS 大部分文件
+系统元数据以明文存储，使得文件替换和内容篡改变得相当容易。
+
+其他全盘加密系统（如 dm-crypt）可以覆盖所有文件系统元数据，这类系统虽然能
+增加这种攻击的难度，但特别是当攻击者能多次访问设备时，也有可能实现攻击。对于
+基于 Linux 块 IO 层的 dm-crypt 等文件系统，可通过 dm-integrity 或
+dm-verity 子系统[DM-INTEGRITY, DM-VERITY]在块层实现完整数据认证，这些
+功能也可与 dm-crypt 结合使用[CRYPTSETUP2]。
+
+本文描述一种为 UBIFS 实现文件内容认证和完整元数据认证的方法。由于 UBIFS
+使用 fscrypt 进行文件内容和文件名加密，认证系统可与 fscrypt 集成以利用密
+钥派生等现有功能。但系统同时也应支持在不启用加密的情况下使用 UBIFS 认证。
+
+
+MTD, UBI & UBIFS
+----------------
+
+在 Linux 中，MTD（内存技术设备）子系统提供访问裸闪存设备的统一接口。运行于
+MTD 之上的重要子系统是 UBI（无序块映像），它为闪存设备提供卷管理功能，类似
+于块设备的 LVM。此外，UBI 还处理闪存特有的磨损均衡和透明 I/O 错误处理。
+UBI 向上层提供逻辑擦除块(LEB)，并透明地映射到闪存的物理擦除块(PEB)。
+
+UBIFS 是运行于 UBI 之上的裸闪存文件系统。因此 UBI 处理磨损均衡和部分闪存
+特性，而 UBIFS专注于可扩展性、性能和可恢复性。
+
+::
+
+ +------------+ +*******+ +-----------+ +-----+
+ | | * UBIFS * | UBI-BLOCK | | ... |
+ | JFFS/JFFS2 | +*******+ +-----------+ +-----+
+ | | +-----------------------------+ +-----------+ +-----+
+ | | | UBI | | MTD-BLOCK | | ... |
+ +------------+ +-----------------------------+ +-----------+ +-----+
+ +------------------------------------------------------------------+
+ | MEMORY TECHNOLOGY DEVICES (MTD) |
+ +------------------------------------------------------------------+
+ +-----------------------------+ +--------------------------+ +-----+
+ | NAND DRIVERS | | NOR DRIVERS | | ... |
+ +-----------------------------+ +--------------------------+ +-----+
+
+ 图1：处理裸闪存的 Linux 内核子系统
+
+
+
+UBIFS 内部维护多个持久化在闪存上的数据结构：
+
+- *索引*：存储在闪存上的 B+ 树，叶节点包含文件系统数据
+- *日志*：在更新闪存索引前收集文件系统变更的辅助数据结构，可减少闪存磨损
+- *树节点缓存(TNC)*：反映当前文件系统状态的内存 B+ 树，避免频繁读取闪存。
+ 本质上是索引的内存表示，但包含额外属性
+- *LEB属性树(LPT)*：用于统计每个 UBI LEB 空闲空间的闪存B+树
+
+本节后续将详细讨论UBIFS的闪存数据结构。因为 TNC 不直接持久化到闪存，其在此
+处的重要性较低。更多 UBIFS 细节详见[UBIFS-WP]。
+
+
+UBIFS 索引与树节点缓存
+~~~~~~~~~~~~~~~~~~~~~~
+
+UBIFS 在闪存上的基础实体称为 *节点* ，包含多种类型。如存储文件内容块的数据
+节点
+( ``struct ubifs_data_node`` )，或表示 VFS 索引节点的 inode 节点
+( ``struct ubifs_ino_node`` )。几乎所有节点共享包含节点类型、长度、序列
+号等基础信息的通用头
+( ``ubifs_ch`` )（见内核源码 ``fs/ubifs/ubifs-media.h`` ）。LPT条目
+和填充节点（用于填充 LEB
+尾部不可用空间）等次要节点类型除外。
+
+为避免每次变更重写整个 B+ 树，UBIFS 采用 *wandering tree* 实现：仅重写
+变更节点，旧版本被标记废弃而非立即擦除。因此索引不固定存储于闪存某处，而是在
+闪存上 *wanders* ，在 LEB 被 UBIFS 重用前，闪存上会存在废弃部分。为定位
+最新索引，UBIFS 在 UBI LEB 1 存储称为 *主节点* 的特殊节点，始终指向最新
+UBIFS 索引根节点。为增强可恢复性，主节点还备份到 LEB 2。因此挂载 UBIFS 只
+需读取 LEB 1 和 2 获取当前主节点，进而定位最新闪存索引。
+
+TNC 是闪存索引的内存表示，包含未持久化的运行时属性（如脏标记）。TNC 作为回
+写式缓存，所有闪存索引修改都通过 TNC 完成。与其他缓存类似，TNC 无需将完整
+索引全部加载到内存中，需要时从闪存读取部分内容。 *提交* 是更新闪存文件系统
+结构（如索引）的 UBIFS 操作。每次提交时，标记为脏的 TNC 节点被写入闪存以更
+新持久化索引。
+
+
+日志
+~~~~
+
+为避免闪存磨损，索引仅在满足特定条件（如 ``fsync(2)`` ）时才持久化（提交）。
+日志用于记录索引提交之间的所有变更（以 inode 节点、数据节点等形式）。挂载时
+从闪存读取日志并重放到 TNC（此时 TNC 按需从闪存索引创建）。
+
+UBIFS 保留一组专用于日志的 LEB（称为 *日志区* ）。日志区 LEB 数量在文件系
+统创建时配置（使用 ``mkfs.ubifs`` ）并存储于超级块节点。日志区仅含两类节
+点： *引用节点* 和 *提交起始节点* 。执行索引提交时写入提交起始节点，每次日
+志更新时写入引用节点。每个引用节点指向构成日志条目的其他节点（ inode 节点、
+数据节点等）在闪存上的位置，这些节点称为 *bud* ，描述包含数据的实际文件系
+统变更。
+
+日志区以环形缓冲区维护。当日志将满时触发提交操作，同时写入提交起始节点。因此
+挂载时 UBIFS 查找最新提交起始节点，仅重放其后的引用节点。提交起始节点前的引
+用节点将被忽略（因其已属于闪存索引）。
+
+写入日志条目时，UBIFS 首先确保有足够空间写入引用节点和该条目的 bud。然后先
+写引用节点，再写描述文件变更的 bud。在日志重放阶段，UBIFS 会记录每个参考节
+点，并检查其引用的 LEB位置以定位 buds。若这些数据损坏或丢失，UBIFS 会尝试
+通过重新读取 LEB 来恢复，但仅针对日志中最后引用的 LEB，因为只有它可能因断
+电而损坏。若恢复失败，UBIFS 将拒绝挂载。对于其他 LEB 的错误，UBIFS 会直接
+终止挂载操作。
+
+::
+
+ | ---- LOG AREA ---- | ---------- MAIN AREA ------------ |
+
+ -----+------+-----+--------+---- ------+-----+-----+---------------
+ \ | | | | / / | | | \
+ / CS | REF | REF | | \ \ DENT | INO | INO | /
+ \ | | | | / / | | | \
+ ----+------+-----+--------+--- -------+-----+-----+----------------
+ | | ^ ^
+ | | | |
+ +------------------------+ |
+ | |
+ +-------------------------------+
+
+
+ 图2：包含提交起始节点(CS)和引用节点(REF)的日志区闪存布局，引用节点指向含
+ bud 的主区
+
+
+LEB属性树/表
+~~~~~~~~~~~~
+
+LEB 属性树用于存储每个 LEB 的信息，包括 LEB 类型、LEB 上的空闲空间和
+*脏空间* （旧空间，废弃内容） [1]_ 的数量。因为 UBIFS 从不在单个 LEB 混
+合存储索引节点和数据节点，所以 LEB 的类型至关重要，每个 LEB 都有特定用途，
+这对空闲空间计算非常有帮助。详见[UBIFS-WP]。
+
+LEB 属性树也是 B+ 树，但远小于索引。因为其体积小，所以每次提交时都整块写入，
+保存 LPT 是原子操作。
+
+
+.. [1] 由于LEB只能追加写入不能覆盖，空闲空间（即 LEB 剩余可写空间）与废弃
+ 内容（先前写入但未擦除前不能覆盖）存在区别。
+
+
+UBIFS认证
+=========
+
+本章介绍UBIFS认证，使UBIFS能验证闪存上元数据和文件内容的真实性与完整性。
+
+
+威胁模型
+--------
+
+UBIFS 认证可检测离线数据篡改。虽然不能防止篡改，但是能让（可信）代码检查闪
+存文件内容和文件系统元数据的完整性与真实性，也能检查文件内容被替换的攻击。
+
+UBIFS 认证不防护全闪存内容回滚（攻击者可转储闪存内容并在后期还原）。也不防护
+单个索引提交的部分回滚（攻击者能部分撤销变更）。这是因为 UBIFS 不立即覆盖索
+引树或日志的旧版本，而是标记为废弃，稍后由垃圾回收擦除。攻击者可擦除当前树部
+分内容并还原闪存上尚未擦除的旧版本。因每次提交总会写入索引根节点和主节点的新
+版本而不覆盖旧版本，UBI 的磨损均衡操作（将内容从物理擦除块复制到另一擦除块
+且非原子擦除原块）进一步助长此问题。
+
+UBIFS 认证不覆盖认证密钥提供后攻击者在设备执行代码的攻击，需结合安全启动和
+可信启动等措施确保设备仅执行可信代码。
+
+
+认证
+----
+
+为完全信任从闪存读取的数据，所有存储在闪存的 UBIFS 数据结构均需认证：
+- 包含文件内容、扩展属性、文件长度等元数据的索引
+- 通过记录文件系统变更来包含文件内容和元数据的日志
+- 存储 UBIFS 用于空闲空间统计的 UBI LEB 元数据的 LPT
+
+
+索引认证
+~~~~~~~~
+
+借助 *wandering tree* 概念，UBIFS 仅更新和持久化从叶节点到根节点的变更
+部分。这允许用子节点哈希增强索引树节点。最终索引基本成为 Merkle 树：因索引
+叶节点含实际文件系统数据，其父索引节点的哈希覆盖所有文件内容和元数据。文件
+变更时，UBIFS 索引从叶节点到根节点（含主节点）相应更新，此过程可挂钩以同步
+重新计算各变更节点的哈希。读取文件时，UBIFS 可从叶节点到根节点逐级验证哈希
+确保节点完整性。
+
+为确保整个索引真实性，UBIFS 主节点存储基于密钥的哈希(HMAC)，覆盖自身内容及
+索引树根节点哈希。如前所述，主节点在索引持久化时（即索引提交时）总会写入闪存。
+
+此方法仅修改 UBIFS 索引节点和主节点以包含哈希，其他类型节点保持不变，减少了
+对 UBIFS 用户（如嵌入式设备）宝贵的存储开销。
+
+::
+
+ +---------------+
+ | Master Node |
+ | (hash) |
+ +---------------+
+ |
+ v
+ +-------------------+
+ | Index Node #1 |
+ | |
+ | branch0 branchn |
+ | (hash) (hash) |
+ +-------------------+
+ | ... | (fanout: 8)
+ | |
+ +-------+ +------+
+ | |
+ v v
+ +-------------------+ +-------------------+
+ | Index Node #2 | | Index Node #3 |
+ | | | |
+ | branch0 branchn | | branch0 branchn |
+ | (hash) (hash) | | (hash) (hash) |
+ +-------------------+ +-------------------+
+ | ... | ... |
+ v v v
+ +-----------+ +----------+ +-----------+
+ | Data Node | | INO Node | | DENT Node |
+ +-----------+ +----------+ +-----------+
+
+
+ 图3：索引节点哈希与主节点 HMAC 的覆盖范围
+
+
+
+健壮性性和断电安全性的关键在于以原子操作持久化哈希值与文件内容。UBIFS 现有
+的变更节点持久化机制专为此设计，能够确保断电时安全恢复。为索引节点添加哈希值
+不会改变该机制，因为每个哈希值都与其对应节点以原子操作同步持久化。
+
+
+日志认证
+~~~~~~~~
+
+日志也需要认证。因为日志持续写入，必须频繁地添加认证信息以确保断电时未认证数
+据量可控。方法是从提交起始节点开始，对先前引用节点、当前引用节点和 bud 节点
+创建连续哈希链。适时地在bud节点间插入认证节点，这种新节点类型包含哈希链当前
+状态的 HMAC。因此日志可认证至最后一个认证节点。日志尾部无认证节点的部分无法
+认证，在日志重放时跳过。
+
+日志认证示意图如下::
+
+ ,,,,,,,,
+ ,......,...........................................
+ ,. CS , hash1.----. hash2.----.
+ ,. | , . |hmac . |hmac
+ ,. v , . v . v
+ ,.REF#0,-> bud -> bud -> bud.-> auth -> bud -> bud.-> auth ...
+ ,..|...,...........................................
+ , | ,
+ , | ,,,,,,,,,,,,,,,
+ . | hash3,----.
+ , | , |hmac
+ , v , v
+ , REF#1 -> bud -> bud,-> auth ...
+ ,,,|,,,,,,,,,,,,,,,,,,
+ v
+ REF#2 -> ...
+ |
+ V
+ ...
+
+因为哈希值包含引用节点，攻击者无法重排或跳过日志头重放，仅能移除日志尾部的
+bud 节点或引用节点，最大限度将文件系统回退至上次提交。
+
+日志区位置存储于主节点。因为主节点通过 HMAC 认证，所以未经检测无法篡改。日
+志区大小在文件系统创建时由 `mkfs.ubifs` 指定并存储于超级块节点。为避免篡
+改此值及其他参数，超级块结构添加 HMAC。超级块节点存储在 LEB 0，仅在功能标
+志等变更时修改，文件变更时不修改。
+
+
+LPT认证
+~~~~~~~
+
+LPT 根节点在闪存上的位置存储于 UBIFS 主节点。因为 LPT 每次提交时都以原子
+操作写入和读取，无需单独认证树节点。通过主节点存储的简单哈希保护完整 LPT
+即可。因为主节点自身已认证，通过验证主节点真实性并比对存储的 LTP 哈希与读
+取的闪存 LPT 计算哈希值，即可验证 LPT 真实性。
+
+
+密钥管理
+--------
+
+为了简化实现，UBIFS 认证使用单一密钥计算超级块、主节点、提交起始节点和引用
+节点的 HMAC。创建文件系统(`mkfs.ubifs`) 时需提供此密钥以认证超级块节点。
+挂载文件系统时也需此密钥验证认证节点并为变更生成新 HMAC。
+
+UBIFS 认证旨在与 UBIFS 加密(fscrypt)协同工作以提供保密性和真实性。因为
+UBIFS 加密采用基于目录的差异化加密策略，可能存在多个 fscrypt 主密钥甚至未
+加密目录。而 UBIFS 认证采用全有或全无方式，要么认证整个文件系统要么完全不
+认证。基于此特性，且为确保认证机制可独立于加密功能使用，UBIFS 认证不与
+fscrypt 共享主密钥，而是维护独立的认证专用密钥。
+
+提供认证密钥的API尚未定义，但可通过类似 fscrypt 的用户空间密钥环提供。需注
+意当前 fscrypt 方案存在缺陷，用户空间 API 终将变更[FSCRYPT-POLICY2]。
+
+用户仍可通过用户空间提供单一口令或密钥覆盖 UBIFS 认证与加密。相应用户空间工
+具可解决此问题：除派生的 fscrypt 加密主密钥外，额外派生认证密钥。
+
+为检查挂载时密钥可用性，UBIFS 超级块节点将额外存储认证密钥的哈希。此方法类
+似 fscrypt 加密策略 v2 提出的方法[FSCRYPT-POLICY2]。
+
+
+未来扩展
+========
+
+特定场景下，若供应商需要向客户提供认证文件系统镜像，应该能在不共享 UBIFS 认
+证密钥的前提下实现。方法是在每个 HMAC 外额外存储数字签名，供应商随文件系统
+镜像分发公钥。若该文件系统后续需要修改，若后续需修改该文件系统，UBIFS 可在
+首次挂载时将全部数字签名替换为 HMAC，其处理逻辑与 IMA/EVM 子系统应对此类情
+况的方式类似。此时，HMAC 密钥需按常规方式预先提供。
+
+
+参考
+====
+
+[CRYPTSETUP2] https://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
+
+[DMC-CBC-ATTACK] https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-en
+crypted-luks-partitions/
+
+[DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst
+
+[DM-VERITY] https://www.kernel.org/doc/Documentation/device-mapper/verity.rst
+
+[FSCRYPT-POLICY2] https://www.spinics.net/lists/linux-ext4/msg58710.html
+
+[UBIFS-WP] http://www.linux-mtd.infradead.org/doc/ubifs_whitepaper.pdf
--
2.27.0
^ permalink raw reply [flat|nested] 8+ messages in thread* [PATCH v5 3/7] Docs/zh_CN: Translate gfs2.rst to Simplified Chinese
2025-09-17 3:50 [PATCH v5 0/7] Docs/zh_CN: Translate filesystems docs to Simplified Chinese shao.mingyin
2025-09-17 3:53 ` [PATCH v5 1/7] Docs/zh_CN: Translate ubifs.rst " shao.mingyin
2025-09-17 3:54 ` [PATCH v5 2/7] Docs/zh_CN: Translate ubifs-authentication.rst " shao.mingyin
@ 2025-09-17 3:55 ` shao.mingyin
2025-09-17 3:56 ` [PATCH v5 4/7] Docs/zh_CN: Translate gfs2-uevents.rst " shao.mingyin
` (3 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: shao.mingyin @ 2025-09-17 3:55 UTC (permalink / raw)
To: shao.mingyin
Cc: alexs, si.yanteng, dzm91, corbet, linux-doc, linux-kernel,
yang.yang29, xu.xin16, yang.tao172, wang.longjie1
From: Shao Mingyin <shao.mingyin@zte.com.cn>
translate the "gfs2.rst" into Simplified Chinese.
Update to commit d9593868cd58("Documentation: Update
filesystems/gfs2.rst")
Signed-off-by: Shao Mingyin <shao.mingyin@zte.com.cn>
Signed-off-by: yang tao <yang.tao172@zte.com.cn>
---
v4->v5
fix some format issues.
.../translations/zh_CN/filesystems/gfs2.rst | 57 +++++++++++++++++++
.../translations/zh_CN/filesystems/index.rst | 1 +
2 files changed, 58 insertions(+)
create mode 100644 Documentation/translations/zh_CN/filesystems/gfs2.rst
diff --git a/Documentation/translations/zh_CN/filesystems/gfs2.rst b/Documentation/translations/zh_CN/filesystems/gfs2.rst
new file mode 100644
index 000000000000..301a6af257b1
--- /dev/null
+++ b/Documentation/translations/zh_CN/filesystems/gfs2.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/filesystems/gfs2.rst
+
+:翻译:
+
+ 邵明寅 Shao Mingyin <shao.mingyin@zte.com.cn>
+
+:校译:
+
+ - 杨涛 yang tao <yang.tao172@zte.com.cn>
+
+=====================================
+全局文件系统 2 (Global File System 2)
+=====================================
+
+GFS2 是一个集群文件系统。它允许一组计算机同时使用在它们之间共享的块设备（通
+过 FC、iSCSI、NBD 等）。GFS2 像本地文件系统一样读写块设备，但也使用一个锁
+模块来让计算机协调它们的 I/O 操作，从而维护文件系统的一致性。GFS2 的出色特
+性之一是完美一致性——在一台机器上对文件系统所做的更改会立即显示在集群中的所
+有其他机器上。
+
+GFS2 使用可互换的节点间锁定机制，当前支持的机制有：
+
+ lock_nolock
+ - 允许将 GFS2 用作本地文件系统
+
+ lock_dlm
+ - 使用分布式锁管理器 (dlm) 进行节点间锁定。
+ 该 dlm 位于 linux/fs/dlm/
+
+lock_dlm 依赖于在上述 URL 中找到的用户空间集群管理系统。
+
+若要将 GFS2 用作本地文件系统，则不需要外部集群系统，只需：:
+
+ $ mkfs -t gfs2 -p lock_nolock -j 1 /dev/block_device
+ $ mount -t gfs2 /dev/block_device /dir
+
+在所有集群节点上都需要安装 gfs2-utils 软件包；对于 lock_dlm，您还需要按
+照文档配置 dlm 和 corosync 用户空间工具。
+
+gfs2-utils 可在 https://pagure.io/gfs2-utils 找到。
+
+GFS2 在磁盘格式上与早期版本的 GFS 不兼容，但它已相当接近。
+
+以下手册页 (man pages) 可在 gfs2-utils 中找到：
+
+ ============ =============================================
+ fsck.gfs2 用于修复文件系统
+ gfs2_grow 用于在线扩展文件系统
+ gfs2_jadd 用于在线向文件系统添加日志
+ tunegfs2 用于操作、检查和调优文件系统
+ gfs2_convert 用于将 gfs 文件系统原地转换为 GFS2
+ mkfs.gfs2 用于创建文件系统
+ ============ =============================================
diff --git a/Documentation/translations/zh_CN/filesystems/index.rst b/Documentation/translations/zh_CN/filesystems/index.rst
index 3c25b39739db..37968fb91f1a 100644
--- a/Documentation/translations/zh_CN/filesystems/index.rst
+++ b/Documentation/translations/zh_CN/filesystems/index.rst
@@ -28,3 +28,4 @@ Linux Kernel中的文件系统
tmpfs
ubifs
ubifs-authentication
+ gfs2
--
2.25.1
^ permalink raw reply [flat|nested] 8+ messages in thread* [PATCH v5 4/7] Docs/zh_CN: Translate gfs2-uevents.rst to Simplified Chinese
2025-09-17 3:50 [PATCH v5 0/7] Docs/zh_CN: Translate filesystems docs to Simplified Chinese shao.mingyin
` (2 preceding siblings ...)
2025-09-17 3:55 ` [PATCH v5 3/7] Docs/zh_CN: Translate gfs2.rst " shao.mingyin
@ 2025-09-17 3:56 ` shao.mingyin
2025-09-17 4:24 ` [PATCH v5 5/7] Docs/zh_CN: Translate gfs2-glocks.rst " shao.mingyin
` (2 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: shao.mingyin @ 2025-09-17 3:56 UTC (permalink / raw)
To: shao.mingyin
Cc: alexs, si.yanteng, dzm91, corbet, linux-doc, linux-kernel,
yang.yang29, xu.xin16, yang.tao172, wang.longjie1
From: Shao Mingyin <shao.mingyin@zte.com.cn>
translate the "gfs2-uevents.rst" into Simplified Chinese.
Update to commit 5b7ac27a6e2c("docs: filesystems: convert
gfs2-uevents.txt to ReST")
Signed-off-by: Shao Mingyin <shao.mingyin@zte.com.cn>
Signed-off-by: yang tao <yang.tao172@zte.com.cn>
---
v4->v5
fix some format issues.
.../zh_CN/filesystems/gfs2-uevents.rst | 97 +++++++++++++++++++
.../translations/zh_CN/filesystems/index.rst | 1 +
2 files changed, 98 insertions(+)
create mode 100644 Documentation/translations/zh_CN/filesystems/gfs2-uevents.rst
diff --git a/Documentation/translations/zh_CN/filesystems/gfs2-uevents.rst b/Documentation/translations/zh_CN/filesystems/gfs2-uevents.rst
new file mode 100644
index 000000000000..8ac820aa8dd5
--- /dev/null
+++ b/Documentation/translations/zh_CN/filesystems/gfs2-uevents.rst
@@ -0,0 +1,97 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/filesystems/gfs2-uevents.rst
+
+:翻译:
+
+ 邵明寅 Shao Mingyin <shao.mingyin@zte.com.cn>
+
+:校译:
+
+ - 杨涛 yang tao <yang.tao172@zte.com.cn>
+
+===============
+uevents 与 GFS2
+===============
+
+在 GFS2 文件系统的挂载生命周期内，会生成多个 uevent。
+本文档解释了这些事件的含义及其用途（被 gfs2-utils 中的 gfs_controld 使用）。
+
+GFS2 uevents 列表
+=================
+
+1. ADD
+------
+
+ADD 事件发生在挂载时。它始终是新建文件系统生成的第一个 uevent。如果挂载成
+功，随后会生成 ONLINE uevent。如果挂载失败，则随后会生成 REMOVE uevent。
+
+ADD uevent 包含两个环境变量：SPECTATOR=[0|1] 和 RDONLY=[0|1]，分别用
+于指定文件系统的观察者状态（一种未分配日志的只读挂载）和只读状态（已分配日志）。
+
+2. ONLINE
+---------
+
+ONLINE uevent 在成功挂载或重新挂载后生成。它具有与 ADD uevent 相同的环
+境变量。ONLINE uevent 及其用于标识观察者和 RDONLY 状态的两个环境变量是较
+新版本内核引入的功能（2.6.32-rc+ 及以上），旧版本内核不会生成此事件。
+
+3. CHANGE
+---------
+
+CHANGE uevent 在两种场景下使用。一是报告第一个节点成功挂载文件系统时
+（FIRSTMOUNT=Done）。这作为信号告知 gfs_controld，此时集群中其他节点可以
+安全挂载该文件系统。
+
+另一个 CHANGE uevent 用于通知文件系统某个日志的日志恢复已完成。它包含两个
+环境变量：JID= 指定刚恢复的日志 ID，RECOVERY=[Done|Failed] 表示操作成
+功与否。这些 uevent 会在每次日志恢复时生成，无论是在初始挂载过程中，还是
+gfs_controld 通过 /sys/fs/gfs2/<fsname>/lock_module/recovery 文件
+请求特定日志恢复的结果。
+
+由于早期版本的 gfs_controld 使用 CHANGE uevent 时未检查环境变量以确定状
+态，若为其添加新功能，存在用户工具版本过旧导致集群故障的风险。因此，在新增用
+于标识成功挂载或重新挂载的 uevent 时，选择了使用 ONLINE uevent。
+
+4. OFFLINE
+----------
+
+OFFLINE uevent 仅在文件系统发生错误时生成，是 "withdraw" 机制的一部分。
+当前该事件未提供具体错误信息，此问题有待修复。
+
+5. REMOVE
+---------
+
+REMOVE uevent 在挂载失败结束或卸载文件系统时生成。所有 REMOVE uevent
+之前都至少存在同一文件系统的 ADD uevent。与其他 uevent 不同，它由内核的
+kobject 子系统自动生成。
+
+
+所有 GFS2 uevents 的通用信息（uevent 环境变量）
+===============================================
+
+1. LOCKTABLE=
+-------------
+
+LOCKTABLE 是一个字符串，其值来源于挂载命令行（locktable=）或 fstab 文件。
+它用作文件系统标签，并为 lock_dlm 类型的挂载提供加入集群所需的信息。
+
+2. LOCKPROTO=
+-------------
+
+LOCKPROTO 是一个字符串，其值取决于挂载命令行或 fstab 中的设置。其值将是
+lock_nolock 或 lock_dlm。未来可能支持其他锁管理器。
+
+3. JOURNALID=
+-------------
+
+如果文件系统正在使用日志（观察者挂载不分配日志），则所有 GFS2 uevent 中都
+会包含此变量，其值为数字形式的日志 ID。
+
+4. UUID=
+--------
+
+在较新版本的 gfs2-utils 中，mkfs.gfs2 会向文件系统超级块写入 UUID。若存
+在 UUID，所有与该文件系统相关的 uevent 中均会包含此信息。
diff --git a/Documentation/translations/zh_CN/filesystems/index.rst b/Documentation/translations/zh_CN/filesystems/index.rst
index 26b7ee6be3b1..7051fd9d94f3 100644
--- a/Documentation/translations/zh_CN/filesystems/index.rst
+++ b/Documentation/translations/zh_CN/filesystems/index.rst
@@ -29,3 +29,4 @@ Linux Kernel中的文件系统
ubifs
ubifs-authentication
gfs2
+ gfs2-uevents
--
2.27.0
^ permalink raw reply [flat|nested] 8+ messages in thread* [PATCH v5 5/7] Docs/zh_CN: Translate gfs2-glocks.rst to Simplified Chinese
2025-09-17 3:50 [PATCH v5 0/7] Docs/zh_CN: Translate filesystems docs to Simplified Chinese shao.mingyin
` (3 preceding siblings ...)
2025-09-17 3:56 ` [PATCH v5 4/7] Docs/zh_CN: Translate gfs2-uevents.rst " shao.mingyin
@ 2025-09-17 4:24 ` shao.mingyin
2025-09-17 4:25 ` [PATCH v5 6/7] Docs/zh_CN: Translate dnotify.rst " shao.mingyin
2025-09-17 4:26 ` [PATCH v5 7/7] Docs/zh_CN: Translate inotify.rst " shao.mingyin
6 siblings, 0 replies; 8+ messages in thread
From: shao.mingyin @ 2025-09-17 4:24 UTC (permalink / raw)
To: shao.mingyin
Cc: alexs, si.yanteng, dzm91, corbet, linux-doc, linux-kernel,
yang.yang29, xu.xin16, yang.tao172, wang.longjie1
From: Shao Mingyin <shao.mingyin@zte.com.cn>
translate the "gfs2-glocks.rst" into Simplified Chinese.
Update to commit 713f8834389f("gfs2: Get rid of emote_ok
checks")
Signed-off-by: Shao Mingyin <shao.mingyin@zte.com.cn>
Signed-off-by: yang tao <yang.tao172@zte.com.cn>
---
v4->v5
fix some format issues.
.../zh_CN/filesystems/gfs2-glocks.rst | 211 ++++++++++++++++++
.../translations/zh_CN/filesystems/index.rst | 1 +
2 files changed, 212 insertions(+)
create mode 100644 Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst
diff --git a/Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst b/Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst
new file mode 100644
index 000000000000..951176c7af9b
--- /dev/null
+++ b/Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst
@@ -0,0 +1,211 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/filesystems/gfs2-glocks.rst
+
+:翻译:
+
+ 邵明寅 Shao Mingyin <shao.mingyin@zte.com.cn>
+
+:校译:
+
+ - 杨涛 yang tao <yang.tao172@zte.com.cn>
+
+==================
+Glock 内部加锁规则
+==================
+
+本文档阐述 glock 状态机内部运作的基本原理。每个 glock（即
+fs/gfs2/incore.h 中的 struct gfs2_glock）包含两把主要的内部锁：
+
+ 1. 自旋锁（gl_lockref.lock）：用于保护内部状态（如
+ gl_state、gl_target）和持有者列表（gl_holders）
+ 2. 非阻塞的位锁（GLF_LOCK）：用于防止其他线程同时调用
+ DLM 等操作。若某线程获取此锁，则在释放时必须调用
+ run_queue（通常通过工作队列），以确保所有待处理任务
+ 得以完成。
+
+gl_holders 列表包含与该 glock 关联的所有排队锁请求（不
+仅是持有者）。若存在已持有的锁，它们将位于列表开头的连
+续条目中。锁的授予严格遵循排队顺序。
+
+glock 层用户可请求三种锁状态：共享（SH）、延迟（DF）和
+排他（EX）。它们对应以下 DLM 锁模式：
+
+========== ====== =====================================================
+Glock 模式 DLM 锁模式
+========== ====== =====================================================
+ UN IV/NL 未加锁（无关联的 DLM 锁）或 NL
+ SH PR 受保护读（Protected read）
+ DF CW 并发写（Concurrent write）
+ EX EX 排他（Exclusive）
+========== ====== =====================================================
+
+因此，DF 本质上是一种与“常规”共享锁模式（SH）互斥的共
+享模式。在 GFS2 中，DF 模式专用于直接 I/O 操作。Glock
+本质上是锁加缓存管理例程的组合，其缓存规则如下：
+
+========== ============== ========== ========== ==============
+Glock 模式 缓存元数据 缓存数据 脏数据 脏元数据
+========== ============== ========== ========== ==============
+ UN 否 否 否 否
+ DF 是 否 否 否
+ SH 是 是 否 否
+ EX 是 是 是 是
+========== ============== ========== ========== ==============
+
+这些规则通过为每种 glock 定义的操作函数实现。并非所有
+glock 类型都使用全部的模式，例如仅 inode glock 使用 DF 模
+式。
+
+glock 操作函数及类型常量说明表：
+
+============== ========================================================
+字段 用途
+============== ========================================================
+go_sync 远程状态变更前调用（如同步脏数据）
+go_xmote_bh 远程状态变更后调用（如刷新缓存）
+go_inval 远程状态变更需使缓存失效时调用
+go_instantiate 获取 glock 时调用
+go_held 每次获取 glock 持有者时调用
+go_dump 为 debugfs 文件打印对象内容，或出错时将 glock 转储至日志
+go_callback 若 DLM 发送回调以释放此锁时调用
+go_unlocked 当 glock 解锁时调用（dlm_unlock()）
+go_type glock 类型，``LM_TYPE_*``
+go_flags 若 glock 关联地址空间，则设置GLOF_ASPACE 标志
+============== ========================================================
+
+每种锁的最短持有时间是指在远程锁授予后忽略远程降级请求
+的时间段。此举旨在防止锁在集群节点间持续弹跳而无实质进
+展的情况，此现象常见于多节点写入的共享内存映射文件。通
+过延迟响应远程回调的降级操作，为用户空间程序争取页面取
+消映射前的处理时间。
+
+未来计划将 glock 的 "EX" 模式设为本地共享，使本地锁通
+过 i_mutex 实现而非 glock。
+
+glock 操作函数的加锁规则：
+
+============== ====================== =============================
+操作 GLF_LOCK 位锁持有 gl_lockref.lock 自旋锁持有
+============== ====================== =============================
+go_sync 是 否
+go_xmote_bh 是 否
+go_inval 是 否
+go_instantiate 否 否
+go_held 否 否
+go_dump 有时 是
+go_callback 有时（N/A） 是
+go_unlocked 是 否
+============== ====================== =============================
+
+.. Note::
+
+ 若入口处持有锁则操作期间不得释放位锁或自旋锁。
+ go_dump 和 do_demote_ok 严禁阻塞。
+ 仅当 glock 状态指示其缓存最新数据时才会调用 go_dump。
+
+GFS2 内部的 glock 加锁顺序：
+
+ 1. i_rwsem（如需要）
+ 2. 重命名 glock（仅用于重命名）
+ 3. Inode glock
+ （父级优先于子级，同级 inode 按锁编号排序）
+ 4. Rgrp glock（用于（反）分配操作）
+ 5. 事务 glock（通过 gfs2_trans_begin，非读操作）
+ 6. i_rw_mutex（如需要）
+ 7. 页锁（始终最后，至关重要！）
+
+每个 inode 对应两把 glock：一把管理 inode 本身（加锁顺
+序如上），另一把（称为 iopen glock）结合 inode 的
+i_nlink 字段决定 inode 生命周期。inode 加锁基于单个
+inode，rgrp 加锁基于单个 rgrp。通常优先获取本地锁再获
+取集群锁。
+
+Glock 统计
+----------
+
+统计分为两类：超级块相关统计和单个 glock 相关统计。超级
+块统计按每 CPU 执行以减少收集开销，并进一步按 glock 类
+型细分。所有时间单位为纳秒。
+
+超级块和 glock 统计收集相同信息。超级块时序统计为 glock
+时序统计提供默认值，使新建 glock 具有合理的初始值。每个
+glock 的计数器在创建时初始化为零，当 glock 从内存移除时
+统计丢失。
+
+统计包含三组均值/方差对及两个计数器。均值/方差对为平滑
+指数估计，算法与网络代码中的往返时间计算类似（参见《
+TCP/IP详解 卷1》第21.3节及《卷2》第25.10节）。与 TCP/IP
+案例不同，此处均值/方差未缩放且单位为整数纳秒。
+
+三组均值/方差对测量以下内容：
+
+ 1. DLM 锁时间（非阻塞请求）
+ 2. DLM 锁时间（阻塞请求）
+ 3. 请求间隔时间（指向 DLM）
+
+非阻塞请求指无论目标 DLM 锁处于何种状态均能立即完成的请求。
+当前满足条件的请求包括：(a)锁当前状态为互斥（如锁降级）、
+(b)请求状态为空置或解锁（同样如锁降级）、或(c)设置"try lock"
+标志的请求。其余锁请求均属阻塞请求。
+
+两个计数器分别统计：
+ 1. 锁请求总数（决定均值/方差计算的数据量）
+ 2. glock 代码顶层的持有者排队数（通常远大于 DLM 锁请求数）
+
+为什么收集这些统计数据？我们需深入分析时序参数的动因如下：
+
+1. 更精准设置 glock "最短持有时间"
+2. 快速识别性能问题
+3. 改进资源组分配算法（基于锁等待时间而非盲目 "try lock"）
+
+因平滑更新的特性，采样量的阶跃变化需经 8 次采样（方差需
+4 次）才能完全体现，解析结果时需审慎考虑。
+
+通过锁请求完成时间和 glock 平均锁请求间隔时间，可计算节
+点使用 glock 时长与集群共享时长的占比，对设置锁最短持有
+时间至关重要。
+
+我们已采取严谨措施，力求精准测量目标量值。任何测量系统均
+存在误差，但我期望当前方案已达到合理精度极限。
+
+超级块状态统计路径::
+
+ /sys/kernel/debug/gfs2/<fsname>/sbstats
+
+Glock 状态统计路径::
+
+ /sys/kernel/debug/gfs2/<fsname>/glstats
+
+（假设 debugfs 挂载于 /sys/kernel/debug，且 <fsname> 替
+换为对应 GFS2 文件系统名）
+
+输出缩写说明：
+
+========= ============================================
+srtt 非阻塞 DLM 请求的平滑往返时间
+srttvar srtt 的方差估计
+srttb （潜在）阻塞 DLM 请求的平滑往返时间
+srttvarb srttb 的方差估计
+sirt DLM 请求的平滑请求间隔时间
+sirtvar sirt 的方差估计
+dlm DLM 请求数（glstats 文件中的 dcnt）
+queue 排队的 glock 请求数（glstats 文件中的 qcnt）
+========= ============================================
+
+sbstats文件按glock类型（每种类型8行）和CPU核心（每CPU一列）
+记录统计数据集。glstats文件则为每个glock提供统计集，其格式
+与glocks文件类似，但所有时序统计量均采用均值/方差格式存储。
+
+gfs2_glock_lock_time 跟踪点实时输出目标 glock 的当前统计
+值，并附带每次接收到的dlm响应附加信息：
+
+====== ============
+status DLM 请求状态
+flags DLM 请求标志
+tdiff 该请求的耗时
+====== ============
+
+（其余字段同上表）
diff --git a/Documentation/translations/zh_CN/filesystems/index.rst b/Documentation/translations/zh_CN/filesystems/index.rst
index 7051fd9d94f3..4a670f6cc080 100644
--- a/Documentation/translations/zh_CN/filesystems/index.rst
+++ b/Documentation/translations/zh_CN/filesystems/index.rst
@@ -30,3 +30,4 @@ Linux Kernel中的文件系统
ubifs-authentication
gfs2
gfs2-uevents
+ gfs2-glocks
--
2.27.0
^ permalink raw reply [flat|nested] 8+ messages in thread* [PATCH v5 6/7] Docs/zh_CN: Translate dnotify.rst to Simplified Chinese
2025-09-17 3:50 [PATCH v5 0/7] Docs/zh_CN: Translate filesystems docs to Simplified Chinese shao.mingyin
` (4 preceding siblings ...)
2025-09-17 4:24 ` [PATCH v5 5/7] Docs/zh_CN: Translate gfs2-glocks.rst " shao.mingyin
@ 2025-09-17 4:25 ` shao.mingyin
2025-09-17 4:26 ` [PATCH v5 7/7] Docs/zh_CN: Translate inotify.rst " shao.mingyin
6 siblings, 0 replies; 8+ messages in thread
From: shao.mingyin @ 2025-09-17 4:25 UTC (permalink / raw)
To: shao.mingyin
Cc: alexs, si.yanteng, dzm91, corbet, linux-doc, linux-kernel,
yang.yang29, xu.xin16, yang.tao172, wang.longjie1
From: Wang Longjie <wang.longjie1@zte.com.cn>
translate the "dnotify.rst" into Simplified Chinese.
Update to commit b31763cff488("docs: filesystems: convert dnotify.txt to
ReST")
Signed-off-by: Wang Longjie <wang.longjie1@zte.com.cn>
Signed-off-by: Shao Mingyin <shao.mingyin@zte.com.cn>
---
v4->v5
fix some format issues.
.../zh_CN/filesystems/dnotify.rst | 69 +++++++++++++++++++
.../translations/zh_CN/filesystems/index.rst | 10 +++
2 files changed, 79 insertions(+)
create mode 100644 Documentation/translations/zh_CN/filesystems/dnotify.rst
diff --git a/Documentation/translations/zh_CN/filesystems/dnotify.rst b/Documentation/translations/zh_CN/filesystems/dnotify.rst
new file mode 100644
index 000000000000..31ce2b4c75ff
--- /dev/null
+++ b/Documentation/translations/zh_CN/filesystems/dnotify.rst
@@ -0,0 +1,69 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/filesystems/dnotify.rst
+
+:翻译:
+
+ 王龙杰 Wang Longjie <wang.longjie1@zte.com.cn>
+
+==============
+Linux 目录通知
+==============
+
+ Stephen Rothwell <sfr@canb.auug.org.au>
+
+目录通知的目的是使用户应用程序能够在目录或目录中的任何文件发生变更时收到通知。基本机制包括应用程序
+通过 fcntl(2) 调用在目录上注册通知，通知本身则通过信号传递。
+
+应用程序可以决定希望收到哪些 “事件” 的通知。当前已定义的事件如下：
+
+ ========= =====================================
+ DN_ACCESS 目录中的文件被访问（read）
+ DN_MODIFY 目录中的文件被修改（write,truncate）
+ DN_CREATE 目录中创建了文件
+ DN_DELETE 目录中的文件被取消链接
+ DN_RENAME 目录中的文件被重命名
+ DN_ATTRIB 目录中的文件属性被更改（chmod,chown）
+ ========= =====================================
+
+通常，应用程序必须在每次通知后重新注册，但如果将 DN_MULTISHOT 与事件掩码进行或运算，则注册
+将一直保持有效，直到被显式移除（通过注册为不接收任何事件）。
+
+默认情况下，SIGIO 信号将被传递给进程，且不附带其他有用的信息。但是，如果使用 F_SETSIG fcntl(2)
+调用让内核知道要传递哪个信号，一个 siginfo 结构体将被传递给信号处理程序，该结构体的 si_fd 成员将
+包含与发生事件的目录相关联的文件描述符。
+
+应用程序最好选择一个实时信号（SIGRTMIN + <n>），以便通知可以被排队。如果指定了 DN_MULTISHOT，
+这一点尤为重要。注意，SIGRTMIN 通常是被阻塞的，因此最好使用（至少）SIGRTMIN + 1。
+
+实现预期（特性与缺陷 :-)）
+--------------------------
+
+对于文件的任何本地访问，通知都应能正常工作，即使实际文件系统位于远程服务器上。这意味着，对本地用户
+模式服务器提供的文件的远程访问应能触发通知。同样的，对本地内核 NFS 服务器提供的文件的远程访问
+也应能触发通知。
+
+为了尽可能减小对文件系统代码的影响，文件硬链接的问题已被忽略。因此，如果一个文件（x）存在于两个
+目录（a 和 b）中，通过名称”a/x”对该文件进行的更改应通知给期望接收目录“a”通知的程序，但不会
+通知给期望接收目录“b”通知的程序。
+
+此外，取消链接的文件仍会在它们链接到的最后一个目录中触发通知。
+
+配置
+----
+
+Dnotify 由 CONFIG_DNOTIFY 配置选项控制。禁用该选项时，fcntl(fd, F_NOTIFY, ...) 将返
+回 -EINVAL。
+
+示例
+----
+
+具体示例可参见 tools/testing/selftests/filesystems/dnotify_test.c。
+
+注意
+----
+
+从 Linux 2.6.13 开始，dnotify 已被 inotify 取代。有关 inotify 的更多信息，请参见
+Documentation/filesystems/inotify.rst。
diff --git a/Documentation/translations/zh_CN/filesystems/index.rst b/Documentation/translations/zh_CN/filesystems/index.rst
index 4a670f6cc080..4e9b1ca46231 100644
--- a/Documentation/translations/zh_CN/filesystems/index.rst
+++ b/Documentation/translations/zh_CN/filesystems/index.rst
@@ -15,6 +15,16 @@ Linux Kernel中的文件系统
文件系统（VFS）层以及基于其上的各种文件系统如何工作呈现给大家。当前\
可以看到下面的内容。
+核心 VFS 文档
+=============
+
+有关 VFS 层本身以及其算法工作方式的文档，请参阅这些手册。
+
+.. toctree::
+ :maxdepth: 1
+
+ dnotify
+
文件系统
========
--
2.27.0
^ permalink raw reply [flat|nested] 8+ messages in thread* [PATCH v5 7/7] Docs/zh_CN: Translate inotify.rst to Simplified Chinese
2025-09-17 3:50 [PATCH v5 0/7] Docs/zh_CN: Translate filesystems docs to Simplified Chinese shao.mingyin
` (5 preceding siblings ...)
2025-09-17 4:25 ` [PATCH v5 6/7] Docs/zh_CN: Translate dnotify.rst " shao.mingyin
@ 2025-09-17 4:26 ` shao.mingyin
6 siblings, 0 replies; 8+ messages in thread
From: shao.mingyin @ 2025-09-17 4:26 UTC (permalink / raw)
To: shao.mingyin
Cc: alexs, si.yanteng, dzm91, corbet, linux-doc, linux-kernel,
yang.yang29, xu.xin16, yang.tao172, wang.longjie1
From: Wang Longjie <wang.longjie1@zte.com.cn>
translate the "inotify.rst" into Simplified Chinese.
Update to commit de389cf08d47("docs: filesystems: convert inotify.txt to
ReST")
Signed-off-by: Wang Longjie <wang.longjie1@zte.com.cn>
Signed-off-by: Shao Mingyin <shao.mingyin@zte.com.cn>
---
v4->v5
fix some format issues.
.../translations/zh_CN/filesystems/index.rst | 1 +
.../zh_CN/filesystems/inotify.rst | 80 +++++++++++++++++++
2 files changed, 81 insertions(+)
create mode 100644 Documentation/translations/zh_CN/filesystems/inotify.rst
diff --git a/Documentation/translations/zh_CN/filesystems/index.rst b/Documentation/translations/zh_CN/filesystems/index.rst
index 4e9b1ca46231..fcc79ff9fdad 100644
--- a/Documentation/translations/zh_CN/filesystems/index.rst
+++ b/Documentation/translations/zh_CN/filesystems/index.rst
@@ -41,3 +41,4 @@ Linux Kernel中的文件系统
gfs2
gfs2-uevents
gfs2-glocks
+ inotify
diff --git a/Documentation/translations/zh_CN/filesystems/inotify.rst b/Documentation/translations/zh_CN/filesystems/inotify.rst
new file mode 100644
index 000000000000..b4d740aca946
--- /dev/null
+++ b/Documentation/translations/zh_CN/filesystems/inotify.rst
@@ -0,0 +1,80 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/filesystems/inotify.rst
+
+:翻译:
+
+ 王龙杰 Wang Longjie <wang.longjie1@zte.com.cn>
+
+==========================================
+Inotify - 一个强大且简单的文件变更通知系统
+==========================================
+
+
+
+文档由 Robert Love <rml@novell.com> 于 2005 年 3 月 15 日开始撰写
+
+文档由 Zhang Zhen <zhenzhang.zhang@huawei.com> 于 2015 年 1 月 4 日更新
+
+ - 删除了已废弃的接口，关于用户接口请参考手册页。
+
+(i) 基本原理
+
+问：
+ 不将监控项与被监控对象打开的文件描述符（fd）绑定，这背后的设计决策是什么？
+
+答：
+ 监控项会与打开的 inotify 设备相关联，而非与打开的文件相关联。这解决了 dnotify 的主要问题：
+ 保持文件打开会锁定文件，更糟的是，还会锁定挂载点。因此，dnotify 在带有可移动介质的桌面系统
+ 上难以使用，因为介质将无法被卸载。监控文件不应要求文件处于打开状态。
+
+问：
+ 与每个监控项一个文件描述符的方式相比，采用每个实例一个文件描述符的设计决策是出于什么
+ 考虑？
+
+答：
+ 每个监控项一个文件描述符会很快的消耗掉超出允许数量的文件描述符，其数量会超出实际可管理的范
+ 围，也会超出 select() 能高效处理的范围。诚然，root 用户可以提高每个进程的文件描述符限制，
+ 用户也可以使用 epoll，但同时要求这两者是不合理且多余的。一个监控项所消耗的内存比一个打开的文
+ 件要少，因此将这两个数量空间分开是合理的。当前的设计正是用户空间开发者所期望的：用户只需初始
+ 化一次 inotify，然后添加 n 个监控项，而这只需要一个文件描述符，无需调整文件描述符限制。初
+ 始化 inotify 实例初始化两千次是很荒谬的。如果我们能够简洁地实现用户空间的偏好——而且我们
+ 确实可以，idr 层让这类事情变得轻而易举——那么我们就应该这么做。
+
+ 还有其他合理的理由。如果只有一个文件描述符，那就只需要在该描述符上阻塞，它对应着一个事件队列。
+ 这个单一文件描述符会返回所有的监控事件以及任何可能的带外数据。而如果每个文件描述符都是一个独
+ 立的监控项，
+
+ - 将无法知晓事件的顺序。文件 foo 和文件 bar 上的事件会触发两个文件描述符上的 poll()，
+ 但无法判断哪个事件先发生。而用单个队列就可以很容易的提供事件的顺序。这种顺序对现有的应用程
+ 序（如 Beagle）至关重要。想象一下，如果“mv a b ; mv b a”这样的事件没有顺序会是什么
+ 情况。
+
+ - 我们将不得不维护 n 个文件描述符和 n 个带有状态的内部队列，而不是仅仅一个。这在 kernel 中
+ 会混乱得多。单个线性队列是合理的数据结构。
+
+ - 用户空间开发者更青睐当前的 API。例如，Beagle 的开发者们就很喜欢它。相信我，我问过他们。
+ 这并不奇怪：谁会想通过 select 来管理以及阻塞在 1000 个文件描述符上呢？
+
+ - 无法获取带外数据。
+
+ - 1024 这个数量仍然太少。 ;-)
+
+ 当要设计一个可扩展到数千个目录的文件变更通知系统时，处理数千个文件描述符似乎并不是合适的接口。
+ 这太繁琐了。
+
+ 此外，创建多个实例、处理多个队列以及相应的多个文件描述符是可行的。不必是每个进程对应一个文件描
+ 述符；而是每个队列对应一个文件描述符，一个进程完全可能需要多个队列。
+
+问：
+ 为什么采用系统调用的方式？
+
+答：
+ 糟糕的用户空间接口是 dnotify 的第二大问题。信号对于文件通知来说是一种非常糟糕的接口。其实对
+ 于其他任何事情，信号也都不是好的接口。从各个角度来看，理想的解决方案是基于文件描述符的，它允许
+ 基本的文件 I/O 操作以及 poll/select 操作。获取文件描述符和管理监控项既可以通过设备文件来
+ 实现，也可以通过一系列新的系统调用来实现。我们决定采用一系列系统调用，因为这是提供新的内核接口
+ 的首选方法。两者之间唯一真正的区别在于，我们是想使用 open(2) 和 ioctl(2)，还是想使用几
+ 个新的系统调用。系统调用比 ioctl 更有优势。
--
2.27.0
^ permalink raw reply [flat|nested] 8+ messages in thread