设计和编写 Devicetree bindings 时的注意事项

这是一份常见评论反馈项目列表，重点关注绑定设计。每条规则都有例外，绑定也有很多灰色区域。

有关补丁的指南，请参阅提交设备树 (DT) 绑定补丁。

总体设计

• 即使驱动程序不支持某些功能，也应尝试完成绑定。例如，如果设备有中断，则即使驱动程序仅处于轮询模式，也应包含“中断”属性。
• 不要在绑定中引用 Linux 或“设备驱动程序”。绑定应基于硬件所具有的内容，而不是操作系统和驱动程序当前支持的内容。
• 请使用与设备类别相匹配的节点名称。DT 规范中定义了许多标准名称。如果没有，请考虑添加它。
• 请检查示例是否与文档相匹配，尤其是在进行审核更改之后。
• 不要仅为实例化驱动程序而创建节点。多功能设备仅在子节点具有自己的 DT 资源时才需要子节点。单个节点可以是多个提供程序（例如时钟和重置）。
• 不要在没有特定兼容字符串的情况下单独使用“syscon”。‘syscon’硬件块应具有足够独特的兼容字符串，以推断整个块的寄存器布局（至少）。

属性

• 一定要使“compatible”属性具体化。不要在compatible字符串中使用通配符。当设备与先前实现相同或只是先前实现的子集时，请使用后备兼容。如果有新功能或错误，请添加新的兼容项。
• 一定要在设备特定的属性名称上使用供应商前缀。考虑属性是否可以在同一类设备之间通用。检查类似设备的其他现有绑定。
• 不要重新定义通用属性。只需引用定义并定义特定于设备的约束。
• 一定要对具有科学单位的属性使用通用属性单位后缀。推荐的后缀列在 https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
• 一定要根据约束定义属性。有多少条目？可能的值有哪些？顺序是什么？

典型案例及注意事项

• 诸如clocks/dmas/interrupts/resets之类的Phandle条目应始终明确排序。如果有多个Phandle，则包括{clock,dma,interrupt,reset}名称。使用时，这两个字段都需要相同的约束（例如项目列表）。
• 对于{clock,dma,interrupt,reset}名称中使用的名称，请勿添加任何后缀，例如：“tx”而不是“txirq”（表示中断）。
• 没有架构类型的属性（例如没有标准后缀或未由架构定义）需要类型，即使这是枚举。
• 如果架构包含其他架构（例如/schemas/i2c/i2c-controller.yaml），请使用“unevaluatedProperties:false”。在其他情况下，通常使用“additionalProperties:false”。
• 对于较大设备的子块/组件（例如 SoC 块），请使用基于设备的兼容（例如基于 SoC 的兼容），而不是该组件的自定义版本。例如，使用“vendor,soc1234-i2c”而不是“vendor,i2c-v2”。
• “syscon”不是通用属性。请使用供应商和类型，例如“vendor,power-manager-syscon”。

Board/SoC .dts 文件

• 务必将所有 MMIO 设备置于总线节点下，而不是顶层。
• 务必使用非空“范围”来限制子总线/设备的大小。64 位平台不需要所有设备都具有 64 位地址和大小。