Documentation/devicetree/bindings/writing-schema.rst

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/writing-schema.rst

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/writing-schema.rst
Extension
.rst
Size
10435 bytes
Lines
262
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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:

Annotation

Implementation Notes