diff mbox series

[v3,1/6] dt-bindings: can: sja1000: Convert to json-schema

Message ID 20220704075032.383700-2-biju.das.jz@bp.renesas.com (mailing list archive)
State Superseded
Delegated to: Netdev Maintainers
Headers show
Series Add support for RZ/N1 SJA1000 CAN controller | expand

Checks

Context Check Description
netdev/tree_selection success Guessed tree name to be net-next
netdev/fixes_present success Fixes tag not required for -next series
netdev/subject_prefix success Link
netdev/cover_letter success Series has a cover letter
netdev/patch_count success Link
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit fail Errors and warnings before: 5 this patch: 5
netdev/cc_maintainers success CCed 11 of 11 maintainers
netdev/build_clang success Errors and warnings before: 0 this patch: 0
netdev/module_param success Was 0 now: 0
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 0 this patch: 0
netdev/checkpatch warning WARNING: DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.rst WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0

Commit Message

Biju Das July 4, 2022, 7:50 a.m. UTC 
Convert the NXP SJA1000 CAN Controller Device Tree binding
documentation to json-schema.

Update the example to match reality.

Signed-off-by: Biju Das <biju.das.jz@bp.renesas.com>
---
v2->v3:
 * Added reg-io-width is a required property for technologic,sja1000
 * Removed enum type from nxp,tx-output-config and updated the description
   for combination of TX0 and TX1.
 * Updated the example
v1->v2:
 * Moved $ref: can-controller.yaml# to top along with if conditional to
   avoid multiple mapping issues with the if conditional in the subsequent
   patch.
---
 .../bindings/net/can/nxp,sja1000.yaml         | 103 ++++++++++++++++++
 .../devicetree/bindings/net/can/sja1000.txt   |  58 ----------
 2 files changed, 103 insertions(+), 58 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
 delete mode 100644 Documentation/devicetree/bindings/net/can/sja1000.txt

Comments

Krzysztof Kozlowski July 4, 2022, 8:46 a.m. UTC | #1 
On 04/07/2022 09:50, Biju Das wrote:
> Convert the NXP SJA1000 CAN Controller Device Tree binding
> documentation to json-schema.
> 
> Update the example to match reality.
> 
> Signed-off-by: Biju Das <biju.das.jz@bp.renesas.com>
> ---
> v2->v3:
>  * Added reg-io-width is a required property for technologic,sja1000
>  * Removed enum type from nxp,tx-output-config and updated the description
>    for combination of TX0 and TX1.
>  * Updated the example
> v1->v2:
>  * Moved $ref: can-controller.yaml# to top along with if conditional to
>    avoid multiple mapping issues with the if conditional in the subsequent
>    patch.
> ---
>  .../bindings/net/can/nxp,sja1000.yaml         | 103 ++++++++++++++++++
>  .../devicetree/bindings/net/can/sja1000.txt   |  58 ----------
>  2 files changed, 103 insertions(+), 58 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
>  delete mode 100644 Documentation/devicetree/bindings/net/can/sja1000.txt
> 
> diff --git a/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> new file mode 100644
> index 000000000000..d34060226e4e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> @@ -0,0 +1,103 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/can/nxp,sja1000.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Memory mapped SJA1000 CAN controller from NXP (formerly Philips)
> +
> +maintainers:
> +  - Wolfgang Grandegger <wg@grandegger.com>
> +
> +allOf:
> +  - $ref: can-controller.yaml#
> +  - if:

The advice of moving it up was not correct. The allOf containing ref and
if:then goes to place like in example-schema, so before
additional/unevaluatedProperties at the bottom.

Please do not introduce some inconsistent style.

> +      properties:
> +        compatible:
> +          contains:
> +            const: technologic,sja1000
> +    then:
> +      required:
> +        - reg-io-width
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - description: NXP SJA1000 CAN Controller
> +        const: nxp,sja1000
> +      - description: Technologic Systems SJA1000 CAN Controller
> +        const: technologic,sja1000

Entire entry should be just enum. Descriptions do not bring any
information - they copy compatible.

> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  reg-io-width:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: I/O register width (in bytes) implemented by this device
> +    default: 1
> +    enum: [ 1, 2, 4 ]
> +
> +  nxp,external-clock-frequency:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    default: 16000000
> +    description: |
> +      Frequency of the external oscillator clock in Hz.
> +      The internal clock frequency used by the SJA1000 is half of that value.
> +
> +  nxp,tx-output-mode:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1, 2, 3 ]
> +    default: 1
> +    description: |
> +      operation mode of the TX output control logic. Valid values are:
> +        <0x0> : bi-phase output mode
> +        <0x1> : normal output mode (default)
> +        <0x2> : test output mode
> +        <0x3> : clock output mode

Use decimal values, just like in enum.

> +
> +  nxp,tx-output-config:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    default: 0x02
> +    description: |
> +      TX output pin configuration. Valid values are any one of the below
> +      or combination of TX0 and TX1:
> +        <0x01> : TX0 invert
> +        <0x02> : TX0 pull-down (default)
> +        <0x04> : TX0 pull-up
> +        <0x06> : TX0 push-pull
> +        <0x08> : TX1 invert
> +        <0x10> : TX1 pull-down
> +        <0x20> : TX1 pull-up
> +        <0x30> : TX1 push-pull
> +
> +  nxp,clock-out-frequency:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: |
> +      clock frequency in Hz on the CLKOUT pin.
> +      If not specified or if the specified value is 0, the CLKOUT pin
> +      will be disabled.
> +
> +  nxp,no-comparator-bypass:
> +    type: boolean
> +    description: Allows to disable the CAN input comparator.
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    can@1a000 {
> +            compatible = "technologic,sja1000";

Unusual indentation. Use 4 spaces for the DTS example.

> +            reg = <0x1a000 0x100>;
> +            interrupts = <1>;
> +            reg-io-width = <2>;
> +            nxp,tx-output-config = <0x06>;
> +            nxp,external-clock-frequency = <24000000>;
> +    };
> diff --git a/Documentation/devicetree/bindings/net/can/sja1000.txt b/Documentation/devicetree/bindings/net/can/sja1000.txt
> deleted file mode 100644
> index ac3160eca96a..000000000000
> --- a/Documentation/devicetree/bindings/net/can/sja1000.txt
> +++ /dev/null
> @@ -1,58 +0,0 @@
> -Memory mapped SJA1000 CAN controller from NXP (formerly Philips)
> -
> -Required properties:
> -
> -- compatible : should be one of "nxp,sja1000", "technologic,sja1000".
> -
> -- reg : should specify the chip select, address offset and size required
> -	to map the registers of the SJA1000. The size is usually 0x80.
> -
> -- interrupts: property with a value describing the interrupt source
> -	(number and sensitivity) required for the SJA1000.
> -
> -Optional properties:
> -
> -- reg-io-width : Specify the size (in bytes) of the IO accesses that
> -	should be performed on the device.  Valid value is 1, 2 or 4.
> -	This property is ignored for technologic version.
> -	Default to 1 (8 bits).
> -
> -- nxp,external-clock-frequency : Frequency of the external oscillator
> -	clock in Hz. Note that the internal clock frequency used by the
> -	SJA1000 is half of that value. If not specified, a default value
> -	of 16000000 (16 MHz) is used.
> -
> -- nxp,tx-output-mode : operation mode of the TX output control logic:
> -	<0x0> : bi-phase output mode
> -	<0x1> : normal output mode (default)
> -	<0x2> : test output mode
> -	<0x3> : clock output mode
> -
> -- nxp,tx-output-config : TX output pin configuration:
> -	<0x01> : TX0 invert
> -	<0x02> : TX0 pull-down (default)
> -	<0x04> : TX0 pull-up
> -	<0x06> : TX0 push-pull
> -	<0x08> : TX1 invert
> -	<0x10> : TX1 pull-down
> -	<0x20> : TX1 pull-up
> -	<0x30> : TX1 push-pull
> -
> -- nxp,clock-out-frequency : clock frequency in Hz on the CLKOUT pin.
> -	If not specified or if the specified value is 0, the CLKOUT pin
> -	will be disabled.
> -
> -- nxp,no-comparator-bypass : Allows to disable the CAN input comparator.
> -
> -For further information, please have a look to the SJA1000 data sheet.
> -
> -Examples:
> -
> -can@3,100 {
> -	compatible = "nxp,sja1000";
> -	reg = <3 0x100 0x80>;
> -	interrupts = <2 0>;
> -	interrupt-parent = <&mpic>;
> -	nxp,external-clock-frequency = <16000000>;
> -};
> -


