[PATCH v3 05/14] drm/solomon: ssd16xx: Add clear_on_init/close/disable session management

[Devarsh Thakkar <devarsht@ti.com>]

E-paper displays are bistable: the last rendered image persists
indefinitely across sessions and power cycles. This creates a session
management choice with no LCD/OLED equivalent since unlike volatile
displays, content visibility outlives the rendering process. Whether this
persistence is a feature or a liability depends entirely on the
application.

Add session-lifetime display clearing with three configurable hooks:
clear_on_init: blank the display when a new DRM master opens the device.
Useful for kiosks and applications that need a clean slate on startup.
Example: a hospital patient room sign must start with a clean slate when a
new patient is admitted, discarding the previous patient's name, dietary
restrictions, and risk warnings.

  clear_on_close: blank the display when the DRM master exits (fd close).
Useful for applications that should not leave content visible after exit.
Example: a transit departure board at a remote bus stop must erase stale
schedule data when the service daemon is stopped — displaying yesterday's
departure times actively misleads commuters.

  clear_on_disable: blank the display on CRTC disable / DPMS off.  Provides
an independent clear point separate from master lifecycle.  Example: When
userspace trigger DPMS off, similar to LCD screen, here with the epaper
too, the display would be cleared.

These hooks help enabling diverse use cases:

  - A conference badge sets clear_on_init but leaves clear_on_close
    disabled, leveraging e-paper's bistability to keep the attendee's name
visible indefinitely after the rendering app exits — saving power while
remaining useful.

  - A hospital patient room sign sets both clear_on_init and
    clear_on_close: a clean slate for the new patient and automatic erasure
on discharge so protected health information does not persist on the
display outside the door.

  - An airport boarding pass kiosk sets clear_on_close so the previous
    passenger's name, booking reference, and seat assignment are erased the
moment the session ends — preventing the next person in the queue from
seeing personal travel information.

  - A meeting room booking display sets clear_on_disable so the schedule is
    wiped when the room session ends via DPMS off, independent of whether
the calendar sync daemon continues running.

Each is an integer selecting the refresh waveform for the clear (-1 =
disabled, 0 = partial, 1 = full, 2 = fast), defaulting to -1 (disabled) in
the panel configuration so the behaviour is opt-in.  A
display_cleared_on_deinit guard prevents redundant double-clears when
multiple paths fire for the same session (e.g. compositor does DPMS off
then exits). first_clear_done ensures clear_on_init fires exactly once per
client session; master_drop resets it so the next client gets a fresh
clear.

All three default to -1 (disabled) in the panel configuration so the
behaviour is opt-in per panel and does not affect panels that have not set
an explicit default.

Signed-off-by: Devarsh Thakkar <devarsht@ti.com>
---
Changes in v3:
- Split display_cleared_on_deinit into cleared_on_disable and
  cleared_on_close. A single flag made a clear on disable suppress the
clear on close and was never re-armed on re-enable
- Add the atomic_disable helper here, with drm_dev_enter()/drm_dev_exit()
- Reset the RAM window before clearing and size the clear buffer per row
- In 3-colour mode clear the red RAM to 0x00 (no red) instead of writing
  the all-white buffer to it, which would paint the panel red. In
black/white mode it keeps the white buffer, as it is the previous-frame
reference for partial refresh
---
 drivers/gpu/drm/solomon/ssd16xx.c | 208 ++++++++++++++++++++++++++++++
 1 file changed, 208 insertions(+)

