[19/19] dt-bindings: media: cal: convert binding to yaml
diff mbox series

Message ID 20191018153437.20614-20-bparrot@ti.com
State Changes Requested
Headers show
Series
  • media: ti-vpe: cal: maintenance
Related show

Checks

Context Check Description
robh/checkpatch warning "total: 0 errors, 1 warnings, 186 lines checked"

Commit Message

Benoit Parrot Oct. 18, 2019, 3:34 p.m. UTC
Convert ti-cal.txt to ti,cal.yaml.

Signed-off-by: Benoit Parrot <bparrot@ti.com>
---
 .../devicetree/bindings/media/ti,cal.yaml     | 186 ++++++++++++++++++
 .../devicetree/bindings/media/ti-cal.txt      |  82 --------
 2 files changed, 186 insertions(+), 82 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/media/ti,cal.yaml
 delete mode 100644 Documentation/devicetree/bindings/media/ti-cal.txt

Comments

Hans Verkuil Oct. 21, 2019, 10:49 a.m. UTC | #1
On 10/18/19 5:34 PM, Benoit Parrot wrote:
> Convert ti-cal.txt to ti,cal.yaml.
> 
> Signed-off-by: Benoit Parrot <bparrot@ti.com>

Can you add this bindings file to MAINTAINERS as well in a separate patch?

Thanks!

	Hans

> ---
>  .../devicetree/bindings/media/ti,cal.yaml     | 186 ++++++++++++++++++
>  .../devicetree/bindings/media/ti-cal.txt      |  82 --------
>  2 files changed, 186 insertions(+), 82 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/media/ti,cal.yaml
>  delete mode 100644 Documentation/devicetree/bindings/media/ti-cal.txt
> 
> diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
> new file mode 100644
> index 000000000000..c3fbb22b4571
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
> @@ -0,0 +1,186 @@
> +# SPDX-License-Identifier: (GPL-2.0)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/media/ti,cal.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
> +
> +maintainers:
> +  - Benoit Parrot <bparrot@ti.com>
> +
> +description: |-
> +  The Camera Adaptation Layer (CAL) is a key component for image capture
> +  applications. The capture module provides the system interface and the
> +  processing capability to connect CSI2 image-sensor modules to the
> +  DRA72x device.
> +
> +  CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> +  should contain a 'port' child node with child 'endpoint' node. Please
> +  refer to the bindings defined in
> +  Documentation/devicetree/bindings/media/video-interfaces.txt.
> +
> +  compatible should be
> +     "ti,dra72-cal", for DRA72 controllers
> +     "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> +     "ti,dra76-cal", for DRA76 controllers
> +     "ti,am654-cal", for AM654 controllers
> +
> +properties:
> +  compatible:
> +      items:
> +        - enum:
> +            - ti,dra72-cal
> +            - ti,dra72-pre-es2-cal
> +            - ti,dra76-cal
> +            - ti,am654-cal
> +
> +  reg:
> +    minItems: 2
> +    items:
> +      - description: The CAL main register region
> +      - description: The RX Core0 (DPHY0) register region
> +      - description: The RX Core1 (DPHY1) register region
> +
> +  reg-names:
> +    minItems: 2
> +    items:
> +      - const: cal_top
> +      - const: cal_rx_core0
> +      - const: cal_rx_core1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  syscon-camerrx:
> +    maxItems: 1
> +    items:
> +      - description:
> +           phandle to the device control module and offset to the
> +           control_camerarx_core register
> +
> +  clocks:
> +    maxItems: 1
> +    description: functional clock
> +
> +  clock-names:
> +    items:
> +      - const: fck
> +
> +  power-domains:
> +    description:
> +      List of phandle and PM domain specifier as documented in
> +      Documentation/devicetree/bindings/power/power_domain.txt
> +    maxItems: 1
> +
> +  # See ./video-interfaces.txt for details
> +  ports:
> +    maxItems: 1
> +    type: object
> +    additionalProperties: false
> +
> +    properties:
> +      "#address-cells":
> +        const: 1
> +
> +      "#size-cells":
> +        const: 0
> +
> +    patternProperties:
> +      '^port@[0-9a-fA-F]+$':
> +        minItems: 1
> +        maxItems: 2
> +        type: object
> +        additionalProperties: false
> +
> +        properties:
> +          reg:
> +            minItems: 1
> +            items:
> +              - description: The port id
> +
> +        patternProperties:
> +          '^endpoint@[0-9a-fA-F]+$':
> +            minItems: 1
> +            type: object
> +            additionalProperties: false
> +
> +            properties:
> +              clock-lanes:
> +                maxItems: 1
> +
> +              data-lanes:
> +                minItems: 1
> +                maxItems: 4
> +
> +              remote-endpoint: true
> +
> +            required:
> +              - remote-endpoint
> +
> +        required:
> +          - reg
> +
> +required:
> +  - compatible
> +  - reg
> +  - reg-names
> +  - interrupts
> +  - syscon-camerrx
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    cal: cal@4845b000 {
> +        compatible = "ti,dra72-cal";
> +        reg = <0x4845B000 0x400>,
> +              <0x4845B800 0x40>,
> +              <0x4845B900 0x40>;
> +        reg-names = "cal_top",
> +                    "cal_rx_core0",
> +                    "cal_rx_core1";
> +        interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> +        syscon-camerrx = <&scm_conf 0xE94>;
> +
> +        ports {
> +              #address-cells = <1>;
> +              #size-cells = <0>;
> +
> +              csi2_0: port@0 {
> +                    reg = <0>;
> +                    csi2_phy0: endpoint@0 {
> +                           remote-endpoint = <&csi2_cam0>;
> +                           clock-lanes = <0>;
> +                           data-lanes = <1 2>;
> +                    };
> +              };
> +        };
> +    };
> +
> +    i2c5: i2c@4807c000 {
> +        status = "okay";
> +        clock-frequency = <400000>;
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ov5640@3c {
> +               compatible = "ovti,ov5640";
> +               reg = <0x3c>;
> +
> +               clocks = <&clk_ov5640_fixed>;
> +               clock-names = "xclk";
> +
> +               port {
> +                    csi2_cam0: endpoint@0 {
> +                            remote-endpoint = <&csi2_phy0>;
> +                            clock-lanes = <0>;
> +                            data-lanes = <1 2>;
> +                    };
> +               };
> +        };
> +    };
> +
> +...
> diff --git a/Documentation/devicetree/bindings/media/ti-cal.txt b/Documentation/devicetree/bindings/media/ti-cal.txt
> deleted file mode 100644
> index b7bf8492dc2a..000000000000
> --- a/Documentation/devicetree/bindings/media/ti-cal.txt
> +++ /dev/null
> @@ -1,82 +0,0 @@
> -Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL)
> -------------------------------------------------------
> -
> -The Camera Adaptation Layer (CAL) is a key component for image capture
> -applications. The capture module provides the system interface and the
> -processing capability to connect CSI2 image-sensor modules to the
> -DRA72x device.
> -
> -Required properties:
> -- compatible:
> - Should be "ti,dra72-cal", for DRA72 controllers
> - Should be "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> - Should be "ti,dra76-cal", for DRA76 controllers
> - Should be "ti,am654-cal", for AM654 controllers
> -- reg:	CAL Top level, Receiver Core #0, Receiver Core #1 and Camera RX
> -	control address space
> -- reg-names: cal_top, cal_rx_core0, cal_rx_core1 and camerrx_control
> -	     registers
> -- interrupts: should contain IRQ line for the CAL;
> -- syscon-camerrx: phandle to the device control module and offset to the
> -		  control_camerarx_core register
> -		  This node is meant to replace the "camerrx_control" reg
> -		  entry above but "camerrx_control" is still handled
> -		  for backward compatibility.
> -
> -CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> -should contain a 'port' child node with child 'endpoint' node. Please
> -refer to the bindings defined in
> -Documentation/devicetree/bindings/media/video-interfaces.txt.
> -
> -Example:
> -	cal: cal@4845b000 {
> -		compatible = "ti,dra72-cal";
> -		reg = <0x4845B000 0x400>,
> -		      <0x4845B800 0x40>,
> -		      <0x4845B900 0x40>;
> -		reg-names = "cal_top",
> -			    "cal_rx_core0",
> -			    "cal_rx_core1";
> -		interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> -		syscon-camerrx = <&scm_conf 0xE94>;
> -		#address-cells = <1>;
> -		#size-cells = <0>;
> -
> -		ports {
> -			#address-cells = <1>;
> -			#size-cells = <0>;
> -
> -			csi2_0: port@0 {
> -				reg = <0>;
> -				csi2_phy0: endpoint@0 {
> -					remote-endpoint = <&csi2_cam0>;
> -					clock-lanes = <0>;
> -					data-lanes = <1 2>;
> -				};
> -			};
> -			csi2_1: port@1 {
> -				reg = <1>;
> -			};
> -		};
> -	};
> -
> -	i2c5: i2c@4807c000 {
> -		status = "okay";
> -		clock-frequency = <400000>;
> -
> -		ov5640@3c {
> -			compatible = "ovti,ov5640";
> -			reg = <0x3c>;
> -
> -			clocks = <&clk_ov5640_fixed>;
> -			clock-names = "xclk";
> -
> -			port {
> -				csi2_cam0: endpoint {
> -					remote-endpoint = <&csi2_phy0>;
> -					clock-lanes = <0>;
> -					data-lanes = <1 2>;
> -				};
> -			};
> -		};
> -	};
>
Sakari Ailus Oct. 22, 2019, 7:46 a.m. UTC | #2
Hi Benoit,

Thanks for the patch.

On Fri, Oct 18, 2019 at 10:34:37AM -0500, Benoit Parrot wrote:
> Convert ti-cal.txt to ti,cal.yaml.
> 
> Signed-off-by: Benoit Parrot <bparrot@ti.com>
> ---
>  .../devicetree/bindings/media/ti,cal.yaml     | 186 ++++++++++++++++++
>  .../devicetree/bindings/media/ti-cal.txt      |  82 --------
>  2 files changed, 186 insertions(+), 82 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/media/ti,cal.yaml
>  delete mode 100644 Documentation/devicetree/bindings/media/ti-cal.txt
> 
> diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
> new file mode 100644
> index 000000000000..c3fbb22b4571
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
> @@ -0,0 +1,186 @@
> +# SPDX-License-Identifier: (GPL-2.0)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/media/ti,cal.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
> +
> +maintainers:
> +  - Benoit Parrot <bparrot@ti.com>
> +
> +description: |-
> +  The Camera Adaptation Layer (CAL) is a key component for image capture
> +  applications. The capture module provides the system interface and the
> +  processing capability to connect CSI2 image-sensor modules to the
> +  DRA72x device.
> +
> +  CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> +  should contain a 'port' child node with child 'endpoint' node. Please
> +  refer to the bindings defined in
> +  Documentation/devicetree/bindings/media/video-interfaces.txt.
> +
> +  compatible should be
> +     "ti,dra72-cal", for DRA72 controllers
> +     "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> +     "ti,dra76-cal", for DRA76 controllers
> +     "ti,am654-cal", for AM654 controllers
> +
> +properties:
> +  compatible:
> +      items:
> +        - enum:
> +            - ti,dra72-cal
> +            - ti,dra72-pre-es2-cal
> +            - ti,dra76-cal
> +            - ti,am654-cal
> +
> +  reg:
> +    minItems: 2
> +    items:
> +      - description: The CAL main register region
> +      - description: The RX Core0 (DPHY0) register region
> +      - description: The RX Core1 (DPHY1) register region
> +
> +  reg-names:
> +    minItems: 2
> +    items:
> +      - const: cal_top
> +      - const: cal_rx_core0
> +      - const: cal_rx_core1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  syscon-camerrx:
> +    maxItems: 1
> +    items:
> +      - description:
> +           phandle to the device control module and offset to the
> +           control_camerarx_core register
> +
> +  clocks:
> +    maxItems: 1
> +    description: functional clock
> +
> +  clock-names:
> +    items:
> +      - const: fck
> +
> +  power-domains:
> +    description:
> +      List of phandle and PM domain specifier as documented in
> +      Documentation/devicetree/bindings/power/power_domain.txt
> +    maxItems: 1
> +
> +  # See ./video-interfaces.txt for details
> +  ports:
> +    maxItems: 1
> +    type: object
> +    additionalProperties: false
> +
> +    properties:
> +      "#address-cells":
> +        const: 1
> +
> +      "#size-cells":
> +        const: 0
> +
> +    patternProperties:
> +      '^port@[0-9a-fA-F]+$':
> +        minItems: 1
> +        maxItems: 2

Obviously you need a port node to connect a sensor. But can the device do
something useful without one? I guess it may be a matter of taste whether
you require one.

> +        type: object
> +        additionalProperties: false
> +
> +        properties:
> +          reg:
> +            minItems: 1
> +            items:
> +              - description: The port id
> +
> +        patternProperties:
> +          '^endpoint@[0-9a-fA-F]+$':
> +            minItems: 1

The graph bindings allows for no endpoints.

> +            type: object
> +            additionalProperties: false
> +
> +            properties:
> +              clock-lanes:
> +                maxItems: 1

Does the device support lane reordering? If not, you could omit the
clock-lanes property. It wasn't documented earlier either albeit the
example had it for some reason.

