diff mbox series

[2/3] dt-bindings: SPI: Add Ingenic SFC bindings.

Message ID 1658508510-15400-3-git-send-email-zhouyanjie@wanyeetech.com (mailing list archive)
State Handled Elsewhere
Headers show
Series Add SFC support for Ingenic SoCs. | expand

Commit Message

Zhou Yanjie July 22, 2022, 4:48 p.m. UTC
Add the SFC bindings for the X1000 SoC, the X1600 SoC, the X1830 SoC,
and the X2000 SoC from Ingenic.

Signed-off-by: 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
---
 .../devicetree/bindings/spi/ingenic,sfc.yaml       | 64 ++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/spi/ingenic,sfc.yaml

Comments

Krzysztof Kozlowski July 22, 2022, 5:46 p.m. UTC | #1
On 22/07/2022 18:48, 周琰杰 (Zhou Yanjie) wrote:
> Add the SFC bindings for the X1000 SoC, the X1600 SoC, the X1830 SoC,
> and the X2000 SoC from Ingenic.
> 
> Signed-off-by: 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
> ---
>  .../devicetree/bindings/spi/ingenic,sfc.yaml       | 64 ++++++++++++++++++++++
>  1 file changed, 64 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
> new file mode 100644
> index 00000000..b7c4cf4
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
> @@ -0,0 +1,64 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/spi/ingenic,sfc.yaml#

File name should be rather based on first compatible, so
ingenic,x1000-sfc.yaml

> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Bindings for SFC in Ingenic SoCs
> +
> +maintainers:
> +  - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
> +
> +description:
> +  The SPI Flash Controller in Ingenic SoCs.
> +

You miss here allOf referencing spi-controller.

> +properties:
> +  compatible:
> +    oneOf:
> +      - enum:
> +          - ingenic,x1000-sfc
> +          - ingenic,x1600-sfc
> +          - ingenic,x2000-sfc
> +      - items:
> +          - enum:
> +              - ingenic,x1830-sfc
> +          - const: ingenic,x1000-sfc
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: sfc

Remove the clock-names entirely, no benefits.

> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/ingenic,x1000-cgu.h>
> +
> +	sfc: spi@13440000 {
> +		compatible = "ingenic,x1000-sfc";


Use 4 spaces for example indentation.

> +		reg = <0x13440000 0x1000>;
> +
> +		interrupt-parent = <&intc>;
> +		interrupts = <7>;
> +
> +		clocks = <&cgu X1000_CLK_SFC>;
> +		clock-names = "sfc";
> +
> +		status = "disabled";

No status in example.

> +	};
> +...


Best regards,
Krzysztof
Rob Herring (Arm) July 22, 2022, 10:44 p.m. UTC | #2
On Sat, 23 Jul 2022 00:48:29 +0800, 周琰杰 (Zhou Yanjie) wrote:
> Add the SFC bindings for the X1000 SoC, the X1600 SoC, the X1830 SoC,
> and the X2000 SoC from Ingenic.
> 
> Signed-off-by: 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
> ---
>  .../devicetree/bindings/spi/ingenic,sfc.yaml       | 64 ++++++++++++++++++++++
>  1 file changed, 64 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:
./Documentation/devicetree/bindings/spi/ingenic,sfc.yaml:52:1: [error] syntax error: found character '\t' that cannot start any token (syntax)

dtschema/dtc warnings/errors:
make[1]: *** Deleting file 'Documentation/devicetree/bindings/spi/ingenic,sfc.example.dts'
Documentation/devicetree/bindings/spi/ingenic,sfc.yaml:52:1: found a tab character where an indentation space is expected
make[1]: *** [Documentation/devicetree/bindings/Makefile:26: Documentation/devicetree/bindings/spi/ingenic,sfc.example.dts] Error 1
make[1]: *** Waiting for unfinished jobs....
./Documentation/devicetree/bindings/spi/ingenic,sfc.yaml:52:1: found a tab character where an indentation space is expected
/builds/robherring/linux-dt-review/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml: ignoring, error parsing file
make: *** [Makefile:1404: dt_binding_check] Error 2

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.
Zhou Yanjie July 23, 2022, 4:50 p.m. UTC | #3
Hi Krzysztof,

