drivers: regulator: add parent DVS API

PCA9420 PMIC offers of multiple operation states, or DVS (Dynamic
Voltage Scaling). Such states may be automatically changed by hardware
using MODESEL0/1 pins. Certain MCUs allow to automatically configure
certain output pins when entering low power modes so that PMIC state is
changed without software intervention.  This means that application just
needs to configure the voltages for each state using
`nxp,modeN-microvolt`, set `nxp,enable-modesel-pins` in devicetree and
forget about configuring regulators.

This patch introduces a new _parent_ API to expose such functionality in
a vendor agnostic way. Consider this API as experimental for now, until
we have other usecases.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>

boards/arm/mimxrt595_evk/mimxrt595_evk_cm33.dts

@@ -7,7 +7,6 @@
 /dts-v1/;
 
 #include <nxp/nxp_rt5xx.dtsi>
-#include <zephyr/dt-bindings/regulator/pca9420.h>
 
 #include "mimxrt595_evk_cm33-pinctrl.dtsi"
 

boards/arm/mimxrt685_evk/mimxrt685_evk_cm33.dts

@@ -8,7 +8,6 @@
 
 #include <nxp/nxp_rt6xx.dtsi>
 #include <zephyr/dt-bindings/pwm/pwm.h>
-#include <zephyr/dt-bindings/regulator/pca9420.h>
 
 #include "mimxrt685_evk_cm33-pinctrl.dtsi"
 

drivers/regulator/regulator_pca9420.c

@@ -10,7 +10,7 @@
 #include <zephyr/kernel.h>
 #include <zephyr/drivers/i2c.h>
 #include <zephyr/drivers/regulator.h>
-#include <zephyr/dt-bindings/regulator/pca9420.h>
+#include <zephyr/drivers/regulator/pca9420.h>
 #include <zephyr/sys/linear_range.h>
 #include <zephyr/sys/util.h>
 
@@ -104,13 +104,10 @@ struct regulator_pca9420_common_config {
 	bool enable_modesel_pins;
 };
 
-struct regulator_pca9420_common_data {
-	regulator_mode_t mode;
-};
-
 struct regulator_pca9420_config {
 	struct regulator_common_config common;
 	bool enable_inverted;
+	int32_t modes_uv[4];
 	const struct regulator_pca9420_desc *desc;
 	const struct device *parent;
 };
