[PATCH v6 1/9] media: dt-bindings: Add OV5670

[PATCH v6 1/9] media: dt-bindings: Add OV5670

[Jacopo Mondi]

Add the bindings documentation for Omnivision OV5670 image sensor.

Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
---
 .../bindings/media/i2c/ovti,ov5670.yaml       | 92 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 2 files changed, 93 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml

diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml
new file mode 100644
index 000000000000..fa264255b5eb
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml
@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov5670.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV5670 5 Megapixels raw image sensor
+
+maintainers:
+  - Jacopo Mondi <jacopo.mondi@ideasonboard.com>
+
+description: |-
+  The OV5670 is a 5 Megapixels raw image sensor which provides images in 10-bits
+  RAW BGGR Bayer format on a 2 data lanes MIPI CSI-2 serial interface and is
+  controlled through an I2C compatible control bus.
+
+properties:
+  compatible:
+    const: ovti,ov5670
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    description: System clock. From 6 to 27 MHz.
+    maxItems: 1
+
+  powerdown-gpios:
+    description: Reference to the GPIO connected to the PWDNB pin. Active low.
+
+  reset-gpios:
+    description: Reference to the GPIO connected to the XSHUTDOWN pin. Active low.
+    maxItems: 1
+
+  avdd-supply:
+    description: Analog circuit power. Typically 2.8V.
+
+  dvdd-supply:
+    description: Digital circuit power. Typically 1.2V.
+
+  dovdd-supply:
+    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
+
+  port:
+    $ref: /schemas/graph.yaml#/$defs/port-base
+    additionalProperties: false
+
+    properties:
+      endpoint:
+        $ref: /schemas/media/video-interfaces.yaml#
+        unevaluatedProperties: false
+
+        properties:
+          data-lanes:
+            minItems: 1
+            maxItems: 2
+            items:
+              enum: [1, 2]
+
+          clock-noncontinuous: true
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - port
+
+additionalProperties: false
+
+examples:
+  - |
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ov5670: sensor@36 {
+            compatible = "ovti,ov5670";
+            reg = <0x36>;
+
+            clocks = <&sensor_xclk>;
+
+            port {
+                ov5670_ep: endpoint {
+                    remote-endpoint = <&csi_ep>;
+                    data-lanes = <1 2>;
+                    clock-noncontinuous;
+                };
+            };
+        };
+    };
+
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index f61eb221415b..38d8d1d5d536 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15468,6 +15468,7 @@ M:	Chiranjeevi Rapolu <chiranjeevi.rapolu@intel.com>
 L:	linux-media@vger.kernel.org
 S:	Maintained
 T:	git git://linuxtv.org/media_tree.git
+F:	Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml
 F:	drivers/media/i2c/ov5670.c

 OMNIVISION OV5675 SENSOR DRIVER
--
2.39.0

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Krzysztof Kozlowski]

On 26/01/2023 17:59, Jacopo Mondi wrote:
> Add the bindings documentation for Omnivision OV5670 image sensor.
> 
> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> ---

(...)

> +
> +  dovdd-supply:
> +    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
> +
> +  port:
> +    $ref: /schemas/graph.yaml#/$defs/port-base
> +    additionalProperties: false
> +
> +    properties:
> +      endpoint:
> +        $ref: /schemas/media/video-interfaces.yaml#
> +        unevaluatedProperties: false
> +
> +        properties:
> +          data-lanes:
> +            minItems: 1
> +            maxItems: 2
> +            items:
> +              enum: [1, 2]
> +
> +          clock-noncontinuous: true

You do not need this. Drop.

> +

Best regards,
Krzysztof

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Jacopo Mondi]

Hi Krzysztof

On Fri, Jan 27, 2023 at 03:19:08PM +0100, Krzysztof Kozlowski wrote:
> On 26/01/2023 17:59, Jacopo Mondi wrote:
> > Add the bindings documentation for Omnivision OV5670 image sensor.
> >
> > Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> > ---
>
> (...)
>
> > +
> > +  dovdd-supply:
> > +    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
> > +
> > +  port:
> > +    $ref: /schemas/graph.yaml#/$defs/port-base
> > +    additionalProperties: false
> > +
> > +    properties:
> > +      endpoint:
> > +        $ref: /schemas/media/video-interfaces.yaml#
> > +        unevaluatedProperties: false
> > +
> > +        properties:
> > +          data-lanes:
> > +            minItems: 1
> > +            maxItems: 2
> > +            items:
> > +              enum: [1, 2]
> > +
> > +          clock-noncontinuous: true
>
> You do not need this. Drop.
>

Is this due to "unevaluatedProperties: false" ?

I read you recent explanation to a similar question on the Visconti
bindings. Let me summarize my understanding:

For a given schema a property could be
- required
        required:
          - foo

- optional
        by default with "unevaluatedProperties: false"
        "foo: true" with "additionalProperties: false"

- forbidden
        "foo: false" with "unevaluatedProperties: false"
        by default wiht "additionalProperties: false"

clock-noncontinuous is defined in video-interfaces.yaml. as I specify
"unevaluatedProperties: false" does it mean
all the properties defined in video-interfaces.yaml are optionally
accepted ? If that's the case that's not what I want as
clock-noncontinuous is -the only- property from that file we want to
accept here (and data-lanes ofc).

