diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..0b21191 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,60 @@ +name: Github Action CI + +on: + push: + branches: + - '**' + tags: + - 'v*' + pull_request: + branches: + master + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + + - name: install + run: | + sudo apt-get update + sudo apt-get install latexmk libalgorithm-diff-perl texlive texlive-latex-extra texlive-humanities graphviz + pip3 install --user mako + pip3 install --user typing + pip3 install --user Sphinx + pip3 install --user codespell + git fetch --tags --force # Needed to make git-describe work + + - name: build pdf + run: | + make latexpdf + mv build/latex/devicetree-specification.pdf build/latex/devicetree-specification-$(git describe).pdf + - name: build html + run: make html + - name: build singlehtml + run: make singlehtml + + - name: upload + uses: actions/upload-artifact@v2 + with: + name: artifacts + path: | + build/latex/devicetree-specification-*.pdf + + - name: deploy + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./build/singlehtml + + - name: release + uses: softprops/action-gh-release@v1 + if: startsWith(github.ref, 'refs/tags/') + with: + files: build/latex/devicetree-specification-*.pdf + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.travis.yml b/.travis.yml index c6c760a..32233b8 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,5 @@ sudo: false -dist: trusty +dist: focal cache: apt: true @@ -15,20 +15,19 @@ git: addons: apt: packages: - - python-pip + - python3-pip - latexmk - libalgorithm-diff-perl - texlive - texlive-latex-extra - texlive-humanities - - texlive-generic-recommended - graphviz - - texlive-generic-extra install: - - pip install --user mako - - pip install --user Sphinx - - pip install --user codespell + - pip3 install --user mako + - pip3 install --user typing + - pip3 install --user Sphinx + - pip3 install --user codespell before_script: - wget https://github.com/ftilmann/latexdiff/releases/download/1.2.1/latexdiff-1.2.1.tar.gz @@ -36,19 +35,18 @@ before_script: - export PATH=$PWD/latexdiff-1.2.1/:$PATH script: - - make check - - git checkout $DIFF_COMMIT + #- git checkout $DIFF_COMMIT + #- make latexpdf + #- mv build/latex build/latex-previous + #- git checkout $TRAVIS_COMMIT - make latexpdf - - mv build/latex build/latex-previous - - git checkout $TRAVIS_COMMIT - - make latexpdf - - make latexdiff + #- make latexdiff - make html - make singlehtml before_deploy: - cp build/latex/devicetree-specification.pdf build/devicetree-specification-$TRAVIS_TAG.pdf - - cp build/latex/devicetree-specification-changebars.pdf build/devicetree-specification-changebars-$TRAVIS_TAG.pdf + #- cp build/latex/devicetree-specification-changebars.pdf build/devicetree-specification-changebars-$TRAVIS_TAG.pdf deploy: - provider: releases diff --git a/FAQ.md b/FAQ.md index 0d8a032..a7cd41c 100644 --- a/FAQ.md +++ b/FAQ.md @@ -7,14 +7,12 @@ You can always find the latest released, as well as all older releases, in our GitHub repository: -[Devicetree Specification release repository](https://github.com/devicetree-org/devicetree-specification-released) +[Devicetree Specification releases](https://github.com/devicetree-org/devicetree-specification) ### How often is a new specification released -We're planning to make a v1.0 release by end of August, 2016, -which will be up to date with current core DT bindings used by the Linux kernel. - -A second major release is planned for December 2016 to cover new features. +The target is once a year or when there is a significant change to prompt a +release. ## Governance @@ -43,3 +41,5 @@ only and not with Linaro membership. The membership proceeds go towards the defraying of Linaro’s costs for hosting devicetree.org. If you have useful FAQs you would like to see here, please contact us through the mailing list + + diff --git a/LICENSE b/LICENSE index b2452fb..af5d10d 100644 --- a/LICENSE +++ b/LICENSE @@ -187,7 +187,7 @@ same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright 2016,2017 Arm, Ltd. + Copyright 2016-2021 Arm, Ltd. Copyright 2016,2017 Linaro, Ltd. Copyright 2008,2011 Power.org, Inc Copyright 2008,2011 Freescale Semiconductor, Inc. diff --git a/Makefile b/Makefile index 3b5d3cd..33446b0 100644 --- a/Makefile +++ b/Makefile @@ -1,152 +1,25 @@ -# Makefile for Sphinx documentation +# SPDX-License-Identifier: Apache-2.0 +# +# Minimal makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -PAPER = +SOURCEDIR = source BUILDDIR = build LATEXDIFF = latexdiff -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) - $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +all: latexpdf html -.PHONY: help +# Put it first so that "make" without argument is like "make help". help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " epub3 to make an epub3" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexdiff to make LaTeX files including changebars against previous release" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - -.PHONY: check -check: - codespell source/*.rst + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo " latexdiff to make LaTeX files including changebars against previous release" -.PHONY: html -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: dirhtml -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/DevicetreeSpecification.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/DevicetreeSpecification.qhc" - -.PHONY: applehelp -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -.PHONY: devhelp -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/DevicetreeSpecification" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/DevicetreeSpecification" - @echo "# devhelp" - -.PHONY: epub -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: epub3 -epub3: - $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 - @echo - @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." +.PHONY: all help latexdiff Makefile -.PHONY: latex -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -.PHONY: latexdiff -latexdiff: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex +latexdiff: latex @echo "Generating LaTeX changebars..." $(LATEXDIFF) --type=UNDERLINE --config VERBATIMENV=sphinxVerbatim $(BUILDDIR)/latex-previous/devicetree-specification.tex $(BUILDDIR)/latex/devicetree-specification.tex > $(BUILDDIR)/latex/devicetree-specification-changebars.tex @echo "Running LaTeX files through pdflatex..." @@ -154,86 +27,7 @@ latexdiff: @echo @echo "latexdiff finished; the PDF files are in $(BUILDDIR)/latex." -.PHONY: latexpdf -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: latexpdfja -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: text -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -.PHONY: info -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -.PHONY: gettext -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -.PHONY: changes -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -.PHONY: doctest -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: xml -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -.PHONY: pseudoxml -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/README.md b/README.md index fa21ecf..7c7bb40 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Document master project for the Devicetree Specification # -The latest release of the specification can be found at http://devicetree.org/ or https://github.com/devicetree-org/devicetree-specification-released +The latest release of the specification can be found at http://devicetree.org/specifications/ or https://github.com/devicetree-org/devicetree-specification/releases This [repository](https://github.com/devicetree-org/devicetree-specification) holds the source for the generation of the Devicetree Specification using Sphinx and LaTeX. @@ -8,7 +8,7 @@ This [repository](https://github.com/devicetree-org/devicetree-specification) ho * Use this mailing list for submitting patches, questions and general discussion * Sign up to the mailing list at http://vger.kernel.org/vger-lists.html#devicetree-spec -## Build Instructions [![Build Status](https://travis-ci.org/devicetree-org/devicetree-specification.svg)](https://travis-ci.org/devicetree-org/devicetree-specification) ## +## Build Instructions [![ci](https://github.com/devicetree-org/devicetree-specification/actions/workflows/ci.yml/badge.svg)](https://github.com/devicetree-org/devicetree-specification/actions/workflows/ci.yml) ## Requirements: * Sphinx: http://sphinx-doc.org/contents.html @@ -62,7 +62,7 @@ On Mac OS X: > >If you are using [brew](http://brew.sh) then you can install graphviz like this: >``` -brew install graphviz +>brew install graphviz >``` >If you are using [macports](https://www.macports.org/) then you can install graphviz like this: >``` @@ -88,7 +88,7 @@ http://www.apache.org/licenses/LICENSE-2.0 ## Contributions ## Please submit all patches to the mailing list devicetree-spec@vger.kernel.org. Contributions to the Devicetree Specification are managed by the gatekeepers, -Grant Likely and Rob Herring +Grant Likely and Rob Herring Anyone can contribute to the Devicetree Specification. Contributions to this project should conform to the `Developer Certificate of Origin` as defined at http://elinux.org/Developer_Certificate_Of_Origin. @@ -136,3 +136,4 @@ By making a contribution to this project, I certify that: this project or the open source license(s) involved. ``` + diff --git a/linux-doc-removal-schedule.rst b/linux-doc-removal-schedule.rst new file mode 100644 index 0000000..b0ae9b1 --- /dev/null +++ b/linux-doc-removal-schedule.rst @@ -0,0 +1,12 @@ +Files scheduled to be removed from Linux documentation tree +=========================================================== + +The content of the following files have been imported into the spec from the Linux kernel documentation directory and the original source should be removed after the next release of the devicetree specification:: + + Documentation/ + devicetree/ + bindings/ + reserved-memory/ + reserved-memory.txt # Added commit 841c0878 + +.. SPDX-License-Identifier: Apache-2.0 diff --git a/source/acknowledgements.rst b/source/acknowledgements.rst index a02e0aa..5e768d4 100644 --- a/source/acknowledgements.rst +++ b/source/acknowledgements.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + **Acknowledgements** The devicetree.org Technical Steering Committee would like to diff --git a/source/introduction.rst b/source/chapter1-introduction.rst similarity index 92% rename from source/introduction.rst rename to source/chapter1-introduction.rst index 98de5fe..6c806af 100644 --- a/source/introduction.rst +++ b/source/chapter1-introduction.rst @@ -1,3 +1,4 @@ +.. SPDX-License-Identifier: Apache-2.0 .. _chapter-introduction: @@ -46,17 +47,17 @@ may include: **Organization of this Document** -* Chapter :ref:`chapter-introduction` introduces the architecture being +* :numref:`Chapter %s ` introduces the architecture being specified by |spec|. -* Chapter :ref:`chapter-devicetree` introduces the devicetree concept +* :numref:`Chapter %s ` introduces the devicetree concept and describes its logical structure and standard properties. -* Chapter :ref:`chapter-device-node-requirements` specifies the +* :numref:`Chapter %s ` specifies the definition of a base set of device nodes required by |spec|-compliant devicetrees. -* Chapter :ref:`chapter-device-bindings` describes device bindings for +* :numref:`Chapter %s ` describes device bindings for certain classes of devices and specific device types. -* Chapter :ref:`chapter-fdt-structure` specifies the DTB encoding of devicetrees. -* Chapter :ref:`chapter-devicetree-source-format` specifies the DTS source language. +* :numref:`Chapter %s ` specifies the DTB encoding of devicetrees. +* :numref:`Chapter %s ` specifies the DTS source language. **Conventions Used in this Document** @@ -75,7 +76,7 @@ The word *may* is used to indicate a course of action permissible within the limits of the standard (*may* equals *is permitted*). Examples of devicetree constructs are frequently shown in *Devicetree -Syntax* form. See section :ref:`chapter-devicetree-source-format` for +Syntax* form. See :numref:`chapter-devicetree-source-format` for an overview of this syntax. Relationship to IEEE™ 1275 and |epapr| diff --git a/source/devicetree-basics.rst b/source/chapter2-devicetree-basics.rst similarity index 93% rename from source/devicetree-basics.rst rename to source/chapter2-devicetree-basics.rst index 01b1958..5ab9e6e 100644 --- a/source/devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -1,4 +1,4 @@ - +.. SPDX-License-Identifier: Apache-2.0 .. _chapter-devicetree: @@ -14,25 +14,36 @@ program’s memory and passes a pointer to the devicetree to the client. This chapter describes the logical structure of the devicetree and specifies a base set of properties for use in describing device nodes. -Chapter :ref:`chapter-device-node-requirements` specifies certain device nodes +:numref:`Chapter %s ` specifies certain device nodes required by a |spec|-compliant -devicetree. Chapter :ref:`chapter-device-bindings` describes the +devicetree. :numref:`Chapter %s ` describes the |spec|-defined device bindings -- the requirements for representing certain device types or classes of devices. -Chapter :ref:`chapter-fdt-structure` describes the in-memory encoding of the devicetree. +:numref:`Chapter %s ` describes the in-memory encoding of the devicetree. A devicetree is a tree data structure with nodes that describe the devices in a system. Each node has property/value pairs that describe the characteristics of the device being represented. Each node has exactly one parent except for the root node, which has no parent. -A |spec|-compliant devicetree describes device information in a system -that cannot necessarily be dynamically detected by a client program. For -example, the architecture of PCI enables a client to probe and detect -attached devices, and thus devicetree nodes describing PCI devices -might not be required. However, a device node is required to describe a -PCI host bridge device in the system if it cannot be detected by -probing. +A device in this context may be an actual hardware device, such as a UART. It +may be part of a hardware device, such as the random-number generator in a TPM. +It may also be a device provided through virtualisation, such as a protocol +providing access to an I2C device attached to a remote CPU. A device may include +functions implemented by firmware running in higher privilege levels or remote +processors. There is no requirement that nodes in a device tree be a physical +hardware device, but generally they have some correlation to physical hardware +devices. Nodes should not be designed for OS- or project- specific purposes. +They should describe something which can be implemented by any OS or project. + +A devicetree is often used to describe devices which cannot necessarily be +dynamically detected by a client program. For example, the architecture of PCI +enables a client to probe and detect attached devices and thus devicetree nodes +describing PCI devices might not be required. However, a device node is often +used to describe a PCI host bridge device in the system. This node is required if +the bridge cannot be detected by probing, but is otherwise optional. Also, a +bootloader may do PCI probing and produce a device tree containing the results +of its scan, for passing to the Operating System. **Example** @@ -146,6 +157,9 @@ level in the tree. The binding for a particular bus may specify additional, more specific requirements for the format of *reg* and the *unit-address*. +In the case of *node-name* without an *@unit-address* the *node-name* shall +be unique from any property names at the same level in the tree. + The root node does not have a node-name or unit-address. It is identified by a forward slash (/). @@ -187,6 +201,7 @@ name should be one of the following choices: * adc * accelerometer + * air-pollution-sensor * atm * audio-codec * audio-controller @@ -199,6 +214,7 @@ name should be one of the following choices: * charger * clock * clock-controller + * co2-sensor * compact-flash * cpu * cpus @@ -235,6 +251,7 @@ name should be one of the following choices: * leds * led-controller * light-sensor + * lora * magnetometer * mailbox * mdio @@ -267,6 +284,7 @@ name should be one of the following choices: * serial * sound * spi + * spmi * sram-controller * ssi-controller * syscon @@ -277,6 +295,7 @@ name should be one of the following choices: * usb * usb-hub * usb-phy + * vibrator * video-codec * vme * watchdog @@ -442,10 +461,12 @@ Standard Properties ------------------- |spec| specifies a set of standard properties for device nodes. These -properties are described in detail in this section. Device nodes defined -by |spec| (see Chapter :ref:`chapter-device-node-requirements`) may specify +properties are described in detail in this section. +Device nodes defined by |spec| +(see :numref:`Chapter %s `) may specify additional requirements or constraints regarding the use of the standard -properties. Chapter :ref:`chapter-device-bindings` describes the representation +properties. +:numref:`Chapter %s ` describes the representation of specific devices and may also specify additional requirements. .. note:: All examples of devicetree nodes in this document use the @@ -476,6 +497,10 @@ Description: (such as a stock ticker symbol), and ``model`` specifies the model number. + The compatible string should consist only of lowercase letters, digits and + dashes, and should start with a letter. A single comma is typically only + used following a vendor prefix. Underscores should not be used. + Example: ``compatible = "fsl,mpc8641", "ns16550";`` @@ -530,6 +555,7 @@ Example: pic@10000000 { phandle = <1>; interrupt-controller; + reg = <0x10000000 0x100>; }; A *phandle* value of 1 is defined. Another device node could reference @@ -561,7 +587,9 @@ Value type: ```` Description: - The ``status`` property indicates the operational status of a device. + The ``status`` property indicates the operational status of a device. The + lack of a ``status`` property should be treated as if the property existed + with the value of ``"okay"``. Valid values are listed and defined in :numref:`table-prop-status-values`. .. tabularcolumns:: | l J | @@ -803,6 +831,32 @@ Description: from the *#size-cells* of this node (the node in which the dma-ranges property appears). +dma-coherent +~~~~~~~~~~~~ + +Property name: ``dma-coherent`` + +Value type: ```` + +Description: + For architectures which are by default non-coherent for I/O, the + *dma-coherent* property is used to indicate a device is capable of + coherent DMA operations. Some architectures have coherent DMA by default + and this property is not applicable. + +dma-noncoherent +~~~~~~~~~~~~ + +Property name: ``dma-noncoherent`` + +Value type: ```` + +Description: + For architectures which are by default coherent for I/O, the + *dma-noncoherent* property is used to indicate a device is not capable of + coherent DMA operations. Some architectures have non-coherent DMA by + default and this property is not applicable. + name (deprecated) ~~~~~~~~~~~~~~~~~ @@ -816,7 +870,7 @@ Description: property is deprecated, and its use is not recommended. However, it might be used in older non-|spec|-compliant devicetrees. Operating system should determine a node’s name based on the *node-name* component of - the node name (see section :ref:`sect-node-names`). + the node name (see :numref:`sect-node-names`). device_type (deprecated) ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -957,7 +1011,6 @@ sits in the logical interrupt tree. "pci-host" -> "i-pci-host" "slot0":e -> "i-slot0":e "slot1":e -> "i-slot1":e - "device1" -> "i-device1" "device2":e -> "i-device2":w "device3":e -> "i-device3":e } @@ -1143,8 +1196,8 @@ Description: unit-address/interrupt specifier pair against the child components in the interrupt-map. Because some fields in the unit interrupt specifier may not be relevant, a mask is applied before the lookup is done. This - mask is defined in the *interrupt-map-mask* property (see section - :ref:`sect-interrupt-map-mask`). + mask is defined in the *interrupt-map-mask* property + (see :numref:`sect-interrupt-map-mask`). .. note:: Both the child node and the interrupt parent node are required to have *#address-cells* and *#interrupt-cells* properties defined. If a @@ -1163,7 +1216,7 @@ Value type: ```` encoded as a bit mask Description: An *interrupt-map-mask* property is specified for a nexus node in the - interrupt tree. This property specifies a mask that is applied to the + interrupt tree. This property specifies a mask that is ANDed with the incoming unit interrupt specifier being looked up in the table specified in the *interrupt-map* property. @@ -1267,8 +1320,9 @@ node with a specified parent unit address and interrupt specifier. node. * The value ``<2 1>`` is a value specified by the device binding for - the Open PIC interrupt controller (see section - :ref:`sect-bindings-simple-bus`). The value ``<2>`` specifies the + the Open PIC interrupt controller + (see :numref:`sect-bindings-simple-bus`). + The value ``<2>`` specifies the physical interrupt source number on the interrupt controller to which INTA is wired. The value ``<1>`` specifies the level/sense encoding. @@ -1344,13 +1398,13 @@ Description: Lookups are performed on the mapping table by matching a specifier against the child specifier in the map. Because some fields in the specifier may not be relevant or need to be modified, a mask is applied before the lookup - is done. This mask is defined in the *-map-mask* property (see - section :ref:`sect-specifier-map-mask`). + is done. This mask is defined in the *-map-mask* property + (see :numref:`sect-specifier-map-mask`). Similarly, when the specifier is mapped, some fields in the unit specifier may need to be kept unmodified and passed through from the child node to the - parent node. In this case, a *-map-pass-thru* property (see - section :ref:`sect-specifier-map-pass-thru`) may be specified to apply + parent node. In this case, a *-map-pass-thru* property + (see :numref:`sect-specifier-map-pass-thru`) may be specified to apply a mask to the child specifier and copy any bits that match to the parent unit specifier. @@ -1366,7 +1420,7 @@ Value type: ```` encoded as a bit mask Description: A *-map-mask* property may be specified for a nexus node. - This property specifies a mask that is applied to the child unit + This property specifies a mask that is ANDed with the child unit specifier being looked up in the table specified in the *-map* property. If this property is not specified, the mask is assumed to be a mask with all bits set. @@ -1407,7 +1461,7 @@ Specifier Mapping Example The following shows the representation of a fragment of a devicetree with two GPIO controllers and a sample specifier map for describing the GPIO routing of a few gpios on both of the controllers through a connector -on a board to a device. The expansion device node is one one side of the +on a board to a device. The expansion device node is on one side of the connector node and the SoC with the two GPIO controllers is on the other side of the connector. diff --git a/source/devicenodes.rst b/source/chapter3-devicenodes.rst similarity index 71% rename from source/devicenodes.rst rename to source/chapter3-devicenodes.rst index 8825ad9..958257e 100644 --- a/source/devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + .. _chapter-device-node-requirements: Device Node Requirements @@ -48,12 +50,24 @@ are descendants. The full path to the root node is ``/``. For example: ``compatible = "fsl,mpc8572ds"`` + ``serial-number`` O ```` Specifies a string representing the device's + serial number. + ``chassis-type`` OR ```` Specifies a string that identifies the form-factor + of the system. The property value can be one of: + + * ``"desktop"`` + * ``"laptop"`` + * ``"convertible"`` + * ``"server"`` + * ``"tablet"`` + * ``"handset"`` + * ``"watch"`` + * ``"embedded"`` Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =========================================================================================== -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. - +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. ``/aliases`` node ----------------- @@ -110,11 +124,12 @@ physical memory layout for the system. If a system has multiple ranges of memory, multiple memory nodes can be created, or the ranges can be specified in the *reg* property of a single memory node. -The *unit-name* component of the node name (see section :ref:`sect-node-names`) +The *unit-name* component of the node name +(see :numref:`sect-node-names`) shall be ``memory``. The client program may access memory not covered by any memory -reservations (see section :ref:`sect-fdt-memory-reservation-block`) +reservations (see :numref:`sect-fdt-memory-reservation-block`) using any storage attributes it chooses. However, before changing the storage attributes used to access a real page, the client program is responsible for performing actions required by the architecture and @@ -149,14 +164,24 @@ If the VLE storage attribute is supported, with VLE=0. address, size). The effective and physical address shall each be 64-bit (```` value), and the size shall be 32-bits (```` value). + ``hotpluggable`` O ```` Specifies an explicit hint to the operating + system that this memory may potentially be + removed later. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ======================================================================================================= -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. + +``/memory`` node and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~ +When booting via [UEFI]_, the system memory map is obtained via the +GetMemoryMap() UEFI boot time service as defined in [UEFI]_ § 7.2, +and if present, the OS must ignore any ``/memory`` nodes. -**Examples** +``/memory`` Examples +~~~~~~~~~~~~~~~~~~~~ Given a 64-bit Power system with the following physical memory layout: @@ -195,6 +220,223 @@ memory ranges. The 2 GB I/O region is skipped. Note that the value of 2, which means that two 32-bit cells are required to define the address and length for the ``reg`` property of the memory node. +``/reserved-memory`` Node +------------------------- + +Reserved memory is specified as a node under the ``/reserved-memory`` node. +The operating system shall exclude reserved memory from normal usage. +One can create child nodes describing particular reserved (excluded from +normal use) memory regions. +Such memory regions are usually designed for the special usage by various +device drivers. + +Parameters for each memory region can be encoded into the device tree +with the following nodes: + +/reserved-memory parent node +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} | +.. table:: /reserved-memory Parent Node Properties + + =================== ===== ================= =============================================== + Property Name Usage Value Type Definition + =================== ===== ================= =============================================== + ``#address-cells`` R ```` Specifies the number of ```` cells to + represent the address in the ``reg`` property in + children of root. + ``#size-cells`` R ```` Specifies the number of ```` cells to + represent the size in the ``reg`` property in + children of root. + ``ranges`` R ```` parent address to child address spaces (see + :numref:`sect-standard-properties-ranges`, + ranges). + Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition + =========================================================================================== + +``#address-cells`` and ``#size-cells`` should use the same values as for the root node, +and ``ranges`` should be empty so that address translation logic works correctly. + +/reserved-memory/ child nodes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each child of the reserved-memory node specifies one or more regions of +reserved memory. Each child node may either use a ``reg`` property to +specify a specific range of reserved memory, or a ``size`` property with +optional constraints to request a dynamically allocated block of memory. + +Following the generic-names recommended practice, node names should +reflect the purpose of the node (ie. "*framebuffer*" or "*dma-pool*"). +Unit address (``@
``) should be appended to the name if the node +is a static allocation. + +A reserved memory node requires either a ``reg`` property for static +allocations, or a ``size`` property for dynamics allocations. +Dynamic allocations may use ``alignment`` and ``alloc-ranges`` properties +to constrain where the memory is allocated from. +If both ``reg`` and ``size`` are present, then the region is treated as a +static allocation with the ``reg`` property taking precedence and ``size`` +is ignored. + +.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} | +.. table:: ``/reserved-memory/`` Child Node Properties + + ======================= ===== ========================= =============================================== + Property Name Usage Value Type Definition + ======================= ===== ========================= =============================================== + ``reg`` O ```` Consists of an arbitrary number of address and + size pairs that specify the physical address + and size of the memory ranges. + ``size`` O ```` Size in bytes of memory to reserve for + dynamically allocated regions. + Size of this property is based on parent node's + ``#size-cells`` property. + ``alignment`` O ```` Address boundary for alignment of allocation. + Size of this property is based on parent node's + ``#size-cells`` property. + ``alloc-ranges`` O ```` Specifies regions of memory that are acceptable + to allocate from. + Format is (address, length pairs) tuples in + same format as for ``reg`` properties. + ``compatible`` O ```` May contain the following strings: + + - ``shared-dma-pool``: This indicates a region of + memory meant to be used as a shared pool of DMA + buffers for a set of devices. + It can be used by an operating system to + instantiate the necessary pool management + subsystem if necessary. + + - vendor specific string in the form + ``,[-]`` + ``no-map`` O ```` If present, indicates the operating system must + not create a virtual mapping of the region as + part of its standard mapping of system memory, + nor permit speculative access to it under any + circumstances other than under the control of + the device driver using the region. + ``reusable`` O ```` The operating system can use the memory in this + region with the limitation that the device + driver(s) owning the region need to be able to + reclaim it back. + Typically that means that the operating system + can use that region to store volatile or cached + data that can be otherwise regenerated or + migrated elsewhere. + Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition + ======================================================================================================= + +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. + +The ``no-map`` and ``reusable`` properties are mutually exclusive and both must +not be used together in the same node. + +Linux implementation notes: + +- If a ``linux,cma-default`` property is present, then Linux will use the + region for the default pool of the contiguous memory allocator. + +- If a ``linux,dma-default`` property is present, then Linux will use the + region for the default pool of the consistent DMA allocator. + +Device node references to reserved memory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Regions in the ``/reserved-memory`` node may be referenced by other device +nodes by adding a ``memory-region`` property to the device node. + +.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} | +.. table:: Properties for referencing reserved-memory regions + + ======================= ===== ========================= =============================================== + Property Name Usage Value Type Definition + ======================= ===== ========================= =============================================== + ``memory-region`` O ```` phandle, specifier pairs to children of + ``/reserved-memory`` + ``memory-region-names`` O ``>`` A list of names, one for each corresponding + entry in the ``memory-region`` property + Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition + ======================================================================================================= + +.. _sect-reserved-memory-uefi: + +``/reserved-memory`` and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When booting via [UEFI]_, static ``/reserved-memory`` regions must +also be listed in the system memory map obtained via the GetMemoryMap() +UEFI boot time service as defined in [UEFI]_ § 7.2. +The reserved memory regions need to be included in the UEFI memory map to +protect against allocations by UEFI applications. + +Reserved regions with the ``no-map`` property must be listed in the memory +map with type ``EfiReservedMemoryType``. +All other reserved regions must be listed with type ``EfiBootServicesData``. + +Dynamic reserved memory regions must not be listed in the [UEFI]_ memory map +because they are allocated by the OS after exiting firmware boot services. + +``/reserved-memory`` Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example defines 3 contiguous regions are defined for Linux kernel: +one default of all device drivers (named ``linux,cma`` and 64MiB in size), +one dedicated to the framebuffer device (named ``framebuffer@78000000``, 8MiB), and +one for multimedia processing (named ``multimedia@77000000``, 64MiB). + +.. code-block:: dts + + / { + #address-cells = <1>; + #size-cells = <1>; + + memory { + reg = <0x40000000 0x40000000>; + }; + + reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + /* global autoconfigured region for contiguous allocations */ + linux,cma { + compatible = "shared-dma-pool"; + reusable; + size = <0x4000000>; + alignment = <0x2000>; + linux,cma-default; + }; + + display_reserved: framebuffer@78000000 { + reg = <0x78000000 0x800000>; + }; + + multimedia_reserved: multimedia@77000000 { + compatible = "acme,multimedia-memory"; + reg = <0x77000000 0x4000000>; + }; + }; + + /* ... */ + + fb0: video@12300000 { + memory-region = <&display_reserved>; + /* ... */ + }; + + scaler: scaler@12500000 { + memory-region = <&multimedia_reserved>; + /* ... */ + }; + + codec: codec@12600000 { + memory-region = <&multimedia_reserved>; + /* ... */ + }; + }; + ``/chosen`` Node ---------------- @@ -228,8 +470,8 @@ time. It shall be a child of the root node. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =================================================================================================== -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. **Example** @@ -268,14 +510,14 @@ which represent the systems CPUs. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =================================================================================================== -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. The ``/cpus`` node may contain properties that are common across ``cpu`` nodes. -See section :ref:`sect-cpus-cpu-node-properties` for details. +See :numref:`sect-cpus-cpu-node-properties` for details. -For an example, see section :ref:`sect-cpu-node-example`. +For an example, see :numref:`sect-cpu-node-example`. .. _sect-cpus-cpu-node-properties: @@ -350,16 +592,16 @@ standard properties with specific applicable detail. controller number space, the CPUs binding may define a binding-specific representation of PIR values if desired. - ``clock-frequency`` | R | array Specifies the current clock speed of the CPU - in Hertz. The value is a ```` - in one of two forms: + ``clock-frequency`` | O | array Specifies the clock speed of the CPU in Hertz, + if that is constant. The value is a + ```` in one of two forms: * A 32-bit integer consisting of one ```` specifying the frequency. * A 64-bit integer represented as a ```` specifying the frequency. - ``timebase-frequency`` | R | array Specifies the current frequency at which the + ``timebase-frequency`` | O | array Specifies the current frequency at which the timebase and decrementer registers are updated (in Hertz). The value is a in one of two forms: @@ -372,8 +614,8 @@ standard properties with specific applicable detail. CPU. This property shall be present for nodes representing CPUs in a symmetric multiprocessing (SMP) configuration. For a CPU - node the meaning of the ``"okay"`` and - ``"disabled"`` values are as follows: + node the meaning of the ``"okay"``, ``"disabled"`` + and ``"fail"`` values are as follows: ``"okay"`` : The CPU is running. @@ -381,6 +623,9 @@ standard properties with specific applicable detail. ``"disabled"`` : The CPU is in a quiescent state. + ``"fail"`` : + The CPU is not operational or does not exist. + A quiescent CPU is in a state where it cannot interfere with the normal operation of other CPUs, nor can its state be affected by the @@ -397,6 +642,11 @@ standard properties with specific applicable detail. loop, held in reset, and electrically isolated from the system bus or in another implementation dependent state. + + A CPU with ``"fail"`` status does not affect the + system in any way. + The status is assigned to nodes for which no + corresponding CPU exists. ``enable-method`` | SD | ```` Describes the method by which a CPU in a disabled state is enabled. This property is required for CPUs with a status property with @@ -431,8 +681,8 @@ standard properties with specific applicable detail. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =============================================================================================== -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. .. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} | @@ -485,8 +735,8 @@ standard properties with specific applicable detail. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ================================================================================================= -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. Older versions of devicetree may be encountered that contain a @@ -536,8 +786,8 @@ buffer in the processor’s MMU. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ================================================================================ -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. Internal (L1) Cache Properties @@ -598,12 +848,12 @@ The following properties of a cpu node describe the processor’s internal ``next-level-cache`` SD ```` If present, indicates that another level of cache exists. The value is the phandle of the next level of cache. The phandle value type is - fully described in section :ref:`sect-standard-properties-phandle`. + fully described in :numref:`sect-standard-properties-phandle`. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =========================================================================================== -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. Older versions of devicetrees may be encountered that contain a @@ -671,8 +921,8 @@ Table 3-9. The L1 cache properties are described in Table 3-8. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ================================================================================== -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. Example @@ -724,11 +974,11 @@ each with their own on-chip L2 and a shared L3. cache-size = <0x8000>; // L1, 32 KB timebase-frequency = <82500000>; // 82.5 MHz clock-frequency = <825000000>; // 825 MHz - cache-level = <2>; next-level-cache = <&L2_1>; // phandle to L2 L2_1:l2-cache { compatible = "cache"; cache-unified; + cache-level = <2>; cache-size = <0x40000>; // 256 KB cache-sets = <0x400>; // 1024 cache-line-size = <32>; // 32 bytes @@ -736,4 +986,3 @@ each with their own on-chip L2 and a shared L3. }; }; }; - diff --git a/source/device-bindings.rst b/source/chapter4-device-bindings.rst similarity index 94% rename from source/device-bindings.rst rename to source/chapter4-device-bindings.rst index 5cdee09..02a8fa0 100644 --- a/source/device-bindings.rst +++ b/source/chapter4-device-bindings.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + .. _chapter-device-bindings: Device Bindings @@ -12,7 +14,7 @@ Bindings may be defined as extensions of other each. For example a new bus type could be defined as an extension of the simple-bus binding. In this case, the compatible property would contain several strings identifying each binding—from the most specific to the most general (see -section :ref:`sect-standard-properties-compatible`, compatible). +:numref:`sect-standard-properties-compatible`, compatible). Binding Guidelines ------------------ @@ -27,20 +29,21 @@ to provide device drivers with needed attributes of the device. Some recommended practices include: -1. Define a compatible string using the conventions described in section - :ref:`sect-standard-properties-compatible`. +1. Define a compatible string using the conventions described in + :numref:`sect-standard-properties-compatible`. -2. Use the standard properties (defined in sections - :ref:`sect-standard-properties` and :ref:`sect-interrupts`) as +2. Use the standard properties (defined in + :numref:`sect-standard-properties` and + :numref:`sect-interrupts`) as applicable for the new device. This usage typically includes the ``reg`` and ``interrupts`` properties at a minimum. -3. Use the conventions specified in section :ref:`chapter-device-bindings` +3. Use the conventions specified in :numref:`chapter-device-bindings` (Device Bindings) if the new device fits into one the |spec| defined device classes. -4. Use the miscellaneous property conventions specified in section - :ref:`sect-misc-properties`, if applicable. +4. Use the miscellaneous property conventions specified in + :numref:`sect-misc-properties`, if applicable. 5. If new properties are needed by the binding, the recommended format for property names is: ``","``, where ```` @@ -196,7 +199,7 @@ the devicetree using following properties. using following formula: ``"registers address" << reg-shift``. If unspecified, the default value is 0. - ``virtual-reg`` SD ```` See section :ref:`sect-standard-properties-virtual-reg`. + ``virtual-reg`` SD ```` See :numref:`sect-standard-properties-virtual-reg`. or Specifies an effective address that maps to the ```` first physical address specified in the ``reg`` property. This property is required if this @@ -204,8 +207,8 @@ the devicetree using following properties. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =================================================================================================== -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. Network devices @@ -267,7 +270,7 @@ Network Class Binding different from the local-mac-address property. This property shall be used only if the value differs from local-mac-address property value. - Example ``mac-address = [ 01 02 03 04 05 06 ];`` + Example ``mac-address = [ 02 03 04 05 06 07 ];`` =========== ============================================================== ``max-frame-size`` Property @@ -409,8 +412,8 @@ specifiers: Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ==================================================================================================== -.. note:: All other standard properties (section - :ref:`sect-standard-properties`) are allowed but are optional. +.. note:: All other standard properties + (:numref:`sect-standard-properties`) are allowed but are optional. .. _sect-bindings-simple-bus: @@ -432,7 +435,10 @@ represented as a node with a compatible value of "simple-bus". ``compatible`` R ```` Value shall include "simple-bus". ``ranges`` R ```` parent address to child address spaces (see - section :ref:`sect-standard-properties-ranges`, + :numref:`sect-standard-properties-ranges`, ranges). + ``nonposted-mmio`` O ```` Specifies that direct children of this bus + should use non-posted memory accesses (i.e. a + non-posted mapping mode) for MMIO ranges. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ==================================================================================================== diff --git a/source/flattened-format.rst b/source/chapter5-flattened-format.rst similarity index 89% rename from source/flattened-format.rst rename to source/chapter5-flattened-format.rst index bd98891..c7f7a48 100644 --- a/source/flattened-format.rst +++ b/source/chapter5-flattened-format.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + .. _chapter-fdt-structure: Flattened Devicetree (DTB) Format @@ -15,11 +17,11 @@ For example, when booting an operating system, firmware will pass a DTB to the O The DTB format encodes the devicetree data within a single, linear, pointerless data structure. It consists of a small header -(see section :ref:`sect-fdt-header`), +(see :numref:`sect-fdt-header`), followed by three variable sized sections: -the memory reservation block (see section :ref:`sect-fdt-memory-reservation-block`), -the structure block (see secton :ref:`sect-fdt-structure-block`), -and the strings block (see section :ref:`sect-fdt-strings-block`). +the memory reservation block (see :numref:`sect-fdt-memory-reservation-block`), +the structure block (see :numref:`sect-fdt-structure-block`), +and the strings block (see :numref:`sect-fdt-strings-block`). These should be present in the flattened devicetree in that order. Thus, the devicetree structure as a whole, when loaded into memory at address, will resemble the diagram in :numref:`figure_device_tree_structure` @@ -35,7 +37,7 @@ will resemble the diagram in :numref:`figure_device_tree_structure` edge [ dir="none" ] node [ shape="Mrecord" width="2.5" ] - "node" [ label = "struct ftd_header | + "node" [ label = "struct fdt_header | (free space) | memory reservation block | (free space) | @@ -46,7 +48,7 @@ will resemble the diagram in :numref:`figure_device_tree_structure` The (free space) sections may not be present, though in some cases they might be required to satisfy the alignment constraints of the individual -blocks (see section :ref:`sect-fdt-alignment`). +blocks (see :numref:`sect-fdt-alignment`). .. _sect-fdt-versioning: @@ -105,15 +107,15 @@ big-endian format. ``off_dt_struct`` This field shall contain the offset in bytes of the structure block - (see section :ref:`sect-fdt-structure-block`) from the beginning of the header. + (see :numref:`sect-fdt-structure-block`) from the beginning of the header. ``off_dt_strings`` This field shall contain the offset in bytes of the strings block - (see section :ref:`sect-fdt-strings-block`) from the beginning of the header. + (see :numref:`sect-fdt-strings-block`) from the beginning of the header. ``off_mem_rsvmap`` This field shall contain the offset in bytes of the memory - reservation block (see section :ref:`sect-fdt-memory-reservation-block`) + reservation block (see :numref:`sect-fdt-memory-reservation-block`) from the beginning of the header. ``version`` @@ -129,8 +131,8 @@ big-endian format. structure with which the version used is backwards compatible. So, for the structure as defined in this document (version 17), this field shall contain 16 because version 17 is backwards compatible - with version 16, but not earlier versions. As per section - :ref:`sect-fdt-versioning`, a |spec| boot program should provide a + with version 16, but not earlier versions. As per + :numref:`sect-fdt-versioning`, a |spec| boot program should provide a devicetree in a format which is backwards compatible with version 16, and thus this field shall always contain 16. @@ -231,8 +233,18 @@ size are equal to 0. Note that the address and size values are always Each uint64_t in the memory reservation block, and thus the memory reservation block as a whole, shall be located at an 8-byte aligned -offset from the beginning of the devicetree blob (see section -:ref:`sect-fdt-alignment`). +offset from the beginning of the devicetree blob (see +:numref:`sect-fdt-alignment`). + +Memory Reservation Block and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As with the ``/reserved-memory`` node (:numref:`sect-reserved-memory-uefi`), +when booting via [UEFI]_ entries in the Memory Reservation Block must also be +listed in the system memory map obtained via the GetMemoryMap() to protect against +allocations by UEFI applications. +The memory reservation block entries should be listed with type +``EfiReservedMemoryType``. .. _sect-fdt-structure-block: @@ -245,7 +257,7 @@ These are organized into a linear tree structure, as described below. Each token in the structure block, and thus the structure block itself, shall be located at a 4-byte aligned offset from the beginning of the -devicetree blob (see :ref:`sect-fdt-alignment`). +devicetree blob (see :numref:`sect-fdt-alignment`). .. _sect-fdt-lexical-structure: @@ -265,7 +277,7 @@ The five token types are as follows: The FDT_BEGIN_NODE token marks the beginning of a node’s representation. It shall be followed by the node’s unit name as extra data. The name is stored as a null-terminated string, and - shall include the unit address (see section :ref:`sect-node-names`), if any. + shall include the unit address (see :numref:`sect-node-names`), if any. The node name is followed by zeroed padding bytes, if necessary for alignment, and then the next token, which may be any token except FDT_END. @@ -291,10 +303,10 @@ The five token types are as follows: Both the fields in this structure are 32-bit big-endian integers. * len gives the length of the property’s value in bytes (which may be - zero, indicating an empty property, see section :ref:`sect-property-values`). + zero, indicating an empty property, see :numref:`sect-property-values`). * nameoff gives an offset into the strings block - (see section :ref:`sect-fdt-strings-block`) + (see :numref:`sect-fdt-strings-block`) at which the property’s name is stored as a null-terminated string. After this structure, the property’s value is given as a byte string of @@ -347,7 +359,7 @@ components: * (optionally) any number of FDT_NOP tokens * FDT_PROP token - * property information as given in section :ref:`sect-fdt-lexical-structure` + * property information as given in :numref:`sect-fdt-lexical-structure` * [zeroed padding bytes to align to a 4-byte boundary] * Representations of all child nodes in this format @@ -378,6 +390,10 @@ offset from the beginning of the devicetree blob. Alignment --------- +The devicetree blob shall be located at an 8-byte-aligned address. To maintain +backwards compatibilty for 32-bit machines, 4-byte alignment is supported by +some software, but this is not |spec|-compliant. + For the data in the memory reservation and structure blocks to be used without unaligned memory accesses, they shall lie at suitably aligned memory addresses. Specifically, the memory reservation block shall be diff --git a/source/source-language.rst b/source/chapter6-source-language.rst similarity index 89% rename from source/source-language.rst rename to source/chapter6-source-language.rst index ed4e234..7b74846 100755 --- a/source/source-language.rst +++ b/source/chapter6-source-language.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + .. _chapter-devicetree-source-format: Devicetree Source (DTS) Format (version 1) @@ -233,15 +235,24 @@ File layout [child nodes] }; -The /dts-v1/; shall be present to identify the file as a version 1 DTS +``/dts-v1/;`` shall be present to identify the file as a version 1 DTS (dts files without this tag will be treated by dtc as being in the obsolete version 0, which uses a different format for integers in addition to other small but incompatible changes). -Memory reservations define an entry for the devicetree blob’s memory -reservation table. They have the form: e.g., /memreserve/
-; Where
and are 64-bit C-style integers. +Memory reservations (see :numref:`sect-fdt-memory-reservation-block`) +are represented by lines in the form:: + + /memreserve/
; + +Where ``
`` and ```` are 64-bit C-style integers, e.g., + +.. code-block:: dts + + /* Reserve memory region 0x10000000..0x10003fff */ + /memreserve/ 0x10000000 0x4000; -* The / { }; section defines the root node of the devicetree. +The ``/ { ... };`` section defines the root node of the devicetree, and +all the device tree data is contained within it. -* C style (/* ... \*/) and C++ style (//) comments are supported. +C style (``/* ... \*/``) and C++ style (``//``) comments are supported. diff --git a/source/conf.py b/source/conf.py index 3f5cc2c..9bde1a8 100644 --- a/source/conf.py +++ b/source/conf.py @@ -1,26 +1,23 @@ +# SPDX-License-Identifier: Apache-2.0 # -*- coding: utf-8 -*- # # Devicetree Specification documentation build configuration file, created by -# sphinx-quickstart on Tue Apr 19 10:28:32 2016. # -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config -import sys -import os -import time -import subprocess +# -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# +import os +import sys +import time +import subprocess +# sys.path.insert(0, os.path.abspath('.')) sys.path.append(os.path.abspath('extensions')) @@ -30,48 +27,47 @@ def setup(app): from sphinx.highlighting import lexers lexers['dts'] = DtsLexer() +# -- Project information ----------------------------------------------------- + +project = u'Devicetree Specification' +copyright = u'2016,2017, devicetree.org' +author = u'devicetree.org' + +# The short X.Y version +try: + version = str(subprocess.check_output(["git", "describe", "--dirty"]), 'utf-8').strip() +except: + version = "unknown-rev" +# The full version, including alpha/beta/rc tags +release = version + -# -- General configuration ------------------------------------------------ +# -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.2.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.graphviz', 'numsec'] +extensions = [ + 'sphinx.ext.todo', + 'sphinx.ext.graphviz' +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: +# # source_suffix = ['.rst', '.md'] source_suffix = '.rst' -# The encoding of source files. -#source_encoding = 'utf-8-sig' - # The master toctree document. master_doc = 'index' -# General information about the project. -project = u'Devicetree Specification' -copyright = u'2016,2017, devicetree.org' -author = u'devicetree.org' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -try: - version = subprocess.check_output(["git", "describe", "--dirty"]).strip() -except: - version = "unknown-rev" -# The full version, including alpha/beta/rc tags. -release = version - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -87,51 +83,32 @@ def setup(app): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path +# This pattern also affects html_static_path and html_extra_path. exclude_patterns = [] # Include at the beginning of every source file that is read with open('rst_prolog', 'rb') as pr: rst_prolog = pr.read().decode('utf-8') -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False +rst_epilog = """ +.. |SpecVersion| replace:: {versionnum} +""".format( +versionnum = version, +) # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - numfig = True highlight_language = 'none' -# -- Options for HTML output ---------------------------------------------- +# -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -import alabaster - +# html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme @@ -142,16 +119,6 @@ def setup(app): 'github_repo': 'devicetree-specification', } -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = [alabaster.get_path()] - -# The name for this set of Sphinx documents. -# " v documentation" by default. -#html_title = u'Devicetree Specification v0.2-pre2' - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - # The name of an image file (relative to this directory) to place at the top # of the sidebar. html_logo = "devicetree-logo.svg" @@ -166,19 +133,18 @@ def setup(app): # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -#html_last_updated_fmt = None -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True +# -- Options for HTMLHelp output --------------------------------------------- # Custom sidebar templates, maps document names to template names. html_sidebars = { @@ -189,70 +155,33 @@ def setup(app): 'searchbox.html', ] } -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. htmlhelp_basename = 'DevicetreeSpecificationdoc' -# -- Options for LaTeX output --------------------------------------------- + +# -- Options for LaTeX output ------------------------------------------------ latex_elements = { - 'classoptions': ',oneside', - 'babel': '\\usepackage[english]{babel}', + 'classoptions': ',oneside', + 'babel': '\\usepackage[english]{babel}', + 'sphinxsetup': 'hmargin=2cm', - # The paper size ('letterpaper' or 'a4paper'). - 'papersize': 'a4paper', + # The paper size ('letterpaper' or 'a4paper'). + # + 'papersize': 'a4paper', - 'sphinxsetup': 'hmargin=2cm', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', -# Latex figure (float) alignment - 'figure_align': 'H', + # Latex figure (float) alignment + # + 'figure_align': 'H', } # Release numbers with a qualifier (ex. '-rc', '-pre') get a watermark. @@ -271,24 +200,7 @@ def setup(app): # the title page. latex_logo = "devicetree-logo.png" -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- +# -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). @@ -297,11 +209,8 @@ def setup(app): [author], 1) ] -# If true, show URL addresses after external links. -#man_show_urls = False - -# -- Options for Texinfo output ------------------------------------------- +# -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, @@ -312,14 +221,28 @@ def setup(app): 'Miscellaneous'), ] -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] -# If false, no module index is generated. -#texinfo_domain_indices = True +# -- Options for Epub output ------------------------------------------------- -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# Bibliographic Dublin Core info. +epub_title = project -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False diff --git a/source/extensions/DtsLexer.py b/source/extensions/DtsLexer.py index eb0e7d6..6be9a6b 100644 --- a/source/extensions/DtsLexer.py +++ b/source/extensions/DtsLexer.py @@ -76,7 +76,7 @@ class DtsLexer(RegexLexer): 'value': [ include('integers'), include('comments'), - (r'(\&)([a-zA-Z0-9_-]+)', bygroups(Operator, Text)), + (r'(\&)?([a-zA-Z0-9_-]+)', bygroups(Operator, Text)), (r'<', Punctuation, '#push'), (r'>', Punctuation, '#pop'), (r'\[', Punctuation, '#push'), diff --git a/source/extensions/numsec.py b/source/extensions/numsec.py deleted file mode 100644 index 3ba89ac..0000000 --- a/source/extensions/numsec.py +++ /dev/null @@ -1,51 +0,0 @@ -""" -Changes section references to be the section number -instead of the title of the section. -""" - -from docutils import nodes -import sphinx.domains.std - -class CustomStandardDomain(sphinx.domains.std.StandardDomain): - - def __init__(self, env): - env.settings['footnote_references'] = 'superscript' - sphinx.domains.std.StandardDomain.__init__(self, env) - - def resolve_xref(self, env, fromdocname, builder, - typ, target, node, contnode): - res = super(CustomStandardDomain, self).resolve_xref(env, fromdocname, builder, - typ, target, node, contnode) - - if res is None: - return res - - if typ == 'ref' and not node['refexplicit']: - docname, labelid, sectname = self.data['labels'].get(target, ('','','')) - res['refdocname'] = docname - - return res - -def doctree_resolved(app, doctree, docname): - secnums = app.builder.env.toc_secnumbers - for node in doctree.traverse(nodes.reference): - if 'refdocname' in node: - refdocname = node['refdocname'] - if refdocname in secnums: - secnum = secnums[refdocname] - toclist = app.builder.env.tocs[refdocname] - for child in node.traverse(): - if isinstance(child, nodes.Text): - text = child.astext() - anchorname = None - for refnode in toclist.traverse(nodes.reference): - if refnode.astext() == text: - anchorname = refnode['anchorname'] - if anchorname is None: - continue - linktext = '.'.join(map(str, secnum[anchorname])) - child.parent.replace(child, nodes.Text(linktext)) - -def setup(app): - app.override_domain(CustomStandardDomain) - app.connect('doctree-resolved', doctree_resolved) diff --git a/source/index.rst b/source/index.rst index ea85396..a4ece47 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,8 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Devicetree Specification's documentation! -==================================================== + SPDX-License-Identifier: Apache-2.0 + +|spec-fullname| |SpecVersion| +====================================== .. toctree:: :numbered: @@ -13,12 +15,12 @@ Welcome to Devicetree Specification's documentation! license acknowledgements revhistory - introduction - devicetree-basics - devicenodes - device-bindings - flattened-format - source-language + chapter1-introduction + chapter2-devicetree-basics + chapter3-devicenodes + chapter4-device-bindings + chapter5-flattened-format + chapter6-source-language references .. @@ -28,4 +30,3 @@ Welcome to Devicetree Specification's documentation! * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/source/license.rst b/source/license.rst index 17a586f..16eccb8 100644 --- a/source/license.rst +++ b/source/license.rst @@ -1,3 +1,4 @@ +.. SPDX-License-Identifier: Apache-2.0 **Copyright** @@ -5,7 +6,7 @@ | Copyright 2008,2011 Freescale Semiconductor, Inc. | Copyright 2008,2011 International Business Machines Corporation. | Copyright 2016,2017 Linaro, Ltd. -| Copyright 2016,2017 Arm, Ltd. +| Copyright 2016-2021 Arm, Ltd. The Linaro and devicetree.org word marks and the Linaro and devicetree.org logos and related marks are trademarks and service marks diff --git a/source/references.rst b/source/references.rst index ff5b1a0..8d8708d 100644 --- a/source/references.rst +++ b/source/references.rst @@ -1,87 +1,30 @@ -.. [b1] *Power ISA™*, Version 2.06 Revision B, July 23, 2010. It is - available from power.org (http://power.org) +.. SPDX-License-Identifier: Apache-2.0 .. [IEEE1275] *Boot (Initialization Configuration) Firmware: Core Requirements and Practices*, 1994, This is the core standard (also known as IEEE 1275) that defines the devicetree concept adopted by the |spec| and |epapr|. It is available from Global Engineering (http://global.ihs.com/). -.. [b3] *PowerPC Processor Binding to IEEE 1275-1994 Standard for Boot - (Initialization, Configuration) Firmware*, Version 2.1, Open Firmware - Working Group, - (http://playground.sun.com/1275/bindings/ppc/release/ppc-2_1.html), - 1996, This document specifies the PowerPC processor specific binding - to the base standard. - -.. [b4] *booting-without-of.txt*, Ben Herrenschmidt, Becky Bruce, et - al., From the Linux kernel source tree (http://www.kernel.org/), - Describes the devicetree as used by the Linux kernel. - -.. [b5] *Device Trees Everywhere*, David Gibson and Ben Herrenschmidt - (http://ozlabs.org/~dgibson/home/papers/dtc-paper.pdf), An overview - of the concept of the devicetree and devicetree compiler. - -.. [b6] *PCI Bus Binding to: IEEE Std 1275-1994 Standard for Boot - (Initialization Configuration) Firmware*, Revision 2.1, Open Firmware - Working Group, 1998 - (http://playground.sun.com/1275/bindings/pci/pci2_1.pdf) - .. [b7] *Open Firmware Recommended Practice: Interrupt Mapping*, Version 0.9, Open Firmware Working Group, 1996 - (http://playground.sun.com/1275/practice/imap/imap0_9d.pdf) - -.. [b8] *Open Firmware Recommended Practice: Device Support Extensions*, - Version 1.0, Open Firmware Working Group, 1997, - (http://playground.sun.com/1275/practice/devicex/dse1_0a.html) This - document describes the binding for various device types such as - network, RTC, keyboard, sound, etc. - -.. [b9] *Open Firmware Recommended Practice: Universal Serial Bus - Binding to IEEE 1275*, Version 1, Open Firmware Working Group, 1998 - (http://playground.sun.com/1275/bindings/usb/usb-1_0.ps) + (http://devicetree.org/open-firmware/practice/imap/imap0_9d.pdf) .. [CHRP] *PowerPC Microprocessor Common Hardware Reference Platform (CHRP) Binding*, Version 1.8, Open Firmware Working Group, 1998 - (http://playground.sun.com/1275/bindings/chrp/chrp1_8a.ps). This + (http://devicetree.org/open-firmware/bindings/chrp/chrp1_8a.ps). This document specifies the properties for Open PIC-compatible interrupt controllers. -.. [b11] *CHRP ISA Interrupt Controller Device Binding*, Unapproved - Draft version 1.1, Open Firmware Working Group, Aug 19, 1996 - (http://playground.sun.com/1275/bindings/devices/postscript/isa-pic-1_1d.ps) - -.. [b12] *The Open Programmable Interrupt Controller (PIC) Register - Interface Specification*, Revision 1.2, Advanced Micro Devices and - Cyrix Corporation, October 1995 - -.. [b13] *PCI Local Bus Specification*, Revision 2.2, PCI Special - Interest Group - -.. [b14] *PCI Express Base Specification*, Revision 1.0a, PCI Special - Interest Group - -.. [b15] *PCI-Express Binding to OF*, P1275 Openboot Working Group - Proposal, 18 August 2004 - .. [PAPR] *Power.org Standard for Power Architecture Platform Requirements*, power.org -.. [b17] *System V Application Binary Interface, Edition 4.1*, Published - by The Santa Cruz Operation, Inc., 1997 - .. [b18] *The Open Programmable Interrupt Controller (PIC) Register Interface Specification Revision 1.2*, AMD and Cyrix, October 1995 -.. [b19] *RFC 2119, Key words for use in RFCs to Indicate Requirement - Levels*, http://www.ietf.org/rfc/rfc2119.txt - -.. [b20] *64-bit PowerPC ELF Application Binary Interface Supplement - 1.9*, Ian Lance Taylor, 2004 - .. [EPAPR] *Power.org Standard for Embedded Power Architecture Platform Requirements*, power.org, 2011, https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/ -.. [ARMv8] *ARM DDI 0487 ARM(c) Architecture Reference Manual, - ARMv8 for ARMv8-A architecture profile*, ARM, - http://infocenter.arm.com/help/topic/com.arm.doc.ddi0487a.h/index.html +.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A + `_, + February 2020, `UEFI Forum `_ diff --git a/source/revhistory.rst b/source/revhistory.rst index e302093..81b71f2 100644 --- a/source/revhistory.rst +++ b/source/revhistory.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + .. _revision-history: .. tabularcolumns:: | p{1.5cm} p{2.25cm} p{11.50cm} | .. table:: Revision History diff --git a/source/rst_prolog b/source/rst_prolog index 6cee60e..2854cc8 100644 --- a/source/rst_prolog +++ b/source/rst_prolog @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + .. Revision of the specification .. |dtspec-major| replace:: 0 diff --git a/writers-guide.rst b/writers-guide.rst index 75c291a..fde76a4 100644 --- a/writers-guide.rst +++ b/writers-guide.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + This document uses the Sphinx implementation of reStructured Text (RST). RST is a flexible markup language with lots of options for laying out text. To keep thinks simple, this file describes the conventions used by this project. As