dt-bindings: Convert graph bindings to json-schema

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:
ports:
type: object
$ref: graph.yaml#/properties/ports

    properties:
      port@0:
        description: What data this port has

      ...

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:

   ports:
     type: object
     $ref: graph.yaml#/properties/ports

     properties:
       port@0:
         description: What data this port has

       ...

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3:
- Move port 'reg' to port@* and make required
- Make remote-endpoint required
- Add 'additionalProperties: true' now required
- Fix yamllint warnings

  Documentation/devicetree/bindings/graph.txt  | 129 +-----------
  Documentation/devicetree/bindings/graph.yaml | 199 +++++++++++++++++++
  2 files changed, 200 insertions(+), 128 deletions(-)

create mode 100644 Documentation/devicetree/bindings/graph.yaml

Documentation/devicetree/bindings/graph.yaml new file +54 -0

new file mode 100644
index 000000000000..b56720c5a13e
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/graph.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for device graphs
+
+description: |
+  The hierarchical organisation of the device tree is well suited to describe
+  control flow to devices, but there can be more complex connections between
+  devices that work together to form a logical compound device, following an
+  arbitrarily complex graph.
+  There already is a simple directed graph between devices tree nodes using
+  phandle properties pointing to other nodes to describe connections that
+  can not be inferred from device tree parent-child relationships. The device
+  tree graph bindings described herein abstract more complex devices that can
+  have multiple specifiable ports, each of which can be linked to one or more
+  ports of other devices.
+
+  These common bindings do not contain any information about the direction or
+  type of the connections, they just map their existence. Specific properties
+  may be described by specialized bindings depending on the type of connection.
+
+  To see how this binding applies to video pipelines, for example, see
+  Documentation/devicetree/bindings/media/video-interfaces.txt.
+  Here the ports describe data interfaces, and the links between them are
+  the connecting data buses. A single port with multiple connections can
+  correspond to multiple devices being connected to the same physical bus.
+
+maintainers:
+  - Philipp Zabel <[email protected]>
+
+select: false
+
+properties:
+  port:
+    type: object
+    description:
+      If there is more than one endpoint node or 'reg' property present in
+      endpoint nodes then '#address-cells' and '#size-cells' properties are
+      required.
+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^endpoint(@[0-9a-f]+)?$":
+        type: object
+        properties:

Documentation/devicetree/bindings/graph.yaml new file +26 -1

+  # Links between endpoints:
+  #
+  # Each endpoint should contain a 'remote-endpoint' phandle property that
+  # points to the corresponding endpoint in the port of the remote device.
+  # In turn, the remote endpoint should contain a 'remote-endpoint' property.
+  # If it has one, it must not point to anything other than the local endpoint.
+  # Two endpoints with their 'remote-endpoint' phandles pointing at each other
+  # form a link between the containing ports.
+  - |
+    device-1 {
+        port {
+            device_1_output: endpoint {
+                remote-endpoint = <&device_2_input>;
+            };
+        };
+    };
+
+    device-2 {
+        port {
+            device_2_input: endpoint {
+                remote-endpoint = <&device_1_output>;
+            };
+        };
+    };
+
+...
--

2.25.1

Hi Rob,

Quoted 43 lines

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:

   ports:
     type: object
     $ref: graph.yaml#/properties/ports

     properties:
       port@0:
         description: What data this port has

       ...

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3:
- Move port 'reg' to port@* and make required
- Make remote-endpoint required
- Add 'additionalProperties: true' now required
- Fix yamllint warnings

  Documentation/devicetree/bindings/graph.txt  | 129 +-----------
  Documentation/devicetree/bindings/graph.yaml | 199 +++++++++++++++++++
  2 files changed, 200 insertions(+), 128 deletions(-)

create mode 100644 Documentation/devicetree/bindings/graph.yaml

...

Quoted 68 lines

Documentation/devicetree/bindings/graph.yaml new file +62 -0

