Re: [PATCH v2 2/4] spi: rockchip-sfc: Bindings for Rockchip serial flash controller

Chris Morgan
2021-05-31T17:18:36Z

On Sat, May 29, 2021 at 10:45:35AM +0200, Johan Jonker wrote:
> Hi Chris,
>
> Some comments. Have a look if it's useful.
>
> Please try to order patches like:
> (1) dt-binding - compatible addition
> (2) driver patches
> (3) devicetree node patches
>
> On 5/28/21 7:00 PM, Chris Morgan wrote:
> > From: Chris Morgan <macromorgan@hotmail.com>
> >
> > Add binding document for the Rockchip serial flash controller.
>
> ... Serial Flash Controller (SFC)
>
> binding, document is same meaning?

Yes, will be more clear in follow up.

>
> > New device specific parameter of rockchip,sfc-no-dma included in
> > documentation.
> >
> > Signed-off-by: Chris Morgan <macromorgan@hotmail.com>
> > ---
> > .../spi/rockchip,serialflash-controller.yaml | 107 ++++++++++++++++++
> > 1 file changed, 107 insertions(+)
> > create mode 100644 Documentation/devicetree/bindings/spi/rockchip,serialflash-controller.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/spi/rockchip,serialflash-controller.yaml b/Documentation/devicetree/bindings/spi/rockchip,serialflash-controller.yaml
> > new file mode 100644
> > index 000000000000..eb073130e82a
> > --- /dev/null
>
> > +++ b/Documentation/devicetree/bindings/spi/rockchip,serialflash-controller.yaml
> > @@ -0,0 +1,107 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/spi/rockchip,serialflash-controller.yaml#
>
> rockchip-sfc.yaml is shorter,
> but ask rob+dt or maintainer for correct name.
> Documents seem to have the format:

I think rockchip-sfc.yaml works better, it fits the
(manufacturer)-(function).yaml format.

>
> (manufacturer), (SoC type)-(function).yaml
>
> (manufacturer)-(function).yaml
>
>
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
>
> > +title: Rockchip SoCs Serial FLASH Controller (SFC)
>
> title: Rockchip Serial Flash Controller (SFC)
>
> > +
>
> > +maintainers:
>
> > + - Andy Yan <andy.yan@rock-chips.com>
>
> This is the original author years ago, but did you ask him to be maintainer?
>
> - Heiko Stuebner <heiko@sntech.de>
>
> Add someone who can respond in a short period of time and who knows the
> hardware in case rob+dt wants to delete something.

I asked Heiko on IRC if he would be okay with me listing him and myself
as maintainers. I'm comfortable enough with the hardware now to be able
to respond/fix basic issues with it, though it would also be good to
have a veteran of the hardware involved too.

>
> > +
> > +allOf:
> > + - $ref: spi-controller.yaml#
> > +
> > +properties:
> > + compatible:
>
> > + oneOf:
> > + - const: rockchip,px30-sfc
> > + - const: rockchip,rv1108-sfc
> > + - items:
> > + - const: rockchip,sfc
>
> Compatible strings are supposed to be SoC orientated, so no generic ones
> here.
>
> "rockchip,sfc" can be found in the manufacturer tree:
> px30.dtsi
> rk1806.dtsi
> rk1808.dtsi
> rk3036.dtsi
> rk312x.dtsi
> rk3308.dtsi
> rv1108.dtsi
>
> Choose the first SoC in line with SFC and add that to your driver. All
> SoCs with SFC compatible after that use a fallback string.
>
> Example if rk3036 is first in line and has support in mainline:
> oneOf:
> - const: rockchip,rk3036-sfc
> - items:
> - enum:
> - rockchip,px30-sfc
> - rockchip,rk3308-sfc
> - rockchip,rv1108-sfc
> - const: rockchip,rk3036-sfc
>
> Check indent with yamllint program.

Thanks, acknowledged. The BSP driver does a runtime check to see if the
underlying hardware is a v3 or a v4 of the IP, whereas this driver only
works as expected on the v3 of the hardware. I don't know which of
those chips are which of the hardware. I'll try and pull datasheets for
each of them, but failing that I can only say for sure this should work
on the rv1108 and px30 (and I can only test against the px30). If it
comes down to only being able to validate what I already know, I'll
pick the oldest SoC by release date and use that one as the const and
list the other one as the compatible.

>
> > +
> > + reg:
> > + maxItems: 1
> > +
> > + interrupts:
> > + maxItems: 1
> > +
> > + clocks:
>
> > + minItems: 2
>
> Remove.
> Already 2 items.

