[PATCH v6 2/5] dt-bindings: media: max9286: Document 'maxim,reverse-channel-microvolt'

[PATCH v6 2/5] dt-bindings: media: max9286: Document 'maxim,reverse-channel-microvolt'

[Jacopo Mondi]

Document the 'reverse-channel-microvolt' vendor property in the
bindings document of the max9286 driver.

The newly introduced property allows to specifying the initial
configuration of the GMSL reverse control channel to accommodate
remote serializers pre-programmed with the high threshold power
supply noise immunity enabled.

Reviewed-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>
Signed-off-by: Jacopo Mondi <jacopo+renesas@jmondi.org>
---
v5->v6:
- Use standard unit suffix 'microvolt' for the custom property
- Drop '$ref' as according to 'example-schema.yaml':
  "Vendor specific properties having a standard unit suffix don't need a type."
---
 .../bindings/media/i2c/maxim,max9286.yaml     | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
index 9ea827092fdd..b22ba3e0db4a 100644
--- a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
+++ b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
@@ -51,6 +51,26 @@ properties:
   '#gpio-cells':
     const: 2

+  maxim,reverse-channel-microvolt:
+    minimum: 30000
+    maximum: 200000
+    default: 170000
+    description: |
+      Initial amplitude of the reverse control channel, in micro volts.
+
+      The initial amplitude shall be adjusted to a value compatible with the
+      configuration of the connected remote serializer.
+
+      Some camera modules (for example RDACM20) include an on-board MCU that
+      pre-programs the embedded serializer with power supply noise immunity
+      (high-threshold) enabled. A typical value of the deserializer's reverse
+      channel amplitude to communicate with pre-programmed serializers is
+      170000 micro volts.
+
+      A typical value for the reverse channel amplitude to communicate with
+      a remote serializer whose high-threshold noise immunity is not enabled
+      is 100000 micro volts
+
   ports:
     type: object
     description: |
@@ -221,6 +241,7 @@ required:
   - ports
   - i2c-mux
   - gpio-controller
+  - maxim,reverse-channel-microvolt

 additionalProperties: false

@@ -243,6 +264,8 @@ examples:
         gpio-controller;
         #gpio-cells = <2>;