On 2022/7/23 上午1:46, Krzysztof Kozlowski wrote:
> On 22/07/2022 18:48, 周琰杰 (Zhou Yanjie) wrote:
>> Add the SFC bindings for the X1000 SoC, the X1600 SoC, the X1830 SoC,
>> and the X2000 SoC from Ingenic.
>>
>> Signed-off-by: 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
>> ---
>>   .../devicetree/bindings/spi/ingenic,sfc.yaml       | 64 ++++++++++++++++++++++
>>   1 file changed, 64 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>> new file mode 100644
>> index 00000000..b7c4cf4
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>> @@ -0,0 +1,64 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/spi/ingenic,sfc.yaml#
> File name should be rather based on first compatible, so
> ingenic,x1000-sfc.yaml


No offense, does it really need to be named that way?
I can't seem to find documentation with instructions on this :(

The use of "ingenic,sfc.yaml" indicates that this is the documentation
for the SFC module for all Ingenic SoCs, without misleading people into
thinking it's only for a specific model of SoC. And there seem to be many
other yaml documents that use similar names (eg. fsl,spi-fsl-qspi.yaml,
spi-rockchip.yaml, spi-nxp-fspi.yaml, ingenic,spi.yaml, spi-sifive.yaml,
omap-spi.yaml), maybe these yaml files that are not named with first
compatible are also for the same consideration. :)


>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Bindings for SFC in Ingenic SoCs
>> +
>> +maintainers:
>> +  - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
>> +
>> +description:
>> +  The SPI Flash Controller in Ingenic SoCs.
>> +
> You miss here allOf referencing spi-controller.


Sure, will add it in the next version.


>> +properties:
>> +  compatible:
>> +    oneOf:
>> +      - enum:
>> +          - ingenic,x1000-sfc
>> +          - ingenic,x1600-sfc
>> +          - ingenic,x2000-sfc
>> +      - items:
>> +          - enum:
>> +              - ingenic,x1830-sfc
>> +          - const: ingenic,x1000-sfc
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  interrupts:
>> +    maxItems: 1
>> +
>> +  clocks:
>> +    maxItems: 1
>> +
>> +  clock-names:
>> +    const: sfc
> Remove the clock-names entirely, no benefits.


Sure.


>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +  - interrupts
>> +  - clocks
>> +  - clock-names
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    #include <dt-bindings/clock/ingenic,x1000-cgu.h>
>> +
>> +	sfc: spi@13440000 {
>> +		compatible = "ingenic,x1000-sfc";
>
> Use 4 spaces for example indentation.


My fault, will fix it in the next version.


>> +		reg = <0x13440000 0x1000>;
>> +
>> +		interrupt-parent = <&intc>;
>> +		interrupts = <7>;
>> +
>> +		clocks = <&cgu X1000_CLK_SFC>;
>> +		clock-names = "sfc";
>> +
>> +		status = "disabled";
> No status in example.


Sure, will remove it in the next version.


Thanks and beset regards!


>
>> +	};
>> +...
>
> Best regards,
> Krzysztof
Krzysztof Kozlowski July 23, 2022, 5:43 p.m. UTC | #4
On 23/07/2022 18:50, Zhou Yanjie wrote:
> Hi Krzysztof,
> 
> On 2022/7/23 上午1:46, Krzysztof Kozlowski wrote:
>> On 22/07/2022 18:48, 周琰杰 (Zhou Yanjie) wrote:
>>> Add the SFC bindings for the X1000 SoC, the X1600 SoC, the X1830 SoC,
>>> and the X2000 SoC from Ingenic.
>>>
>>> Signed-off-by: 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
>>> ---
>>>   .../devicetree/bindings/spi/ingenic,sfc.yaml       | 64 ++++++++++++++++++++++
>>>   1 file changed, 64 insertions(+)
>>>   create mode 100644 Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>
>>> diff --git a/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>> new file mode 100644
>>> index 00000000..b7c4cf4
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>> @@ -0,0 +1,64 @@
>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>>> +%YAML 1.2
>>> +---
>>> +$id: http://devicetree.org/schemas/spi/ingenic,sfc.yaml#
>> File name should be rather based on first compatible, so
>> ingenic,x1000-sfc.yaml
> 
> 
> No offense, does it really need to be named that way?
> I can't seem to find documentation with instructions on this :(
> 
> The use of "ingenic,sfc.yaml" indicates that this is the documentation
> for the SFC module for all Ingenic SoCs, without misleading people into
> thinking it's only for a specific model of SoC. And there seem to be many
> other yaml documents that use similar names (eg. fsl,spi-fsl-qspi.yaml,
> spi-rockchip.yaml, spi-nxp-fspi.yaml, ingenic,spi.yaml, spi-sifive.yaml,
> omap-spi.yaml), maybe these yaml files that are not named with first
> compatible are also for the same consideration. :)

