more pedantic proofing of DTSpec version 0.1

more pedantic proofing of DTSpec version 0.1

[Robert P. J. Day]

  a few more notes on more of the 0.1 DTSpec; all page numbers refer
to the current PDF doc. lots of nitpickery, feel free to ignore any or
all.

p. 21: "... an [sic] DTSpec-compliant devicetree." (there are a number
of places in the spec that use "an" before "DTSpec", which seems
awkward.)

p. 21: in that early bullet list, is there a reason that the "/cpus"
node name has a leading slash, and the "memory" node name does not?
that seems inconsistent. (p.s. it's presented as "/memory" on the very
next page.)

p. 21: table 3.1 mentions "model" root node property but, as before,
it's not clear what value that property has, other than being mildly
informational. is it actually used for anything in terms of matching?

p. 21: table 3.1 uses example of "fsl,mpc8572ds" for compatibility;
there is no longer any such string in the kernel source, i'd replace
that with "fsl,ns16550", of which there are plenty of occurrences.

p. 21,22: explanation of /aliases node refers solely to property
values specifying the "full path" to a node in the device tree, using
examples like:

  aliases {
      serial0 = "/simple-bus@fe000000/serial@llc500";
      ethernet0 = "/simple-bus@fe000000/ethernet@31c000";
  }    <----- missing semicolon?

but (of course) everyone uses much shorter forms such as:

   aliases {
      mmcblk0 = &mmc1;
      mmcblk1 = &mmc2;
   };

is there a reason that section doesn't mention this second form? are
readers simply supposed to know automatically about that? note that
the wording in that section *strongly* implies that the property value
*must* be a full path and nothing else, so it seems at least a little
misleading.

p. 22: "Given the alias serial0, ..." i would render "serial0" in
monospaced font for consistency.

p. 23,24: i notice in the kernel that the OF code searches for the
node "/chosen" and, as an alternative, "/chosen@0". i assume a node
name of "/chosen@0" is long dead and need not be mentioned. in any
event, i don't see a single DTS file in the current tree that uses it.

p. 24,25: it might be worth rendering more content in monospaced font
to make it clear that content is, say, a proper (node?) name. eg., in
the section "/cpus Node Properties," lines like:

  "A [cpus] node ..."
  "... for child [cpu] nodes ..."
  "The [cpus] node ..."
  "A [cpu] node ..."
  "... may be placed in the [cpus] node instead."

  ... and so on. most of the time, node names are rendered that way,
so might as well be consistent. also using a leading slash in cases
like that would be consistent.

p. 25: table 3.6, the acronym "PIR" comes out of nowhere, perhaps
explain it the first time?

p. 32: "... of other each [sic]."

p. 32: "... if the new device fits into one [of] the ..."
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: more pedantic proofing of DTSpec version 0.1

[Rob Herring]

On Sat, Aug 26, 2017 at 10:50:46AM -0400, Robert P. J. Day wrote:
> 
>   a few more notes on more of the 0.1 DTSpec; all page numbers refer
> to the current PDF doc. lots of nitpickery, feel free to ignore any or
> all.

Can you send patches at least for ones you know what the correction 
should be. I'm happy to apply. Less likely to go fix them myself.
> 
> p. 21: "... an [sic] DTSpec-compliant devicetree." (there are a number
> of places in the spec that use "an" before "DTSpec", which seems
> awkward.)

Because it used to say "an ePAPR-compliant ..."

> p. 21: in that early bullet list, is there a reason that the "/cpus"
> node name has a leading slash, and the "memory" node name does not?
> that seems inconsistent. (p.s. it's presented as "/memory" on the very
> next page.)
> 
> p. 21: table 3.1 mentions "model" root node property but, as before,
> it's not clear what value that property has, other than being mildly
> informational. is it actually used for anything in terms of matching?

That won't be easy to fix because PowerPC and ARM diverged here. For 
ARM, it is just descriptive. For PowerPC, it's similar to top-level 
compatible. If the spec is not clear, I don't have a better explanation. 
ePAPR predates me.

> p. 21: table 3.1 uses example of "fsl,mpc8572ds" for compatibility;
> there is no longer any such string in the kernel source, i'd replace
> that with "fsl,ns16550", of which there are plenty of occurrences.

Of course, FSL as a company doesn't exist anymore either...

I don't think it matters. Chips come and go in the kernel and I don't 
think we should try to keep examples in sync unless they are just wrong 
for current style guidelines.