Best regards,
Krzysztof
Biju Das July 4, 2022, 9:03 a.m. UTC | #2 
Hi Krystof,

Thanks for the feedback.

> Subject: Re: [PATCH v3 1/6] dt-bindings: can: sja1000: Convert to json-
> schema
> 
> On 04/07/2022 09:50, Biju Das wrote:
> > Convert the NXP SJA1000 CAN Controller Device Tree binding
> > documentation to json-schema.
> >
> > Update the example to match reality.
> >
> > Signed-off-by: Biju Das <biju.das.jz@bp.renesas.com>
> > ---
> > v2->v3:
> >  * Added reg-io-width is a required property for technologic,sja1000
> >  * Removed enum type from nxp,tx-output-config and updated the
> description
> >    for combination of TX0 and TX1.
> >  * Updated the example
> > v1->v2:
> >  * Moved $ref: can-controller.yaml# to top along with if conditional
> > to
> >    avoid multiple mapping issues with the if conditional in the
> subsequent
> >    patch.
> > ---
> >  .../bindings/net/can/nxp,sja1000.yaml         | 103 ++++++++++++++++++
> >  .../devicetree/bindings/net/can/sja1000.txt   |  58 ----------
> >  2 files changed, 103 insertions(+), 58 deletions(-)  create mode
> > 100644 Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> >  delete mode 100644
> > Documentation/devicetree/bindings/net/can/sja1000.txt
> >
> > diff --git
> > a/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> > b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> > new file mode 100644
> > index 000000000000..d34060226e4e
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> > @@ -0,0 +1,103 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2
> > +---
> > +$id:
> > +
> > +title: Memory mapped SJA1000 CAN controller from NXP (formerly
> > +Philips)
> > +
> > +maintainers:
> > +  - Wolfgang Grandegger <wg@grandegger.com>
> > +
> > +allOf:
> > +  - $ref: can-controller.yaml#
> > +  - if:
> 
> The advice of moving it up was not correct. The allOf containing ref and
> if:then goes to place like in example-schema, so before
> additional/unevaluatedProperties at the bottom.
> 
> Please do not introduce some inconsistent style.

There are some examples like[1], where allOf is at the top.
[1] https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/tree/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml?h=next-20220704

Marc, please let us know, if you still prefer allOf at the top.

> 
> > +      properties:
> > +        compatible:
> > +          contains:
> > +            const: technologic,sja1000
> > +    then:
> > +      required:
> > +        - reg-io-width
> > +
> > +properties:
> > +  compatible:
> > +    oneOf:
> > +      - description: NXP SJA1000 CAN Controller
> > +        const: nxp,sja1000
> > +      - description: Technologic Systems SJA1000 CAN Controller
> > +        const: technologic,sja1000
> 
> Entire entry should be just enum. Descriptions do not bring any
> information - they copy compatible.

OK, I will remove description and will use enum.