@@ -214,7 +211,6 @@ static int regulator_pca9420_set_voltage(const struct device *dev,
 					 int32_t min_uv, int32_t max_uv)
 {
 	const struct regulator_pca9420_config *config = dev->config;
-	struct regulator_pca9420_common_data *cdata = config->parent->data;
 	const struct regulator_pca9420_common_config *cconfig = config->parent->config;
 	uint16_t idx;
 	int ret;
@@ -228,25 +224,20 @@ static int regulator_pca9420_set_voltage(const struct device *dev,
 
 	idx <<= config->desc->vsel_pos;
 
-	return i2c_reg_update_byte_dt(
+	return i2c_reg_update_byte_dt(&cconfig->i2c, config->desc->vsel_reg,
-		&cconfig->i2c,
+				      config->desc->vsel_mask, (uint8_t)idx);
-		config->desc->vsel_reg + PCA9420_MODECFG_OFFSET(cdata->mode),
-		config->desc->vsel_mask, (uint8_t)idx);
 }
 
 static int regulator_pca9420_get_voltage(const struct device *dev,
 					 int32_t *volt_uv)
 {
 	const struct regulator_pca9420_config *config = dev->config;
-	struct regulator_pca9420_common_data *cdata = config->parent->data;
 	const struct regulator_pca9420_common_config *cconfig = config->parent->config;
 	int ret;
 	uint8_t raw_reg;
 
-	ret = i2c_reg_read_byte_dt(
+	ret = i2c_reg_read_byte_dt(&cconfig->i2c, config->desc->vsel_reg,
-		&cconfig->i2c,
+				   &raw_reg);
-		config->desc->vsel_reg + PCA9420_MODECFG_OFFSET(cdata->mode),
-		&raw_reg);
 	if (ret < 0) {
 		return ret;
 	}
@@ -273,34 +264,6 @@ static int regulator_pca9420_get_current_limit(const struct device *dev,
 	return 0;
 }
 
-static int regulator_pca9420_set_mode(const struct device *dev,
-				      regulator_mode_t mode)
-{
-	const struct regulator_pca9420_config *config = dev->config;
-	const struct regulator_pca9420_common_config *cconfig = config->parent->config;
-	struct regulator_pca9420_common_data *cdata = config->parent->data;
-	int ret;
-
-	/* change mode, to allow configuring voltage, but return -EPERM to
-	 * indicate we are not really changing mode, as it is managed externally
-	 */
-	if (cconfig->enable_modesel_pins) {
-		cdata->mode = mode;
-		return -EPERM;
-	}
-
-	ret = i2c_reg_update_byte_dt(&cconfig->i2c, PCA9420_TOP_CNTL3,
-				     mode << PCA9420_TOP_CNTL3_MODE_I2C_POS,
-				     PCA9420_TOP_CNTL3_MODE_I2C_MASK);
-	if (ret < 0) {
-		return ret;
-	}
-
-	cdata->mode = mode;
-
-	return 0;
-}
-
 static int regulator_pca9420_enable(const struct device *dev)
 {
 	const struct regulator_pca9420_config *config = dev->config;
@@ -323,9 +286,20 @@ static int regulator_pca9420_disable(const struct device *dev)
 				      config->desc->enable_mask, dis_val);
 }
 
+static const struct regulator_driver_api api = {
+	.enable = regulator_pca9420_enable,
+	.disable = regulator_pca9420_disable,
+	.count_voltages = regulator_pca9420_count_voltages,
+	.list_voltage = regulator_pca9420_list_voltage,
+	.set_voltage = regulator_pca9420_set_voltage,
+	.get_voltage = regulator_pca9420_get_voltage,
+	.get_current_limit = regulator_pca9420_get_current_limit,
+};
+
 static int regulator_pca9420_init(const struct device *dev)
 {
 	const struct regulator_pca9420_config *config = dev->config;
+	const struct regulator_pca9420_common_config *cconfig = config->parent->config;
 	int rc  = 0;
 
 	regulator_common_data_init(dev);
@@ -334,6 +308,42 @@ static int regulator_pca9420_init(const struct device *dev)
 		return -ENODEV;
 	}
 
+	/* configure mode voltages */
+	for (uint8_t i = 0U; i < ARRAY_SIZE(config->modes_uv); i++) {
+		int ret;
+
+		if (config->modes_uv[i] == 0) {
+			/* disable mode if voltage is 0 */
+			ret = i2c_reg_update_byte_dt(
+				&cconfig->i2c,
+				config->desc->enable_reg + PCA9420_MODECFG_OFFSET(i),
+				config->desc->enable_mask, 0U);
+			if (ret < 0) {
+				return ret;
+			}
+		} else if (config->modes_uv[i] > 0) {
+			uint16_t idx;
+
+			/* program mode voltage */
+			ret = linear_range_group_get_win_index(
+				config->desc->ranges, config->desc->num_ranges,
+				config->modes_uv[i], config->modes_uv[i], &idx);
+			if (ret < 0) {
+				return ret;
+			}
+
+			idx <<= config->desc->vsel_pos;
+
+			ret = i2c_reg_update_byte_dt(
+				&cconfig->i2c,
+				config->desc->vsel_reg + PCA9420_MODECFG_OFFSET(i),
+				config->desc->vsel_mask, (uint8_t)idx);
+			if (ret < 0) {
+				return ret;
+			}
+		}
+	}
+
 	if ((config->common.flags & REGULATOR_INIT_ENABLED) != 0U) {
 		rc = regulator_pca9420_enable(dev);
 	}
@@ -341,10 +351,31 @@ static int regulator_pca9420_init(const struct device *dev)
 	return rc;
 }
 
+int regulator_pca9420_dvs_state_set(const struct device *dev,
+				    regulator_dvs_state_t state)
+{
+	const struct regulator_pca9420_common_config *config = dev->config;
+
+	if (state >= PCA9420_NUM_MODES) {
+		return -ENOTSUP;
+	}
+
+	if (config->enable_modesel_pins) {
+		return -EPERM;
+	}
+
+	return i2c_reg_update_byte_dt(&config->i2c, PCA9420_TOP_CNTL3,
+				      state << PCA9420_TOP_CNTL3_MODE_I2C_POS,
+				      PCA9420_TOP_CNTL3_MODE_I2C_MASK);
+}
+
+static const struct regulator_parent_driver_api parent_api = {
+	.dvs_state_set = regulator_pca9420_dvs_state_set,
+};
+
 static int regulator_pca9420_common_init(const struct device *dev)
 {
 	const struct regulator_pca9420_common_config *config = dev->config;
-	const struct regulator_pca9420_common_data *data = dev->data;
 	uint8_t reg_val = PCA9420_TOP_CNTL0_VIN_ILIM_SEL_DISABLED;
 	int ret;
 
@@ -365,14 +396,6 @@ static int regulator_pca9420_common_init(const struct device *dev)
 				return ret;
 			}
 		}
-	} else {
-		ret = i2c_reg_update_byte_dt(
-			&config->i2c, PCA9420_TOP_CNTL3,
-			data->mode << PCA9420_TOP_CNTL3_MODE_I2C_POS,
-			PCA9420_TOP_CNTL3_MODE_I2C_MASK);
-		if (ret < 0) {
-			return ret;
-		}
 	}
 
 	/* configure VIN current limit */
