lkml.org 
[lkml]   [2020]   [Oct]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v4 08/15] Documentation: of: Convert graph bindings to json-schema
    Date
    Convert device tree bindings of graph to YAML format.

    Signed-off-by: Sameer Pujar <spujar@nvidia.com>
    Cc: Philipp Zabel <p.zabel@pengutronix.de>
    ---
    Documentation/devicetree/bindings/graph.txt | 128 --------------------
    Documentation/devicetree/bindings/graph.yaml | 170 +++++++++++++++++++++++++++
    2 files changed, 170 insertions(+), 128 deletions(-)
    delete mode 100644 Documentation/devicetree/bindings/graph.txt
    create mode 100644 Documentation/devicetree/bindings/graph.yaml

    diff --git a/Documentation/devicetree/bindings/graph.txt b/Documentation/devicetree/bindings/graph.txt
    deleted file mode 100644
    index 0415e2c..0000000
    --- a/Documentation/devicetree/bindings/graph.txt
    +++ /dev/null
    @@ -1,128 +0,0 @@
    -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.
    -
    diff --git a/Documentation/devicetree/bindings/graph.yaml b/Documentation/devicetree/bindings/graph.yaml
    new file mode 100644
    index 0000000..67804c1
    --- /dev/null
    +++ b/Documentation/devicetree/bindings/graph.yaml
    @@ -0,0 +1,170 @@
    +# 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 <p.zabel@pengutronix.de>
    +
    +definitions:
    +
    + port:
    + type: object
    + description: |
    + 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
    + '#address-cells' and '#size-cells' properties are required in relevant
    + parent node.
    +
    + patternProperties:
    + "^endpoint(@[0-9a-f]+)?$":
    + type: object
    + properties:
    + remote-endpoint:
    + description: |
    + phandle to an 'endpoint' subnode of a remote device node.
    + $ref: /schemas/types.yaml#/definitions/phandle
    +
    + ports:
    + type: object
    + patternProperties:
    + "^port(@[0-9a-f]+)?$":
    + $ref: "#/definitions/port"
    +
    +properties:
    + ports:
    + $ref: "#/definitions/ports"
    +
    +patternProperties:
    + "^port(@[0-9a-f]+)?$":
    + $ref: "#/definitions/port"
    +
    +additionalProperties: false
    +
    +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>;
    + };
    + };
    + };
    +
    +...
    --
    2.7.4
    \
     
     \ /
      Last update: 2020-10-16 16:45    [W:5.648 / U:0.028 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site