> 
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  reg-io-width:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description: I/O register width (in bytes) implemented by this
> device
> > +    default: 1
> > +    enum: [ 1, 2, 4 ]
> > +
> > +  nxp,external-clock-frequency:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    default: 16000000
> > +    description: |
> > +      Frequency of the external oscillator clock in Hz.
> > +      The internal clock frequency used by the SJA1000 is half of that
> value.
> > +
> > +  nxp,tx-output-mode:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    enum: [ 0, 1, 2, 3 ]
> > +    default: 1
> > +    description: |
> > +      operation mode of the TX output control logic. Valid values are:
> > +        <0x0> : bi-phase output mode
> > +        <0x1> : normal output mode (default)
> > +        <0x2> : test output mode
> > +        <0x3> : clock output mode
> 
> Use decimal values, just like in enum.

OK.

> 
> > +
> > +  nxp,tx-output-config:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    default: 0x02
> > +    description: |
> > +      TX output pin configuration. Valid values are any one of the
> below
> > +      or combination of TX0 and TX1:
> > +        <0x01> : TX0 invert
> > +        <0x02> : TX0 pull-down (default)
> > +        <0x04> : TX0 pull-up
> > +        <0x06> : TX0 push-pull
> > +        <0x08> : TX1 invert
> > +        <0x10> : TX1 pull-down
> > +        <0x20> : TX1 pull-up
> > +        <0x30> : TX1 push-pull
> > +
> > +  nxp,clock-out-frequency:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description: |
> > +      clock frequency in Hz on the CLKOUT pin.
> > +      If not specified or if the specified value is 0, the CLKOUT pin
> > +      will be disabled.
> > +
> > +  nxp,no-comparator-bypass:
> > +    type: boolean
> > +    description: Allows to disable the CAN input comparator.
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - interrupts
> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > +  - |
> > +    can@1a000 {
> > +            compatible = "technologic,sja1000";
> 
> Unusual indentation. Use 4 spaces for the DTS example.

OK, Will do.

Cheers,
Biju

> 
> > +            reg = <0x1a000 0x100>;
> > +            interrupts = <1>;
> > +            reg-io-width = <2>;
> > +            nxp,tx-output-config = <0x06>;
> > +            nxp,external-clock-frequency = <24000000>;
> > +    };
> > diff --git a/Documentation/devicetree/bindings/net/can/sja1000.txt
> > b/Documentation/devicetree/bindings/net/can/sja1000.txt
> > deleted file mode 100644
> > index ac3160eca96a..000000000000
> > --- a/Documentation/devicetree/bindings/net/can/sja1000.txt
> > +++ /dev/null
> > @@ -1,58 +0,0 @@
> > -Memory mapped SJA1000 CAN controller from NXP (formerly Philips)
> > -
> > -Required properties:
> > -
> > -- compatible : should be one of "nxp,sja1000", "technologic,sja1000".
> > -
> > -- reg : should specify the chip select, address offset and size
> required
> > -	to map the registers of the SJA1000. The size is usually 0x80.
> > -
> > -- interrupts: property with a value describing the interrupt source
> > -	(number and sensitivity) required for the SJA1000.
> > -
> > -Optional properties:
> > -
> > -- reg-io-width : Specify the size (in bytes) of the IO accesses that
> > -	should be performed on the device.  Valid value is 1, 2 or 4.
> > -	This property is ignored for technologic version.
> > -	Default to 1 (8 bits).
> > -
> > -- nxp,external-clock-frequency : Frequency of the external oscillator
> > -	clock in Hz. Note that the internal clock frequency used by the
> > -	SJA1000 is half of that value. If not specified, a default value
> > -	of 16000000 (16 MHz) is used.
> > -
> > -- nxp,tx-output-mode : operation mode of the TX output control logic:
> > -	<0x0> : bi-phase output mode
> > -	<0x1> : normal output mode (default)
> > -	<0x2> : test output mode
> > -	<0x3> : clock output mode
> > -
> > -- nxp,tx-output-config : TX output pin configuration:
> > -	<0x01> : TX0 invert
> > -	<0x02> : TX0 pull-down (default)
> > -	<0x04> : TX0 pull-up
> > -	<0x06> : TX0 push-pull
> > -	<0x08> : TX1 invert
> > -	<0x10> : TX1 pull-down
> > -	<0x20> : TX1 pull-up
> > -	<0x30> : TX1 push-pull
> > -
> > -- nxp,clock-out-frequency : clock frequency in Hz on the CLKOUT pin.
> > -	If not specified or if the specified value is 0, the CLKOUT pin
> > -	will be disabled.
> > -
> > -- nxp,no-comparator-bypass : Allows to disable the CAN input
> comparator.
> > -
> > -For further information, please have a look to the SJA1000 data sheet.
> > -
> > -Examples:
> > -
> > -can@3,100 {
> > -	compatible = "nxp,sja1000";
> > -	reg = <3 0x100 0x80>;
> > -	interrupts = <2 0>;
> > -	interrupt-parent = <&mpic>;
> > -	nxp,external-clock-frequency = <16000000>;
> > -};
> > -
Krzysztof Kozlowski July 4, 2022, 9:08 a.m. UTC | #3 
On 04/07/2022 11:03, Biju Das wrote:
> Hi Krystof,
> 
> Thanks for the feedback.
> 
>> Subject: Re: [PATCH v3 1/6] dt-bindings: can: sja1000: Convert to json-
>> schema
>>
>> On 04/07/2022 09:50, Biju Das wrote:
>>> Convert the NXP SJA1000 CAN Controller Device Tree binding
>>> documentation to json-schema.
>>>
>>> Update the example to match reality.
>>>
>>> Signed-off-by: Biju Das <biju.das.jz@bp.renesas.com>
>>> ---
>>> v2->v3:
>>>  * Added reg-io-width is a required property for technologic,sja1000
>>>  * Removed enum type from nxp,tx-output-config and updated the
>> description
>>>    for combination of TX0 and TX1.
>>>  * Updated the example
>>> v1->v2:
>>>  * Moved $ref: can-controller.yaml# to top along with if conditional
>>> to
>>>    avoid multiple mapping issues with the if conditional in the
>> subsequent
>>>    patch.
>>> ---
>>>  .../bindings/net/can/nxp,sja1000.yaml         | 103 ++++++++++++++++++
>>>  .../devicetree/bindings/net/can/sja1000.txt   |  58 ----------
>>>  2 files changed, 103 insertions(+), 58 deletions(-)  create mode
>>> 100644 Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
>>>  delete mode 100644
>>> Documentation/devicetree/bindings/net/can/sja1000.txt
>>>
>>> diff --git
>>> a/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
>>> b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
>>> new file mode 100644
>>> index 000000000000..d34060226e4e
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
>>> @@ -0,0 +1,103 @@
>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2
>>> +---
>>> +$id:
>>> +
>>> +title: Memory mapped SJA1000 CAN controller from NXP (formerly
>>> +Philips)
>>> +
>>> +maintainers:
>>> +  - Wolfgang Grandegger <wg@grandegger.com>
>>> +
>>> +allOf:
>>> +  - $ref: can-controller.yaml#
>>> +  - if:
>>
>> The advice of moving it up was not correct. The allOf containing ref and
>> if:then goes to place like in example-schema, so before
>> additional/unevaluatedProperties at the bottom.
>>
>> Please do not introduce some inconsistent style.
> 
> There are some examples like[1], where allOf is at the top.
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/tree/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml?h=next-20220704