diff --git a/drivers/gpu/drm/solomon/ssd16xx.c b/drivers/gpu/drm/solomon/ssd16xx.c
index ca6550b5dd5b..7b0096448768 100644
--- a/drivers/gpu/drm/solomon/ssd16xx.c
+++ b/drivers/gpu/drm/solomon/ssd16xx.c
@@ -298,6 +298,18 @@ struct ssd16xx_device_config {
 	/* Whether to re-send border waveform command before each display update */
 	bool default_border_refresh_on_every_update;
 
+	/*
+	 * Default clear-on-init behaviour.
+	 * -1=disabled, 0=partial, 1=full, 2=fast (matches enum ssd16xx_refresh_mode)
+	 */
+	int default_clear_on_init;
+
+	/* Default clear-on-close behaviour (-1=disabled, 0=partial, 1=full, 2=fast) */
+	int default_clear_on_close;
+
+	/* Default clear-on-disable behaviour (-1=disabled, 0=partial, 1=full, 2=fast) */
+	int default_clear_on_disable;
+
 	/*
 	 * Default refresh-mode-init: -1=disabled, else skip baseline establishment
 	 * and start directly in this refresh mode.
@@ -347,6 +359,9 @@ struct ssd16xx_device {
 
 	bool initialized;
 	bool init_refresh_pending; /* First frame after refresh_mode_init enable */
+	bool first_clear_done;  /* clear_on_init has already fired once */
+	bool cleared_on_disable; /* Avoid redundant clear in atomic_disable */
+	bool cleared_on_close;   /* Avoid redundant clear in master_drop */
 
 	int orientation; /* Display orientation in degrees: 0/90/180/270 */
 	enum ssd16xx_refresh_mode refresh_mode; /* Active refresh mode */
@@ -360,6 +375,9 @@ struct ssd16xx_device {
 	bool border_waveform_pending;   /* One-shot: send border cmd on next update */
 
 	/* Display control */
+	int clear_on_init;    /* -1=disabled, 0=partial, 1=full, 2=fast */
+	int clear_on_close;   /* -1=disabled, 0=partial, 1=full, 2=fast */
+	int clear_on_disable; /* -1=disabled, 0=partial, 1=full, 2=fast */
 	int refresh_mode_init; /* -1=disabled, else use this mode for the first frame */
 
 	u8  *tx_buf;     /* 1bpp frame buffer (mono + white) */
@@ -417,6 +435,9 @@ static const struct ssd16xx_device_config ssd16xx_device_configs[] = {
 		.default_border_waveform_init   = SSD16XX_BORDER_LUT1,  /* white, clean clear */
 		.default_border_waveform_update = SSD16XX_BORDER_HIZ,   /* floating, preserve */
 		.default_border_refresh_on_every_update = false,
+		.default_clear_on_init    = -1,
+		.default_clear_on_close   = -1,
+		.default_clear_on_disable = -1,
 		.default_refresh_mode_init = SSD16XX_REFRESH_FULL,
 		.red_supported = false,  /* 2-colour black/white panel */
 		.default_color_mode = SSD16XX_COLOR_MODE_BW,
@@ -754,6 +775,138 @@ static int ssd16xx_hw_init(struct ssd16xx_device *device)
 	return err;
 }
 
+/*
+ * Clear display by writing all-white to both BW and RED RAM.
+ * The ctrl2 argument selects the waveform (full/partial/fast refresh).
+ * Border waveform is set to init value before clearing, then restored
+ * to the update value to preserve the border during subsequent updates.
+ */
+static int ssd16xx_clear_display(struct ssd16xx_device *device, u8 ctrl2)
+{
+	const u8 *bw_tbl = device->controller_cfg->border_waveform_table;
+	int err = 0;
+	unsigned int data_size = DIV_ROUND_UP(device->width, 8) * device->height;
+	u8 *white_buffer = device->tx_buf;
+	u8 *red_buffer = white_buffer;
+	u16 ram_x_end, ram_y_end;
+
+	memset(white_buffer, 0xFF, data_size);
+
+	if (device->controller_cfg->ram_x_address_bits == 8)
+		ram_x_end = (device->width / 8) - 1;
+	else
+		ram_x_end = device->width - 1;
+	ram_y_end = device->height - 1;
+
+	/* Reset full display RAM window before clearing */
+	ssd16xx_send_cmd(device, SSD16XX_CMD_SET_RAM_X_ADDRESS_START_END, &err);
+	ssd16xx_send_x_param(device, 0x00, &err);
+	ssd16xx_send_x_param(device, ram_x_end, &err);
+
+	ssd16xx_send_cmd(device, SSD16XX_CMD_SET_RAM_Y_ADDRESS_START_END, &err);
+	ssd16xx_send_y_param(device, 0x00, &err);
+	ssd16xx_send_y_param(device, ram_y_end, &err);
+
+	ssd16xx_send_cmd(device, SSD16XX_CMD_SET_RAM_X_ADDRESS_COUNTER, &err);
+	ssd16xx_send_x_param(device, 0x00, &err);
+
+	ssd16xx_send_cmd(device, SSD16XX_CMD_SET_RAM_Y_ADDRESS_COUNTER, &err);
+	ssd16xx_send_y_param(device, 0x00, &err);
+
+	ssd16xx_send_cmd(device, SSD16XX_CMD_WRITE_RAM_BW, &err);
+	ssd16xx_send_data_bulk(device, white_buffer, data_size, &err);
+
+	/*
+	 * In 3-colour mode RED RAM is the red plane, so clear it to 0x00 (no
+	 * red).  Otherwise it is the previous-frame reference for partial
+	 * refresh and must match the now all-white BW RAM.
+	 */
+	if (device->color_mode == SSD16XX_COLOR_MODE_3COLOR && device->tx_red_buf) {
+		red_buffer = device->tx_red_buf;
+		memset(red_buffer, 0x00, data_size);
+	}
+
+	ssd16xx_send_cmd(device, SSD1683_CMD_WRITE_RAM_RED, &err);
+	ssd16xx_send_data_bulk(device, red_buffer, data_size, &err);
+
+	/* Set border waveform for the clear operation */
+	drm_dbg(&device->drm, "clear_display: Set border init waveform: 0x%02x\n",
+		bw_tbl[device->border_waveform_init_idx]);
+	ssd16xx_send_cmd(device, SSD16XX_CMD_BORDER_WAVEFORM_CONTROL, &err);
+	ssd16xx_send_data(device,
+			  bw_tbl[device->border_waveform_init_idx],
+			  &err);
+
+	/* 3-colour mode: CTRL1_NORMAL (read both RAMs); BW mode: bypass RED. */
+	ssd16xx_display_update(device,
+			       device->color_mode == SSD16XX_COLOR_MODE_3COLOR
+					? device->controller_cfg->ctrl1_normal
+					: device->controller_cfg->ctrl1_bypass_red_ram,
+			       SSD16XX_CTRL1_BYTE2_DEFAULT, ctrl2, &err);
+
+	/* Restore border waveform to update/preservation value */
+	drm_dbg(&device->drm, "clear_display: Restored border update waveform: 0x%02x\n",
+		bw_tbl[device->border_waveform_update_idx]);
+	ssd16xx_send_cmd(device, SSD16XX_CMD_BORDER_WAVEFORM_CONTROL, &err);
+	ssd16xx_send_data(device,
+			  bw_tbl[device->border_waveform_update_idx],
+			  &err);
+
+	return err;
+}
+
+static u8 ssd16xx_refresh_mode_to_ctrl2(struct ssd16xx_device *device,
+					enum ssd16xx_refresh_mode mode)
+{
+	if (mode < ARRAY_SIZE(device->controller_cfg->ctrl2_refresh))
+		return device->controller_cfg->ctrl2_refresh[mode];
+	return device->controller_cfg->ctrl2_refresh[SSD16XX_REFRESH_FULL];
+}
+
+/*
+ * Clear display on new DRM master open (if clear_on_init >= 0).
+ * Guarded by device->first_clear_done; master_drop resets it unconditionally
+ * so each new client session gets a fresh clear.
+ */
+static int ssd16xx_clear_display_on_init(struct ssd16xx_device *device)
+{
+	int ret;
+
+	if (device->clear_on_init < 0 || device->first_clear_done)
+		return 0;
+
+	drm_dbg(&device->drm, "clear_on_init: running, mode=%d\n",
+		device->clear_on_init);
+	ret = ssd16xx_clear_display(device,
+				    ssd16xx_refresh_mode_to_ctrl2(device, device->clear_on_init));
+	if (ret)
+		return ret;
+
+	device->first_clear_done = true;
+	return 0;
+}
+
+/*
+ * Clear display when the displaying client exits (if clear_on_close >= 0).
+ * Called from ssd16xx_drm_master_drop().
+ */
+static int ssd16xx_clear_display_on_exit(struct ssd16xx_device *device)
+{
+	int ret;
+
+	if (device->clear_on_close < 0)
+		return 0;
+
+	drm_dbg(&device->drm, "clear_on_close: running, mode=%d\n",
+		device->clear_on_close);
+	ret = ssd16xx_clear_display(device,
+				    ssd16xx_refresh_mode_to_ctrl2(device, device->clear_on_close));
+	if (ret)
+		return ret;
+
+	return 0;
+}
+
 /*
  * ssd16xx_pixel_luma() - return ITU-R BT.601 luminance (0-255) for one pixel.
  *
@@ -1367,6 +1520,33 @@ static int ssd16xx_crtc_atomic_check(struct drm_crtc *crtc,
 	return drm_atomic_helper_check_crtc_primary_plane(new_crtc_state);
 }
 
+static void ssd16xx_crtc_atomic_disable(struct drm_crtc *crtc,
+					struct drm_atomic_commit *state)
+{
+	struct ssd16xx_device *device = crtc_to_ssd16xx_device(crtc);
+	int ret, idx;
+
+	if (!drm_dev_enter(&device->drm, &idx))
+		return;
+
+	if (device->clear_on_disable < 0 || device->cleared_on_disable)
+		goto out;
+
+	drm_dbg(&device->drm, "clear_on_disable: running, mode=%d\n",
+		device->clear_on_disable);
+	ret = ssd16xx_clear_display(device,
+				    ssd16xx_refresh_mode_to_ctrl2(device,
+								  device->clear_on_disable));
+	if (ret) {
+		drm_err(&device->drm, "atomic_disable: clear failed: %d\n", ret);
+		goto out;
+	}
+
+	device->cleared_on_disable = true;
+out:
+	drm_dev_exit(idx);
+}
+
 static void ssd16xx_crtc_atomic_enable(struct drm_crtc *crtc,
 				       struct drm_atomic_commit *state)
 {
@@ -1388,6 +1568,12 @@ static void ssd16xx_crtc_atomic_enable(struct drm_crtc *crtc,
 		}
 		device->initialized = true;
 	}
+	device->cleared_on_disable = false;
+
+	/* Clear display on first app launch if configured */
+	ret = ssd16xx_clear_display_on_init(device);
+	if (ret)
+		drm_err(&device->drm, "crtc_atomic_enable: clear on init failed: %d\n", ret);
 
 	/*
 	 * If refresh_mode_init is set, arm init_refresh_pending so
@@ -1407,6 +1593,7 @@ static void ssd16xx_crtc_atomic_enable(struct drm_crtc *crtc,
 static const struct drm_crtc_helper_funcs ssd16xx_crtc_helper_funcs = {
 	.mode_valid     = ssd16xx_crtc_mode_valid,
 	.atomic_check   = ssd16xx_crtc_atomic_check,
+	.atomic_disable = ssd16xx_crtc_atomic_disable,
 	.atomic_enable  = ssd16xx_crtc_atomic_enable,
 };
 
@@ -1473,6 +1660,9 @@ static void ssd16xx_drm_master_set(struct drm_device *drm,
 {
 	struct ssd16xx_device *device = to_ssd16xx_device(drm);
 
+	device->cleared_on_close = false;
+	device->first_clear_done = false;
+
 	if (device->refresh_mode_init >= 0)
 		device->init_refresh_pending = true;
 }
@@ -1485,8 +1675,23 @@ static void ssd16xx_drm_master_drop(struct drm_device *drm,
 				    struct drm_file *file)
 {
 	struct ssd16xx_device *device = to_ssd16xx_device(drm);
+	int ret, idx;
 
 	device->init_refresh_pending = false;
+	device->first_clear_done = false;
+
+	if (device->clear_on_close < 0 || device->cleared_on_close)
+		return;
+
+	if (!drm_dev_enter(drm, &idx))
+		return;
+
+	ret = ssd16xx_clear_display_on_exit(device);
+	if (ret)
+		drm_err(drm, "master_drop: clear on close failed: %d\n", ret);
+
+	device->cleared_on_close = true;
+	drm_dev_exit(idx);
 }
 
 static struct drm_driver ssd16xx_drm_driver = {
@@ -1623,6 +1828,9 @@ static int ssd16xx_probe(struct spi_device *spi)
 	device->border_waveform_update_idx = device->device_cfg->default_border_waveform_update;
 	device->border_refresh_on_every_update =
 		device->device_cfg->default_border_refresh_on_every_update;
+	device->clear_on_init    = device->device_cfg->default_clear_on_init;
+	device->clear_on_close   = device->device_cfg->default_clear_on_close;
+	device->clear_on_disable = device->device_cfg->default_clear_on_disable;
 	device->refresh_mode_init = device->device_cfg->default_refresh_mode_init;
 
 	/* Parse "rotation" DT property; swap mode dimensions for portrait. */
-- 
2.39.1