如何将您的补丁提交到 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 属性时，请查看芯片的功能。虽然我们不期望您的驱动程序支持芯片可能提供的所有功能，但它至少应支持所有限制和警报。
最后但同样重要的是，在开始编写新驱动程序之前，请检查您的芯片是否已有现有驱动程序。特别是对于温度传感器，新芯片通常是先前发布芯片的变体。在某些情况下，一个所谓的新芯片可能只是被重新贴牌了。