Should I change "unevaluatedProperties: false" to
"additionalProperties: false" and keep "clock-noncontinuous: true"  ?

Thanks
   j

> > +
>
> Best regards,
> Krzysztof
>

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Krzysztof Kozlowski]

On 27/01/2023 19:14, Jacopo Mondi wrote:
> Hi Krzysztof
> 
> On Fri, Jan 27, 2023 at 03:19:08PM +0100, Krzysztof Kozlowski wrote:
>> On 26/01/2023 17:59, Jacopo Mondi wrote:
>>> Add the bindings documentation for Omnivision OV5670 image sensor.
>>>
>>> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
>>> ---
>>
>> (...)
>>
>>> +
>>> +  dovdd-supply:
>>> +    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
>>> +
>>> +  port:
>>> +    $ref: /schemas/graph.yaml#/$defs/port-base
>>> +    additionalProperties: false
>>> +
>>> +    properties:
>>> +      endpoint:
>>> +        $ref: /schemas/media/video-interfaces.yaml#
>>> +        unevaluatedProperties: false
>>> +
>>> +        properties:
>>> +          data-lanes:
>>> +            minItems: 1
>>> +            maxItems: 2
>>> +            items:
>>> +              enum: [1, 2]
>>> +
>>> +          clock-noncontinuous: true
>>
>> You do not need this. Drop.
>>
> 
> Is this due to "unevaluatedProperties: false" ?
> 
> I read you recent explanation to a similar question on the Visconti
> bindings. Let me summarize my understanding:
> 
> For a given schema a property could be
> - required
>         required:
>           - foo
> 
> - optional
>         by default with "unevaluatedProperties: false"
>         "foo: true" with "additionalProperties: false"
> 
> - forbidden
>         "foo: false" with "unevaluatedProperties: false"
>         by default wiht "additionalProperties: false"
> 
> clock-noncontinuous is defined in video-interfaces.yaml. as I specify
> "unevaluatedProperties: false" does it mean
> all the properties defined in video-interfaces.yaml are optionally
> accepted ? If that's the case that's not what I want as
> clock-noncontinuous is -the only- property from that file we want to
> accept here (and data-lanes ofc).
> 
> Should I change "unevaluatedProperties: false" to
> "additionalProperties: false" and keep "clock-noncontinuous: true"  ?
>

Why would you disallow other properties? Just because driver does not
use them? That's not correct, driver change but bindings should stay the
same.

Best regards,
Krzysztof

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Sakari Ailus]

Hi Krzysztof,

On Fri, Jan 27, 2023 at 08:58:20PM +0100, Krzysztof Kozlowski wrote:
> On 27/01/2023 19:14, Jacopo Mondi wrote:
> > Hi Krzysztof
> > 
> > On Fri, Jan 27, 2023 at 03:19:08PM +0100, Krzysztof Kozlowski wrote:
> >> On 26/01/2023 17:59, Jacopo Mondi wrote:
> >>> Add the bindings documentation for Omnivision OV5670 image sensor.
> >>>
> >>> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> >>> ---
> >>
> >> (...)
> >>
> >>> +
> >>> +  dovdd-supply:
> >>> +    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
> >>> +
> >>> +  port:
> >>> +    $ref: /schemas/graph.yaml#/$defs/port-base
> >>> +    additionalProperties: false
> >>> +
> >>> +    properties:
> >>> +      endpoint:
> >>> +        $ref: /schemas/media/video-interfaces.yaml#
> >>> +        unevaluatedProperties: false
> >>> +
> >>> +        properties:
> >>> +          data-lanes:
> >>> +            minItems: 1
> >>> +            maxItems: 2
> >>> +            items:
> >>> +              enum: [1, 2]
> >>> +
> >>> +          clock-noncontinuous: true
> >>
> >> You do not need this. Drop.
> >>
> > 
> > Is this due to "unevaluatedProperties: false" ?
> > 
> > I read you recent explanation to a similar question on the Visconti
> > bindings. Let me summarize my understanding:
> > 
> > For a given schema a property could be
> > - required
> >         required:
> >           - foo
> > 
> > - optional
> >         by default with "unevaluatedProperties: false"
> >         "foo: true" with "additionalProperties: false"
> > 
> > - forbidden
> >         "foo: false" with "unevaluatedProperties: false"
> >         by default wiht "additionalProperties: false"
> > 
> > clock-noncontinuous is defined in video-interfaces.yaml. as I specify
> > "unevaluatedProperties: false" does it mean
> > all the properties defined in video-interfaces.yaml are optionally
> > accepted ? If that's the case that's not what I want as
> > clock-noncontinuous is -the only- property from that file we want to
> > accept here (and data-lanes ofc).
> > 
> > Should I change "unevaluatedProperties: false" to
> > "additionalProperties: false" and keep "clock-noncontinuous: true"  ?
> >
> 
> Why would you disallow other properties? Just because driver does not
> use them? That's not correct, driver change but bindings should stay the
> same.

The clock-noncontinuous property is relevant for the hardware. There are
some properties not listed here that might be relevant (for all camera
sensors) but most properties in video-interfaces.yaml are not applicable to
this device.

I also think is be useful to say what is relevant in DT bindings, as the
other sources of information left are hardware datasheets (if you have
access to them) or the driver (which is supposed not to be relevant for the
bindings).

-- 
Kind regards,

Sakari Ailus

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Krzysztof Kozlowski]

