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

[Johan Jonker]

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 at hotmail.com>
> 
> Add binding document for the Rockchip serial flash controller.

... Serial Flash Controller (SFC)

binding, document is same meaning?

> New device specific parameter of rockchip,sfc-no-dma included in
> documentation.
> 
> Signed-off-by: Chris Morgan <macromorgan at 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:

(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 at rock-chips.com>

This is the original author years ago, but did you ask him to be maintainer?

  - Heiko Stuebner <heiko at 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.

> +
> +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.

> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:

> +    minItems: 2

Remove.
Already 2 items.

> +    items:
> +      - description: Module Clock
> +      - description: Bus Clock
> +
> +  clock-names:

> +    minItems: 2

Remove.
Already 2 items.

> +    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);

> +
> +  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?

> +      reg:
> +        minimum: 0
> +        maximum: 3

This is a further restriction.
#define SFC_MAX_CHIPSELECT_NUM		4

> +
> +      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 at ff3a0000 {

Recheck example indent.

> +	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 at 0 {

	nor_flash: flash at 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

> +	};
> +};
> +
> +...
>