+        maxim,reverse-channel-microvolt = <170000>;
+
         ports {
           #address-cells = <1>;
           #size-cells = <0>;
--
2.29.2

Re: [PATCH v6 2/5] dt-bindings: media: max9286: Document 'maxim,reverse-channel-microvolt'

[Laurent Pinchart]

Hi Jacopo,

Thank you for the patch.

On Tue, Dec 15, 2020 at 06:09:54PM +0100, Jacopo Mondi wrote:
> Document the 'reverse-channel-microvolt' vendor property in the
> bindings document of the max9286 driver.
> 
> The newly introduced property allows to specifying the initial
> configuration of the GMSL reverse control channel to accommodate
> remote serializers pre-programmed with the high threshold power
> supply noise immunity enabled.
> 
> Reviewed-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>
> Signed-off-by: Jacopo Mondi <jacopo+renesas@jmondi.org>

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> ---
> v5->v6:
> - Use standard unit suffix 'microvolt' for the custom property
> - Drop '$ref' as according to 'example-schema.yaml':
>   "Vendor specific properties having a standard unit suffix don't need a type."
> ---
>  .../bindings/media/i2c/maxim,max9286.yaml     | 23 +++++++++++++++++++
>  1 file changed, 23 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> index 9ea827092fdd..b22ba3e0db4a 100644
> --- a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> +++ b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> @@ -51,6 +51,26 @@ properties:
>    '#gpio-cells':
>      const: 2
> 
> +  maxim,reverse-channel-microvolt:
> +    minimum: 30000
> +    maximum: 200000
> +    default: 170000
> +    description: |
> +      Initial amplitude of the reverse control channel, in micro volts.
> +
> +      The initial amplitude shall be adjusted to a value compatible with the
> +      configuration of the connected remote serializer.
> +
> +      Some camera modules (for example RDACM20) include an on-board MCU that
> +      pre-programs the embedded serializer with power supply noise immunity
> +      (high-threshold) enabled. A typical value of the deserializer's reverse
> +      channel amplitude to communicate with pre-programmed serializers is
> +      170000 micro volts.
> +
> +      A typical value for the reverse channel amplitude to communicate with
> +      a remote serializer whose high-threshold noise immunity is not enabled
> +      is 100000 micro volts
> +
>    ports:
>      type: object
>      description: |
> @@ -221,6 +241,7 @@ required:
>    - ports
>    - i2c-mux
>    - gpio-controller
> +  - maxim,reverse-channel-microvolt
> 
>  additionalProperties: false
> 
> @@ -243,6 +264,8 @@ examples:
>          gpio-controller;
>          #gpio-cells = <2>;
> 
> +        maxim,reverse-channel-microvolt = <170000>;
> +
>          ports {
>            #address-cells = <1>;
>            #size-cells = <0>;

-- 
Regards,

Laurent Pinchart

Re: [PATCH v6 2/5] dt-bindings: media: max9286: Document 'maxim,reverse-channel-microvolt'

[Laurent Pinchart]

On Wed, Dec 16, 2020 at 07:05:34PM +0200, Laurent Pinchart wrote:
> Hi Jacopo,
> 
> Thank you for the patch.
> 
> On Tue, Dec 15, 2020 at 06:09:54PM +0100, Jacopo Mondi wrote:
> > Document the 'reverse-channel-microvolt' vendor property in the
> > bindings document of the max9286 driver.
> > 
> > The newly introduced property allows to specifying the initial
> > configuration of the GMSL reverse control channel to accommodate
> > remote serializers pre-programmed with the high threshold power
> > supply noise immunity enabled.
> > 
> > Reviewed-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>
> > Signed-off-by: Jacopo Mondi <jacopo+renesas@jmondi.org>
> 
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> 
> > ---
> > v5->v6:
> > - Use standard unit suffix 'microvolt' for the custom property
> > - Drop '$ref' as according to 'example-schema.yaml':
> >   "Vendor specific properties having a standard unit suffix don't need a type."
> > ---
> >  .../bindings/media/i2c/maxim,max9286.yaml     | 23 +++++++++++++++++++
> >  1 file changed, 23 insertions(+)
> > 
> > diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> > index 9ea827092fdd..b22ba3e0db4a 100644
> > --- a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> > +++ b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> > @@ -51,6 +51,26 @@ properties:
> >    '#gpio-cells':
> >      const: 2
> > 
> > +  maxim,reverse-channel-microvolt:
> > +    minimum: 30000
> > +    maximum: 200000
> > +    default: 170000
> > +    description: |
> > +      Initial amplitude of the reverse control channel, in micro volts.
> > +
> > +      The initial amplitude shall be adjusted to a value compatible with the
> > +      configuration of the connected remote serializer.
> > +
> > +      Some camera modules (for example RDACM20) include an on-board MCU that
> > +      pre-programs the embedded serializer with power supply noise immunity
> > +      (high-threshold) enabled. A typical value of the deserializer's reverse
> > +      channel amplitude to communicate with pre-programmed serializers is
> > +      170000 micro volts.
> > +
> > +      A typical value for the reverse channel amplitude to communicate with
> > +      a remote serializer whose high-threshold noise immunity is not enabled
> > +      is 100000 micro volts
> > +
> >    ports:
> >      type: object
> >      description: |
> > @@ -221,6 +241,7 @@ required:
> >    - ports
> >    - i2c-mux
> >    - gpio-controller
> > +  - maxim,reverse-channel-microvolt

One comment though: You specify a default value above, which isn't very
useful when the property is required. Should we either drop the default
value, or make the property optional ?

> > 
> >  additionalProperties: false
> > 
> > @@ -243,6 +264,8 @@ examples:
> >          gpio-controller;
> >          #gpio-cells = <2>;
> > 
> > +        maxim,reverse-channel-microvolt = <170000>;
> > +
> >          ports {
> >            #address-cells = <1>;
> >            #size-cells = <0>;

-- 
Regards,

Laurent Pinchart

Re: [PATCH v6 2/5] dt-bindings: media: max9286: Document 'maxim,reverse-channel-microvolt'

[Rob Herring]

On Wed, Dec 16, 2020 at 07:17:05PM +0200, Laurent Pinchart wrote:
> On Wed, Dec 16, 2020 at 07:05:34PM +0200, Laurent Pinchart wrote:
> > Hi Jacopo,
> > 
> > Thank you for the patch.
> > 
> > On Tue, Dec 15, 2020 at 06:09:54PM +0100, Jacopo Mondi wrote:
> > > Document the 'reverse-channel-microvolt' vendor property in the
> > > bindings document of the max9286 driver.
> > > 
> > > The newly introduced property allows to specifying the initial
> > > configuration of the GMSL reverse control channel to accommodate
> > > remote serializers pre-programmed with the high threshold power
> > > supply noise immunity enabled.
> > > 
> > > Reviewed-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com>
> > > Signed-off-by: Jacopo Mondi <jacopo+renesas@jmondi.org>
> > 
> > Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > 
> > > ---
> > > v5->v6:
> > > - Use standard unit suffix 'microvolt' for the custom property
> > > - Drop '$ref' as according to 'example-schema.yaml':
> > >   "Vendor specific properties having a standard unit suffix don't need a type."
> > > ---
> > >  .../bindings/media/i2c/maxim,max9286.yaml     | 23 +++++++++++++++++++
> > >  1 file changed, 23 insertions(+)
> > > 
> > > diff --git a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> > > index 9ea827092fdd..b22ba3e0db4a 100644
> > > --- a/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> > > +++ b/Documentation/devicetree/bindings/media/i2c/maxim,max9286.yaml
> > > @@ -51,6 +51,26 @@ properties:
> > >    '#gpio-cells':
> > >      const: 2
> > > 
> > > +  maxim,reverse-channel-microvolt:
> > > +    minimum: 30000
> > > +    maximum: 200000
> > > +    default: 170000
> > > +    description: |
> > > +      Initial amplitude of the reverse control channel, in micro volts.
> > > +
> > > +      The initial amplitude shall be adjusted to a value compatible with the
> > > +      configuration of the connected remote serializer.
> > > +
> > > +      Some camera modules (for example RDACM20) include an on-board MCU that
> > > +      pre-programs the embedded serializer with power supply noise immunity
> > > +      (high-threshold) enabled. A typical value of the deserializer's reverse
> > > +      channel amplitude to communicate with pre-programmed serializers is
> > > +      170000 micro volts.
> > > +
> > > +      A typical value for the reverse channel amplitude to communicate with
> > > +      a remote serializer whose high-threshold noise immunity is not enabled
> > > +      is 100000 micro volts
> > > +
> > >    ports:
> > >      type: object
> > >      description: |
> > > @@ -221,6 +241,7 @@ required:
> > >    - ports
> > >    - i2c-mux
> > >    - gpio-controller
> > > +  - maxim,reverse-channel-microvolt
> 
> One comment though: You specify a default value above, which isn't very
> useful when the property is required. Should we either drop the default
> value, or make the property optional ?

And generally added properties can't be required unless for some reason 
DT's without the property are broken.

With required dropped,

Reviewed-by: Rob Herring <robh@kernel.org>

Rob

Re: [PATCH v6 2/5] dt-bindings: media: max9286: Document 'maxim,reverse-channel-microvolt'

[Jacopo Mondi]

Hi Rob, Laurent,

On Mon, Dec 21, 2020 at 11:58:27AM -0700, Rob Herring wrote:
> On Wed, Dec 16, 2020 at 07:17:05PM +0200, Laurent Pinchart wrote:
> > > > @@ -221,6 +241,7 @@ required:
> > > >    - ports
> > > >    - i2c-mux
> > > >    - gpio-controller
> > > > +  - maxim,reverse-channel-microvolt
> >
> > One comment though: You specify a default value above, which isn't very
> > useful when the property is required. Should we either drop the default
> > value, or make the property optional ?
>
> And generally added properties can't be required unless for some reason
> DT's without the property are broken.

My thinking was to make it required for new DTS and specify a default
for the old ones that do not have the property. I'll drop required and
keep the default value in next version.

Thanks
  j

>
> With required dropped,
>
> Reviewed-by: Rob Herring <robh@kernel.org>
>
> Rob