On 27/01/2023 21:38, Sakari Ailus wrote:
> Hi Krzysztof,
> 
> On Fri, Jan 27, 2023 at 08:58:20PM +0100, Krzysztof Kozlowski wrote:
>> On 27/01/2023 19:14, Jacopo Mondi wrote:
>>> Hi Krzysztof
>>>
>>> On Fri, Jan 27, 2023 at 03:19:08PM +0100, Krzysztof Kozlowski wrote:
>>>> On 26/01/2023 17:59, Jacopo Mondi wrote:
>>>>> Add the bindings documentation for Omnivision OV5670 image sensor.
>>>>>
>>>>> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
>>>>> ---
>>>>
>>>> (...)
>>>>
>>>>> +
>>>>> +  dovdd-supply:
>>>>> +    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
>>>>> +
>>>>> +  port:
>>>>> +    $ref: /schemas/graph.yaml#/$defs/port-base
>>>>> +    additionalProperties: false
>>>>> +
>>>>> +    properties:
>>>>> +      endpoint:
>>>>> +        $ref: /schemas/media/video-interfaces.yaml#
>>>>> +        unevaluatedProperties: false
>>>>> +
>>>>> +        properties:
>>>>> +          data-lanes:
>>>>> +            minItems: 1
>>>>> +            maxItems: 2
>>>>> +            items:
>>>>> +              enum: [1, 2]
>>>>> +
>>>>> +          clock-noncontinuous: true
>>>>
>>>> You do not need this. Drop.
>>>>
>>>
>>> Is this due to "unevaluatedProperties: false" ?
>>>
>>> I read you recent explanation to a similar question on the Visconti
>>> bindings. Let me summarize my understanding:
>>>
>>> For a given schema a property could be
>>> - required
>>>         required:
>>>           - foo
>>>
>>> - optional
>>>         by default with "unevaluatedProperties: false"
>>>         "foo: true" with "additionalProperties: false"
>>>
>>> - forbidden
>>>         "foo: false" with "unevaluatedProperties: false"
>>>         by default wiht "additionalProperties: false"
>>>
>>> clock-noncontinuous is defined in video-interfaces.yaml. as I specify
>>> "unevaluatedProperties: false" does it mean
>>> all the properties defined in video-interfaces.yaml are optionally
>>> accepted ? If that's the case that's not what I want as
>>> clock-noncontinuous is -the only- property from that file we want to
>>> accept here (and data-lanes ofc).
>>>
>>> Should I change "unevaluatedProperties: false" to
>>> "additionalProperties: false" and keep "clock-noncontinuous: true"  ?
>>>
>>
>> Why would you disallow other properties? Just because driver does not
>> use them? That's not correct, driver change but bindings should stay the
>> same.
> 
> The clock-noncontinuous property is relevant for the hardware. There are
> some properties not listed here that might be relevant (for all camera
> sensors) but most properties in video-interfaces.yaml are not applicable to
> this device.
> 
> I also think is be useful to say what is relevant in DT bindings, as the
> other sources of information left are hardware datasheets (if you have
> access to them) or the driver (which is supposed not to be relevant for the
> bindings).
> 

Then it might be meaningful to list all allowed properties - even if not
currently supported by the driver - and use additionalProperties:false.
This has drawback - whenever video-interfaces gets something new, the
bindings here (and other such devices) will have to be explicitly enabled.

Best regards,
Krzysztof

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Jacopo Mondi]

Hi Krzysztof

On Fri, Jan 27, 2023 at 09:44:25PM +0100, Krzysztof Kozlowski wrote:
> On 27/01/2023 21:38, Sakari Ailus wrote:
> > Hi Krzysztof,
> >
> > On Fri, Jan 27, 2023 at 08:58:20PM +0100, Krzysztof Kozlowski wrote:
> >> On 27/01/2023 19:14, Jacopo Mondi wrote:
> >>> Hi Krzysztof
> >>>
> >>> On Fri, Jan 27, 2023 at 03:19:08PM +0100, Krzysztof Kozlowski wrote:
> >>>> On 26/01/2023 17:59, Jacopo Mondi wrote:
> >>>>> Add the bindings documentation for Omnivision OV5670 image sensor.
> >>>>>
> >>>>> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> >>>>> ---
> >>>>
> >>>> (...)
> >>>>
> >>>>> +
> >>>>> +  dovdd-supply:
> >>>>> +    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
> >>>>> +
> >>>>> +  port:
> >>>>> +    $ref: /schemas/graph.yaml#/$defs/port-base
> >>>>> +    additionalProperties: false
> >>>>> +
> >>>>> +    properties:
> >>>>> +      endpoint:
> >>>>> +        $ref: /schemas/media/video-interfaces.yaml#
> >>>>> +        unevaluatedProperties: false
> >>>>> +
> >>>>> +        properties:
> >>>>> +          data-lanes:
> >>>>> +            minItems: 1
> >>>>> +            maxItems: 2
> >>>>> +            items:
> >>>>> +              enum: [1, 2]
> >>>>> +
> >>>>> +          clock-noncontinuous: true
> >>>>
> >>>> You do not need this. Drop.
> >>>>
> >>>
> >>> Is this due to "unevaluatedProperties: false" ?
> >>>
> >>> I read you recent explanation to a similar question on the Visconti
> >>> bindings. Let me summarize my understanding:
> >>>
> >>> For a given schema a property could be
> >>> - required
> >>>         required:
> >>>           - foo
> >>>
> >>> - optional
> >>>         by default with "unevaluatedProperties: false"
> >>>         "foo: true" with "additionalProperties: false"
> >>>
> >>> - forbidden
> >>>         "foo: false" with "unevaluatedProperties: false"
> >>>         by default wiht "additionalProperties: false"
> >>>
> >>> clock-noncontinuous is defined in video-interfaces.yaml. as I specify
> >>> "unevaluatedProperties: false" does it mean
> >>> all the properties defined in video-interfaces.yaml are optionally
> >>> accepted ? If that's the case that's not what I want as
> >>> clock-noncontinuous is -the only- property from that file we want to
> >>> accept here (and data-lanes ofc).
> >>>
> >>> Should I change "unevaluatedProperties: false" to
> >>> "additionalProperties: false" and keep "clock-noncontinuous: true"  ?
> >>>
> >>
> >> Why would you disallow other properties? Just because driver does not
> >> use them? That's not correct, driver change but bindings should stay the
> >> same.
> >
> > The clock-noncontinuous property is relevant for the hardware. There are
> > some properties not listed here that might be relevant (for all camera
> > sensors) but most properties in video-interfaces.yaml are not applicable to
> > this device.
> >
> > I also think is be useful to say what is relevant in DT bindings, as the
> > other sources of information left are hardware datasheets (if you have
> > access to them) or the driver (which is supposed not to be relevant for the
> > bindings).
> >
>
> Then it might be meaningful to list all allowed properties - even if not
> currently supported by the driver - and use additionalProperties:false.

