devicetree-specification: the source behind the Devicetree Specification PDF

The PDF is a build artifact, not the source

The Devicetree Specification is the reference document that describes the Devicetree format used to describe hardware in Linux systems. What sits in this repository is not that document as a finished artifact but the source it is generated from. The repository is described as the document master project, holding the source for the generation of the Devicetree Specification using Sphinx and LaTeX.

The published releases live elsewhere. The README points to http://devicetree.org/specifications/ and to the GitHub releases page for the latest release, so the PDF a reader downloads is produced by running a build here, not by editing a file here.

That distinction matters for anyone who wants to propose a change. A patch to the source is a patch to a document, and it is reviewed as prose by people who are responsible for the specification as a whole. The top level tree reflects the nature of the project: a `source/` directory holding the document sources, a `Makefile` driving Sphinx, a `writers-guide.rst` for contributors, a `FAQ.md`, a `CONTRIBUTIONS` file, a `TODO` file, and a `linux-doc-removal-schedule.rst`.

The primary language is recorded as Python, which comes from the tooling in the build chain rather than from the document content, which is reStructuredText and LaTeX.

Sphinx plus LaTeX, and the tools each one needs

The build has two halves, and the README lists the requirements for each. Sphinx is required at version 1.2.3 or later, and it is the component that turns the reStructuredText sources into HTML or drives the LaTeX pass. LaTeX with pdflatex and various LaTeX packages is required for the PDF output, and Graphviz is required, specifically the `dot` program, which is what the specification's diagrams are generated with.

On Debian and Ubuntu the README gives a single install line that covers the LaTeX side and Graphviz:

apt-get install python-sphinx texlive texlive-latex-extra libalgorithm-diff-perl \
                 texlive-humanities texlive-generic-recommended graphviz \
                 texlive-generic-extra

If the packaged Sphinx is too old, the README suggests installing a newer one through the Python package installer and pointing `SPHINXBUILD` at it:

export SPHINXBUILD=~/.local/bin/sphinx-build

On macOS the route is MacTeX for the LaTeX toolchain, pip for Sphinx, and Homebrew or MacPorts for Graphviz. The MacPorts variant is given as `sudo port install graphviz`, the Homebrew one as `brew install graphviz`.

One more dependency shows up only when you want a release comparison. Creating the changebars PDF needs latexdiff version 1.2.1 or later, and until distributions ship a current release the README says to install it straight from its GitHub repository and put it on the path.

Three make targets and a build subdirectory

The Makefile is minimal and does one thing: it forwards to Sphinx. The variables at the top are `SPHINXOPTS`, `SPHINXBUILD` defaulting to `sphinx-build`, `SOURCEDIR` set to `source`, `BUILDDIR` set to `build`, and `LATEXDIFF` set to `latexdiff`. A catch-all rule routes any unknown target to Sphinx in make mode, so a target Sphinx understands works without being written down in the Makefile.

The three targets the README actually documents are:

make latexpdf # For generating pdf
make html # For generating a hierarchy of html pages
make singlehtml # For generating a single html page

Output lands in the `build` subdirectory. The `all` target runs `latexpdf html`, but `help` is put first in the Makefile, so a bare `make` shows the help instead.

The distinction between `html` and `singlehtml` is worth knowing before you start reading output. The hierarchy build produces a tree of HTML pages, one per section, and the single page build produces one long document. For a reader who wants to jump to a chapter, the hierarchy is friendlier. For printing or for reading on a device, the single file is easier.

Because the Makefile defers to Sphinx, the usual Sphinx options still work, for instance by setting `SPHINXOPTS` on the command line.

ChANGebars: seeing what changed between two releases

The `latexdiff` target is the part of the build that turns two document versions into a diff you can read. It runs latexdiff with the `--type=UNDERLINE` option and a configuration that sets `VERBATIMENV=sphinxVerbatim`, comparing the previous release's LaTeX file against the current one and writing a changebars variant, then rebuilds the PDF from that file.

The target's own echo lines describe the sequence: it generates the LaTeX changebars, runs the LaTeX files through pdflatex, and finishes with a message saying the PDF files are in the `build`/`latex` directory. The comparison source is a file under `build/latex-previous` compared with `build/latex`, which means a previous release's sources have to be present for the target to have something to compare against.

That is the mechanism behind a changelog in the document itself. Instead of a hand-written list of what changed, the difference between two releases is rendered inline in the PDF, which is a format that is hard to get wrong and hard to maintain by hand.

The `help` target lists the available targets, with latexdiff described as making LaTeX files including changebars against the previous release.

Patches go to a mailing list under the DCO

Contributions do not arrive as pull requests. The README asks for all patches to be submitted to the mailing list [email protected], and the sign-up instructions point at the vger list server. General discussion, questions and patch submission all happen on that list, and a dedicated mailing list section in the README makes it the first thing a newcomer sees.

Contributions are managed by two named gatekeepers, Grant Likely and Rob Herring, who review and merge what comes out of the list. The README states that anyone can contribute, and that contributions should conform to the Developer Certificate of Origin as defined at elinux.org.

The practical requirement is the sign-off line in the commit message:

Signed-off-by: Your Name <[email protected]>

The repository carries a full copy of the Developer Certificate of Origin 1.1 text, and the README explains what the sign-off means. By signing, the contributor certifies that the work is theirs or is covered by an appropriate open source licence, that they have the right to submit it under the licence indicated in the file, and that they understand the contribution and the record of it, including their sign-off, are maintained indefinitely and may be redistributed.

The DCO differs from a contributor licence agreement, and the difference is why the sign-off is a one-line trailer rather than a signed document.

Apache-2.0, release tags, and what this repository is not

The project is licensed under the Apache V2 licence, and the README points at the LICENSE and NOTICE files in the repository as well as the licence text online. The source file itself carries an SPDX identifier comment reading Apache-2.0, and the Makefile carries the same line at the top.

The release tags are sparse and unevenly spaced. v0.3 was published on 2020-02-13, v0.4-rc1 on 2021-11-30, and v0.4 on 2023-06-28. The repository is not archived and the last push was on 2026-09-23, so the document is being revised even though the tags are not recent.

That gap is normal for a specification project, where the document version and the source repository version are different things, but it means the tags in this repository are not a reliable indicator of which text is current. The published specification at devicetree.org is the authority on what is released.

It is also worth being clear about what this repository is not. There is no parser, no schema description in machine-readable form, and no bindings here. The `TODO` file and `linux-doc-removal-schedule.rst` are working notes about the document's own content, and the FAQ is about the specification. If you are looking to parse a Devicetree at runtime, or to generate bindings from a schema, none of that is here.

Editorial conclusion

devicetree-specification fits a kernel engineer who needs to build the current Devicetree Specification locally, to read a release diff as changebars, or to propose a wording change under the Developer Certificate of Origin. It does not fit a developer looking for a Devicetree parser, a schema file or a binding, since the repository holds documentation sources only. Before sending anything, read writers-guide.rst, remember that patches go to [email protected] rather than to a pull request, and sign the commit with a Signed-off-by line so the gatekeepers can accept it.

Frequently asked questions

Official sources

1. devicetree-org/devicetree-specification on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases