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

[David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>]

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