* [PATCH v2 0/4] docs/zh_CN: Add four process translations
@ 2026-11-17 11:55 YikunWei
2026-11-17 11:55 ` [PATCH v2 1/4] docs/zh_CN: Add contribution maturity model translation YikunWei
` (4 more replies)
0 siblings, 5 replies; 6+ messages in thread
From: YikunWei @ 2026-11-17 11:55 UTC (permalink / raw)
To: alexs; +Cc: si.yanteng, dzm91, linux-doc, Yikun Wei
From: Yikun Wei <YikunWei@126.com>
Changes in v2:
- Reformat contribution-maturity-model.rst to align line lengths with the
English source and restore the link to the 2021 Maintainers' Summit
discussion, as pointed out by Dongliang Mu.
- Send all four translations as a single patchset instead of separate
patches, since they share dependent changes to the process index.rst.
This series adds Chinese translations for four documents under
Documentation/process/: the contribution maturity model, deprecated
interfaces, backporting, and ioctl pitfalls. Index entries are updated
accordingly.
Yikun Wei (4):
docs/zh_CN: Add contribution maturity model translation
docs/zh_CN: Add deprecated translation
docs/zh_CN: Add backporting translation
docs/zh_CN: Add botching-up-ioctls translation
.../zh_CN/process/backporting.rst | 464 ++++++++++++++++++
.../zh_CN/process/botching-up-ioctls.rst | 186 +++++++
.../process/contribution-maturity-model.rst | 83 ++++
.../translations/zh_CN/process/deprecated.rst | 361 ++++++++++++++
.../translations/zh_CN/process/index.rst | 8 +-
5 files changed, 1098 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/zh_CN/process/backporting.rst
create mode 100644 Documentation/translations/zh_CN/process/botching-up-ioctls.rst
create mode 100644 Documentation/translations/zh_CN/process/contribution-maturity-model.rst
create mode 100644 Documentation/translations/zh_CN/process/deprecated.rst
--
2.43.0
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH v2 1/4] docs/zh_CN: Add contribution maturity model translation
2026-11-17 11:55 [PATCH v2 0/4] docs/zh_CN: Add four process translations YikunWei
@ 2026-11-17 11:55 ` YikunWei
2026-11-17 11:55 ` [PATCH v2 2/4] docs/zh_CN: Add deprecated translation YikunWei
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: YikunWei @ 2026-11-17 11:55 UTC (permalink / raw)
To: alexs; +Cc: si.yanteng, dzm91, linux-doc, Yikun Wei
From: Yikun Wei <YikunWei@126.com>
Translate .../process/contribution-maturity-model.rst into Chinese.
Update the translation through commit 10a29eb658b3
("Documentation/process: Add Linux Kernel Contribution Maturity Model")
Signed-off-by: Yikun Wei <YikunWei@126.com>
---
.../process/contribution-maturity-model.rst | 83 +++++++++++++++++++
.../translations/zh_CN/process/index.rst | 2 +-
2 files changed, 84 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/process/contribution-maturity-model.rst
diff --git a/Documentation/translations/zh_CN/process/contribution-maturity-model.rst b/Documentation/translations/zh_CN/process/contribution-maturity-model.rst
new file mode 100644
index 000000000000..3bc410386006
--- /dev/null
+++ b/Documentation/translations/zh_CN/process/contribution-maturity-model.rst
@@ -0,0 +1,83 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/process/contribution-maturity-model.rst
+
+:翻译:
+
+ Yikun Wei <YikunWei@126.com>
+
+Linux 内核贡献成熟度模型
+========================
+
+背景
+====
+
+作为 2021 年 Linux 内核维护者峰会的一部分,与会者围绕内核维护者招募以及维护者
+接棒这一难题展开了 `讨论 <https://lwn.net/Articles/870581/>`_。讨论形成的一项
+共识是:作为 Linux 内核社区一员的各家公司,应当允许工程师把担任维护者纳入本职
+工作,使其得以成长为受人尊重的领导者,并最终成为内核维护者。为了维系一条稳固的
+人才梯队,应当允许并鼓励开发者承担上游贡献,例如审阅他人的补丁、重构内核基础设施
+以及编写文档。
+
+为此,Linux 基金会技术顾问委员会(TAB)提出了本《Linux 内核贡献成熟度模型》。
+这些针对上游社区参与的共同期望,旨在提升个体开发者的影响力、加强组织间的协作,
+并改善 Linux 内核生态的整体健康度。
+
+TAB 敦促各组织持续评估自身的开源成熟度模型,并承诺做出改进以与该模型对齐。为使
+评估真正见效,评估应吸纳来自组织各层面的反馈,包括管理层以及各个资历层级的开发者。
+本着开源的精神,我们鼓励各组织公开其评估结果以及改善上游社区参与度的计划。
+
+第 0 级
+=======
+
+* 不允许软件工程师向 Linux 内核贡献补丁。
+
+第 1 级
+=======
+
+* 允许软件工程师向 Linux 内核贡献补丁,无论是作为本职工作的一部分,还是利用
+ 个人时间。
+
+第 2 级
+=======
+
+* 期望软件工程师将向上游 Linux 内核贡献作为本职工作的一部分。
+* 支持软件工程师将参加 Linux 相关的会议纳入工作范畴。
+* 在晋升与绩效评估中,将考量软件工程师的上游代码贡献。
+
+第 3 级
+=======
+
+* 期望软件工程师将审阅补丁(包括由其他公司工程师撰写的补丁)作为本职工作的
+ 一部分。
+* 向 Linux 相关会议或学术会议(例如由 Linux 基金会、Usenix、ACM 等组织的会议)
+ 提交演讲或论文,被视为工程师工作的一部分。
+* 在晋升与绩效评估中,将考量软件工程师的社区贡献。
+* 组织应定期汇报其开源贡献的度量指标,并对这些指标长期跟踪。这些指标可以仅限
+ 组织内部发布,也可由组织自行决定部分或全部对外公开。强烈建议纳入的度量指标
+ 包括:
+
+ * 团队或组织的上游内核贡献数量(例如,向某位经理、总监或副总裁汇报的所有人员)。
+ * 组织内做出过上游贡献的内核开发者,占组织内核开发者总数的比例。
+ * 组织服务器和/或产品中所用内核,与内部内核所基于的上游内核发布日期之间的
+ 时间间隔。
+ * 内部内核中存在的树外(out-of-tree)提交数量。
+
+第 4 级
+=======
+
+* 鼓励软件工程师将一部分工作时间投入到“上游工作”中。此处“上游工作”指:审阅补丁、
+ 担任程序委员会委员、改进核心项目基础设施(如编写或维护测试)、削减上游技术债务、
+ 编写文档等。
+* 支持软件工程师协助组织 Linux 相关的会议。
+* 组织将在正式的绩效评估中,考量社区成员的反馈。
+
+第 5 级
+=======
+
+* 将上游内核开发视为一个正式的工作岗位,工程师至少要将三分之一的时间用于上游
+ 工作。
+* 组织将主动征求社区成员的反馈,并将其作为正式绩效评估的一项考量因素。
+* 组织将在内部定期汇报:上游工作与直接追求业务目标的工作之间的时间比例。
diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst
index 3a36ca7d9333..4fbc2c4eb605 100644
--- a/Documentation/translations/zh_CN/process/index.rst
+++ b/Documentation/translations/zh_CN/process/index.rst
@@ -66,6 +66,7 @@ TODOLIST:
stable-kernel-rules
submit-checklist
researcher-guidelines
+ contribution-maturity-model
TODOLIST:
@@ -73,7 +74,6 @@ TODOLIST:
* kernel-docs
* deprecated
* maintainers
-* contribution-maturity-model
这些是一些总体性技术指南,由于不大好分类而放在这里:
--
2.43.0
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH v2 2/4] docs/zh_CN: Add deprecated translation
2026-11-17 11:55 [PATCH v2 0/4] docs/zh_CN: Add four process translations YikunWei
2026-11-17 11:55 ` [PATCH v2 1/4] docs/zh_CN: Add contribution maturity model translation YikunWei
@ 2026-11-17 11:55 ` YikunWei
2026-11-17 11:55 ` [PATCH v2 3/4] docs/zh_CN: Add backporting translation YikunWei
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: YikunWei @ 2026-11-17 11:55 UTC (permalink / raw)
To: alexs; +Cc: si.yanteng, dzm91, linux-doc, Yikun Wei
From: Yikun Wei <YikunWei@126.com>
Translate Documentation/process/deprecated.rst into Chinese.
Update translations/zh_CN/process/index.rst to reference the new
translation and drop the item from the TODOLIST.
Signed-off-by: Yikun Wei <YikunWei@126.com>
---
.../translations/zh_CN/process/deprecated.rst | 361 ++++++++++++++++++
.../translations/zh_CN/process/index.rst | 2 +-
2 files changed, 362 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/process/deprecated.rst
diff --git a/Documentation/translations/zh_CN/process/deprecated.rst b/Documentation/translations/zh_CN/process/deprecated.rst
new file mode 100644
index 000000000000..1f1f19871481
--- /dev/null
+++ b/Documentation/translations/zh_CN/process/deprecated.rst
@@ -0,0 +1,361 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/process/deprecated.rst
+
+:翻译:
+
+ Yikun Wei <YikunWei@126.com>
+
+.. _cn_deprecated:
+
+=====================================================================
+已弃用的接口、语言特性、属性与约定
+=====================================================================
+
+在一个理想的世界里,我们可以在单个开发周期内把某个已弃用 API 的所有用法都转换成
+新 API,并彻底移除旧 API。然而,由于内核规模庞大、维护者层级分明,再加上时机问题,
+这类转换往往无法一次性完成。这意味着,在旧用法被移除的同时,新的用法可能又悄悄混
+进内核,结果只是让移除该 API 的工作量越积越多。为了让开发者了解哪些东西已被弃用、
+以及为什么被弃用,我们整理出这份清单,当有人想把被弃用的东西加进内核时,就可以
+拿它来作为依据。
+
+__deprecated
+------------
+
+尽管这个属性在视觉上确实能将一个接口标记为“已弃用”,但它已经不会再在构建过程中
+产生警告了,原因在于内核长期以来的目标之一就是“零警告构建”,而实际上并没有人在
+真正着手移除这些被弃用的接口。虽然使用 __deprecated 可以方便地在头文件里标注某个
+旧接口,但这并不是完整的解决方案。这类接口要么必须被彻底从内核中移除,要么应当被
+写进本文件,以劝阻他人在将来继续使用它们。
+
+BUG() 与 BUG_ON()
+-----------------
+
+请改用 WARN() 与 WARN_ON(),并尽可能优雅地处理这种“不可能发生”的错误状况。BUG()
+系列接口最初被设计成一种“绝不该出现”的断言,用来“安全地”干掉某个内核线程,但
+事实证明它们风险实在太大。(比如:“锁到底该按什么顺序释放?各种状态是否已经恢复?”
+)使用 BUG() 极其常见地会让系统变得不稳定,甚至彻底崩溃,从而让人无从调试,连一份
+像样的崩溃报告都拿不到。Linus 对这一点有着 `非常强烈
+<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_
+的 `看法
+<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_。
+
+请注意,WARN() 系列只应当用于“预期不可达”的情形。如果你想对“可达但不希望出现”
+的情况发出警告,请改用 pr_warn() 系列函数。系统管理员可能设置了 *panic_on_warn*
+这个 sysctl,以确保系统在遇到“不可达”状况时不会继续运行。(例如,参见类似 `这个
+提交
+<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_ 中的改动。)
+
+分配器参数里的明文算术
+----------------------
+
+动态尺寸的计算(尤其是乘法)不应当直接写在内存分配器(或类似函数)的参数里,因为
+存在溢出的风险。这可能导致数值回绕,从而分配出比调用者预期更小的内存块。使用这类
+分配结果,可能造成堆内存的线性溢出以及其他各种异常行为。(唯一的例外是字面值,此时
+编译器可以在可能溢出时发出警告。不过即便如此,推荐的做法仍是按下面建议的方式重构
+代码,以避免这种明文算术。)
+
+例如,不要像下面这样把 ``count * size`` 当作参数使用::
+
+ foo = kmalloc(count * size, GFP_KERNEL);
+
+应当改用分配器的“双因子”形式::
+
+ foo = kmalloc_array(count, size, GFP_KERNEL);
+
+具体来说,kmalloc() 可以替换为 kmalloc_array(),而 kzalloc() 可以替换为 kcalloc()。
+
+如果没有对应的双因子形式,则应当使用“溢出饱和”辅助函数::
+
+ bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL);
+
+另一个应当避免的常见情形,是计算“末尾带有其他结构体数组”的结构体大小,例如::
+
+ header = kzalloc(sizeof(*header) + count * sizeof(*header->item),
+ GFP_KERNEL);
+
+应当改用辅助函数::
+
+ header = kzalloc(struct_size(header, item, count), GFP_KERNEL);
+
+.. note:: 如果你在一个“以零长度数组或单元素数组作为末尾成员”的结构体上使用
+ struct_size(),请重构这种数组用法,改用 `灵活数组成员
+ <#zero-length-and-one-element-arrays>`_。
+
+对于其他计算,请组合使用 size_mul()、size_add() 与 size_sub() 这几个辅助函数。
+例如,对于下面这种情况::
+
+ foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL);
+
+应当改用辅助函数::
+
+ foo = krealloc(size_add(current_size,
+ size_mul(chunk_size,
+ size_sub(count, 3))), GFP_KERNEL);
+
+更多细节,另请参考 array3_size() 与 flex_array_size(),以及相关的
+check_mul_overflow()、check_add_overflow()、check_sub_overflow() 与
+check_shl_overflow() 这一系列函数。
+
+simple_strtol()、simple_strtoll()、simple_strtoul()、simple_strtoull()
+-------------------------------------------------------------------
+
+simple_strtol()、simple_strtoll()、simple_strtoul() 与 simple_strtoull()
+这几个函数会明确地忽略溢出,这可能给调用者带来意料之外的结果。对应的
+kstrtol()、kstrtoll()、kstrtoul() 与 kstrtoull() 通常才是正确的替代函数,不过要
+注意,它们要求字符串必须以 NUL 或换行符结尾。
+
+strcpy()
+--------
+
+strcpy() 不会对目标缓冲区做边界检查。这可能导致缓冲区末尾之后的线性溢出,从而引发
+各种异常行为。虽然开启 `CONFIG_FORTIFY_SOURCE=y` 以及使用各种编译器标志有助于降低
+使用该函数的风险,但没有理由再引入它的新用法。安全的替代函数是 strscpy(),不过对于
+原先使用了 strcpy() 返回值的地方要格外小心,因为 strscpy() 返回的不是指向目标的
+指针,而是已拷贝的非 NUL 字节数(或者在发生截断时返回负的 errno)。
+
+strncpy()
+---------
+
+strncpy() 已经从内核中移除,所有原先的调用者都已被迁移到更安全的替代方案。
+
+strncpy() 无法保证目标缓冲区以 NUL 结尾,这会导致线性读溢出以及其他异常行为。它
+还会无条件地把目标填充 NUL,对于只使用以 NUL 结尾字符串的调用者而言,这是一种无谓
+的性能损耗。由于这些行为各不相同,它成了一套含义模糊的 API,让人难以判断作者在做
+这次拷贝时真正的意图是什么。
+
+strncpy() 的替代方案包括:
+
+- strscpy():当目标必须是以 NUL 结尾时使用。
+- strscpy_pad():当目标必须是以 NUL 结尾,且需要零填充时(例如跨越特权边界的
+ 结构体)。
+- memtostr():当源是定宽、非 NUL 结尾,而目标是 NUL 结尾时使用(源需带有
+ ``__nonstring`` 属性)。
+- memtostr_pad():同上,但进行零填充。
+- strtomem():当目标是定宽、非 NUL 结尾时使用(目标需带有 ``__nonstring`` 属性)。
+- strtomem_pad():当目标非 NUL 结尾、且还需要零填充时使用。
+- memcpy_and_pad():当目标大小是运行时值、且源可能未以 NUL 结尾的有界拷贝时使用。
+
+strlcpy()
+---------
+
+strlcpy() 会先读取整个源缓冲区(因为它的返回值要与 strlen() 保持一致)。这种读取
+可能会超出目标的大小限制。这既低效,又可能在源字符串未以 NUL 结尾时导致线性读溢出。
+安全的替代函数是 strscpy(),不过对于原先使用了 strlcpy() 返回值的地方要格外小心,
+因为 strscpy() 在发生截断时会返回负的 errno。
+
+%p 格式说明符
+-------------
+
+传统上,在格式字符串里使用 "%p" 会导致在 dmesg、proc、sysfs 等地方频繁暴露地址,
+从而形成漏洞。我们没有任由这些漏洞被利用,而是把内核里所有的 "%p" 都改成打印成
+哈希后的值,使其无法被用于定位地址。不应再往内核里添加新的 "%p" 用法。对于文本地址,
+使用 "%pS" 可能更合适,因为它会输出更有用的符号名而非地址。除此之外,绝大多数情况
+干脆就不要再加 "%p"。
+
+转述 Linus 目前给出的 `指引
+<https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_:
+
+- 如果哈希后的 "%p" 值毫无意义,不妨自问这个指针本身是否重要。也许它本就该被彻底
+ 删掉?
+- 如果你确实认为真实的指针值很重要,那为什么某些系统状态或用户特权级别会被视为
+ “特殊”?如果你觉得自己能在注释和提交日志里给出足够充分的理由、经得起 Linus 的
+ 审视,那么或许可以使用 "%px",同时务必确保你拥有合理的权限控制。
+
+如果你在调试时遇到 "%p" 哈希造成的问题,可以在启动时临时加上调试参数
+"`no_hash_pointers
+<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_"。
+
+变长数组(VLA)
+--------------
+
+在栈上使用变长数组(VLA)会比使用静态大小的栈数组产生差得多的机器码。尽管仅凭这些
+不小的 `性能问题
+<https://git.kernel.org/linus/02361bc77888>`_ 就足以成为消除 VLA 的理由,但它们
+同时也是安全风险。栈数组的动态增长可能会超出栈段中剩余的内存。这可能导致崩溃、可能
+覆盖栈末尾的敏感内容(在未开启 `CONFIG_THREAD_INFO_IN_TASK=y` 构建时),或者覆盖
+栈相邻的内存(在未开启 `CONFIG_VMAP_STACK=y` 构建时)。
+
+switch case 的隐式贯穿(fall-through)
+-------------------------------------
+
+C 语言允许在 switch 的某个 case 末尾缺少 "break" 语句时,自然地“贯穿”到下一个
+case。然而,这会在代码中引入歧义,因为那个缺失的 break 究竟是有意为之还是 bug,
+并不总是清楚。例如,单看代码并不显然 `STATE_ONE` 是否是有意设计为贯穿进入
+`STATE_TWO`::
+
+ switch (value) {
+ case STATE_ONE:
+ do_something();
+ case STATE_TWO:
+ do_other();
+ break;
+ default:
+ WARN("unknown state");
+ }
+
+由于历史上出现过一长串因缺少 "break" 语句 `而导致的缺陷
+<https://cwe.mitre.org/data/definitions/484.html>`_,我们不再允许隐式的贯穿
+(fall-through)。为了标识那些有意为之的贯穿,我们采纳了一个伪关键字宏
+"fallthrough",它会展开为 gcc 的扩展 `__attribute__((__fallthrough__))
+<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_。(当 C17/C18 的
+``[[fallthrough]]`` 语法被 C 编译器、静态分析器和 IDE 更广泛地支持后,我们就可以
+把宏这个伪关键字切换成那种语法了。)
+
+所有的 switch/case 代码块必须以以下几种之一结尾:
+
+* break;
+* fallthrough;
+* continue;
+* goto <label>;
+* return [expression];
+
+零长度数组与单元素数组
+----------------------
+
+内核中经常需要一种方式,用来声明“结构体末尾带有动态大小元素集合”。这类情形,内核
+代码应当始终使用 `"灵活数组成员"
+<https://en.wikipedia.org/wiki/Flexible_array_member>`_。较早的“单元素数组”或
+“零长度数组”写法不应再被使用。
+
+在较早的 C 代码里,动态大小的末尾元素是通过在结构体末尾声明一个单元素数组来实现的::
+
+ struct something {
+ size_t count;
+ struct foo items[1];
+ };
+
+这导致借助 sizeof() 得出的大小计算十分脆弱(必须先减掉那个末尾单元素的大小,才能
+得到“头部”的正确尺寸)。后来引入了 GNU C 扩展,允许使用零长度数组,以避免这类尺寸
+问题::
+
+ struct something {
+ size_t count;
+ struct foo items[0];
+ };
+
+但这又带来了别的问题,而且也没有解决两种写法共有的某些毛病,比如无法察觉这种数组
+在什么时候被意外地用在了结构体“非末尾”的位置(这可能直接发生,也可能在该结构体被
+放进联合体、结构体的结构体等情况下发生)。
+
+C99 引入了“灵活数组成员”,其数组声明完全不带数字尺寸::
+
+ struct something {
+ size_t count;
+ struct foo items[];
+ };
+
+这正是内核期望用来声明动态大小末尾元素的方式。它让编译器能在灵活数组没有出现在
+结构体最后时直接报错,从而有助于避免某些 `未定义行为
+<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_ 的 bug 被
+无意中引入代码库。它还能让编译器正确分析数组尺寸(通过 sizeof()、`CONFIG_FORTIFY_SOURCE`
+与 `CONFIG_UBSAN_BOUNDS`)。举例来说,没有任何机制会警告我们:下面这种对零长度数组
+使用 sizeof() 运算符,结果永远为零::
+
+ struct something {
+ size_t count;
+ struct foo items[0];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
+ instance->count = count;
+
+ size = sizeof(instance->items) * instance->count;
+ memcpy(instance->items, source, size);
+
+在上面代码的最后一行,``size`` 的结果其实是 ``zero``(零),而人们往往以为它代表
+刚刚为末尾数组 ``items`` 动态分配的那段内存的总字节数。这个问题有 `示例一
+<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_、
+`示例二
+<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_ 两个例子。
+相反,灵活数组成员具有“不完整类型”,因此 sizeof() 运算符不能作用于它,于是任何对此
+类运算符的误用都会在构建时被立即发现。
+
+关于单元素数组,必须清楚地认识到:这类数组占用的空间至少等同于该类型的一个对象,
+因此它会增大外围结构体的尺寸。每当人们想要计算“含有此类数组作为成员的结构体”所需
+分配的动态内存总大小时,都很容易出错::
+
+ struct something {
+ size_t count;
+ struct foo items[1];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
+ instance->count = count;
+
+ size = sizeof(instance->items) * instance->count;
+ memcpy(instance->items, source, size);
+
+在上面的例子里,使用 struct_size() 辅助函数时必须记得计算 ``count - 1``,否则就会
+——无意中——为多出来的一个 ``items`` 对象分配内存。最干净、最少出错的写法,是使用
+灵活数组成员,配合 struct_size() 与 flex_array_size() 辅助函数::
+
+ struct something {
+ size_t count;
+ struct foo items[];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
+ instance->count = count;
+
+ memcpy(instance->items, source, flex_array_size(instance, items, instance->count));
+
+有两种特殊情况在替换时需要用到 DECLARE_FLEX_ARRAY() 辅助宏。(注意,在 UAPI 头文件中
+它名为 __DECLARE_FLEX_ARRAY()。)这两种情况是:灵活数组要么单独存在于某个结构体中,
+要么作为联合体的一部分。这两点在 C99 规范里是被禁止的,但其实并没有什么技术上的理由
+(从这类数组在这些地方既有的使用、以及 DECLARE_FLEX_ARRAY() 所采用的变通写法中都
+可以看出)。例如,要把下面这样改写::
+
+ struct something {
+ ...
+ union {
+ struct type1 one[0];
+ struct type2 two[0];
+ };
+ };
+
+就必须使用辅助宏::
+
+ struct something {
+ ...
+ union {
+ DECLARE_FLEX_ARRAY(struct type1, one);
+ DECLARE_FLEX_ARRAY(struct type2, two);
+ };
+ };
+
+结构体对象的明文 kmalloc 赋值
+----------------------------
+
+直接手写 kmalloc() 系列的内存分配赋值,会妨碍内核(以及编译器)检查被赋值变量的类型,
+从而限制那些有助于对齐、回绕防护以及额外加固的相关内省能力。kmalloc_obj() 系列宏
+提供了这种内省能力,可用于单对象、数组对象以及灵活对象的常见分配写法。例如,下面这
+些手写赋值::
+
+ ptr = kmalloc(sizeof(*ptr), gfp);
+ ptr = kzalloc(sizeof(*ptr), gfp);
+ ptr = kmalloc_array(count, sizeof(*ptr), gfp);
+ ptr = kcalloc(count, sizeof(*ptr), gfp);
+ ptr = kmalloc(struct_size(ptr, flex_member, count), gfp);
+ ptr = kmalloc(sizeof(struct foo), gfp);
+
+分别改写为::
+
+ ptr = kmalloc_obj(*ptr [, gfp] );
+ ptr = kzalloc_obj(*ptr [, gfp] );
+ ptr = kmalloc_objs(*ptr, count [, gfp] );
+ ptr = kzalloc_objs(*ptr, count [, gfp] );
+ ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] );
+ __auto_type ptr = kmalloc_obj(struct foo [, gfp] );
+
+参数 gfp 是可选的,默认值为 GFP_KERNEL。如果 ``ptr->flex_member`` 标注了
+``__counted_by()``,那么当 ``count`` 大于与 ``flex_member`` 关联的计数成员所能表示的
+最大值时,该分配会自动失败。
diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst
index 4fbc2c4eb605..cd02cce21bf0 100644
--- a/Documentation/translations/zh_CN/process/index.rst
+++ b/Documentation/translations/zh_CN/process/index.rst
@@ -67,12 +67,12 @@ TODOLIST:
submit-checklist
researcher-guidelines
contribution-maturity-model
+ deprecated
TODOLIST:
* changes
* kernel-docs
-* deprecated
* maintainers
--
2.43.0
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH v2 3/4] docs/zh_CN: Add backporting translation
2026-11-17 11:55 [PATCH v2 0/4] docs/zh_CN: Add four process translations YikunWei
2026-11-17 11:55 ` [PATCH v2 1/4] docs/zh_CN: Add contribution maturity model translation YikunWei
2026-11-17 11:55 ` [PATCH v2 2/4] docs/zh_CN: Add deprecated translation YikunWei
@ 2026-11-17 11:55 ` YikunWei
2026-11-17 11:55 ` [PATCH v2 4/4] docs/zh_CN: Add botching-up-ioctls translation YikunWei
2026-11-17 14:17 ` [PATCH v2 0/4] docs/zh_CN: Add four process translations Weijie Yuan
4 siblings, 0 replies; 6+ messages in thread
From: YikunWei @ 2026-11-17 11:55 UTC (permalink / raw)
To: alexs; +Cc: si.yanteng, dzm91, linux-doc, Yikun Wei
From: Yikun Wei <YikunWei@126.com>
Translate Documentation/process/backporting.rst into Chinese.
Update translations/zh_CN/process/index.rst to reference the new
translation and drop the item from the TODOLIST.
Signed-off-by: Yikun Wei <YikunWei@126.com>
---
.../zh_CN/process/backporting.rst | 464 ++++++++++++++++++
.../translations/zh_CN/process/index.rst | 2 +-
2 files changed, 465 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/process/backporting.rst
diff --git a/Documentation/translations/zh_CN/process/backporting.rst b/Documentation/translations/zh_CN/process/backporting.rst
new file mode 100644
index 000000000000..334fe5e982ea
--- /dev/null
+++ b/Documentation/translations/zh_CN/process/backporting.rst
@@ -0,0 +1,464 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/process/backporting.rst
+
+:翻译:
+
+ Yikun Wei <YikunWei@126.com>
+
+.. _cn_backporting:
+
+===================================
+补丁回填与冲突解决
+===================================
+
+:Author: Vegard Nossum <vegard.nossum@oracle.com>
+
+.. contents::
+ :local:
+ :depth: 3
+ :backlinks: none
+
+简介
+====
+
+有些开发者在日常工作中可能从来不需要处理补丁回填(backporting)、分支合并或冲突
+解决,因此一旦真遇到合并冲突,往往会让人发怵。所幸,解决冲突和任何其他技能一样,
+是可以练出来的;而且有许多实用的技巧,能让整个过程更顺畅,也让你对结果更有信心。
+
+本文档旨在成为一份全面、循序渐进的补丁回填与冲突解决指南。
+
+将补丁应用到代码树
+==================
+
+有时候你要回填的补丁本身已经是一个 git 提交,这种情况下直接用 ``git cherry-pick``
+把它摘取过来即可。不过,如果该补丁来自一封邮件(Linux 内核的补丁经常如此),你就
+得用 ``git am`` 把它打到代码树上。
+
+如果你用过 ``git am``,大概已经知道它对补丁能否干净地打到源码树上相当挑剔。事实上,
+你可能还对 ``.rej`` 文件、以及为了能让补丁打上而手动去改补丁的噩梦记忆犹新。
+
+强烈建议的做法是:先找一个能让补丁干净应用的合适基线版本,*然后* 再把它摘取到你的
+目标代码树上。这样一来,Git 就会输出冲突标记,让你能够借助 Git 以及任何你偏好的
+冲突解决工具来解决问题。例如,如果你想把一个刚发到 LKML 上的补丁应用到较旧的稳定
+内核,可以先把它打到最新的主线内核上,再摘取到你的旧稳定分支。
+
+一般来说,使用和补丁原本生成时所基于的版本完全一致的基础更好;但只要能干净地打上、
+且与原始基线相差不算太远,其实差别不大。把补丁打到“错误”的基线上,唯一的问题在于:
+当你把它摘取到旧分支时,diff 的上下文里可能会混入更多不相干的改动。
+
+相比 ``git am``,更推荐 ``git cherry-pick`` 的一个理由是:Git 掌握着一个已有提交的
+确切历史,因此当代码被移动过、行号发生变化时它也能知晓;这反过来又降低了把补丁打错
+位置的概率(打错位置可能导致隐蔽的错误,或产生一团乱麻般的冲突)。
+
+如果你正在使用 `b4`_,并且是直接从一个邮件来应用补丁,那么可以配合 ``-g``/
+``--guess-base`` 与 ``-3``/``--prep-3way`` 选项来让 b4 自动完成上述部分工作(更多
+信息请参阅 `b4 presentation`_)。不过,本文其余部分都假定你是在做一次普通的
+``git cherry-pick``。
+
+一旦把补丁放进 Git,就可以着手把它摘取到你的源码树里了。如果你想留下该补丁来自
+何处的书面记录,别忘了在摘取时加上 ``-x``!
+
+注意,如果你是为 stable 提交补丁,格式会略有不同;主题行之后的第一行需要是::
+
+ commit <upstream commit> upstream
+
+或者::
+
+ [ Upstream commit <upstream commit> ]
+
+解决冲突
+========
+
+哎呀,摘取失败了,还附带一条颇有些吓人的信息::
+
+ CONFLICT (content): Merge conflict
+
+现在该怎么办?
+
+一般来说,当补丁的上下文(也就是被修改的行,以及/或者修改点周围的行)与你试图把
+补丁打上去的那棵树对不上时,冲突就会出现。
+
+对于回填而言,更可能的情况是:你从中回填的分支里,包含了目标分支所没有的某些补丁。
+不过,反过来也有可能。无论如何,结果都是一个需要解决的冲突。
+
+如果你尝试的摘取因冲突而失败,Git 会自动修改相关文件,插入所谓的“冲突标记”,告诉
+你冲突在哪里、两个分支又是如何分道扬镳的。解决冲突通常意味着:编辑出最终结果,使之
+兼顾其他那些提交。
+
+解决冲突既可以徒手在普通文本编辑器里完成,也可以使用专门的冲突解决工具。
+
+许多人更习惯用自己平常用的文本编辑器直接编辑冲突,因为这样更容易理解自己在做什么、
+也更容易掌控最终结果。两种方法各有优劣,有时两者结合使用也很有价值。
+
+这里我们不打算介绍各类专用合并工具的使用,只给出一些可供选用的工具线索:
+
+- `Emacs Ediff mode <https://www.emacswiki.org/emacs/EdiffMode>`__
+- `vimdiff/gvimdiff <https://linux.die.net/man/1/vimdiff>`__
+- `KDiff3 <http://kdiff3.sourceforge.net/>`__
+- `TortoiseMerge <https://tortoisesvn.net/TortoiseMerge.html>`__
+- `Meld <https://meldmerge.org/help/>`__
+- `P4Merge <https://www.perforce.com/products/helix-core-apps/merge-diff-tool-p4merge>`__
+- `Beyond Compare <https://www.scootersoftware.com/>`__
+- `IntelliJ <https://www.jetbrains.com/help/idea/resolve-conflicts.html>`__
+- `VSCode <https://code.visualstudio.com/docs/editor/versioncontrol>`__
+
+要配置 Git 来配合这些工具,请参阅 ``git mergetool --help`` 或官方的
+`git-mergetool documentation`_。
+
+前置补丁
+--------
+
+大多数冲突之所以发生,是因为你所要回填到的分支,相比你从中回填的分支少了若干补丁。
+在更一般的情况下(比如合并两个互不相干的分支),开发可能发生在任意一条分支上,或者
+两条分支干脆就分叉了——也许你的旧分支上已经打过别的回填补丁,而那些补丁本身就需要
+解决冲突,从而造成了分叉。
+
+始终弄清楚究竟是哪一次(或哪几次)提交引发了冲突,这一点非常重要,否则你无法对解决
+结果的正确性有信心。额外的好处是:尤其是当你对出问题的代码区域并不熟悉时,这些提交的
+改变日志(changelog)往往能给你提供理解这段代码、以及认清你的冲突解决方案可能存在的
+问题或陷阱所需的背景。
+
+git log
+~~~~~~~
+
+一个不错的起点,是查看出现冲突的那个文件的 ``git log``——当该文件改动不多时,这通常
+就足够了;但如果文件很大、且经常被打补丁,结果可能会让人一头雾水。你应当针对当前所在
+分支(``HEAD``)与你所摘取的补丁的父提交(``<commit>``)之间的提交区间来运行
+``git log``,即::
+
+ git log HEAD..<commit>^ -- <path>
+
+更好的是,如果你只想把输出限定在某个函数内(因为冲突正是出现在那里),可以使用下面
+这样的语法::
+
+ git log -L:'\<function\>':<path> HEAD..<commit>^
+
+.. note::
+ 函数名两侧的 ``\<`` 与 ``\>`` 用于确保匹配锚定在单词边界上。这一点很重要,因为
+ 这部分其实是一个正则表达式,而 git 只取第一个匹配;所以如果你写
+ ``-L:thread_stack:kernel/fork.c``,即使该文件中还有许多其他名字里含有
+ ``thread_stack`` 字符串的函数,它可能也只会给你
+ ``try_release_thread_stack_to_cache`` 这个函数的结果。
+
+``git log`` 另一个有用的选项是 ``-G``,它可以让你按“出现在所列提交 diff 中的某些
+字符串”来过滤::
+
+ git log -G'regex' HEAD..<commit>^ -- <path>
+
+这也是一种快速定位“某样东西(比如一次函数调用或一个变量)是何时被改动、新增或删除”
+的便捷方式。搜索字符串是正则表达式,这意味着你甚至能搜得更具体,比如对某个结构体
+成员的赋值::
+
+ git log -G'\->index\>.*='
+
+git blame
+~~~~~~~~~
+
+另一种寻找前置提交的办法(尽管对每个冲突只能找到最近的那一次)是运行 ``git blame``。
+这种情况下,你需要针对你所摘取的补丁的父提交、以及出现冲突的文件来运行它,即::
+
+ git blame <commit>^ -- <path>
+
+这个命令也接受 ``-L`` 参数(用于把输出限定在单个函数内),不过此时你要像平常一样把
+文件名放在命令末尾::
+
+ git blame -L:'\<function\>' <commit>^ -- <path>
+
+定位到冲突发生的地方。blame 输出的第一列,就是新增那行代码的补丁的提交 ID。
+
+你不妨 ``git show`` 这些提交,看看它们是否像引发冲突的源头。有时这样的提交不止一个,
+原因可能是多个提交修改了同一冲突区域的不同行,*或者* 多个后续补丁对同一行(或几行)
+反复修改过。在后一种情况下,你可能需要再次运行 ``git blame``,并指定该文件的较旧版本
+来查看,以便向文件历史更深处追溯。
+
+前置补丁与偶然补丁
+~~~~~~~~~~~~~~~~~~
+
+找到引发冲突的补丁之后,你需要判断它究竟是你要回填的补丁的*前置条件*,还是仅仅是个
+*偶然* 存在、可以跳过的补丁。所谓偶然补丁,指的是它触碰了与你回填补丁相同的代码,但
+并没有以任何实质方式改变代码的语义。例如,一次空白符清理补丁完全是偶然的——同理,仅仅
+是重命名某个函数或变量的补丁也是偶然的。另一方面,如果那个被修改的函数在你的当前分支
+里根本就不存在,那这绝不只是偶然,你需要仔细考虑:是否应当先把新增该函数的那个补丁
+摘取过来。
+
+如果你发现存在必要的前置补丁,就需要停下来,改为先把它摘取过来。如果你已经在另一个
+文件里解决了若干冲突、不想重来一遍,可以先给那个文件做个临时副本。
+
+要中止当前的摘取,直接运行 ``git cherry-pick --abort``,然后用前置补丁的提交 ID 重新
+开始摘取过程。
+
+理解冲突标记
+------------
+
+组合 diff
+~~~~~~~~~
+
+假设你已经决定不再去摘取(或回退)额外的补丁,只想解决眼前的冲突。Git 会在你的文件里
+插入冲突标记。开箱即用时,它看起来大致像这样::
+
+ <<<<<<< HEAD
+ this is what's in your current tree before cherry-picking
+ =======
+ this is what the patch wants it to be after cherry-picking
+ >>>>>>> <commit>... title
+
+这就是你在编辑器里打开文件时会看到的内容。然而,如果你不带任何参数地运行 ``git diff``,
+输出则会像这样::
+
+ $ git diff
+ [...]
+ ++<<<<<<<< HEAD
+ +this is what's in your current tree before cherry-picking
+ ++========
+ + this is what the patch wants it to be after cherry-picking
+ ++>>>>>>>> <commit>... title
+
+在解决冲突时,``git diff`` 的行为与平时不同。注意这里有两列 diff 标记,而非常见的一
+列;这就是所谓的“`combined diff`_”,此处展示的是三方 diff(或者说 diff 的 diff),
+介于:
+
+#. 当前分支(摘取前)与当前工作目录之间,以及
+#. 当前分支(摘取前)与“原补丁应用之后”的文件之间。
+
+更清晰的 diff
+~~~~~~~~~~~~
+
+三方的组合 diff 包含了你的当前分支与你所摘取的分支之间,该文件发生的所有其他改动。
+虽然这有助于发现你需要兼顾的其他改动,但也让 ``git diff`` 的输出显得有些吓人、难以
+阅读。你或许更愿意运行 ``git diff HEAD``(或 ``git diff --ours``),它只展示当前
+分支(摘取前)与当前工作目录之间的差异。它看起来像这样::
+
+ $ git diff HEAD
+ [...]
+ +<<<<<<<< HEAD
+ this is what's in your current tree before cherry-picking
+ +========
+ +this is what the patch wants it to be after cherry-picking
+ +>>>>>>>> <commit>... title
+
+如你所见,读起来就和任何别的 diff 一样,并且清楚地表明哪些行属于当前分支、哪些行是
+作为合并冲突或所摘取补丁的一部分而被加入的。
+
+合并风格与 diff3
+~~~~~~~~~~~~~~~
+
+上面展示的默认冲突标记风格被称为 ``merge`` 风格。此外还有另一种风格,叫做 ``diff3``
+风格,看起来像这样::
+
+ <<<<<<< HEAD
+ this is what is in your current tree before cherry-picking
+ ||||||| parent of <commit> (title)
+ this is what the patch expected to find there
+ =======
+ this is what the patch wants it to be after being applied
+ >>>>>>> <commit> (title)
+
+如你所见,它有三段而非两段,并且包含了 Git 本期望在那里找到、却没找到的内容。*强烈
+推荐* 使用这种冲突风格,因为它能更清楚地展示该补丁究竟改了什么;也就是说,它能让你
+对所摘取提交的文件“修改前/修改后”两个版本做对比。这有助于你对如何解决冲突做出更好的
+判断。
+
+要切换冲突标记风格,可以使用如下命令::
+
+ git config merge.conflictStyle diff3
+
+还有第三个选项 ``zdiff3``,在 `Git 2.35`_ 中引入,它和 ``diff3`` 一样有三段,但会把
+公共行裁掉,从而在某些情况下缩小冲突区域。
+
+迭代式解决冲突
+--------------
+
+任何冲突解决过程的第一步,都是先理解你要回填的补丁。对于 Linux 内核而言这一点尤为
+重要,因为一处不正确的改动可能导致整个系统崩溃——甚至更糟,埋下一个未被察觉的安全
+漏洞。
+
+理解补丁的难易,取决于补丁本身、它的改变日志,以及你对所改代码的熟悉程度。不过,对
+每一处改动(或补丁的每一个 hunk)都可以问一个好问题:“这个 hunk 为什么会出现在补丁
+里?”这些问题的答案,将指导你的冲突解决。
+
+解决流程
+~~~~~~~~
+
+有时最简单的做法,就是把冲突中除第一部分以外的部分全部删掉,让文件基本保持原样,然后
+徒手把改动应用上去。举例来说,假设某次冲突改动把一个函数调用参数从 ``0`` 改成了
+``1``,而与之冲突的另一处改动则在参数列表末尾新增了一个完全无关紧要的参数;这种情况
+下,徒手把参数从 ``0`` 改成 ``1``、其余参数原样保留即可。这种“手动应用改动”的技巧,
+在冲突牵扯进大量你其实无需关心的上下文时尤其有用。
+
+对于带有大量冲突标记、尤其棘手的冲突,你可以用 ``git add`` 或 ``git add -i`` 有选择
+地暂存你的解决方案,把它们从待办中挪开;这也让你能用 ``git diff HEAD`` 随时查看还有
+哪些没解决,或用 ``git diff --cached`` 查看当前补丁长什么样。
+
+处理文件重命名
+~~~~~~~~~~~~~~
+
+回填补丁时最恼人的一件事,就是发现被修补的某个文件已经被重命名了,因为那通常意味着
+Git 连冲突标记都不会插入,而只是摊开两手说(意译):“未合并的路径!你来干活……”
+
+一般有几招可以应对。如果被重命名文件的补丁很小,比如只有一行改动,最简单就是直接徒手
+把它改上、了事。反之,如果改动很大或很复杂,你肯定不想手动去做。
+
+作为第一步,你可以试试类似下面的命令,它会把重命名检测的阈值降到 30%(默认情况下 Git
+用 50%,也就是说两个文件至少要有一半以上内容相同,Git 才会把一对“新增+删除”视为可能
+的重命名)::
+
+ git cherry-pick -strategy=recursive -Xrename-threshold=30
+
+有时正确的做法是:把那个做了重命名的补丁也一并回填,但这绝对不是最常见的情况。你真正
+可以做的,是在你要回填到的分支里临时把那个文件重命名(用 ``git mv`` 并提交结果),
+重新尝试摘取该补丁,再把文件改回原名(再次 ``git mv`` 并提交),最后用 ``git rebase
+-i`` 把结果压成一个提交(参见 `rebase tutorial`_),这样完成时它看起来就像一个单独的
+提交。
+
+注意事项
+--------
+
+函数参数
+~~~~~~~~
+
+注意函数参数的变化!人们很容易一扫而过、以为两行相同,实则它们在某个小细节上并不一样,
+比如究竟把哪个变量作为实参传了进去(尤其是当两个变量都是长得几乎一样的单个字符时,
+比如 i 和 j)。
+
+错误处理
+~~~~~~~~
+
+如果你摘取的补丁里包含一条 ``goto`` 语句(通常用于错误处理),那么绝对有必要仔细核查:
+在你回填到的分支里,它跳转的目标标签是否依然正确。对于新增的 ``return``、``break``
+和 ``continue`` 语句,道理相同。
+
+错误处理通常位于函数的末尾,因此即便它被其他补丁改动过,也可能并不属于冲突的一部分。
+
+确保你审查了错误路径的一个好办法,是在检视改动时始终使用 ``git diff -W`` 和
+``git show -W``(也即 ``--function-context``)。对于 C 代码,这会展示出补丁中被改动
+函数的整个函数体。回填过程中经常出错的一点就是:在你从中或向之回填的两条分支上,函数
+里的别处发生了改动。把整个函数纳入 diff,你能获得更多上下文,也更容易发现那些本可能
+被忽略的问题。
+
+被重构的代码
+~~~~~~~~~~~~
+
+相当常见的一件事是:代码通过把一段公共代码序列或模式“抽取”成一个辅助函数而被重构。
+当把补丁回填到一个已经发生过这类重构的区域时,你实际上需要在回填时反其道而行之:某个
+应用到单一位置的补丁,在回填版本里可能需要应用到多个位置。(这种情况的一个征兆是某
+函数被重命名了——但也不总是如此。)
+
+为了避免不完整的回填,值得花点心思去搞清:该补丁修复的 bug 是否出现在不止一处。一个
+办法是用 ``git grep``。(其实这本身是个好主意,不仅限于回填。)如果你确实发现同样的
+修复也适用于别处,那还值得看看这些地方在上游是否存在——如果不存在,那么该补丁很可能
+需要做相应调整。``git log`` 是你弄清这些区域发生了什么的好帮手,因为 ``git blame``
+不会展示已被删除的代码。
+
+如果你在上游树里确实发现了同一模式的其他实例,却不确定它是否也是个 bug,那么去问问
+补丁作者不失为妥当之举。回填过程中发现新 bug 可一点都不罕见!
+
+验证结果
+========
+
+colordiff
+---------
+
+提交了一个无冲突的新补丁之后,你现在可以把自己的补丁和原始补丁做个对比。强烈推荐
+使用像 `colordiff`_ 这样的工具,它能并排展示两个文件,并按它们之间的差异上色::
+
+ colordiff -yw -W 200 <(git diff -W <upstream commit>^-) <(git diff -W HEAD^-) | less -SR
+
+这里,``-y`` 表示做并排对比;``-w`` 忽略空白符;``-W 200`` 设置输出宽度(否则默认用
+130,往往有点偏小)。
+
+``rev^-`` 这种语法是 ``rev^..rev`` 的便捷简写,本质上就是只给出那一次提交的 diff;
+另请参阅官方的 `git rev-parse documentation`_。
+
+再次提醒,注意在 ``git diff`` 里加上 ``-W``;它能确保你看到任何被改动函数的完整
+函数体。
+
+colordiff 一个极其重要的作用,是突出显示不同的行。例如,如果错误处理用的 ``goto`` 在
+原始补丁与回填补丁之间换了标签,colordiff 会把它俩并排展示、却用不同颜色高亮。于是,
+一眼就能看出这两条 ``goto`` 跳转的是不同的标签。同理,那些没有被任一补丁修改、却因
+上下文不同而相异的行,也会被高亮,从而在人工检视时格外显眼。
+
+当然,这终究只是肉眼检查;真正的检验还得靠构建并运行被打过补丁的内核(或程序)。
+
+构建测试
+--------
+
+运行时测试这里就不展开了,但只构建补丁所触及的文件作为快速健全性检查,是个不错的主意。
+对于 Linux 内核,在 ``.config`` 与构建环境都已正确就绪的前提下,你可以像这样单独构建
+某个文件::
+
+ make path/to/file.o
+
+注意,这发现不了链接错误,因此在确认单个文件能编译通过后,你仍应做一次完整构建。先
+编译单个文件,可以避免在(万一)你改动过的文件里存在编译错误时,还得苦等一次完整
+构建。
+
+运行时测试
+----------
+
+即便是成功的构建或启动测试,也未必足以排除某处缺失依赖的可能性。尽管概率很小,但完全
+可能存在这样的代码改动:对同一文件的两处独立改动,既不会产生冲突,也不会引发编译期
+错误,而只在极个别情况下才暴露运行时错误。
+
+一个具体的例子是:有一对针对系统调用入口代码的补丁,第一个保存/恢复了某个寄存器,而
+后一个补丁在这段序列中间的某处用到了同一个寄存器。由于两处改动毫无重叠,你大可以摘取
+第二个补丁、不产生任何冲突,并以为一切安好,而事实上代码此刻正在覆盖一个未被保存的
+寄存器。
+
+尽管绝大多数错误都会在编译期间、或在浅层执行代码时被捕获,但*真正*验证一次回填的唯一
+办法,是以你对待(或应当对待)任何其他补丁的同等级别去审查最终补丁。拥有单元测试、回归
+测试或其他类型的自动化测试,有助于提升对回填正确性的信心。
+
+向 stable 提交回填补丁
+=====================
+
+当 stable 维护者试图把主线修复摘取到他们的稳定内核时,遇到冲突他们可能会发邮件来
+索要回填补丁,例如见
+<https://lore.kernel.org/stable/2023101528-jawed-shelving-071a@gregkh/>。这些邮件
+通常会包含你需要把补丁摘取到正确代码树并提交的确切步骤。
+
+有一件要确保的事,是你的改变日志要符合预期格式::
+
+ <original patch title>
+
+ [ Upstream commit <mainline rev> ]
+
+ <rest of the original changelog>
+ [ <summary of the conflicts and their resolutions> ]
+ Signed-off-by: <your name and email>
+
+“Upstream commit”这一行有时会因 stable 版本不同而略有差异。较旧的版本使用如下格式::
+
+ commit <mainline rev> upstream.
+
+最常见的是在邮件主题行里标明该补丁所适用的内核版本(例如使用
+``git send-email --subject-prefix='PATCH 6.1.y'``),但也可以把它放在 Signed-off-by
+区域附近,或 ``---`` 线以下。
+
+stable 维护者希望对每一个活跃的稳定版本分别提交,而且每次提交也应当分别测试。
+
+最后几点建议
+============
+
+1) 以谦逊之心对待回填过程。
+2) 理解你要回填的补丁;这意味着既要读改变日志,也要读代码。
+3) 提交补丁时,坦诚说明你对其结果有几分把握。
+4) 向相关维护者索要明确的 ack。
+
+示例
+====
+
+上面大致展示了理想化的回填流程。若要一个更具体的例子,请参阅这段把两个补丁从主线回填
+到 stable 的视频教程:`Backporting Linux Kernel Patches`_。
+
+.. _b4: https://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestation
+.. _b4 presentation: https://youtu.be/mF10hgVIx9o?t=2996
+.. _git-mergetool documentation: https://git-scm.com/docs/git-mergetool
+.. _combined diff: https://git-scm.com/docs/diff-format#_combined_diff_format
+.. _rebase tutorial: https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec
+.. _Git 2.35: https://github.blog/2022-01-24-highlights-from-git-2-35/
+.. _colordiff: https://www.colordiff.org/
+.. _git rev-parse documentation: https://git-scm.com/docs/git-rev-parse#_other_rev_parent_shorthand_notations
+.. _Backporting Linux Kernel Patches: https://youtu.be/sBR7R1V2FeA
diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst
index cd02cce21bf0..0913e0f5e72a 100644
--- a/Documentation/translations/zh_CN/process/index.rst
+++ b/Documentation/translations/zh_CN/process/index.rst
@@ -84,12 +84,12 @@ TODOLIST:
magic-number
applying-patches
volatile-considered-harmful
+ backporting
../arch/riscv/patch-acceptance
../core-api/unaligned-memory-access
TODOLIST:
-* backporting
* adding-syscalls
* botching-up-ioctls
* clang-format
--
2.43.0
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH v2 4/4] docs/zh_CN: Add botching-up-ioctls translation
2026-11-17 11:55 [PATCH v2 0/4] docs/zh_CN: Add four process translations YikunWei
` (2 preceding siblings ...)
2026-11-17 11:55 ` [PATCH v2 3/4] docs/zh_CN: Add backporting translation YikunWei
@ 2026-11-17 11:55 ` YikunWei
2026-11-17 14:17 ` [PATCH v2 0/4] docs/zh_CN: Add four process translations Weijie Yuan
4 siblings, 0 replies; 6+ messages in thread
From: YikunWei @ 2026-11-17 11:55 UTC (permalink / raw)
To: alexs; +Cc: si.yanteng, dzm91, linux-doc, Yikun Wei
From: Yikun Wei <YikunWei@126.com>
Translate Documentation/process/botching-up-ioctls.rst into Chinese.
Update translations/zh_CN/process/index.rst to reference the new
translation and drop the item from the TODOLIST.
Signed-off-by: Yikun Wei <YikunWei@126.com>
---
.../zh_CN/process/botching-up-ioctls.rst | 186 ++++++++++++++++++
.../translations/zh_CN/process/index.rst | 2 +-
2 files changed, 187 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/process/botching-up-ioctls.rst
diff --git a/Documentation/translations/zh_CN/process/botching-up-ioctls.rst b/Documentation/translations/zh_CN/process/botching-up-ioctls.rst
new file mode 100644
index 000000000000..0e8985a9fcb6
--- /dev/null
+++ b/Documentation/translations/zh_CN/process/botching-up-ioctls.rst
@@ -0,0 +1,186 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/process/botching-up-ioctls.rst
+
+:翻译:
+
+ Yikun Wei <YikunWei@126.com>
+
+.. _cn_botching_up_ioctls:
+
+=================================
+(如何避免)搞砸 ioctl
+=================================
+
+From: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html
+
+By: Daniel Vetter, Copyright © 2013 Intel Corporation
+
+过去几年里,内核图形领域的开发者们得到一个明确的认识:试图设计一套统一的接口,
+在完全不同的 GPU 上管理执行单元和内存,是徒劳的。所以如今每个驱动都有自己一套
+ioctl 来分配内存、向 GPU 提交任务。这挺好的,因为不再有那种假通用、实际却只用
+一次的蹩脚接口。但明显的缺点是,把事情搞砸的可能性大大增加了。
+
+为了避免把所有同样的错误再犯一遍,我写下一些在为 drm/i915 驱动干活(并把事情
+搞砸)的过程中学到的经验教训。其中大多数只涉及技术细节,而非大局问题,比如
+命令提交 ioctl 究竟应该长什么样。学习这些教训,恐怕是每个 GPU 驱动都得自己走
+一遍的过程。
+
+
+前提条件
+--------
+
+首先是前提条件。缺了这些你就已经失败了,因为你将需要添加一个 32 位兼容层:
+
+ * 只使用固定大小的整数。为避免与用户空间的 typedef 冲突,内核提供了 __u32、
+ __s64 这样的特殊类型。请使用它们。
+
+ * 让所有内容按自然大小对齐,并使用显式填充。32 位平台不一定把 64 位值按
+ 64 位边界对齐,但 64 位平台会。所以我们总是需要按自然大小填充,才能把它
+ 做对。
+
+ * 如果结构体包含 64 位类型,就把整个结构体填充到 64 位的整数倍——否则结构体
+ 大小在 32 位和 64 位上会不同。当把结构体数组传给内核时,或者当内核检查
+ 结构体大小时(例如 drm 核心就会这么做),结构体大小不一致会造成麻烦。
+
+ * 指针用 __u64,在用户空间侧与 uintptr_t 相互转换,在内核侧与 void __user *
+ 相互转换。务必尽量不要推迟这种转换,更糟糕的是别把原始的 __u64 在你的代码
+ 里到处乱传,因为那会削弱 sparse 之类检查工具的作用。内核里可以用
+ u64_to_user_ptr 宏来避免关于整数和指针大小不同的警告。
+
+
+基础
+----
+
+免去了编写兼容层的乐趣之后,我们可以看看一些基础性的错误。忽视这些会让向后和
+向前兼容性变成真正的痛苦。而且由于第一次尝试就做对几乎是不可能的,所以对于任何
+一个给定的接口,你都会有第二次迭代,或者至少是一次扩展。
+
+ * 要有清晰的方法让用户空间判断某个内核是否支持你的新 ioctl 或 ioctl 扩展。
+ 如果你不能指望旧内核拒绝新的标志位/模式或 ioctl(因为过去这一点被搞砸了),
+ 那么你需要在某处提供一个驱动特性标志或版本号。
+
+ * 要有一个用新标志位或在结构体末尾新增字段来扩展 ioctl 的计划。drm 核心会
+ 检查每次 ioctl 调用传入的大小,并对内核与用户空间之间的不一致做零扩展。
+ 这有帮助,但不是一个完整的解决方案,因为旧内核上的新用户空间不会注意到
+ 末尾新增的字段被忽略了。所以这仍然需要一个新的驱动特性标志。
+
+ * 检查所有未使用的字段和标志位、以及所有填充位是否为 0,若不是则拒绝该
+ ioctl。否则你那个漂亮的未来扩展计划就泡汤了,因为总会有人提交一个 ioctl
+ 结构体,其尚未使用的部分塞满了随机的栈垃圾。这随后就把 ABI 固化成:这些
+ 字段除了垃圾之外永远不能用于其他用途。这也是为什么你必须显式填充所有
+ 结构体,即使你从不把它们用在数组里——编译器可能插入的填充位也许含有垃圾。
+
+ * 为以上所有情况准备简单的测试用例。
+
+
+错误路径的乐趣
+--------------
+
+如今我们再也找不到借口让 drm 驱动变成精巧的本地提权漏洞了。这意味着我们既需要
+完整的输入校验,也需要可靠的错误处理路径——GPU 总会在最古怪的边界情况下死掉:
+
+ * ioctl 必须检查数组溢出。还需要检查整数值的上溢/下溢和截断问题。常见的例子
+ 是精灵(sprite)定位值被直接喂给硬件,而硬件只有大约 12 位。这本来工作得
+ 很好,直到某个古怪的显示服务器懒得自己做截断,光标就绕回到屏幕另一边了。
+
+ * 为 ioctl 中每一种输入校验失败的情况准备简单的测试用例。检查错误码是否符合
+ 预期。最后要确保你在每个子测试里只测试单一的错误路径,提交的数据在其他方面
+ 都完全有效。否则,前面某个检查可能早就拒绝了这个 ioctl,从而遮蔽了你真正
+ 想测试的代码路径,隐藏了 bug 和回归。
+
+ * 让你所有的 ioctl 都可重启(restartable)。首先 X 非常喜欢信号,其次这将让
+ 你只需不断用信号打断主测试套件,就能测试 90% 的错误处理路径。多亏了 X 对
+ 信号的偏爱,对于图形驱动来说,你几乎可以免费获得所有错误路径的出色基础
+ 覆盖率。另外,处理 ioctl 重启的方式要保持一致——例如 drm 在其用户空间库中
+ 有一个小小的 drmIoctl 辅助函数。i915 驱动在 set_tiling ioctl 上搞砸了这一点,
+ 现在我们在内核和用户空间里都被某些晦涩的语义永远困住了。
+
+ * 如果你无法让某条代码路径可重启,至少要让卡住的任务可被杀死。GPU 就是会死机,
+ 如果你的驱动把整台机器都挂住(通过一个杀不掉的 X 进程),用户可不会更喜欢你。
+ 如果状态恢复仍然太棘手,就加一个超时或 hangcheck 安全网作为最后手段,以防
+ 硬件彻底发疯。
+
+ * 为错误恢复代码中真正棘手的边界情况准备测试用例——在 hangcheck 代码和等待者
+ 之间造成死锁,实在太容易了。
+
+
+时间、等待与错过
+----------------
+
+GPU 绝大部分工作都是异步完成的,所以我们需要给操作计时、并等待尚未完成的操作。
+这可是件相当棘手的事;目前 drm/i915 支持的 ioctl 没有一个是完全做对了这一点的,
+这意味着这里还有大量的教训等着我们去学。
+
+ * 始终使用 CLOCK_MONOTONIC 作为你的参考时间。如今这是 alsa、drm 和 v4l 默认
+ 采用的。但要让用户空间知道,哪些时间戳来自不同的时钟域,比如你的主系统时钟
+ (由内核提供)或别处某个独立的硬件计数器。只要看得足够仔细,时钟总会对不上,
+ 但如果性能测量工具掌握这些信息,它们至少可以做出补偿。如果你的用户空间能够
+ 拿到某些时钟的原始值(例如通过命令流内的性能计数器采样指令),不妨考虑把这些
+ 值也暴露出来。
+
+ * 用 __s64 秒加 __u64 纳秒来指定时间。这不是最方便的时间表示方式,但基本是
+ 事实上的标准。
+
+ * 检查输入的时间值是否已归一化,若否则拒绝。注意内核原生的 struct ktime 对秒
+ 和纳秒都使用有符号整数,所以要当心。
+
+ * 对于超时,使用绝对时间。如果你是个好人、把 ioctl 做成了可重启的,那么相对
+ 超时往往太粗糙,会因为每次重启时的取整而无限延长你的等待时间。尤其是当你的
+ 参考时钟是显示帧计数器这种非常慢的东西时。从一个钻牛角尖的规范律师角度看,
+ 这不算 bug——毕竟超时总是可以被延长的——但如果用户漂亮的动画因此开始卡顿,
+ 他们肯定会恨死你。
+
+ * 考虑干脆抛弃所有带超时的同步等待 ioctl,改为在一个可 poll 的文件描述符上
+ 投递异步事件。这样能更好地融入事件驱动应用的主循环。
+
+ * 为边界情况准备测试用例,尤其是已经完成的事件、成功的等待和超时的等待这几种
+ 情况的返回值是否都合理、且符合你的需要。
+
+
+不泄漏资源
+----------
+
+一个完整的 drm 驱动本质上实现了一个小型操作系统,只不过是专用于特定 GPU 平台的。
+这意味着驱动需要向用户空间暴露大量不同对象和其他资源的句柄。要把这件事做对,
+自有其一套小小的陷阱:
+
+ * 始终把动态创建资源的生命周期绑定到某个文件描述符的生命周期上。如果你的资源
+ 需要跨进程共享,可以考虑采用 1:1 的映射——通过 UNIX 域套接字传递 fd 也能简化
+ 用户空间的生命周期管理。
+
+ * 始终支持 O_CLOEXEC。
+
+ * 确保不同客户端之间有充分的隔离。默认情况下选择私有的、每 fd 一个的命名空间,
+ 强制任何共享都必须显式进行。只有当对象确实是设备唯一的时候,才采用更全局的
+ 每设备命名空间。drm modeset 接口里有一个反例:per-device 的 modeset 对象(如
+ connector)与 framebuffer 对象共享同一个命名空间,而后者大多根本不共享。为
+ framebuffer 单独设一个默认私有的命名空间会更合适。
+
+ * 想清楚用户空间句柄的唯一性要求。例如对大多数 drm 驱动来说,在同一次命令提交
+ ioctl 里两次提交同一个对象是用户空间的 bug。但如果对象是可共享的,用户空间
+ 就需要知道自己是否已经见过某个从别的进程导入的对象。我自己还没试过这个做法,
+ 因为缺一类新的对象,但可以考虑用共享文件描述符的 inode 号作为唯一标识符——
+ 真正的文件也是这样区分的。可惜这需要在内核里实现一个完整的文件系统。
+
+
+最后但并非最不重要
+------------------
+
+并非每个问题都需要一个新的 ioctl:
+
+ * 仔细想想你是否真的想要一个驱动私有接口。当然,推送一个驱动私有接口,比为了
+ 一个更通用的方案展开漫长讨论要快得多。偶尔搞一个私有接口来为某个新概念打头阵,
+ 也确实是需要的。但最终,一旦通用接口出现,你将不得不无限期地维护两个接口。
+
+ * 考虑 ioctl 之外的其他接口。对于每设备设置,或者对于生命周期相当静态的子对象
+ (比如 drm 里带各种检测覆盖属性的输出连接器),sysfs 属性要好得多。又或许只有
+ 你的测试套件需要这个接口,那么用 debugfs 更合适,它本身就声明了不保证稳定的
+ ABI。
+
+最后,这场游戏的要点是第一次就把它做对,因为如果你的驱动流行起来、硬件平台又
+长命百岁,那么你就基本上会被某个 ioctl 永远困住。你可以尝试在更新一代的硬件上
+弃用那些糟糕的 ioctl,但一般来说这要花上好几年。然后还要再等好几年,直到最后
+一个还能抱怨回归的用户也消失为止。
diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst
index 0913e0f5e72a..9f657597b3f9 100644
--- a/Documentation/translations/zh_CN/process/index.rst
+++ b/Documentation/translations/zh_CN/process/index.rst
@@ -85,13 +85,13 @@ TODOLIST:
applying-patches
volatile-considered-harmful
backporting
+ botching-up-ioctls
../arch/riscv/patch-acceptance
../core-api/unaligned-memory-access
TODOLIST:
* adding-syscalls
-* botching-up-ioctls
* clang-format
.. only:: subproject and html
--
2.43.0
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH v2 0/4] docs/zh_CN: Add four process translations
2026-11-17 11:55 [PATCH v2 0/4] docs/zh_CN: Add four process translations YikunWei
` (3 preceding siblings ...)
2026-11-17 11:55 ` [PATCH v2 4/4] docs/zh_CN: Add botching-up-ioctls translation YikunWei
@ 2026-11-17 14:17 ` Weijie Yuan
4 siblings, 0 replies; 6+ messages in thread
From: Weijie Yuan @ 2026-11-17 14:17 UTC (permalink / raw)
To: YikunWei; +Cc: alexs, si.yanteng, dzm91, linux-doc
On Tue, Nov 17, 2026 at 07:55:21PM +0800, YikunWei wrote:
> From: Yikun Wei <YikunWei@126.com>
>
> Changes in v2:
> - Reformat contribution-maturity-model.rst to align line lengths with the
> English source and restore the link to the 2021 Maintainers' Summit
> discussion, as pointed out by Dongliang Mu.
> - Send all four translations as a single patchset instead of separate
> patches, since they share dependent changes to the process index.rst.
>
> This series adds Chinese translations for four documents under
> Documentation/process/: the contribution maturity model, deprecated
> interfaces, backporting, and ioctl pitfalls. Index entries are updated
> accordingly.
>
> Yikun Wei (4):
> docs/zh_CN: Add contribution maturity model translation
> docs/zh_CN: Add deprecated translation
> docs/zh_CN: Add backporting translation
> docs/zh_CN: Add botching-up-ioctls translation
Thanks for turning them into a series, please notice that Sphinx
complains:
| Documentation/translations/zh_CN/process/backporting.rst:227: WARNING: Title underline too short.
|
| 更清晰的 diff
| ~~~~~~~~~~~~ [docutils]
| Documentation/translations/zh_CN/process/backporting.rst:246: WARNING: Title underline too short.
|
| 合并风格与 diff3
| ~~~~~~~~~~~~~~~ [docutils]
| Documentation/translations/zh_CN/process/backporting.rst:415: WARNING: Title underline too short.
|
| 向 stable 提交回填补丁
| ===================== [docutils]
| Documentation/translations/zh_CN/process/deprecated.rst:103: WARNING: Title underline too short.
|
| simple_strtol()、simple_strtoll()、simple_strtoul()、simple_strtoull()
| ------------------------------------------------------------------- [docutils]
| Documentation/translations/zh_CN/process/deprecated.rst:172: WARNING: Title underline too short.
|
| 变长数组(VLA)
| -------------- [docutils]
| Documentation/translations/zh_CN/process/deprecated.rst:182: WARNING: Title underline too short.
|
| switch case 的隐式贯穿(fall-through)
| ------------------------------------- [docutils]
| Documentation/translations/zh_CN/process/deprecated.rst:336: WARNING: Title underline too short.
|
| 结构体对象的明文 kmalloc 赋值
| ---------------------------- [docutils]
After fixing them locally, please wait for the subsequent reviews before
sending out your v3.
Thanks.
> .../zh_CN/process/backporting.rst | 464 ++++++++++++++++++
> .../zh_CN/process/botching-up-ioctls.rst | 186 +++++++
> .../process/contribution-maturity-model.rst | 83 ++++
> .../translations/zh_CN/process/deprecated.rst | 361 ++++++++++++++
> .../translations/zh_CN/process/index.rst | 8 +-
> 5 files changed, 1098 insertions(+), 4 deletions(-)
> create mode 100644 Documentation/translations/zh_CN/process/backporting.rst
> create mode 100644 Documentation/translations/zh_CN/process/botching-up-ioctls.rst
> create mode 100644 Documentation/translations/zh_CN/process/contribution-maturity-model.rst
> create mode 100644 Documentation/translations/zh_CN/process/deprecated.rst
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2026-11-17 14:17 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-17 11:55 [PATCH v2 0/4] docs/zh_CN: Add four process translations YikunWei
2026-11-17 11:55 ` [PATCH v2 1/4] docs/zh_CN: Add contribution maturity model translation YikunWei
2026-11-17 11:55 ` [PATCH v2 2/4] docs/zh_CN: Add deprecated translation YikunWei
2026-11-17 11:55 ` [PATCH v2 3/4] docs/zh_CN: Add backporting translation YikunWei
2026-11-17 11:55 ` [PATCH v2 4/4] docs/zh_CN: Add botching-up-ioctls translation YikunWei
2026-11-17 14:17 ` [PATCH v2 0/4] docs/zh_CN: Add four process translations Weijie Yuan
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox