Merge #19915

19915: drivers/lcd: support MCU 8080 8-bit parallel mode r=benpicco a=gschorcht

### Contribution description

LCD driver ICs usually support
- SPI serial mode,
- MCU 8080 8-bit parallel mode and
- MCU 8080 16-bit parallel mode.

This PR extends the LCD display driver API to support the MCU 8080 8-/16-bit parallel modes and implements a GPIO-driven MCU 8080 8-bit parallel mode.

The following features are already working locally and will be provided as follow-on PRs for which this PR is a prerequisite.

- GPIO-driven bit-banging implementation of the 16-bit mode of the MCU 8080 parallel interface
- Enabling the display on `stm32f723e-disco` and `stm32l496g-disco` using the feature above
- Definition of a low-level API for the parallel modes using the LCD controller of the MCU
- Using FMC for the display on `stm32f723e-disco` and `stm32l496g-disco`
- Using LCD controller for the display of `esp32-wt32-sc01-plus` (PR #19917)

### Testing procedure

The PR can be tested with PR #19917 on top of this PR.
```
BOARD=esp32s3-wt32-sc01-plus make -j8 -C tests/drivers/st77xx flash
```
The following video shows the test.

**Please note** The test is pretty slow because the display has 480 x 320 pixels and the MCU 8080 8-bit parallel interface is realized by a GPIO-driven bit-banging implementation where each GPIO of the data bus is set separately. A follow-up PR will use the ESP32-S3 LCD controller and DMA for this board. This PR just defines the extension of the driver by the parallel interface and provides the bit-banging implementation for MCUs that don't have a LCD controller on chip.

https://github.com/RIOT-OS/RIOT/assets/31932013/c1e3e3d7-05d9-4ca5-8fff-9a5eaca50fba

### Issues/PRs references

Co-authored-by: Gunar Schorcht <[email protected]>

Author: bors[bot]

drivers/ili9341/include/ili9341_params.h

@@ -71,13 +71,45 @@ extern "C" {
 #define ILI9341_PARAM_OFFSET_Y          0               /**< Vertival offset */
 #endif
 
+#if MODULE_LCD_SPI || DOXYGEN
+/** Default interface params if SPI serial interface is enabled */
+#define ILI9341_PARAM_IF_SPI        .spi = ILI9341_PARAM_SPI, \
+                                    .spi_clk = ILI9341_PARAM_SPI_CLK, \
+                                    .spi_mode = ILI9341_PARAM_SPI_MODE,
+#else
+#define ILI9341_PARAM_IF_SPI
+#endif
+
+#if MODULE_LCD_PARALLEL || DOXYGEN
+/** Default interface params if MCU 8080 8-bit parallel interface is enabled */
+#define ILI9341_PARAM_IF_PAR        .d0_pin = ILI9341_PARAM_D0, \
+                                    .d1_pin = ILI9341_PARAM_D1, \
+                                    .d2_pin = ILI9341_PARAM_D2, \
+                                    .d3_pin = ILI9341_PARAM_D3, \
+                                    .d4_pin = ILI9341_PARAM_D4, \
+                                    .d5_pin = ILI9341_PARAM_D5, \
+                                    .d6_pin = ILI9341_PARAM_D6, \
+                                    .d7_pin = ILI9341_PARAM_D7, \
+                                    .wrx_pin = ILI9341_PARAM_WRX, \
+                                    .rdx_pin = ILI9341_PARAM_RDX,
+#else
+#define ILI9341_PARAM_IF_PAR
+#endif
+
 /**
  * @brief   Default params
+ *
+ * @note The default parameter set defined here can only be used if a single
+ *       ILI9341 display and only one interface mode is used. If multiple
+ *       ILI9341 displays are used or if multiple interface modes are enabled
+ *       by the modules `lcd_spi`, lcd_parallel and `lcd_parallel_16bit`, a user
+ *       defined parameter set @ref ILI9341_PARAMS has to be defined. In the
+ *       latter case @ref lcd_params_t::spi must then be set to @ref SPI_UNDEF
+ *       for displays with MCU 8080 8-/16-bit parallel interfaces.
  */
 #ifndef ILI9341_PARAMS
-#define ILI9341_PARAMS              { .spi = ILI9341_PARAM_SPI, \
-                                      .spi_clk = ILI9341_PARAM_SPI_CLK, \
-                                      .spi_mode = ILI9341_PARAM_SPI_MODE, \
+#define ILI9341_PARAMS              { ILI9341_PARAM_IF_SPI \
+                                      ILI9341_PARAM_IF_PAR \
                                       .cs_pin = ILI9341_PARAM_CS, \
                                       .dcx_pin = ILI9341_PARAM_DCX, \
                                       .rst_pin = ILI9341_PARAM_RST, \
@@ -124,7 +156,6 @@ static const uint8_t ili9341_screen_ids[] =
  */
 #define ILI9341_SCREEN_NUMOF    ARRAY_SIZE(ili9341_screen_ids)
 
-
 #ifdef __cplusplus
 }
 #endif

drivers/include/lcd.h

@@ -1,6 +1,7 @@
 /*
  * Copyright (C) 2018 Koen Zandberg
  *               2021 Francisco Molina
+ *               2023 Gunar Schorcht
  *
  * This file is subject to the terms and conditions of the GNU Lesser
  * General Public License v2.1. See the file LICENSE in the top level
@@ -13,8 +14,22 @@
  *
  * @brief       Driver for the LCD display
  *
- * The LCD is a generic display driver for small RGB displays. The driver
- * implemented here operates over SPI to communicate with the device.
+ * The LCD is a generic display driver for small RGB displays. It communicates
+ * with the device either via an
+ *
+ * - SPI serial interface (if module `lcd_spi` enabled) or an
+ * - MCU 8080 8-/16-bit parallel interface (if module `lcd_parallel` or
+ *   module `lcd_parallel_16` is enabled).
+ *
+ * Usually the device driver is used either for a single display with SPI serial
+ * interface or for a display with parallel MCU 8080 8-/16-bit parallel
+ * interface. However, the device driver can also be used simultaneously for
+ * multiple displays with different interfaces if several of the `lcd_spi`,
+ * `lcd_parallel` and `lcd_parallel_16bit` modules are enabled at the same time.
+ * In this case, please refer to the notes in @ref lcd_params_t.
+ *
+ * @warning MCU 8080 16-bit parallel interface (module `lcd_parallel_16bit`) is
+ *          not supported yet.
  *
  * The device requires colors to be send in big endian RGB-565 format. The
  * @ref CONFIG_LCD_LE_MODE compile time option can switch this, but only use this
@@ -28,13 +43,15 @@
  *
  * @author      Koen Zandberg <[email protected]>
  * @author      Francisco Molina <[email protected]>
+ * @author      Gunar Schorcht <[email protected]>
  *
  */
 
 #ifndef LCD_H
 #define LCD_H
 
 #include "board.h"
+#include "mutex.h"
 #include "periph/spi.h"
 #include "periph/gpio.h"
 
@@ -70,18 +87,58 @@ extern "C" {
 
 /**
  * @brief   Device initialization parameters
+ *
+ * @note The device driver can be used simultaneously for displays with
+ *       SPI serial interface and parallel MCU 8080 8-/16-bit interfaces
+ *       if the modules `lcd_spi` and `lcd_parallel` or `lcd_parallel_16bit`
+ *       are enabled at the same time. In this case the interface parameters
+ *       for the SPI serial interface and the MCU 8080 parallel 8-/16-bit
+ *       interfaces are defined. @ref lcd_params_t::spi must then be set to
+ *       @ref SPI_UNDEF for displays that use the MCU-8080-parallel-8-/16-bit
+ *       interface, i.e. @ref lcd_params_t::spi is then used to detect the
+ *       interface mode.
  */
 typedef  struct {
+#if MODULE_LCD_SPI || DOXYGEN
+    /* Interface parameters used for serial interface */
     spi_t spi;                  /**< SPI device that the display is connected to */
     spi_clk_t spi_clk;          /**< SPI clock speed to use */
     spi_mode_t spi_mode;        /**< SPI mode */
+#endif
+#if MODULE_LCD_PARALLEL || DOXYGEN
+    /* Interface parameters used for MCU 8080 8-bit parallel interface */
+    gpio_t wrx_pin;             /**< pin connected to the WRITE ENABLE line */
+    gpio_t rdx_pin;             /**< pin connected to the READ ENABLE line */
+    gpio_t d0_pin;              /**< pin connected to the D0 line */
+    gpio_t d1_pin;              /**< pin connected to the D1 line */
+    gpio_t d2_pin;              /**< pin connected to the D2 line */
+    gpio_t d3_pin;              /**< pin connected to the D3 line */
+    gpio_t d4_pin;              /**< pin connected to the D4 line */
+    gpio_t d5_pin;              /**< pin connected to the D5 line */
+    gpio_t d6_pin;              /**< pin connected to the D6 line */
+    gpio_t d7_pin;              /**< pin connected to the D7 line */
+#if MODULE_LCD_PARALLEL_16BIT || DOXYGEN
+    /* Interface parameters used for MCU 8080 16-bit parallel interface */
+    gpio_t d8_pin;              /**< pin connected to the D8 line */
+    gpio_t d9_pin;              /**< pin connected to the D9 line */
+    gpio_t d10_pin;             /**< pin connected to the D10 line */
+    gpio_t d11_pin;             /**< pin connected to the D11 line */
+    gpio_t d12_pin;             /**< pin connected to the D12 line */
+    gpio_t d13_pin;             /**< pin connected to the D13 line */
+    gpio_t d14_pin;             /**< pin connected to the D14 line */
+    gpio_t d15_pin;             /**< pin connected to the D15 line */
+#endif /* MODULE_LCD_PARALLEL_16BIT */
+#endif /* MODULE_LCD_PARALLEL */
+    /* Common interface parameters */
     gpio_t cs_pin;              /**< pin connected to the CHIP SELECT line */
     gpio_t dcx_pin;             /**< pin connected to the DC line */
-    gpio_t rst_pin;             /**< pin connected to the reset line */
-    bool rgb;                   /**< True when display is connected in RGB mode
-                                 *  False when display is connected in BGR mode */
+    gpio_t rst_pin;             /**< pin connected to the RESET line */
+    bool rgb;                   /**< True when display is connected in RGB mode\n
+                                     False when display is connected in BGR mode */
     bool inverted;              /**< Display works in inverted color mode */
-    uint16_t lines;             /**< Number of lines, from 16 to 320 in 8 line steps */
+    uint16_t lines;             /**< Number of lines, from 16 to the number of
+                                     lines supported by the driver IC in 8 line
+                                     steps */
     uint16_t rgb_channels;      /**< Display rgb channels */
     uint8_t rotation;           /**< Display rotation mode */
     uint8_t offset_x;           /**< LCD offset to apply on x axis. */
@@ -104,11 +161,15 @@ typedef struct lcd_driver lcd_driver_t;
  * @brief   Device descriptor for a lcd
  */
 typedef struct {
-#ifdef MODULE_DISP_DEV
+#if MODULE_DISP_DEV || DOXYGEN
     disp_dev_t *dev;                /**< Pointer to the generic display device */
 #endif
     const lcd_driver_t *driver;     /**< LCD driver */
     const lcd_params_t *params;     /**< Device initialization parameters */
+#if MODULE_LCD_PARALLEL || DOXYGEN
+    mutex_t lock;                   /**< Mutex used to lock the device in
+                                         MCU 8080 parallel interface mode */
+#endif
 } lcd_t;
 
 /**
@@ -142,7 +203,7 @@ struct lcd_driver {
      * @param[in] y2   y coordinate of the opposite corner
      *
      */
-    void (*set_area)(const lcd_t *dev, uint16_t x1, uint16_t x2, uint16_t y1,
+    void (*set_area)(lcd_t *dev, uint16_t x1, uint16_t x2, uint16_t y1,
                      uint16_t y2);
 };
 
@@ -162,14 +223,14 @@ struct lcd_driver {
  *
  * @param[out]  dev     device descriptor
  */
-void lcd_ll_acquire(const lcd_t *dev);
+void lcd_ll_acquire(lcd_t *dev);
 
 /**
  * @brief   Low-level function to release the device
  *
  * @param[out]  dev     device descriptor
  */
-void lcd_ll_release(const lcd_t *dev);
+void lcd_ll_release(lcd_t *dev);
 
 /**
  * @brief   Low-level function to write a command
@@ -182,7 +243,7 @@ void lcd_ll_release(const lcd_t *dev);
  * @param[in]   data    command data to the device
  * @param[in]   len     length of the command data
  */
-void lcd_ll_write_cmd(const lcd_t *dev, uint8_t cmd, const uint8_t *data,
+void lcd_ll_write_cmd(lcd_t *dev, uint8_t cmd, const uint8_t *data,
                       size_t len);
 
 /**
@@ -201,7 +262,7 @@ void lcd_ll_write_cmd(const lcd_t *dev, uint8_t cmd, const uint8_t *data,
  * @param[out]  data    data from the device
  * @param[in]   len     length of the returned data
  */
-void lcd_ll_read_cmd(const lcd_t *dev, uint8_t cmd, uint8_t *data, size_t len);
+void lcd_ll_read_cmd(lcd_t *dev, uint8_t cmd, uint8_t *data, size_t len);
 /** @} */
 
 /**
@@ -234,7 +295,7 @@ int lcd_init(lcd_t *dev, const lcd_params_t *params);
  * @param[in]   y2      y coordinate of the opposite corner
  * @param[in]   color   single color to fill the area with
  */
-void lcd_fill(const lcd_t *dev, uint16_t x1, uint16_t x2,
+void lcd_fill(lcd_t *dev, uint16_t x1, uint16_t x2,
               uint16_t y1, uint16_t y2, uint16_t color);
 
 /**
@@ -253,7 +314,7 @@ void lcd_fill(const lcd_t *dev, uint16_t x1, uint16_t x2,
  * @param[in]   y2      y coordinate of the opposite corner
  * @param[in]   color   array of colors to fill the area with
  */
-void lcd_pixmap(const lcd_t *dev, uint16_t x1, uint16_t x2, uint16_t y1,
+void lcd_pixmap(lcd_t *dev, uint16_t x1, uint16_t x2, uint16_t y1,
                 uint16_t y2, const uint16_t *color);
 
 /**
@@ -264,34 +325,38 @@ void lcd_pixmap(const lcd_t *dev, uint16_t x1, uint16_t x2, uint16_t y1,
  * @param[in]   data    command data to the device
  * @param[in]   len     length of the command data
  */
-void lcd_write_cmd(const lcd_t *dev, uint8_t cmd, const uint8_t *data,
+void lcd_write_cmd(lcd_t *dev, uint8_t cmd, const uint8_t *data,
                    size_t len);
 
 /**
  * @brief   Raw read command
  *
+ * @note Very often the SPI MISO signal of the serial interface or the RDX
+ *       signal of the MCU 8080 parallel interface are not connected to the
+ *       display. In this case the read command does not provide valid data.
+ *
  * @pre         len > 0
  *
  * @param[in]   dev     device descriptor
  * @param[in]   cmd     command
  * @param[out]  data    data from the device
  * @param[in]   len     length of the returned data
  */
-void lcd_read_cmd(const lcd_t *dev, uint8_t cmd, uint8_t *data, size_t len);
+void lcd_read_cmd(lcd_t *dev, uint8_t cmd, uint8_t *data, size_t len);
 
 /**
  * @brief   Invert the display colors
  *
  * @param[in]   dev     device descriptor
  */
-void lcd_invert_on(const lcd_t *dev);
+void lcd_invert_on(lcd_t *dev);
 
 /**
  * @brief   Disable color inversion
  *
  * @param[in]   dev     device descriptor
  */
-void lcd_invert_off(const lcd_t *dev);
+void lcd_invert_off(lcd_t *dev);
 /** @} */
 
 #ifdef __cplusplus

drivers/include/st77xx.h

@@ -22,8 +22,18 @@
  * @ref lcd_params_t::cntrl or as macro @ref ST77XX_PARAM_CNTRL if the
  * default parameter set @ref ST77XX_PARAMS is used.
  *
- * The driver uses the SPI serial interface to communicate with the display
- * controller.
+ * The driver communicates with the device either via an
+ *
+ * - SPI serial interface (if module `lcd_spi` enabled) or an
+ * - MCU 8080 8-/16-bit parallel interface (if module `lcd_parallel` or
+ *   module `lcd_parallel_16` is enabled).
+ *
+ * Usually the device driver is used either for a single display with SPI serial
+ * interface or for a display with parallel MCU 8080 8-/16-bit parallel
+ * interface. However, the device driver can also be used simultaneously for
+ * multiple displays with different interfaces if several of the `lcd_spi`,
+ * `lcd_parallel` and `lcd_parallel_16bit` modules are enabled at the same time.
+ * In this case, please refer to the notes in @ref lcd_params_t.
  *
  * The device requires colors to be send in big endian RGB-565 format. The
  * @ref CONFIG_LCD_LE_MODE compile time option can switch this, but only use this

drivers/lcd/Kconfig

@@ -7,17 +7,57 @@
 
 config MODULE_LCD
     bool "LCD display driver"
-    depends on HAS_PERIPH_SPI
     depends on HAS_PERIPH_GPIO
     depends on TEST_KCONFIG
-    select MODULE_PERIPH_SPI
     select MODULE_PERIPH_GPIO
 
 config MODULE_LCD_MULTI_CNTRL
     bool
     help
         The controller-specific driver supports multiple controller variants.
 
+config MODULE_LCD_SPI
+    bool
+    default y if !MODULE_LCD_PARALLEL && !MODULE_LCD_PARALLEL_16BIT
+    default y if HAVE_LCD_SPI
+    depends on HAS_PERIPH_SPI
+    depends on MODULE_LCD
+    select MODULE_PERIPH_SPI
+    help
+        SPI serial interface is used
+
+config MODULE_LCD_PARALLEL
+    bool
+    default y if HAVE_LCD_PARALLEL || HAVE_LCD_PARALLEL_16BIT
+    depends on MODULE_LCD
+    help
+        MCU 8080 8-/16-bit parallel interface is used
+
+config MODULE_LCD_PARALLEL_16BIT
+    bool
+    default y if HAVE_LCD_PARALLEL_16BIT
+    depends on MODULE_LCD
+    help
+        MCU 8080 16-bit paralell interface is used
+
+config HAVE_LCD_SPI
+    bool
+    help
+        Indicates that a display with MCU 8080 8-/16-bit parallel interface
+        is present
+
+config HAVE_LCD_PARALLEL
+    bool
+    help
+        Indicates that a display with MCU 8080 8-/16-bit parallel interface
+        is present
+
+config HAVE_LCD_PARALLEL_16BIT
+    bool
+    help
+        Indicates that a display with MCU 8080 16-bit parallel interface
+        is present
+
 menuconfig KCONFIG_USEMODULE_LCD
     bool "Configure LCD driver"
     depends on USEMODULE_LCD

drivers/lcd/Makefile.dep

@@ -1,2 +1,14 @@
-FEATURES_REQUIRED += periph_spi
 FEATURES_REQUIRED += periph_gpio
+
+ifneq (,$(filter lcd_parallel_16bit,$(USEMODULE)))
+  USEMODULE += lcd_parallel
+endif
+
+ifeq (,$(filter lcd_parallel%,$(USEMODULE)))
+  # default to SPI serial interface if no MCU 8080 parallel interface is enabled
+  USEMODULE += lcd_spi
+endif
+
+ifneq (,$(filter lcd_spi,$(USEMODULE)))
+  FEATURES_REQUIRED += periph_spi
+endif

drivers/lcd/Makefile.include

@@ -1,4 +1,8 @@
 PSEUDOMODULES += lcd_multi_cntrl
 
+PSEUDOMODULES += lcd_spi
+PSEUDOMODULES += lcd_parallel
+PSEUDOMODULES += lcd_parallel_16bit
+
 USEMODULE_INCLUDES_lcd := $(LAST_MAKEFILEDIR)/include
 USEMODULE_INCLUDES += $(USEMODULE_INCLUDES_lcd)