Skip to contentSkip to conversation

Clarify DTB section preable

PATCH In review Grant Likely 3 participants 4 messages Dec 12, 2017 – Dec 16, 2017 2 messages not in the archive

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Clarify DTB section preable

The DTB chapter used to be titled the "Flattened Devicetree Structure" chapter, but that seems to be unclear when it is talking about a specific encoding of devicetree. In this case, the encoding is 'dtb'. The source format chapter specifies "DTS", so change the start of this chapter to line up with the DTS chapter.

At the same time, update the introduction to include the source format chapter.

---
 source/flattened-format.rst | 17 ++++++++++++-----
 source/source-language.rst  |  2 +-
 2 files changed, 13 insertions(+), 6 deletions(-)
source/flattened-format.rst +12 -5
index a1c358e..bd98891 100644
@@ -1,13 +1,20 @@
 .. _chapter-fdt-structure:
 
-Flat Devicetree Physical Structure
+Flattened Devicetree (DTB) Format
 ==================================
 
-With the exception of platforms using IEEE1275 Open Firmware [IEEE1275], the
-devicetree data is contained within a single, linear, pointerless data structure
-known as the flattened devicetree or devicetree blob.
+The Devicetree Blob (DTB) format is a flat binary encoding of devicetree data.
+It used to exchange devicetree data between software programs.
+For example, when booting an operating system, firmware will pass a DTB to the OS kernel.
 
-This data structure consists of a small header
+.. note::
+
+   IEEE1275 Open Firmware [IEEE1275] does not define the DTB format.
+   On most Open Firmware compliant platforms the devicetree is extracted by calling firmware methods
+   to walk through the tree structure.
+
+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`),
 followed by three variable sized sections:
 the memory reservation block (see section :ref:`sect-fdt-memory-reservation-block`),
source/source-language.rst +1 -1
index fd6f8af..8dd9710 100755
@@ -1,6 +1,6 @@
 .. _chapter-devicetree-source-format:
 
-Devicetree Source Format (version 1)
+Devicetree Source (DTS) Format (version 1)
 ================================================
 
 The Devicetree Source (DTS) format is a textual representation of a
Signature · 1 line
2.11.0

A message that is not in the archive (sent off-list or not yet received): [email protected]

#2 lore raw
Quoted 50 lines · Grant Likely

The DTB chapter used to be titled the "Flattened Devicetree Structure" chapter, but that seems to be unclear when it is talking about a specific encoding of devicetree. In this case, the encoding is 'dtb'. The source format chapter specifies "DTS", so change the start of this chapter to line up with the DTS chapter.

At the same time, update the introduction to include the source format chapter.

---
 source/flattened-format.rst | 17 ++++++++++++-----
 source/source-language.rst  |  2 +-
 2 files changed, 13 insertions(+), 6 deletions(-)
source/flattened-format.rst +12 -5
index a1c358e..bd98891 100644
@@ -1,13 +1,20 @@
 .. _chapter-fdt-structure:
 
-Flat Devicetree Physical Structure
+Flattened Devicetree (DTB) Format
 ==================================
 
-With the exception of platforms using IEEE1275 Open Firmware [IEEE1275], the
-devicetree data is contained within a single, linear, pointerless data structure
-known as the flattened devicetree or devicetree blob.
+The Devicetree Blob (DTB) format is a flat binary encoding of devicetree data.
+It used to exchange devicetree data between software programs.
+For example, when booting an operating system, firmware will pass a DTB to the OS kernel.
 
-This data structure consists of a small header
+.. note::
+
+   IEEE1275 Open Firmware [IEEE1275] does not define the DTB format.
+   On most Open Firmware compliant platforms the devicetree is extracted by calling firmware methods
+   to walk through the tree structure.
+
+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`),
 followed by three variable sized sections:
 the memory reservation block (see section :ref:`sect-fdt-memory-reservation-block`),
source/source-language.rst +0 -0
index fd6f8af..8dd9710 100755

source/source-language.rst

Quoted 8 lines
source/source-language.rst +1 -2
@@ -1,6 +1,6 @@
 .. _chapter-devicetree-source-format:
 
-Devicetree Source Format (version 1)
+Devicetree Source (DTS) Format (version 1)
 ================================================
 
 The Devicetree Source (DTS) format is a textual representation of a
--

Oops, this hunk got omitted from the patch:

source/introduction.rst +1 -2
index d7dc2fc..8105c4f 100644
@@ -55,8 +55,8 @@ may include:
   devicetrees.
 * Chapter :ref:`chapter-device-bindings` describes device bindings for
   certain classes of devices and specific device types.
-* Chapter :ref:`chapter-fdt-structure` specifies the physical structure
-  of devicetrees.
+* Chapter :ref:`chapter-fdt-structure` specifies the DTB encoding of

devicetrees.
+* Chapter :ref:chapter-devicetree-source-format specifies the DTS source language.

**Conventions Used in this Document**

Quoted 2 lines

2.11.0