We have many bad examples, many poor patterns and they are never an
argument to add one more bad pattern.

It might never grow to new devices (because they might be different), so
that is not really an argument.

All bindings are to follow this rule, so I don't understand why you
think it is an exception for you?


Best regards,
Krzysztof
Mike Yang July 23, 2022, 6:47 p.m. UTC | #5
On 7/24/22 01:43, Krzysztof Kozlowski wrote:
> On 23/07/2022 18:50, Zhou Yanjie wrote:
>> Hi Krzysztof,
>>
>> On 2022/7/23 上午1:46, Krzysztof Kozlowski wrote:
>>> On 22/07/2022 18:48, 周琰杰 (Zhou Yanjie) wrote:
>>>> Add the SFC bindings for the X1000 SoC, the X1600 SoC, the X1830 SoC,
>>>> and the X2000 SoC from Ingenic.
>>>>
>>>> Signed-off-by: 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
>>>> ---
>>>>   .../devicetree/bindings/spi/ingenic,sfc.yaml       | 64 ++++++++++++++++++++++
>>>>   1 file changed, 64 insertions(+)
>>>>   create mode 100644 Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>> new file mode 100644
>>>> index 00000000..b7c4cf4
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>> @@ -0,0 +1,64 @@
>>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>>>> +%YAML 1.2
>>>> +---
>>>> +$id: http://devicetree.org/schemas/spi/ingenic,sfc.yaml#
>>> File name should be rather based on first compatible, so
>>> ingenic,x1000-sfc.yaml
>>
>>
>> No offense, does it really need to be named that way?
>> I can't seem to find documentation with instructions on this :(
>>
>> The use of "ingenic,sfc.yaml" indicates that this is the documentation
>> for the SFC module for all Ingenic SoCs, without misleading people into
>> thinking it's only for a specific model of SoC. And there seem to be many
>> other yaml documents that use similar names (eg. fsl,spi-fsl-qspi.yaml,
>> spi-rockchip.yaml, spi-nxp-fspi.yaml, ingenic,spi.yaml, spi-sifive.yaml,
>> omap-spi.yaml), maybe these yaml files that are not named with first
>> compatible are also for the same consideration. :)
> 
> We have many bad examples, many poor patterns and they are never an
> argument to add one more bad pattern.

Zhou already mentioned he was unable find the naming guidelines of these .yaml files.

Apparently you think it's unacceptable for new contributors of a certain subsystem to use existing code as examples, and/or they're responsible for figuring out what's a good example and what's a bad one in the existing codebase.

> 
> It might never grow to new devices (because they might be different), so
> that is not really an argument.

It is an argument. A very valid one.

"they *might* be different". You may want to get your hands on real hardware and try another word. Or at least read the datasheets instead of believing your imagination.

I would enjoy duplicating the st,stm32-spi.yaml into st,stm32{f,h}{0..7}-spi.yaml if I'm bored at a Sunday afternoon.

> 
> All bindings are to follow this rule, so I don't understand why you
> think it is an exception for you?

Zhou didn't ask you to make an exception. They have a valid point and they're asking why.

You may want to avoid further incidents of this kind by stop being bossy and actually writing a guideline of naming these .yaml files and publish it somewhere online.

> 
> 
> Best regards,
> Krzysztof

Best regards,
Mike Yang
Mark Brown July 23, 2022, 7:27 p.m. UTC | #6
On Sun, Jul 24, 2022 at 02:47:14AM +0800, Mike Yang wrote:
> On 7/24/22 01:43, Krzysztof Kozlowski wrote:
> > On 23/07/2022 18:50, Zhou Yanjie wrote:

> >> No offense, does it really need to be named that way?
> >> I can't seem to find documentation with instructions on this :(

...

> > All bindings are to follow this rule, so I don't understand why you
> > think it is an exception for you?

> Zhou didn't ask you to make an exception. They have a valid
> point and they're asking why.

> You may want to avoid further incidents of this kind by stop
> being bossy and actually writing a guideline of naming these
> .yaml files and publish it somewhere online.