new file mode 100644
index 000000000000..b56720c5a13e
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/graph.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for device graphs
+
+description: |
+  The hierarchical organisation of the device tree is well suited to describe
+  control flow to devices, but there can be more complex connections between
+  devices that work together to form a logical compound device, following an
+  arbitrarily complex graph.
+  There already is a simple directed graph between devices tree nodes using
+  phandle properties pointing to other nodes to describe connections that
+  can not be inferred from device tree parent-child relationships. The device
+  tree graph bindings described herein abstract more complex devices that can
+  have multiple specifiable ports, each of which can be linked to one or more
+  ports of other devices.
+
+  These common bindings do not contain any information about the direction or
+  type of the connections, they just map their existence. Specific properties
+  may be described by specialized bindings depending on the type of connection.
+
+  To see how this binding applies to video pipelines, for example, see
+  Documentation/devicetree/bindings/media/video-interfaces.txt.
+  Here the ports describe data interfaces, and the links between them are
+  the connecting data buses. A single port with multiple connections can
+  correspond to multiple devices being connected to the same physical bus.
+
+maintainers:
+  - Philipp Zabel <[email protected]>
+
+select: false
+
+properties:
+  port:
+    type: object
+    description:
+      If there is more than one endpoint node or 'reg' property present in
+      endpoint nodes then '#address-cells' and '#size-cells' properties are
+      required.
+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^endpoint(@[0-9a-f]+)?$":
+        type: object
+        properties:
+          reg:
+            maxItems: 1
+
+          remote-endpoint:
+            description: |
+              phandle to an 'endpoint' subnode of a remote device node.
+            $ref: /schemas/types.yaml#/definitions/phandle
+

Documentation/devicetree/bindings/graph.yaml line 64

Quoted 2 lines

Documentation/devicetree/bindings/graph.yaml new file +2 -0

+        required:
+          - remote-endpoint

Does 'remote-endpoint' have to be a required property?
In case of pluggable modules, the remote-endpoint may not be available unless the module is plugged in. In other words, device-2 in below example may not always be available, but still device-1 endpoint configuration and usage may be required?

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:
ports:

    type: object
    $ref: graph.yaml#/properties/ports

    properties:
      port@0:
        description: What data this port has

      ...

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3:
- Move port 'reg' to port@* and make required
- Make remote-endpoint required
- Add 'additionalProperties: true' now required
- Fix yamllint warnings

 Documentation/devicetree/bindings/graph.txt  | 129 +-----------
 Documentation/devicetree/bindings/graph.yaml | 199 +++++++++++++++++++
 2 files changed, 200 insertions(+), 128 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/graph.yaml

Documentation/devicetree/bindings/graph.txt +1 -128

