diff mbox series

[v3,1/4] dt-bindings: iio: magnetometer: ak8975: convert txt format to yaml

Message ID 20200519124402.26076-2-jonathan.albrieux@gmail.com
State Superseded
Headers show
Series iio: magnetometer: ak8975: Add gpio reset support | expand

Checks

Context Check Description
robh/dt-meta-schema success
robh/checkpatch warning total: 0 errors, 2 warnings, 66 lines checked

Commit Message

Jonathan Albrieux May 19, 2020, 12:43 p.m. UTC
Converts documentation from txt format to yaml.

Signed-off-by: Jonathan Albrieux <jonathan.albrieux@gmail.com>
---
 .../bindings/iio/magnetometer/ak8975.txt      | 30 ---------
 .../bindings/iio/magnetometer/ak8975.yaml     | 66 +++++++++++++++++++
 2 files changed, 66 insertions(+), 30 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
 create mode 100644 Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml

Comments

Stephan Gerhold May 19, 2020, 1:22 p.m. UTC | #1
On Tue, May 19, 2020 at 02:43:51PM +0200, Jonathan Albrieux wrote:
> Converts documentation from txt format to yaml.
> 
> Signed-off-by: Jonathan Albrieux <jonathan.albrieux@gmail.com>
> ---
>  .../bindings/iio/magnetometer/ak8975.txt      | 30 ---------
>  .../bindings/iio/magnetometer/ak8975.yaml     | 66 +++++++++++++++++++
>  2 files changed, 66 insertions(+), 30 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
>  create mode 100644 Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
> deleted file mode 100644
> index aa67ceb0d4e0..000000000000
> --- a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
> +++ /dev/null
> @@ -1,30 +0,0 @@
> -* AsahiKASEI AK8975 magnetometer sensor
> -
> -Required properties:
> -
> -  - compatible : should be "asahi-kasei,ak8975"
> -  - reg : the I2C address of the magnetometer
> -
> -Optional properties:
> -
> -  - gpios : should be device tree identifier of the magnetometer DRDY pin
> -  - vdd-supply: an optional regulator that needs to be on to provide VDD
> -  - mount-matrix: an optional 3x3 mounting rotation matrix
> -
> -Example:
> -
> -ak8975@c {
> -        compatible = "asahi-kasei,ak8975";
> -        reg = <0x0c>;
> -        gpios = <&gpj0 7 0>;
> -        vdd-supply = <&ldo_3v3_gnss>;
> -        mount-matrix = "-0.984807753012208",  /* x0 */
> -                       "0",                   /* y0 */
> -                       "-0.173648177666930",  /* z0 */
> -                       "0",                   /* x1 */
> -                       "-1",                  /* y1 */
> -                       "0",                   /* z1 */
> -                       "-0.173648177666930",  /* x2 */
> -                       "0",                   /* y2 */
> -                       "0.984807753012208";   /* z2 */
> -};
> diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml
> new file mode 100644
> index 000000000000..86e3efa693a8
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml
> @@ -0,0 +1,66 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/magnetometer/ak8975.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: AsahiKASEI AK8975 magnetometer sensor
> +
> +maintainers:
> +  - can't find a mantainer, author is Laxman Dewangan <ldewangan@nvidia.com>

Should probably add someone here, although I'm not sure who either.

> +
> +properties:
> +  compatible:
> +    enum:
> +      - "asahi-kasei,ak8975"
> +      - "ak8975"
> +      - "asahi-kasei,ak8963"
> +      - "ak8963"
> +      - "asahi-kasei,ak09911"
> +      - "ak09911"
> +      - "asahi-kasei,ak09912"
> +      - "ak09912"
> +

I wonder if the ones without vendor prefix (asahi-kasei,) should be
marked as deprecated somehow?

Looking at some other schemas I see either a "# deprecated" comment, or:

properties:
  compatible:
    oneOf:
      - const: asahi-kasei,ak8975
      - const: asahi-kasei,ak8963
      - const: asahi-kasei,ak09911
      - const: asahi-kasei,ak09912
      - const: ak8975
        deprecated: true
      - const: ak8963
        deprecated: true
      - const: ak09911
        deprecated: true
      - const: ak09912
        deprecated: true

(e.g. in Documentation/devicetree/bindings/sound/samsung,odroid.yaml)
I guess this one is preferred since it allows parsing those
compatibles as deprecated?

> +  reg:
> +    maxItems: 1
> +    description: the I2C address of the magnetometer
> +
> +  gpios:
> +    description: should be device tree identifier of the magnetometer DRDY pin
> +
> +  vdd-supply:
> +    maxItems: 1
> +    description: |
> +      an optional regulator that needs to be on to provide VDD power to
> +      the sensor.
> +
> +  mount-matrix:
> +    description: an optional 3x3 mounting rotation matrix
> +
> +required:
> +  - compatible
> +  - reg
> +
> +examples:
> +  - |
> +    i2c@78b7000 {
> +        reg = <0x78b6000 0x600>;
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ak8975@c {

Per device tree specification this should preferably use a generic name
describing the function of the device, i.e. magnetometer@c.

> +            compatible = "asahi-kasei,ak8975";
> +            reg = <0x0c>;
> +            gpios = <&gpj0 7 0>;

I think using the dt-bindings constants for the GPIO flags is preferred
now, i.e. gpios = <&gpj0 7 GPIO_ACTIVE_HIGH>.

> +            vdd-supply = <&ldo_3v3_gnss>;
> +            mount-matrix = "-0.984807753012208",  /* x0 */
> +                           "0",                   /* y0 */
> +                           "-0.173648177666930",  /* z0 */
> +                           "0",                   /* x1 */
> +                           "-1",                  /* y1 */
> +                           "0",                   /* z1 */
> +                           "-0.173648177666930",  /* x2 */
> +                           "0",                   /* y2 */
> +                           "0.984807753012208";   /* z2 */
> +        };
> +    };
> -- 
> 2.17.1
Jonathan Albrieux May 19, 2020, 2:03 p.m. UTC | #2
On Tue, May 19, 2020 at 03:22:07PM +0200, Stephan Gerhold wrote:
> On Tue, May 19, 2020 at 02:43:51PM +0200, Jonathan Albrieux wrote:
> > Converts documentation from txt format to yaml.
> > 
> > Signed-off-by: Jonathan Albrieux <jonathan.albrieux@gmail.com>
> > ---
> >  .../bindings/iio/magnetometer/ak8975.txt      | 30 ---------
> >  .../bindings/iio/magnetometer/ak8975.yaml     | 66 +++++++++++++++++++
> >  2 files changed, 66 insertions(+), 30 deletions(-)
> >  delete mode 100644 Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
> >  create mode 100644 Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
> > deleted file mode 100644
> > index aa67ceb0d4e0..000000000000
> > --- a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
> > +++ /dev/null
> > @@ -1,30 +0,0 @@
> > -* AsahiKASEI AK8975 magnetometer sensor
> > -
> > -Required properties:
> > -
> > -  - compatible : should be "asahi-kasei,ak8975"
> > -  - reg : the I2C address of the magnetometer
> > -
> > -Optional properties:
> > -
> > -  - gpios : should be device tree identifier of the magnetometer DRDY pin
> > -  - vdd-supply: an optional regulator that needs to be on to provide VDD
> > -  - mount-matrix: an optional 3x3 mounting rotation matrix
> > -
> > -Example:
> > -
> > -ak8975@c {
> > -        compatible = "asahi-kasei,ak8975";
> > -        reg = <0x0c>;
> > -        gpios = <&gpj0 7 0>;
> > -        vdd-supply = <&ldo_3v3_gnss>;
> > -        mount-matrix = "-0.984807753012208",  /* x0 */
> > -                       "0",                   /* y0 */
> > -                       "-0.173648177666930",  /* z0 */
> > -                       "0",                   /* x1 */
> > -                       "-1",                  /* y1 */
> > -                       "0",                   /* z1 */
> > -                       "-0.173648177666930",  /* x2 */
> > -                       "0",                   /* y2 */
> > -                       "0.984807753012208";   /* z2 */
> > -};
> > diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml
> > new file mode 100644
> > index 000000000000..86e3efa693a8
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml
> > @@ -0,0 +1,66 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/magnetometer/ak8975.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: AsahiKASEI AK8975 magnetometer sensor
> > +
> > +maintainers:
> > +  - can't find a mantainer, author is Laxman Dewangan <ldewangan@nvidia.com>
> 
> Should probably add someone here, although I'm not sure who either.
> 

Yep I couldn't find a maintainer for that driver..what to do in this case?

> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - "asahi-kasei,ak8975"
> > +      - "ak8975"
> > +      - "asahi-kasei,ak8963"
> > +      - "ak8963"
> > +      - "asahi-kasei,ak09911"
> > +      - "ak09911"
> > +      - "asahi-kasei,ak09912"
> > +      - "ak09912"
> > +
> 
> I wonder if the ones without vendor prefix (asahi-kasei,) should be
> marked as deprecated somehow?
> 
> Looking at some other schemas I see either a "# deprecated" comment, or:
> 
> properties:
>   compatible:
>     oneOf:
>       - const: asahi-kasei,ak8975
>       - const: asahi-kasei,ak8963
>       - const: asahi-kasei,ak09911
>       - const: asahi-kasei,ak09912
>       - const: ak8975
>         deprecated: true
>       - const: ak8963
>         deprecated: true
>       - const: ak09911
>         deprecated: true
>       - const: ak09912
>         deprecated: true
> 
> (e.g. in Documentation/devicetree/bindings/sound/samsung,odroid.yaml)
> I guess this one is preferred since it allows parsing those
> compatibles as deprecated?
> 

Ok I'll work on it

> > +  reg:
> > +    maxItems: 1
> > +    description: the I2C address of the magnetometer
> > +
> > +  gpios:
> > +    description: should be device tree identifier of the magnetometer DRDY pin
> > +
> > +  vdd-supply:
> > +    maxItems: 1
> > +    description: |
> > +      an optional regulator that needs to be on to provide VDD power to
> > +      the sensor.
> > +
> > +  mount-matrix:
> > +    description: an optional 3x3 mounting rotation matrix
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +
> > +examples:
> > +  - |
> > +    i2c@78b7000 {
> > +        reg = <0x78b6000 0x600>;
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        ak8975@c {
> 
> Per device tree specification this should preferably use a generic name
> describing the function of the device, i.e. magnetometer@c.
> 
> > +            compatible = "asahi-kasei,ak8975";
> > +            reg = <0x0c>;
> > +            gpios = <&gpj0 7 0>;
>

Yes it would be better, I'll work on that too
 
> I think using the dt-bindings constants for the GPIO flags is preferred
> now, i.e. gpios = <&gpj0 7 GPIO_ACTIVE_HIGH>.
> 
> > +            vdd-supply = <&ldo_3v3_gnss>;
> > +            mount-matrix = "-0.984807753012208",  /* x0 */
> > +                           "0",                   /* y0 */
> > +                           "-0.173648177666930",  /* z0 */
> > +                           "0",                   /* x1 */
> > +                           "-1",                  /* y1 */
> > +                           "0",                   /* z1 */
> > +                           "-0.173648177666930",  /* x2 */
> > +                           "0",                   /* y2 */
> > +                           "0.984807753012208";   /* z2 */
> > +        };
> > +    };
> > -- 
> > 2.17.1

Thank you for having took the time to review, will work on edits right now.
I just have a question: by creating the new patchset how can I deal with
the "Reviewed by"? It's the first patch I submit and still haven't dealt
with the full process,

Best regards,
Jonathan Albrieux
Andy Shevchenko May 19, 2020, 4:01 p.m. UTC | #3
On Tue, May 19, 2020 at 04:03:54PM +0200, Jonathan Albrieux wrote:
> On Tue, May 19, 2020 at 03:22:07PM +0200, Stephan Gerhold wrote:
> > On Tue, May 19, 2020 at 02:43:51PM +0200, Jonathan Albrieux wrote:

...

> > > +maintainers:
> > > +  - can't find a mantainer, author is Laxman Dewangan <ldewangan@nvidia.com>
> > 
> > Should probably add someone here, although I'm not sure who either.
> > 
> 
> Yep I couldn't find a maintainer for that driver..what to do in this case?

Volunteer yourself!
Jonathan Albrieux May 19, 2020, 4:44 p.m. UTC | #4
On Tue, May 19, 2020 at 07:01:37PM +0300, Andy Shevchenko wrote:
> On Tue, May 19, 2020 at 04:03:54PM +0200, Jonathan Albrieux wrote:
> > On Tue, May 19, 2020 at 03:22:07PM +0200, Stephan Gerhold wrote:
> > > On Tue, May 19, 2020 at 02:43:51PM +0200, Jonathan Albrieux wrote:
> 
> ...
> 
> > > > +maintainers:
> > > > +  - can't find a mantainer, author is Laxman Dewangan <ldewangan@nvidia.com>
> > > 
> > > Should probably add someone here, although I'm not sure who either.
> > > 
> > 
> > Yep I couldn't find a maintainer for that driver..what to do in this case?
> 
> Volunteer yourself!
> 

While I'd really like to, I have to decline the offer as I currently don't have
enought knowledge to become a maintainer :-) but thank you! (Who knows, maybe in
a couple of year!) Now I'll make the final edits and will submit a new
patchset soon with all the changes

> -- 
> With Best Regards,
> Andy Shevchenko
> 
> 

Best regards,
Jonathan Albrieux
Jonathan Cameron May 19, 2020, 5:37 p.m. UTC | #5
On Tue, 19 May 2020 18:44:33 +0200
Jonathan Albrieux <jonathan.albrieux@gmail.com> wrote:

> On Tue, May 19, 2020 at 07:01:37PM +0300, Andy Shevchenko wrote:
> > On Tue, May 19, 2020 at 04:03:54PM +0200, Jonathan Albrieux wrote:  
> > > On Tue, May 19, 2020 at 03:22:07PM +0200, Stephan Gerhold wrote:  
> > > > On Tue, May 19, 2020 at 02:43:51PM +0200, Jonathan Albrieux wrote:  
> > 
> > ...
> >   
> > > > > +maintainers:
> > > > > +  - can't find a mantainer, author is Laxman Dewangan <ldewangan@nvidia.com>  
> > > > 
> > > > Should probably add someone here, although I'm not sure who either.
> > > >   
> > > 
> > > Yep I couldn't find a maintainer for that driver..what to do in this case?  
> > 
> > Volunteer yourself!
> >   
> 
> While I'd really like to, I have to decline the offer as I currently don't have
> enought knowledge to become a maintainer :-) but thank you! (Who knows, maybe in
> a couple of year!) Now I'll make the final edits and will submit a new
> patchset soon with all the changes

Don't be so hard on yourself.  We all get thrown in at the deep end :)

Note that being a driver maintainer (or even just the binding) really
just means you get cc'd on the patches and I'll make sure you've had time
to review them if you wish.   Best of all, if you have hardware (and time)
being able to test them, that is extremely useful (whether you are
maintaining the driver or not!) 

I closely review the majority of stuff that comes through IIO and in
the case of bindings we also have Rob and co. doing an amazing job.
We have some excellent additional reviewers who review IIO stuff all the
time, some of which have reviewed your patch I see.  Without them I'd
never survive the deluge.

Of course it's entirely your decision, but I'd definitely encourage you
to give it a go.

Thanks,

Jonathan




> 
> > -- 
> > With Best Regards,
> > Andy Shevchenko
> > 
> >   
> 
> Best regards,
> Jonathan Albrieux
Jonathan Albrieux May 20, 2020, 6:56 a.m. UTC | #6
On Tue, May 19, 2020 at 06:37:05PM +0100, Jonathan Cameron wrote:
> On Tue, 19 May 2020 18:44:33 +0200
> Jonathan Albrieux <jonathan.albrieux@gmail.com> wrote:
> 
> > On Tue, May 19, 2020 at 07:01:37PM +0300, Andy Shevchenko wrote:
> > > On Tue, May 19, 2020 at 04:03:54PM +0200, Jonathan Albrieux wrote:  
> > > > On Tue, May 19, 2020 at 03:22:07PM +0200, Stephan Gerhold wrote:  
> > > > > On Tue, May 19, 2020 at 02:43:51PM +0200, Jonathan Albrieux wrote:  
> > > 
> > > ...
> > >   
> > > > > > +maintainers:
> > > > > > +  - can't find a mantainer, author is Laxman Dewangan <ldewangan@nvidia.com>  
> > > > > 
> > > > > Should probably add someone here, although I'm not sure who either.
> > > > >   
> > > > 
> > > > Yep I couldn't find a maintainer for that driver..what to do in this case?  
> > > 
> > > Volunteer yourself!
> > >   
> > 
> > While I'd really like to, I have to decline the offer as I currently don't have
> > enought knowledge to become a maintainer :-) but thank you! (Who knows, maybe in
> > a couple of year!) Now I'll make the final edits and will submit a new
> > patchset soon with all the changes
> 
> Don't be so hard on yourself.  We all get thrown in at the deep end :)
> 
> Note that being a driver maintainer (or even just the binding) really
> just means you get cc'd on the patches and I'll make sure you've had time
> to review them if you wish.   Best of all, if you have hardware (and time)
> being able to test them, that is extremely useful (whether you are
> maintaining the driver or not!) 
> 
> I closely review the majority of stuff that comes through IIO and in
> the case of bindings we also have Rob and co. doing an amazing job.
> We have some excellent additional reviewers who review IIO stuff all the
> time, some of which have reviewed your patch I see.  Without them I'd
> never survive the deluge.
> 
> Of course it's entirely your decision, but I'd definitely encourage you
> to give it a go.
> 
> Thanks,
> 
> Jonathan
> 

