drivers: ssd16xx: Use device-specific compatibles

The SSD16xx driver currently provides basic support for most chips in
the Solomon Systech SSD16xx range of e-paper drivers. We currently use
the SSD1608, SSD1673, SSD1675A, and SSD1681 in various boards
supported by Zephyr.

The main user-facing difference between the various SSD16xx chips is
the resolution they support (sources & gates), but there are other
differences as well. For example:

 * 8 or 16 bits used to represent x coordinates
 * 8 or 16 bits used to represent y coordinates
 * Differences in refresh configuration (SSD16XX_CMD_UPDATE_CTRL2)
 * Differences in LUT sizes

The driver currently assumes that the user specifies the number of
bits used to describe coordinates. However, as we add support for more
chips, more of the differences will become apparent and need
workaround.

Comparing data sheets from different chips in the SSD16xx range
suggests that there are (at least) two different generations
present. These differ in the size of the LUTs they expect and the way
they handle partial refresh. This impacts register layout where
SSD16XX_CMD_UPDATE_CTRL2 uses bit 3 selects "mode 2" whereas older
devices uses this for a mode referred to as "initial".

In order to add support for partial refresh in newer devices, we need
to be able to distinguish between the different generations of the
chip. It might be possible to add a DT property to indicate the
revision, but that seems like a bit of an anti-pattern and it would be
hard for users to specify the correct chip generation.

This change introduces chip-specific compatible strings instead of the
generic SSD16xx. There is unfortunately clear pattern that can be used
to distinguish different generations, so the full chip name must be
specified. A benefit of this is that we don't need to specify the
width of the fields describing coordinates in device trees.

Signed-off-by: Andreas Sandberg <[email protected]>

Author: andysan

boards/arm/reel_board/reel_board.dts