@@ -387,24 +410,18 @@ static int regulator_pca9420_common_init(const struct device *dev)
 		reg_val << PCA9420_TOP_CNTL0_VIN_ILIM_SEL_POS);
 }
 
-
-static const struct regulator_driver_api api = {
-	.enable = regulator_pca9420_enable,
-	.disable = regulator_pca9420_disable,
-	.count_voltages = regulator_pca9420_count_voltages,
-	.list_voltage = regulator_pca9420_list_voltage,
-	.set_voltage = regulator_pca9420_set_voltage,
-	.get_voltage = regulator_pca9420_get_voltage,
-	.get_current_limit = regulator_pca9420_get_current_limit,
-	.set_mode = regulator_pca9420_set_mode,
-};
-
 #define REGULATOR_PCA9420_DEFINE(node_id, id, name, _parent)                   \
 	static struct regulator_pca9420_data data_##id;                        \
                                                                                \
 	static const struct regulator_pca9420_config config_##id = {           \
 		.common = REGULATOR_DT_COMMON_CONFIG_INIT(node_id),            \
 		.enable_inverted = DT_PROP(node_id, enable_inverted),          \
+		.modes_uv = {                                                  \
+			DT_PROP_OR(node_id, nxp_mode0_microvolt, -1),          \
+			DT_PROP_OR(node_id, nxp_mode1_microvolt, -1),          \
+			DT_PROP_OR(node_id, nxp_mode2_microvolt, -1),          \
+			DT_PROP_OR(node_id, nxp_mode3_microvolt, -1),          \
+		},                                                             \
 		.desc = &name ## _desc,                                        \
 		.parent = _parent,                                             \
 	};                                                                     \
@@ -420,10 +437,6 @@ static const struct regulator_driver_api api = {
 		    ())
 
 #define REGULATOR_PCA9420_DEFINE_ALL(inst)                                     \
-	static struct regulator_pca9420_common_data data_##inst = {            \
-		.mode = 0U                                                     \
-	};                                                                     \
-                                                                               \
 	static const struct regulator_pca9420_common_config config_##inst = {  \
 		.i2c = I2C_DT_SPEC_INST_GET(inst),                             \
 		.vin_ilim_ua = DT_INST_PROP(inst, nxp_vin_ilim_microamp),      \
@@ -431,10 +444,10 @@ static const struct regulator_driver_api api = {
 			DT_INST_PROP(inst, nxp_enable_modesel_pins),           \
 	};                                                                     \
                                                                                \
-	DEVICE_DT_INST_DEFINE(inst, regulator_pca9420_common_init, NULL,       \
+	DEVICE_DT_INST_DEFINE(inst, regulator_pca9420_common_init, NULL, NULL, \
-			      &data_##inst, &config_##inst, POST_KERNEL,       \
+			      &config_##inst, POST_KERNEL,                     \
 			      CONFIG_REGULATOR_PCA9420_COMMON_INIT_PRIORITY,   \
-			      NULL);                                           \
+			      &parent_api);                                    \
                                                                                \
 	REGULATOR_PCA9420_DEFINE_COND(inst, buck1, DEVICE_DT_INST_GET(inst))   \
 	REGULATOR_PCA9420_DEFINE_COND(inst, buck2, DEVICE_DT_INST_GET(inst))   \

dts/bindings/regulator/nxp,pca9420.yaml

@@ -79,3 +79,27 @@ child-binding:
           description: |
             If the enable bit should be zero to turn the regulator on, add this
             property.
+
+      nxp,mode0-microvolt:
+        type: int
+        description: |
+          The voltage level to be configured for mode 0, in microvolts. Setting
+          this value to zero will disable the source in mode 0.
+
+      nxp,mode1-microvolt:
+        type: int
+        description: |
+          The voltage level to be configured for mode 1, in microvolts. Setting
+          this value to zero will disable the source in mode 1.
+
+      nxp,mode2-microvolt:
+        type: int
+        description: |
+          The voltage level to be configured for mode 2, in microvolts. Setting
+          this value to zero will disable the source in mode 2.
+
+      nxp,mode3-microvolt:
+        type: int
+        description: |
+          The voltage level to be configured for mode 3, in microvolts. Setting
+          this value to zero will disable the source in mode 3.

include/zephyr/drivers/regulator.h

