Device tree node names

Device tree node names

[Stephen Warren]

As I understand it, there is a rule when writing device tree files (and
bindings) that nodes should be named after the type of object they
represent, and not the particular instance of the object. Related, node
names should not be interpreted as data.

This rules makes perfect sense when talking about nodes on a bus that
represent devices; something like:

    i2c@7000c000 {
        compatible = "nvidia,tegra20-i2c";
        reg = <0x7000c000 0x100>;
        ...
    };

    i2c@7000c400 {
        compatible = "nvidia,tegra20-i2c";
        reg = <0x7000c400 0x100>;
        ...
    };

However, when nodes are being used to represent configuration
information inside a device node, or even when representing
pseudo-devices that don't directly exist on a specific bus, this rules
becomes quite annoying.

As an example, consider a device that contains 10 voltage regulators
(named "ldon" in the chip documentation), and each needs some
configuration provided through DT. A simple binding might result in:

    i2c@7000c000 {
        ldo0 {
            ... (configuration data here)
        };
        ldo1 {
            ...
        };
        ...
    };

Where regulator "name"'s configuration is encoded into node "name".

Instead, if we follow this rule precisely, we end up with something more
like:

    i2c@7000c000 {
        #address-cells = <1>;
        #size-cells = <0>;

        ldo@0 {
            reg = <0>;
            regulator-id = "ldo0";
            ...
        };
        ldo@1 {
            reg = <1>;
            regulator-id = "ldo1";
            ...
        };
        ...
    };

This is a fair bit more wordy, and the only advantage appears to be that
it correctly conforms to some apparently arbitrary rule for node naming.

