diff mbox series

[v4,1/3] dt-bindings: hwmon: Add Microchip emc2305 support

Message ID 20250313125746.2901904-2-florin.leotescu@oss.nxp.com (mailing list archive)
State New
Headers show
Series Add OF support for Microchip emc2305 fan controller | expand

Commit Message

Florin Leotescu (OSS) March 13, 2025, 12:57 p.m. UTC
From: Florin Leotescu <florin.leotescu@nxp.com>

Introduce yaml schema for Microchip emc2305 pwm fan controller.

Signed-off-by: Florin Leotescu <florin.leotescu@nxp.com>
---
 .../bindings/hwmon/microchip,emc2305.yaml     | 104 ++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml

Comments

Frank Li March 13, 2025, 4:39 p.m. UTC | #1
On Thu, Mar 13, 2025 at 02:57:44PM +0200, florin.leotescu@oss.nxp.com wrote:
> From: Florin Leotescu <florin.leotescu@nxp.com>
>
> Introduce yaml schema for Microchip emc2305 pwm fan controller.
>
> Signed-off-by: Florin Leotescu <florin.leotescu@nxp.com>
> ---
>  .../bindings/hwmon/microchip,emc2305.yaml     | 104 ++++++++++++++++++
>  1 file changed, 104 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml
>
> diff --git a/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml b/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml
> new file mode 100644
> index 000000000000..3107fcafcf6a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml
> @@ -0,0 +1,104 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +
> +$id: http://devicetree.org/schemas/hwmon/microchip,emc2305.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Microchip EMC2305 SMBus compliant PWM fan controller
> +
> +maintainers:
> +  - Michael Shych <michaelsh@nvidia.com>
> +
> +description:
> +  Microchip EMC2301/2/3/5 pwm controller which supports
> +  up to five programmable fan control circuits.
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - enum:
> +          - microchip,emc2305
> +      - items:
> +          - enum:
> +              - microchip,emc2303
> +              - microchip,emc2302
> +              - microchip,emc2301
> +          - const: microchip,emc2305
> +
> +  reg:
> +    maxItems: 1
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0
> +
> +  '#pwm-cells':
> +    const: 2
> +
> +patternProperties:
> +  "^fan@[0-4]$":
> +    $ref: fan-common.yaml#
> +    unevaluatedProperties: false
> +    properties:
> +      reg:
> +        description:
> +          The fan number.
> +
> +    required:
> +      - reg
> +      - pwms
> +
> +required:
> +  - compatible
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        fan_controller: fan-controller@2f {
> +            compatible = "microchip,emc2305";
> +            reg = <0x2f>;
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +            #pwm-cells = <2>;
> +
> +            fan@0 {
> +                #cooling-cells = <2>;
> +                reg = <0x0>;
> +                pwms = <&fan_controller 1 1>;
> +            };
> +
> +            fan@1 {
> +                #cooling-cells = <2>;
> +                reg = <0x1>;
> +                pwms = <&fan_controller 1 1>;
> +            };
> +
> +            fan@2 {
> +                #cooling-cells = <2>;
> +                reg = <0x2>;
> +                pwms = <&fan_controller 1 1>;
> +            };
> +
> +            fan@3 {
> +                #cooling-cells = <2>;
> +                reg = <0x3>;
> +                pwms = <&fan_controller 1 1>;
> +            };
> +
> +            fan@4 {
> +                #cooling-cells = <2>;
> +                reg = <0x4>;
> +                pwms = <&fan_controller 1 1>;
> +            };

I think one child node should be enough for example.

Reviewed-by: Frank Li <Frank.Li@nxp.com>

> +        };
> +    };
> +...
> --
> 2.34.1
>
Krzysztof Kozlowski March 14, 2025, 8:07 a.m. UTC | #2
On Thu, Mar 13, 2025 at 02:57:44PM +0200, florin.leotescu@oss.nxp.com wrote:
> +  '#size-cells':
> +    const: 0
> +
> +  '#pwm-cells':
> +    const: 2
> +
> +patternProperties:
> +  "^fan@[0-4]$":

Keep consistent quotes, either ' or "