@@ -26,11 +26,20 @@
 extern "C" {
 #endif
 
+/** Opaque type to store regulator DVS states */
+typedef uint8_t regulator_dvs_state_t;
+
 /** Opaque type to store regulator modes */
 typedef uint8_t regulator_mode_t;
 
 /** @cond INTERNAL_HIDDEN */
 
+/** @brief Driver-specific API functions to support parent regulator control. */
+__subsystem struct regulator_parent_driver_api {
+	int (*dvs_state_set)(const struct device *dev,
+			     regulator_dvs_state_t state);
+};
+
 /** @brief Driver-specific API functions to support regulator control. */
 __subsystem struct regulator_driver_api {
 	int (*enable)(const struct device *dev);
@@ -146,6 +155,46 @@ void regulator_common_data_init(const struct device *dev);
 
 /** @endcond */
 
+/**
+ * @brief Regulator Parent Interface
+ * @defgroup regulator_parent_interface Regulator Parent Interface
+ * @{
+ */
+
+/**
+ * @brief Set a DVS state.
+ *
+ * Some PMICs feature DVS (Dynamic Voltage Scaling) by allowing to program the
+ * voltage level for multiple states. Such states may be automatically changed
+ * by hardware using GPIO pins. Certain MCUs even allow to automatically
+ * configure specific output pins when entering low-power modes so that PMIC
+ * state is changed without software intervention. This API can be used when
+ * state needs to be changed by software.
+ *
+ * @param dev Parent regulator device instance.
+ * @param state DVS state (vendor specific identifier).
+ *
+ * @retval 0 If successful.
+ * @retval -ENOTSUP If given state is not supported.
+ * @retval -EPERM If state can't be changed by software.
+ * @retval -ENOSYS If function is not implemented.
+ * @retval -errno In case of any other error.
+ */
+static inline int regulator_parent_dvs_state_set(const struct device *dev,
+						 regulator_dvs_state_t state)
+{
+	const struct regulator_parent_driver_api *api =
+		(const struct regulator_parent_driver_api *)dev->api;
+
+	if (api->dvs_state_set == NULL) {
+		return -ENOSYS;
+	}
+
+	return api->dvs_state_set(dev, state);
+}
+
+/** @} */
+
 /**
  * @brief Enable a regulator.
  *
@@ -337,18 +386,10 @@ static inline int regulator_get_current_limit(const struct device *dev,
  * the regulator. Allowed modes may be limited using `regulator-allowed-modes`
  * devicetree property.
  *
- * Some regulators may only allow setting mode externally, but still allow
- * configuring the parameters such as the output voltage. For such devices, this
- * function will return -EPERM, indicating mode can't be changed. However, all
- * future calls to e.g. regulator_set_voltage() will apply to the selected mode.
- *
- * Some regulators may apply a mode to all of its regulators simultaneously.
- *
  * @param dev Regulator device instance.
  * @param mode Mode to select for this regulator.
  *
  * @retval 0 If successful.
- * @retval -EPERM If mode can not be changed.
  * @retval -ENOTSUP If mode is not supported.
  * @retval -ENOSYS If function is not implemented.
  * @retval -errno In case of any other error.

include/zephyr/drivers/regulator/pca9420.h

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2022 Nordic Semiconductor ASA
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DRIVERS_REGULATOR_PCA9420_H_
+#define ZEPHYR_INCLUDE_DRIVERS_REGULATOR_PCA9420_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup regulator_parent_pca9420 PCA9420 Utilities.
+ * @ingroup regulator_parent_interface
+ * @{
+ */
+
+/** @brief DVS state 'MODE0' */
+#define REGULATOR_PCA9420_DVS_MODE0 0
+/** @brief DVS state 'MODE1' */
+#define REGULATOR_PCA9420_DVS_MODE1 1
+/** @brief DVS state 'MODE2' */
+#define REGULATOR_PCA9420_DVS_MODE2 2
+/** @brief DVS state 'MODE3' */
+#define REGULATOR_PCA9420_DVS_MODE3 3
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_INCLUDE_DRIVERS_REGULATOR_PCA9420_H_ */

include/zephyr/dt-bindings/regulator/pca9420.h

@@ -1,28 +0,0 @@
-/*
- * Copyright (c) 2021, NXP
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-
-#ifndef ZEPHYR_INCLUDE_DT_BINDINGS_REGULATOR_PCA9420_H_
-#define ZEPHYR_INCLUDE_DT_BINDINGS_REGULATOR_PCA9420_H_
-
-/**
- * @defgroup regulator_pca9420 PCA9420 Devicetree helpers.
- * @ingroup regulator_interface
- * @{
- */
-
-/**
- * @name PCA9420 Regulator modes
- * @{
- */
-#define PCA9420_MODE0 0
-#define PCA9420_MODE1 1
-#define PCA9420_MODE2 2
-#define PCA9420_MODE3 3
-/** @} */
-
-/** @} */
-
-#endif /* ZEPHYR_INCLUDE_DT_BINDINGS_REGULATOR_PCA9420_H_*/