> +
> +              data-lanes:
> +                minItems: 1
> +                maxItems: 4
> +
> +              remote-endpoint: true
> +
> +            required:
> +              - remote-endpoint
> +
> +        required:
> +          - reg
> +
> +required:
> +  - compatible
> +  - reg
> +  - reg-names
> +  - interrupts
> +  - syscon-camerrx
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    cal: cal@4845b000 {
> +        compatible = "ti,dra72-cal";
> +        reg = <0x4845B000 0x400>,
> +              <0x4845B800 0x40>,
> +              <0x4845B900 0x40>;
> +        reg-names = "cal_top",
> +                    "cal_rx_core0",
> +                    "cal_rx_core1";
> +        interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> +        syscon-camerrx = <&scm_conf 0xE94>;
> +
> +        ports {
> +              #address-cells = <1>;
> +              #size-cells = <0>;
> +
> +              csi2_0: port@0 {
> +                    reg = <0>;
> +                    csi2_phy0: endpoint@0 {
> +                           remote-endpoint = <&csi2_cam0>;
> +                           clock-lanes = <0>;
> +                           data-lanes = <1 2>;
> +                    };
> +              };
> +        };
> +    };
> +
> +    i2c5: i2c@4807c000 {
> +        status = "okay";
> +        clock-frequency = <400000>;
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ov5640@3c {
> +               compatible = "ovti,ov5640";
> +               reg = <0x3c>;
> +
> +               clocks = <&clk_ov5640_fixed>;
> +               clock-names = "xclk";
> +
> +               port {
> +                    csi2_cam0: endpoint@0 {
> +                            remote-endpoint = <&csi2_phy0>;
> +                            clock-lanes = <0>;
> +                            data-lanes = <1 2>;
> +                    };
> +               };
> +        };
> +    };
> +
> +...
> diff --git a/Documentation/devicetree/bindings/media/ti-cal.txt b/Documentation/devicetree/bindings/media/ti-cal.txt
> deleted file mode 100644
> index b7bf8492dc2a..000000000000
> --- a/Documentation/devicetree/bindings/media/ti-cal.txt
> +++ /dev/null
> @@ -1,82 +0,0 @@
> -Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL)
> -------------------------------------------------------
> -
> -The Camera Adaptation Layer (CAL) is a key component for image capture
> -applications. The capture module provides the system interface and the
> -processing capability to connect CSI2 image-sensor modules to the
> -DRA72x device.
> -
> -Required properties:
> -- compatible:
> - Should be "ti,dra72-cal", for DRA72 controllers
> - Should be "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> - Should be "ti,dra76-cal", for DRA76 controllers
> - Should be "ti,am654-cal", for AM654 controllers
> -- reg:	CAL Top level, Receiver Core #0, Receiver Core #1 and Camera RX
> -	control address space
> -- reg-names: cal_top, cal_rx_core0, cal_rx_core1 and camerrx_control
> -	     registers
> -- interrupts: should contain IRQ line for the CAL;
> -- syscon-camerrx: phandle to the device control module and offset to the
> -		  control_camerarx_core register
> -		  This node is meant to replace the "camerrx_control" reg
> -		  entry above but "camerrx_control" is still handled
> -		  for backward compatibility.
> -
> -CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> -should contain a 'port' child node with child 'endpoint' node. Please
> -refer to the bindings defined in
> -Documentation/devicetree/bindings/media/video-interfaces.txt.
> -
> -Example:
> -	cal: cal@4845b000 {
> -		compatible = "ti,dra72-cal";
> -		reg = <0x4845B000 0x400>,
> -		      <0x4845B800 0x40>,
> -		      <0x4845B900 0x40>;
> -		reg-names = "cal_top",
> -			    "cal_rx_core0",
> -			    "cal_rx_core1";
> -		interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> -		syscon-camerrx = <&scm_conf 0xE94>;
> -		#address-cells = <1>;
> -		#size-cells = <0>;
> -
> -		ports {
> -			#address-cells = <1>;
> -			#size-cells = <0>;
> -
> -			csi2_0: port@0 {
> -				reg = <0>;
> -				csi2_phy0: endpoint@0 {
> -					remote-endpoint = <&csi2_cam0>;
> -					clock-lanes = <0>;
> -					data-lanes = <1 2>;
> -				};
> -			};
> -			csi2_1: port@1 {
> -				reg = <1>;
> -			};
> -		};
> -	};
> -
> -	i2c5: i2c@4807c000 {
> -		status = "okay";
> -		clock-frequency = <400000>;
> -
> -		ov5640@3c {
> -			compatible = "ovti,ov5640";
> -			reg = <0x3c>;
> -
> -			clocks = <&clk_ov5640_fixed>;
> -			clock-names = "xclk";
> -
> -			port {
> -				csi2_cam0: endpoint {
> -					remote-endpoint = <&csi2_phy0>;
> -					clock-lanes = <0>;
> -					data-lanes = <1 2>;
> -				};
> -			};
> -		};
> -	};
Benoit Parrot Oct. 23, 2019, 4:06 p.m. UTC | #3
Hans Verkuil <hverkuil@xs4all.nl> wrote on Mon [2019-Oct-21 12:49:00 +0200]:
> On 10/18/19 5:34 PM, Benoit Parrot wrote:
> > Convert ti-cal.txt to ti,cal.yaml.
> > 
> > Signed-off-by: Benoit Parrot <bparrot@ti.com>
> 
> Can you add this bindings file to MAINTAINERS as well in a separate patch?

Yes I can do that, no problem.

Benoit