A message that is not in the archive (sent off-list or not yet received): CACxGe6v5uFLM5eAnFrRTP1z2+BaUHKaa98y29nZJTyP=Mw4OFg-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

Reviewed-by
#4 lore raw
Quoted 54 lines · Grant Likely
Quoted 52 lines · Grant Likely

The DTB chapter used to be titled the "Flattened Devicetree Structure" chapter, but that seems to be unclear when it is talking about a specific encoding of devicetree. In this case, the encoding is 'dtb'. The source format chapter specifies "DTS", so change the start of this chapter to line up with the DTS chapter.

At the same time, update the introduction to include the source format chapter.

---
 source/flattened-format.rst | 17 ++++++++++++-----
 source/source-language.rst  |  2 +-
 2 files changed, 13 insertions(+), 6 deletions(-)
source/flattened-format.rst +12 -5
index a1c358e..bd98891 100644
@@ -1,13 +1,20 @@
 .. _chapter-fdt-structure:
 
-Flat Devicetree Physical Structure
+Flattened Devicetree (DTB) Format
 ==================================
 
-With the exception of platforms using IEEE1275 Open Firmware [IEEE1275], the
-devicetree data is contained within a single, linear, pointerless data structure
-known as the flattened devicetree or devicetree blob.
+The Devicetree Blob (DTB) format is a flat binary encoding of devicetree data.
+It used to exchange devicetree data between software programs.
+For example, when booting an operating system, firmware will pass a DTB to the OS kernel.
 
-This data structure consists of a small header
+.. note::
+
+   IEEE1275 Open Firmware [IEEE1275] does not define the DTB format.
+   On most Open Firmware compliant platforms the devicetree is extracted by calling firmware methods
+   to walk through the tree structure.
+
+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`),
 followed by three variable sized sections:
 the memory reservation block (see section :ref:`sect-fdt-memory-reservation-block`),
source/source-language.rst +0 -0
index fd6f8af..8dd9710 100755
@@ -1,6 +1,6 @@
 .. _chapter-devicetree-source-format:
 
Quoted 8 lines

source/source-language.rst

Quoted 6 lines
source/source-language.rst +1 -2
-Devicetree Source Format (version 1)
+Devicetree Source (DTS) Format (version 1)
 ================================================
 
 The Devicetree Source (DTS) format is a textual representation of a
--

Oops, this hunk got omitted from the patch:

With this hunk:

#5 lore raw
In reply to a message not in the archive
Quoted 23 lines · Grant Likely

The DTB chapter used to be titled the "Flattened Devicetree Structure" chapter, but that seems to be unclear when it is talking about a specific encoding of devicetree. In this case, the encoding is 'dtb'. The source format chapter specifies "DTS", so change the start of this chapter to line up with the DTS chapter.

At the same time, update the introduction to include the source format chapter.

---
 source/flattened-format.rst | 17 ++++++++++++-----
 source/source-language.rst  |  2 +-
 2 files changed, 13 insertions(+), 6 deletions(-)
source/flattened-format.rst +0 -1
index a1c358e..bd98891 100644
@@ -1,13 +1,20 @@
 .. _chapter-fdt-structure:
 
-Flat Devicetree Physical Structure

source/flattened-format.rst line 9

Quoted 10 lines
source/flattened-format.rst +3 -3
+Flattened Devicetree (DTB) Format
 ==================================
 
-With the exception of platforms using IEEE1275 Open Firmware [IEEE1275], the
-devicetree data is contained within a single, linear, pointerless data structure
-known as the flattened devicetree or devicetree blob.
+The Devicetree Blob (DTB) format is a flat binary encoding of devicetree data.
 
 
+It used to exchange devicetree data between software programs.> +For example, when booting an operating system, firmware will pass a DTB to the OS kernel.

That wording is vague enough to allow the imaginative reader plenty of room to jump to false conclusions. For example, someone with a BIOS background might assume that the kernel can use the blob to communicate to the boot loader.

The wording at the start of the 4th paragraph on p. 4 (the "Relationship to IEEE 1275 and ePAPR" section) is more clear and precise:

"... concepts from the devicetree architecture by which a boot program can
describe and communicate system hardware information to client program, thus eliminating the need for the client program to have hard-coded descriptions of system hardware."

I would suggest to either not add the two sentences in the patch, or else to model them to be more like the wording on p. 4.

Quoted 26 lines
source/flattened-format.rst +8 -1
-This data structure consists of a small header
+.. note::
+
+   IEEE1275 Open Firmware [IEEE1275] does not define the DTB format.
+   On most Open Firmware compliant platforms the devicetree is extracted by calling firmware methods
+   to walk through the tree structure.
+
+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`),
 followed by three variable sized sections:
 the memory reservation block (see section :ref:`sect-fdt-memory-reservation-block`),
source/source-language.rst +1 -1
index fd6f8af..8dd9710 100755
@@ -1,6 +1,6 @@
 .. _chapter-devicetree-source-format:
 
-Devicetree Source Format (version 1)
+Devicetree Source (DTS) Format (version 1)
 ================================================
 
 The Devicetree Source (DTS) format is a textual representation of a