Yeah, I do have to say that I was also completely unaware that
there was any enforced convention here.
Krzysztof Kozlowski July 23, 2022, 8:05 p.m. UTC | #7
On 23/07/2022 20:47, Mike Yang wrote:
> On 7/24/22 01:43, Krzysztof Kozlowski wrote:
>> On 23/07/2022 18:50, Zhou Yanjie wrote:
>>> Hi Krzysztof,
>>>
>>> On 2022/7/23 上午1:46, Krzysztof Kozlowski wrote:
>>>> On 22/07/2022 18:48, 周琰杰 (Zhou Yanjie) wrote:
>>>>> Add the SFC bindings for the X1000 SoC, the X1600 SoC, the X1830 SoC,
>>>>> and the X2000 SoC from Ingenic.
>>>>>
>>>>> Signed-off-by: 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
>>>>> ---
>>>>>   .../devicetree/bindings/spi/ingenic,sfc.yaml       | 64 ++++++++++++++++++++++
>>>>>   1 file changed, 64 insertions(+)
>>>>>   create mode 100644 Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>>>
>>>>> diff --git a/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>>> new file mode 100644
>>>>> index 00000000..b7c4cf4
>>>>> --- /dev/null
>>>>> +++ b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>>> @@ -0,0 +1,64 @@
>>>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>>>>> +%YAML 1.2
>>>>> +---
>>>>> +$id: http://devicetree.org/schemas/spi/ingenic,sfc.yaml#
>>>> File name should be rather based on first compatible, so
>>>> ingenic,x1000-sfc.yaml
>>>
>>>
>>> No offense, does it really need to be named that way?
>>> I can't seem to find documentation with instructions on this :(
>>>
>>> The use of "ingenic,sfc.yaml" indicates that this is the documentation
>>> for the SFC module for all Ingenic SoCs, without misleading people into
>>> thinking it's only for a specific model of SoC. And there seem to be many
>>> other yaml documents that use similar names (eg. fsl,spi-fsl-qspi.yaml,
>>> spi-rockchip.yaml, spi-nxp-fspi.yaml, ingenic,spi.yaml, spi-sifive.yaml,
>>> omap-spi.yaml), maybe these yaml files that are not named with first
>>> compatible are also for the same consideration. :)
>>
>> We have many bad examples, many poor patterns and they are never an
>> argument to add one more bad pattern.
> 
> Zhou already mentioned he was unable find the naming guidelines of these .yaml files.
> 
> Apparently you think it's unacceptable for new contributors of a certain subsystem to use existing code as examples, and/or they're responsible for figuring out what's a good example and what's a bad one in the existing codebase.

It's everywhere in the kernel, what can I say? If you copy existing
code, you might copy poor code...

> 
>>
>> It might never grow to new devices (because they might be different), so
>> that is not really an argument.
> 
> It is an argument. A very valid one.
> 
> "they *might* be different". You may want to get your hands on real hardware and try another word. Or at least read the datasheets instead of believing your imagination.
> 
> I would enjoy duplicating the st,stm32-spi.yaml into st,stm32{f,h}{0..7}-spi.yaml if I'm bored at a Sunday afternoon.
> 
>>
>> All bindings are to follow this rule, so I don't understand why you
>> think it is an exception for you?
> 
> Zhou didn't ask you to make an exception. They have a valid point and they're asking why.

Hm, everyone has the same valid point and such recommendation is to
everyone, although it is nothing serious.

> You may want to avoid further incidents of this kind by stop being bossy and actually writing a guideline of naming these .yaml files and publish it somewhere online.

I did not see any incident here... Process of review includes comments
and there is nothing bad happening when you receive a comment. No
incident...

Best regards,
Krzysztof
Krzysztof Kozlowski July 23, 2022, 8:07 p.m. UTC | #8
On 23/07/2022 21:27, Mark Brown wrote:
> On Sun, Jul 24, 2022 at 02:47:14AM +0800, Mike Yang wrote:
>> On 7/24/22 01:43, Krzysztof Kozlowski wrote:
>>> On 23/07/2022 18:50, Zhou Yanjie wrote:
> 
>>>> No offense, does it really need to be named that way?
>>>> I can't seem to find documentation with instructions on this :(
> 
> ...
> 
>>> All bindings are to follow this rule, so I don't understand why you
>>> think it is an exception for you?
> 
>> Zhou didn't ask you to make an exception. They have a valid
>> point and they're asking why.
> 
>> You may want to avoid further incidents of this kind by stop
>> being bossy and actually writing a guideline of naming these
>> .yaml files and publish it somewhere online.
> 
> Yeah, I do have to say that I was also completely unaware that
> there was any enforced convention here.