> +    $ref: fan-common.yaml#
> +    unevaluatedProperties: false
> +    properties:
> +      reg:
> +        description:
> +          The fan number.
> +
> +    required:
> +      - reg
> +      - pwms
> +
> +required:
> +  - compatible
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        fan_controller: fan-controller@2f {
> +            compatible = "microchip,emc2305";
> +            reg = <0x2f>;
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +            #pwm-cells = <2>;
> +
> +            fan@0 {
> +                #cooling-cells = <2>;
> +                reg = <0x0>;

Please follow DTS coding style, so reg is here the first property.

> +                pwms = <&fan_controller 1 1>;

It's the same PWM for all fans? So isn't it basically one fan? How do
you exactly control them independently, if the same PWM channel is used?

> +            };
> +
> +            fan@1 {
> +                #cooling-cells = <2>;
> +                reg = <0x1>;
> +                pwms = <&fan_controller 1 1>;


Best regards,
Krzysztof
Florin Leotescu (OSS) March 14, 2025, 3:02 p.m. UTC | #3
>> +  '#size-cells':
>> +    const: 0
>> +
>> +  '#pwm-cells':
>> +    const: 2
>> +
>> +patternProperties:
>> +  "^fan@[0-4]$":
> 
> Keep consistent quotes, either ' or "
>

Thank you! I will correct that.

>> +    $ref: fan-common.yaml#
>> +    unevaluatedProperties: false
>> +    properties:
>> +      reg:
>> +        description:
>> +          The fan number.
>> +
>> +    required:
>> +      - reg
>> +      - pwms
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    i2c {
>> +        #address-cells = <1>;
>> +        #size-cells = <0>;
>> +
>> +        fan_controller: fan-controller@2f {
>> +            compatible = "microchip,emc2305";
>> +            reg = <0x2f>;
>> +            #address-cells = <1>;
>> +            #size-cells = <0>;
>> +            #pwm-cells = <2>;
>> +
>> +            fan@0 {
>> +                #cooling-cells = <2>;
>> +                reg = <0x0>;
>
> Please follow DTS coding style, so reg is here the first property.
>

Ok, I will correct it. Thanks!

>> +                pwms = <&fan_controller 1 1>;
>
> It's the same PWM for all fans? So isn't it basically one fan? How do you exactly control them independently, if the same PWM channel is used?
>

It is the same PWM controller, but each fan has a different PWM channel. According to datasheet, the EMC2305 could control up to five programmable fan control circuits.
The driver will parse all fan child nodes during probe and use reg to differentiate the channels, similar as it is done on max6639 hwmon driver. 
The 'pwms' arguments in the example are used to select the polarity and pwm output, which will be parsed in the driver to generate the bits for the registers used to select pwm output and pwm polarity. 
(... <&fan_controller [pwm_polarity] [pwm_output]> ...).  Now, I realized that I should use: <&fan_controller [pwm_channel] [pwm_frequency] [pwm_polarity] [pwm_output]>. I will also document the arguments in #pwm-cells description. 
Thanks!

>> +            };
>> +
>> +            fan@1 {
>> +                #cooling-cells = <2>;
>> +                reg = <0x1>;
>> +                pwms = <&fan_controller 1 1>;

Best regards,
Florin
Guenter Roeck March 14, 2025, 3:17 p.m. UTC | #4
On 3/14/25 08:02, Florin Leotescu (OSS) wrote:
>>> +  '#size-cells':
>>> +    const: 0
>>> +
>>> +  '#pwm-cells':
>>> +    const: 2
>>> +
>>> +patternProperties:
>>> +  "^fan@[0-4]$":
>>
>> Keep consistent quotes, either ' or "
>>
> 
> Thank you! I will correct that.
> 
>>> +    $ref: fan-common.yaml#
>>> +    unevaluatedProperties: false
>>> +    properties:
>>> +      reg:
>>> +        description:
>>> +          The fan number.
>>> +
>>> +    required:
>>> +      - reg
>>> +      - pwms
>>> +
>>> +required:
>>> +  - compatible
>>> +  - reg
>>> +
>>> +additionalProperties: false
>>> +
>>> +examples:
>>> +  - |
>>> +    i2c {
>>> +        #address-cells = <1>;
>>> +        #size-cells = <0>;
>>> +
>>> +        fan_controller: fan-controller@2f {
>>> +            compatible = "microchip,emc2305";
>>> +            reg = <0x2f>;
>>> +            #address-cells = <1>;
>>> +            #size-cells = <0>;
>>> +            #pwm-cells = <2>;
>>> +
>>> +            fan@0 {
>>> +                #cooling-cells = <2>;
>>> +                reg = <0x0>;
>>
>> Please follow DTS coding style, so reg is here the first property.
>>
> 
> Ok, I will correct it. Thanks!
> 
>>> +                pwms = <&fan_controller 1 1>;
>>
>> It's the same PWM for all fans? So isn't it basically one fan? How do you exactly control them independently, if the same PWM channel is used?
>>
> 
> It is the same PWM controller, but each fan has a different PWM channel. According to datasheet, the EMC2305 could control up to five programmable fan control circuits.
> The driver will parse all fan child nodes during probe and use reg to differentiate the channels, similar as it is done on max6639 hwmon driver.
> The 'pwms' arguments in the example are used to select the polarity and pwm output, which will be parsed in the driver to generate the bits for the registers used to select pwm output and pwm polarity.
> (... <&fan_controller [pwm_polarity] [pwm_output]> ...).  Now, I realized that I should use: <&fan_controller [pwm_channel] [pwm_frequency] [pwm_polarity] [pwm_output]>. I will also document the arguments in #pwm-cells description.
> Thanks!
> 

Please also document that the channel assignment is fixed. Technically it
doesn't even make sense to specify the pwm channel (it is fixed and
matches "reg"). I don't know if the channel number can be omitted from pwms.
All you really need is polarity, frequency, and output type.

I am not really sure what to do if the channel number is mandatory.
If it is, I'd suggest to document it as mandated but not needed/used,
and then ignore it in the code.

Thanks,
Guenter
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml b/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml
new file mode 100644
index 000000000000..3107fcafcf6a
--- /dev/null
+++ b/Documentation/devicetree/bindings/hwmon/microchip,emc2305.yaml
@@ -0,0 +1,104 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+
+$id: http://devicetree.org/schemas/hwmon/microchip,emc2305.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Microchip EMC2305 SMBus compliant PWM fan controller
+
+maintainers:
+  - Michael Shych <michaelsh@nvidia.com>
+
+description:
+  Microchip EMC2301/2/3/5 pwm controller which supports
+  up to five programmable fan control circuits.
+
+properties:
+  compatible:
+    oneOf:
+      - enum:
+          - microchip,emc2305
+      - items:
+          - enum:
+              - microchip,emc2303
+              - microchip,emc2302
+              - microchip,emc2301
+          - const: microchip,emc2305
+
+  reg:
+    maxItems: 1
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+  '#pwm-cells':
+    const: 2
+
+patternProperties:
+  "^fan@[0-4]$":
+    $ref: fan-common.yaml#
+    unevaluatedProperties: false
+    properties:
+      reg:
+        description:
+          The fan number.
+
+    required:
+      - reg
+      - pwms
+
+required:
+  - compatible
+  - reg
+
+additionalProperties: false
+
+examples:
+  - |
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        fan_controller: fan-controller@2f {
+            compatible = "microchip,emc2305";
+            reg = <0x2f>;
+            #address-cells = <1>;
+            #size-cells = <0>;
+            #pwm-cells = <2>;
+
+            fan@0 {
+                #cooling-cells = <2>;
+                reg = <0x0>;
+                pwms = <&fan_controller 1 1>;
+            };
+
+            fan@1 {
+                #cooling-cells = <2>;
+                reg = <0x1>;
+                pwms = <&fan_controller 1 1>;
+            };
+
+            fan@2 {
+                #cooling-cells = <2>;
+                reg = <0x2>;
+                pwms = <&fan_controller 1 1>;
+            };
+
+            fan@3 {
+                #cooling-cells = <2>;
+                reg = <0x3>;
+                pwms = <&fan_controller 1 1>;
+            };
+
+            fan@4 {
+                #cooling-cells = <2>;
+                reg = <0x4>;
+                pwms = <&fan_controller 1 1>;
+            };
+        };
+    };
+...