Re: [PATCH v4 3/9] dt-bindings: mfd: add support for mule

[Rob Herring <robh@kernel.org>]

On Tue, Jun 18, 2024 at 06:06:45PM +0200, Farouk Bouabid wrote:
> Mule is an MCU that emulates a set of I2C devices, among which an amc6821
> device and an I2C mux that exposes more emulated devices. These two devices
> share the same I2C address. Only the I2C mux uses register (0xff) as a
> config register.

Everywhere (or the first place in any section (subject, commit msg, 
title, description, etc.) you say 'mule' I think should be preceeded 
with the vendor because 'mule' has no meaning on its own unless we are 
talking animals.

> 
> Add dt-binding support for the Mule I2C multi-function device.
> 
> Signed-off-by: Farouk Bouabid <farouk.bouabid@cherry.de>
> ---
>  .../devicetree/bindings/i2c/tsd,mule-i2c-mux.yaml  | 48 +++++++++++++
>  .../devicetree/bindings/mfd/tsd,mule.yaml          | 82 ++++++++++++++++++++++
>  2 files changed, 130 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/i2c/tsd,mule-i2c-mux.yaml b/Documentation/devicetree/bindings/i2c/tsd,mule-i2c-mux.yaml
> new file mode 100644
> index 000000000000..ac9dfc936272
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/i2c/tsd,mule-i2c-mux.yaml
> @@ -0,0 +1,48 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/i2c/tsd,mule-i2c-mux.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Mule I2C multiplexer
> +
> +maintainers:
> +  - Farouk Bouabid <farouk.bouabid@cherry.de>
> +  - Quentin Schulz <quentin.schulz@cherry.de>
> +
> +description: |
> +  This module is part of the Mule I2C multi-function device. For more
> +  details see ../mfd/tsd,mule.yaml.
> +
> +  Mule I2C-mux configures the active device that can be accessed on address
> +  0x6f through the config register.
> +
> +      +--------------------------------------------------+
> +      | Mule                                             |
> +  0x18|    +---------------+                             |
> +  -------->|Config register|----+                        |
> +      |    +---------------+    |                        |
> +      |                         V_                       |
> +      |                        |  \          +--------+  |
> +      |                        |   \-------->| dev #0 |  |
> +      |                        |   |         +--------+  |
> +  0x6f|                        | M |-------->| dev #1 |  |
> +  ---------------------------->| U |         +--------+  |
> +      |                        | X |-------->| dev #2 |  |
> +      |                        |   |         +--------+  |
> +      |                        |   /-------->| dev #3 |  |
> +      |                        |__/          +--------+  |
> +      +--------------------------------------------------+
> +
> +
> +allOf:
> +  - $ref: /schemas/i2c/i2c-mux.yaml#
> +
> +properties:
> +  compatible:
> +    const: tsd,mule-i2c-mux
> +
> +required:
> +  - compatible
> +
> +unevaluatedProperties: false
> diff --git a/Documentation/devicetree/bindings/mfd/tsd,mule.yaml b/Documentation/devicetree/bindings/mfd/tsd,mule.yaml
> new file mode 100644
> index 000000000000..ab532340a17c
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/tsd,mule.yaml
> @@ -0,0 +1,82 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mfd/tsd,mule.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Mule I2C multi function device
> +
> +maintainers:
> +  - Farouk Bouabid <farouk.bouabid@cherry.de>
> +  - Quentin Schulz <quentin.schulz@cherry.de>
> +
> +description:
> +  Mule is an MCU that emulates a set of I2C devices, among which an amc6821
> +  device and an I2C mux that exposes more emulated devices. These two devices
> +  share the same I2C address. Only the I2C mux uses register (0xff) as a config
> +  register.
> +
> +properties:
> +  compatible:
> +    const: tsd,mule
> +
> +  reg:
> +    maxItems: 1
> +
> +  "#address-cells":
> +    const: 1
> +
> +  "#size-cells":
> +    const: 0
> +
> +patternProperties:
> +  "^fan(@[0-9a-f]+)?$":
> +    $ref: /schemas/trivial-devices.yaml

That doesn't really define which device. You should do something like 
this:

additionalProperties: true
properties:
  compatible:
    contains:
      const: ti,amc6821

If the compatible is correct, then the schema for it will be applied 
separately.

> +
> +  "^i2c-mux(@[0-9a-f]+)?$":
> +    $ref: /schemas/i2c/tsd,mule-i2c-mux.yaml
> +
> +required:
> +  - "#address-cells"
> +  - "#size-cells"
> +  - compatible
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        mule@18 {
> +            compatible = "tsd,mule";
> +            reg = <0x18>;
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +
> +            fan@18 {
> +                compatible = "ti,amc6821";
> +                reg = <0x18>;
> +            };
> +
> +            i2c-mux {
> +                compatible = "tsd,mule-i2c-mux";
> +                #address-cells = <1>;
> +                #size-cells = <0>;
> +
> +                i2c@0 {
> +                    reg = <0x0>;
> +                    #address-cells = <1>;
> +                    #size-cells = <0>;
> +
> +                    rtc@6f {
> +                        compatible = "isil,isl1208";
> +                        reg = <0x6f>;
> +                    };
> +                };
> +            };
> +        };
> +    };
> +...
> 
> -- 
> 2.34.1
>