GitHub - devicetree-org/dt-schema: Devicetree schema tools
Devicetree Schema Tools / 设备树模式工具
dtschema 模块包含使用 json-schema ( JSON Schema )词汇表验证 Devicetree 模式的工具和模式数据。这些工具使用 DT 绑定模式文件验证 Devicetree 文件。工具还能验证 DT 绑定模式文件。模式文件采用与 JSON 兼容的 YAML 子集编写，具有人机可读性。
| The dtschema module contains tools and schema data for Devicetree schema validation using the json-schema vocabulary. The tools validate Devicetree files using DT binding schema files. The tools also validate the DT binding schema files. Schema files are written in a JSON compatible subset of YAML to be both human and machine readable. |
1，Data Model / 数据模型
要了解验证是如何工作的，就必须了解模式数据是如何组织和使用的。如果您正在阅读这篇文章，我想您已经熟悉 Devicetree 和 .dts 文件格式了。
在这个资源库中，你会发现两种数据文件：模式和元模式。
| To understand how validation works, it is important to understand how schema data is organized and used. If you're reading this, I assume you're already familiar with Devicetree and the .dts file format. In this repository you will find 2 kinds of data files; Schemas and Meta-Schemas. |
Devicetree Schemas / 设备树模式
Found under ./dtschema/schemas
Devicetree 模式描述了 Devicetree 数据的格式。原始 Devicetree 文件格式非常开放，不限制数据的编码方式。所以，编写devietree时很容易犯错误。模式文件对可以放入 Devicetree 的数据施加了限制。
该资源库包含 "核心 "模式，其中包括 DT 规范中定义的 DT 属性以及 GPIO、时钟和 PHY 绑定等常见绑定。
该资源库不包含特定设备绑定。这些绑定目前与 Devicetree 文件（.dts）一起保存在 Linux 内核树中。
验证时，该工具将加载所有能找到的模式文件，然后遍历 Devicetree 的所有节点。对于每个节点，工具将确定哪些模式适用，并确保节点数据与模式约束相匹配。未通过模式测试的节点将显示错误。不匹配任何模式的节点会发出警告。
| Devicetree Schemas describe the format of devicetree data. The raw Devicetree file format is very open ended and doesn't restrict how data is encoded.Hence, it is easy to make mistakes when writing a Devicetree. Schema files impose the constraints on what data can be put into a Devicetree. This repository contains the 'core' schemas which consists of DT properties defined within the DT Specification and common bindings such as the GPIO, clock, and PHY bindings. This repository does not contain device specific bindings. Those are currently maintained within the Linux kernel tree alongside Devicetree files (.dts). When validating, the tool will load all the schema files it can find and then iterate over all the nodes of the Devicetree. For each node, the tool will determine which schema(s) are applicable and make sure the node data matches the schema constraints. Nodes failing a schema test will emit an error. Nodes that don't match any schema can emit a warning. |
作为开发人员，您需要为创建的每个新设备绑定编写 Devicetree 模式文件，并将其添加到 ./schemas 目录中。
模式文件还具有文档描述绑定的双重目的。定义新绑定时，只需创建一个文件，其中包含机器可验证的数据格式和文档。
Devicetree 模式文件是使用 jsonschema 词汇表的普通 YAML 文件。
Devicetree 模式文件经过简化，更加紧凑。
json-schema 中数组的默认大小是可变的。可以通过定义 "minItems"、"maxItems "和 "additionalItems "来加以限制。在大多数情况下，DeviceTree 模式需要一个固定大小的数组，因此这些属性是根据 "items "列表的大小添加的。
| As a developer, you would write a Devicetree schema file for each new device binding that you create and add it to the ./schemas directory. Schema files also have the dual purpose of documenting a binding. When you define a new binding, you only have to create one file that contains both the machine-verifiable data format and the documentation. Devicetree Schema files are normal YAML files using the jsonschema vocabulary. The Devicetree Schema files are simplified to make them more compact. The default for arrays in json-schema is they are variable sized. This can be restricted by defining 'minItems', 'maxItems', and 'additionalItems'. For DeviceTree Schemas, a fixed size is desired in most cases, so these properties are added based on the size of 'items' list. |
Devicetree Meta-Schemas / 设备树元模式
Found in ./dtschema/meta-schemas
Devicetree 元模式描述 Devicetree 模式文件的数据格式。元模式确保所有绑定模式都采用正确的格式，如果格式不正确，工具就会出错。默认情况下，json-schema 对模式中允许使用的内容非常宽松。例如，未知关键字会被静默忽略。DT 元模式旨在编写模式时时限制允许的内容，并捕捉编写模式时的常见错误。
作为开发人员，通常不需要编写元模式文件。
Devicetree 元模式文件是使用 jsonschema 词汇表的普通 YAML 文件。
| Devicetree Meta-Schemas describe the data format of Devicetree Schema files. The Meta-schemas make sure all the binding schemas are in the correct format and the tool will emit an error if the format is incorrect. json-schema by default is very relaxed in terms of what is allowed in schemas. Unknown keywords are silently ignored as an example. The DT Meta-schemas are designed to limit what is allowed and catch common errors in writing schemas. As a developer you normally will not need to write metaschema files. Devicetree Meta-Schema files are normal YAML files using the jsonschema vocabulary. |
2，Usage / 使用
tools/ 目录中有几种可用工具。
tools/dt-doc-validate: 该工具获取模式文件或模式文件目录，并根据 DT 元模式对其进行验证。
| There are several tools available in the tools/ directory. tools/dt-doc-validate: This tool takes a schema file(s) or directory of schema files and validates them against the DT meta-schema. |
Example:
dt-doc-validate -u test/schemas test/schemas/good-example.yaml
tools/dt-mk-schema:
该工具获取用户提供的模式文件和本软件仓库中的核心模式文件，删除验证中不需要的所有内容，对模式进行修正，并输出一个包含处理后模式的文件。这一步是可选的，可单独完成，以加快 Devicetrees 的后续验证。
| tools/dt-mk-schema: This tool takes user-provided schema file(s) plus the core schema files in this repo, removes everything not needed for validation, applies fix-ups to the schemas, and outputs a single file with the processed schema. This step is optional and can be done separately to speed up subsequent validation of Devicetrees. |
Example:
dt-mk-schema -j test/schemas/ > processed-schema.json
tools/dt-validate:
该工具接收用户提供的 Devicetree 和模式目录或来自 dt-mk-schema 的预处理模式文件，然后根据模式验证 Devicetree。
| tools/dt-validate: This tool takes user-provided Devicetree(s) and either a schema directory or a pre-processed schema file from dt-mk-schema, and then validates the Devicetree against the schema. |
Example:
dtc -O dtb -o device.dtb test/device.dts
dt-validate -s processed-schema.json device.dtb
tools/dt-check-compatible:
该工具测试模式中是否存在兼容字符串列表。默认情况下，当兼容字符串与模式中的字符串（或模式）匹配时，就会打印出来。
| tools/dt-check-compatible: This tool tests whether a list of compatible strings are found or not in the schemas. By default, a compatible string is printed when it matches one (or a pattern) in the schemas. |
Example:
dt-check-compatible -s processed-schema.json vendor,a-compatible
3，Installing / 安装
The project and its dependencies can be installed with pip:
pip3 install dtschema
or directly from git:
pip3 install git+https://github.com/devicetree-org/dt-schema.git@main
All executables will be installed. Ensure ~/.local/bin is in the PATH.
For development, clone the git repository manually and run pip on local tree:
git clone https://github.com/devicetree-org/dt-schema.git
cd dt-schema
pip3 install -e .
4，Dependencies / 依赖
注：上述安装说明会自动处理所有依赖关系。
此代码依赖于 Python 3 以及 pylibfdt、ruamel.yaml、rfc3987 和 jsonschema 库。安装 pylibfdt 依赖于 "swig" 程序。
在 Debian/Ubuntu 上，可以使用 apt 或 pip 安装依赖项。rfc3987 模块未打包，因此必须使用 pip：
| Note: The above installation instructions handle all of the dependencies automatically. This code depends on Python 3 with the pylibfdt, ruamel.yaml, rfc3987, and jsonschema libraries. Installing pylibfdt depends on the 'swig' program. On Debian/Ubuntu, the dependencies can be installed with apt and/or pip. The rfc3987 module is not packaged, so pip must be used: |
sudo apt install swig
sudo apt install python3 python3-ruamel.yaml
pip3 install rfc3987
jsonschema
该代码至少依赖于 Python jsonschema 库（GitHub - python-jsonschema/jsonschema: An implementation of the JSON Schema specification for Python）的 4.1.2 版本，以支持 Draft 2019-09。
可使用 pip 直接从 github 安装该模块：
| This code depends on at least version 4.1.2 of the Python jsonschema library for Draft 2019-09 support. The module can be installed directly from github with pip: |
pip3 install git+https://github.com/Julian/jsonschema.git
