devicetree: add dependency information to edtlib

[pabigot]

Device tree nodes have a dependency on their parents, as well as other nodes. To ensure driver instances are initialized in the proper we need to identify these dependencies and construct a total order on nodes that ensures no node is initialized before something it depends on.

Add a Graph class that calculates a partial order on nodes, taking into account the potential for cycles in the dependency graph.

When generating devicetree value headers calculate the dependency graph and document the order and dependencies in the derived files. In the future these dependencies may be expressed in binding data.

Example of content added by this:

# Devicetree node: /soc/gpio@50000000
# Binding (compatible = nordic,nrf-gpio): /mnt/devel/external/zp/zephyr/dts/bindings/gpio/nordic,nrf-gpio.yaml
# Binding description: This is a representation of the NRF GPIO nodes
# Ordinal: 4
# Requires: 3 /soc
# Supports: 5 /buttons/button_0
# Supports: 27 /soc/i2c@40003000/hts221@5f
...
# Devicetree node: /soc/i2c@40003000/hts221@5f
# Binding (compatible = st,hts221): /mnt/devel/external/zp/zephyr/dts/bindings/sensor/st,hts221.yaml
# Binding description: This binding gives a base representation of HTS221 humidity and temperature sensor
# Ordinal: 27
# Requires: 4 /soc/gpio@50000000
# Requires: 10 /soc/i2c@40003000

[zephyrbot]

All checks are passing now.

Tip: The bot edits this comment instead of posting a new one, so you can check the comment's history to see earlier messages.

[pizi-nordic]

I fully support all work towards proper handling of dependencies in Zephyr :)

[pizi-nordic]

FYI: @barsok

[ulfalizer]

Some nits and a defaultdict tip.

Feels like a simpler algo might be possible if all that's needed is ordering + dependency loop detection, but shouldn't hurt at least.

[ulfalizer]

Accidental blank line.

[ulfalizer]

Could call it init_order maybe, to give a better hint about what it's about. I like it better than init_ordinal, even if the node would never get initialized.

[ulfalizer]

Could have add_edge(self, source, target), etc., to be consistent with the rest of the code.

[ulfalizer]

Could use a set literal:

self.__roots = {root}

[ulfalizer]

Could rephrase to be less academicy maybe.

[ulfalizer]

Instead of reset, maybe there could be an internal _dirty flag or the like that gets set whenever the graph is updated.

Wonder if the caching here might be a bit overkill though.

[ulfalizer]

Rest of the code uses format(), which is a bit less quirky. Makes it easier to switch to f-strings later too.

[ulfalizer]

If the raise Exception within tarjan() is kept, then it should be transformed into an EDTError exception here, so that the library consistently raises that.

[ulfalizer]

Missing space before not.

[pabigot]

@ulfalizer OK, done with updates, please re-check.

Many of your comments (style, features) are due to "grutil" being derived from a more general dependency module I wrote in Python 2 over ten years ago. I've done what I can to convert the code to your preferred style.

One thing I have not done is changed the term ordinal. At the moment, this PR introduces the only order on EDT Nodes present in the system: a stable total order that satisfies the relations in the dependency graph.

I don't want to call this "init(ialization) order" because that's not what it is. Zephyr partitions initialization into four phases: PRE_KERNEL_1, PRE_KERNEL_2, POST_KERNEL, and APPLICATION. Initialization order is currently defined by Kconfig priorities within each group.

There is a relation between initialization order and the partial order defined by dependencies, and that order should ultimately be provided by the devicetree scripting, but it won't be the same as this order.

I also don't want to call the Node attribute "order" because that's not what it is either. It's the position of a node within a sequence, i.e. its ordinal.

[ulfalizer]

One thing I have not done is changed the term ordinal. At the moment, this PR introduces the only order on EDT Nodes present in the system: a stable total order that satisfies the relations in the dependency graph.

What about something like dep_ordinal, to give some hint at least? Even if you know what "ordinal" means (I was shaky on it), it's not obvious what the sequence is.

Personally, I try hard to avoid using a word/term when I suspect most people might not know what it means. It's a bit more effort and less auto-pilot, but can make stuff more efficient for people reading the code.

[pabigot]

@ulfalizer ok exception handling and attribute rename done.

[ulfalizer]

Markup in docstrings and __ variables aren't used elsewhere, so that's a bit inconsistent, but not super important.

[ulfalizer]

Remembered another thing.

Might be good to generate edges for Node.interrupts as well. That one's still hardcoded, because it doesn't work like any other property (and deals with both interrupts and interrupts-extended).

[pabigot]

Rebased and updated generated text to be consistent with new documentation format:

/*
 * Devicetree node:
 *   /soc/gpio@50000000
 *
 * Binding (compatible = nordic,nrf-gpio):
 *   $ZEPHYR_BASE/dts/bindings/gpio/nordic,nrf-gpio.yaml
 *
 * Dependency Ordinal: 4
 *
 * Requires:
 *   3 /soc
 *
 * Supports:
 *   5 /buttons/button_0
 *   28 /soc/i2c@40003000/hts221@5f
 *   31 /soc/i2c@40004000/lis2dh12@19
 *
 * Description:
 *   This is a representation of the NRF GPIO nodes
 */