Indeed, it's not a enforced pattern. But there are many other
insignificant ones which we also tend to forget during review, like
using words "Device Tree bindings" in title or using unnecessary quotes
around "refs" (also in ID of schema). It's not a big deal, but I ask
when I notice it.


Best regards,
Krzysztof
Mike Yang July 23, 2022, 8:49 p.m. UTC | #9
On 7/24/22 04:07, Krzysztof Kozlowski wrote:
> On 23/07/2022 21:27, Mark Brown wrote:
>> On Sun, Jul 24, 2022 at 02:47:14AM +0800, Mike Yang wrote:
>>> On 7/24/22 01:43, Krzysztof Kozlowski wrote:
>>>> On 23/07/2022 18:50, Zhou Yanjie wrote:
>>
>>>>> No offense, does it really need to be named that way?
>>>>> I can't seem to find documentation with instructions on this :(
>>
>> ...
>>
>>>> All bindings are to follow this rule, so I don't understand why you
>>>> think it is an exception for you?
>>
>>> Zhou didn't ask you to make an exception. They have a valid
>>> point and they're asking why.
>>
>>> You may want to avoid further incidents of this kind by stop
>>> being bossy and actually writing a guideline of naming these
>>> .yaml files and publish it somewhere online.
>>
>> Yeah, I do have to say that I was also completely unaware that
>> there was any enforced convention here.
> 
> Indeed, it's not a enforced pattern. But there are many other
> insignificant ones which we also tend to forget during review, like
> using words "Device Tree bindings" in title or using unnecessary quotes
> around "refs" (also in ID of schema). It's not a big deal, but I ask
> when I notice it.

Good. Thanks for paying attention to these details.


>> Zhou already mentioned he was unable find the naming guidelines of these .yaml files.
>>
>> Apparently you think it's unacceptable for new contributors of a certain subsystem to use existing code as examples, and/or they're responsible for figuring out what's a good example and what's a bad one in the existing codebase.
> 
> It's everywhere in the kernel, what can I say? If you copy existing
> code, you might copy poor code...

Still, it shouldn't be a responsibility of new contributors to determine the quality of an existing piece of code, unless there are clear guidelines (i.e. one should use the new "cs-gpios" attribute in SPI controllers).

> 
>>
>>>
>>> It might never grow to new devices (because they might be different), so
>>> that is not really an argument.
>>
>> It is an argument. A very valid one.
>>
>> "they *might* be different". You may want to get your hands on real hardware and try another word. Or at least read the datasheets instead of believing your imagination.
>>
>> I would enjoy duplicating the st,stm32-spi.yaml into st,stm32{f,h}{0..7}-spi.yaml if I'm bored at a Sunday afternoon.
>>
>>>
>>> All bindings are to follow this rule, so I don't understand why you
>>> think it is an exception for you?
>>
>> Zhou didn't ask you to make an exception. They have a valid point and they're asking why.
> 
> Hm, everyone has the same valid point and such recommendation is to
> everyone, although it is nothing serious.
> 
>> You may want to avoid further incidents of this kind by stop being bossy and actually writing a guideline of naming these .yaml files and publish it somewhere online.
> 
> I did not see any incident here... Process of review includes comments
> and there is nothing bad happening when you receive a comment. No
> incident...


Okay. After careful inspection of the Ingenic datasheets, now I have the conclusion: The Ingenic X1000, X1021, X1500, X1501, X1520, X1600, X1800, X1830, X2000, X2100, X2500 have the same SFC controller.

X1600 has a newer version (let's say v2) of the SFC, and X2000-2500 have v3. Others have the original version (let's say v1). Each new version introduced new features such as arbitrary DMA sizes, and the rest features are the same.


So IMO the name "ingenic,sfc.yaml" is perfectly logical.


Regards,
Mike Yang
Zhou Yanjie July 24, 2022, 2:52 p.m. UTC | #10
Hi Krzysztof, Mike & Mark,

