使用 json-schema 编写设备树绑定¶
设备树绑定使用 json-schema 词汇编写。模式文件以 JSON 兼容的 YAML 子集编写。之所以使用 YAML 而不是 JSON，是因为它被认为更易于人类阅读，并且具有一些优势，例如允许注释（以 '#' 开头）。
另请参阅 带注释的示例模式。
模式内容¶
每个模式文档都是一个结构化的 json-schema，由一组顶级属性定义。通常，每个文件定义一个绑定。使用的顶级 json-schema 属性是：
- $id
一个 json-schema 唯一标识符字符串。该字符串必须是有效的 URI，通常包含绑定的文件名和路径。对于 DT 模式，它必须以“http://devicetree.org/schemas/”开头。URL 用于构造对模式“$ref”属性中指定的其他文件的引用。带有前导 '/' 的 $ref 值将预先添加主机名。仅具有相对路径或文件名的 $ref 值将预先添加当前模式文件的“$id”值的主机名和路径组件。即使对于本地文件也使用 URL，但这些位置可能实际上不存在文件。
- $schema
指示模式文件遵循的元模式。
- title
绑定模式中描述的硬件的一行描述。
- maintainers
一个 DT 特定属性。包含此绑定的维护者的电子邮件地址列表。
- description
可选。一个多行文本块，包含有关此硬件的任何详细信息。它应包含诸如模块或设备的功能、设备符合的标准以及指向数据表的链接以获取更多信息等内容。
YAML 格式有几种定义文本块格式的选项。这些选项由键后面的指示符字符控制（例如，“description: |”）。应使用块所需的最小格式。格式控件不仅会影响 YAML 是否可以正确解析，而且在将文本块呈现为另一种形式时也很重要。选项如下。
没有任何指示符的默认值为流式、普通标量样式，其中单行断行和前导空格被删除。段落由空行分隔（即双行断行）。这种样式不能包含“: ”，因为它将被解释为键。任何“ #”序列都将被解释为注释。对字符也有其他限制。大多数限制都针对第一个字符。
第二种样式是折叠式，由“>”字符指示。除了在双行断行上保持换行符之外，折叠式还保持超出第一行缩进的前导空格。缩进行上的换行符也会被保持。
第三种样式是字面样式，由“|”字符指示。字面样式保持所有换行符和空格（超出第一行的缩进）。
以上不是 YAML 文本块的完整描述。有关多行 YAML 文本块的更多详细信息，可以在网上找到
- select
可选。一个用于匹配节点以应用模式的 json-schema。默认情况下，如果没有“select”，则会根据节点可能的兼容字符串值或节点名称来匹配节点。大多数绑定不需要 select。
- allOf
可选。要包含的其他模式的列表。用于包含绑定所符合的其他模式。这可能是特定类设备（如 I2C 或 SPI 控制器）的模式。
- properties
一组子模式，定义绑定的所有 DT 属性。确切的模式语法取决于属性是已知的、通用属性（例如“interrupts”）还是绑定/供应商特定的属性。
属性还可以定义一个子 DT 节点，并在其下定义子属性。
有关属性部分的更多详细信息，请参阅“属性模式”部分。
- patternProperties
可选。与“properties”类似，但名称是正则表达式。
- required
“properties”部分中必须始终存在的 DT 属性列表。
- additionalProperties / unevaluatedProperties
控制模式如何验证此模式的“properties”或“patternProperties”未匹配的属性的关键字。每个模式都应该在顶层部分正好包含其中一个关键字，因此是 additionalProperties 或 unevaluatedProperties。嵌套节点（即属性是对象）也应该包含一个。
- additionalProperties: false
最常见的情况，其中没有引用其他模式，或者如果此绑定允许来自其他引用模式的属性子集。
- unevaluatedProperties: false
当此绑定引用其他应允许其所有属性的模式时使用。
- additionalProperties: true
罕见情况，用于实现通用属性集的模式。此类模式应由其他模式引用，然后这些模式使用“unevaluatedProperties: false”。通常是总线或通用部分模式。
- examples
可选。一个或多个仅实现此绑定的 DTS 代码段列表。示例不应包含不相关的设备节点，例如提供程序绑定中的使用者节点，或 phandle 引用的其他节点。注意：YAML 不允许前导制表符，因此必须使用空格代替。
除非另有说明，否则所有属性都是必需的。
属性模式¶
模式的“properties”部分包含绑定的所有 DT 属性。每个属性都包含一组使用 json-schema 词汇对该属性的约束。属性模式是用于验证 DT 文件的模式。
对于通用属性，只需要定义通用绑定模式未涵盖的附加约束，例如有效值的数量或哪些可能的值是有效的。
供应商特定的属性通常需要更详细的模式。除了布尔属性之外，它们都应该引用 schemas/types.yaml 中的类型。始终需要“description”属性。
设备树模式与 dtc 生成的 YAML 编码的 DT 数据并不完全匹配。它们经过简化以使其更紧凑并避免大量的样板代码。工具会处理模式文件以生成用于验证的最终模式。当前，工具有 2 种转换方式。
json-schema 中数组的默认值是它们的大小可变，并且允许比显式定义的条目更多。可以通过定义“minItems”、“maxItems”和“additionalItems”来限制这一点。但是，对于设备树模式，在大多数情况下都希望固定大小，因此这些属性是根据“items”列表中的条目数量添加的。
YAML 设备树格式还将所有字符串值设为数组，将标量值设为矩阵（为了定义分组），即使仅存在单个值时也是如此。模式中的单个条目被修复以匹配此编码。
编码风格¶
使用 YAML 编码风格（两个空格缩进）。对于模式中的 DTS 示例，首选四个空格缩进。
测试¶
依赖项¶
必须安装 DT 模式项目，以便验证 DT 模式绑定文档并使用 DT 模式验证 DTS 文件。可以使用 pip 安装 DT 模式项目
pip3 install dtschema
请注意，“dtschema”安装首先需要安装“swig”和 Python 开发文件。在 Debian/Ubuntu 系统上
apt install swig python3-dev
将安装几个可执行文件（dt-doc-validate、dt-mk-schema、dt-validate）。确保它们在您的 PATH 中（默认情况下为 ~/.local/bin）。
还建议安装 yamllint（存在时由 dtschema 使用）。
运行检查¶
必须使用元模式（模式的模式）验证 DT 模式绑定文档，以确保它们既是有效的 json-schema 又是有效的绑定模式。可以使用 dt_binding_check 目标验证所有 DT 绑定文档
make dt_binding_check
为了执行 DT 源文件的验证，请使用 dtbs_check 目标
make dtbs_check
请注意，dtbs_check 将跳过任何包含错误的绑定模式文件。必须使用 dt_binding_check 来获取绑定模式文件中的所有验证错误。
可以在单个命令中同时运行这两者
make dt_binding_check dtbs_check
还可以通过将 DT_SCHEMA_FILES 变量设置为一个或多个特定模式文件或模式（固定字符串的部分匹配）来运行与匹配模式文件子集的检查。每个文件或模式应以“:”分隔。
make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml
make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml:rtc.yaml
make dt_binding_check DT_SCHEMA_FILES=/gpio/
make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml
json-schema 资源¶
带注释的示例模式¶
也可以作为单独的文件提供：example-schema.yaml
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright 2018 Linaro Ltd.
%YAML 1.2
---
# All the top-level keys are standard json-schema keywords except for
# 'maintainers' and 'select'
# $id is a unique identifier based on the filename. There may or may not be a
# file present at the URL.
$id: http://devicetree.org/schemas/example-schema.yaml#
# $schema is the meta-schema this schema should be validated with.
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: An Example Device
maintainers:
- Rob Herring <[email protected]>
description: |
A more detailed multi-line description of the binding.
Details about the hardware device and any links to datasheets can go here.
Literal blocks are marked with the '|' at the beginning. The end is marked by
indentation less than the first line of the literal block. Lines also cannot
begin with a tab character.
select: false
# 'select' is a schema applied to a DT node to determine if this binding
# schema should be applied to the node. It is optional and by default the
# possible compatible strings are extracted and used to match.
# In this case, a 'false' schema will never match.
properties:
# A dictionary of DT properties for this binding schema
compatible:
# More complicated schema can use oneOf (XOR), anyOf (OR), or allOf (AND)
# to handle different conditions.
# In this case, it's needed to handle a variable number of values as there
# isn't another way to express a constraint of the last string value.
# The boolean schema must be a list of schemas.
oneOf:
- items:
# items is a list of possible values for the property. The number of
# values is determined by the number of elements in the list.
# Order in lists is significant, order in dicts is not
# Must be one of the 1st enums followed by the 2nd enum
#
# Each element in items should be 'enum' or 'const'
- enum:
- vendor,soc4-ip
- vendor,soc3-ip
- vendor,soc2-ip
- const: vendor,soc1-ip
# additionalItems being false is implied
# minItems/maxItems equal to 2 is implied
- items:
# 'const' is just a special case of an enum with a single possible value
- const: vendor,soc1-ip
reg:
# The core schema already checks that reg values are numbers, so device
# specific schema don't need to do those checks.
# The description of each element defines the order and implicitly defines
# the number of reg entries.
items:
- description: core registers
- description: aux registers
# minItems/maxItems equal to 2 is implied
reg-names:
# The core schema enforces this (*-names) is a string array
items:
- const: core
- const: aux
clocks:
# Cases that have only a single entry just need to express that with maxItems
maxItems: 1
description: bus clock. A description is only needed for a single item if
there's something unique to add.
The items should have a fixed order, so pattern matching names are
discouraged.
clock-names:
# For single-entry lists in clocks, resets etc., the xxx-names often do not
# bring any value, especially if they copy the IP block name. In such case
# just skip the xxx-names.
items:
- const: bus
interrupts:
# Either 1 or 2 interrupts can be present
minItems: 1
items:
- description: tx or combined interrupt
- description: rx interrupt
description:
A variable number of interrupts warrants a description of what conditions
affect the number of interrupts. Otherwise, descriptions on standard
properties are not necessary.
The items should have a fixed order, so pattern matching names are
discouraged.
interrupt-names:
# minItems must be specified here because the default would be 2
minItems: 1
items:
- const: tx irq
- const: rx irq
# Property names starting with '#' must be quoted
'#interrupt-cells':
# A simple case where the value must always be '2'.
# The core schema handles that this must be a single integer.
const: 2
interrupt-controller: true
# The core checks this is a boolean, so just have to list it here to be
# valid for this binding.
clock-frequency:
# The type is set in the core schema. Per-device schema only need to set
# constraints on the possible values.
minimum: 100
maximum: 400000
# The value that should be used if the property is not present
default: 200
foo-gpios:
maxItems: 1
description: A connection of the 'foo' gpio line.
# *-supply is always a single phandle, so nothing more to define.
foo-supply: true
# Vendor-specific properties
#
# Vendor-specific properties have slightly different schema requirements than
# common properties. They must have at least a type definition and
# 'description'.
vendor,int-property:
description: Vendor-specific properties must have a description
$ref: /schemas/types.yaml#/definitions/uint32
enum: [2, 4, 6, 8, 10]
vendor,bool-property:
description: Vendor-specific properties must have a description. Boolean
properties are one case where the json-schema 'type' keyword can be used
directly.
type: boolean
vendor,string-array-property:
description: Vendor-specific properties should reference a type in the
core schema.
$ref: /schemas/types.yaml#/definitions/string-array
items:
- enum: [foo, bar]
- enum: [baz, boo]
vendor,property-in-standard-units-microvolt:
description: Vendor-specific properties having a standard unit suffix
don't need a type.
enum: [ 100, 200, 300 ]
vendor,int-array-variable-length-and-constrained-values:
description: Array might define what type of elements might be used (e.g.
their range).
$ref: /schemas/types.yaml#/definitions/uint32-array
minItems: 2
maxItems: 3
items:
minimum: 0
maximum: 8
child-node:
description: Child nodes are just another property from a json-schema
perspective.
type: object # DT nodes are json objects
# Child nodes also need additionalProperties or unevaluatedProperties
additionalProperties: false
properties:
vendor,a-child-node-property:
description: Child node properties have all the same schema
requirements.
type: boolean
required:
- vendor,a-child-node-property
# Describe the relationship between different properties
dependencies:
# 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
# is present
vendor,bool-property: [ 'vendor,string-array-property' ]
# Expressing 2 properties in both orders means all of the set of properties
# must be present or none of them.
vendor,string-array-property: [ 'vendor,bool-property' ]
required:
- compatible
- reg
- interrupts
- interrupt-controller
# if/then schema can be used to handle conditions on a property affecting
# another property. A typical case is a specific 'compatible' value changes the
# constraints on other properties.
#
# For multiple 'if' schema, group them under an 'allOf'.
#
# If the conditionals become too unweldy, then it may be better to just split
# the binding into separate schema documents.
allOf:
- if:
properties:
compatible:
contains:
const: vendor,soc2-ip
then:
required:
- foo-supply
else:
# If otherwise the property is not allowed:
properties:
foo-supply: false
# Altering schema depending on presence of properties is usually done by
# dependencies (see above), however some adjustments might require if:
- if:
required:
- vendor,bool-property
then:
properties:
vendor,int-property:
enum: [2, 4, 6]
# Ideally, the schema should have this line otherwise any other properties
# present are allowed. There's a few common properties such as 'status' and
# 'pinctrl-*' which are added automatically by the tooling.
#
# This can't be used in cases where another schema is referenced
# (i.e. allOf: [{$ref: ...}]).
# If and only if another schema is referenced and arbitrary children nodes can
# appear, "unevaluatedProperties: false" could be used. A typical example is
# an I2C controller where no name pattern matching for children can be added.
additionalProperties: false
examples:
# Examples are now compiled with dtc and validated against the schemas
#
# Examples have a default #address-cells and #size-cells value of 1. This can
# be overridden or an appropriate parent bus node should be shown (such as on
# i2c buses).
#
# Any includes used have to be explicitly included. Use 4-space indentation.
- |
node@1000 {
compatible = "vendor,soc4-ip", "vendor,soc1-ip";
reg = <0x1000 0x80>,
<0x3000 0x80>;
reg-names = "core", "aux";
interrupts = <10>;
interrupt-controller;
#interrupt-cells = <2>;
};