Re: [PATCH 6/8] dt-bindings: mfd: syscon: Split and enforce documenting MFD children

[Rob Herring]

On Sun, May 19, 2024 at 08:42:21PM +0200, Krzysztof Kozlowski wrote:
> Simple syscon nodes can be documented in common syscon.yaml, however
> devices with simple-mfd compatible, thus with some children, should have
> their own schema listing these children.  Such listing makes the binding
> specific, allows better validation (so the incorrect child would not
> appear in the simple-mfd node) and actually enforces repeated rule for
> simple-mfd devices:
> 
>   "simple-mfd" is only for simple devices, where the children do not
>   depend on the parent.
> 
> Currently the syscon+simple-mfd binding is quite broad and allows
> any child or property, thus above rule cannot be enforced.
> 
> Split the syscon.yaml binding into:
> 1. Common syscon properties, used potentially by many bindings.
> 2. Simple syscon devices (NO simple-mfd!).
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@xxxxxxxxxx>
> 
> ---
> 
> Depends on:
> 1. https://lore.kernel.org/r/20240510123018.3902184-1-robh@xxxxxxxxxx
> 2. Previous patches in the series.
> ---
>  .../devicetree/bindings/mfd/syscon-common.yaml     |  72 +++++++
>  Documentation/devicetree/bindings/mfd/syscon.yaml  | 212 +++++++++------------
>  2 files changed, 162 insertions(+), 122 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/mfd/syscon-common.yaml b/Documentation/devicetree/bindings/mfd/syscon-common.yaml
> new file mode 100644
> index 000000000000..c3ff3a7afce3
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/syscon-common.yaml
> @@ -0,0 +1,72 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mfd/syscon-common.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: System Controller Registers R/W Common Properties
> +
> +description: |
> +  System controller node represents a register region containing a set
> +  of miscellaneous registers. The registers are not cohesive enough to
> +  represent as any specific type of device. The typical use-case is
> +  for some other node's driver, or platform-specific code, to acquire
> +  a reference to the syscon node (e.g. by phandle, node path, or
> +  search using a specific compatible value), interrogate the node (or
> +  associated OS driver) to determine the location of the registers,
> +  and access the registers directly.
> +
> +maintainers:
> +  - Lee Jones <lee@xxxxxxxxxx>
> +
> +select:
> +  properties:
> +    compatible:
> +      contains:
> +        enum:
> +          - syscon
> +
> +  required:
> +    - compatible
> +
> +properties:
> +  compatible:
> +    contains:
> +      const: syscon
> +    minItems: 2
> +    maxItems: 5  # Should be enough
> +
> +  reg:
> +    maxItems: 1
> +
> +  reg-io-width:
> +    description: |
> +      The size (in bytes) of the IO accesses that should be performed
> +      on the device.
> +    enum: [1, 2, 4, 8]
> +
> +required:
> +  - compatible
> +  - reg
> +
> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: simple-mfd
> +    then:
> +      properties:
> +        compatible:
> +          minItems: 3
> +          maxItems: 5
> +
> +additionalProperties: true
> +
> +examples:
> +  - |
> +    syscon: syscon@1c00000 {
> +        compatible = "allwinner,sun8i-h3-system-controller", "syscon";
> +        reg = <0x01c00000 0x1000>;
> +    };
> +...
> diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml
> index b17fa0487178..70e3961bc96f 100644
> --- a/Documentation/devicetree/bindings/mfd/syscon.yaml
> +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml
> @@ -4,7 +4,7 @@
>  $id: http://devicetree.org/schemas/mfd/syscon.yaml#
>  $schema: http://devicetree.org/meta-schemas/core.yaml#
>  
> -title: System Controller Registers R/W
> +title: System Controller Devices
>  
>  description: |
>    System controller node represents a register region containing a set
> @@ -19,122 +19,99 @@ description: |
>  maintainers:
>    - Lee Jones <lee@xxxxxxxxxx>
>  
> -select:
> -  properties:
> -    compatible:
> -      contains:
> -        enum:
> -          - syscon
> -
> -  required:
> -    - compatible
> -

Removing this is only going to work with v2024.04. The only way it 
works for older versions is listing all the compatibles here. That's a 
bit new for us to require it.

Rob