> 
> Thanks!
> 
> 	Hans
> 
> > ---
> >  .../devicetree/bindings/media/ti,cal.yaml     | 186 ++++++++++++++++++
> >  .../devicetree/bindings/media/ti-cal.txt      |  82 --------
> >  2 files changed, 186 insertions(+), 82 deletions(-)
> >  create mode 100644 Documentation/devicetree/bindings/media/ti,cal.yaml
> >  delete mode 100644 Documentation/devicetree/bindings/media/ti-cal.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
> > new file mode 100644
> > index 000000000000..c3fbb22b4571
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
> > @@ -0,0 +1,186 @@
> > +# SPDX-License-Identifier: (GPL-2.0)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/media/ti,cal.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
> > +
> > +maintainers:
> > +  - Benoit Parrot <bparrot@ti.com>
> > +
> > +description: |-
> > +  The Camera Adaptation Layer (CAL) is a key component for image capture
> > +  applications. The capture module provides the system interface and the
> > +  processing capability to connect CSI2 image-sensor modules to the
> > +  DRA72x device.
> > +
> > +  CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> > +  should contain a 'port' child node with child 'endpoint' node. Please
> > +  refer to the bindings defined in
> > +  Documentation/devicetree/bindings/media/video-interfaces.txt.
> > +
> > +  compatible should be
> > +     "ti,dra72-cal", for DRA72 controllers
> > +     "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> > +     "ti,dra76-cal", for DRA76 controllers
> > +     "ti,am654-cal", for AM654 controllers
> > +
> > +properties:
> > +  compatible:
> > +      items:
> > +        - enum:
> > +            - ti,dra72-cal
> > +            - ti,dra72-pre-es2-cal
> > +            - ti,dra76-cal
> > +            - ti,am654-cal
> > +
> > +  reg:
> > +    minItems: 2
> > +    items:
> > +      - description: The CAL main register region
> > +      - description: The RX Core0 (DPHY0) register region
> > +      - description: The RX Core1 (DPHY1) register region
> > +
> > +  reg-names:
> > +    minItems: 2
> > +    items:
> > +      - const: cal_top
> > +      - const: cal_rx_core0
> > +      - const: cal_rx_core1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  syscon-camerrx:
> > +    maxItems: 1
> > +    items:
> > +      - description:
> > +           phandle to the device control module and offset to the
> > +           control_camerarx_core register
> > +
> > +  clocks:
> > +    maxItems: 1
> > +    description: functional clock
> > +
> > +  clock-names:
> > +    items:
> > +      - const: fck
> > +
> > +  power-domains:
> > +    description:
> > +      List of phandle and PM domain specifier as documented in
> > +      Documentation/devicetree/bindings/power/power_domain.txt
> > +    maxItems: 1
> > +
> > +  # See ./video-interfaces.txt for details
> > +  ports:
> > +    maxItems: 1
> > +    type: object
> > +    additionalProperties: false
> > +
> > +    properties:
> > +      "#address-cells":
> > +        const: 1
> > +
> > +      "#size-cells":
> > +        const: 0
> > +
> > +    patternProperties:
> > +      '^port@[0-9a-fA-F]+$':
> > +        minItems: 1
> > +        maxItems: 2
> > +        type: object
> > +        additionalProperties: false
> > +
> > +        properties:
> > +          reg:
> > +            minItems: 1
> > +            items:
> > +              - description: The port id
> > +
> > +        patternProperties:
> > +          '^endpoint@[0-9a-fA-F]+$':
> > +            minItems: 1
> > +            type: object
> > +            additionalProperties: false
> > +
> > +            properties:
> > +              clock-lanes:
> > +                maxItems: 1
> > +
> > +              data-lanes:
> > +                minItems: 1
> > +                maxItems: 4
> > +
> > +              remote-endpoint: true
> > +
> > +            required:
> > +              - remote-endpoint
> > +
> > +        required:
> > +          - reg
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - reg-names
> > +  - interrupts
> > +  - syscon-camerrx
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +
> > +    cal: cal@4845b000 {
> > +        compatible = "ti,dra72-cal";
> > +        reg = <0x4845B000 0x400>,
> > +              <0x4845B800 0x40>,
> > +              <0x4845B900 0x40>;
> > +        reg-names = "cal_top",
> > +                    "cal_rx_core0",
> > +                    "cal_rx_core1";
> > +        interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> > +        syscon-camerrx = <&scm_conf 0xE94>;
> > +
> > +        ports {
> > +              #address-cells = <1>;
> > +              #size-cells = <0>;
> > +
> > +              csi2_0: port@0 {
> > +                    reg = <0>;
> > +                    csi2_phy0: endpoint@0 {
> > +                           remote-endpoint = <&csi2_cam0>;
> > +                           clock-lanes = <0>;
> > +                           data-lanes = <1 2>;
> > +                    };
> > +              };
> > +        };
> > +    };
> > +
> > +    i2c5: i2c@4807c000 {
> > +        status = "okay";
> > +        clock-frequency = <400000>;
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        ov5640@3c {
> > +               compatible = "ovti,ov5640";
> > +               reg = <0x3c>;
> > +
> > +               clocks = <&clk_ov5640_fixed>;
> > +               clock-names = "xclk";
> > +
> > +               port {
> > +                    csi2_cam0: endpoint@0 {
> > +                            remote-endpoint = <&csi2_phy0>;
> > +                            clock-lanes = <0>;
> > +                            data-lanes = <1 2>;
> > +                    };
> > +               };
> > +        };
> > +    };
> > +
> > +...
> > diff --git a/Documentation/devicetree/bindings/media/ti-cal.txt b/Documentation/devicetree/bindings/media/ti-cal.txt
> > deleted file mode 100644
> > index b7bf8492dc2a..000000000000
> > --- a/Documentation/devicetree/bindings/media/ti-cal.txt
> > +++ /dev/null
> > @@ -1,82 +0,0 @@
> > -Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL)
> > -------------------------------------------------------
> > -
> > -The Camera Adaptation Layer (CAL) is a key component for image capture
> > -applications. The capture module provides the system interface and the
> > -processing capability to connect CSI2 image-sensor modules to the
> > -DRA72x device.
> > -
> > -Required properties:
> > -- compatible:
> > - Should be "ti,dra72-cal", for DRA72 controllers
> > - Should be "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> > - Should be "ti,dra76-cal", for DRA76 controllers
> > - Should be "ti,am654-cal", for AM654 controllers
> > -- reg:	CAL Top level, Receiver Core #0, Receiver Core #1 and Camera RX
> > -	control address space
> > -- reg-names: cal_top, cal_rx_core0, cal_rx_core1 and camerrx_control
> > -	     registers
> > -- interrupts: should contain IRQ line for the CAL;
> > -- syscon-camerrx: phandle to the device control module and offset to the
> > -		  control_camerarx_core register
> > -		  This node is meant to replace the "camerrx_control" reg
> > -		  entry above but "camerrx_control" is still handled
> > -		  for backward compatibility.
> > -
> > -CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> > -should contain a 'port' child node with child 'endpoint' node. Please
> > -refer to the bindings defined in
> > -Documentation/devicetree/bindings/media/video-interfaces.txt.
> > -
> > -Example:
> > -	cal: cal@4845b000 {
> > -		compatible = "ti,dra72-cal";
> > -		reg = <0x4845B000 0x400>,
> > -		      <0x4845B800 0x40>,
> > -		      <0x4845B900 0x40>;
> > -		reg-names = "cal_top",
> > -			    "cal_rx_core0",
> > -			    "cal_rx_core1";
> > -		interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> > -		syscon-camerrx = <&scm_conf 0xE94>;
> > -		#address-cells = <1>;
> > -		#size-cells = <0>;
> > -
> > -		ports {
> > -			#address-cells = <1>;
> > -			#size-cells = <0>;
> > -
> > -			csi2_0: port@0 {
> > -				reg = <0>;
> > -				csi2_phy0: endpoint@0 {
> > -					remote-endpoint = <&csi2_cam0>;
> > -					clock-lanes = <0>;
> > -					data-lanes = <1 2>;
> > -				};
> > -			};
> > -			csi2_1: port@1 {
> > -				reg = <1>;
> > -			};
> > -		};
> > -	};
> > -
> > -	i2c5: i2c@4807c000 {
> > -		status = "okay";
> > -		clock-frequency = <400000>;
> > -
> > -		ov5640@3c {
> > -			compatible = "ovti,ov5640";
> > -			reg = <0x3c>;
> > -
> > -			clocks = <&clk_ov5640_fixed>;
> > -			clock-names = "xclk";
> > -
> > -			port {
> > -				csi2_cam0: endpoint {
> > -					remote-endpoint = <&csi2_phy0>;
> > -					clock-lanes = <0>;
> > -					data-lanes = <1 2>;
> > -				};
> > -			};
> > -		};
> > -	};
> > 
>
Benoit Parrot Oct. 23, 2019, 4:18 p.m. UTC | #4
Sakari Ailus <sakari.ailus@iki.fi> wrote on Tue [2019-Oct-22 10:46:23 +0300]:
> Hi Benoit,
> 
> Thanks for the patch.
> 
> On Fri, Oct 18, 2019 at 10:34:37AM -0500, Benoit Parrot wrote:
> > Convert ti-cal.txt to ti,cal.yaml.
> > 
> > Signed-off-by: Benoit Parrot <bparrot@ti.com>
> > ---
> >  .../devicetree/bindings/media/ti,cal.yaml     | 186 ++++++++++++++++++
> >  .../devicetree/bindings/media/ti-cal.txt      |  82 --------
> >  2 files changed, 186 insertions(+), 82 deletions(-)
> >  create mode 100644 Documentation/devicetree/bindings/media/ti,cal.yaml
> >  delete mode 100644 Documentation/devicetree/bindings/media/ti-cal.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
> > new file mode 100644
> > index 000000000000..c3fbb22b4571
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
> > @@ -0,0 +1,186 @@
> > +# SPDX-License-Identifier: (GPL-2.0)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/media/ti,cal.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
> > +
> > +maintainers:
> > +  - Benoit Parrot <bparrot@ti.com>
> > +
> > +description: |-
> > +  The Camera Adaptation Layer (CAL) is a key component for image capture
> > +  applications. The capture module provides the system interface and the
> > +  processing capability to connect CSI2 image-sensor modules to the
> > +  DRA72x device.
> > +
> > +  CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> > +  should contain a 'port' child node with child 'endpoint' node. Please
> > +  refer to the bindings defined in
> > +  Documentation/devicetree/bindings/media/video-interfaces.txt.
> > +
> > +  compatible should be
> > +     "ti,dra72-cal", for DRA72 controllers
> > +     "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> > +     "ti,dra76-cal", for DRA76 controllers
> > +     "ti,am654-cal", for AM654 controllers
> > +
> > +properties:
> > +  compatible:
> > +      items:
> > +        - enum:
> > +            - ti,dra72-cal
> > +            - ti,dra72-pre-es2-cal
> > +            - ti,dra76-cal
> > +            - ti,am654-cal
> > +
> > +  reg:
> > +    minItems: 2
> > +    items:
> > +      - description: The CAL main register region
> > +      - description: The RX Core0 (DPHY0) register region
> > +      - description: The RX Core1 (DPHY1) register region
> > +
> > +  reg-names:
> > +    minItems: 2
> > +    items:
> > +      - const: cal_top
> > +      - const: cal_rx_core0
> > +      - const: cal_rx_core1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  syscon-camerrx:
> > +    maxItems: 1
> > +    items:
> > +      - description:
> > +           phandle to the device control module and offset to the
> > +           control_camerarx_core register
> > +
> > +  clocks:
> > +    maxItems: 1
> > +    description: functional clock
> > +
> > +  clock-names:
> > +    items:
> > +      - const: fck
> > +
> > +  power-domains:
> > +    description:
> > +      List of phandle and PM domain specifier as documented in
> > +      Documentation/devicetree/bindings/power/power_domain.txt
> > +    maxItems: 1
> > +
> > +  # See ./video-interfaces.txt for details
> > +  ports:
> > +    maxItems: 1
> > +    type: object
> > +    additionalProperties: false
> > +
> > +    properties:
> > +      "#address-cells":
> > +        const: 1
> > +
> > +      "#size-cells":
> > +        const: 0
> > +
> > +    patternProperties:
> > +      '^port@[0-9a-fA-F]+$':
> > +        minItems: 1
> > +        maxItems: 2
> 
> Obviously you need a port node to connect a sensor. But can the device do
> something useful without one? I guess it may be a matter of taste whether
> you require one.

In an ideal world all of these would be covered by a video-interfaces.yaml
file I would just need to include... :)

But I'll try and add some more "required" and see how much trouble it gets
me.
> 
> > +        type: object
> > +        additionalProperties: false
> > +
> > +        properties:
> > +          reg:
> > +            minItems: 1
> > +            items:
> > +              - description: The port id
> > +
> > +        patternProperties:
> > +          '^endpoint@[0-9a-fA-F]+$':
> > +            minItems: 1
> 
> The graph bindings allows for no endpoints.

