Re: editing-type thoughts on devicetree spec 0.1 document

[Frank Rowand <frowand.list-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

adding devicetree-spec to distribution list

-Frank

On 08/20/17 12:08, Robert P. J. Day wrote:
> 
>   Was recently asked to give a short tutorial on device trees, so
> started perusing the current 0.1 spec, comparing contents to current
> linux git repo, made a few notes, here they are, admittedly incredibly
> nitpicky so anyone is free to do with them what they want or just
> ignore them in their entirety; it's just my editor/proofreader side
> coming out. Page numbers refer to PDF document.
> 
> p. 2: "... would like [to] thank ..."
> 
> p. 2: "... development [of] this specification ..."
> 
> p. 3: "In this document the term boot program ..."; italicize "boot
> program"
> 
> p. 3,4: "Examples of a boot programs [sic] ..."
> 
> p. 4: "IEEE-1275" should not be hyphenated (occurs more than once)
> 
> p. 4: Should it be "PowerISA" or "Power ISA"? Both forms are used.
> 
> p. 6: "An [sic] DTSpec-compliant ..."
> 
> p. 7: "The nodes with the name Ethernet [sic] ..." actually, it's
> "ethernet".
> 
> p. 8: Why are uart node and first ethernet node both at fe001000? Is
> that deliberate? That seems wrong.
> 
> p. 9: Non-standard property names include orgs fsl, ibm and linux ...
> i would be tempted to add samsung since there is a *ton* of samsung
> content of that form. Just a thought.
> 
> p. 11: "Chapter 4 describes the representation of specific devices
> [and?] may also specify additional requirements."
> 
> p. 11: Example of compatible property is:
> 
>   compatible = "fsl,mpc8641-uart", "ns16550";
> 
> No such line appears in the current kernel source, but there is a
> *pile* of:
> 
>   compatible = "fsl,ns16550", "ns16550";
> 
> if one wants to provide an example that actually occurs in the source.
> 
> p. 11: What is the "model" property used for? Apart from being
> moderately informational, is it used for any compatibility matching?
> That short section doesn't make that clear.
> 
> p. 12: Regarding the deprecated "linux,phandle" property, the current
> linux source using that as part of an actual DTS file appears to
> consist entirely of three occurrences:
> 
>   arm/boot/dts/imx6qdl-gw560x.dtsi:	linux,phandle = <&reg_vdd_arm>;
>   arm/boot/dts/imx6qdl-gw5903.dtsi:	linux,phandle = <&reg_vdd_arm>;
>   arm/boot/dts/imx6qdl-gw5903.dtsi:	linux,phandle = <&reg_vdd_soc>;
> 
> If those last three instances were fixed, would there be any need to
> continue supporting "linux,phandle"?
> 
> Still on the topic of phandles, i notice a number of lines of the
> form:
> 
>   dcr-parent = <&{/cpus/cpu@0}>;
> 
> What's with the curly braces there? Perhaps i missed it, but those
> don't seem to be explained in the spec. Are curly braces required when
> specifying the full path to the node name? If so, is that mentioned
> somewhere?
> 
> p. 12: One listed value for status is "okay", but I notice a number of
> lines in various DTS files:
> 
>   status = "ok";
> 
> If that's an acceptable alternative, it should be mentioned.
> 
> p. 13: "arbitraty"
> 
> 
>   i think i need to take a break and read the interrupts section
> carefully.
> 
> rday
>