[nrf fromlist] drivers: modem: Implement runtime power management for CMUX

CMUX driver can enable the support for idle-timer in
devicetree and can be requested to shut down the pipe
during sleep.

Then UART backend put the actual device into sleep when
pipe is closed.

Waking up is requested by sending data to DLC pipe
or by manually opening the uart_pipe.
Modem may request similar wake-up by a RING interrupt which
would open the same pipe.

When UART is powered and pipe is not closed, CMUX wake-up
procedure is automatic. Either end may initiate the wake-up.

Upstream PR #: 97362

Signed-off-by: Seppo Takalo <[email protected]>

Author: SeppoTakalo

drivers/modem/modem_cellular.c

@@ -17,6 +17,8 @@
 #include <zephyr/modem/backend/uart.h>
 #include <zephyr/net/ppp.h>
 #include <zephyr/pm/device.h>
+#include <zephyr/pm/device.h>
+#include <zephyr/pm/device_runtime.h>
 #include <zephyr/sys/atomic.h>
 
 #include <zephyr/logging/log.h>
@@ -191,6 +193,9 @@ struct modem_cellular_config {
 	uint16_t startup_time_ms;
 	uint16_t shutdown_time_ms;
 	bool autostarts;
+	bool cmux_enable_runtime_power_save;
+	bool cmux_close_pipe_on_power_save;
+	k_timeout_t cmux_idle_timeout;
 	const struct modem_chat_script *init_chat_script;
 	const struct modem_chat_script *dial_chat_script;
 	const struct modem_chat_script *periodic_chat_script;
@@ -2102,7 +2107,6 @@ static int modem_cellular_init(const struct device *dev)
 
 	k_mutex_init(&data->api_lock);
 	k_work_init_delayable(&data->timeout_work, modem_cellular_timeout_handler);
-
 	k_work_init(&data->event_dispatch_work, modem_cellular_event_dispatch_handler);
 	ring_buf_init(&data->event_rb, sizeof(data->event_buf), data->event_buf);
 
@@ -2149,6 +2153,9 @@ static int modem_cellular_init(const struct device *dev)
 			.receive_buf_size = ARRAY_SIZE(data->cmux_receive_buf),
 			.transmit_buf = data->cmux_transmit_buf,
 			.transmit_buf_size = ARRAY_SIZE(data->cmux_transmit_buf),
+			.enable_runtime_power_management = config->cmux_enable_runtime_power_save,
+			.close_pipe_on_power_save = config->cmux_close_pipe_on_power_save,
+			.idle_timeout = config->cmux_idle_timeout,
 		};
 
 		modem_cmux_init(&data->cmux, &cmux_config);
@@ -2886,11 +2893,8 @@ MODEM_CHAT_SCRIPT_DEFINE(sqn_gm02s_periodic_chat_script,
 
 /* Helper to define modem instance */
 #define MODEM_CELLULAR_DEFINE_INSTANCE(inst, power_ms, reset_ms, startup_ms, shutdown_ms, start,   \
-				       set_baudrate_script,                                        \
-				       init_script,                                                \
-				       dial_script,                                                \
-				       periodic_script,                                            \
-				       shutdown_script)                                            \
+				       set_baudrate_script, init_script, dial_script,              \
+				       periodic_script, shutdown_script)                           \
 	static const struct modem_cellular_config MODEM_CELLULAR_INST_NAME(config, inst) = {       \
 		.uart = DEVICE_DT_GET(DT_INST_BUS(inst)),                                          \
 		.power_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_power_gpios, {}),                 \