Similar situations exist when describing the set of power sequences
needed to enable/disable a device [1] or pinctrl configurations (see
Linux kernel file arch/arm/boot/dts/tegra20-harmony.dts, node
/pinmux/pinmux where I haven't actually followed this rule correctly) etc.

So, my question is: Can/should we relax this rule? Can we allow drivers
(bindings) to require specific node names for things, lookup up specific
configuration data by node name and/or enumerate all nodes, and parse
data out of the node names (e.g. the value n for nodes named LDOn in the
above example)?

[1]
https://lists.ozlabs.org/pipermail/devicetree-discuss/2012-August/018433.html

Re: Device tree node names

[Mitch Bradley]

On 8/16/2012 9:34 AM, Stephen Warren wrote:
> As I understand it, there is a rule when writing device tree files (and
> bindings) that nodes should be named after the type of object they
> represent, and not the particular instance of the object. Related, node
> names should not be interpreted as data.
> 
> This rules makes perfect sense when talking about nodes on a bus that
> represent devices; something like:
> 
>     i2c@7000c000 {
>         compatible = "nvidia,tegra20-i2c";
>         reg = <0x7000c000 0x100>;
>         ...
>     };
> 
>     i2c@7000c400 {
>         compatible = "nvidia,tegra20-i2c";
>         reg = <0x7000c400 0x100>;
>         ...
>     };
> 
> However, when nodes are being used to represent configuration
> information inside a device node, or even when representing
> pseudo-devices that don't directly exist on a specific bus, this rules
> becomes quite annoying.
> 
> As an example, consider a device that contains 10 voltage regulators
> (named "ldon" in the chip documentation), and each needs some
> configuration provided through DT. A simple binding might result in:
> 
>     i2c@7000c000 {
>         ldo0 {
>             ... (configuration data here)
>         };
>         ldo1 {
>             ...
>         };
>         ...
>     };
> 
> Where regulator "name"'s configuration is encoded into node "name".
> 
> Instead, if we follow this rule precisely, we end up with something more
> like:
> 
>     i2c@7000c000 {
>         #address-cells = <1>;
>         #size-cells = <0>;
> 
>         ldo@0 {
>             reg = <0>;
>             regulator-id = "ldo0";
>             ...
>         };
>         ldo@1 {
>             reg = <1>;
>             regulator-id = "ldo1";
>             ...
>         };
>         ...
>     };
> 
> This is a fair bit more wordy, and the only advantage appears to be that
> it correctly conforms to some apparently arbitrary rule for node naming.
> 
> Similar situations exist when describing the set of power sequences
> needed to enable/disable a device [1] or pinctrl configurations (see
> Linux kernel file arch/arm/boot/dts/tegra20-harmony.dts, node
> /pinmux/pinmux where I haven't actually followed this rule correctly) etc.
> 
> So, my question is: Can/should we relax this rule? Can we allow drivers
> (bindings) to require specific node names for things, lookup up specific
> configuration data by node name and/or enumerate all nodes, and parse
> data out of the node names (e.g. the value n for nodes named LDOn in the
> above example)?

As far as I'm concerned, within the privacy of your own node, you can do
whatever you want.  Perhaps others will disagree...

The main "rule" for node names is that a user browsing the device tree
can easily determine what something is.  Thus "ethernet" instead of
"DEC,21140".

As an historical note, in early Open Boot, it was just the other way
around.  I originally thought that node names should be precise - and
the ill-considered "device_type" property gave the "generic"
identification.   But it soon became clear that "precise" names were
neither human-understandable nor actually precise. Pathnames looked like
gobbledygook with strings of part numbers that only an expert could
remember, and the evolution of part numbers, coupled with companies
going out of business and other companies making compatible parts, made
"precise" names change semi-randomly.  Thus was born the "generic names"
rethink, in which the name became human-meaningful (but generally
meaningless to software in any precise sense), device_type was
deprecated, and compatible appeared, as a list.

> 
> [1]
> https://lists.ozlabs.org/pipermail/devicetree-discuss/2012-August/018433.html
> 

Associating devices with multiple parents

[Mitch Bradley]

Here is the situation:  We (OLPC) have an audio codec that is strongly
associated with an audio controller, but it also has some registers that
you get at with I2C.

In some sense, the codec has two parents, the audio controller
(connected via I2S) and the I2C controller.

Is there an established Linux convention for expressing that dual-parent
relationship for I2C?  The phandle schemes for cross-tree gpio, clk, and
interrupt relationships obviously bear some resemblance to the problem,
but I haven't seen anything for I2C.

(We actually have two devices with the same problem - the other is an
LCD panel controller than wants to be a child of the display device, but
also has some I2C registers accessed by an IC2 controller that's not
part of the display controller.)

Re: Associating devices with multiple parents

[Grant Likely]

[-- Attachment #1.1: Type: text/plain, Size: 1254 bytes --]

On Aug 16, 2012 3:46 PM, "Mitch Bradley" <wmb-D5eQfiDGL7eakBO8gow8eQ@public.gmane.org> wrote:
>
> Here is the situation:  We (OLPC) have an audio codec that is strongly
> associated with an audio controller, but it also has some registers that
> you get at with I2C.
>
> In some sense, the codec has two parents, the audio controller
> (connected via I2S) and the I2C controller.
>
> Is there an established Linux convention for expressing that dual-parent
> relationship for I2C?  The phandle schemes for cross-tree gpio, clk, and
> interrupt relationships obviously bear some resemblance to the problem,
> but I haven't seen anything for I2C.

Yes. Place the codec under the i2c controller and use a tope level audio
complex node with phandles to both the codec and i2s nodes.

Generally we've been choosing patent hood based on the path used to control
the device, as opposed to the data path. Another example is ETH phy devices
on an MDIO bus and the ETH MAC has a phandle to the phy(s).

g.

>
> (We actually have two devices with the same problem - the other is an
> LCD panel controller than wants to be a child of the display device, but
> also has some I2C registers accessed by an IC2 controller that's not
> part of the display controller.)
>

[-- Attachment #1.2: Type: text/html, Size: 1560 bytes --]

[-- Attachment #2: Type: text/plain, Size: 192 bytes --]

_______________________________________________
devicetree-discuss mailing list
devicetree-discuss-uLR06cmDAlY/bJ5BZ2RsiQ@public.gmane.org
https://lists.ozlabs.org/listinfo/devicetree-discuss

Re: Associating devices with multiple parents

[Mark Brown]

On Thu, Aug 16, 2012 at 04:20:47PM -0600, Grant Likely wrote:
> On Aug 16, 2012 3:46 PM, "Mitch Bradley" <wmb-D5eQfiDGL7eakBO8gow8eQ@public.gmane.org> wrote:

> > Is there an established Linux convention for expressing that dual-parent
> > relationship for I2C?  The phandle schemes for cross-tree gpio, clk, and
> > interrupt relationships obviously bear some resemblance to the problem,
> > but I haven't seen anything for I2C.

> Yes. Place the codec under the i2c controller and use a tope level audio
> complex node with phandles to both the codec and i2s nodes.

The nVidia bindings are probably the best ones to look at as an example
here.

Re: Device tree node names

[Mark Brown]

On Thu, Aug 16, 2012 at 11:36:31AM -1000, Mitch Bradley wrote:

> The main "rule" for node names is that a user browsing the device tree
> can easily determine what something is.  Thus "ethernet" instead of
> "DEC,21140".

Does this actually buy us much?  It seems like it's something that's
much better addressed through comments in the device tree than with
syntax.

Re: Device tree node names

[Mitch Bradley]

On 8/17/2012 1:36 AM, Mark Brown wrote:
> On Thu, Aug 16, 2012 at 11:36:31AM -1000, Mitch Bradley wrote:
> 
>> The main "rule" for node names is that a user browsing the device tree
>> can easily determine what something is.  Thus "ethernet" instead of
>> "DEC,21140".
> 
> Does this actually buy us much?  It seems like it's something that's
> much better addressed through comments in the device tree than with
> syntax.
> 

By "comments in the device tree", I assume that you mean "comments in
the DTS source file".  In real Open Firmware, there is no DTS source
file - device nodes are created dynamically by the boot firmware.
Pathnames are visible to, and typed by, users of that firmware.

Re: Device tree node names

[Stephen Warren]

Grant, Rob, Segher, Arnd, Olof,

Can you please state if you agree with Mitch's opinion below? Thanks.

On 08/16/2012 03:36 PM, Mitch Bradley wrote:
> On 8/16/2012 9:34 AM, Stephen Warren wrote:
>> As I understand it, there is a rule when writing device tree files (and
>> bindings) that nodes should be named after the type of object they
>> represent, and not the particular instance of the object. Related, node
>> names should not be interpreted as data.
>>
>> This rules makes perfect sense when talking about nodes on a bus that
>> represent devices; something like:
>>
>>     i2c@7000c000 {
>>         compatible = "nvidia,tegra20-i2c";
>>         reg = <0x7000c000 0x100>;
>>         ...
>>     };
>>
>>     i2c@7000c400 {
>>         compatible = "nvidia,tegra20-i2c";
>>         reg = <0x7000c400 0x100>;
>>         ...
>>     };
>>
>> However, when nodes are being used to represent configuration
>> information inside a device node, or even when representing
>> pseudo-devices that don't directly exist on a specific bus, this rules
>> becomes quite annoying.
>>
>> As an example, consider a device that contains 10 voltage regulators
>> (named "ldon" in the chip documentation), and each needs some
>> configuration provided through DT. A simple binding might result in:
>>
>>     i2c@7000c000 {
>>         ldo0 {
>>             ... (configuration data here)
>>         };
>>         ldo1 {
>>             ...
>>         };
>>         ...
>>     };
>>
>> Where regulator "name"'s configuration is encoded into node "name".
>>
>> Instead, if we follow this rule precisely, we end up with something more
>> like:
>>
>>     i2c@7000c000 {
>>         #address-cells = <1>;
>>         #size-cells = <0>;
>>
>>         ldo@0 {
>>             reg = <0>;
>>             regulator-id = "ldo0";
>>             ...
>>         };
>>         ldo@1 {
>>             reg = <1>;
>>             regulator-id = "ldo1";
>>             ...
>>         };
>>         ...
>>     };
>>
>> This is a fair bit more wordy, and the only advantage appears to be that
>> it correctly conforms to some apparently arbitrary rule for node naming.
>>
>> Similar situations exist when describing the set of power sequences
>> needed to enable/disable a device [1] or pinctrl configurations (see
>> Linux kernel file arch/arm/boot/dts/tegra20-harmony.dts, node
>> /pinmux/pinmux where I haven't actually followed this rule correctly) etc.
>>
>> So, my question is: Can/should we relax this rule? Can we allow drivers
>> (bindings) to require specific node names for things, lookup up specific
>> configuration data by node name and/or enumerate all nodes, and parse
>> data out of the node names (e.g. the value n for nodes named LDOn in the
>> above example)?
> 
> As far as I'm concerned, within the privacy of your own node, you can do
> whatever you want.  Perhaps others will disagree...

If everyone agrees with this, it'll certainly give a lot more
flexibility for individual bindings to come up with simple
representations for configuration data within their own node.

Nodes that represent addressable buses would of course continue to use
standardized conventions in my opinion.

> The main "rule" for node names is that a user browsing the device tree
> can easily determine what something is.  Thus "ethernet" instead of
> "DEC,21140".
> 
> As an historical note, in early Open Boot, it was just the other way
> around.  I originally thought that node names should be precise - and
> the ill-considered "device_type" property gave the "generic"
> identification.   But it soon became clear that "precise" names were
> neither human-understandable nor actually precise. Pathnames looked like
> gobbledygook with strings of part numbers that only an expert could
> remember, and the evolution of part numbers, coupled with companies
> going out of business and other companies making compatible parts, made
> "precise" names change semi-randomly.  Thus was born the "generic names"
> rethink, in which the name became human-meaningful (but generally
> meaningless to software in any precise sense), device_type was
> deprecated, and compatible appeared, as a list.
> 
>>
>> [1]
>> https://lists.ozlabs.org/pipermail/devicetree-discuss/2012-August/018433.html

Re: Device tree node names

[Rob Herring]

On 08/22/2012 10:19 AM, Stephen Warren wrote:
> Grant, Rob, Segher, Arnd, Olof,
> 
> Can you please state if you agree with Mitch's opinion below? Thanks.
> 
> On 08/16/2012 03:36 PM, Mitch Bradley wrote:
>> On 8/16/2012 9:34 AM, Stephen Warren wrote:
>>> As I understand it, there is a rule when writing device tree files (and
>>> bindings) that nodes should be named after the type of object they
>>> represent, and not the particular instance of the object. Related, node
>>> names should not be interpreted as data.
>>>
>>> This rules makes perfect sense when talking about nodes on a bus that
>>> represent devices; something like:
>>>
>>>     i2c@7000c000 {
>>>         compatible = "nvidia,tegra20-i2c";
>>>         reg = <0x7000c000 0x100>;
>>>         ...
>>>     };
>>>
>>>     i2c@7000c400 {
>>>         compatible = "nvidia,tegra20-i2c";
>>>         reg = <0x7000c400 0x100>;
>>>         ...
>>>     };
>>>
>>> However, when nodes are being used to represent configuration
>>> information inside a device node, or even when representing
>>> pseudo-devices that don't directly exist on a specific bus, this rules
>>> becomes quite annoying.
>>>
>>> As an example, consider a device that contains 10 voltage regulators
>>> (named "ldon" in the chip documentation), and each needs some
>>> configuration provided through DT. A simple binding might result in:
>>>
>>>     i2c@7000c000 {
>>>         ldo0 {
>>>             ... (configuration data here)
>>>         };
>>>         ldo1 {
>>>             ...
>>>         };
>>>         ...
>>>     };
>>>
>>> Where regulator "name"'s configuration is encoded into node "name".
>>>
>>> Instead, if we follow this rule precisely, we end up with something more
>>> like:
>>>
>>>     i2c@7000c000 {
>>>         #address-cells = <1>;
>>>         #size-cells = <0>;
>>>
>>>         ldo@0 {
>>>             reg = <0>;
>>>             regulator-id = "ldo0";
>>>             ...
>>>         };
>>>         ldo@1 {
>>>             reg = <1>;
>>>             regulator-id = "ldo1";
>>>             ...
>>>         };
>>>         ...
>>>     };
>>>
>>> This is a fair bit more wordy, and the only advantage appears to be that
>>> it correctly conforms to some apparently arbitrary rule for node naming.
>>>
>>> Similar situations exist when describing the set of power sequences
>>> needed to enable/disable a device [1] or pinctrl configurations (see
>>> Linux kernel file arch/arm/boot/dts/tegra20-harmony.dts, node
>>> /pinmux/pinmux where I haven't actually followed this rule correctly) etc.
>>>
>>> So, my question is: Can/should we relax this rule? Can we allow drivers
>>> (bindings) to require specific node names for things, lookup up specific
>>> configuration data by node name and/or enumerate all nodes, and parse
>>> data out of the node names (e.g. the value n for nodes named LDOn in the
>>> above example)?
>>
>> As far as I'm concerned, within the privacy of your own node, you can do
>> whatever you want.  Perhaps others will disagree...
> 
> If everyone agrees with this, it'll certainly give a lot more
> flexibility for individual bindings to come up with simple
> representations for configuration data within their own node.
> 
> Nodes that represent addressable buses would of course continue to use
> standardized conventions in my opinion.

I don't really have a strong opinion on this. So I guess I'm okay with
it, but I still reserve the right to object to how it gets (ab)used. :)

In fact, the nodes for the highbank clocks does exactly this. In this
case it is only used to get the clock names when no clock-output-names
property is present.

Rob

>> The main "rule" for node names is that a user browsing the device tree
>> can easily determine what something is.  Thus "ethernet" instead of
>> "DEC,21140".
>>
>> As an historical note, in early Open Boot, it was just the other way
>> around.  I originally thought that node names should be precise - and
>> the ill-considered "device_type" property gave the "generic"
>> identification.   But it soon became clear that "precise" names were
>> neither human-understandable nor actually precise. Pathnames looked like
>> gobbledygook with strings of part numbers that only an expert could
>> remember, and the evolution of part numbers, coupled with companies
>> going out of business and other companies making compatible parts, made
>> "precise" names change semi-randomly.  Thus was born the "generic names"
>> rethink, in which the name became human-meaningful (but generally
>> meaningless to software in any precise sense), device_type was
>> deprecated, and compatible appeared, as a list.
>>
>>>
>>> [1]
>>> https://lists.ozlabs.org/pipermail/devicetree-discuss/2012-August/018433.html
> 
> _______________________________________________
> devicetree-discuss mailing list
> devicetree-discuss-uLR06cmDAlY/bJ5BZ2RsiQ@public.gmane.org
> https://lists.ozlabs.org/listinfo/devicetree-discuss
>