Maybe but then it is not much use.
> 
> > +            type: object
> > +            additionalProperties: false
> > +
> > +            properties:
> > +              clock-lanes:
> > +                maxItems: 1
> 
> Does the device support lane reordering? If not, you could omit the
> clock-lanes property. It wasn't documented earlier either albeit the
> example had it for some reason.

Not sure what you mean by lane re-ordering here, but this IP needs to know
which lanes are used for data and which lane is the clock lane.

I cannot just assume that clock lane is always lane 0, I have a sensor
where the clock lane is #2 for instance and the data lanes are 0, 1, 3, 4.

But at any rate before it was not specifically documented because I thought
it was covered by the "see
Documentation/devicetree/bindings/media/video-interfaces.txt" or de we need
to duplicate that in every binding?

Benoit
> 
> > +
> > +              data-lanes:
> > +                minItems: 1
> > +                maxItems: 4
> > +
> > +              remote-endpoint: true
> > +
> > +            required:
> > +              - remote-endpoint
> > +
> > +        required:
> > +          - reg
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - reg-names
> > +  - interrupts
> > +  - syscon-camerrx
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +
> > +    cal: cal@4845b000 {
> > +        compatible = "ti,dra72-cal";
> > +        reg = <0x4845B000 0x400>,
> > +              <0x4845B800 0x40>,
> > +              <0x4845B900 0x40>;
> > +        reg-names = "cal_top",
> > +                    "cal_rx_core0",
> > +                    "cal_rx_core1";
> > +        interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> > +        syscon-camerrx = <&scm_conf 0xE94>;
> > +
> > +        ports {
> > +              #address-cells = <1>;
> > +              #size-cells = <0>;
> > +
> > +              csi2_0: port@0 {
> > +                    reg = <0>;
> > +                    csi2_phy0: endpoint@0 {
> > +                           remote-endpoint = <&csi2_cam0>;
> > +                           clock-lanes = <0>;
> > +                           data-lanes = <1 2>;
> > +                    };
> > +              };
> > +        };
> > +    };
> > +
> > +    i2c5: i2c@4807c000 {
> > +        status = "okay";
> > +        clock-frequency = <400000>;
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        ov5640@3c {
> > +               compatible = "ovti,ov5640";
> > +               reg = <0x3c>;
> > +
> > +               clocks = <&clk_ov5640_fixed>;
> > +               clock-names = "xclk";
> > +
> > +               port {
> > +                    csi2_cam0: endpoint@0 {
> > +                            remote-endpoint = <&csi2_phy0>;
> > +                            clock-lanes = <0>;
> > +                            data-lanes = <1 2>;
> > +                    };
> > +               };
> > +        };
> > +    };
> > +
> > +...
> > diff --git a/Documentation/devicetree/bindings/media/ti-cal.txt b/Documentation/devicetree/bindings/media/ti-cal.txt
> > deleted file mode 100644
> > index b7bf8492dc2a..000000000000
> > --- a/Documentation/devicetree/bindings/media/ti-cal.txt
> > +++ /dev/null
> > @@ -1,82 +0,0 @@
> > -Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL)
> > -------------------------------------------------------
> > -
> > -The Camera Adaptation Layer (CAL) is a key component for image capture
> > -applications. The capture module provides the system interface and the
> > -processing capability to connect CSI2 image-sensor modules to the
> > -DRA72x device.
> > -
> > -Required properties:
> > -- compatible:
> > - Should be "ti,dra72-cal", for DRA72 controllers
> > - Should be "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> > - Should be "ti,dra76-cal", for DRA76 controllers
> > - Should be "ti,am654-cal", for AM654 controllers
> > -- reg:	CAL Top level, Receiver Core #0, Receiver Core #1 and Camera RX
> > -	control address space
> > -- reg-names: cal_top, cal_rx_core0, cal_rx_core1 and camerrx_control
> > -	     registers
> > -- interrupts: should contain IRQ line for the CAL;
> > -- syscon-camerrx: phandle to the device control module and offset to the
> > -		  control_camerarx_core register
> > -		  This node is meant to replace the "camerrx_control" reg
> > -		  entry above but "camerrx_control" is still handled
> > -		  for backward compatibility.
> > -
> > -CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> > -should contain a 'port' child node with child 'endpoint' node. Please
> > -refer to the bindings defined in
> > -Documentation/devicetree/bindings/media/video-interfaces.txt.
> > -
> > -Example:
> > -	cal: cal@4845b000 {
> > -		compatible = "ti,dra72-cal";
> > -		reg = <0x4845B000 0x400>,
> > -		      <0x4845B800 0x40>,
> > -		      <0x4845B900 0x40>;
> > -		reg-names = "cal_top",
> > -			    "cal_rx_core0",
> > -			    "cal_rx_core1";
> > -		interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> > -		syscon-camerrx = <&scm_conf 0xE94>;
> > -		#address-cells = <1>;
> > -		#size-cells = <0>;
> > -
> > -		ports {
> > -			#address-cells = <1>;
> > -			#size-cells = <0>;
> > -
> > -			csi2_0: port@0 {
> > -				reg = <0>;
> > -				csi2_phy0: endpoint@0 {
> > -					remote-endpoint = <&csi2_cam0>;
> > -					clock-lanes = <0>;
> > -					data-lanes = <1 2>;
> > -				};
> > -			};
> > -			csi2_1: port@1 {
> > -				reg = <1>;
> > -			};
> > -		};
> > -	};
> > -
> > -	i2c5: i2c@4807c000 {
> > -		status = "okay";
> > -		clock-frequency = <400000>;
> > -
> > -		ov5640@3c {
> > -			compatible = "ovti,ov5640";
> > -			reg = <0x3c>;
> > -
> > -			clocks = <&clk_ov5640_fixed>;
> > -			clock-names = "xclk";
> > -
> > -			port {
> > -				csi2_cam0: endpoint {
> > -					remote-endpoint = <&csi2_phy0>;
> > -					clock-lanes = <0>;
> > -					data-lanes = <1 2>;
> > -				};
> > -			};
> > -		};
> > -	};
> 
> -- 
> Kind regards,
> 
> Sakari Ailus
Sakari Ailus Oct. 24, 2019, 6:13 a.m. UTC | #5
Hi Benoit,