Have a look at what properties video-interfaces.yaml lists. Some of
them only apply to CSI-2 sensors (data lanes, link-frequencies etc),
some of them only to parallel sensors (lines polarities, bus-width
etc).

I see most of the bindings in media/i2c reporting

        $ref: /schemas/media/video-interfaces.yaml#
        unevaluatedProperties: false

I think that's actually wrong as there's no way all the properties in
video-interfaces.yaml can apply to a single device (with the exception
of a few sensors that support both bus types).

> This has drawback - whenever video-interfaces gets something new, the
> bindings here (and other such devices) will have to be explicitly enabled.

video-interfaces is rarely updated, and when it happes it's to add
properties required by a newly supported device, so this doesn't
concern me much personally.

>
> Best regards,
> Krzysztof
>

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Sakari Ailus]

Hi Jacopo, Krzysztof,

On Sat, Jan 28, 2023 at 10:58:31AM +0100, Jacopo Mondi wrote:
> Hi Krzysztof
> 
> On Fri, Jan 27, 2023 at 09:44:25PM +0100, Krzysztof Kozlowski wrote:
> > On 27/01/2023 21:38, Sakari Ailus wrote:
> > > Hi Krzysztof,
> > >
> > > On Fri, Jan 27, 2023 at 08:58:20PM +0100, Krzysztof Kozlowski wrote:
> > >> On 27/01/2023 19:14, Jacopo Mondi wrote:
> > >>> Hi Krzysztof
> > >>>
> > >>> On Fri, Jan 27, 2023 at 03:19:08PM +0100, Krzysztof Kozlowski wrote:
> > >>>> On 26/01/2023 17:59, Jacopo Mondi wrote:
> > >>>>> Add the bindings documentation for Omnivision OV5670 image sensor.
> > >>>>>
> > >>>>> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> > >>>>> ---
> > >>>>
> > >>>> (...)
> > >>>>
> > >>>>> +
> > >>>>> +  dovdd-supply:
> > >>>>> +    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
> > >>>>> +
> > >>>>> +  port:
> > >>>>> +    $ref: /schemas/graph.yaml#/$defs/port-base
> > >>>>> +    additionalProperties: false
> > >>>>> +
> > >>>>> +    properties:
> > >>>>> +      endpoint:
> > >>>>> +        $ref: /schemas/media/video-interfaces.yaml#
> > >>>>> +        unevaluatedProperties: false
> > >>>>> +
> > >>>>> +        properties:
> > >>>>> +          data-lanes:
> > >>>>> +            minItems: 1
> > >>>>> +            maxItems: 2
> > >>>>> +            items:
> > >>>>> +              enum: [1, 2]
> > >>>>> +
> > >>>>> +          clock-noncontinuous: true
> > >>>>
> > >>>> You do not need this. Drop.
> > >>>>
> > >>>
> > >>> Is this due to "unevaluatedProperties: false" ?
> > >>>
> > >>> I read you recent explanation to a similar question on the Visconti
> > >>> bindings. Let me summarize my understanding:
> > >>>
> > >>> For a given schema a property could be
> > >>> - required
> > >>>         required:
> > >>>           - foo
> > >>>
> > >>> - optional
> > >>>         by default with "unevaluatedProperties: false"
> > >>>         "foo: true" with "additionalProperties: false"
> > >>>
> > >>> - forbidden
> > >>>         "foo: false" with "unevaluatedProperties: false"
> > >>>         by default wiht "additionalProperties: false"
> > >>>
> > >>> clock-noncontinuous is defined in video-interfaces.yaml. as I specify
> > >>> "unevaluatedProperties: false" does it mean
> > >>> all the properties defined in video-interfaces.yaml are optionally
> > >>> accepted ? If that's the case that's not what I want as
> > >>> clock-noncontinuous is -the only- property from that file we want to
> > >>> accept here (and data-lanes ofc).
> > >>>
> > >>> Should I change "unevaluatedProperties: false" to
> > >>> "additionalProperties: false" and keep "clock-noncontinuous: true"  ?
> > >>>
> > >>
> > >> Why would you disallow other properties? Just because driver does not
> > >> use them? That's not correct, driver change but bindings should stay the
> > >> same.
> > >
> > > The clock-noncontinuous property is relevant for the hardware. There are
> > > some properties not listed here that might be relevant (for all camera
> > > sensors) but most properties in video-interfaces.yaml are not applicable to
> > > this device.
> > >
> > > I also think is be useful to say what is relevant in DT bindings, as the
> > > other sources of information left are hardware datasheets (if you have
> > > access to them) or the driver (which is supposed not to be relevant for the
> > > bindings).
> > >
> >
> > Then it might be meaningful to list all allowed properties - even if not
> > currently supported by the driver - and use additionalProperties:false.
> 
> Have a look at what properties video-interfaces.yaml lists. Some of
> them only apply to CSI-2 sensors (data lanes, link-frequencies etc),
> some of them only to parallel sensors (lines polarities, bus-width
> etc).
> 
> I see most of the bindings in media/i2c reporting
> 
>         $ref: /schemas/media/video-interfaces.yaml#
>         unevaluatedProperties: false
> 
> I think that's actually wrong as there's no way all the properties in
> video-interfaces.yaml can apply to a single device (with the exception
> of a few sensors that support both bus types).

It's been in my plan to split this into multiple files so you could refer
to fewer than all the properties. I have no schedule for this though.

> 
> > This has drawback - whenever video-interfaces gets something new, the
> > bindings here (and other such devices) will have to be explicitly enabled.
> 
> video-interfaces is rarely updated, and when it happes it's to add
> properties required by a newly supported device, so this doesn't
> concern me much personally.

Me neither.

-- 
Kind regards,

Sakari Ailus

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Jacopo Mondi]

Since I got the attention of both of you, let me point out another
issue I'm facing.

We also have video-interface-devices.yaml which lists properties for
the device node and not for the endpoints.

video-interface-devices lists properties that should be all optionally
accepted, as they can potentially apply to all sensors (things like
rotation, orientation, lens-focus, flash-leds are valid for all
devices)

Being properties for the device node they should be specified in the
schema top-level and I see a few schema that do that by

        allOf:
          - $ref: /schemas/media/video-interface-devices.yaml#

However top level schemas usually specify

        additionalProperties: false

Which means each sensor schema has to list the properties it accepts from
video-interface-devices.yaml. It's easy to verify this just by
adding "orientation" to the example in a schema that refers to
video-interface-devices.yaml and see that the bindings validation
fails (see below)

TL;DR is there a way to tell in a schema with a top-level
"additionalProperties: false" that all properties from a referenced
schema are accepted ?

I'll leave video-interface-devices.yaml this out from this series for
now and only resend this patch with the previous comments on the usage
of unevaluatedProperties fixed.

Thanks
  j


-----------------------------------------------------------------------------
--- a/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml
@@ -109,6 +109,7 @@ examples:
               powerdown-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>;
               reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>;
               rotation = <180>;
+              orientation = <0>;

               port {
                   /* MIPI CSI-2 bus endpoint */


$ make ARCH=arm64 dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml
  DTEX    Documentation/devicetree/bindings/media/i2c/ovti,ov5640.example.dts
  DTC_CHK Documentation/devicetree/bindings/media/i2c/ovti,ov5640.example.dtb
  /home/jmondi/linux-worktree/mainline/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.example.dtb: camera@3c: 'orientation' does not match any of the regexes: 'pinctrl-[0-9]+'
	From schema: /home/jmondi/linux-worktree/mainline/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml

On Sat, Jan 28, 2023 at 12:07:44PM +0200, Sakari Ailus wrote:
> Hi Jacopo, Krzysztof,
>
> On Sat, Jan 28, 2023 at 10:58:31AM +0100, Jacopo Mondi wrote:
> > Hi Krzysztof
> >
> > On Fri, Jan 27, 2023 at 09:44:25PM +0100, Krzysztof Kozlowski wrote:
> > > On 27/01/2023 21:38, Sakari Ailus wrote:
> > > > Hi Krzysztof,
> > > >
> > > > On Fri, Jan 27, 2023 at 08:58:20PM +0100, Krzysztof Kozlowski wrote:
> > > >> On 27/01/2023 19:14, Jacopo Mondi wrote:
> > > >>> Hi Krzysztof
> > > >>>
> > > >>> On Fri, Jan 27, 2023 at 03:19:08PM +0100, Krzysztof Kozlowski wrote:
> > > >>>> On 26/01/2023 17:59, Jacopo Mondi wrote:
> > > >>>>> Add the bindings documentation for Omnivision OV5670 image sensor.
> > > >>>>>
> > > >>>>> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> > > >>>>> ---
> > > >>>>
> > > >>>> (...)
> > > >>>>
> > > >>>>> +
> > > >>>>> +  dovdd-supply:
> > > >>>>> +    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
> > > >>>>> +
> > > >>>>> +  port:
> > > >>>>> +    $ref: /schemas/graph.yaml#/$defs/port-base
> > > >>>>> +    additionalProperties: false
> > > >>>>> +
> > > >>>>> +    properties:
> > > >>>>> +      endpoint:
> > > >>>>> +        $ref: /schemas/media/video-interfaces.yaml#
> > > >>>>> +        unevaluatedProperties: false
> > > >>>>> +
> > > >>>>> +        properties:
> > > >>>>> +          data-lanes:
> > > >>>>> +            minItems: 1
> > > >>>>> +            maxItems: 2
> > > >>>>> +            items:
> > > >>>>> +              enum: [1, 2]
> > > >>>>> +
> > > >>>>> +          clock-noncontinuous: true
> > > >>>>
> > > >>>> You do not need this. Drop.
> > > >>>>
> > > >>>
> > > >>> Is this due to "unevaluatedProperties: false" ?
> > > >>>
> > > >>> I read you recent explanation to a similar question on the Visconti
> > > >>> bindings. Let me summarize my understanding:
> > > >>>
> > > >>> For a given schema a property could be
> > > >>> - required
> > > >>>         required:
> > > >>>           - foo
> > > >>>
> > > >>> - optional
> > > >>>         by default with "unevaluatedProperties: false"
> > > >>>         "foo: true" with "additionalProperties: false"
> > > >>>
> > > >>> - forbidden
> > > >>>         "foo: false" with "unevaluatedProperties: false"
> > > >>>         by default wiht "additionalProperties: false"
> > > >>>
> > > >>> clock-noncontinuous is defined in video-interfaces.yaml. as I specify
> > > >>> "unevaluatedProperties: false" does it mean
> > > >>> all the properties defined in video-interfaces.yaml are optionally
> > > >>> accepted ? If that's the case that's not what I want as
> > > >>> clock-noncontinuous is -the only- property from that file we want to
> > > >>> accept here (and data-lanes ofc).
> > > >>>
> > > >>> Should I change "unevaluatedProperties: false" to
> > > >>> "additionalProperties: false" and keep "clock-noncontinuous: true"  ?
> > > >>>
> > > >>
> > > >> Why would you disallow other properties? Just because driver does not
> > > >> use them? That's not correct, driver change but bindings should stay the
> > > >> same.
> > > >
> > > > The clock-noncontinuous property is relevant for the hardware. There are
> > > > some properties not listed here that might be relevant (for all camera
> > > > sensors) but most properties in video-interfaces.yaml are not applicable to
> > > > this device.
> > > >
> > > > I also think is be useful to say what is relevant in DT bindings, as the
> > > > other sources of information left are hardware datasheets (if you have
> > > > access to them) or the driver (which is supposed not to be relevant for the
> > > > bindings).
> > > >
> > >
> > > Then it might be meaningful to list all allowed properties - even if not
> > > currently supported by the driver - and use additionalProperties:false.
> >
> > Have a look at what properties video-interfaces.yaml lists. Some of
> > them only apply to CSI-2 sensors (data lanes, link-frequencies etc),
> > some of them only to parallel sensors (lines polarities, bus-width
> > etc).
> >
> > I see most of the bindings in media/i2c reporting
> >
> >         $ref: /schemas/media/video-interfaces.yaml#
> >         unevaluatedProperties: false
> >
> > I think that's actually wrong as there's no way all the properties in
> > video-interfaces.yaml can apply to a single device (with the exception
> > of a few sensors that support both bus types).
>
> It's been in my plan to split this into multiple files so you could refer
> to fewer than all the properties. I have no schedule for this though.
>
> >
> > > This has drawback - whenever video-interfaces gets something new, the
> > > bindings here (and other such devices) will have to be explicitly enabled.
> >
> > video-interfaces is rarely updated, and when it happes it's to add
> > properties required by a newly supported device, so this doesn't
> > concern me much personally.
>
> Me neither.
>
> --
> Kind regards,
>
> Sakari Ailus

Re: [PATCH v6 1/9] media: dt-bindings: Add OV5670

[Krzysztof Kozlowski]

On 28/01/2023 12:03, Jacopo Mondi wrote:
> Since I got the attention of both of you, let me point out another
> issue I'm facing.
> 
> We also have video-interface-devices.yaml which lists properties for
> the device node and not for the endpoints.
> 
> video-interface-devices lists properties that should be all optionally
> accepted, as they can potentially apply to all sensors (things like
> rotation, orientation, lens-focus, flash-leds are valid for all
> devices)
> 
> Being properties for the device node they should be specified in the
> schema top-level and I see a few schema that do that by
> 
>         allOf:
>           - $ref: /schemas/media/video-interface-devices.yaml#
> 
> However top level schemas usually specify
> 
>         additionalProperties: false
> 
> Which means each sensor schema has to list the properties it accepts from
> video-interface-devices.yaml. It's easy to verify this just by
> adding "orientation" to the example in a schema that refers to
> video-interface-devices.yaml and see that the bindings validation
> fails (see below)
> 
> TL;DR is there a way to tell in a schema with a top-level
> "additionalProperties: false" that all properties from a referenced
> schema are accepted ?

No, because this would make it exactly the same as
unevaluatedProperties, so we would have two keywords with same meaning.

https://lore.kernel.org/all/c2740d66-b51f-efc2-6583-a69bde950c68@linaro.org/

Best regards,
Krzysztof

[PATCH v6.1] media: dt-bindings: Add OV5670

[Jacopo Mondi]

Add the bindings documentation for Omnivision OV5670 image sensor.

Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
---
v6->6.1
- Use additionalProperties: false for endpoint properties from
  video-interfaces.yaml
- List 'remote-endpoint' among the accepted endpoint properties
  now that we use additionalProperties: false
---
 .../bindings/media/i2c/ovti,ov5670.yaml       | 93 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 2 files changed, 94 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml

diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml
new file mode 100644
index 000000000000..6e089fe1d613
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ovti,ov5670.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Omnivision OV5670 5 Megapixels raw image sensor
+
+maintainers:
+  - Jacopo Mondi <jacopo.mondi@ideasonboard.com>
+
+description: |-
+  The OV5670 is a 5 Megapixels raw image sensor which provides images in 10-bits
+  RAW BGGR Bayer format on a 2 data lanes MIPI CSI-2 serial interface and is
+  controlled through an I2C compatible control bus.
+
+properties:
+  compatible:
+    const: ovti,ov5670
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    description: System clock. From 6 to 27 MHz.
+    maxItems: 1
+
+  powerdown-gpios:
+    description: Reference to the GPIO connected to the PWDNB pin. Active low.
+
+  reset-gpios:
+    description: Reference to the GPIO connected to the XSHUTDOWN pin. Active low.
+    maxItems: 1
+
+  avdd-supply:
+    description: Analog circuit power. Typically 2.8V.
+
+  dvdd-supply:
+    description: Digital circuit power. Typically 1.2V.
+
+  dovdd-supply:
+    description: Digital I/O circuit power. Typically 2.8V or 1.8V.
+
+  port:
+    $ref: /schemas/graph.yaml#/$defs/port-base
+    additionalProperties: false
+
+    properties:
+      endpoint:
+        $ref: /schemas/media/video-interfaces.yaml#
+        additionalProperties: false
+
+        properties:
+          data-lanes:
+            minItems: 1
+            maxItems: 2
+            items:
+              enum: [1, 2]
+
+          clock-noncontinuous: true
+          remote-endpoint: true
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - port
+
+additionalProperties: false
+
+examples:
+  - |
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ov5670: sensor@36 {
+            compatible = "ovti,ov5670";
+            reg = <0x36>;
+
+            clocks = <&sensor_xclk>;
+
+            port {
+                ov5670_ep: endpoint {
+                    remote-endpoint = <&csi_ep>;
+                    data-lanes = <1 2>;
+                    clock-noncontinuous;
+                };
+            };
+        };
+    };
+
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index f61eb221415b..38d8d1d5d536 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15468,6 +15468,7 @@ M:	Chiranjeevi Rapolu <chiranjeevi.rapolu@intel.com>
 L:	linux-media@vger.kernel.org
 S:	Maintained
 T:	git git://linuxtv.org/media_tree.git
+F:	Documentation/devicetree/bindings/media/i2c/ovti,ov5670.yaml
 F:	drivers/media/i2c/ov5670.c

 OMNIVISION OV5675 SENSOR DRIVER
--
2.39.0

Re: [PATCH v6.1] media: dt-bindings: Add OV5670

[Krzysztof Kozlowski]

On 28/01/2023 12:27, Jacopo Mondi wrote:
> Add the bindings documentation for Omnivision OV5670 image sensor.
> 
> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> ---
> v6->6.1
> - Use additionalProperties: false for endpoint properties from
>   video-interfaces.yaml
> - List 'remote-endpoint' among the accepted endpoint properties
>   now that we use additionalProperties: false

b4 diff '20230128112736.8000-1-jacopo.mondi@ideasonboard.com'
Could not create fake-am range for lower series v1

Can you send patches in a way it does not break out workflows? Why
making our review process more difficult?

Best regards,
Krzysztof

Re: [PATCH v6.1] media: dt-bindings: Add OV5670

[Jacopo Mondi]

On Sun, Jan 29, 2023 at 12:40:03PM +0100, Krzysztof Kozlowski wrote:
> On 28/01/2023 12:27, Jacopo Mondi wrote:
> > Add the bindings documentation for Omnivision OV5670 image sensor.
> >
> > Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> > ---
> > v6->6.1
> > - Use additionalProperties: false for endpoint properties from
> >   video-interfaces.yaml
> > - List 'remote-endpoint' among the accepted endpoint properties
> >   now that we use additionalProperties: false
>
> b4 diff '20230128112736.8000-1-jacopo.mondi@ideasonboard.com'
> Could not create fake-am range for lower series v1
>
> Can you send patches in a way it does not break out workflows? Why
> making our review process more difficult?

Because it's a nit on a 10 patches series with no other changes
requested ?

What is difficult exactly ?

I see several patches in linux-media being sent inline to a previous
version for small fixes if the only required changed is a nit like
this one.


> Best regards,
> Krzysztof
>

Re: [PATCH v6.1] media: dt-bindings: Add OV5670

[Krzysztof Kozlowski]

