| 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 |
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
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.
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
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
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
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.
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
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
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
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
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
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 --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"; + }; +...
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