Device-tree schemas

近年来，设备树已经变得无处不在，作为描述不可发现系统（例如许多基于ARM的设备）的硬件布局的一种方式。 设备树绑定定义了如何在设备树中描述特定硬件。 然后驱动程序实现这些绑定。 设备树文档显示了如何使用绑定来描述系统：哪些属性可用以及它们可能具有哪些值。 理论上，绑定，驱动程序和文档应该彼此一致。 在实践中，它们通常不一致，即使它们在实际设备树中正确使用这些绑定也不是一项微不足道的任务。 因此，开发人员多年来一直在考虑对设备树文件进行正式验证。 最近，Rob Herring提议使用JSON Schema转换为更结构化的设备树绑定文档格式，以允许自动验证。

今天的设备树文档是*格式文本，带有一些已定义的结构和可选示例（如gpio-mux-clock.txt中的通用GPIO时钟多路复用器文档）。 对于新绑定，审核过程完全是手动的，并且取决于审阅者查找自动化系统可能会捕获的拼写错误和错误。 没有工具可以检查任何给定的设备树文件是否符合绑定文档。 此外，绑定文档文件有时会复制也包含在其他位置的信息，或者缺少验证设备树文件所需的信息。

过去已经提出了许多建议来解决设备树的验证问题。 其中一个使用YAML作为设备树文件的源格式。 Herring没那么远; 相反，他建议仅使用JSON Schema转换文档文件，同时保持设备树格式本身不变。 他在提交的封面中解释了这一选择：“该语言有一个明确的规范，很好地映射到DT数据，并且有许多现有的工具可以利用”。 他更喜欢使用YAML子集，因为它通常被认为更易于阅读，并允许某些添加，包括注释。 该解决方案还利用现有技术和库，避免发明新语言。 目标是允许在构建时验证设备树文件并验证文档的正确性。 此外，错误和警告消息可以变得更有意义。

Documentation format and validation process

新格式的设备树文档成为结构化文件，即schema。 它使用JSON兼容格式在YAML中编写。 模式应包括验证设备树文件所需的信息。 模式文件有许多部分（强制和可选），包括：

• $id — gives a unique schema identifier
• $schema — gives the identifier of the meta-schema this schema follows
• title — provides the schema title
• description — includes a multi-line description of the binding
• maintainers — a list of email addresses of all maintainers
• properties — the sections with the dictionary of property descriptions (this is a big part, of course)
• requires — lists the mandatory properties
• examples — that may include examples using the DTS language

补丁集文档包含带注释的示例。 一个简单的文件可能如下所示：

$id: "http://devicetree.org/schemas/bindings/vendor/someexample.yaml#"
$schema: "http://devicetree.org/meta-schemas/core.yaml#"

title: Documentation example

maintainers:
    - Our Maintainer <[email protected]>

description:  |
    Multi-line description is to be added here.

properties:
    # Here we define the compatible property with one possible string
    compatible:
        items:
            - const: vendor,my-clk
    reg:
        maxItems: 1

required:
    - compatible

模式文件必须遵循许多规则，并且可以使用也在YAML中实现的所谓meta-schemas 进行验证。 meta-schemas 随工具提供，文档编写者不会修改它们。

Current status and further plans

提交的系列添加了build支持，文档，并在ARM树中转换了一些绑定。 另一个工具doc2yaml存在于Herring的树中，但尚未提交; 该脚本可用于将当前文本格式的设备树绑定文件初步转换为YAML。

现在，meta-schemas，schemas和验证工具托管在一个单独的存储库中。 存储库包含许多脚本（在Python 3中使用ruamel.yaml和JSON Schema实现）。 有三种预计会被最多使用。 dt doc-validate可以帮助验证模式。 dt-mk-schema从提供的schema文件和存储库中的通用模式创建单个schema文件; 期望使用这种处理的模式来加速设备树验证。 最后，dt-validate接受YAML设备树并根据模式验证它们。

使用补丁集，内核构建系统获得两个新目标：dt_binding_check用于检查设备树绑定schema文档，dtbs_check用于检查设备树文件与绑定schema。 它们使用4.20：YAML输出中存在的设备树编译器（dtc）的新功能。 确切的格式仅用于验证目的，将来可能会更改。

在转换过程中，Herring重构了一些文档。 在此过程中，他将绑定移动到每个文件有一个绑定，并将各种绑定（用于多个SoC）移动到单独的文件中。 计划是直接合并核心更改，然后使用特定树来转换绑定文档。 未来的计划包括转换更多文档文件，根据模式验证示例，允许验证所选目标，以及更多地控制用于验证的模式（以便花费更少的时间）。

补丁集已收到一些评论，一些得到直接批准，另一些要求澄清。 许多问题涉及模式文件语法的细节。 对设备树绑定的更结构化文档的整体推动似乎是无可争议的。 看起来支持新格式的工具很快就会合并。 但是，转换本身可能需要更多工作。 从主线内核转换随机文档文件的简单尝试表明，许多属性需要手动描述。 将这种新格式设置为新提交的规则肯定有助于使格式在未来几个月内普及。

More information is available in the slides from a couple of recent Linaro Connect talks on this subject; they give examples of the device-tree schema and their usage: presentation PDF and BoF slides PDF.