设计和编写Devicetree绑定的注意事项

这是针对绑定设计的常见评审反馈项列表。每条规则都有例外，并且绑定存在许多灰色区域。

有关补丁相关的指南，请参阅提交Devicetree (DT) 绑定补丁

总体设计

  • 务必尝试使绑定完整，即使驱动程序不支持某些功能。例如，如果一个设备有中断，那么即使驱动程序只支持轮询模式，也应包含‘interrupts’属性。

  • 切勿在绑定中提及 Linux 或“设备驱动程序”。绑定应基于硬件所具备的功能，而不是操作系统和驱动程序目前支持的功能。

  • 务必使用与设备类别匹配的节点名称。许多标准名称已在DT规范中定义。如果不存在，请考虑添加。

  • 务必检查示例是否与文档匹配，尤其是在进行评审更改之后。

  • 切勿仅仅为了实例化驱动程序而创建节点。多功能设备仅在其子节点拥有自己的DT资源时才需要子节点。单个节点可以作为多个提供者（例如时钟和复位）。

  • 切勿单独使用‘syscon’，而不带特定的兼容字符串。‘syscon’硬件块应具有足够唯一的兼容字符串，以便（至少）推断出整个块的寄存器布局。

属性

  • 务必使‘compatible’属性具体明确。切勿在兼容字符串中使用通配符。当设备与现有实现相同或为其子集时，务必使用回退兼容。如果存在新功能或缺陷，务必添加新的兼容。

  • 务必在设备特定的属性名称上使用供应商前缀。考虑属性是否可能在同类设备之间通用。检查其他现有绑定中类似设备的用法。

  • 切勿重新定义通用属性。只需引用定义并定义设备特定的约束。

  • 务必对带有科学单位的属性使用通用的属性单位后缀。建议的后缀列于 https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml

  • 务必根据约束来定义属性。有多少条目？可能的值有哪些？顺序是什么？

典型案例和注意事项

  • Phandle条目，如时钟/DMA/中断/复位，应始终明确排序。如果存在多个phandle，请包含 {clock,dma,interrupt,reset}-names。使用时，这两个字段需要相同的约束（例如，项目列表）。

  • 对于在 {clock,dma,interrupt,reset}-names 中使用的名称，不要添加任何后缀，例如：使用“tx”而不是“txirq”（用于中断）。

  • 没有模式类型（例如没有标准后缀或未由模式定义）的属性需要指定类型，即使它是枚举类型。

  • 如果模式包含其他模式（例如 /schemas/i2c/i2c-controller.yaml），请使用“unevaluatedProperties:false”。在其他情况下，通常使用“additionalProperties:false”。

  • 对于大型设备的子块/组件（例如 SoC 块），应使用基于设备的兼容（例如基于 SoC 的兼容），而不是该组件的自定义版本化。例如，使用“vendor,soc1234-i2c”而不是“vendor,i2c-v2”。

  • “syscon”不是一个通用属性。请使用供应商和类型，例如“vendor,power-manager-syscon”。

板级/SoC .dts 文件

  • 务必将所有MMIO设备放置在总线节点下，而不是顶层。

  • 务必使用非空的‘ranges’来限制子总线/设备的大小。64位平台无需所有设备都具有64位地址和大小。