Skip to contentSkip to conversation

Device tree node names

DISCUSSION Stephen Warren 5 participants 9 messages Aug 16, 2012 – Aug 22, 2012 6 messages not in the archive

lore
Share & tools
lore
#0 lore raw

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

A message that is not in the archive (sent off-list or not yet received): [email protected]

#2 lore raw
Quoted 69 lines · 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.

Quoted 5 lines

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.

Quoted 4 lines

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

A message that is not in the archive (sent off-list or not yet received): [email protected]

#4 lore raw
Quoted 3 lines · Mitch Bradley

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.

A message that is not in the archive (sent off-list or not yet received): 20120817113610.GB32216-yzvPICuk2AATkU/[email protected]

#6 lore raw
Quoted 10 lines · Mark Brown
Quoted 3 lines · Mitch Bradley

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.

#7 lore raw
In reply to a message not in the archive

Grant, Rob, Segher, Arnd, Olof,

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

Quoted 70 lines · Mitch Bradley
Quoted 69 lines · 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.

Quoted 8 lines
Quoted 5 lines

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.

Quoted 20 lines

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.

Quoted 3 lines

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

A message that is not in the archive (sent off-list or not yet received): [email protected]

#9 lore raw
Quoted 84 lines · Stephen Warren

Grant, Rob, Segher, Arnd, Olof,

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

Quoted 70 lines · Mitch Bradley
Quoted 69 lines · 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.

Quoted 8 lines
Quoted 5 lines

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

Quoted 6 lines

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

Quoted 26 lines
Quoted 4 lines

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

Quoted 16 lines

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.

Quoted 3 lines

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

_______________________________________________
devicetree-discuss mailing list devicetree-discuss-uLR06cmDAlY/[email protected]
https://lists.ozlabs.org/listinfo/devicetree-discuss

#10 lore raw

Associating devices with multiple parents

In reply to a message not in the archive

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

A message that is not in the archive (sent off-list or not yet received): [email protected]

#12 lore raw

Re: Associating devices with multiple parents

Quoted 5 lines · 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.

Quoted 7 lines

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.

Quoted 6 lines

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

_______________________________________________
devicetree-discuss mailing list devicetree-discuss-uLR06cmDAlY/[email protected]
https://lists.ozlabs.org/listinfo/devicetree-discuss

A message that is not in the archive (sent off-list or not yet received): CACxGe6uqWG7kRUL0o3qPCMDvG52UyqTMez+AT1yK55X-xgaRuQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

#14 lore raw

Re: Associating devices with multiple parents

Quoted 9 lines · Grant Likely
Quoted 4 lines · Mitch Bradley

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.