index 0415e2c53ba0..b7818d61cef7 100644
@@ -1,128 +1 @@
-Common bindings for device graphs
-
-General concept
----------------
-
-The hierarchical organisation of the device tree is well suited to describe
-control flow to devices, but there can be more complex connections between
-devices that work together to form a logical compound device, following an
-arbitrarily complex graph.
-There already is a simple directed graph between devices tree nodes using
-phandle properties pointing to other nodes to describe connections that
-can not be inferred from device tree parent-child relationships. The device
-tree graph bindings described herein abstract more complex devices that can
-have multiple specifiable ports, each of which can be linked to one or more
-ports of other devices.
-
-These common bindings do not contain any information about the direction or
-type of the connections, they just map their existence. Specific properties
-may be described by specialized bindings depending on the type of connection.
-
-To see how this binding applies to video pipelines, for example, see
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-Here the ports describe data interfaces, and the links between them are
-the connecting data buses. A single port with multiple connections can
-correspond to multiple devices being connected to the same physical bus.
-
-Organisation of ports and endpoints
------------------------------------
-
-Ports are described by child 'port' nodes contained in the device node.
-Each port node contains an 'endpoint' subnode for each remote device port
-connected to this port. If a single port is connected to more than one
-remote device, an 'endpoint' child node must be provided for each link.
-If more than one port is present in a device node or there is more than one
-endpoint at a port, or a port node needs to be associated with a selected
-hardware interface, a common scheme using '#address-cells', '#size-cells'
-and 'reg' properties is used to number the nodes.
-
-device {
-        ...
-        #address-cells = <1>;
-        #size-cells = <0>;
-
-        port@0 {
-	        #address-cells = <1>;
-	        #size-cells = <0>;
-		reg = <0>;
-
-                endpoint@0 {
-			reg = <0>;
-			...
-		};
-                endpoint@1 {
-			reg = <1>;
-			...
-		};
-        };
-
-        port@1 {
-		reg = <1>;
-
-		endpoint { ... };
-	};
-};
-
-All 'port' nodes can be grouped under an optional 'ports' node, which
-allows to specify #address-cells, #size-cells properties for the 'port'
-nodes independently from any other child device nodes a device might
-have.
-
-device {
-        ...
-        ports {
-                #address-cells = <1>;
-                #size-cells = <0>;
-
-                port@0 {
-                        ...
-                        endpoint@0 { ... };
-                        endpoint@1 { ... };
-                };
-
-                port@1 { ... };
-        };
-};
-
-Links between endpoints
------------------------
-
-Each endpoint should contain a 'remote-endpoint' phandle property that points
-to the corresponding endpoint in the port of the remote device. In turn, the
-remote endpoint should contain a 'remote-endpoint' property. If it has one, it
-must not point to anything other than the local endpoint. Two endpoints with
-their 'remote-endpoint' phandles pointing at each other form a link between the
-containing ports.
-
-device-1 {
-        port {
-                device_1_output: endpoint {
-                        remote-endpoint = <&device_2_input>;
-                };
-        };
-};
-
-device-2 {
-        port {
-                device_2_input: endpoint {
-                        remote-endpoint = <&device_1_output>;
-                };
-        };
-};
-
-Required properties
--------------------
-
-If there is more than one 'port' or more than one 'endpoint' node or 'reg'
-property present in the port and/or endpoint nodes then the following
-properties are required in a relevant parent node:
-
- - #address-cells : number of cells required to define port/endpoint
-                    identifier, should be 1.
- - #size-cells    : should be zero.
-
-Optional endpoint properties
-----------------------------
-
-- remote-endpoint: phandle to an 'endpoint' subnode of a remote device node.
-
+This file has moved to graph.yaml

Documentation/devicetree/bindings/graph.yaml new file +54 -0

new file mode 100644
index 000000000000..b56720c5a13e
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/graph.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for device graphs
+
+description: |
+  The hierarchical organisation of the device tree is well suited to describe
+  control flow to devices, but there can be more complex connections between
+  devices that work together to form a logical compound device, following an
+  arbitrarily complex graph.
+  There already is a simple directed graph between devices tree nodes using
+  phandle properties pointing to other nodes to describe connections that
+  can not be inferred from device tree parent-child relationships. The device
+  tree graph bindings described herein abstract more complex devices that can
+  have multiple specifiable ports, each of which can be linked to one or more
+  ports of other devices.
+
+  These common bindings do not contain any information about the direction or
+  type of the connections, they just map their existence. Specific properties
+  may be described by specialized bindings depending on the type of connection.
+
+  To see how this binding applies to video pipelines, for example, see
+  Documentation/devicetree/bindings/media/video-interfaces.txt.
+  Here the ports describe data interfaces, and the links between them are
+  the connecting data buses. A single port with multiple connections can
+  correspond to multiple devices being connected to the same physical bus.
+
+maintainers:
+  - Philipp Zabel <[email protected]>
+
+select: false
+
+properties:
+  port:
+    type: object
+    description:
+      If there is more than one endpoint node or 'reg' property present in
+      endpoint nodes then '#address-cells' and '#size-cells' properties are
+      required.
+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^endpoint(@[0-9a-f]+)?$":
+        type: object
+        properties:

Documentation/devicetree/bindings/graph.yaml new file +11 -0

+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^port(@[0-9a-f]+)?$":
+        $ref: "#/properties/port"

Documentation/devicetree/bindings/graph.yaml new file +106 -0

