Skip to contentSkip to conversation

Add description of labels to source format chapter

PATCH In review Grant Likely 3 participants 5 messages Nov 27, 2017 2 messages not in the archive

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Add description of labels to source format chapter

The source format chapter was missing details about the characters that are valid for labels and what labels are for. Add a paragraph to cover those details.

---
 source/source-language.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 mode change 100644 => 100755 source/source-language.rst
source/source-language.rst +27 -0
old mode 100644
new mode 100755
index cefbbd8..c17aab0
@@ -22,6 +22,33 @@ additional files.
 
     /include/ "FILE"
 
+Labels
+------
+The source format support attaching labels to any node or property data in the device tree.
+Phandle and path references can be automatically generated by referencing the label instead of
+explicitly specifying the phandle value or the full path to a node.
+Labels are only used in the devicetree source format and are not encoded into the binary format.
+
+A label shall be between 1 to 31 characters in length,
+be composed only of the characters in the set :numref:`label-characters`,
+and must not start with a number.
+
+Labels are created by appending a colon (':') to the label name.
+References are created by adding an ampersand ('&') suffix to the label name.
+
+.. tabularcolumns:: | c p{8cm} |
+.. _label-characters:
+.. table:: Valid characters for DTS labels
+
+   ========= ================
+   Character Description
+   ========= ================
+   ``0-9``   digit
+   ``a-z``   lowercase letter
+   ``A-Z``   uppercase letter
+   ``_``     underscore
+   ========= ================
+
 Node and property definitions
 -----------------------------
 
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 23 lines · Grant Likely

The source format chapter was missing details about the characters that are valid for labels and what labels are for. Add a paragraph to cover those details.

---
 source/source-language.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 mode change 100644 => 100755 source/source-language.rst
source/source-language.rst +3 -0
old mode 100644
new mode 100755
index cefbbd8..c17aab0
@@ -22,6 +22,33 @@ additional files.
 
     /include/ "FILE"
 
+Labels
+------
+The source format support attaching labels to any node or property data in the device tree.

source/source-language.rst additional files. · line 37

Quoted 10 lines
source/source-language.rst +10 -0
+Phandle and path references can be automatically generated by referencing the label instead of
+explicitly specifying the phandle value or the full path to a node.
+Labels are only used in the devicetree source format and are not encoded into the binary format.
+
+A label shall be between 1 to 31 characters in length,
+be composed only of the characters in the set :numref:`label-characters`,
+and must not start with a number.
+
+Labels are created by appending a colon (':') to the label name.
+References are created by adding an ampersand ('&') suffix to the label name.

Oops, embarassing. This line should be:

References are created by prefixing the label name with an ampersand ('&').

Should really remember to commit my changes.

g.

Quoted 20 lines
source/source-language.rst +14 -1
+
+.. tabularcolumns:: | c p{8cm} |
+.. _label-characters:
+.. table:: Valid characters for DTS labels
+
+   ========= ================
+   Character Description
+   ========= ================
+   ``0-9``   digit
+   ``a-z``   lowercase letter
+   ``A-Z``   uppercase letter
+   ``_``     underscore
+   ========= ================
+
 Node and property definitions
 -----------------------------
 
--

2.11.0

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

The source format chapter was missing details about the characters that are valid for labels and what labels are for. Add a paragraph to cover those details.

---
 source/source-language.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 mode change 100644 => 100755 source/source-language.rst
source/source-language.rst +0 -0
old mode 100644
new mode 100755
index cefbbd8..c17aab0

source/source-language.rst additional files. · line 27

Quoted 6 lines
source/source-language.rst +3 -0
@@ -22,6 +22,33 @@ additional files.
 
     /include/ "FILE"
 
+Labels
+------
+The source format support attaching labels to any node or property data in the device tree.

s/support/supports/

What do you mean by property data? You can do:

label: foo = "bar";

News to me if so. But how would one use that in a reference?

source/source-language.rst additional files. · line 30

Quoted 3 lines
source/source-language.rst +3 -0
+Phandle and path references can be automatically generated by referencing the label instead of
+explicitly specifying the phandle value or the full path to a node.
+Labels are only used in the devicetree source format and are not encoded into the binary format.

The last part is not true now with overlays (A mistake IMO, primarily because we have no standard around label names).

Quoted 31 lines
source/source-language.rst +21 -1
+
+A label shall be between 1 to 31 characters in length,
+be composed only of the characters in the set :numref:`label-characters`,
+and must not start with a number.
+
+Labels are created by appending a colon (':') to the label name.
+References are created by adding an ampersand ('&') suffix to the label name.
+
+.. tabularcolumns:: | c p{8cm} |
+.. _label-characters:
+.. table:: Valid characters for DTS labels
+
+   ========= ================
+   Character Description
+   ========= ================
+   ``0-9``   digit
+   ``a-z``   lowercase letter
+   ``A-Z``   uppercase letter
+   ``_``     underscore
+   ========= ================
+
 Node and property definitions
 -----------------------------
 