And they are wrong. There is always some incorrect code in the kernel,
but that's not argument to do it in incorrect way. The coding style is
here expressed in example-schema, so use this as an argument.

> 
> Marc, please let us know, if you still prefer allOf at the top.
> 
>>


Best regards,
Krzysztof
Biju Das July 4, 2022, 9:26 a.m. UTC | #4 
Hi Krzysztof,

Thanks for the feedback.

> Subject: Re: [PATCH v3 1/6] dt-bindings: can: sja1000: Convert to json-
> schema
> 
> On 04/07/2022 11:03, Biju Das wrote:
> > Hi Krystof,
> >
> > Thanks for the feedback.
> >
> >> Subject: Re: [PATCH v3 1/6] dt-bindings: can: sja1000: Convert to
> >> json- schema
> >>
> >> On 04/07/2022 09:50, Biju Das wrote:
> >>> Convert the NXP SJA1000 CAN Controller Device Tree binding
> >>> documentation to json-schema.
> >>>
> >>> Update the example to match reality.
> >>>
> >>> Signed-off-by: Biju Das <biju.das.jz@bp.renesas.com>
> >>> ---
> >>> v2->v3:
> >>>  * Added reg-io-width is a required property for technologic,sja1000
> >>>  * Removed enum type from nxp,tx-output-config and updated the
> >> description
> >>>    for combination of TX0 and TX1.
> >>>  * Updated the example
> >>> v1->v2:
> >>>  * Moved $ref: can-controller.yaml# to top along with if conditional
> >>> to
> >>>    avoid multiple mapping issues with the if conditional in the
> >> subsequent
> >>>    patch.
> >>> ---
> >>>  .../bindings/net/can/nxp,sja1000.yaml         | 103
> ++++++++++++++++++
> >>>  .../devicetree/bindings/net/can/sja1000.txt   |  58 ----------
> >>>  2 files changed, 103 insertions(+), 58 deletions(-)  create mode
> >>> 100644 Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> >>>  delete mode 100644
> >>> Documentation/devicetree/bindings/net/can/sja1000.txt
> >>>
> >>> diff --git
> >>> a/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> >>> b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> >>> new file mode 100644
> >>> index 000000000000..d34060226e4e
> >>> --- /dev/null
> >>> +++ b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
> >>> @@ -0,0 +1,103 @@
> >>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2
> >>> +---
> >>> +$id:
> >>> +
> >>> +title: Memory mapped SJA1000 CAN controller from NXP (formerly
> >>> +Philips)
> >>> +
> >>> +maintainers:
> >>> +  - Wolfgang Grandegger <wg@grandegger.com>
> >>> +
> >>> +allOf:
> >>> +  - $ref: can-controller.yaml#
> >>> +  - if:
> >>
> >> The advice of moving it up was not correct. The allOf containing ref
> >> and if:then goes to place like in example-schema, so before
> >> additional/unevaluatedProperties at the bottom.
> >>
> >> Please do not introduce some inconsistent style.
> >
> > There are some examples like[1], where allOf is at the top.
> > [1]
=Mw4Fhkri5BLK1Cqg8Wd1EKkbe0xDg%2Fnbl0JSd5j6Kmo%3D&amp;reser
> > ved=0
> 
> And they are wrong. There is always some incorrect code in the kernel,
> but that's not argument to do it in incorrect way. The coding style is
> here expressed in example-schema, so use this as an argument.