@@ -2899,14 +2903,19 @@ MODEM_CHAT_SCRIPT_DEFINE(sqn_gm02s_periodic_chat_script,
 		.dtr_gpio = GPIO_DT_SPEC_INST_GET_OR(inst, mdm_dtr_gpios, {}),                     \
 		.power_pulse_duration_ms = (power_ms),                                             \
 		.reset_pulse_duration_ms = (reset_ms),                                             \
-		.startup_time_ms  = (startup_ms),                                                  \
+		.startup_time_ms = (startup_ms),                                                   \
 		.shutdown_time_ms = (shutdown_ms),                                                 \
 		.autostarts = DT_INST_PROP_OR(inst, autostarts, (start)),                          \
-		.set_baudrate_chat_script    = (set_baudrate_script),                              \
-		.init_chat_script            = (init_script),                                      \
-		.dial_chat_script            = (dial_script),                                      \
+		.cmux_enable_runtime_power_save =                                                  \
+			DT_INST_PROP_OR(inst, cmux_enable_runtime_power_save, 0),                  \
+		.cmux_close_pipe_on_power_save =                                                   \
+			DT_INST_PROP_OR(inst, cmux_close_pipe_on_power_save, 0),                   \
+		.cmux_idle_timeout = K_MSEC(DT_INST_PROP_OR(inst, cmux_idle_timeout_ms, 0)),       \
+		.set_baudrate_chat_script = (set_baudrate_script),                                 \
+		.init_chat_script = (init_script),                                                 \
+		.dial_chat_script = (dial_script),                                                 \
 		.periodic_chat_script = (periodic_script),                                         \
-		.shutdown_chat_script  = (shutdown_script),                                        \
+		.shutdown_chat_script = (shutdown_script),                                         \
 		.user_pipes = MODEM_CELLULAR_GET_USER_PIPES(inst),                                 \
 		.user_pipes_size = ARRAY_SIZE(MODEM_CELLULAR_GET_USER_PIPES(inst)),                \
 	};                                                                                         \

dts/bindings/modem/zephyr,cellular-modem-device.yaml

@@ -25,3 +25,22 @@ properties:
 
       Asserted (logical high) when UART is active and
       deasserted (logical low) when UART is inactive, powered down or in low power mode.
+
+  cmux-enable-runtime-power-save:
+    type: boolean
+    description: |
+      Enable runtime power saving using CMUX PSC commands.
+      This requires modem to support CMUX and PSC commands while keeping the data
+      connection active.
+
+  cmux-close-pipe-on-power-save:
+    type: boolean
+    description: |
+      Close the modem pipe when entering power save mode.
+      When runtime power management is enabled, this closes the UART.
+      This requires modem to support waking up the UART using RING signal.
+
+  cmux-idle-timeout-ms:
+    type: int
+    description: Time in milliseconds after which CMUX will enter power save mode.
+    default: 10000

include/zephyr/modem/cmux.h

