PoE HAT driver cleanup

* Fix undeclared variable in rpi_poe_fan_suspend
* Add SPDX-License-Identifier
* Expand PoE acronym in Kconfig help
* Give clearer error message on of_property_count_u32_elems fail
* Add documentation
* Add vendor to of_device_id compatible string.
* Rename m_data_s struct to fw_data_s
* Fix typos

Fixes: #2665

Signed-off-by: Serge Schneider <[email protected]>

Author: XECDesign

Documentation/devicetree/bindings/hwmon/rpi-poe-fan.txt

@@ -0,0 +1,55 @@
+Bindings for the Raspberry Pi PoE HAT fan
+
+Required properties:
+- compatible	: "raspberrypi,rpi-poe-fan"
+- firmware	: Reference to the RPi firmware device node
+- pwms		: the PWM that is used to control the PWM fan
+- cooling-levels      : PWM duty cycle values in a range from 0 to 255
+			which correspond to thermal cooling states
+
+Example:
+	fan0: rpi-poe-fan@0 {
+		compatible = "raspberrypi,rpi-poe-fan";
+		firmware = <&firmware>;
+		cooling-min-state = <0>;
+		cooling-max-state = <3>;
+		#cooling-cells = <2>;
+		cooling-levels = <0 50 150 255>;
+		status = "okay";
+	};
+
+	thermal-zones {
+		cpu_thermal: cpu-thermal {
+			trips {
+				threshold: trip-point@0 {
+					temperature = <45000>;
+					hysteresis = <5000>;
+					type = "active";
+				};
+				target: trip-point@1 {
+					temperature = <50000>;
+					hysteresis = <2000>;
+					type = "active";
+				};
+				cpu_hot: cpu_hot@0 {
+					temperature = <55000>;
+					hysteresis = <2000>;
+					type = "active";
+				};
+			};
+			cooling-maps {
+				map0 {
+					trip = <&threshold>;
+					cooling-device = <&fan0 0 1>;
+				};
+				map1 {
+					trip = <&target>;
+					cooling-device = <&fan0 1 2>;
+				};
+				map2 {
+					trip = <&cpu_hot>;
+					cooling-device = <&fan0 2 3>;
+				};
+			};
+		};
+	};

Documentation/hwmon/rpi-poe-fan

@@ -0,0 +1,15 @@
+Kernel driver rpi-poe-fan
+=====================
+
+This driver enables the use of the Raspberry Pi PoE HAT fan.
+
+Author: Serge Schneider <[email protected]>
+
+Description
+-----------
+
+The driver implements a simple interface for driving the Raspberry Pi PoE
+(Power over Ethernet) HAT fan. The driver passes commands to the Raspberry Pi
+firmware through the mailbox property interface. The firmware then forwards
+the commands to the board over I2C on the ID_EEPROM pins. The driver exposes
+the fan to the user space through the hwmon sysfs interface.

arch/arm/boot/dts/overlays/rpi-poe-overlay.dts

@@ -11,7 +11,7 @@
 		target-path = "/";
 		__overlay__ {
 			fan0: rpi-poe-fan@0 {
-				compatible = "rpi-poe-fan";
+				compatible = "raspberrypi,rpi-poe-fan";
 				firmware = <&firmware>;
 				cooling-min-state = <0>;
 				cooling-max-state = <3>;

drivers/hwmon/Kconfig

@@ -1287,11 +1287,12 @@ config SENSORS_PWM_FAN
 	  will be called pwm-fan.
 
 config SENSORS_RPI_POE_FAN
-	tristate "Raspberry Pi POE HAT fan"
+	tristate "Raspberry Pi PoE HAT fan"
 	depends on RASPBERRYPI_FIRMWARE
 	depends on THERMAL || THERMAL=n
 	help
-	  If you say yes here you get support for Raspberry Pi POE HAT fan.
+	  If you say yes here you get support for Raspberry Pi PoE (Power over
+	  Ethernet) HAT fan.
 
 	  This driver can also be built as a module.  If so, the module
 	  will be called rpi-poe-fan.

drivers/hwmon/rpi-poe-fan.c

@@ -1,20 +1,11 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
- * rpi-poe-fan.c - Hwmon driver for Raspberry Pi POE HAT fan.
+ * rpi-poe-fan.c - Hwmon driver for Raspberry Pi PoE HAT fan.
  *
  * Copyright (C) 2018 Raspberry Pi (Trading) Ltd.
  * Based on pwm-fan.c by Kamil Debski <[email protected]>
  *
  * Author: Serge Schneider <[email protected]>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
  */
 
 #include <linux/hwmon.h>
@@ -46,41 +37,41 @@ struct rpi_poe_fan_ctx {
 	struct notifier_block nb;
 };
 
-struct m_data_s{
+struct fw_tag_data_s{
 	u32 reg;
 	u32 val;
 	u32 ret;
 };
 
 static int write_reg(struct rpi_firmware *fw, u32 reg, u32 *val){
-	struct m_data_s m_data = {
+	struct fw_tag_data_s fw_tag_data = {
 		.reg = reg,
 		.val = *val
 	};
 	int ret;
 	ret = rpi_firmware_property(fw, RPI_FIRMWARE_SET_POE_HAT_VAL,
-				    &m_data, sizeof(m_data));
+				    &fw_tag_data, sizeof(fw_tag_data));
 	if (ret) {
 		return ret;
-	} else if (m_data.ret) {
+	} else if (fw_tag_data.ret) {
 		return -EIO;
 	}
 	return 0;
 }
 
 static int read_reg(struct rpi_firmware *fw, u32 reg, u32 *val){
-	struct m_data_s m_data = {
+	struct fw_tag_data_s fw_tag_data = {
 		.reg = reg,
 	};
 	int ret;
 	ret = rpi_firmware_property(fw, RPI_FIRMWARE_GET_POE_HAT_VAL,
-				    &m_data, sizeof(m_data));
+				    &fw_tag_data, sizeof(fw_tag_data));
 	if (ret) {
 		return ret;
-	} else if (m_data.ret) {
+	} else if (fw_tag_data.ret) {
 		return -EIO;
 	}
-	*val = m_data.val;
+	*val = fw_tag_data.val;
 	return 0;
 }
 
@@ -268,7 +259,8 @@ static int rpi_poe_fan_of_get_cooling_data(struct device *dev,
 
 	ret = of_property_count_u32_elems(np, "cooling-levels");
 	if (ret <= 0) {
-		dev_err(dev, "Wrong data!\n");
+		dev_err(dev, "cooling-levels property missing or invalid: %d\n",
+			ret);
 		return ret ? : -EINVAL;
 	}
 
@@ -397,10 +389,11 @@ static int rpi_poe_fan_suspend(struct device *dev)
 {
 	struct rpi_poe_fan_ctx *ctx = dev_get_drvdata(dev);
 	u32 value = 0;
+	int ret = 0;
 
 	if (ctx->pwm_value != value)
 		ret = write_reg(ctx->fw, POE_CUR_PWM, &value);
-	return 0;
+	return ret;
 }
 
 static int rpi_poe_fan_resume(struct device *dev)
@@ -420,7 +413,7 @@ static SIMPLE_DEV_PM_OPS(rpi_poe_fan_pm, rpi_poe_fan_suspend,
 			 rpi_poe_fan_resume);
 
 static const struct of_device_id of_rpi_poe_fan_match[] = {
-	{ .compatible = "rpi-poe-fan", },
+	{ .compatible = "raspberrypi,rpi-poe-fan", },
 	{},
 };
 MODULE_DEVICE_TABLE(of, of_rpi_poe_fan_match);
@@ -439,5 +432,5 @@ module_platform_driver(rpi_poe_fan_driver);
 
 MODULE_AUTHOR("Serge Schneider <[email protected]>");
 MODULE_ALIAS("platform:rpi-poe-fan");
-MODULE_DESCRIPTION("Raspberry Pi POE HAT fan driver");
+MODULE_DESCRIPTION("Raspberry Pi PoE HAT fan driver");
 MODULE_LICENSE("GPL");