On Wed, Oct 23, 2019 at 11:18:45AM -0500, Benoit Parrot wrote:
> Sakari Ailus <sakari.ailus@iki.fi> wrote on Tue [2019-Oct-22 10:46:23 +0300]:
> > Hi Benoit,
> > 
> > Thanks for the patch.
> > 
> > On Fri, Oct 18, 2019 at 10:34:37AM -0500, Benoit Parrot wrote:
> > > Convert ti-cal.txt to ti,cal.yaml.
> > > 
> > > Signed-off-by: Benoit Parrot <bparrot@ti.com>
> > > ---
> > >  .../devicetree/bindings/media/ti,cal.yaml     | 186 ++++++++++++++++++
> > >  .../devicetree/bindings/media/ti-cal.txt      |  82 --------
> > >  2 files changed, 186 insertions(+), 82 deletions(-)
> > >  create mode 100644 Documentation/devicetree/bindings/media/ti,cal.yaml
> > >  delete mode 100644 Documentation/devicetree/bindings/media/ti-cal.txt
> > > 
> > > diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
> > > new file mode 100644
> > > index 000000000000..c3fbb22b4571
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
> > > @@ -0,0 +1,186 @@
> > > +# SPDX-License-Identifier: (GPL-2.0)
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/media/ti,cal.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
> > > +
> > > +maintainers:
> > > +  - Benoit Parrot <bparrot@ti.com>
> > > +
> > > +description: |-
> > > +  The Camera Adaptation Layer (CAL) is a key component for image capture
> > > +  applications. The capture module provides the system interface and the
> > > +  processing capability to connect CSI2 image-sensor modules to the
> > > +  DRA72x device.
> > > +
> > > +  CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> > > +  should contain a 'port' child node with child 'endpoint' node. Please
> > > +  refer to the bindings defined in
> > > +  Documentation/devicetree/bindings/media/video-interfaces.txt.
> > > +
> > > +  compatible should be
> > > +     "ti,dra72-cal", for DRA72 controllers
> > > +     "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> > > +     "ti,dra76-cal", for DRA76 controllers
> > > +     "ti,am654-cal", for AM654 controllers
> > > +
> > > +properties:
> > > +  compatible:
> > > +      items:
> > > +        - enum:
> > > +            - ti,dra72-cal
> > > +            - ti,dra72-pre-es2-cal
> > > +            - ti,dra76-cal
> > > +            - ti,am654-cal
> > > +
> > > +  reg:
> > > +    minItems: 2
> > > +    items:
> > > +      - description: The CAL main register region
> > > +      - description: The RX Core0 (DPHY0) register region
> > > +      - description: The RX Core1 (DPHY1) register region
> > > +
> > > +  reg-names:
> > > +    minItems: 2
> > > +    items:
> > > +      - const: cal_top
> > > +      - const: cal_rx_core0
> > > +      - const: cal_rx_core1
> > > +
> > > +  interrupts:
> > > +    maxItems: 1
> > > +
> > > +  syscon-camerrx:
> > > +    maxItems: 1
> > > +    items:
> > > +      - description:
> > > +           phandle to the device control module and offset to the
> > > +           control_camerarx_core register
> > > +
> > > +  clocks:
> > > +    maxItems: 1
> > > +    description: functional clock
> > > +
> > > +  clock-names:
> > > +    items:
> > > +      - const: fck
> > > +
> > > +  power-domains:
> > > +    description:
> > > +      List of phandle and PM domain specifier as documented in
> > > +      Documentation/devicetree/bindings/power/power_domain.txt
> > > +    maxItems: 1
> > > +
> > > +  # See ./video-interfaces.txt for details
> > > +  ports:
> > > +    maxItems: 1
> > > +    type: object
> > > +    additionalProperties: false
> > > +
> > > +    properties:
> > > +      "#address-cells":
> > > +        const: 1
> > > +
> > > +      "#size-cells":
> > > +        const: 0
> > > +
> > > +    patternProperties:
> > > +      '^port@[0-9a-fA-F]+$':
> > > +        minItems: 1
> > > +        maxItems: 2
> > 
> > Obviously you need a port node to connect a sensor. But can the device do
> > something useful without one? I guess it may be a matter of taste whether
> > you require one.
> 
> In an ideal world all of these would be covered by a video-interfaces.yaml
> file I would just need to include... :)
> 
> But I'll try and add some more "required" and see how much trouble it gets
> me.
> > 
> > > +        type: object
> > > +        additionalProperties: false
> > > +
> > > +        properties:
> > > +          reg:
> > > +            minItems: 1
> > > +            items:
> > > +              - description: The port id
> > > +
> > > +        patternProperties:
> > > +          '^endpoint@[0-9a-fA-F]+$':
> > > +            minItems: 1
> > 
> > The graph bindings allows for no endpoints.
> 
> Maybe but then it is not much use.

I guess you can require the endpoint in device bindings still. But the
question is: do you need to?

> > 
> > > +            type: object
> > > +            additionalProperties: false
> > > +
> > > +            properties:
> > > +              clock-lanes:
> > > +                maxItems: 1
> > 
> > Does the device support lane reordering? If not, you could omit the
> > clock-lanes property. It wasn't documented earlier either albeit the
> > example had it for some reason.
> 
> Not sure what you mean by lane re-ordering here, but this IP needs to know
> which lanes are used for data and which lane is the clock lane.
> 
> I cannot just assume that clock lane is always lane 0, I have a sensor
> where the clock lane is #2 for instance and the data lanes are 0, 1, 3, 4.
> 
> But at any rate before it was not specifically documented because I thought
> it was covered by the "see
> Documentation/devicetree/bindings/media/video-interfaces.txt" or de we need
> to duplicate that in every binding?

Then you should indeed have clock-lanes here as you need to know the
position of the clock lane. Most devices either just can make use of the
number of lanes or the order of the lanes is freely configurable (e.g. OMAP
3 ISP). The former group just needs data-lanes.
Rob Herring Oct. 29, 2019, 2:22 p.m. UTC | #6
On Fri, Oct 18, 2019 at 10:34:37AM -0500, Benoit Parrot wrote:
> Convert ti-cal.txt to ti,cal.yaml.
> 
> Signed-off-by: Benoit Parrot <bparrot@ti.com>
> ---
>  .../devicetree/bindings/media/ti,cal.yaml     | 186 ++++++++++++++++++
>  .../devicetree/bindings/media/ti-cal.txt      |  82 --------
>  2 files changed, 186 insertions(+), 82 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/media/ti,cal.yaml
>  delete mode 100644 Documentation/devicetree/bindings/media/ti-cal.txt
> 
> diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
> new file mode 100644
> index 000000000000..c3fbb22b4571
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
> @@ -0,0 +1,186 @@
> +# SPDX-License-Identifier: (GPL-2.0)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/media/ti,cal.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
> +
> +maintainers:
> +  - Benoit Parrot <bparrot@ti.com>
> +
> +description: |-
> +  The Camera Adaptation Layer (CAL) is a key component for image capture
> +  applications. The capture module provides the system interface and the
> +  processing capability to connect CSI2 image-sensor modules to the
> +  DRA72x device.
> +
> +  CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> +  should contain a 'port' child node with child 'endpoint' node. Please
> +  refer to the bindings defined in
> +  Documentation/devicetree/bindings/media/video-interfaces.txt.
> +
> +  compatible should be
> +     "ti,dra72-cal", for DRA72 controllers
> +     "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> +     "ti,dra76-cal", for DRA76 controllers
> +     "ti,am654-cal", for AM654 controllers

Drop these or add as comments to the schema below.

> +
> +properties:
> +  compatible:
> +      items:

You can drop 'items' here since there is only 1.

> +        - enum:
> +            - ti,dra72-cal
> +            - ti,dra72-pre-es2-cal
> +            - ti,dra76-cal
> +            - ti,am654-cal
> +
> +  reg:
> +    minItems: 2
> +    items:
> +      - description: The CAL main register region
> +      - description: The RX Core0 (DPHY0) register region
> +      - description: The RX Core1 (DPHY1) register region
> +
> +  reg-names:
> +    minItems: 2
> +    items:
> +      - const: cal_top
> +      - const: cal_rx_core0
> +      - const: cal_rx_core1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  syscon-camerrx:

Needs a type definition.

> +    maxItems: 1
> +    items:
> +      - description:
> +           phandle to the device control module and offset to the
> +           control_camerarx_core register
> +
> +  clocks:
> +    maxItems: 1
> +    description: functional clock

You can drop the description.

> +
> +  clock-names:
> +    items:

Drop items.

> +      - const: fck
> +
> +  power-domains:
> +    description:
> +      List of phandle and PM domain specifier as documented in
> +      Documentation/devicetree/bindings/power/power_domain.txt
> +    maxItems: 1
> +
> +  # See ./video-interfaces.txt for details
> +  ports:
> +    maxItems: 1

But ports is not an array...

> +    type: object
> +    additionalProperties: false
> +
> +    properties:
> +      "#address-cells":
> +        const: 1
> +
> +      "#size-cells":
> +        const: 0
> +
> +    patternProperties:
> +      '^port@[0-9a-fA-F]+$':

In a device binding, you need to specify 'port@0' and 'port@1' (assuming 
0 and 1) and say what they are.

> +        minItems: 1
> +        maxItems: 2

Not valid for an object (aka node).

> +        type: object
> +        additionalProperties: false
> +
> +        properties:
> +          reg:
> +            minItems: 1
> +            items:
> +              - description: The port id
> +
> +        patternProperties:
> +          '^endpoint@[0-9a-fA-F]+$':

Just 'endpoint' is valid too.