--

2.11.0

--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): CAL_Jsq+eZ-=PoyWwpvTk+Urc4eYHfRyUiRQZ9_V6Z6UfLOfPNQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

#5 lore raw
Quoted 20 lines · Rob Herring
Quoted 18 lines · Grant Likely

The source format chapter was missing details about the characters that are valid for labels and what labels are for. Add a paragraph to cover those details.

---
 source/source-language.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 mode change 100644 => 100755 source/source-language.rst
source/source-language.rst +0 -0
old mode 100644
new mode 100755
index cefbbd8..c17aab0
@@ -22,6 +22,33 @@ additional files.
 
Quoted 7 lines

source/source-language.rst additional files. · line 27

Quoted 5 lines
source/source-language.rst +3 -0
     /include/ "FILE"
 
+Labels
+------
+The source format support attaching labels to any node or property data in the device tree.

s/support/supports/

Got it, thanks.

Quoted 2 lines

What do you mean by property data? You can do:

I should say "property value" here. Labels can be placed almost anywhere in the property data, but the only user of this is when emitting asm output.

Here's the text from further down in that file:

- Labels may also appear before or after any component of a property value, or between cells of a cell array, or between bytes of a bytestring. Examples:

::

        reg = reglabel: <0 sizelabel: 0x1000000>;
        prop = [ab cd ef byte4: 00 ff fe];
        str = start: "string value" end: ;
Quoted 4 lines

label: foo = "bar";

News to me if so. But how would one use that in a reference?

IIRC the intent was to allow dumb firmware to directly access part of the DT data when it is assembled and linked into the firmware binary.

Quoted 7 lines

source/source-language.rst additional files. · line 30

Quoted 4 lines
source/source-language.rst +3 -0
+Phandle and path references can be automatically generated by referencing the label instead of
+explicitly specifying the phandle value or the full path to a node.
+Labels are only used in the devicetree source format and are not encoded into the binary format.

The last part is not true now with overlays (A mistake IMO, primarily because we have no standard around label names).

RIght. Would you be okay with leaving this as-is in this commit, to be rewritten when overlay support is added to the spec?

Cheers,
g.

#6 lore raw
In reply to a message not in the archive
Quoted 28 lines · Rob Herring
Quoted 17 lines · Grant Likely

The source format chapter was missing details about the characters that are valid for labels and what labels are for. Add a paragraph to cover those details.

---
 source/source-language.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 mode change 100644 => 100755 source/source-language.rst
source/source-language.rst +0 -0
old mode 100644
new mode 100755
index cefbbd8..c17aab0

source/source-language.rst additional files. · line 27

Quoted 6 lines
source/source-language.rst +3 -0
@@ -22,6 +22,33 @@ additional files.
 
     /include/ "FILE"
 
+Labels
+------
+The source format support attaching labels to any node or property data in the device tree.

s/support/supports/

Quoted 3 lines

What do you mean by property data? You can do:

label: foo = "bar";

Yes, you can. Only really does anything if you're using -Oasm, though.

In fact you can even put labels in the middle of property data, but again only useful if you're using -Oasm.

Quoted 1 line

News to me if so. But how would one use that in a reference?

The idea came from an earlier time when I thought a more common option would be to use an essentially fixed device tree for a board, with only some "in place" changes of a few values. The idea is you could use -Oasm to link the dtb right into your bootloader/kernel/whatever then use the labels to use update the few neccessary values as though they were variables.

Quoted 32 lines

source/source-language.rst additional files. · line 30

Quoted 3 lines
source/source-language.rst +3 -0
+Phandle and path references can be automatically generated by referencing the label instead of
+explicitly specifying the phandle value or the full path to a node.
+Labels are only used in the devicetree source format and are not encoded into the binary format.

The last part is not true now with overlays (A mistake IMO, primarily because we have no standard around label names).

Quoted 25 lines
source/source-language.rst +21 -0
+
+A label shall be between 1 to 31 characters in length,
+be composed only of the characters in the set :numref:`label-characters`,
+and must not start with a number.
+
+Labels are created by appending a colon (':') to the label name.
+References are created by adding an ampersand ('&') suffix to the label name.
+
+.. tabularcolumns:: | c p{8cm} |
+.. _label-characters:
+.. table:: Valid characters for DTS labels
+
+   ========= ================
+   Character Description
+   ========= ================
+   ``0-9``   digit
+   ``a-z``   lowercase letter
+   ``A-Z``   uppercase letter
+   ``_``     underscore
+   ========= ================
+
 Node and property definitions
 -----------------------------
 
Signature · 4 lines
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson