lcd: update i80 lcd example to work with PSRAM

examples/peripherals/lcd/gc9a01/README.md

@@ -4,7 +4,7 @@
 
 `esp_lcd` allows user to add their own panel drivers in the project scope (i.e. panel driver can live outside of esp-idf), so that the upper layer code like LVGL porting code can be reused without any modifications, as long as user-implemented panel driver follows the interface defined in the `esp_lcd` component.
 
-This example shows how to add the GC9A01 driver in the project folder but still use the API provided by `esp_lcd` component. As GC9A01 is famous in the form of a circular screen, this example will draw a fancy dash board with the LVGL library. For more information about porting the LVGL library, you can also refer to another [lvgl porting example](../lvgl/README.md).
+This example shows how to add the GC9A01 driver in the project folder but still use the API provided by `esp_lcd` component. As GC9A01 is famous in the form of a circular screen, this example will draw a fancy dash board with the LVGL library. For more information about porting the LVGL library, you can also refer to another [lvgl porting example](../i80_controller/README.md).
 
 ## How to use the example
 

examples/peripherals/lcd/i80_controller/CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.5)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-project(lcd_lvgl)
+project(i80_controller)
 
 # As the upstream LVGL library has build warnings in esp-idf build system, this is only for temporarily workaround
 # Will remove this workaround when upstream LVGL fixes the warnings in the next release

examples/peripherals/lcd/i80_controller/README.md

@@ -1,12 +1,12 @@
 | Supported Targets | ESP32 | ESP32-S2 | ESP32-S3 |
 | ----------------- | ----- | -------- | -------- |
-# LVGL porting example
+# LVGL porting example (based on i80 interfaced LCD controller)
 
 LVGL is an open-source graphics library for creating modern GUIs. It has plenty of built-in graphical elements with low memory footprint, which is friendly for embedded GUI applications.
 
 This example can be taken as a skeleton of porting the LVGL library onto the `esp_lcd` driver layer. **Note** that, this example only focuses on the display interface, regardless of the input device driver.
 
-The whole porting code is located in [this main file](main/lvgl_example_main.c), and the UI demo code is located in [another single file](main/lvgl_demo_ui.c).
+The whole porting code is located in [i80_controller_example_main.c](main/i80_controller_example_main.c), and the UI demo code is located in [lvgl_demo_ui.c](main/lvgl_demo_ui.c).
 
 The UI will display two images (one Espressif logo and another Espressif text), which have been converted into C arrays by the [online converting tool](https://lvgl.io/tools/imageconverter), and will be compiled directly into application binary.
 
@@ -49,11 +49,17 @@ The connection between ESP Board and the LCD is as follows:
 └─────────────┘              └────────────────┘
 ```
 
-The GPIO number used by this example can be changed in [lvgl_example_main.c](main/lvgl_example_main.c).
-Especially, please pay attention to the level used to turn on the LCD backlight, some LCD module needs a low level to turn it on, while others take a high level. You can change the backlight level macro `EXAMPLE_LCD_BK_LIGHT_ON_LEVEL` in [lvgl_example_main.c](main/lvgl_example_main.c).
+The GPIO number used by this example can be changed in [i80_controller_example_main.c](main/i80_controller_example_main.c).
+Especially, please pay attention to the binary signal level used to turn the LCD backlight on, some LCD modules need a low level to turn it on, while others require a high level. You can change the backlight level macro `EXAMPLE_LCD_BK_LIGHT_ON_LEVEL` in [i80_controller_example_main.c](main/i80_controller_example_main.c).
 
 ### Build and Flash
 
+Run `idf.py set-target <target-name>` to select one supported target that can run this example. This step will also apply the default Kconfig configurations into the `sdkconfig` file.
+
+Run `idf.py menuconfig` to open a terminal UI where you can tune specific configuration for this example in the `Example Configuration` menu.
+
+* `Allocate color data from PSRAM`: Select this option if you want to allocate the LVGL draw buffers from PSRAM.
+
 Run `idf.py -p PORT build flash monitor` to build, flash and monitor the project. A fancy animation will show up on the LCD as expected.
 
 The first time you run `idf.py` for the example will cost extra time as the build system needs to address the component dependencies and downloads the missing components from registry into `managed_components` folder.
@@ -80,4 +86,8 @@ I (558) example: Display LVGL animation
 
 ## Troubleshooting
 
+* Can't get a stable UI when `EXAMPLE_LCD_I80_COLOR_IN_PSRAM` is enabled.
+
+   This is because of the limited PSRAM bandwidth, compared to the internal SRAM. You can either decrease the PCLK clock `EXAMPLE_LCD_PIXEL_CLOCK_HZ` in [i80_controller_example_main.c](main/i80_controller_example_main.c) or increase the PSRAM working frequency `SPIRAM_SPEED` from the KConfig (e.g. **ESP32S3-Specific** -> **Set RAM clock speed**) or decrease the FPS in LVGL configuration. For illustration, this example has set the refresh period to 100ms in the default sdkconfig file.
+
 For any technical queries, please open an [issue] (https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

examples/peripherals/lcd/i80_controller/main/CMakeLists.txt

@@ -0,0 +1,4 @@
+file(GLOB_RECURSE IMAGE_SOURCES images/*.c)
+
+idf_component_register(SRCS "i80_controller_example_main.c" "lvgl_demo_ui.c" ${IMAGE_SOURCES}
+                       INCLUDE_DIRS ".")

examples/peripherals/lcd/i80_controller/main/Kconfig.projbuild

@@ -0,0 +1,11 @@
+menu "Example Configuration"
+
+    config EXAMPLE_LCD_I80_COLOR_IN_PSRAM
+        bool "Allocate color data from PSRAM"
+        depends on IDF_TARGET_ESP32S3
+        default y
+        help
+            Enable this option if you wish to allocate the color buffer used by LVGL from PSRAM.
+            Unmatched PSRAM band width with LCD requirement can lead to blurred image display.
+
+endmenu

examples/peripherals/lcd/i80_controller/main/i80_controller_example_main.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: CC0-1.0
  */
@@ -21,22 +21,28 @@ static const char *TAG = "example";
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 //////////////////// Please update the following configuration according to your LCD spec //////////////////////////////
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+#if CONFIG_EXAMPLE_LCD_I80_COLOR_IN_PSRAM
+// PCLK frequency can't go too high as the limitation of PSRAM bandwidth
+#define EXAMPLE_LCD_PIXEL_CLOCK_HZ     (2 * 1000 * 1000)
+#else
 #define EXAMPLE_LCD_PIXEL_CLOCK_HZ     (10 * 1000 * 1000)
+#endif // CONFIG_EXAMPLE_LCD_I80_COLOR_IN_PSRAM
+
 #define EXAMPLE_LCD_BK_LIGHT_ON_LEVEL  1
 #define EXAMPLE_LCD_BK_LIGHT_OFF_LEVEL !EXAMPLE_LCD_BK_LIGHT_ON_LEVEL
-#define EXAMPLE_PIN_NUM_DATA0          19
-#define EXAMPLE_PIN_NUM_DATA1          21
-#define EXAMPLE_PIN_NUM_DATA2          0
-#define EXAMPLE_PIN_NUM_DATA3          22
-#define EXAMPLE_PIN_NUM_DATA4          23
-#define EXAMPLE_PIN_NUM_DATA5          33
-#define EXAMPLE_PIN_NUM_DATA6          32
-#define EXAMPLE_PIN_NUM_DATA7          27
-#define EXAMPLE_PIN_NUM_PCLK           18
-#define EXAMPLE_PIN_NUM_CS             4
-#define EXAMPLE_PIN_NUM_DC             5
-#define EXAMPLE_PIN_NUM_RST            -1
-#define EXAMPLE_PIN_NUM_BK_LIGHT       2
+#define EXAMPLE_PIN_NUM_DATA0          6
+#define EXAMPLE_PIN_NUM_DATA1          7
+#define EXAMPLE_PIN_NUM_DATA2          8
+#define EXAMPLE_PIN_NUM_DATA3          9
+#define EXAMPLE_PIN_NUM_DATA4          10
+#define EXAMPLE_PIN_NUM_DATA5          11
+#define EXAMPLE_PIN_NUM_DATA6          12
+#define EXAMPLE_PIN_NUM_DATA7          13
+#define EXAMPLE_PIN_NUM_PCLK           5
+#define EXAMPLE_PIN_NUM_CS             3
+#define EXAMPLE_PIN_NUM_DC             4
+#define EXAMPLE_PIN_NUM_RST            2
+#define EXAMPLE_PIN_NUM_BK_LIGHT       1
 
 // The pixel number in horizontal and vertical
 #define EXAMPLE_LCD_H_RES              240
@@ -47,6 +53,9 @@ static const char *TAG = "example";
 
 #define EXAMPLE_LVGL_TICK_PERIOD_MS    2
 
+// Supported alignment: 16, 32, 64. A higher alignment can enables higher burst transfer size, thus a higher i80 bus throughput.
+#define EXAMPLE_PSRAM_DATA_ALIGNMENT   64
+
 extern void example_lvgl_demo_ui(lv_obj_t *scr);
 
 static bool example_notify_lvgl_flush_ready(esp_lcd_panel_io_handle_t panel_io, esp_lcd_panel_io_event_data_t *edata, void *user_ctx)
@@ -102,7 +111,9 @@ void app_main(void)
             EXAMPLE_PIN_NUM_DATA7,
         },
         .bus_width = 8,
-        .max_transfer_bytes = EXAMPLE_LCD_H_RES * 40 * sizeof(uint16_t)
+        .max_transfer_bytes = EXAMPLE_LCD_H_RES * 100 * sizeof(uint16_t),
+        .psram_trans_align = EXAMPLE_PSRAM_DATA_ALIGNMENT,
+        .sram_trans_align = 4,
     };
     ESP_ERROR_CHECK(esp_lcd_new_i80_bus(&bus_config, &i80_bus));
     esp_lcd_panel_io_handle_t io_handle = NULL;
@@ -145,12 +156,23 @@ void app_main(void)
     lv_init();
     // alloc draw buffers used by LVGL
     // it's recommended to choose the size of the draw buffer(s) to be at least 1/10 screen sized
-    lv_color_t *buf1 = heap_caps_malloc(EXAMPLE_LCD_H_RES * 20 * sizeof(lv_color_t), MALLOC_CAP_DMA);
+    lv_color_t *buf1 = NULL;
+    lv_color_t *buf2 = NULL;
+#if CONFIG_EXAMPLE_LCD_I80_COLOR_IN_PSRAM
+    buf1 = heap_caps_aligned_alloc(EXAMPLE_PSRAM_DATA_ALIGNMENT, EXAMPLE_LCD_H_RES * 100 * sizeof(lv_color_t), MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
+#else
+    buf1 = heap_caps_malloc(EXAMPLE_LCD_H_RES * 100 * sizeof(lv_color_t), MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
+#endif
     assert(buf1);
-    lv_color_t *buf2 = heap_caps_malloc(EXAMPLE_LCD_H_RES * 20 * sizeof(lv_color_t), MALLOC_CAP_DMA);
+#if CONFIG_EXAMPLE_LCD_I80_COLOR_IN_PSRAM
+    buf2 = heap_caps_aligned_alloc(EXAMPLE_PSRAM_DATA_ALIGNMENT, EXAMPLE_LCD_H_RES * 100 * sizeof(lv_color_t), MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
+#else
+    buf2 = heap_caps_malloc(EXAMPLE_LCD_H_RES * 100 * sizeof(lv_color_t), MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL);
+#endif
     assert(buf2);
+    ESP_LOGI(TAG, "buf1@%p, buf2@%p", buf1, buf2);
     // initialize LVGL draw buffers
-    lv_disp_draw_buf_init(&disp_buf, buf1, buf2, EXAMPLE_LCD_H_RES * 20);
+    lv_disp_draw_buf_init(&disp_buf, buf1, buf2, EXAMPLE_LCD_H_RES * 100);
 
     ESP_LOGI(TAG, "Register display driver to LVGL");
     lv_disp_drv_init(&disp_drv);

examples/peripherals/lcd/i80_controller/main/idf_component.yml

@@ -1,3 +1,3 @@
 dependencies:
   idf: ">=4.4"
-  lvgl/lvgl: "==8.0.2"
+  lvgl/lvgl: "~8.0.2"

examples/peripherals/lcd/i80_controller/main/images/esp_logo.c

@@ -1,3 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+// NOTE: The logo in this file is registered trademark by Espressif Systems (Shanghai) CO LTD.
+
 #include "lvgl.h"
 
 

examples/peripherals/lcd/i80_controller/main/images/esp_text.c

@@ -1,3 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
 #include "lvgl.h"
 
 #ifndef LV_ATTRIBUTE_MEM_ALIGN

examples/peripherals/lcd/i80_controller/main/lvgl_demo_ui.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: CC0-1.0
  */

examples/peripherals/lcd/i80_controller/sdkconfig.defaults

@@ -1,3 +1,5 @@
+CONFIG_LV_MEM_CUSTOM=y
+CONFIG_LV_MEMCPY_MEMSET_STD=y
 CONFIG_LV_USE_PERF_MONITOR=y
 CONFIG_LV_USE_USER_DATA=y
 CONFIG_LV_COLOR_16_SWAP=y

examples/peripherals/lcd/i80_controller/sdkconfig.defaults.esp32s3

@@ -0,0 +1,4 @@
+CONFIG_ESP32S3_SPIRAM_SUPPORT=y
+CONFIG_SPIRAM_SPEED_80M=y
+# Can't set the FPS too high due to the limitation of PSRAM bandwidth
+CONFIG_LV_DISP_DEF_REFR_PERIOD=100

examples/peripherals/lcd/lvgl/main/CMakeLists.txt

@@ -1,4 +0,0 @@
-file(GLOB_RECURSE IMAGE_SOURCES images/*.c)
-
-idf_component_register(SRCS "lvgl_example_main.c" "lvgl_demo_ui.c" ${IMAGE_SOURCES}
-                       INCLUDE_DIRS ".")