> p. 21,22: explanation of /aliases node refers solely to property
> values specifying the "full path" to a node in the device tree, using
> examples like:
> 
>   aliases {
>       serial0 = "/simple-bus@fe000000/serial@llc500";
>       ethernet0 = "/simple-bus@fe000000/ethernet@31c000";
>   }    <----- missing semicolon?

Yes.

> 
> but (of course) everyone uses much shorter forms such as:
> 
>    aliases {
>       mmcblk0 = &mmc1;
>       mmcblk1 = &mmc2;
>    };
> 
> is there a reason that section doesn't mention this second form? are
> readers simply supposed to know automatically about that? note that
> the wording in that section *strongly* implies that the property value
> *must* be a full path and nothing else, so it seems at least a little
> misleading.

Those compile to the same thing. The latter is just convenience in the 
source format.

> 
> p. 22: "Given the alias serial0, ..." i would render "serial0" in
> monospaced font for consistency.
> 
> p. 23,24: i notice in the kernel that the OF code searches for the
> node "/chosen" and, as an alternative, "/chosen@0". i assume a node
> name of "/chosen@0" is long dead and need not be mentioned. in any
> event, i don't see a single DTS file in the current tree that uses it.

That could be for real OpenFirmware which doesn't apply to DTSpec. So I 
think you're right.

> 
> p. 24,25: it might be worth rendering more content in monospaced font
> to make it clear that content is, say, a proper (node?) name. eg., in
> the section "/cpus Node Properties," lines like:
> 
>   "A [cpus] node ..."
>   "... for child [cpu] nodes ..."
>   "The [cpus] node ..."
>   "A [cpu] node ..."
>   "... may be placed in the [cpus] node instead."
> 
>   ... and so on. most of the time, node names are rendered that way,
> so might as well be consistent. also using a leading slash in cases
> like that would be consistent.

Agreed on the font. I think the leading / makes sense if we are talking 
about the full path, but for just the node name it should not have a 
leading /. So '/cpus' and 'cpu' in this case.


> p. 25: table 3.6, the acronym "PIR" comes out of nowhere, perhaps
> explain it the first time?

I'm drawing a blank as to what that is.

> 
> p. 32: "... of other each [sic]."
> 
> p. 32: "... if the new device fits into one [of] the ..."
> --
> To unsubscribe from this list: send the line "unsubscribe devicetree" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: more pedantic proofing of DTSpec version 0.1

[Robert P. J. Day]

On Thu, 31 Aug 2017, Rob Herring wrote:

> On Sat, Aug 26, 2017 at 10:50:46AM -0400, Robert P. J. Day wrote:
> >
> >   a few more notes on more of the 0.1 DTSpec; all page numbers refer
> > to the current PDF doc. lots of nitpickery, feel free to ignore any or
> > all.
>
> Can you send patches at least for ones you know what the correction
> should be. I'm happy to apply. Less likely to go fix them myself.

  can i post patches to this list? is that acceptable? i'll try to
bundle aesthetic fixes into a single patch.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: more pedantic proofing of DTSpec version 0.1

[Frank Rowand]

On 08/31/17 13:56, Rob Herring wrote:
> On Sat, Aug 26, 2017 at 10:50:46AM -0400, Robert P. J. Day wrote:
>>

< snip >

>> p. 25: table 3.6, the acronym "PIR" comes out of nowhere, perhaps
>> explain it the first time?
> 
> I'm drawing a blank as to what that is.

According to the Mindshare book: PowerPC System Architecture:

"Processor ID Register (PIR)

The PIR is a 32-bit register that can be used by the OS to assign
an ID to the processor.  Aside from any OS-specific usage of the
assigned ID, the processor uses the ID when communicating with
I/O devices."

< snip >


--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: more pedantic proofing of DTSpec version 0.1

[Robert P. J. Day]

On Tue, 5 Sep 2017, Frank Rowand wrote:

> On 08/31/17 13:56, Rob Herring wrote:
> > On Sat, Aug 26, 2017 at 10:50:46AM -0400, Robert P. J. Day wrote:
> >>
>
> < snip >
>
> >> p. 25: table 3.6, the acronym "PIR" comes out of nowhere, perhaps
> >> explain it the first time?
> >
> > I'm drawing a blank as to what that is.
>
> According to the Mindshare book: PowerPC System Architecture:
>
> "Processor ID Register (PIR)
>
> The PIR is a 32-bit register that can be used by the OS to assign
> an ID to the processor.  Aside from any OS-specific usage of the
> assigned ID, the processor uses the ID when communicating with
> I/O devices."

  whoops, then my patch was wrong. dang.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html