Thank you for your encouraging words and for the trust! As a tester I will
be very pleased to give an help on this hardware but as a maintainer I
could contribute little to nothing at the moment and I'm not being hard
with myself but currently I really have to focus on the basic concepts first
and I'm lucky enought to have willing people helping me to do so :-)

Accepting to become the maintainer after the first contribution let me feels
like I'm burning some foundamental stage. I really hope you understand!

> 
> 
> > 
> > > -- 
> > > With Best Regards,
> > > Andy Shevchenko
> > > 
> > >   
> > 
> > Best regards,
> > Jonathan Albrieux
> 
> 

Best regards,
Jonathan Albrieux
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
deleted file mode 100644
index aa67ceb0d4e0..000000000000
--- a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt
+++ /dev/null
@@ -1,30 +0,0 @@ 
-* AsahiKASEI AK8975 magnetometer sensor
-
-Required properties:
-
-  - compatible : should be "asahi-kasei,ak8975"
-  - reg : the I2C address of the magnetometer
-
-Optional properties:
-
-  - gpios : should be device tree identifier of the magnetometer DRDY pin
-  - vdd-supply: an optional regulator that needs to be on to provide VDD
-  - mount-matrix: an optional 3x3 mounting rotation matrix
-
-Example:
-
-ak8975@c {
-        compatible = "asahi-kasei,ak8975";
-        reg = <0x0c>;
-        gpios = <&gpj0 7 0>;
-        vdd-supply = <&ldo_3v3_gnss>;
-        mount-matrix = "-0.984807753012208",  /* x0 */
-                       "0",                   /* y0 */
-                       "-0.173648177666930",  /* z0 */
-                       "0",                   /* x1 */
-                       "-1",                  /* y1 */
-                       "0",                   /* z1 */
-                       "-0.173648177666930",  /* x2 */
-                       "0",                   /* y2 */
-                       "0.984807753012208";   /* z2 */
-};
diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml
new file mode 100644
index 000000000000..86e3efa693a8
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.yaml
@@ -0,0 +1,66 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/magnetometer/ak8975.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AsahiKASEI AK8975 magnetometer sensor
+
+maintainers:
+  - can't find a mantainer, author is Laxman Dewangan <ldewangan@nvidia.com>
+
+properties:
+  compatible:
+    enum:
+      - "asahi-kasei,ak8975"
+      - "ak8975"
+      - "asahi-kasei,ak8963"
+      - "ak8963"
+      - "asahi-kasei,ak09911"
+      - "ak09911"
+      - "asahi-kasei,ak09912"
+      - "ak09912"
+
+  reg:
+    maxItems: 1
+    description: the I2C address of the magnetometer
+
+  gpios:
+    description: should be device tree identifier of the magnetometer DRDY pin
+
+  vdd-supply:
+    maxItems: 1
+    description: |
+      an optional regulator that needs to be on to provide VDD power to
+      the sensor.
+
+  mount-matrix:
+    description: an optional 3x3 mounting rotation matrix
+
+required:
+  - compatible
+  - reg
+
+examples:
+  - |
+    i2c@78b7000 {
+        reg = <0x78b6000 0x600>;
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ak8975@c {
+            compatible = "asahi-kasei,ak8975";
+            reg = <0x0c>;
+            gpios = <&gpj0 7 0>;
+            vdd-supply = <&ldo_3v3_gnss>;
+            mount-matrix = "-0.984807753012208",  /* x0 */
+                           "0",                   /* y0 */
+                           "-0.173648177666930",  /* z0 */
+                           "0",                   /* x1 */
+                           "-1",                  /* y1 */
+                           "0",                   /* z1 */
+                           "-0.173648177666930",  /* x2 */
+                           "0",                   /* y2 */
+                           "0.984807753012208";   /* z2 */
+        };
+    };