+    additionalProperties: false
+
+additionalProperties: true
+
+examples:
+  # Organisation of ports and endpoints:
+  #
+  # Ports are described by child 'port' nodes contained in the device node.
+  # Each port node contains an 'endpoint' subnode for each remote device port
+  # connected to this port. If a single port is connected to more than one
+  # remote device, an 'endpoint' child node must be provided for each link.
+  # If more than one port is present in a device node or there is more than
+  # one endpoint at a port, or a port node needs to be associated with a
+  # selected hardware interface, a common scheme using '#address-cells',
+  # '#size-cells' and 'reg' properties is used to number the nodes.
+  - |
+    device {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        port@0 {
+            #address-cells = <1>;
+            #size-cells = <0>;
+            reg = <0>;
+
+            endpoint@0 {
+                reg = <0>;
+                // ...
+            };
+            endpoint@1 {
+                reg = <1>;
+                // ...
+            };
+        };
+
+        port@1 {
+            reg = <1>;
+
+            endpoint {
+                // ...
+            };
+        };
+    };
+
+  # All 'port' nodes can be grouped under an optional 'ports' node, which
+  # allows to specify #address-cells, #size-cells properties for the 'port'
+  # nodes independently from any other child device nodes a device might
+  # have.
+  - |
+    device {
+        // ...
+        ports {
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            port@0 {
+                #address-cells = <1>;
+                #size-cells = <0>;
+                reg = <0>;
+                // ...
+
+                endpoint@0 {
+                    reg = <0>;
+                    // ...
+                };
+                endpoint@1 {
+                    reg = <1>;
+                    // ...
+                };
+            };
+
+            port@1 {
+                #address-cells = <1>;
+                #size-cells = <0>;
+                reg = <1>;
+                // ...
+            };
+        };
+    };
+
+  # Links between endpoints:
+  #
+  # Each endpoint should contain a 'remote-endpoint' phandle property that
+  # points to the corresponding endpoint in the port of the remote device.
+  # In turn, the remote endpoint should contain a 'remote-endpoint' property.
+  # If it has one, it must not point to anything other than the local endpoint.
+  # Two endpoints with their 'remote-endpoint' phandles pointing at each other
+  # form a link between the containing ports.
+  - |
+    device-1 {
+        port {
+            device_1_output: endpoint {
+                remote-endpoint = <&device_2_input>;
+            };
+        };
+    };
+
+    device-2 {
+        port {
+            device_2_input: endpoint {
+                remote-endpoint = <&device_1_output>;
+            };
+        };
+    };
+
+...

Hi Rob and Sameer,

Thank you for the patch.

Quoted 20 lines · Rob Herring

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:
ports:

    type: object
    $ref: graph.yaml#/properties/ports

    properties:
      port@0:
        description: What data this port has

      ...

Quoted 7 lines

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Sounds like a good approach.

Quoted 14 lines

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3:
- Move port 'reg' to port@* and make required
- Make remote-endpoint required
- Add 'additionalProperties: true' now required
- Fix yamllint warnings

 Documentation/devicetree/bindings/graph.txt  | 129 +-----------
 Documentation/devicetree/bindings/graph.yaml | 199 +++++++++++++++++++
 2 files changed, 200 insertions(+), 128 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/graph.yaml

Quoted 60 lines

Documentation/devicetree/bindings/graph.yaml new file +54 -0

new file mode 100644
index 000000000000..b56720c5a13e
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/graph.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for device graphs
+
+description: |
+  The hierarchical organisation of the device tree is well suited to describe
+  control flow to devices, but there can be more complex connections between
+  devices that work together to form a logical compound device, following an
+  arbitrarily complex graph.
+  There already is a simple directed graph between devices tree nodes using
+  phandle properties pointing to other nodes to describe connections that
+  can not be inferred from device tree parent-child relationships. The device
+  tree graph bindings described herein abstract more complex devices that can
+  have multiple specifiable ports, each of which can be linked to one or more
+  ports of other devices.
+
+  These common bindings do not contain any information about the direction or
+  type of the connections, they just map their existence. Specific properties
+  may be described by specialized bindings depending on the type of connection.
+
+  To see how this binding applies to video pipelines, for example, see
+  Documentation/devicetree/bindings/media/video-interfaces.txt.
+  Here the ports describe data interfaces, and the links between them are
+  the connecting data buses. A single port with multiple connections can
+  correspond to multiple devices being connected to the same physical bus.
+
+maintainers:
+  - Philipp Zabel <[email protected]>
+
+select: false
+
+properties:
+  port:
+    type: object
+    description:
+      If there is more than one endpoint node or 'reg' property present in
+      endpoint nodes then '#address-cells' and '#size-cells' properties are
+      required.
+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^endpoint(@[0-9a-f]+)?$":
+        type: object
+        properties:

Documentation/devicetree/bindings/graph.yaml line 64

Quoted 10 lines

Documentation/devicetree/bindings/graph.yaml new file +10 -0

+          reg:
+            maxItems: 1
+
+          remote-endpoint:
+            description: |
+              phandle to an 'endpoint' subnode of a remote device node.
+            $ref: /schemas/types.yaml#/definitions/phandle
+
+        required:
+          - remote-endpoint

As noted elsewhere, this shouldn't be required.

Should we set additionalProperties: false here ?

Documentation/devicetree/bindings/graph.yaml line 72

Quoted 7 lines

Documentation/devicetree/bindings/graph.yaml new file +7 -0

+  ports:
+    type: object
+    description: |
+      If there is more than one port node or 'reg' property present in port
+      nodes then '#address-cells' and '#size-cells' properties are required.
+      In such cases all port nodes can be grouped under 'ports' independently
+      from any other child device nodes a device might have.

Allowing multiple port nodes not grouped in a ports node has created complexity, with very little gain. Should we forbid that going forward ?

Quoted 10 lines

Documentation/devicetree/bindings/graph.yaml new file +10 -0

+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^port(@[0-9a-f]+)?$":
+        $ref: "#/properties/port"

Documentation/devicetree/bindings/graph.yaml line 93

Quoted 10 lines

Documentation/devicetree/bindings/graph.yaml new file +10 -0

+        type: object
+
+        properties:
+          reg:
+            maxItems: 1
+
+        required:
+          - reg
+
+

Maybe a single blank line ?

Reviewed-by Laurent Pinchart <[email protected]>

Quoted 45 lines · Laurent Pinchart

Quoted 20 lines · Rob Herring

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:
ports:

    type: object
    $ref: graph.yaml#/properties/ports

    properties:
      port@0:
        description: What data this port has

      ...

Quoted 7 lines

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Sounds like a good approach.

Quoted 14 lines

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3:
- Move port 'reg' to port@* and make required
- Make remote-endpoint required
- Add 'additionalProperties: true' now required
- Fix yamllint warnings

 Documentation/devicetree/bindings/graph.txt  | 129 +-----------
 Documentation/devicetree/bindings/graph.yaml | 199 +++++++++++++++++++
 2 files changed, 200 insertions(+), 128 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/graph.yaml

[...]

Quoted 73 lines

Quoted 60 lines

Documentation/devicetree/bindings/graph.yaml new file +54 -0

new file mode 100644
index 000000000000..b56720c5a13e
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/graph.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for device graphs
+
+description: |
+  The hierarchical organisation of the device tree is well suited to describe
+  control flow to devices, but there can be more complex connections between
+  devices that work together to form a logical compound device, following an
+  arbitrarily complex graph.
+  There already is a simple directed graph between devices tree nodes using
+  phandle properties pointing to other nodes to describe connections that
+  can not be inferred from device tree parent-child relationships. The device
+  tree graph bindings described herein abstract more complex devices that can
+  have multiple specifiable ports, each of which can be linked to one or more
+  ports of other devices.
+
+  These common bindings do not contain any information about the direction or
+  type of the connections, they just map their existence. Specific properties
+  may be described by specialized bindings depending on the type of connection.
+
+  To see how this binding applies to video pipelines, for example, see
+  Documentation/devicetree/bindings/media/video-interfaces.txt.
+  Here the ports describe data interfaces, and the links between them are
+  the connecting data buses. A single port with multiple connections can
+  correspond to multiple devices being connected to the same physical bus.
+
+maintainers:
+  - Philipp Zabel <[email protected]>
+
+select: false
+
+properties:
+  port:
+    type: object
+    description:
+      If there is more than one endpoint node or 'reg' property present in
+      endpoint nodes then '#address-cells' and '#size-cells' properties are
+      required.
+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^endpoint(@[0-9a-f]+)?$":
+        type: object
+        properties:

Documentation/devicetree/bindings/graph.yaml line 64

Quoted 10 lines

Documentation/devicetree/bindings/graph.yaml new file +10 -0

+          reg:
+            maxItems: 1
+
+          remote-endpoint:
+            description: |
+              phandle to an 'endpoint' subnode of a remote device node.
+            $ref: /schemas/types.yaml#/definitions/phandle
+
+        required:
+          - remote-endpoint

As noted elsewhere, this shouldn't be required.

Quoted 1 line

Should we set additionalProperties: false here ?

No, we've got a bunch of properties that get added to endpoint nodes. There's a few cases where 'port' nodes have properties too.

Quoted 8 lines

Quoted 7 lines

Documentation/devicetree/bindings/graph.yaml new file +7 -0

+  ports:
+    type: object
+    description: |
+      If there is more than one port node or 'reg' property present in port
+      nodes then '#address-cells' and '#size-cells' properties are required.
+      In such cases all port nodes can be grouped under 'ports' independently
+      from any other child device nodes a device might have.

Quoted 2 lines

Allowing multiple port nodes not grouped in a ports node has created complexity, with very little gain. Should we forbid that going forward ?

Yes, that's probably a separate change. The examples need updating too. We do have a few cases we'll have to support though.

Quoted 23 lines

Quoted 10 lines

Documentation/devicetree/bindings/graph.yaml new file +10 -0

+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^port(@[0-9a-f]+)?$":
+        $ref: "#/properties/port"

Documentation/devicetree/bindings/graph.yaml line 93

Quoted 10 lines

Documentation/devicetree/bindings/graph.yaml new file +10 -0

+        type: object
+
+        properties:
+          reg:
+            maxItems: 1
+
+        required:
+          - reg
+
+

Maybe a single blank line ?

Quoted 1 line

Reviewed-by Laurent Pinchart <[email protected]>

I've gone thru and updated schemas to use this. Primarily to prove out a meta-schema for it. So I'll be sending out another version.

Hi Rob,

Quoted 122 lines · Rob Herring

Quoted 45 lines · Laurent Pinchart

Quoted 20 lines · Rob Herring

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:
ports:

    type: object
    $ref: graph.yaml#/properties/ports

    properties:
      port@0:
        description: What data this port has

      ...

Quoted 7 lines

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Sounds like a good approach.

Quoted 14 lines

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3:
- Move port 'reg' to port@* and make required
- Make remote-endpoint required
- Add 'additionalProperties: true' now required
- Fix yamllint warnings

 Documentation/devicetree/bindings/graph.txt  | 129 +-----------
 Documentation/devicetree/bindings/graph.yaml | 199 +++++++++++++++++++
 2 files changed, 200 insertions(+), 128 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/graph.yaml

[...]

Quoted 73 lines

Quoted 60 lines

Documentation/devicetree/bindings/graph.yaml new file +54 -0

new file mode 100644
index 000000000000..b56720c5a13e
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/graph.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for device graphs
+
+description: |
+  The hierarchical organisation of the device tree is well suited to describe
+  control flow to devices, but there can be more complex connections between
+  devices that work together to form a logical compound device, following an
+  arbitrarily complex graph.
+  There already is a simple directed graph between devices tree nodes using
+  phandle properties pointing to other nodes to describe connections that
+  can not be inferred from device tree parent-child relationships. The device
+  tree graph bindings described herein abstract more complex devices that can
+  have multiple specifiable ports, each of which can be linked to one or more
+  ports of other devices.
+
+  These common bindings do not contain any information about the direction or
+  type of the connections, they just map their existence. Specific properties
+  may be described by specialized bindings depending on the type of connection.
+
+  To see how this binding applies to video pipelines, for example, see
+  Documentation/devicetree/bindings/media/video-interfaces.txt.
+  Here the ports describe data interfaces, and the links between them are
+  the connecting data buses. A single port with multiple connections can
+  correspond to multiple devices being connected to the same physical bus.
+
+maintainers:
+  - Philipp Zabel <[email protected]>
+
+select: false
+
+properties:
+  port:
+    type: object
+    description:
+      If there is more than one endpoint node or 'reg' property present in
+      endpoint nodes then '#address-cells' and '#size-cells' properties are
+      required.
+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^endpoint(@[0-9a-f]+)?$":
+        type: object
+        properties:

