요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
Writing Devicetree Bindings in json-schema
==========================================
Devicetree bindings are written using json-schema vocabulary. Schema files are
written in a JSON-compatible subset of YAML. YAML is used instead of JSON as it
is considered more human readable and has some advantages such as allowing
comments (Prefixed with '#').
Also see :ref:`example-schema`.
Schema Contents
---------------
Each schema doc is a structured json-schema which is defined by a set of
top-level properties. Generally, there is one binding defined per file. The
top-level json-schema properties used are:
$id
A json-schema unique identifier string. The string must be a valid
URI typically containing the binding's filename and path. For DT schema, it must
begin with "http://devicetree.org/schemas/". The URL is used in constructing
references to other files specified in schema "$ref" properties. A $ref value
with a leading '/' will have the hostname prepended. A $ref value with only a
relative path or filename will be prepended with the hostname and path
components of the current schema file's '$id' value. A URL is used even for
local files, but there may not actually be files present at those locations.
$schema
Indicates the meta-schema the schema file adheres to.
title
A one-line description of the hardware being described in the binding schema.
maintainers
A DT specific property. Contains a list of email address(es)
for maintainers of this binding.
description
Optional. A multi-line text block containing any detailed
information about this hardware. It should contain things such as what the block
or device does, standards the device conforms to, and links to datasheets for
more information.
The YAML format has several options for defining the formatting of the text
block. The options are controlled with indicator characters following the key
(e.g. "description: \|"). The minimum formatting needed for a block should be
used. The formatting controls can not only affect whether the YAML can be
parsed correctly, but are important when the text blocks are rendered to
another form. The options are as follows.
The default without any indicators is flowed, plain scalar style where single
line breaks and leading whitespace are stripped. Paragraphs are delimited by
blank lines (i.e. double line break). This style cannot contain ": " in it as
it will be interpreted as a key. Any " #" sequence will be interpreted as
a comment. There's other restrictions on characters as well. Most
restrictions are on what the first character can be.
The second style is folded which is indicated by ">" character. In addition
to maintaining line breaks on double line breaks, the folded style also
maintains leading whitespace beyond indentation of the first line. The line
breaks on indented lines are also maintained.
The third style is literal which is indicated by "\|" character. The literal
style maintains all line breaks and whitespace (beyond indentation of the
first line).
The above is not a complete description of YAML text blocks. More details on
multi-line YAML text blocks can be found online:
https://yaml-multiline.info/
https://www.yaml.info/learn/quote.html
select
Optional. A json-schema used to match nodes for applying the
schema. By default, without 'select', nodes are matched against their possible
compatible-string values or node name. Most bindings should not need select.
allOf
Optional. A list of other schemas to include. This is used to
include other schemas the binding conforms to. This may be schemas for a
particular class of devices such as I2C or SPI controllers.
properties
A set of sub-schema defining all the DT properties for the
binding. The exact schema syntax depends on whether properties are known,
common properties (e.g. 'interrupts') or are binding/vendor-specific
properties.
A property can also define a child DT node with child properties defined
under it.
For more details on properties sections, see 'Property Schema' section.
patternProperties
Optional. Similar to 'properties', but names are regex.
required
A list of DT properties from the 'properties' section that
must always be present.
additionalProperties / unevaluatedProperties
Keywords controlling how schema will validate properties not matched by this
schema's 'properties' or 'patternProperties'. Each schema is supposed to
have exactly one of these keywords in top-level part, so either
additionalProperties or unevaluatedProperties. Nested nodes, so properties
being objects, are supposed to have one as well.
* additionalProperties: false
Most common case, where no additional schema is referenced or if this
binding allows subset of properties from other referenced schemas.
* unevaluatedProperties: false
Used when this binding references other schema whose all properties
should be allowed.
* additionalProperties: true
- Top-level part:
Rare case, used for schemas implementing common set of properties. Such
schemas are supposed to be referenced by other schemas, which then use
'unevaluatedProperties: false'. Typically bus or common-part schemas.
- Nested node:
When listing only the expected compatible of the nested node and there
is an another schema matching that compatible which ends with one of
two above cases ('false').
examples
Optional. A list of one or more DTS hunks implementing this binding only.
Example should not contain unrelated device nodes, e.g. consumer nodes in a
provider binding, other nodes referenced by phandle.
Note: YAML doesn't allow leading tabs, so spaces must be used instead.
Unless noted otherwise, all properties are required.
Property Schema
---------------
The 'properties' section of the schema contains all the DT properties for a
binding. Each property contains a set of constraints using json-schema
vocabulary for that property. The properties schemas are what are used for
validation of DT files.
For common properties, only additional constraints not covered by the common,
binding schema need to be defined such as how many values are valid or what
possible values are valid.
Vendor-specific properties will typically need more detailed schema. With the
exception of boolean properties, they should have a reference to a type in
schemas/types.yaml. A "description" property is always required.
The Devicetree schemas don't exactly match the YAML-encoded DT data produced by
dtc. They are simplified to make them more compact and avoid a bunch of
boilerplate. The tools process the schema files to produce the final schema for
validation. There are currently 2 transformations the tools perform.
The default for arrays in json-schema is they are variable-sized and allow more
entries than explicitly defined. This can be restricted by defining 'minItems',
'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
size is desired in most cases, so these properties are added based on the
number of entries in an 'items' list.
The YAML Devicetree format also makes all string values an array and scalar
values a matrix (in order to define groupings) even when only a single value
is present. Single entries in schemas are fixed up to match this encoding.
When bindings cover multiple similar devices that differ in some properties,
those properties should be constrained for each device. This usually means:
* In top level 'properties' define the property with the broadest constraints.
* In 'if:then:' blocks, further narrow the constraints for those properties.
* Do not define the properties within an 'if:then:' block (note that
'additionalItems' also won't allow that).
Coding style
------------
Use YAML coding style (two-space indentation). For DTS examples in the schema,
preferred is four-space indentation.
Place entries in 'properties' and 'required' sections in the same order, using
style from Documentation/devicetree/bindings/dts-coding-style.rst.
Testing
-------
Dependencies
~~~~~~~~~~~~
The DT schema project must be installed in order to validate the DT schema
binding documents and validate DTS files using the DT schema. The DT schema
project can be installed with pip::
pip3 install dtschema
Note that 'dtschema' installation requires 'swig' and Python development files
installed first. On Debian/Ubuntu systems::
apt install swig python3-dev
Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
installed. Ensure they are in your PATH (~/.local/bin by default).
Recommended is also to install yamllint (used by dtschema when present).
Running checks
~~~~~~~~~~~~~~
The DT schema binding documents must be validated using the meta-schema (the
schema for the schema) to ensure they are both valid json-schema and valid
binding schema. All of the DT binding documents can be validated using the
``dt_binding_check`` target::
make dt_binding_check
In order to perform validation of DT source files, use the ``dtbs_check`` target::
make dtbs_check
Note that ``dtbs_check`` will skip any binding schema files with errors. It is
necessary to use ``dt_binding_check`` to get all the validation errors in the
binding schema files.
It is possible to run both in a single command::
make dt_binding_check dtbs_check
It is also possible to run checks with a subset of matching schema files by
setting the ``DT_SCHEMA_FILES`` variable to 1 or more specific schema files or
patterns (partial match of a fixed string). Each file or pattern should be
separated by ':'.
::
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 Resources
---------------------
`JSON-Schema Specifications <http://json-schema.org/>`_
`Using JSON Schema Book <http://usingjsonschema.com/>`_
.. _example-schema:
Annotated Example Schema
------------------------
Also available as a separate file: :download:`example-schema.yaml`
.. literalinclude:: example-schema.yaml
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
json-schema와 YAML
1-12Devicetree binding은 json-schema vocabulary로 작성합니다. schema 파일은 JSON과 호환되는 YAML subset으로 작성합니다. YAML은 JSON보다 사람이 읽기 쉽고 `#`로 시작하는 comment를 허용하는 등의 장점이 있어 사용됩니다.
주석이 달린 전체 예제는 `example-schema` 참조를 함께 확인합니다.
Schema의 최상위 metadata
13-45각 schema 문서는 최상위 속성 집합으로 정의되는 구조화된 json-schema입니다. 일반적으로 파일 하나에 binding 하나를 정의합니다.
`$id`는 json-schema의 고유 식별 문자열입니다. 유효한 URI여야 하며 보통 binding의 파일 이름과 경로를 포함합니다. DT schema에서는 `http://devicetree.org/schemas/`로 시작해야 합니다.
`$id` URL은 schema의 `$ref`가 지정하는 다른 파일의 참조를 구성하는 데 사용합니다. `/`로 시작하는 `$ref`에는 hostname을 앞에 붙입니다. 상대 경로나 파일 이름만 있는 `$ref`에는 현재 schema 파일 `$id`의 hostname과 path component를 앞에 붙입니다. local file에도 URL을 사용하지만 해당 위치에 실제 파일이 존재하지 않을 수 있습니다.
`$schema`는 schema 파일이 따르는 meta-schema를 나타냅니다. `title`은 binding schema가 설명하는 hardware를 한 줄로 기술합니다.
`maintainers`는 DT 전용 속성으로 이 binding을 관리하는 사람의 email address 목록을 담습니다.
선택 속성 `description`은 hardware에 관한 자세한 정보를 담는 여러 줄 text block입니다. block이나 장치가 하는 일, 장치가 따르는 표준, 추가 정보를 위한 datasheet link 등을 포함해야 합니다.
YAML multiline description 형식
46-75YAML에는 text block의 형식을 정의하는 여러 선택지가 있습니다. key 뒤의 indicator 문자, 예를 들어 `description: |`로 제어합니다. block에 필요한 최소한의 formatting만 사용해야 합니다. 이 제어는 YAML parsing 성공 여부뿐 아니라 text block을 다른 형식으로 render할 때도 중요합니다.
indicator가 없는 기본 형식은 flowed plain scalar style입니다. 한 번의 줄바꿈과 leading whitespace는 제거되고, 빈 줄 즉 두 번의 줄바꿈이 paragraph 경계가 됩니다. `: `는 key로 해석되므로 포함할 수 없고, ` #` sequence는 comment로 해석됩니다. 그 밖의 문자 제한도 있으며 대부분 첫 문자에 적용됩니다.
두 번째 folded style은 `>` 문자로 표시합니다. 두 번의 줄바꿈을 유지할 뿐 아니라 첫 줄 indentation을 넘는 leading whitespace도 유지합니다. 들여쓴 줄의 줄바꿈 역시 보존합니다.
세 번째 literal style은 `|` 문자로 표시합니다. 첫 줄 indentation을 제외한 모든 줄바꿈과 whitespace를 유지합니다.
이 설명은 YAML text block의 전체 규격이 아닙니다. 자세한 내용은 `https://yaml-multiline.info/`와 `https://www.yaml.info/learn/quote.html`을 참고합니다.
선택 조건과 속성 schema
76-103선택 속성 `select`는 schema를 적용할 node를 찾는 json-schema입니다. `select`가 없으면 기본적으로 가능한 compatible 문자열 값이나 node 이름으로 node를 match합니다. 대부분의 binding에는 `select`가 필요하지 않습니다.
선택 속성 `allOf`는 포함할 다른 schema의 목록입니다. binding이 따르는 schema를 포함하는 데 사용하며 I2C나 SPI controller 같은 특정 장치 class의 schema일 수 있습니다.
`properties`는 binding의 모든 DT 속성을 정의하는 sub-schema 집합입니다. 정확한 schema 문법은 속성이 알려진 공통 속성인지, 예를 들어 `interrupts`인지, 아니면 binding 또는 vendor 전용 속성인지에 따라 달라집니다.
속성 하나가 child DT node를 정의할 수도 있으며 그 아래에 child 속성을 정의합니다. 자세한 내용은 이 문서의 Property Schema 절을 참고합니다.
선택 속성 `patternProperties`는 `properties`와 비슷하지만 이름을 regex로 지정합니다. `required`는 `properties` 절의 DT 속성 가운데 항상 존재해야 하는 항목 목록입니다.
추가 속성 제어와 DTS 예제
104-136`additionalProperties`와 `unevaluatedProperties`는 이 schema의 `properties` 또는 `patternProperties`와 match하지 않는 속성을 검증하는 방법을 제어합니다. 각 schema의 최상위에는 두 keyword 가운데 정확히 하나가 있어야 합니다. object인 nested node에도 둘 중 하나가 필요합니다.
`additionalProperties: false`는 가장 일반적인 경우입니다. 다른 schema를 참조하지 않거나, 참조한 다른 schema의 속성 중 일부 subset만 이 binding이 허용할 때 사용합니다.
`unevaluatedProperties: false`는 이 binding이 참조하는 다른 schema의 모든 속성을 허용해야 할 때 사용합니다.
최상위의 `additionalProperties: true`는 공통 속성 집합을 구현하는 schema에 드물게 사용합니다. 이런 schema는 다른 schema가 참조해야 하며, 참조하는 쪽은 `unevaluatedProperties: false`를 사용합니다. 일반적으로 bus 또는 공통 부분 schema입니다.
nested node에서 `additionalProperties: true`는 예상되는 compatible만 나열하고, 그 compatible과 match하는 다른 schema가 앞의 두 `false` 경우 가운데 하나로 끝날 때 사용합니다.
선택 속성 `examples`는 이 binding만 구현하는 DTS fragment를 하나 이상 나열합니다. provider binding의 consumer node나 phandle로 참조하는 다른 node처럼 관련 없는 device node를 예제에 넣지 않습니다. YAML은 leading tab을 허용하지 않으므로 반드시 space를 사용합니다.
별도 표기가 없다면 모든 속성은 필수입니다.
Property Schema와 도구 변환
137-175schema의 `properties` 절에는 binding의 모든 DT 속성이 들어갑니다. 각 속성은 해당 속성에 적용할 json-schema vocabulary 기반 constraint 집합을 포함합니다. 이 property schema가 DT 파일 검증에 사용됩니다.
공통 속성은 공통 binding schema가 다루지 않는 추가 constraint만 정의하면 됩니다. 예를 들어 유효한 값의 개수나 가능한 값을 제한합니다.
vendor 전용 속성에는 일반적으로 더 자세한 schema가 필요합니다. boolean 속성을 제외하면 `schemas/types.yaml`의 type을 참조해야 하고 `description` 속성은 항상 필수입니다.
Devicetree schema는 `dtc`가 만든 YAML encoding DT data와 정확히 같지 않습니다. 더 간결하게 만들고 반복 boilerplate를 피하도록 단순화되어 있으며, 도구가 schema 파일을 처리해 최종 검증 schema를 만듭니다. 현재 도구는 두 가지 변환을 수행합니다.
json-schema array는 기본적으로 가변 크기이며 명시한 항목보다 많은 entry를 허용합니다. `minItems`, `maxItems`, `additionalItems`로 제한할 수 있습니다. 그러나 DeviceTree Schema는 대부분 고정 크기를 원하므로 도구가 `items` 목록의 항목 수를 바탕으로 이 속성들을 추가합니다.
YAML Devicetree 형식은 값이 하나뿐이어도 모든 string 값을 array로, scalar 값을 grouping 표현을 위한 matrix로 만듭니다. schema의 단일 entry는 이 encoding에 맞도록 보정됩니다.
binding 하나가 일부 속성이 다른 여러 유사 장치를 포괄한다면 장치별로 그 속성을 제한해야 합니다. 최상위 `properties`에서 가장 넓은 constraint로 속성을 정의하고, `if: then:` block에서 constraint를 더 좁힙니다. 속성 자체를 `if: then:` block 안에서 정의하면 안 되며 `additionalItems` 역시 이를 허용하지 않습니다.
Coding style
176-184YAML coding style은 2-space indentation을 사용합니다. schema 안의 DTS 예제에는 4-space indentation을 권장합니다.
`properties`와 `required` 절의 항목은 같은 순서로 배치하고 `Documentation/devicetree/bindings/dts-coding-style.rst`의 style을 따릅니다.
검증 도구 의존성
185-206DT schema binding 문서와 DT schema를 사용하는 DTS 파일을 검증하려면 DT schema project를 설치해야 합니다. `pip`로 `dtschema`를 설치합니다.
pip3 install dtschema`dtschema`를 설치하기 전에 `swig`와 Python development file이 필요합니다. Debian 또는 Ubuntu에서는 다음 package를 설치합니다.
apt install swig python3-dev`dt-doc-validate`, `dt-mk-schema`, `dt-validate` executable이 설치됩니다. 기본 위치인 `~/.local/bin` 등을 확인해 이 명령들이 `PATH`에 들어 있는지 확인합니다.
또한 설치되어 있으면 `dtschema`가 사용하는 `yamllint`도 설치하기를 권장합니다.
Schema와 DTS 검사 실행
207-241DT schema binding 문서는 유효한 json-schema이면서 유효한 binding schema인지 확인하기 위해 meta-schema, 즉 schema를 위한 schema로 검증해야 합니다. 모든 DT binding 문서는 `dt_binding_check` target으로 검증합니다.
make dt_binding_checkDT source 파일을 검증하려면 `dtbs_check` target을 사용합니다.
make dtbs_check`dtbs_check`는 오류가 있는 binding schema 파일을 건너뜁니다. binding schema 파일의 모든 validation error를 확인하려면 `dt_binding_check`를 사용해야 합니다.
두 검사를 한 명령으로 실행할 수도 있습니다.
make dt_binding_check dtbs_check`DT_SCHEMA_FILES` 변수를 하나 이상의 schema 파일이나 pattern으로 설정하면 match하는 schema subset만 검사할 수 있습니다. pattern은 고정 문자열의 partial match이며 파일이나 pattern은 `:`로 구분합니다.
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.yamljson-schema 자료와 주석 예제
242-257json-schema 자료로 `JSON-Schema Specifications <http://json-schema.org/>`와 `Using JSON Schema Book <http://usingjsonschema.com/>`을 참고합니다.
주석을 단 Example Schema는 별도 파일 `example-schema.yaml`로도 제공되며, 문서에서는 `literalinclude`로 이 파일 전체를 포함합니다.
요약과 해설
writing-schema.rst:1-257Devicetree binding을 YAML 기반 json-schema로 작성하고 검증하는 구조·속성·도구 사용법을 설명합니다. 접을 수 있는 영어 원문 전체와 한국어 전문 번역을 함께 제공하며, schema keyword, command, URL, source path, 코드 블록과 줄 좌표는 원문 표기를 보존합니다.