Re: [PATCH 1/2] dt-bindings: mux: Document mux-states property

[Peter Rosin]

Hi Aswath!

Some language nits. But other than that it looks good to me!

On 2021-11-30 13:18, Aswath Govindraju wrote:
> In some cases, it is required to provide the state to which the mux
> controller has be set to, from the consumer device tree node. Document the
s/has be/has to be/

> property mux-states that can be used for adding this support.
> 
> Signed-off-by: Aswath Govindraju <a-govindraju@xxxxxx>
> ---
>  .../devicetree/bindings/mux/gpio-mux.yaml     | 11 ++++++--
>  .../devicetree/bindings/mux/mux-consumer.yaml | 14 ++++++++++
>  .../bindings/mux/mux-controller.yaml          | 26 ++++++++++++++++++-
>  3 files changed, 48 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/mux/gpio-mux.yaml b/Documentation/devicetree/bindings/mux/gpio-mux.yaml
> index 0a7c8d64981a..ee4de9fbaf4d 100644
> --- a/Documentation/devicetree/bindings/mux/gpio-mux.yaml
> +++ b/Documentation/devicetree/bindings/mux/gpio-mux.yaml
> @@ -26,7 +26,10 @@ properties:
>        List of gpios used to control the multiplexer, least significant bit first.
>  
>    '#mux-control-cells':
> -    const: 0
> +    enum: [ 0, 1 ]
> +
> +  '#mux-state-cells':
> +    enum: [ 1, 2 ]
>  
>    idle-state:
>      default: -1
> @@ -34,7 +37,11 @@ properties:
>  required:
>    - compatible
>    - mux-gpios
> -  - "#mux-control-cells"
> +anyOf:
> +  - required:
> +      - "#mux-control-cells"
> +  - required:
> +      - "#mux-state-cells"
>  
>  additionalProperties: false
>  
> diff --git a/Documentation/devicetree/bindings/mux/mux-consumer.yaml b/Documentation/devicetree/bindings/mux/mux-consumer.yaml
> index 7af93298ab5c..64f353714227 100644
> --- a/Documentation/devicetree/bindings/mux/mux-consumer.yaml
> +++ b/Documentation/devicetree/bindings/mux/mux-consumer.yaml
> @@ -25,6 +25,11 @@ description: |
>    strings to label each of the mux controllers listed in the "mux-controls"
>    property.
>  
> +  If it is required to provide the state that the mux controller needs to
> +  be set to, the property "mux-states" must be used. An optional property
> +  "mux-state-names" can be used to provide a list of strings, to label
> +  each of the mux controllers listed in the "mux-states" property.

s/mux controllers/multiplexer states/

> +
>    mux-ctrl-specifier typically encodes the chip-relative mux controller number.
>    If the mux controller chip only provides a single mux controller, the
>    mux-ctrl-specifier can typically be left out.
> @@ -35,12 +40,21 @@ properties:
>    mux-controls:
>      $ref: /schemas/types.yaml#/definitions/phandle-array
>  
> +  mux-states:
> +    $ref: /schemas/types.yaml#/definitions/phandle-array
> +
>    mux-control-names:
>      description:
>        Devices that use more than a single mux controller can use the
>        "mux-control-names" property to map the name of the requested mux
>        controller to an index into the list given by the "mux-controls" property.
>  
> +  mux-state-names:
> +    description:
> +      Devices that use more than a single mux controller can use the

s/mux controller/multiplexer state/

> +      "mux-state-names" property to map the name of the requested mux
> +      controller to an index into the list given by the "mux-states" property.

And again, over the line break.

> +
>  additionalProperties: true
>  
>  ...
> diff --git a/Documentation/devicetree/bindings/mux/mux-controller.yaml b/Documentation/devicetree/bindings/mux/mux-controller.yaml
> index 736a84c3b6a5..b29dbf521f01 100644
> --- a/Documentation/devicetree/bindings/mux/mux-controller.yaml
> +++ b/Documentation/devicetree/bindings/mux/mux-controller.yaml
> @@ -25,7 +25,9 @@ description: |
>    --------------------
>  
>    Mux controller nodes must specify the number of cells used for the
> -  specifier using the '#mux-control-cells' property.
> +  specifier using the '#mux-control-cells' or 'mux-state-cells'

'#mux-state-cells' (missing #)

> +  property. Value of '#mux-state-cells' will always be one greater then

s/Value/The value/
s/then/than/

Cheers,
Peter

> +  the value of '#mux-control-cells'.
>  
>    Optionally, mux controller nodes can also specify the state the mux should
>    have when it is idle. The idle-state property is used for this. If the
> @@ -67,6 +69,8 @@ select:
>            pattern: '^mux-controller'
>      - required:
>          - '#mux-control-cells'
> +    - required:
> +        - '#mux-state-cells'
>  
>  properties:
>    $nodename:
> @@ -75,6 +79,9 @@ properties:
>    '#mux-control-cells':
>      enum: [ 0, 1 ]
>  
> +  '#mux-state-cells':
> +    enum: [ 1, 2 ]
> +
>    idle-state:
>      $ref: /schemas/types.yaml#/definitions/int32
>      minimum: -2
> @@ -179,4 +186,21 @@ examples:
>              };
>          };
>      };
> +
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    mux1: mux-controller {
> +        compatible = "gpio-mux";
> +        #mux-state-cells = <1>;
> +        mux-gpios = <&exp_som 2 GPIO_ACTIVE_HIGH>;
> +    };
> +
> +    transceiver4: can-phy4 {
> +        compatible = "ti,tcan1042";
> +        #phy-cells = <0>;
> +        max-bitrate = <5000000>;
> +        standby-gpios = <&exp_som 7 GPIO_ACTIVE_HIGH>;
> +        mux-states = <&mux1 1>;
> +    };
>  ...
>