Documentation/devicetree/bindings/graph.yaml line 64

Quoted 10 lines

Documentation/devicetree/bindings/graph.yaml new file +10 -0

+          reg:
+            maxItems: 1
+
+          remote-endpoint:
+            description: |
+              phandle to an 'endpoint' subnode of a remote device node.
+            $ref: /schemas/types.yaml#/definitions/phandle
+
+        required:
+          - remote-endpoint

As noted elsewhere, this shouldn't be required.

Quoted 4 lines

Quoted 1 line

Should we set additionalProperties: false here ?

No, we've got a bunch of properties that get added to endpoint nodes. There's a few cases where 'port' nodes have properties too.

I meant the port node, which I wasn't aware needed additional properties. Do you have any example ? (I wonder if you will point me to bindings that I have written ;-))

Quoted 123 lines · Laurent Pinchart

Quoted 122 lines · Rob Herring

Quoted 45 lines · Laurent Pinchart

Quoted 20 lines · Rob Herring

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:
ports:

    type: object
    $ref: graph.yaml#/properties/ports

    properties:
      port@0:
        description: What data this port has

      ...

Quoted 7 lines

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Sounds like a good approach.

Quoted 14 lines

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3:
- Move port 'reg' to port@* and make required
- Make remote-endpoint required
- Add 'additionalProperties: true' now required
- Fix yamllint warnings

 Documentation/devicetree/bindings/graph.txt  | 129 +-----------
 Documentation/devicetree/bindings/graph.yaml | 199 +++++++++++++++++++
 2 files changed, 200 insertions(+), 128 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/graph.yaml

[...]

Quoted 73 lines

Quoted 60 lines

Documentation/devicetree/bindings/graph.yaml new file +54 -0

new file mode 100644
index 000000000000..b56720c5a13e
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/graph.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for device graphs
+
+description: |
+  The hierarchical organisation of the device tree is well suited to describe
+  control flow to devices, but there can be more complex connections between
+  devices that work together to form a logical compound device, following an
+  arbitrarily complex graph.
+  There already is a simple directed graph between devices tree nodes using
+  phandle properties pointing to other nodes to describe connections that
+  can not be inferred from device tree parent-child relationships. The device
+  tree graph bindings described herein abstract more complex devices that can
+  have multiple specifiable ports, each of which can be linked to one or more
+  ports of other devices.
+
+  These common bindings do not contain any information about the direction or
+  type of the connections, they just map their existence. Specific properties
+  may be described by specialized bindings depending on the type of connection.
+
+  To see how this binding applies to video pipelines, for example, see
+  Documentation/devicetree/bindings/media/video-interfaces.txt.
+  Here the ports describe data interfaces, and the links between them are
+  the connecting data buses. A single port with multiple connections can
+  correspond to multiple devices being connected to the same physical bus.
+
+maintainers:
+  - Philipp Zabel <[email protected]>
+
+select: false
+
+properties:
+  port:
+    type: object
+    description:
+      If there is more than one endpoint node or 'reg' property present in
+      endpoint nodes then '#address-cells' and '#size-cells' properties are
+      required.
+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      "^endpoint(@[0-9a-f]+)?$":
+        type: object
+        properties:

Documentation/devicetree/bindings/graph.yaml line 64

Quoted 10 lines

Documentation/devicetree/bindings/graph.yaml new file +10 -0

+          reg:
+            maxItems: 1
+
+          remote-endpoint:
+            description: |
+              phandle to an 'endpoint' subnode of a remote device node.
+            $ref: /schemas/types.yaml#/definitions/phandle
+
+        required:
+          - remote-endpoint

As noted elsewhere, this shouldn't be required.

