如何将您的补丁提交到 Hwmon 子系统

本文收集了为 hwmon 子系统编写补丁或驱动程序的建议。遵循这些建议将大大增加您的更改被接受的机会。

1. 通则

  • 无需赘述,请阅读并遵循以下内容:

  • 请使用 ‘checkpatch --strict’ 运行您的补丁。应该没有错误、没有警告,检查消息也应尽可能少。如果有任何消息,请准备好解释。

  • 请使用标准的多行注释风格。不要在同一个驱动程序中混用 C 和 C++ 风格的注释(SPDX 许可证标识符除外)。

  • 如果您的补丁生成了 checkpatch 错误、警告或检查消息,请避免给出“我更喜欢那种编码风格”之类的解释。请记住,每个不必要的消息都会掩盖一个真正的问题,而一致的编码风格则有助于他人理解和审查代码。

  • 请彻底测试您的补丁。我们不是您的测试组。有时因为缺少硬件,补丁无法或无法完全测试。在这种情况下,您应该在至少一种架构上测试构建代码。如果未进行运行时测试,则应在补丁头部下方明确说明。

  • 如果您的补丁(或驱动程序)受 CONFIG_SMP 等配置选项影响,请确保它能为所有配置变体编译。

2. 为现有驱动程序添加功能

  • 确保 Documentation/hwmon/<driver_name>.rst 中的文档是最新的。

  • 确保 Kconfig 中的信息是最新的。

  • 如果添加的功能需要一些清理或结构性更改,请将您的补丁拆分为清理部分和实际添加部分。这使得审查您的更改以及二分查找任何导致的问题变得更加容易。

  • 切勿在单个补丁中混合错误修复、清理和功能增强。

3. 新驱动程序

  • 即使您的补丁或驱动程序文件通过 checkpatch 检查,也并不意味着其格式是干净的。如果您不确定新驱动程序的格式,请通过 Lindent 运行它。Lindent 并非完美,您可能需要进行一些小的清理,但这是一个好的开始。

  • 考虑将自己添加到 MAINTAINERS 文件中。

  • 在 Documentation/hwmon/<driver_name>.rst 中记录驱动程序。

  • 将驱动程序按字母顺序添加到 Kconfig 和 Makefile 中。

  • 确保所有依赖项都列在 Kconfig 中。

  • 请按字母顺序排列头文件。

  • 请将续行与前一行中的 ‘(’ 对齐。

  • 尽可能避免前向声明。如有必要,请重新安排代码。

  • 避免使用宏来生成成组的传感器属性。这不仅会使 checkpatch 混淆,还会使代码审查更加困难。

  • 避免在宏和宏生成的函数中进行计算。虽然此类宏可能在源代码中节省一两行,但它会使代码变得模糊,并使代码审查更加困难。它也可能导致代码比必要更复杂。请改用内联函数或普通函数。

  • 限制内核日志消息的数量。通常,您的驱动程序不应仅仅因为运行时操作失败就生成错误消息。请改为使用适当的错误代码向用户空间报告错误。请记住,内核错误日志消息不仅会填满内核日志,而且是同步打印的,很可能在中断禁用时,通常输出到串行控制台。过多的日志记录会严重影响系统性能。

  • 尽可能使用 devres 函数来分配资源。有关原理和支持的函数,请参阅 Devres - 管理的设备资源。如果某个函数不受 devres 支持,请考虑使用 devm_add_action()。

  • 如果驱动程序有检测(detect)功能,请确保它是静默的。调试消息和成功检测后打印的消息是可以接受的,但它绝不能打印“芯片 XXX 未找到/不支持”之类的消息。

    请记住,如果某个地址上检测到芯片,则所有支持该地址的驱动程序都会运行其检测功能。不必要的消息只会污染内核日志,且不提供任何价值。

  • 仅当芯片可以可靠检测时才提供检测(detect)功能。

  • 仅应探测以下 I2C 地址:0x18-0x1f, 0x28-0x2f, 0x48-0x4f, 0x58, 0x5c, 0x73 和 0x77。强烈不建议探测其他地址,因为已知这会与其他(非 hwmon)I2C 芯片引起问题。如果您的芯片位于无法探测的地址,则必须显式实例化设备(无论如何,这总是更好的选择)。

  • 避免在检测功能中写入芯片寄存器。如果您必须写入,请仅在您已收集到足够数据以确定检测将成功之后再进行。

    请记住,芯片可能并非您的驱动程序所认为的那样,对其进行写入可能会导致错误的配置。

  • 确保探测(probe)功能中没有竞争条件。具体而言,请首先完全初始化您的芯片和驱动程序,然后向 hwmon 子系统注册。

  • 使用 devm_hwmon_device_register_with_info() 或,如果您的驱动程序需要一个 remove 函数,使用 hwmon_device_register_with_info() 来将您的驱动程序注册到 hwmon 子系统。如果可能,尝试使用 devm_add_action() 代替 remove 函数。不要使用任何已弃用的注册函数。

  • 您的驱动程序应该能够构建为模块。如果不能,请准备好解释为什么它必须内置到内核中。

  • 不要支持已弃用的 sysfs 属性。

  • 除非确实需要,否则不要创建非标准属性。如果您必须使用非标准属性,或者您认为需要使用,请先在邮件列表中讨论。无论哪种情况,请提供详细解释为何需要非标准属性。标准属性在 sysfs 文件的命名和数据格式标准 中指定。

  • 在决定支持哪些 sysfs 属性时,请查看芯片的功能。虽然我们不期望您的驱动程序支持芯片可能提供的所有功能,但它至少应支持所有限制和警报。

  • 最后但同样重要的是,在开始编写新驱动程序之前,请检查您的芯片是否已有现有驱动程序。特别是对于温度传感器,新芯片通常是先前发布芯片的变体。在某些情况下,一个所谓的新芯片可能只是被重新贴牌了。