On 2022/7/24 上午4:05, Krzysztof Kozlowski wrote:
> On 23/07/2022 20:47, Mike Yang wrote:
>> On 7/24/22 01:43, Krzysztof Kozlowski wrote:
>>> On 23/07/2022 18:50, Zhou Yanjie wrote:
>>>> Hi Krzysztof,
>>>>
>>>> On 2022/7/23 上午1:46, Krzysztof Kozlowski wrote:
>>>>> On 22/07/2022 18:48, 周琰杰 (Zhou Yanjie) wrote:
>>>>>> Add the SFC bindings for the X1000 SoC, the X1600 SoC, the X1830 SoC,
>>>>>> and the X2000 SoC from Ingenic.
>>>>>>
>>>>>> Signed-off-by: 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
>>>>>> ---
>>>>>>    .../devicetree/bindings/spi/ingenic,sfc.yaml       | 64 ++++++++++++++++++++++
>>>>>>    1 file changed, 64 insertions(+)
>>>>>>    create mode 100644 Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>>>>
>>>>>> diff --git a/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>>>> new file mode 100644
>>>>>> index 00000000..b7c4cf4
>>>>>> --- /dev/null
>>>>>> +++ b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
>>>>>> @@ -0,0 +1,64 @@
>>>>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>>>>>> +%YAML 1.2
>>>>>> +---
>>>>>> +$id: http://devicetree.org/schemas/spi/ingenic,sfc.yaml#
>>>>> File name should be rather based on first compatible, so
>>>>> ingenic,x1000-sfc.yaml
>>>>
>>>> No offense, does it really need to be named that way?
>>>> I can't seem to find documentation with instructions on this :(
>>>>
>>>> The use of "ingenic,sfc.yaml" indicates that this is the documentation
>>>> for the SFC module for all Ingenic SoCs, without misleading people into
>>>> thinking it's only for a specific model of SoC. And there seem to be many
>>>> other yaml documents that use similar names (eg. fsl,spi-fsl-qspi.yaml,
>>>> spi-rockchip.yaml, spi-nxp-fspi.yaml, ingenic,spi.yaml, spi-sifive.yaml,
>>>> omap-spi.yaml), maybe these yaml files that are not named with first
>>>> compatible are also for the same consideration. :)
>>> We have many bad examples, many poor patterns and they are never an
>>> argument to add one more bad pattern.
>> Zhou already mentioned he was unable find the naming guidelines of these .yaml files.
>>
>> Apparently you think it's unacceptable for new contributors of a certain subsystem to use existing code as examples, and/or they're responsible for figuring out what's a good example and what's a bad one in the existing codebase.
> It's everywhere in the kernel, what can I say? If you copy existing
> code, you might copy poor code...
>
>>> It might never grow to new devices (because they might be different), so
>>> that is not really an argument.
>> It is an argument. A very valid one.
>>
>> "they *might* be different". You may want to get your hands on real hardware and try another word. Or at least read the datasheets instead of believing your imagination.
>>
>> I would enjoy duplicating the st,stm32-spi.yaml into st,stm32{f,h}{0..7}-spi.yaml if I'm bored at a Sunday afternoon.
>>
>>> All bindings are to follow this rule, so I don't understand why you
>>> think it is an exception for you?
>> Zhou didn't ask you to make an exception. They have a valid point and they're asking why.
> Hm, everyone has the same valid point and such recommendation is to
> everyone, although it is nothing serious.
>
>> You may want to avoid further incidents of this kind by stop being bossy and actually writing a guideline of naming these .yaml files and publish it somewhere online.
> I did not see any incident here... Process of review includes comments
> and there is nothing bad happening when you receive a comment. No
> incident...


I have no intention of provoking arguments, I just did *grep -rn "first 
compatible"* in the
Documentation folder after you mentioned the naming rules about "first 
compatible" before,
but just found a "first compatible" in "Documentation/fb/sstfb.rst", but 
It has absolutely
nothing to do with file naming. As Mike and Mark said, my question in 
the previous email
was just out of curiosity about where to look for a detailed explanation 
of the rule.
Since it would be somewhat strange to have two "Ingenic" yaml files with 
different naming
rules in the SPI subsystem, maybe Rob can guide us here?


Thanks and best regards!


>
> Best regards,
> Krzysztof
Zhou Yanjie July 24, 2022, 3:33 p.m. UTC | #11
Hi Mike,

On 2022/7/24 上午4:49, Mike Yang wrote:
> On 7/24/22 04:07, Krzysztof Kozlowski wrote:
>> On 23/07/2022 21:27, Mark Brown wrote:
>>> On Sun, Jul 24, 2022 at 02:47:14AM +0800, Mike Yang wrote:
>>>> On 7/24/22 01:43, Krzysztof Kozlowski wrote:
>>>>> On 23/07/2022 18:50, Zhou Yanjie wrote:
>>>>>> No offense, does it really need to be named that way?
>>>>>> I can't seem to find documentation with instructions on this :(
>>> ...
>>>
>>>>> All bindings are to follow this rule, so I don't understand why you
>>>>> think it is an exception for you?
>>>> Zhou didn't ask you to make an exception. They have a valid
>>>> point and they're asking why.
>>>> You may want to avoid further incidents of this kind by stop
>>>> being bossy and actually writing a guideline of naming these
>>>> .yaml files and publish it somewhere online.
>>> Yeah, I do have to say that I was also completely unaware that
>>> there was any enforced convention here.
>> Indeed, it's not a enforced pattern. But there are many other
>> insignificant ones which we also tend to forget during review, like
>> using words "Device Tree bindings" in title or using unnecessary quotes
>> around "refs" (also in ID of schema). It's not a big deal, but I ask
>> when I notice it.
> Good. Thanks for paying attention to these details.
>
>
>>> Zhou already mentioned he was unable find the naming guidelines of these .yaml files.
>>>
>>> Apparently you think it's unacceptable for new contributors of a certain subsystem to use existing code as examples, and/or they're responsible for figuring out what's a good example and what's a bad one in the existing codebase.
>> It's everywhere in the kernel, what can I say? If you copy existing
>> code, you might copy poor code...
> Still, it shouldn't be a responsibility of new contributors to determine the quality of an existing piece of code, unless there are clear guidelines (i.e. one should use the new "cs-gpios" attribute in SPI controllers).
>
>>>> It might never grow to new devices (because they might be different), so
>>>> that is not really an argument.
>>> It is an argument. A very valid one.
>>>
>>> "they *might* be different". You may want to get your hands on real hardware and try another word. Or at least read the datasheets instead of believing your imagination.
>>>
>>> I would enjoy duplicating the st,stm32-spi.yaml into st,stm32{f,h}{0..7}-spi.yaml if I'm bored at a Sunday afternoon.
>>>
>>>> All bindings are to follow this rule, so I don't understand why you
>>>> think it is an exception for you?
>>> Zhou didn't ask you to make an exception. They have a valid point and they're asking why.
>> Hm, everyone has the same valid point and such recommendation is to
>> everyone, although it is nothing serious.
>>
>>> You may want to avoid further incidents of this kind by stop being bossy and actually writing a guideline of naming these .yaml files and publish it somewhere online.
>> I did not see any incident here... Process of review includes comments
>> and there is nothing bad happening when you receive a comment. No
>> incident...
>
> Okay. After careful inspection of the Ingenic datasheets, now I have the conclusion: The Ingenic X1000, X1021, X1500, X1501, X1520, X1600, X1800, X1830, X2000, X2100, X2500 have the same SFC controller.


Actually, you are also missing out the X1630 and X1660, and the upcoming 
X2600.


>
> X1600 has a newer version (let's say v2) of the SFC, and X2000-2500 have v3. Others have the original version (let's say v1). Each new version introduced new features such as arbitrary DMA sizes, and the rest features are the same.
>
>
> So IMO the name "ingenic,sfc.yaml" is perfectly logical.
>
>
> Regards,
> Mike Yang
Rob Herring (Arm) July 25, 2022, 6:30 p.m. UTC | #12
On Sun, Jul 24, 2022 at 04:49:25AM +0800, Mike Yang wrote:
> On 7/24/22 04:07, Krzysztof Kozlowski wrote:
> > On 23/07/2022 21:27, Mark Brown wrote:
> >> On Sun, Jul 24, 2022 at 02:47:14AM +0800, Mike Yang wrote:
> >>> On 7/24/22 01:43, Krzysztof Kozlowski wrote:
> >>>> On 23/07/2022 18:50, Zhou Yanjie wrote:
> >>
> >>>>> No offense, does it really need to be named that way?
> >>>>> I can't seem to find documentation with instructions on this :(
> >>
> >> ...
> >>
> >>>> All bindings are to follow this rule, so I don't understand why you
> >>>> think it is an exception for you?
> >>
> >>> Zhou didn't ask you to make an exception. They have a valid
> >>> point and they're asking why.
> >>
> >>> You may want to avoid further incidents of this kind by stop
> >>> being bossy and actually writing a guideline of naming these
> >>> .yaml files and publish it somewhere online.