OK. Will stick to example-schema as coding style.

Cheers,
Biju
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
new file mode 100644
index 000000000000..d34060226e4e
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/can/nxp,sja1000.yaml
@@ -0,0 +1,103 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/can/nxp,sja1000.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Memory mapped SJA1000 CAN controller from NXP (formerly Philips)
+
+maintainers:
+  - Wolfgang Grandegger <wg@grandegger.com>
+
+allOf:
+  - $ref: can-controller.yaml#
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: technologic,sja1000
+    then:
+      required:
+        - reg-io-width
+
+properties:
+  compatible:
+    oneOf:
+      - description: NXP SJA1000 CAN Controller
+        const: nxp,sja1000
+      - description: Technologic Systems SJA1000 CAN Controller
+        const: technologic,sja1000
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  reg-io-width:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: I/O register width (in bytes) implemented by this device
+    default: 1
+    enum: [ 1, 2, 4 ]
+
+  nxp,external-clock-frequency:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    default: 16000000
+    description: |
+      Frequency of the external oscillator clock in Hz.
+      The internal clock frequency used by the SJA1000 is half of that value.
+
+  nxp,tx-output-mode:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1, 2, 3 ]
+    default: 1
+    description: |
+      operation mode of the TX output control logic. Valid values are:
+        <0x0> : bi-phase output mode
+        <0x1> : normal output mode (default)
+        <0x2> : test output mode
+        <0x3> : clock output mode
+
+  nxp,tx-output-config:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    default: 0x02
+    description: |
+      TX output pin configuration. Valid values are any one of the below
+      or combination of TX0 and TX1:
+        <0x01> : TX0 invert
+        <0x02> : TX0 pull-down (default)
+        <0x04> : TX0 pull-up
+        <0x06> : TX0 push-pull
+        <0x08> : TX1 invert
+        <0x10> : TX1 pull-down
+        <0x20> : TX1 pull-up
+        <0x30> : TX1 push-pull
+
+  nxp,clock-out-frequency:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: |
+      clock frequency in Hz on the CLKOUT pin.
+      If not specified or if the specified value is 0, the CLKOUT pin
+      will be disabled.
+
+  nxp,no-comparator-bypass:
+    type: boolean
+    description: Allows to disable the CAN input comparator.
+
+required:
+  - compatible
+  - reg
+  - interrupts
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    can@1a000 {
+            compatible = "technologic,sja1000";
+            reg = <0x1a000 0x100>;
+            interrupts = <1>;
+            reg-io-width = <2>;
+            nxp,tx-output-config = <0x06>;
+            nxp,external-clock-frequency = <24000000>;
+    };
diff --git a/Documentation/devicetree/bindings/net/can/sja1000.txt b/Documentation/devicetree/bindings/net/can/sja1000.txt
deleted file mode 100644
index ac3160eca96a..000000000000
--- a/Documentation/devicetree/bindings/net/can/sja1000.txt
+++ /dev/null
@@ -1,58 +0,0 @@ 
-Memory mapped SJA1000 CAN controller from NXP (formerly Philips)
-
-Required properties:
-
-- compatible : should be one of "nxp,sja1000", "technologic,sja1000".
-
-- reg : should specify the chip select, address offset and size required
-	to map the registers of the SJA1000. The size is usually 0x80.
-
-- interrupts: property with a value describing the interrupt source
-	(number and sensitivity) required for the SJA1000.
-
-Optional properties:
-
-- reg-io-width : Specify the size (in bytes) of the IO accesses that
-	should be performed on the device.  Valid value is 1, 2 or 4.
-	This property is ignored for technologic version.
-	Default to 1 (8 bits).
-
-- nxp,external-clock-frequency : Frequency of the external oscillator
-	clock in Hz. Note that the internal clock frequency used by the
-	SJA1000 is half of that value. If not specified, a default value
-	of 16000000 (16 MHz) is used.
-
-- nxp,tx-output-mode : operation mode of the TX output control logic:
-	<0x0> : bi-phase output mode
-	<0x1> : normal output mode (default)
-	<0x2> : test output mode
-	<0x3> : clock output mode
-
-- nxp,tx-output-config : TX output pin configuration:
-	<0x01> : TX0 invert
-	<0x02> : TX0 pull-down (default)
-	<0x04> : TX0 pull-up
-	<0x06> : TX0 push-pull
-	<0x08> : TX1 invert
-	<0x10> : TX1 pull-down
-	<0x20> : TX1 pull-up
-	<0x30> : TX1 push-pull
-
-- nxp,clock-out-frequency : clock frequency in Hz on the CLKOUT pin.
-	If not specified or if the specified value is 0, the CLKOUT pin
-	will be disabled.
-
-- nxp,no-comparator-bypass : Allows to disable the CAN input comparator.
-
-For further information, please have a look to the SJA1000 data sheet.
-
-Examples:
-
-can@3,100 {
-	compatible = "nxp,sja1000";
-	reg = <3 0x100 0x80>;
-	interrupts = <2 0>;
-	interrupt-parent = <&mpic>;
-	nxp,external-clock-frequency = <16000000>;
-};
-