今日重点:📖 阅读——内核里有一类改动最难推:给既有代码立一条新规矩。 规矩本身一句话能说完,难的是让十几个子系统的维护者都认账。Google Ian Rogers 的 [PATCH v3 0/9] Add __must_init and require explicit kobj_type::release 就是一封立规矩的 cover letter:先立编译器属性,再引官方文档当依据,最后公布「执法结果」。 精读它的三段论证结构。
📖 阅读:机制定义 + 一段命名考古
/ sectionClang supports the 'require_explicit_initialization' attribute on struct fields to enforce that the field is explicitly initialized when an aggregate object is constructed, emitting -Wuninitialized-explicit-init (enabled by default) if the field is omitted. Following discussion at the Linux Plumbers Conference [1], patch 1 adds the attribute to include/linux/compiler_attributes.h as __must_init. In v1 it was called __require_explicit_initialization. Kees picked up that patch with a first seq_file user [2], and in that thread Greg suggested the shorter __must_init spelling, which Kees and Miguel agreed to. As the attribute did not land in the v7.4 merge window, Kees asked that this series carry the renamed attribute.
第一段是「机制说明」的标准骨架:主句 Clang supports the ... attribute on struct fields 给属性落户(谁的特性、作用于什么),不定式 to enforce that ... 说强制什么,现在分词 emitting -Wuninitialized-explicit-init ... if the field is omitted 补违规后果——支持什么 → 强制什么 → 漏了会怎样,三拍 一段说完。写机制定义时照这个骨架套,不会漏要素。
第二段是一段「命名考古」,也是三个社区高频动词的现场教学。Kees picked up that patch——pick up 是「维护者把别人的补丁接手进自己的 分支」,不是捡起;Greg suggested the shorter __must_init spelling, which Kees and Miguel agreed to——改名不是作者拍的板,是 Greg 提议、两位维护者附议; the attribute did not land in the v7.4 merge window——land 专指「赶进合并窗落地」;收尾 Kees asked that this series carry the renamed attribute——carry 是「本系列捎带」。四个动词把「一个名字怎么被社区 讨论出来」讲得明明白白,也把立规矩的正当性顺手建立了:这不是我一个人的主意。
📖 阅读:引文档立规 + 公布「执法结果」
/ columnAs Documentation/core-api/kobject.rst notes: "One important point cannot be overstated: every kobject must have a release() method, and the kobject must persist (in a consistent state) until that method is called. If these constraints are not met, the code is flawed." Annotating struct kobj_type::release caught struct kobj_type definitions across the tree that omitted .release: - Patches 2-8 fix struct kobj_type definitions where dynamically allocated kobjects, ksets, or enclosing structures were either leaked on kobject_put(), freed prematurely before kobject release, or missing proper static initializers. - Patch 9 annotates struct kobj_type::release with __must_init and explicitly sets .release = NULL (with explanatory comments prefixed with "Pre-existing:") on the remaining legacy struct kobj_type definitions whose kobjects are static, per-CPU, permanent firmware structures, or embedded in devm- or parent-managed allocations.
先引「宪法」再执法。As Documentation/core-api/kobject.rst notes: 加一段逐字引用——cover letter 里引用官方文档,等于给改动找宪法依据:规矩不是我 定的,是文档里一直写着的,我只是让它可被编译器检查。这段引文本身也值得背: cannot be overstated(再怎么强调也不为过)是强调句的天花板;收尾 the code is flawed 四个字下判词,不带脏字但毫无余地——文档措辞里罕见的 强硬,被作者精准地借用了。
执法结果一句开场:Annotating struct kobj_type::release caught struct kobj_type definitions across the tree that omitted .release——主语是 「标注」这个动作,谓语 caught(抓到)用得极妙:标注像撒网,网住的全是 既有问题,仿佛它们自己游了进来。接着 either leaked on kobject_put(), freed prematurely before kobject release, or missing proper static initializers 把三类故障排比列出——漏释放、提前释放、压根没初始化,一对反义加一个缺省, 评审一看就知道这张网捞上来的不是误会,是真 bug 温床。
★ 阅读拆点 · 四个值得内化的说法
One important point cannot be overstated: ... 字面「这一点无法被过度强调」,即「再怎么强调也不为过」。写文档或邮件要强调某条铁律时用它起头,后面必接冒号 + 规则本体。比 It is very important that ... 高一个量级,且是内核文档里真实在用的原句。 pick up a patch = 维护者接手某补丁;land in the v7.4 merge window = 赶进某个版本的合并窗落地(没赶上就说 did not land in);this series carry the renamed attribute 的 carry = 本系列捎带。读 cover letter 的变更史时,这三个动词出现频率极高。 caught,宾语是既有问题。言下之意「我不生产 bug,我只是让它们现形」。同义替换:The audit turned up ... / The new warning exposed ...。 leaked(该放不放)对 freed prematurely(不该放先放)。prematurely(过早地)是评审高频词,配对的还有 freed twice。成对记住,读 bug 报告时一眼定位是哪一类。 🔗 原文
✨ 辅助彩蛋(写作)
/ column★ 写作彩蛋 · AI 披露写法 + 求 Ack 的礼貌句式
Note on tool use: An LLM coding assistant was used to help audit the compiler diagnostics across the tree, draft the fixes and changelog descriptions, and verify builds and review feedback. Move LLM assistance attribution from Assisted-by tags to this cover letter per commit 1e035297ffda——社区现行做法:AI 辅助披露放在封面信正文(说明工具参与了哪些环节:审计诊断、起草修复、验证构建),不进 commit message 的署名链。用被动语态 was used to help ...,主语是工具,责任仍在作者。 Subsystem maintainer Acked-by tags are still needed (and would be much appreciated!) for the following three patches——催办但不施压的标准说法:先陈述事实 are still needed,再用括号加感叹号表谢意 (and would be much appreciated!),最后点名具体是哪几个补丁。跨子系统推系列时照抄。 🔗 原文
✍️ 今日练习
/ column💡 显示答案
Quote the rules before you enforce them — authority first, patch second.
素材:lore.kernel.org dri-devel · [PATCH v3 0/9] __must_init cover letter(Ian Rogers,〔11-09 06:39 北京〕,原文经 lore git 协议逐字提取)· 内核英语 · 每日一篇