@@ -159,6 +159,12 @@ struct modem_cmux {
 	enum modem_cmux_state state;
 	bool flow_control_on : 1;
 	bool initiator : 1;
+	/** Enable runtime power management */
+	bool enable_runtime_power_management;
+	/** Close pipe on power save */
+	bool close_pipe_on_power_save;
+	/** Idle timeout for power save */
+	k_timeout_t idle_timeout;
 
 	/* Work lock */
 	bool attached : 1;
@@ -188,10 +194,12 @@ struct modem_cmux {
 	struct k_work_delayable transmit_work;
 	struct k_work_delayable connect_work;
 	struct k_work_delayable disconnect_work;
+	struct k_work_delayable runtime_pm_work;
 
 	/* Synchronize actions */
 	struct k_event event;
 	k_timepoint_t t3_timepoint;
+	k_timepoint_t idle_timepoint;
 
 	/* Statistics */
 #if CONFIG_MODEM_STATS
@@ -220,6 +228,12 @@ struct modem_cmux_config {
 	uint8_t *transmit_buf;
 	/** Size of transmit buffer in bytes [149, ...] */
 	uint16_t transmit_buf_size;
+	/** Enable runtime power management */
+	bool enable_runtime_power_management;
+	/** Close pipe on power save */
+	bool close_pipe_on_power_save;
+	/** Idle timeout for power save */
+	k_timeout_t idle_timeout;
 };
 
 /**

subsys/modem/backends/modem_backend_uart_async.c

@@ -11,6 +11,7 @@
 LOG_MODULE_REGISTER(modem_backend_uart_async, CONFIG_MODEM_MODULES_LOG_LEVEL);
 
 #include <zephyr/kernel.h>
+#include <zephyr/pm/device_runtime.h>
 #include <zephyr/drivers/gpio.h>
 #include <string.h>
 
@@ -158,6 +159,11 @@ static int modem_backend_uart_async_open(void *data)
 	atomic_clear(&backend->async.common.state);
 	ring_buf_reset(&backend->async.receive_rb);
 
+	ret = pm_device_runtime_get(backend->uart);
+	if (ret < 0) {
+		LOG_ERR("Failed to power on UART: %d", ret);
+		return ret;
+	}
 	if (backend->dtr_gpio) {
 		gpio_pin_set_dt(backend->dtr_gpio, 1);
 	}
@@ -269,13 +275,20 @@ static int modem_backend_uart_async_receive(void *data, uint8_t *buf, size_t siz
 static int modem_backend_uart_async_close(void *data)
 {
 	struct modem_backend_uart *backend = (struct modem_backend_uart *)data;
+	int ret;
 
 	atomic_clear_bit(&backend->async.common.state, MODEM_BACKEND_UART_ASYNC_STATE_OPEN_BIT);
 	uart_tx_abort(backend->uart);
 	uart_rx_disable(backend->uart);
 	if (backend->dtr_gpio) {
 		gpio_pin_set_dt(backend->dtr_gpio, 0);
 	}
+	ret = pm_device_runtime_put_async(backend->uart, K_NO_WAIT);
+	if (ret < 0) {
+		LOG_ERR("Failed to power off UART: %d", ret);
+		return ret;
+	}
+	modem_pipe_notify_closed(&backend->pipe);
 	return 0;
 }
 

subsys/modem/backends/modem_backend_uart_async_hwfc.c

@@ -11,6 +11,7 @@
 LOG_MODULE_REGISTER(modem_backend_uart_async_hwfc, CONFIG_MODEM_MODULES_LOG_LEVEL);
 
 #include <zephyr/kernel.h>
+#include <zephyr/pm/device_runtime.h>
 #include <zephyr/drivers/gpio.h>
 #include <string.h>
 
@@ -222,6 +223,11 @@ static int modem_backend_uart_async_hwfc_open(void *data)
 		return -ENOMEM;
 	}
 
+	ret = pm_device_runtime_get(backend->uart);
+	if (ret < 0) {
+		LOG_ERR("Failed to power on UART: %d", ret);
+		return ret;
+	}
 	if (backend->dtr_gpio) {
 		gpio_pin_set_dt(backend->dtr_gpio, 1);
 	}
@@ -352,6 +358,7 @@ static int modem_backend_uart_async_hwfc_receive(void *data, uint8_t *buf, size_
 static int modem_backend_uart_async_hwfc_close(void *data)
 {
 	struct modem_backend_uart *backend = (struct modem_backend_uart *)data;
+	int ret;
 
 	atomic_clear_bit(&backend->async.common.state, MODEM_BACKEND_UART_ASYNC_STATE_OPEN_BIT);
 	uart_tx_abort(backend->uart);
@@ -365,6 +372,13 @@ static int modem_backend_uart_async_hwfc_close(void *data)
 	if (backend->dtr_gpio) {
 		gpio_pin_set_dt(backend->dtr_gpio, 0);
 	}
+	ret = pm_device_runtime_put_async(backend->uart, K_NO_WAIT);
+	if (ret < 0) {
+		LOG_ERR("Failed to power off UART: %d", ret);
+		return ret;
+	}
+	modem_pipe_notify_closed(&backend->pipe);
+
 	return 0;
 }