From b11458b7535e69ef3beb77b178fbc6d2332951fa Mon Sep 17 00:00:00 2001 From: Arkadiusz Drabczyk Date: Thu, 20 Feb 2020 21:11:54 +0100 Subject: [PATCH 01/49] Fix displaying GPIO_ACTIVE_LOW in devicetree-basics.rst expansion_device { reset-gpios = <&connector 2 GPIO_ACTIVE_LOW>; ^^^^^^^^^^^^^^^ }; ^^... was shown in red boxes in the output PDF, HTML and possibly everything else. Signed-off-by: Arkadiusz Drabczyk Signed-off-by: Rob Herring --- source/extensions/DtsLexer.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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'), From b75a2fc56f738a6df86190db2b39fa620744bee6 Mon Sep 17 00:00:00 2001 From: Arkadiusz Drabczyk Date: Thu, 20 Feb 2020 21:52:16 +0100 Subject: [PATCH 02/49] Fix typo: one one -> on one Signed-off-by: Arkadiusz Drabczyk Signed-off-by: Rob Herring --- source/devicetree-basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index 01b1958..d3fb241 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -1407,7 +1407,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. From 14b68c574918f7151d087475c388085316911adc Mon Sep 17 00:00:00 2001 From: Arkadiusz Drabczyk Date: Thu, 20 Feb 2020 21:59:33 +0100 Subject: [PATCH 03/49] Add required missing reg property Signed-off-by: Arkadiusz Drabczyk Signed-off-by: Rob Herring --- source/devicetree-basics.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index d3fb241..f405977 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -530,6 +530,7 @@ Example: pic@10000000 { phandle = <1>; interrupt-controller; + reg = <0x10000000 0x100>; }; A *phandle* value of 1 is defined. Another device node could reference From 88af74d67f9950db7d142ecc8d5a427b28c95643 Mon Sep 17 00:00:00 2001 From: Arkadiusz Drabczyk Date: Thu, 20 Feb 2020 22:14:42 +0100 Subject: [PATCH 04/49] Explain what kind of bitmask is used in masks Signed-off-by: Arkadiusz Drabczyk Signed-off-by: Rob Herring --- source/devicetree-basics.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index f405977..8292a31 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -1164,7 +1164,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. @@ -1367,7 +1367,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. From 4738e3d9da548f494b1a28216a521c952344253d Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 4 Mar 2020 18:07:33 -0600 Subject: [PATCH 05/49] Fix python3 compatibility for sphinx conf.py In python3, subprocess.check_output() returns a bytearray. We need to encode this into a string type for 'version' and fix this error: Configuration error: There is a programmable error in your configuration file: Traceback (most recent call last): File "/usr/lib/python3/dist-packages/sphinx/config.py", line 368, in eval_config_file execfile_(filename, namespace) File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line 150, in execfile_ exec_(code, _globals) File "/home/rob/proj/git/devicetree-specification/source/conf.py", line 260, in if '-' in release: TypeError: a bytes-like object is required, not 'str' Signed-off-by: Rob Herring --- source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 3f5cc2c..c6cddb9 100644 --- a/source/conf.py +++ b/source/conf.py @@ -66,7 +66,7 @@ def setup(app): # # The short X.Y version. try: - version = subprocess.check_output(["git", "describe", "--dirty"]).strip() + version = subprocess.check_output(["git", "describe", "--dirty"]).strip().encode() except: version = "unknown-rev" # The full version, including alpha/beta/rc tags. From 1777371bb53db54e6c4cf2ccb42a5863d254f98b Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 4 Mar 2020 18:12:04 -0600 Subject: [PATCH 06/49] Add 'serial-number' as a root node property 'serial-number' is a root node property originating from OpenFirmware and has been documented for a long time in Linux kernel's boot-without-of.txt. Signed-off-by: Rob Herring --- source/devicenodes.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/devicenodes.rst b/source/devicenodes.rst index 8825ad9..519aa37 100644 --- a/source/devicenodes.rst +++ b/source/devicenodes.rst @@ -48,6 +48,8 @@ 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. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =========================================================================================== From ad1a97929138697036690cba8dd15de891a7586c Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 4 Mar 2020 18:17:34 -0600 Subject: [PATCH 07/49] Add 'hotpluggable' property for /memory nodes The 'hotpluggable' property has been documented and supported in the Linux kernel since 2016. Add the property to the spec so we can remove the kernel specific documentation. Signed-off-by: Rob Herring --- source/devicenodes.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/devicenodes.rst b/source/devicenodes.rst index 519aa37..3aa4650 100644 --- a/source/devicenodes.rst +++ b/source/devicenodes.rst @@ -151,6 +151,9 @@ 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 ======================================================================================================= @@ -738,4 +741,3 @@ each with their own on-chip L2 and a shared L3. }; }; }; - From 8a02bdcdfa712689c1eddaf5ea4ff521de4b18f9 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 4 Mar 2020 18:24:15 -0600 Subject: [PATCH 08/49] Add 'dma-coherent' property as a standard property The 'dma-coherent' property was added for architectures which by default have non-coherent I/O (e.g. Arm) as a way to specify certain devices are coherent. It's been in use since 2012. Signed-off-by: Rob Herring --- source/devicetree-basics.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index 8292a31..90d49a1 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -804,6 +804,19 @@ 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. + name (deprecated) ~~~~~~~~~~~~~~~~~ From 70965864dd075e9695e4112f5c78d7530b81242f Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 4 Mar 2020 18:28:06 -0600 Subject: [PATCH 09/49] references: Drop references without any spec reference A bunch of the references to external docs are never referenced in the spec. Let's just remove them. Signed-off-by: Rob Herring --- source/references.rst | 62 ------------------------------------------- 1 file changed, 62 deletions(-) diff --git a/source/references.rst b/source/references.rst index ff5b1a0..a37ded9 100644 --- a/source/references.rst +++ b/source/references.rst @@ -1,87 +1,25 @@ -.. [b1] *Power ISA™*, Version 2.06 Revision B, July 23, 2010. It is - available from power.org (http://power.org) .. [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) - .. [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 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 From fe5508829db9792c5b4e27776da52cf5221e1262 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 4 Mar 2020 18:29:37 -0600 Subject: [PATCH 10/49] references: Replace stale playground.sun.com links with devicetree.org mirror playground.sun.com has been dead for a long time. Fix the links. Signed-off-by: Rob Herring --- source/references.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/references.rst b/source/references.rst index a37ded9..961fa20 100644 --- a/source/references.rst +++ b/source/references.rst @@ -6,11 +6,11 @@ .. [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) + (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. From 894bdc0e8ccbaa183b5b4867d37d2c363ac3ec4c Mon Sep 17 00:00:00 2001 From: Manivannan Sadhasivam Date: Sun, 3 May 2020 09:44:46 +0530 Subject: [PATCH 11/49] Add lora as a standard node name LoRa (Long Range) is a wireless communication technology operates in the Sub-Gigahertz spectrum. LoRa usually implies to the radio which acts as a transceiver. Hence, add it as a standard node name. Signed-off-by: Manivannan Sadhasivam --- source/devicetree-basics.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index 90d49a1..ab64d90 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -235,6 +235,7 @@ name should be one of the following choices: * leds * led-controller * light-sensor + * lora * magnetometer * mailbox * mdio From d216cd4c784aefe9d9888b32312f99ae5483fec8 Mon Sep 17 00:00:00 2001 From: Tomasz Duszynski Date: Fri, 20 Dec 2019 11:54:04 +0000 Subject: [PATCH 12/49] Add air-pollution-sensor to the recommended node names We have had drivers for these type of sensors in kernel for some time already hence add a new node name to the list for completeness. Signed-off-by: Tomasz Duszynski --- source/devicetree-basics.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index ab64d90..af2a416 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -187,6 +187,7 @@ name should be one of the following choices: * adc * accelerometer + * air-pollution-sensor * atm * audio-codec * audio-controller From 75c10b12a4369f72e71a66139599135f7ae9dd4e Mon Sep 17 00:00:00 2001 From: Pengfei Zhang Date: Sat, 7 Dec 2019 09:04:19 +0000 Subject: [PATCH 13/49] Fix typo Signed-off-by: Pengfei Zhang --- source/flattened-format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/flattened-format.rst b/source/flattened-format.rst index bd98891..28e5bd4 100644 --- a/source/flattened-format.rst +++ b/source/flattened-format.rst @@ -35,7 +35,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) | From fcf50a07064ec1721bf5315a27df3b9778dee23a Mon Sep 17 00:00:00 2001 From: Kumar Gala Date: Wed, 6 May 2020 08:49:13 -0500 Subject: [PATCH 14/49] Clarify lack of status property Add details that lack of status property is similar to status = "okay". Signed-off-by: Kumar Gala --- source/devicetree-basics.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index af2a416..8f688de 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -564,7 +564,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 | From ed4ab6e75322f76710108074e7a0b4f8b2fd0261 Mon Sep 17 00:00:00 2001 From: Tomasz Duszynski Date: Mon, 22 Jun 2020 14:34:31 +0200 Subject: [PATCH 15/49] Add co2-sensor to the recommended node names co2-sensor node name has recently appeared in one of binding files hence should be documented here as well for completeness. Signed-off-by: Tomasz Duszynski --- source/devicetree-basics.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index 8f688de..969001a 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -200,6 +200,7 @@ name should be one of the following choices: * charger * clock * clock-controller + * co2-sensor * compact-flash * cpu * cpus From 045ff32a4f97d0a6185d8d9bdd1483449bd23201 Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Mon, 14 Sep 2020 15:16:50 +0100 Subject: [PATCH 16/49] trivial: Add chapter number to source files It is easier to follow the organization of the source files if the chapter numbers are included in the file names. This patch only renames the main chapter .rst files and fixes up the index.rst with the new names. Signed-off-by: Grant Likely Cc: Rob Herring --- .../{introduction.rst => chapter1-introduction.rst} | 0 ...ree-basics.rst => chapter2-devicetree-basics.rst} | 0 source/{devicenodes.rst => chapter3-devicenodes.rst} | 0 ...ice-bindings.rst => chapter4-device-bindings.rst} | 0 ...ened-format.rst => chapter5-flattened-format.rst} | 0 ...rce-language.rst => chapter6-source-language.rst} | 0 source/index.rst | 12 ++++++------ 7 files changed, 6 insertions(+), 6 deletions(-) rename source/{introduction.rst => chapter1-introduction.rst} (100%) rename source/{devicetree-basics.rst => chapter2-devicetree-basics.rst} (100%) rename source/{devicenodes.rst => chapter3-devicenodes.rst} (100%) rename source/{device-bindings.rst => chapter4-device-bindings.rst} (100%) rename source/{flattened-format.rst => chapter5-flattened-format.rst} (100%) rename source/{source-language.rst => chapter6-source-language.rst} (100%) diff --git a/source/introduction.rst b/source/chapter1-introduction.rst similarity index 100% rename from source/introduction.rst rename to source/chapter1-introduction.rst diff --git a/source/devicetree-basics.rst b/source/chapter2-devicetree-basics.rst similarity index 100% rename from source/devicetree-basics.rst rename to source/chapter2-devicetree-basics.rst diff --git a/source/devicenodes.rst b/source/chapter3-devicenodes.rst similarity index 100% rename from source/devicenodes.rst rename to source/chapter3-devicenodes.rst diff --git a/source/device-bindings.rst b/source/chapter4-device-bindings.rst similarity index 100% rename from source/device-bindings.rst rename to source/chapter4-device-bindings.rst diff --git a/source/flattened-format.rst b/source/chapter5-flattened-format.rst similarity index 100% rename from source/flattened-format.rst rename to source/chapter5-flattened-format.rst diff --git a/source/source-language.rst b/source/chapter6-source-language.rst similarity index 100% rename from source/source-language.rst rename to source/chapter6-source-language.rst diff --git a/source/index.rst b/source/index.rst index ea85396..568e72b 100644 --- a/source/index.rst +++ b/source/index.rst @@ -13,12 +13,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 .. From a4ef87f50ef69f2c4ef3ddb98c3f2a586a3aa405 Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Mon, 14 Sep 2020 15:55:52 +0100 Subject: [PATCH 17/49] Fix python3 compatibility and switch travis to python3 Python2 is EOL. Switch to py3. The move to python3 requires the 'typing' package to be installed. Add it to the travisci file. Also update to 'focal' Ubuntu release to get a python newer than 3.3. This patch reworks the use of git-describe to work out the document version number. The existing code falls over when using Sphinx on Python 3 due to the string datatype changes. Wrap the output of subprocess with str() to fix. Finally, the changebar version build is currently failing and causing latex to stall. Drop it for now until it can be resolved. Signed-off-by: Grant Likely --- .travis.yml | 26 ++++++++++++-------------- source/conf.py | 2 +- 2 files changed, 13 insertions(+), 15 deletions(-) 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/source/conf.py b/source/conf.py index c6cddb9..c84edc3 100644 --- a/source/conf.py +++ b/source/conf.py @@ -66,7 +66,7 @@ def setup(app): # # The short X.Y version. try: - version = subprocess.check_output(["git", "describe", "--dirty"]).strip().encode() + version = str(subprocess.check_output(["git", "describe", "--dirty"]), 'utf-8').strip() except: version = "unknown-rev" # The full version, including alpha/beta/rc tags. From 5028248122be57beee8675b8db11d7990e2c6f21 Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Mon, 14 Sep 2020 15:48:48 +0100 Subject: [PATCH 18/49] Update Makefile to newer Sphinx 'minimal' style Drops a ton of lines from the Makefile and makes it easier to track upstream Sphinx changes. This change is in line with Sphinx 1.8 Signed-off-by: Grant Likely --- Makefile | 232 +++---------------------------------------------------- 1 file changed, 11 insertions(+), 221 deletions(-) diff --git a/Makefile b/Makefile index 3b5d3cd..e1430fa 100644 --- a/Makefile +++ b/Makefile @@ -1,152 +1,21 @@ -# Makefile for Sphinx documentation +# 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 - -.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: 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 +23,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) From 33a734285d44cbead9c86ff25582b90b581477f6 Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Mon, 14 Sep 2020 19:44:44 +0100 Subject: [PATCH 19/49] Updates to match Sphinx templates This should be a no-op commit. It restructures the config file to match the style and format of the generic config file generated by sphinx-quickstart. The only reason to do this is to make it easy to adapt to changes to Sphinx going forward. This commit reflects the behaviour of Sphinx 1.8.4 which is what is packaged into Debian. The previous config file was generated by a 1.2.x era of Sphinx. Signed-off-by: Grant Likely --- source/conf.py | 255 +++++++++++++++++-------------------------------- 1 file changed, 86 insertions(+), 169 deletions(-) diff --git a/source/conf.py b/source/conf.py index c84edc3..10abaf7 100644 --- a/source/conf.py +++ b/source/conf.py @@ -1,26 +1,22 @@ # -*- 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 +26,48 @@ 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', + 'numsec' +] # 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 = str(subprocess.check_output(["git", "describe", "--dirty"]), 'utf-8').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,26 @@ 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 - # 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 +113,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 +127,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 +149,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 +194,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 +203,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 +215,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 From 06d64a86660d17a01268e2f45500c99c884f539a Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Tue, 15 Sep 2020 17:57:46 +0100 Subject: [PATCH 20/49] Build latexpdf and html targets by default I rarely want to build 'help', but I always want latexpdf! Change the default build target to latexpdf and html Signed-off-by: Grant Likely --- Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index e1430fa..8e5475d 100644 --- a/Makefile +++ b/Makefile @@ -8,12 +8,14 @@ SOURCEDIR = source BUILDDIR = build LATEXDIFF = latexdiff +all: latexpdf html + # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @echo " latexdiff to make LaTeX files including changebars against previous release" -.PHONY: help latexdiff Makefile +.PHONY: all help latexdiff Makefile latexdiff: latex @echo "Generating LaTeX changebars..." From f14fc0b409a7170e569047c808253a38afc6a93c Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Wed, 16 Sep 2020 16:34:13 +0100 Subject: [PATCH 21/49] Use native :numref: macro instead of numsec extension Sphinx can natively use chapter number references now. Drop the numsec extension and use :numref: everywhere. Signed-off-by: Grant Likely --- source/chapter1-introduction.rst | 14 ++++---- source/chapter2-devicetree-basics.rst | 33 +++++++++-------- source/chapter3-devicenodes.rst | 48 ++++++++++++------------- source/chapter4-device-bindings.rst | 29 +++++++-------- source/chapter5-flattened-format.rst | 34 +++++++++--------- source/conf.py | 3 +- source/extensions/numsec.py | 51 --------------------------- 7 files changed, 82 insertions(+), 130 deletions(-) delete mode 100644 source/extensions/numsec.py diff --git a/source/chapter1-introduction.rst b/source/chapter1-introduction.rst index 98de5fe..f50e6b5 100644 --- a/source/chapter1-introduction.rst +++ b/source/chapter1-introduction.rst @@ -46,17 +46,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 +75,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/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 969001a..f782137 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -14,12 +14,12 @@ 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 @@ -445,10 +445,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 @@ -835,7 +837,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) ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1162,8 +1164,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 @@ -1286,8 +1288,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. @@ -1363,13 +1366,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. diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index 3aa4650..9627645 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -53,9 +53,8 @@ are descendants. The full path to the root node is ``/``. 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 ----------------- @@ -112,11 +111,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 @@ -157,8 +157,8 @@ If the VLE storage attribute is supported, with VLE=0. 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. **Examples** @@ -233,8 +233,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** @@ -273,14 +273,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: @@ -436,8 +436,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} | @@ -490,8 +490,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 @@ -541,8 +541,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 @@ -603,12 +603,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 @@ -676,8 +676,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 diff --git a/source/chapter4-device-bindings.rst b/source/chapter4-device-bindings.rst index 5cdee09..7e1a0f4 100644 --- a/source/chapter4-device-bindings.rst +++ b/source/chapter4-device-bindings.rst @@ -12,7 +12,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 +27,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 +197,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 +205,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 @@ -409,8 +410,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 +433,7 @@ 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). Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ==================================================================================================== diff --git a/source/chapter5-flattened-format.rst b/source/chapter5-flattened-format.rst index 28e5bd4..6eb6011 100644 --- a/source/chapter5-flattened-format.rst +++ b/source/chapter5-flattened-format.rst @@ -15,11 +15,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` @@ -46,7 +46,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 +105,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 +129,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 +231,8 @@ 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`). .. _sect-fdt-structure-block: @@ -245,7 +245,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 +265,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 +291,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 +347,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 diff --git a/source/conf.py b/source/conf.py index 10abaf7..1803dfa 100644 --- a/source/conf.py +++ b/source/conf.py @@ -52,8 +52,7 @@ def setup(app): # ones. extensions = [ 'sphinx.ext.todo', - 'sphinx.ext.graphviz', - 'numsec' + 'sphinx.ext.graphviz' ] # Add any paths that contain templates here, relative to this directory. 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) From 24e6aa0a37c554c95968e38afde084d308decbfc Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Tue, 15 Sep 2020 15:51:23 +0100 Subject: [PATCH 22/49] Clarify language on /memreserve/ The language was ambiguous. Rephrase and reformat to be more readable. Co-authored-by: Heinrich Schuchardt Signed-off-by: Grant Likely Cc: Heinrich Schuchardt --- source/chapter6-source-language.rst | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/source/chapter6-source-language.rst b/source/chapter6-source-language.rst index ed4e234..61d05d4 100755 --- a/source/chapter6-source-language.rst +++ b/source/chapter6-source-language.rst @@ -233,15 +233,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:: -* The / { }; section defines the root node of the devicetree. + /memreserve/
; -* C style (/* ... \*/) and C++ style (//) comments are supported. +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, and +all the device tree data is contained within it. + +C style (``/* ... \*/``) and C++ style (``//``) comments are supported. From ca634485063fad874bf90e212f7af3abd846aa4b Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Mon, 14 Sep 2020 20:50:35 +0100 Subject: [PATCH 23/49] Import /reserved-memory specification text Imported from linux kernel source tree: Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt Very minor editorial changes made while importing, with one exception. Added clause that the 'no-map' and 'reusable' properties are mutually exclusive. Also add a document to keep track of the bindings that have been copied out of the Linux kernel documentation tree so that they can be removed after the next formal release. Signed-off-by: Grant Likely Acked-by: Thierry Reding Cc: Rob Herring Cc: Heinrich Schuchardt Cc: Ard Biesheuvel --- linux-doc-removal-schedule.rst | 10 ++ source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++- 2 files changed, 212 insertions(+), 1 deletion(-) create mode 100644 linux-doc-removal-schedule.rst diff --git a/linux-doc-removal-schedule.rst b/linux-doc-removal-schedule.rst new file mode 100644 index 0000000..90eeed0 --- /dev/null +++ b/linux-doc-removal-schedule.rst @@ -0,0 +1,10 @@ +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 diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index 9627645..a5684d2 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -161,7 +161,8 @@ If the VLE storage attribute is supported, with VLE=0. (:numref:`sect-standard-properties`) are allowed but are optional. -**Examples** +``/memory`` Examples +~~~~~~~~~~~~~~~~~~~~ Given a 64-bit Power system with the following physical memory layout: @@ -200,6 +201,206 @@ 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 + ======================================================================================================= + +``/reserved-memory`` Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example defines 3 contiguous regions are defined for Linux kernel: +one default of all device drivers (named ``linux,cma@72000000`` and 64MiB in size), +one dedicated to the framebuffer device (named ``framebuffer@78000000``, 8MiB), and +one for multimedia processing (named ``multimedia-memory@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 ---------------- From f998b10c3e78502d2b220589916c15efb213373b Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Tue, 15 Sep 2020 12:01:55 +0100 Subject: [PATCH 24/49] Add details of UEFI interaction with /memory and /reserved-memory Output from discussion on EBBR issue: https://github.com/ARM-software/ebbr/issues/52 When using the UEFI ABI for booting, the DT memory map is ignored and instead UEFI GetMemoryMap() is used to find system memory. Also, regions described in /reserved-memory need to also be added to the UEFI memory map to protect against overlapping allocations. The patch adds language to cover both of those cases. Signed-off-by: Grant Likely Cc: Heinrich Schuchardt Cc: Ard Biesheuvel Reviewed-by: Etienne Carriere --- source/chapter3-devicenodes.rst | 31 ++++++++++++++++++++++++---- source/chapter5-flattened-format.rst | 10 +++++++++ source/references.rst | 4 ++++ 3 files changed, 41 insertions(+), 4 deletions(-) diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index a5684d2..c248f53 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -160,6 +160,12 @@ If the VLE storage attribute is supported, with VLE=0. .. 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. ``/memory`` Examples ~~~~~~~~~~~~~~~~~~~~ @@ -205,8 +211,8 @@ address and length for the ``reg`` property of the 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 +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. @@ -341,13 +347,30 @@ nodes by adding a ``memory-region`` property to the device node. 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@72000000`` and 64MiB in size), +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-memory@77000000``, 64MiB). +one for multimedia processing (named ``multimedia@77000000``, 64MiB). .. code-block:: dts diff --git a/source/chapter5-flattened-format.rst b/source/chapter5-flattened-format.rst index 6eb6011..6b1e182 100644 --- a/source/chapter5-flattened-format.rst +++ b/source/chapter5-flattened-format.rst @@ -234,6 +234,16 @@ reservation block as a whole, shall be located at an 8-byte aligned 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: Structure Block diff --git a/source/references.rst b/source/references.rst index 961fa20..8400e96 100644 --- a/source/references.rst +++ b/source/references.rst @@ -23,3 +23,7 @@ .. [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/ + +.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A + `_, + February 2020, `UEFI Forum `_ From 283a190a6b5370466597ed8b0ff0e4185e5a5abb Mon Sep 17 00:00:00 2001 From: Grant Likely Date: Thu, 17 Sep 2020 15:11:47 +0100 Subject: [PATCH 25/49] Trivial: Add SPDX tags to source files Signed-off-by: Grant Likely --- FAQ.md | 2 ++ Makefile | 2 ++ README.md | 1 + linux-doc-removal-schedule.rst | 2 ++ source/acknowledgements.rst | 2 ++ source/chapter1-introduction.rst | 1 + source/chapter2-devicetree-basics.rst | 2 +- source/chapter3-devicenodes.rst | 2 ++ source/chapter4-device-bindings.rst | 2 ++ source/chapter5-flattened-format.rst | 2 ++ source/chapter6-source-language.rst | 2 ++ source/conf.py | 1 + source/index.rst | 2 ++ source/license.rst | 1 + source/references.rst | 1 + source/revhistory.rst | 2 ++ source/rst_prolog | 2 ++ writers-guide.rst | 2 ++ 18 files changed, 30 insertions(+), 1 deletion(-) diff --git a/FAQ.md b/FAQ.md index 0d8a032..c1a470e 100644 --- a/FAQ.md +++ b/FAQ.md @@ -43,3 +43,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/Makefile b/Makefile index 8e5475d..33446b0 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: Apache-2.0 +# # Minimal makefile for Sphinx documentation # diff --git a/README.md b/README.md index fa21ecf..57b16d8 100644 --- a/README.md +++ b/README.md @@ -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 index 90eeed0..b0ae9b1 100644 --- a/linux-doc-removal-schedule.rst +++ b/linux-doc-removal-schedule.rst @@ -8,3 +8,5 @@ The content of the following files have been imported into the spec from the Lin 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/chapter1-introduction.rst b/source/chapter1-introduction.rst index f50e6b5..6c806af 100644 --- a/source/chapter1-introduction.rst +++ b/source/chapter1-introduction.rst @@ -1,3 +1,4 @@ +.. SPDX-License-Identifier: Apache-2.0 .. _chapter-introduction: diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index f782137..50a6a86 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -1,4 +1,4 @@ - +.. SPDX-License-Identifier: Apache-2.0 .. _chapter-devicetree: diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index c248f53..b731b8f 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + .. _chapter-device-node-requirements: Device Node Requirements diff --git a/source/chapter4-device-bindings.rst b/source/chapter4-device-bindings.rst index 7e1a0f4..6e481f1 100644 --- a/source/chapter4-device-bindings.rst +++ b/source/chapter4-device-bindings.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: Apache-2.0 + .. _chapter-device-bindings: Device Bindings diff --git a/source/chapter5-flattened-format.rst b/source/chapter5-flattened-format.rst index 6b1e182..26efe6e 100644 --- a/source/chapter5-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 diff --git a/source/chapter6-source-language.rst b/source/chapter6-source-language.rst index 61d05d4..7b74846 100755 --- a/source/chapter6-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) diff --git a/source/conf.py b/source/conf.py index 1803dfa..51ffa2b 100644 --- a/source/conf.py +++ b/source/conf.py @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: Apache-2.0 # -*- coding: utf-8 -*- # # Devicetree Specification documentation build configuration file, created by diff --git a/source/index.rst b/source/index.rst index 568e72b..120c991 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,6 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. + SPDX-License-Identifier: Apache-2.0 + Welcome to Devicetree Specification's documentation! ==================================================== diff --git a/source/license.rst b/source/license.rst index 17a586f..b480895 100644 --- a/source/license.rst +++ b/source/license.rst @@ -1,3 +1,4 @@ +.. SPDX-License-Identifier: Apache-2.0 **Copyright** diff --git a/source/references.rst b/source/references.rst index 8400e96..8d8708d 100644 --- a/source/references.rst +++ b/source/references.rst @@ -1,3 +1,4 @@ +.. 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 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 From 5522013b5a2385d78c7fa0764770c64c37c141b6 Mon Sep 17 00:00:00 2001 From: Kumar Gala Date: Fri, 5 Feb 2021 11:47:46 -0600 Subject: [PATCH 26/49] Add addtional constraint on node name and property names. Require node name w/o unit-address and property names to be unique if they exist as the same level in the tree. Signed-off-by: Kumar Gala --- source/chapter2-devicetree-basics.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 50a6a86..976d75c 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -146,6 +146,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 (/). From b455431271d575475e14dc4d835d3694fb5119c9 Mon Sep 17 00:00:00 2001 From: Hector Martin Date: Wed, 10 Mar 2021 18:08:54 +0900 Subject: [PATCH 27/49] simple-bus: Add nonposted-mmio property This property indicates that nodes which are direct children of this bus shall use non-posted (i.e. no early return) MMIO mapping modes when mapping MMIO registers. This is a requirement that can be imposed by the bus on otherwise generic devices. Signed-off-by: Hector Martin --- source/chapter4-device-bindings.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/chapter4-device-bindings.rst b/source/chapter4-device-bindings.rst index 6e481f1..ee99209 100644 --- a/source/chapter4-device-bindings.rst +++ b/source/chapter4-device-bindings.rst @@ -437,5 +437,8 @@ represented as a node with a compatible value of "simple-bus". array>`` parent address to child address spaces (see :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 ==================================================================================================== From 089b0f31584b9ee5da0224c9e84b52b565f3de57 Mon Sep 17 00:00:00 2001 From: AristoChen Date: Wed, 17 Mar 2021 22:43:26 +0800 Subject: [PATCH 28/49] Fix incorrect format in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 57b16d8..e654a6f 100644 --- a/README.md +++ b/README.md @@ -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: >``` From 05a34819e59d57f3a2465d0a1b8148aa98bb7a37 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 23 Mar 2021 14:10:30 +1300 Subject: [PATCH 29/49] Add more restrictions on compatible strings Mostly we use lower case and we try to avoid underscores. Add a note about this. I believe this is just writing down the existing conventions. I have not gone as far as using a character table (as with aliases) or specifying a maximum length. Signed-off-by: Simon Glass --- source/chapter2-devicetree-basics.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 976d75c..fa39625 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -484,6 +484,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. A single comma is typically only used following a vendor + prefix. Underscores should not be used. + Example: ``compatible = "fsl,mpc8641", "ns16550";`` From deb8f231762a7c6fc3bd51785f3c392ead85983d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 8 Apr 2021 06:32:23 +1200 Subject: [PATCH 30/49] State the 64-bit alignment requirement earlier This is currently buried in a paragraph later in the Alignment section. State the requirement up front, along with a note about existing uses. Series-to: dtc Series-cc: rob Signed-off-by: Simon Glass --- source/chapter5-flattened-format.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/chapter5-flattened-format.rst b/source/chapter5-flattened-format.rst index 26efe6e..c7f7a48 100644 --- a/source/chapter5-flattened-format.rst +++ b/source/chapter5-flattened-format.rst @@ -390,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 From 963c5fae71e827f9000876d972a053658af398db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Mon, 17 May 2021 08:20:25 -0700 Subject: [PATCH 31/49] Add note about the initial character in a compatible MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Commit 05a34819e5 ("Add more restrictions on compatible strings") started to add recommendations on the contents of compatible strings. Add an additional recommendation that compatibles should start with a letter. In particular, this matches what dt-schema is doing. Signed-off-by: Martí Bolívar --- source/chapter2-devicetree-basics.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index fa39625..40be221 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -484,9 +484,9 @@ 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. A single comma is typically only used following a vendor - prefix. Underscores should not be used. + 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: From 9a499e06702627506308c522f2298301bf3e673f Mon Sep 17 00:00:00 2001 From: Arnaud Ferraris Date: Wed, 8 Sep 2021 21:29:01 +0200 Subject: [PATCH 32/49] Add new 'chassis-type' root node property ACPI-based systems generally provide DMI data allowing userspace software to identify the form-factor of the running system. Such information can be useful (for example, in order to implement different behavior on a desktop and on a smartphone) but is not readily available on DT-based systems. This patch proposes adding a new optional property to the root node, allowing a way to specify the system form factor. The new property is named `chassis-type`, using the same values as systemd's hostnamed. Signed-off-by: Arnaud Ferraris --- source/chapter3-devicenodes.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index b731b8f..1cea148 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -52,6 +52,17 @@ are descendants. The full path to the root node is ``/``. ``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 =========================================================================================== From 13a1a82d118b06e8c4c5b7cf393a4f52bb6a8dad Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Fri, 11 Jun 2021 15:21:13 -0600 Subject: [PATCH 33/49] Add Github Action CI workflow Travis-ci.org is going away and moving to Travis-ci.com requires some work. It would probably involve fixing authentication issues yet again. Instead, let's just move to a GH actions job which is fairly trivial to setup. This has the side benefit of CI will run on anyone's fork without further setup. As part of this, the specification file name gains a 'git-describe' based version number. Signed-off-by: Rob Herring --- .github/workflows/ci.yml | 60 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..99fc512 --- /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 + + - name: build pdf + run: | + make latexpdf + git fetch --tags --force # Needed to make git-describe work + 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 }} From 4294fd73f3635f81912870bd247ce1516eea5deb Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Thu, 16 Sep 2021 16:10:28 +0200 Subject: [PATCH 34/49] Describe "fail" status for /cpus/cpu* nodes There are situations where it is desirable to use the same base Device Tree for devices with a different number of CPUs: There may be CPU variants with different numbers of cores that can be used interchangably on the same mainboard, or there are multiple CPU sockets. Not needing to explicitly build a device tree for each such variant can make maintenance significantly easier. For this to work, a system firmware / bootloader needs to adjust the Device Tree by removing or disabling the excess CPU nodes. However, this is currently not easily possible due to the special meaning of the "disabled" status for CPU nodes: - A "disabled" CPU node is interpreted as inactive, but existent. The Linux kernel will attempt to enable such CPUs on boot, which will obviously fail for non-existent CPUs - Removing the CPU node altogether from a Device Tree is much more complex than setting a single property, as it may leave dangling phandle references, often requiring specific knowledge of other nodes' structure to deal with them. In the discussion [1] it was suggested to introduce a new status value for CPUs that should really not be used at all. Rob proposed to use the value "fail", which already exists in the generic definitions of the status property. [1] https://www.lkml.org/lkml/2020/8/26/1237 Suggested-by: Rob Herring Signed-off-by: Matthias Schiffer Signed-off-by: Rob Herring --- source/chapter3-devicenodes.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index 1cea148..9d8ef6e 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -614,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. @@ -623,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 @@ -639,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 From a13d0e0b84784ef23bcef6051dd32c9b6ec03d12 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Tue, 30 Nov 2021 09:05:47 -0600 Subject: [PATCH 35/49] README: Correct the URLs for releases The devicetree-specification-released repo is not used as releases are part of this repo on Github. Signed-off-by: Rob Herring --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e654a6f..bd997f0 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. From 4a159da56934a925e1ce33701e39115e0a573680 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Tue, 30 Nov 2021 09:07:22 -0600 Subject: [PATCH 36/49] README: Update CI status badge to GH workflow Travis CI is defunct and we've moved to GH workflows, so update the status badge. Signed-off-by: Rob Herring --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bd997f0..2d47e96 100644 --- a/README.md +++ b/README.md @@ -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 From 55d08962dbf8f9f4e56bda820a86ffbaef206dc7 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Tue, 30 Nov 2021 09:09:41 -0600 Subject: [PATCH 37/49] README: Update Rob's email address My Linaro email has not worked for some time. Update it to my kernel.org address. Signed-off-by: Rob Herring --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2d47e96..7c7bb40 100644 --- a/README.md +++ b/README.md @@ -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. From e15e2ab9467da1c474ab334c60ad52323c7c3228 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Tue, 30 Nov 2021 09:26:54 -0600 Subject: [PATCH 38/49] Update Arm copyright years thru 2021 The copyright for Arm, Ltd. is out of date. Signed-off-by: Rob Herring --- LICENSE | 2 +- source/license.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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/source/license.rst b/source/license.rst index b480895..16eccb8 100644 --- a/source/license.rst +++ b/source/license.rst @@ -6,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 From 092b05f794ae8b460f83fa4fe113fa2db7bed959 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Tue, 30 Nov 2021 09:40:05 -0600 Subject: [PATCH 39/49] Add version to specification text Currently the HTML version of the specification doesn't have any indication of the version. Add the version to the title in the doc. Signed-off-by: Rob Herring --- source/conf.py | 6 ++++++ source/index.rst | 5 ++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/source/conf.py b/source/conf.py index 51ffa2b..9bde1a8 100644 --- a/source/conf.py +++ b/source/conf.py @@ -90,6 +90,12 @@ def setup(app): with open('rst_prolog', 'rb') as pr: rst_prolog = pr.read().decode('utf-8') +rst_epilog = """ +.. |SpecVersion| replace:: {versionnum} +""".format( +versionnum = version, +) + # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/source/index.rst b/source/index.rst index 120c991..a4ece47 100644 --- a/source/index.rst +++ b/source/index.rst @@ -5,8 +5,8 @@ SPDX-License-Identifier: Apache-2.0 -Welcome to Devicetree Specification's documentation! -==================================================== +|spec-fullname| |SpecVersion| +====================================== .. toctree:: :numbered: @@ -30,4 +30,3 @@ Welcome to Devicetree Specification's documentation! * :ref:`genindex` * :ref:`modindex` * :ref:`search` - From 7e1cc178c4698715e47baa23743111cf83d789ef Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Tue, 30 Nov 2021 09:56:38 -0600 Subject: [PATCH 40/49] Update FAQ release location and frequency questions The FAQ is horribly out of date. Fix the easy answers... Signed-off-by: Rob Herring --- FAQ.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/FAQ.md b/FAQ.md index c1a470e..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 From 84c7557cb63410cd34a7c3f10f31229bdc7d341e Mon Sep 17 00:00:00 2001 From: Jaap Keuter Date: Sat, 11 Dec 2021 22:21:20 +0100 Subject: [PATCH 41/49] Use valid MAC address example Closes #47 Signed-off-by: Jaap Keuter --- source/chapter4-device-bindings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/chapter4-device-bindings.rst b/source/chapter4-device-bindings.rst index ee99209..02a8fa0 100644 --- a/source/chapter4-device-bindings.rst +++ b/source/chapter4-device-bindings.rst @@ -270,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 From 1c6c0c8a6f60401f03ddd53bb9ea223df36dbb39 Mon Sep 17 00:00:00 2001 From: Manivannan Sadhasivam Date: Tue, 21 Dec 2021 12:36:19 +0530 Subject: [PATCH 42/49] Add SPMI to the list of generic node names System Power Management Interface Protocol (SPMI) is a MIPI standard bus used to connect the Power Management Integrated Circuits (PMIC) to the SoCs. Let's add "spmi" to the list of generic node names. Signed-off-by: Manivannan Sadhasivam --- source/chapter2-devicetree-basics.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 40be221..22569b6 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -273,6 +273,7 @@ name should be one of the following choices: * serial * sound * spi + * spmi * sram-controller * ssi-controller * syscon From 3ff0688d9ec60362d3f16357d46ae6d9b23fa48e Mon Sep 17 00:00:00 2001 From: Bill Mills Date: Wed, 23 Feb 2022 09:32:11 -0500 Subject: [PATCH 43/49] Fix multi-level cache example. The cache-level 2 statement should be in the level 2 cache node, not the cpu level where level 1 is assumed. Signed-off-by: Bill Mills --- source/chapter3-devicenodes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index 9d8ef6e..ceac92d 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -974,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 From 321b1b4df8bd0227836ebb0f357660a5cb2e4259 Mon Sep 17 00:00:00 2001 From: Bill Mills Date: Wed, 23 Feb 2022 18:14:48 -0500 Subject: [PATCH 44/49] Workaround: Delete problematic edge in interrupt tree example dot has an issue with edges between two "record" shaped nodes that are directly on top of each other. This is reported to occur since 2.40 of graphviz. In v0.3 this device1 -> i-device1 edge was not drawn either but now this error causes the whole diagram to be missing from the output. Until dot is fixed or a better work around is found, delete the problematic edge. This gets us back to the v0.3 state. Signed-off-by: Bill Mills --- source/chapter2-devicetree-basics.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 22569b6..47d2fad 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -986,7 +986,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 } From 639f3e9a97040b6a60ee8716748b558bf883aae1 Mon Sep 17 00:00:00 2001 From: Heiko Stuebner Date: Thu, 16 Jun 2022 20:14:37 +0200 Subject: [PATCH 45/49] Add 'dma-noncoherent' property as a standard property Similar to the 'dma-coherent' property, some architectures may be coherent by default with some devices being non-coherent. Add a property for this case tool. Signed-off-by: Heiko Stuebner --- source/chapter2-devicetree-basics.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 47d2fad..bdd7b9f 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -832,6 +832,19 @@ Description: 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) ~~~~~~~~~~~~~~~~~ From 75b03995fceb6ee5553a26135cd37bd0d86ead76 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 18 Nov 2022 14:31:44 -0700 Subject: [PATCH 46/49] Adjust language around what a device is The current definition is causing people to decide that only 'real' hardware devices should be in the device tree. Rewrite two paragraphs to adjust this. Signed-off-by: Simon Glass --- source/chapter2-devicetree-basics.rst | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index bdd7b9f..1072983 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -26,13 +26,24 @@ 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** From c2cdd4a0db1d79f245ab62362191aa3fad2f4a43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Przywara?= Date: Tue, 7 Feb 2023 00:39:37 +0000 Subject: [PATCH 47/49] cpus node: Make clock-frequency optional Modern CPU implementations overwhelmingly implement frequency scaling, so there is no real notion of "the current" CPU clock frequency anymore. Make the "clock-frequency" and "timebase-frequency" property of each CPU node optional instead of required, and reword the description of the clock-frequency to only encourage using this property if the CPU speed is fixed. Signed-off-by: Andre Przywara --- source/chapter3-devicenodes.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index ceac92d..958257e 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -592,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: From bc6e9455de0a7f747b8bc2e61eda2766d7884cf8 Mon Sep 17 00:00:00 2001 From: Luca Weiss Date: Sun, 30 Apr 2023 13:06:17 +0200 Subject: [PATCH 48/49] Add 'vibrator' to list of generic node names Closes #58 Signed-off-by: Luca Weiss --- source/chapter2-devicetree-basics.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 1072983..5ab9e6e 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -295,6 +295,7 @@ name should be one of the following choices: * usb * usb-hub * usb-phy + * vibrator * video-codec * vme * watchdog From 112f53cc57e5931f1503dfcaa1644caf15362c30 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Wed, 28 Jun 2023 10:58:51 -0600 Subject: [PATCH 49/49] github workflow: Attempt to fix version in doc The released version wasn't picking up the release tag, but using the prior tag instead. Signed-off-by: Rob Herring --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 99fc512..0b21191 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,11 +27,11 @@ jobs: 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 - git fetch --tags --force # Needed to make git-describe work mv build/latex/devicetree-specification.pdf build/latex/devicetree-specification-$(git describe).pdf - name: build html run: make html