[PATCH] Add description of labels to source format chapter

[PATCH] Add description of labels to source format chapter

[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.

Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
---
 source/source-language.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 mode change 100644 => 100755 source/source-language.rst

diff --git a/source/source-language.rst b/source/source-language.rst
old mode 100644
new mode 100755
index cefbbd8..c17aab0
--- a/source/source-language.rst
+++ b/source/source-language.rst
@@ -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
 -----------------------------
 
-- 
2.11.0

Re: [PATCH] Add description of labels to source format chapter

[Grant Likely]

On Mon, Nov 27, 2017 at 4:14 PM, Grant Likely <grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
> 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.
>
> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
> ---
>  source/source-language.rst | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
>  mode change 100644 => 100755 source/source-language.rst
>
> diff --git a/source/source-language.rst b/source/source-language.rst
> old mode 100644
> new mode 100755
> index cefbbd8..c17aab0
> --- a/source/source-language.rst
> +++ b/source/source-language.rst
> @@ -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.

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.

> +
> +.. 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
>

Re: [PATCH] Add description of labels to source format chapter

[Rob Herring]

On Mon, Nov 27, 2017 at 10:14 AM, Grant Likely
<grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
> 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.
>
> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
> ---
>  source/source-language.rst | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
>  mode change 100644 => 100755 source/source-language.rst
>
> diff --git a/source/source-language.rst b/source/source-language.rst
> old mode 100644
> new mode 100755
> index cefbbd8..c17aab0
> --- a/source/source-language.rst
> +++ b/source/source-language.rst
> @@ -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?

> +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).

> +
> +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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Add description of labels to source format chapter

[Grant Likely]

On Mon, Nov 27, 2017 at 6:44 PM, Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:
> On Mon, Nov 27, 2017 at 10:14 AM, Grant Likely
> <grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
>> 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.
>>
>> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
>> ---
>>  source/source-language.rst | 27 +++++++++++++++++++++++++++
>>  1 file changed, 27 insertions(+)
>>  mode change 100644 => 100755 source/source-language.rst
>>
>> diff --git a/source/source-language.rst b/source/source-language.rst
>> old mode 100644
>> new mode 100755
>> index cefbbd8..c17aab0
>> --- a/source/source-language.rst
>> +++ b/source/source-language.rst
>> @@ -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/

Got it, thanks.

>
> 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: ;


>
> 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.

>
>> +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.

Re: [PATCH] Add description of labels to source format chapter

[David Gibson]

[-- Attachment #1: Type: text/plain, Size: 3218 bytes --]

On Mon, Nov 27, 2017 at 12:44:49PM -0600, Rob Herring wrote:
> On Mon, Nov 27, 2017 at 10:14 AM, Grant Likely
> <grant.likely-s3s/WqlpOiPyB63q8FvJNQ@public.gmane.org> wrote:
> > 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.
> >
> > Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
> > ---
> >  source/source-language.rst | 27 +++++++++++++++++++++++++++
> >  1 file changed, 27 insertions(+)
> >  mode change 100644 => 100755 source/source-language.rst
> >
> > diff --git a/source/source-language.rst b/source/source-language.rst
> > old mode 100644
> > new mode 100755
> > index cefbbd8..c17aab0
> > --- a/source/source-language.rst
> > +++ b/source/source-language.rst
> > @@ -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";

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.

> 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.

> > +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).
> 
> > +
> > +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
> >  -----------------------------
> >
> >

-- 
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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]