> +            minItems: 1
> +            type: object
> +            additionalProperties: false
> +
> +            properties:
> +              clock-lanes:
> +                maxItems: 1
> +
> +              data-lanes:
> +                minItems: 1
> +                maxItems: 4
> +
> +              remote-endpoint: true
> +
> +            required:
> +              - remote-endpoint
> +
> +        required:
> +          - reg
> +
> +required:
> +  - compatible
> +  - reg
> +  - reg-names
> +  - interrupts
> +  - syscon-camerrx
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    cal: cal@4845b000 {
> +        compatible = "ti,dra72-cal";
> +        reg = <0x4845B000 0x400>,
> +              <0x4845B800 0x40>,
> +              <0x4845B900 0x40>;
> +        reg-names = "cal_top",
> +                    "cal_rx_core0",
> +                    "cal_rx_core1";
> +        interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> +        syscon-camerrx = <&scm_conf 0xE94>;
> +
> +        ports {
> +              #address-cells = <1>;
> +              #size-cells = <0>;
> +
> +              csi2_0: port@0 {
> +                    reg = <0>;
> +                    csi2_phy0: endpoint@0 {
> +                           remote-endpoint = <&csi2_cam0>;
> +                           clock-lanes = <0>;
> +                           data-lanes = <1 2>;
> +                    };
> +              };
> +        };
> +    };
> +
> +    i2c5: i2c@4807c000 {
> +        status = "okay";
> +        clock-frequency = <400000>;
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ov5640@3c {
> +               compatible = "ovti,ov5640";
> +               reg = <0x3c>;
> +
> +               clocks = <&clk_ov5640_fixed>;
> +               clock-names = "xclk";
> +
> +               port {
> +                    csi2_cam0: endpoint@0 {
> +                            remote-endpoint = <&csi2_phy0>;
> +                            clock-lanes = <0>;
> +                            data-lanes = <1 2>;
> +                    };
> +               };
> +        };
> +    };
> +
> +...
Benoit Parrot Oct. 30, 2019, 1:54 p.m. UTC | #7
Rob Herring <robh@kernel.org> wrote on Tue [2019-Oct-29 09:22:53 -0500]:
> On Fri, Oct 18, 2019 at 10:34:37AM -0500, Benoit Parrot wrote:
> > Convert ti-cal.txt to ti,cal.yaml.
> > 
> > Signed-off-by: Benoit Parrot <bparrot@ti.com>
> > ---
> >  .../devicetree/bindings/media/ti,cal.yaml     | 186 ++++++++++++++++++
> >  .../devicetree/bindings/media/ti-cal.txt      |  82 --------
> >  2 files changed, 186 insertions(+), 82 deletions(-)
> >  create mode 100644 Documentation/devicetree/bindings/media/ti,cal.yaml
> >  delete mode 100644 Documentation/devicetree/bindings/media/ti-cal.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
> > new file mode 100644
> > index 000000000000..c3fbb22b4571
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
> > @@ -0,0 +1,186 @@
> > +# SPDX-License-Identifier: (GPL-2.0)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/media/ti,cal.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
> > +
> > +maintainers:
> > +  - Benoit Parrot <bparrot@ti.com>
> > +
> > +description: |-
> > +  The Camera Adaptation Layer (CAL) is a key component for image capture
> > +  applications. The capture module provides the system interface and the
> > +  processing capability to connect CSI2 image-sensor modules to the
> > +  DRA72x device.
> > +
> > +  CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
> > +  should contain a 'port' child node with child 'endpoint' node. Please
> > +  refer to the bindings defined in
> > +  Documentation/devicetree/bindings/media/video-interfaces.txt.
> > +
> > +  compatible should be
> > +     "ti,dra72-cal", for DRA72 controllers
> > +     "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
> > +     "ti,dra76-cal", for DRA76 controllers
> > +     "ti,am654-cal", for AM654 controllers
> 
> Drop these or add as comments to the schema below.

Ok.

> 
> > +
> > +properties:
> > +  compatible:
> > +      items:
> 
> You can drop 'items' here since there is only 1.

Ok so just enum then?

> 
> > +        - enum:
> > +            - ti,dra72-cal
> > +            - ti,dra72-pre-es2-cal
> > +            - ti,dra76-cal
> > +            - ti,am654-cal
> > +
> > +  reg:
> > +    minItems: 2
> > +    items:
> > +      - description: The CAL main register region
> > +      - description: The RX Core0 (DPHY0) register region
> > +      - description: The RX Core1 (DPHY1) register region
> > +
> > +  reg-names:
> > +    minItems: 2
> > +    items:
> > +      - const: cal_top
> > +      - const: cal_rx_core0
> > +      - const: cal_rx_core1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  syscon-camerrx:
> 
> Needs a type definition.

Hmm, is there a phandle generic type?

> 
> > +    maxItems: 1
> > +    items:
> > +      - description:
> > +           phandle to the device control module and offset to the
> > +           control_camerarx_core register
> > +
> > +  clocks:
> > +    maxItems: 1
> > +    description: functional clock
> 
> You can drop the description.

Ok.

> 
> > +
> > +  clock-names:
> > +    items:
> 
> Drop items.

Ok.

> 
> > +      - const: fck
> > +
> > +  power-domains:
> > +    description:
> > +      List of phandle and PM domain specifier as documented in
> > +      Documentation/devicetree/bindings/power/power_domain.txt
> > +    maxItems: 1
> > +
> > +  # See ./video-interfaces.txt for details
> > +  ports:
> > +    maxItems: 1
> 
> But ports is not an array...

So remove maxItems? Not sure what you mean here?

> 
> > +    type: object
> > +    additionalProperties: false
> > +
> > +    properties:
> > +      "#address-cells":
> > +        const: 1
> > +
> > +      "#size-cells":
> > +        const: 0
> > +
> > +    patternProperties:
> > +      '^port@[0-9a-fA-F]+$':
> 
> In a device binding, you need to specify 'port@0' and 'port@1' (assuming 
> 0 and 1) and say what they are.

Well depending on the 'variant' the device might have 1 or 2 physical csi2
ports so how would you represent that then?

> 
> > +        minItems: 1
> > +        maxItems: 2
> 
> Not valid for an object (aka node).

Again not sure how else to represent this.

> 
> > +        type: object
> > +        additionalProperties: false
> > +
> > +        properties:
> > +          reg:
> > +            minItems: 1
> > +            items:
> > +              - description: The port id
> > +
> > +        patternProperties:
> > +          '^endpoint@[0-9a-fA-F]+$':
> 
> Just 'endpoint' is valid too.

Ok I'll change that.

> 
> > +            minItems: 1
> > +            type: object
> > +            additionalProperties: false
> > +
> > +            properties:
> > +              clock-lanes:
> > +                maxItems: 1
> > +
> > +              data-lanes:
> > +                minItems: 1
> > +                maxItems: 4
> > +
> > +              remote-endpoint: true
> > +
> > +            required:
> > +              - remote-endpoint
> > +
> > +        required:
> > +          - reg
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - reg-names
> > +  - interrupts
> > +  - syscon-camerrx
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +
> > +    cal: cal@4845b000 {
> > +        compatible = "ti,dra72-cal";
> > +        reg = <0x4845B000 0x400>,
> > +              <0x4845B800 0x40>,
> > +              <0x4845B900 0x40>;
> > +        reg-names = "cal_top",
> > +                    "cal_rx_core0",
> > +                    "cal_rx_core1";
> > +        interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
> > +        syscon-camerrx = <&scm_conf 0xE94>;
> > +
> > +        ports {
> > +              #address-cells = <1>;
> > +              #size-cells = <0>;
> > +
> > +              csi2_0: port@0 {
> > +                    reg = <0>;
> > +                    csi2_phy0: endpoint@0 {
> > +                           remote-endpoint = <&csi2_cam0>;
> > +                           clock-lanes = <0>;
> > +                           data-lanes = <1 2>;
> > +                    };
> > +              };
> > +        };
> > +    };
> > +
> > +    i2c5: i2c@4807c000 {
> > +        status = "okay";
> > +        clock-frequency = <400000>;
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        ov5640@3c {
> > +               compatible = "ovti,ov5640";
> > +               reg = <0x3c>;
> > +
> > +               clocks = <&clk_ov5640_fixed>;
> > +               clock-names = "xclk";
> > +
> > +               port {
> > +                    csi2_cam0: endpoint@0 {
> > +                            remote-endpoint = <&csi2_phy0>;
> > +                            clock-lanes = <0>;
> > +                            data-lanes = <1 2>;
> > +                    };
> > +               };
> > +        };
> > +    };
> > +
> > +...