I don't like your tone. Patches are welcome to fix deficiencies in 
documentation. Out of the hundreds of bindings a year, I see <5 
documentation patches a year.

The documentation clearly says to run 'make dt_binding_check' and that 
was obviously not followed here. 

> >> Yeah, I do have to say that I was also completely unaware that
> >> there was any enforced convention here.
> > 
> > Indeed, it's not a enforced pattern. But there are many other
> > insignificant ones which we also tend to forget during review, like
> > using words "Device Tree bindings" in title or using unnecessary quotes
> > around "refs" (also in ID of schema). It's not a big deal, but I ask
> > when I notice it.
> 
> Good. Thanks for paying attention to these details.
> 
> 
> >> Zhou already mentioned he was unable find the naming guidelines of these .yaml files.
> >>
> >> Apparently you think it's unacceptable for new contributors of a certain subsystem to use existing code as examples, and/or they're responsible for figuring out what's a good example and what's a bad one in the existing codebase.

Please wrap your lines on replies.


> > 
> > It's everywhere in the kernel, what can I say? If you copy existing
> > code, you might copy poor code...
> 
> Still, it shouldn't be a responsibility of new contributors to 
> determine the quality of an existing piece of code, unless there are 
> clear guidelines (i.e. one should use the new "cs-gpios" attribute in SPI controllers).

Generally the guidance is to look at newer drivers for current best 
practices.


> >>> It might never grow to new devices (because they might be different), so
> >>> that is not really an argument.
> >>
> >> It is an argument. A very valid one.
> >>
> >> "they *might* be different". You may want to get your hands on real hardware and try another word. Or at least read the datasheets instead of believing your imagination.
> >>
> >> I would enjoy duplicating the st,stm32-spi.yaml into st,stm32{f,h}{0..7}-spi.yaml if I'm bored at a Sunday afternoon.
> >>
> >>>
> >>> All bindings are to follow this rule, so I don't understand why you
> >>> think it is an exception for you?
> >>
> >> Zhou didn't ask you to make an exception. They have a valid point and they're asking why.
> > 
> > Hm, everyone has the same valid point and such recommendation is to
> > everyone, although it is nothing serious.
> > 
> >> You may want to avoid further incidents of this kind by stop being bossy and actually writing a guideline of naming these .yaml files and publish it somewhere online.
> > 
> > I did not see any incident here... Process of review includes comments
> > and there is nothing bad happening when you receive a comment. No
> > incident...
> 
> 
> Okay. After careful inspection of the Ingenic datasheets, now I have 
> the conclusion: The Ingenic X1000, X1021, X1500, X1501, X1520, X1600, 
> X1800, X1830, X2000, X2100, X2500 have the same SFC controller.

So if they are all 'the same', then I expect they all have a fallback 
compatible with x1000 and using that for the filename makes sense.


> X1600 has a newer version (let's say v2) of the SFC, and X2000-2500 
> have v3. Others have the original version (let's say v1). Each new 
> version introduced new features such as arbitrary DMA sizes, and the 
> rest features are the same.

So backwards compatible? If so, then they should have x1000 for 
fallback.

> 
> So IMO the name "ingenic,sfc.yaml" is perfectly logical.

Covering all 3 versions? If so and not backwards compatible, then I 
would agree.

Rob
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
new file mode 100644
index 00000000..b7c4cf4
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/ingenic,sfc.yaml
@@ -0,0 +1,64 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/spi/ingenic,sfc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Bindings for SFC in Ingenic SoCs
+
+maintainers:
+  - 周琰杰 (Zhou Yanjie) <zhouyanjie@wanyeetech.com>
+
+description:
+  The SPI Flash Controller in Ingenic SoCs.
+
+properties:
+  compatible:
+    oneOf:
+      - enum:
+          - ingenic,x1000-sfc
+          - ingenic,x1600-sfc
+          - ingenic,x2000-sfc
+      - items:
+          - enum:
+              - ingenic,x1830-sfc
+          - const: ingenic,x1000-sfc
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    const: sfc
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/ingenic,x1000-cgu.h>
+
+	sfc: spi@13440000 {
+		compatible = "ingenic,x1000-sfc";
+		reg = <0x13440000 0x1000>;
+
+		interrupt-parent = <&intc>;
+		interrupts = <7>;
+
+		clocks = <&cgu X1000_CLK_SFC>;
+		clock-names = "sfc";
+
+		status = "disabled";
+	};
+...