Okay.

>
> > + items:
> > + - description: Module Clock
> > + - description: Bus Clock
> > +
> > + clock-names:
>
> > + minItems: 2
>
> Remove.
> Already 2 items.

Okay.

>
> > + items:
>
> > + - const: clk-sfc
> > + - const: clk-hsfc
>
> - const: clk
> - const: hclk
>
> Ask Heiko for exact name.
> The driver internal uses:
>
> + clk_disable_unprepare(sfc->clk);
> + clk_disable_unprepare(sfc->hclk);

I'll ask, as the BSP has this all over the place (both).

>
> > +
> > + power-domains:
> > + maxItems: 1
> > +
> > + rockchip,sfc-no-dma:
>
> ===
> vendor,bool-property:
> description: Vendor specific properties must have a description. Boolean
> properties are one case where the json-schema 'type' keyword can
> be used
> directly.
> type: boolean
> ===
>
> > + - descrption: Boolean value for disabling DMA
>
> description:
>
> without "-"
>
> > +
>
> > +patternProperties:
>
> > + "^spi-nor@[0-3]$":
>
> "^flash@[0-3]$":
> Maybe restrict further to flash only?
>
> > + type: object
> > + properties:
>
> > +
> > + compatible:
> > + oneOf:
> > + - const: jedec,spi-nor
>
> Remove, use $ref to jedec,spi-nor.yaml.
>
> ===
> patternProperties:
> "^flash@[0-3]$":
> type: object
>
> $ref: "/schemas/mtd/jedec,spi-nor.yaml#"
>
> properties:
> reg:
> minimum: 0
> maximum: 3
>
> unevaluatedProperties: false
> ===
>
> Could you try/test above example?

My hardware has only a single flash chip soldered to CS 0. I'm afraid
I'm not able to test any more configurations. The best I can say is
the registers on the hardware for CS accept a 2 bit value so anything
between 0 and 3 should be acceptable.

>
> > + reg:
> > + minimum: 0
> > + maximum: 3
>
> This is a further restriction.
> #define SFC_MAX_CHIPSELECT_NUM 4

Correct, because I have 2 bits to work with, bits 31:30 of SFC_CMD
(0x0100) to define the chip select.

>
> > +
> > + spi-max-frequency:
> > + maxItems: 1
> > + - description: Maximum frequency for SPI Flash
>
> > +
> > + spi-rx-bus-width:
> > + maxItems: 1
> > + - description: RX Bus Width (1x, 2x, or 4x mode)
> > +
> > + spi-tx-bus-width:
> > + maxItems: 1
> > + - description: TX Bus Width (1x, 2x, or 4x mode)
>
> Already in spi-controller.yaml if nothing changed.
>
> > +
> > +
> > +required:
> > + - compatible
> > + - reg
> > + - interrupts
> > + - clocks
> > + - clock-names
> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > + - |
> > + #include <dt-bindings/clock/px30-cru.h>
> > + #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +
>
> > +sfc: spi@ff3a0000 {
>
> Recheck example indent.

Will do, I'll make sure the next version I try to fix the indents
better.

>
> > + compatible = "rockchip,px30-sfc","rockchip,sfc";
>
> compatible = "rockchip,px30-sfc", "rockchip,rk3036-sfc";
>
> See comment above.
>
> > + reg = <0x0 0xff3a0000 0x0 0x4000>;
> > + interrupts = <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>;
> > + clocks = <&cru SCLK_SFC>, <&cru HCLK_SFC>;
> > + clock-names = "sfc", "hsfc";
>
> clock-names = "clk", "hclk";
>
> > + pinctrl-0 = <&sfc_clk &sfc_cs &sfc_bus2>;
>
> pinctrl-names = "default";
>
> sort
>
> > + power-domains = <&power PX30_PD_MMC_NAND>;
>
> #address-cells = <1>;
> #size-cells = <0>;
>
> Things with "#" below in the list.
>
> > +
>
> > + nor_flash: spi-nor@0 {
>
> nor_flash: flash@0 {
>
> > + reg = <0>;
>
> > + compatible = "xtx,xt25f128b","jedec,spi-nor";
>
> compatible = "jedec,spi-nor";
>
> > + spi-rx-bus-width = <2>;
> > + spi-tx-bus-width = <2>;
> > + spi-max-frequency = <108000000>;
>
> sort
>
> > + };
> > +};
> > +
> > +...
> >

Thank you for your comments. I'll try to get it all sorted out with the
next update.