@@ -57,14 +57,11 @@
 	pinctrl-1 = <&spi1_sleep>;
 	pinctrl-names = "default", "sleep";
 	ssd16xx: ssd16xxfb@0 {
-		compatible = "gooddisplay,gdeh0213b1", "solomon,ssd1673", "solomon,ssd16xxfb";
-		label = "SSD16XX";
+		compatible = "gooddisplay,gdeh0213b1", "solomon,ssd1673";
 		spi-max-frequency = <4000000>;
 		reg = <0>;
 		width = <250>;
 		height = <122>;
-		pp-width-bits = <8>;
-		pp-height-bits = <8>;
 		reset-gpios = <&gpio0 15 GPIO_ACTIVE_LOW>;
 		dc-gpios = <&gpio0 16 GPIO_ACTIVE_LOW>;
 		busy-gpios = <&gpio0 14 GPIO_ACTIVE_HIGH>;

boards/arm/reel_board/reel_board_v2.dts

@@ -40,14 +40,11 @@
 	pinctrl-1 = <&spi1_sleep>;
 	pinctrl-names = "default", "sleep";
 	ssd16xx: ssd16xxfb@0 {
-		compatible = "gooddisplay,gdeh0213b72", "solomon,ssd1675a", "solomon,ssd16xxfb";
-		label = "SSD16XX";
+		compatible = "gooddisplay,gdeh0213b72", "solomon,ssd1675a";
 		spi-max-frequency = <4000000>;
 		reg = <0>;
 		width = <250>;
 		height = <122>;
-		pp-width-bits = <8>;
-		pp-height-bits = <16>;
 		reset-gpios = <&gpio0 15 GPIO_ACTIVE_LOW>;
 		dc-gpios = <&gpio0 16 GPIO_ACTIVE_LOW>;
 		busy-gpios = <&gpio0 14 GPIO_ACTIVE_HIGH>;

boards/shields/waveshare_epaper/waveshare_epaper_gdeh0154a07.overlay

@@ -14,14 +14,11 @@
 
 &arduino_spi {
 	ssd16xx: ssd16xxfb@0 {
-		compatible = "gooddisplay,gdeh0154a07", "solomon,ssd1681", "solomon,ssd16xxfb";
-		label = "SSD16XX";
+		compatible = "gooddisplay,gdeh0154a07", "solomon,ssd1681";
 		spi-max-frequency = <4000000>;
 		reg = <0>;
 		width = <200>;
 		height = <200>;
-		pp-width-bits = <8>;
-		pp-height-bits = <16>;
 		dc-gpios = <&arduino_header 15 GPIO_ACTIVE_LOW>;	/* D9 */
 		reset-gpios = <&arduino_header 14 GPIO_ACTIVE_LOW>;	/* D8 */
 		busy-gpios = <&arduino_header 13 GPIO_ACTIVE_HIGH>;	/* D7 */

boards/shields/waveshare_epaper/waveshare_epaper_gdeh0213b1.overlay

@@ -14,14 +14,11 @@
 
 &arduino_spi {
 	ssd16xx: ssd16xxfb@0 {
-		compatible = "gooddisplay,gdeh0213b1", "solomon,ssd1673", "solomon,ssd16xxfb";
-		label = "SSD16XX";
+		compatible = "gooddisplay,gdeh0213b1", "solomon,ssd1673";
 		spi-max-frequency = <4000000>;
 		reg = <0>;
 		width = <250>;
 		height = <120>;
-		pp-width-bits = <8>;
-		pp-height-bits = <8>;
 		dc-gpios = <&arduino_header 15 GPIO_ACTIVE_LOW>;	/* D9 */
 		reset-gpios = <&arduino_header 14 GPIO_ACTIVE_LOW>;	/* D8 */
 		busy-gpios = <&arduino_header 13 GPIO_ACTIVE_HIGH>;	/* D7 */

boards/shields/waveshare_epaper/waveshare_epaper_gdeh0213b72.overlay

@@ -14,14 +14,11 @@
 
 &arduino_spi {
 	ssd16xx: ssd16xxfb@0 {
-		compatible = "gooddisplay,gdeh0213b72", "solomon,ssd1675a", "solomon,ssd16xxfb";
-		label = "SSD16XX";
+		compatible = "gooddisplay,gdeh0213b72", "solomon,ssd1675a";
 		spi-max-frequency = <4000000>;
 		reg = <0>;
 		width = <250>;
 		height = <120>;
-		pp-width-bits = <8>;
-		pp-height-bits = <16>;
 		dc-gpios = <&arduino_header 15 GPIO_ACTIVE_LOW>;	/* D9 */
 		reset-gpios = <&arduino_header 14 GPIO_ACTIVE_LOW>;	/* D8 */
 		busy-gpios = <&arduino_header 13 GPIO_ACTIVE_HIGH>;	/* D7 */

boards/shields/waveshare_epaper/waveshare_epaper_gdeh029a1.overlay

@@ -14,14 +14,11 @@
 
 &arduino_spi {
 	ssd16xx: ssd16xxfb@0 {
-		compatible = "gooddisplay,gdeh029a1", "solomon,ssd1608", "solomon,ssd16xxfb";
-		label = "SSD16XX";
+		compatible = "gooddisplay,gdeh029a1", "solomon,ssd1608";
 		spi-max-frequency = <4000000>;
 		reg = <0>;
 		width = <296>;
 		height = <128>;
-		pp-width-bits = <16>;
-		pp-height-bits = <16>;
 		dc-gpios = <&arduino_header 15 GPIO_ACTIVE_LOW>;	/* D9 */
 		reset-gpios = <&arduino_header 14 GPIO_ACTIVE_LOW>;	/* D8 */
 		busy-gpios = <&arduino_header 13 GPIO_ACTIVE_HIGH>;	/* D7 */

drivers/display/ssd16xx.c

@@ -5,8 +5,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#define DT_DRV_COMPAT solomon_ssd16xxfb
-
 #define LOG_LEVEL CONFIG_DISPLAY_LOG_LEVEL
 #include <zephyr/logging/log.h>
 LOG_MODULE_REGISTER(ssd16xx);
@@ -23,7 +21,7 @@ LOG_MODULE_REGISTER(ssd16xx);
 #include "ssd16xx_regs.h"
 
 /**
- * SSD1673, SSD1608, SSD1681, ILI3897 compatible EPD controller driver.
+ * SSD16xx compatible EPD controller driver.
  */
 
 #define EPD_PANEL_NUMOF_ROWS_PER_PAGE	8
@@ -33,6 +31,17 @@ LOG_MODULE_REGISTER(ssd16xx);
 #define SSD16XX_DEFAULT_TR_VALUE	25U
 #define SSD16XX_TR_SCALE_FACTOR		256U
 
+struct ssd16xx_quirks {
+	/* Gates */
+	uint16_t max_width;
+	/* Sources */
+	uint16_t max_height;
+	/* Width (bits) of integer type representing an x coordinate */
+	uint8_t pp_width_bits;
+	/* Width (bits) of integer type representing a y coordinate */
+	uint8_t pp_height_bits;
+};
+
 struct ssd16xx_data {
 	bool read_supported;
 	uint8_t scan_mode;
@@ -62,6 +71,8 @@ struct ssd16xx_config {
 	struct gpio_dt_spec busy_gpio;
 	struct gpio_dt_spec reset_gpio;
 
+	const struct ssd16xx_quirks *quirks;
+
 	struct ssd16xx_dt_array softstart;
 
 	struct ssd16xx_profile profile_initial;
@@ -71,8 +82,6 @@ struct ssd16xx_config {
 	uint16_t height;
 	uint16_t width;
 	uint8_t tssv;
-	uint8_t pp_width_bits;
-	uint8_t pp_height_bits;
 
 	uint8_t dummy_line;
 	bool override_dummy_line;
@@ -189,17 +198,18 @@ static inline size_t push_x_param(const struct device *dev,
 {
 	const struct ssd16xx_config *config = dev->config;
 
-	if (config->pp_width_bits == 8) {
+	if (config->quirks->pp_width_bits == 8) {
 		data[0] = (uint8_t)x;
 		return 1;
 	}
 
-	if (config->pp_width_bits == 16) {
+	if (config->quirks->pp_width_bits == 16) {
 		sys_put_le16(sys_cpu_to_le16(x), data);
 		return 2;
 	}
 
-	LOG_ERR("Unsupported pp_width_bits %u", config->pp_width_bits);
+	LOG_ERR("Unsupported pp_width_bits %u",
+		config->quirks->pp_width_bits);
 	return 0;
 }
 
@@ -208,17 +218,18 @@ static inline size_t push_y_param(const struct device *dev,
 {
 	const struct ssd16xx_config *config = dev->config;
 
-	if (config->pp_height_bits == 8) {
+	if (config->quirks->pp_height_bits == 8) {
 		data[0] = (uint8_t)y;
 		return 1;
 	}
 
-	if (config->pp_height_bits == 16) {
+	if (config->quirks->pp_height_bits == 16) {
 		sys_put_le16(sys_cpu_to_le16(y), data);
 		return 2;
 	}
 
-	LOG_ERR("Unsupported pp_height_bitsa %u", config->pp_height_bits);
+	LOG_ERR("Unsupported pp_height_bitsa %u",
+		config->quirks->pp_height_bits);
 	return 0;
 }
 
@@ -885,6 +896,12 @@ static int ssd16xx_init(const struct device *dev)
 		return err;
 	}
 
+	if (config->width > config->quirks->max_width ||
+	    config->height > config->quirks->max_height) {
+		LOG_ERR("Display size out of range.");
+		return -EINVAL;
+	}
+
 	return ssd16xx_controller_init(dev);
 }
 
@@ -901,6 +918,42 @@ static struct display_driver_api ssd16xx_driver_api = {
 	.set_orientation = ssd16xx_set_orientation,
 };
 
+#if DT_HAS_COMPAT_STATUS_OKAY(solomon_ssd1608)
+static struct ssd16xx_quirks quirks_solomon_ssd1608 = {
+	.max_width = 320,
+	.max_height = 240,
+	.pp_width_bits = 16,
+	.pp_height_bits = 16,
+};
+#endif
+
+#if DT_HAS_COMPAT_STATUS_OKAY(solomon_ssd1673)
+static struct ssd16xx_quirks quirks_solomon_ssd1673 = {
+	.max_width = 250,
+	.max_height = 150,
+	.pp_width_bits = 8,
+	.pp_height_bits = 8,
+};
+#endif
+
+#if DT_HAS_COMPAT_STATUS_OKAY(solomon_ssd1675a)
+static struct ssd16xx_quirks quirks_solomon_ssd1675a = {
+	.max_width = 296,
+	.max_height = 160,
+	.pp_width_bits = 8,
+	.pp_height_bits = 16,
+};
+#endif
+
+#if DT_HAS_COMPAT_STATUS_OKAY(solomon_ssd1681)
+static struct ssd16xx_quirks quirks_solomon_ssd1681 = {
+	.max_width = 200,
+	.max_height = 200,
+	.pp_width_bits = 8,
+	.pp_height_bits = 16,
+};
+#endif
+
 #define LUT_DEFAULT_ASSIGN(n)						\
 		.lut_default = {					\
 			.data = lut_default_##n,			\
@@ -913,70 +966,75 @@ static struct display_driver_api ssd16xx_driver_api = {
 			.len = sizeof(softstart_##n),			\
 		},
 
-#define SSD16XX_MAKE_INST_ARRAY_OPT(n, p)				\
-	static uint8_t data_ ## n ## _ ## p[] = DT_INST_PROP_OR(n, p, {})
+#define SSD16XX_MAKE_ARRAY_OPT(n, p)					\
+	static uint8_t data_ ## n ## _ ## p[] =				\
+		DT_PROP_OR(n, p, {})
 
 #define SSD16XX_ASSIGN_ARRAY(n, p)					\
 	{								\
 		.data = data_ ## n ## _ ## p,				\
-		.len = sizeof(data_ ## n ## _ ## p),			\
+		.len = sizeof(data_ ## n ## _ ## p),		\
 	}
 
 #define SSD16XX_INITIAL_PROFILE_DEFINE(n)				\
-	SSD16XX_MAKE_INST_ARRAY_OPT(n, lut_initial);			\
-	SSD16XX_MAKE_INST_ARRAY_OPT(n, gdv);				\
-	SSD16XX_MAKE_INST_ARRAY_OPT(n, sdv)
+	SSD16XX_MAKE_ARRAY_OPT(n, lut_initial);				\
+	SSD16XX_MAKE_ARRAY_OPT(n, gdv);					\
+	SSD16XX_MAKE_ARRAY_OPT(n, sdv)
 
 #define SSD16XX_INITIAL_PROFILE(n)					\
 	{								\
 		.lut = SSD16XX_ASSIGN_ARRAY(n, lut_initial),		\
 		.gdv = SSD16XX_ASSIGN_ARRAY(n, gdv),			\
 		.sdv = SSD16XX_ASSIGN_ARRAY(n, sdv),			\
-		.vcom = DT_INST_PROP_OR(n, vcom, 0),			\
-		.override_vcom = DT_INST_NODE_HAS_PROP(n, vcom),	\
-		.bwf = DT_INST_PROP_OR(n, border_waveform, 0),		\
-		.override_bwf = DT_INST_NODE_HAS_PROP(n, border_waveform), \
+		.vcom = DT_PROP_OR(n, vcom, 0),				\
+		.override_vcom = DT_NODE_HAS_PROP(n, vcom),		\
+		.bwf = DT_PROP_OR(n, border_waveform, 0),		\
+		.override_bwf = DT_NODE_HAS_PROP(n, border_waveform),	\
 	}
 
-#define SSD16XX_DEFINE(n)						\
-	SSD16XX_MAKE_INST_ARRAY_OPT(n, lut_default);			\
-	SSD16XX_MAKE_INST_ARRAY_OPT(n, softstart);			\
+#define SSD16XX_DEFINE(n, quirks_ptr)					\
+	SSD16XX_MAKE_ARRAY_OPT(n, lut_default);				\
+	SSD16XX_MAKE_ARRAY_OPT(n, softstart);				\
 	SSD16XX_INITIAL_PROFILE_DEFINE(n);				\
 									\
-	static const struct ssd16xx_config ssd16xx_cfg_##n = {		\
-		.bus = SPI_DT_SPEC_INST_GET(n,				\
+	static const struct ssd16xx_config ssd16xx_cfg_ ## n = {	\
+		.bus = SPI_DT_SPEC_GET(n,				\
 			SPI_OP_MODE_MASTER | SPI_WORD_SET(8) |		\
 			SPI_HOLD_ON_CS | SPI_LOCK_ON,			\
 			0),						\
-		.reset_gpio = GPIO_DT_SPEC_INST_GET(n, reset_gpios),	\
-		.dc_gpio = GPIO_DT_SPEC_INST_GET(n, dc_gpios),		\
-		.busy_gpio = GPIO_DT_SPEC_INST_GET(n, busy_gpios),	\
-		.height = DT_INST_PROP(n, height),			\
-		.width = DT_INST_PROP(n, width),			\
-		.orientation = DT_INST_PROP(n, orientation_flipped),	\
-		.pp_width_bits = DT_INST_PROP(n, pp_width_bits),	\
-		.pp_height_bits = DT_INST_PROP(n, pp_height_bits),	\
-		.tssv = DT_INST_PROP_OR(n, tssv, 0),			\
+		.reset_gpio = GPIO_DT_SPEC_GET(n, reset_gpios),		\
+		.dc_gpio = GPIO_DT_SPEC_GET(n, dc_gpios),		\
+		.busy_gpio = GPIO_DT_SPEC_GET(n, busy_gpios),		\
+		.quirks = quirks_ptr,					\
+		.height = DT_PROP(n, height),				\
+		.width = DT_PROP(n, width),				\
+		.orientation = DT_PROP(n, orientation_flipped),		\
+		.tssv = DT_PROP_OR(n, tssv, 0),				\
 		.softstart = SSD16XX_ASSIGN_ARRAY(n, softstart),	\
 		.lut_default = SSD16XX_ASSIGN_ARRAY(n, lut_default),	\
 		.profile_initial = SSD16XX_INITIAL_PROFILE(n),		\
-		.dummy_line = DT_INST_PROP_OR(n, dummy_line, 0),	\
-		.override_dummy_line =					\
-			DT_INST_NODE_HAS_PROP(n, dummy_line),		\
-		.gate_line_width =					\
-			DT_INST_PROP_OR(n, gate_line_width, 0),		\
-		.override_gate_line_width =				\
-			DT_INST_NODE_HAS_PROP(n, gate_line_width),	\
+		.dummy_line = DT_PROP_OR(n, dummy_line, 0),		\
+		.override_dummy_line = DT_NODE_HAS_PROP(n, dummy_line),	\
+		.gate_line_width = DT_PROP_OR(n, gate_line_width, 0),	\
+		.override_gate_line_width = DT_NODE_HAS_PROP(		\
+			n, gate_line_width),				\
 	};								\
 									\
-	static struct ssd16xx_data ssd16xx_data_##n;			\
+	static struct ssd16xx_data ssd16xx_data_ ## n;			\
 									\
-	DEVICE_DT_INST_DEFINE(n, ssd16xx_init, NULL,			\
-			      &ssd16xx_data_##n,			\
-			      &ssd16xx_cfg_##n,				\
-			      POST_KERNEL,				\
-			      CONFIG_DISPLAY_INIT_PRIORITY,		\
-			      &ssd16xx_driver_api);			\
-
-
-DT_INST_FOREACH_STATUS_OKAY(SSD16XX_DEFINE)
+	DEVICE_DT_DEFINE(n,						\
+			 ssd16xx_init, NULL,				\
+			 &ssd16xx_data_ ## n,				\
+			 &ssd16xx_cfg_ ## n,				\
+			 POST_KERNEL,					\
+			 CONFIG_DISPLAY_INIT_PRIORITY,			\
+			 &ssd16xx_driver_api)
+
+DT_FOREACH_STATUS_OKAY_VARGS(solomon_ssd1608, SSD16XX_DEFINE,
+			     &quirks_solomon_ssd1608);
+DT_FOREACH_STATUS_OKAY_VARGS(solomon_ssd1673, SSD16XX_DEFINE,
+			     &quirks_solomon_ssd1673);
+DT_FOREACH_STATUS_OKAY_VARGS(solomon_ssd1675a, SSD16XX_DEFINE,
+			     &quirks_solomon_ssd1675a);
+DT_FOREACH_STATUS_OKAY_VARGS(solomon_ssd1681, SSD16XX_DEFINE,
+			     &quirks_solomon_ssd1681);

dts/bindings/display/solomon,ssd1608.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2022 Andreas Sandberg
+# SPDX-License-Identifier: Apache-2.0
+
+description: Solomon Systech SSD1608 320x240 EPD display controller
+
+compatible: "solomon,ssd1608"
+
+include: solomon,ssd16xx-common.yaml

dts/bindings/display/solomon,ssd1673.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2022 Andreas Sandberg
+# SPDX-License-Identifier: Apache-2.0
+
+description: Solomon Systech SSD1673 250x150 EPD display controller
+
+compatible: "solomon,ssd1673"
+
+include: solomon,ssd16xx-common.yaml

dts/bindings/display/solomon,ssd1675a.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2022 Andreas Sandberg
+# SPDX-License-Identifier: Apache-2.0
+
+description: Solomon Systech SSD1675A 296x160 EPD display controller
+
+compatible: "solomon,ssd1675a"
+
+include: solomon,ssd16xx-common.yaml