On 29/01/2023 13:11, Jacopo Mondi wrote:
> On Sun, Jan 29, 2023 at 12:40:03PM +0100, Krzysztof Kozlowski wrote:
>> On 28/01/2023 12:27, Jacopo Mondi wrote:
>>> Add the bindings documentation for Omnivision OV5670 image sensor.
>>>
>>> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
>>> ---
>>> v6->6.1
>>> - Use additionalProperties: false for endpoint properties from
>>>   video-interfaces.yaml
>>> - List 'remote-endpoint' among the accepted endpoint properties
>>>   now that we use additionalProperties: false
>>
>> b4 diff '20230128112736.8000-1-jacopo.mondi@ideasonboard.com'
>> Could not create fake-am range for lower series v1
>>
>> Can you send patches in a way it does not break out workflows? Why
>> making our review process more difficult?
> 
> Because it's a nit on a 10 patches series with no other changes
> requested ?
> 
> What is difficult exactly ?

I wrote above what's difficult.

> 
> I see several patches in linux-media being sent inline to a previous
> version for small fixes if the only required changed is a nit like
> this one.

If you sent it as separate v7 would be fine, but:
1. Threading is wrong - it's buried in other patch.
2. Version is wrong - you did there changes, not nits. There are no
point versions...

Best regards,
Krzysztof

Re: [PATCH v6.1] media: dt-bindings: Add OV5670

[Rob Herring]

On Sun, Jan 29, 2023 at 01:11:32PM +0100, Jacopo Mondi wrote:
> On Sun, Jan 29, 2023 at 12:40:03PM +0100, Krzysztof Kozlowski wrote:
> > On 28/01/2023 12:27, Jacopo Mondi wrote:
> > > Add the bindings documentation for Omnivision OV5670 image sensor.
> > >
> > > Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> > > ---
> > > v6->6.1
> > > - Use additionalProperties: false for endpoint properties from
> > >   video-interfaces.yaml
> > > - List 'remote-endpoint' among the accepted endpoint properties
> > >   now that we use additionalProperties: false
> >
> > b4 diff '20230128112736.8000-1-jacopo.mondi@ideasonboard.com'
> > Could not create fake-am range for lower series v1
> >
> > Can you send patches in a way it does not break out workflows? Why
> > making our review process more difficult?
> 
> Because it's a nit on a 10 patches series with no other changes
> requested ?

So? Think of patch series as an 'email transport' for your git branches. 
If you rebase your branch, that's a whole new branch to send.

> What is difficult exactly ?

In addition to 'b4 diff', if a maintainer is applying this series, for a 
v7 they just do:

b4 shazam msgid-of-v7

For v6.1, they do:

b4 shazam msgid-of-v6
git rebase -i ...
<stop on patch 1>
git reset --hard HEAD^
b4 shazam msgid-of-v6.1
git rebase --continue

Which one makes the maintainer's life easier?

If it's a CI job trying to apply and test this, there's no way it's 
going to do the second case.

Rob

Re: [PATCH v6.1] media: dt-bindings: Add OV5670

[Jacopo Mondi]

On Mon, Jan 30, 2023 at 09:58:40AM -0600, Rob Herring wrote:
> On Sun, Jan 29, 2023 at 01:11:32PM +0100, Jacopo Mondi wrote:
> > On Sun, Jan 29, 2023 at 12:40:03PM +0100, Krzysztof Kozlowski wrote:
> > > On 28/01/2023 12:27, Jacopo Mondi wrote:
> > > > Add the bindings documentation for Omnivision OV5670 image sensor.
> > > >
> > > > Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> > > > ---
> > > > v6->6.1
> > > > - Use additionalProperties: false for endpoint properties from
> > > >   video-interfaces.yaml
> > > > - List 'remote-endpoint' among the accepted endpoint properties
> > > >   now that we use additionalProperties: false
> > >
> > > b4 diff '20230128112736.8000-1-jacopo.mondi@ideasonboard.com'
> > > Could not create fake-am range for lower series v1
> > >
> > > Can you send patches in a way it does not break out workflows? Why
> > > making our review process more difficult?
> >
> > Because it's a nit on a 10 patches series with no other changes
> > requested ?
>
> So? Think of patch series as an 'email transport' for your git branches.
> If you rebase your branch, that's a whole new branch to send.
>

So if a series has a single comment and could be then collected as it
is but one patch I saw it happening multiple times on the ML and I
thought it was an accepted practice.


> > What is difficult exactly ?
>
> In addition to 'b4 diff', if a maintainer is applying this series, for a
> v7 they just do:
>
> b4 shazam msgid-of-v7
>
> For v6.1, they do:
>
> b4 shazam msgid-of-v6
> git rebase -i ...
> <stop on patch 1>
> git reset --hard HEAD^
> b4 shazam msgid-of-v6.1
> git rebase --continue
>
> Which one makes the maintainer's life easier?
>

With b4 it now certainly makes a difference.

As I save patches from my mail client and apply them manually I never
really considered picking one patch over the other from the same
thread "more difficult". I should have noticed when Krzysztof
mentioned b4 in his first reply.

> If it's a CI job trying to apply and test this, there's no way it's
> going to do the second case.
>

That's another point yes.

Got your message, I'll stop :)

Don't think a v7 is needed for this on though (if not other
comments ofc)

> Rob

Re: [PATCH v6.1] media: dt-bindings: Add OV5670

[Krzysztof Kozlowski]

On 28/01/2023 12:27, Jacopo Mondi wrote:
> Add the bindings documentation for Omnivision OV5670 image sensor.
> 
> Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> ---
> v6->6.1
> - Use additionalProperties: false for endpoint properties from
>   video-interfaces.yaml
> - List 'remote-endpoint' among the accepted endpoint properties
>   now that we use additionalProperties: false
> ---


Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Best regards,
Krzysztof