Support circular DTS node references

[danieldegrasse]

Is your enhancement proposal related to a problem? Please describe.
Zephyr's current devicetree infrastructure does not support devicetree nodes having circular references. A few examples of this:

"Classic" circular reference

nodea: nodea {
	status = "okay";
	compatible = "vnd,deva";
	dev-ref = <&nodeb>;
};

nodeb: nodeb {
	status = "okay";
	compatible = "vnd,devb";
	dev-ref = <&nodea>;
};

Parent referencing child- this is also a circular reference

parent_node: parent {
	status = "okay";
	compatible = "vnd,dev-parent";
	child-ref = <&child_node>;
	child_node: child {
		compatible = "vnd,dev-child";
		status = "okay";
	};
};

Any of these devicetrees will fail to compile, as the current devicetree scripting cannot create dependency ordinal numbers for all devicetree nodes when a circular reference exists. The key issue here is that we need to determine which of these nodes has a higher initialization priority, which is not clear from the circular reference.

Describe the solution you'd like
A method to support circular references in devicetree- One method that has been proposed by @mbolivar to handle this is treating circular references as a block of strongly connected components: https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm.

Additional context
While this issue will affect any devicetree, the core driver behind the request is a way to support the sometimes complicate devicetree infrastructure needed to accurately describe display pipelines. One such example:

&mipi_dsi {
    status = "okay";

    ports {
        #address-cells = <1>;
        #size-cells = <0>;
        port@0 {
            reg = <0>;
            dsi_in: endpoint {
                remote-endpoint = <&dcnano_out>;
            };
        };

        port@1 {
            reg = <1>;
            dsi_out: endpoint {
                remote-endpoint = <&dsi_panel_in>;
            };
        };
    };

    rm68200@0 {
        status = "okay";
        compatible = "raydium,rm68200";
        reg = <0x0>;
        reset-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>;
        data-lanes = <2>;
        width = <720>;
        height = <1280>;
                pixel-clock = <6200000>;
        pixel-format = <MIPI_DSI_PIXFMT_RGB565>;
        width = <720>;
        height = <1280>;
        hsync = <8>;
        hfp = <32>;
        hbp = <32>;
        vsync = <2>;
        vfp = <16>;
        vbp = <14>;
        port {
            dsi_panel_in: endpoint {
                remote-endpoint = <&dsi_out>;
            };
        };
    };
};

cc @gmarull

[mbolivar-nordic]

I want to make clear that especially with my upcoming departure from Nordic, I have no plans to work on this any time soon. I also want to point out that @gmarull 's close collaboration will be needed, since any solution needs to be compatible with what we want for #22545, and that's really in the device model

[josuah]

needed to accurately describe display pipelines

It turns out that remote-endpoint is not used at all in the current drivers.

I would be glad to know more about the model you had in mind, as I wish to do the same for implementing UVC.

[josuah]

It looks like fetching the remote-endpoint works... I could get it going from end to end.
I had to add the remote-endpoint property on a .yaml file, maybe that helped?

compatible: blah,blah

child-binding:
  child-binding:
    properties:
      remote-endpoint:
        type: phandle
        required: true

Then the devicetre actually started to validate the remote-endpoint like it is on Linux: requiring a parent that is called endpoint, whose parent is called port. So the validation logic seems hardcoded somehow, but this works as Video4Zephyr seems to preserve Video4Linux devicetree syntax.

[josuah]

Further insights by tinkering with yaml devicetree bindings:

Given zephyr/dts/bindings/video/video-device.yaml as:

# Copyright (c) 2024 tinyVision.ai Inc.
# SPDX-License-Identifier: Apache-2.0

description: |
  Video device common definitions
  This follows some of V4L2 conventions:
  https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/media/video-interfaces.yaml