Quoted 8 lines

Quoted 4 lines

Quoted 1 line

Should we set additionalProperties: false here ?

No, we've got a bunch of properties that get added to endpoint nodes. There's a few cases where 'port' nodes have properties too.

I meant the port node, which I wasn't aware needed additional properties. Do you have any example ? (I wonder if you will point me to bindings that I have written ;-))

Not you, but Renesas. dual-lvds-{odd,even}-pixels was the only one I think. But really, I think we could actually drop those if the port numbering defines even/odd instead. There's a patch I just reviewed for common dual lane panels. See [email protected]

From: Sameer Pujar <[email protected]>

Convert device tree bindings of graph to YAML format. Currently graph.txt doc is referenced in multiple files and all of these need to use schema references. For now graph.txt is updated to refer to graph.yaml.

For users of the graph binding, they should reference to the graph schema from either 'ports' or 'port' property:

properties:
ports:

    type: object
    $ref: graph.yaml#/properties/ports

    properties:
      port@0:
        description: What data this port has

      ...

Or:

properties:
port:
description: What data this port has
type: object
$ref: graph.yaml#/properties/port

Signed-off-by Sameer Pujar <[email protected]>

Acked-by Philipp Zabel <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3:
- Move port 'reg' to port@* and make required
- Make remote-endpoint required
- Add 'additionalProperties: true' now required
- Fix yamllint warnings

 Documentation/devicetree/bindings/graph.txt  | 129 +-----------
 Documentation/devicetree/bindings/graph.yaml | 199 +++++++++++++++++++
 2 files changed, 200 insertions(+), 128 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/graph.yaml

Now that we have a graph schema, reference it from the usb-connector schema.

Signed-off-by Rob Herring <[email protected]>

---
v3: new patch

 .../devicetree/bindings/connector/usb-connector.yaml   | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

Documentation/devicetree/bindings/connector/usb-connector.yaml +6 -4

index 728f82db073d..64f2e1246ddb 100644
@@ -125,11 +125,13 @@ properties:
       power dual role.
 
   ports:
-    description: OF graph bindings (specified in bindings/graph.txt) that model
-      any data bus to the connector unless the bus is between parent node and
-      the connector. Since a single connector can have multiple data buses every
-      bus has an assigned OF graph port number as described below.
+    $ref: /schemas/graph.yaml#/properties/ports
     type: object
+    description: OF graph bindings modeling any data bus to the connector
+      unless the bus is between parent node and the connector. Since a single
+      connector can have multiple data buses every bus has an assigned OF graph
+      port number as described below.
+
     properties:
       port@0:
         type: object

Now that we have a graph schema, reference it from the common panel schema.

Cc Thierry Reding <[email protected]>

Cc Sam Ravnborg <[email protected]>

Cc Laurent Pinchart <[email protected]>

Signed-off-by Rob Herring <[email protected]>

Now that we have a graph schema, reference it from the common panel schema.

Cc Thierry Reding <[email protected]>

Cc Sam Ravnborg <[email protected]>

Cc Laurent Pinchart <[email protected]>

Signed-off-by Rob Herring <[email protected]>

---
v3: new patch

 .../devicetree/bindings/display/panel/panel-common.yaml    | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

Documentation/devicetree/bindings/display/panel/panel-common.yaml +3 -4

index cd6dc5461721..a3a72c574213 100644
@@ -68,16 +68,15 @@ properties:
 
   # Connectivity
   port:
-    type: object
+    $ref: /schemas/graph.yaml#/properties/port
 
   ports:
-    type: object
+    $ref: /schemas/graph.yaml#/properties/ports
     description:
       Panels receive video data through one or multiple connections. While
       the nature of those connections is specific to the panel type, the
       connectivity is expressed in a standard fashion using ports as specified
-      in the device graph bindings defined in
-      Documentation/devicetree/bindings/graph.txt.
+      in the device graph bindings.
 
   ddc-i2c-bus:
     $ref: /schemas/types.yaml#/definitions/phandle

Sameer, I wanted to experiment with what the interface for graph users looks like, so I've tweaked your patch a bit and converted 2 users.