Patch
diff mbox series

diff --git a/Documentation/devicetree/bindings/media/ti,cal.yaml b/Documentation/devicetree/bindings/media/ti,cal.yaml
new file mode 100644
index 000000000000..c3fbb22b4571
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/ti,cal.yaml
@@ -0,0 +1,186 @@ 
+# SPDX-License-Identifier: (GPL-2.0)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/ti,cal.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) Device Tree Bindings
+
+maintainers:
+  - Benoit Parrot <bparrot@ti.com>
+
+description: |-
+  The Camera Adaptation Layer (CAL) is a key component for image capture
+  applications. The capture module provides the system interface and the
+  processing capability to connect CSI2 image-sensor modules to the
+  DRA72x device.
+
+  CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
+  should contain a 'port' child node with child 'endpoint' node. Please
+  refer to the bindings defined in
+  Documentation/devicetree/bindings/media/video-interfaces.txt.
+
+  compatible should be
+     "ti,dra72-cal", for DRA72 controllers
+     "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
+     "ti,dra76-cal", for DRA76 controllers
+     "ti,am654-cal", for AM654 controllers
+
+properties:
+  compatible:
+      items:
+        - enum:
+            - ti,dra72-cal
+            - ti,dra72-pre-es2-cal
+            - ti,dra76-cal
+            - ti,am654-cal
+
+  reg:
+    minItems: 2
+    items:
+      - description: The CAL main register region
+      - description: The RX Core0 (DPHY0) register region
+      - description: The RX Core1 (DPHY1) register region
+
+  reg-names:
+    minItems: 2
+    items:
+      - const: cal_top
+      - const: cal_rx_core0
+      - const: cal_rx_core1
+
+  interrupts:
+    maxItems: 1
+
+  syscon-camerrx:
+    maxItems: 1
+    items:
+      - description:
+           phandle to the device control module and offset to the
+           control_camerarx_core register
+
+  clocks:
+    maxItems: 1
+    description: functional clock
+
+  clock-names:
+    items:
+      - const: fck
+
+  power-domains:
+    description:
+      List of phandle and PM domain specifier as documented in
+      Documentation/devicetree/bindings/power/power_domain.txt
+    maxItems: 1
+
+  # See ./video-interfaces.txt for details
+  ports:
+    maxItems: 1
+    type: object
+    additionalProperties: false
+
+    properties:
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+    patternProperties:
+      '^port@[0-9a-fA-F]+$':
+        minItems: 1
+        maxItems: 2
+        type: object
+        additionalProperties: false
+
+        properties:
+          reg:
+            minItems: 1
+            items:
+              - description: The port id
+
+        patternProperties:
+          '^endpoint@[0-9a-fA-F]+$':
+            minItems: 1
+            type: object
+            additionalProperties: false
+
+            properties:
+              clock-lanes:
+                maxItems: 1
+
+              data-lanes:
+                minItems: 1
+                maxItems: 4
+
+              remote-endpoint: true
+
+            required:
+              - remote-endpoint
+
+        required:
+          - reg
+
+required:
+  - compatible
+  - reg
+  - reg-names
+  - interrupts
+  - syscon-camerrx
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    cal: cal@4845b000 {
+        compatible = "ti,dra72-cal";
+        reg = <0x4845B000 0x400>,
+              <0x4845B800 0x40>,
+              <0x4845B900 0x40>;
+        reg-names = "cal_top",
+                    "cal_rx_core0",
+                    "cal_rx_core1";
+        interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
+        syscon-camerrx = <&scm_conf 0xE94>;
+
+        ports {
+              #address-cells = <1>;
+              #size-cells = <0>;
+
+              csi2_0: port@0 {
+                    reg = <0>;
+                    csi2_phy0: endpoint@0 {
+                           remote-endpoint = <&csi2_cam0>;
+                           clock-lanes = <0>;
+                           data-lanes = <1 2>;
+                    };
+              };
+        };
+    };
+
+    i2c5: i2c@4807c000 {
+        status = "okay";
+        clock-frequency = <400000>;
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ov5640@3c {
+               compatible = "ovti,ov5640";
+               reg = <0x3c>;
+
+               clocks = <&clk_ov5640_fixed>;
+               clock-names = "xclk";
+
+               port {
+                    csi2_cam0: endpoint@0 {
+                            remote-endpoint = <&csi2_phy0>;
+                            clock-lanes = <0>;
+                            data-lanes = <1 2>;
+                    };
+               };
+        };
+    };
+
+...
diff --git a/Documentation/devicetree/bindings/media/ti-cal.txt b/Documentation/devicetree/bindings/media/ti-cal.txt
deleted file mode 100644
index b7bf8492dc2a..000000000000
--- a/Documentation/devicetree/bindings/media/ti-cal.txt
+++ /dev/null
@@ -1,82 +0,0 @@ 
-Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL)
-------------------------------------------------------
-
-The Camera Adaptation Layer (CAL) is a key component for image capture
-applications. The capture module provides the system interface and the
-processing capability to connect CSI2 image-sensor modules to the
-DRA72x device.
-
-Required properties:
-- compatible:
- Should be "ti,dra72-cal", for DRA72 controllers
- Should be "ti,dra72-pre-es2-cal", for DRA72 controllers pre ES2.0
- Should be "ti,dra76-cal", for DRA76 controllers
- Should be "ti,am654-cal", for AM654 controllers
-- reg:	CAL Top level, Receiver Core #0, Receiver Core #1 and Camera RX
-	control address space
-- reg-names: cal_top, cal_rx_core0, cal_rx_core1 and camerrx_control
-	     registers
-- interrupts: should contain IRQ line for the CAL;
-- syscon-camerrx: phandle to the device control module and offset to the
-		  control_camerarx_core register
-		  This node is meant to replace the "camerrx_control" reg
-		  entry above but "camerrx_control" is still handled
-		  for backward compatibility.
-
-CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes
-should contain a 'port' child node with child 'endpoint' node. Please
-refer to the bindings defined in
-Documentation/devicetree/bindings/media/video-interfaces.txt.
-
-Example:
-	cal: cal@4845b000 {
-		compatible = "ti,dra72-cal";
-		reg = <0x4845B000 0x400>,
-		      <0x4845B800 0x40>,
-		      <0x4845B900 0x40>;
-		reg-names = "cal_top",
-			    "cal_rx_core0",
-			    "cal_rx_core1";
-		interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>;
-		syscon-camerrx = <&scm_conf 0xE94>;
-		#address-cells = <1>;
-		#size-cells = <0>;
-
-		ports {
-			#address-cells = <1>;
-			#size-cells = <0>;
-
-			csi2_0: port@0 {
-				reg = <0>;
-				csi2_phy0: endpoint@0 {
-					remote-endpoint = <&csi2_cam0>;
-					clock-lanes = <0>;
-					data-lanes = <1 2>;
-				};
-			};
-			csi2_1: port@1 {
-				reg = <1>;
-			};
-		};
-	};
-
-	i2c5: i2c@4807c000 {
-		status = "okay";
-		clock-frequency = <400000>;
-
-		ov5640@3c {
-			compatible = "ovti,ov5640";
-			reg = <0x3c>;
-
-			clocks = <&clk_ov5640_fixed>;
-			clock-names = "xclk";
-
-			port {
-				csi2_cam0: endpoint {
-					remote-endpoint = <&csi2_phy0>;
-					clock-lanes = <0>;
-					data-lanes = <1 2>;
-				};
-			};
-		};
-	};