child-binding:
  description: |
    A port entity of a device
    Allowing devices with multiple input and output connection, such as an
    HDMI stream selector with many input ports and one output.

  child-binding:
    description: |
      An endpoint entity of a port
      Allowing devices with multiple channels per port, such as MIPI virtual
      channels.

    properties:
      remote-endpoint:
        type: phandle
        required: true
        description: |
          Reference to a Video endpoint
          This Video endpoint should implement the "video" driver API, and will
          provide data either directly, or through an associated video device.
          For instance, an image sensor providing data over a MIPI peripheral.

And the given app.overlay:

&zephyr_udc0 {
        /* IN and OUT counting together as one endpoint */
        num-bidir-endpoints = <2>;

        /* Number of transfer requests for each endpoint */
        num-endpoint-trb = </* EP0 */ 2 2 /* EP1 */ 0 32>;

        /* full-speed: 12 Mhz, high-speed: 480 Mhz, super-speed: 5000 Mhz */
        maximum-speed = "high-speed";

        uvc0: zephyr_uvc0 {
                compatible = "zephyr,uvc";
                status = "okay";

                uvc0in: input-terminal {
                        compatible = "zephyr,uvc-input-terminal";

                        port {
                                uvc0ep: endpoint {
                                        remote-endpoint = <&gen0out>;
                                };
                        };
                };

                uvc0out: output-terminal {
                        compatible = "zephyr,uvc-output-terminal";
                        source = <&uvc0in>;
                };
        };
};

/ {
        soc {
                tinygen@b1100000 {
                        compatible = "tinyvision,tinygen";
                        reg = <0xb1100000 0x0010000>;

                        port {
                                gen0out: endpoint {
                                        remote-endpoint = <&uvc0ep>;
                                };
                        };
                };
        };
};

This works

zephyr/dts/bindings/video/tinyvision,tinygen.yaml:

description: small pattern generator
compatible: "tinyvision,tinygen"
include: video-device.yaml

zephyr/dts/bindings/usb/uvc/zephyr,uvc-input-terminal.yaml:

description: USB Video Class Input Terminal entity
compatible: "zephyr,uvc-input-terminal"
#include: video-device.yaml

This works

zephyr/dts/bindings/video/tinyvision,tinygen.yaml:

description: small pattern generator
compatible: "tinyvision,tinygen"
#include: video-device.yaml

zephyr/dts/bindings/usb/uvc/zephyr,uvc-input-terminal.yaml:

description: USB Video Class Input Terminal entity
compatible: "zephyr,uvc-input-terminal"
include: video-device.yaml

This fails

zephyr/dts/bindings/video/tinyvision,tinygen.yaml:

description: small pattern generator
compatible: "tinyvision,tinygen"
include: video-device.yaml

zephyr/dts/bindings/usb/uvc/zephyr,uvc-input-terminal.yaml:

description: USB Video Class Input Terminal entity
compatible: "zephyr,uvc-input-terminal"
include: video-device.yaml

With the error that the tinyvision,tinygen node and zephyr,uvc-input-terminal both have the _ORD number set to -1:

devicetree_generated.h.txt

Maybe this is the same bug.

At least, in my case, the temporary workaround is to set a YAML binding rule like child-node: child-node: property: remote-endpoint: type: phandle on exactly one of the two link endpoints. This is terribly ad-hoc, but allows to keep experimenting, to hopefully discover more about this bug.

[danieldegrasse]

At least, in my case, the temporary workaround is to set a YAML binding rule like child-node: child-node: property: remote-endpoint: type: phandle on exactly one of the two link endpoints. This is terribly ad-hoc, but allows to keep experimenting, to hopefully discover more about this bug.

I am not a devicetree expert- but my understanding is that by only adding the child-node properties pulled in by including video-device.yaml, the devicetree python scripting would only parse the remote-endpoint for one of the endpoints, not both. If the python scripting skips a node in devicetree (IE does not validate it), it will not be included in the output generated devicetree header file- so it wouldn't be usable from a Zephyr driver. Were you able to find a way around this issue, or does it not occur for you?