From beef3bd065163f269a8ae93d3ef08c6c41960f33 Mon Sep 17 00:00:00 2001 From: Liu Zhongwei Date: Tue, 12 Sep 2023 15:33:30 +0800 Subject: [PATCH] feat(esp_lcd): add lock for lvgl in examples --- .../lcd/i2c_oled/main/i2c_oled_example_main.c | 9 ++- .../peripherals/lcd/i80_controller/README.md | 6 +- .../main/i80_controller_example_main.c | 57 +++++++++++++++--- examples/peripherals/lcd/rgb_panel/README.md | 8 ++- .../lcd/rgb_panel/main/rgb_lcd_example_main.c | 60 +++++++++++++++---- .../peripherals/lcd/spi_lcd_touch/README.md | 6 +- .../main/spi_lcd_touch_example_main.c | 58 +++++++++++++++--- 7 files changed, 173 insertions(+), 31 deletions(-) diff --git a/examples/peripherals/lcd/i2c_oled/main/i2c_oled_example_main.c b/examples/peripherals/lcd/i2c_oled/main/i2c_oled_example_main.c index fa71893d5f..b95a6f77b8 100644 --- a/examples/peripherals/lcd/i2c_oled/main/i2c_oled_example_main.c +++ b/examples/peripherals/lcd/i2c_oled/main/i2c_oled_example_main.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: CC0-1.0 */ @@ -141,5 +141,10 @@ void app_main(void) lv_disp_set_rotation(disp, LV_DISP_ROT_NONE); ESP_LOGI(TAG, "Display LVGL Scroll Text"); - example_lvgl_demo_ui(disp); + // Lock the mutex due to the LVGL APIs are not thread-safe + if (lvgl_port_lock(0)) { + example_lvgl_demo_ui(disp); + // Release the mutex + lvgl_port_unlock(); + } } diff --git a/examples/peripherals/lcd/i80_controller/README.md b/examples/peripherals/lcd/i80_controller/README.md index 55652f79c2..81f68ae419 100644 --- a/examples/peripherals/lcd/i80_controller/README.md +++ b/examples/peripherals/lcd/i80_controller/README.md @@ -13,7 +13,7 @@ The UI will display two images (one Espressif logo and another Espressif text), This example is constructed by [IDF component manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html), all the external dependency will be handled by the CMake build system automatically. In this case, it will help download the lvgl from [registry](https://components.espressif.com/component/lvgl/lvgl), with the version specified in the [manifest file](main/idf_component.yml). -This example uses the [esp_timer](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/esp_timer.html) to generate the ticks needed by LVGL. For more porting guides, please refer to [LVGL porting doc](https://docs.lvgl.io/master/porting/index.html). +This example uses the [esp_timer](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/esp_timer.html) to generate the ticks needed by LVGL and uses a dedicated task to run the `lv_timer_handler()`. Since the LVGL APIs are not thread-safe, this example uses a mutex which be invoked before the call of `lv_timer_handler()` and released after it. The same mutex needs to be used in other tasks and threads around every LVGL (lv_...) related function call and code. For more porting guides, please refer to [LVGL porting doc](https://docs.lvgl.io/master/porting/index.html). ## How to use the example @@ -94,7 +94,9 @@ I (558) example: Turn on LCD backlight I (558) example: Initialize LVGL library I (558) example: Register display driver to LVGL I (558) example: Install LVGL tick timer -I (558) example: Display LVGL animation +I (558) example: Create LVGL task +I (558) example: Starting LVGL task +I (638) example: Display LVGL animation ``` ## Touch Screen Support diff --git a/examples/peripherals/lcd/i80_controller/main/i80_controller_example_main.c b/examples/peripherals/lcd/i80_controller/main/i80_controller_example_main.c index 13a72fc0af..f8c5ea29c9 100644 --- a/examples/peripherals/lcd/i80_controller/main/i80_controller_example_main.c +++ b/examples/peripherals/lcd/i80_controller/main/i80_controller_example_main.c @@ -7,6 +7,7 @@ #include #include "freertos/FreeRTOS.h" #include "freertos/task.h" +#include "freertos/semphr.h" #include "esp_timer.h" #include "esp_lcd_panel_io.h" #include "esp_lcd_panel_vendor.h" @@ -86,10 +87,16 @@ static const char *TAG = "example"; #endif #define EXAMPLE_LVGL_TICK_PERIOD_MS 2 +#define EXAMPLE_LVGL_TASK_MAX_DELAY_MS 500 +#define EXAMPLE_LVGL_TASK_MIN_DELAY_MS 1 +#define EXAMPLE_LVGL_TASK_STACK_SIZE (4 * 1024) +#define EXAMPLE_LVGL_TASK_PRIORITY 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 +static SemaphoreHandle_t lvgl_mux = NULL; + extern void example_lvgl_demo_ui(lv_disp_t *disp); 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) @@ -139,6 +146,39 @@ static void example_increase_lvgl_tick(void *arg) lv_tick_inc(EXAMPLE_LVGL_TICK_PERIOD_MS); } +bool example_lvgl_lock(int timeout_ms) +{ + // Convert timeout in milliseconds to FreeRTOS ticks + // If `timeout_ms` is set to -1, the program will block until the condition is met + const TickType_t timeout_ticks = (timeout_ms == -1) ? portMAX_DELAY : pdMS_TO_TICKS(timeout_ms); + return xSemaphoreTakeRecursive(lvgl_mux, timeout_ticks) == pdTRUE; +} + +void example_lvgl_unlock(void) +{ + xSemaphoreGiveRecursive(lvgl_mux); +} + +static void example_lvgl_port_task(void *arg) +{ + ESP_LOGI(TAG, "Starting LVGL task"); + uint32_t task_delay_ms = EXAMPLE_LVGL_TASK_MAX_DELAY_MS; + while (1) { + // Lock the mutex due to the LVGL APIs are not thread-safe + if (example_lvgl_lock(-1)) { + task_delay_ms = lv_timer_handler(); + // Release the mutex + example_lvgl_unlock(); + } + if (task_delay_ms > EXAMPLE_LVGL_TASK_MAX_DELAY_MS) { + task_delay_ms = EXAMPLE_LVGL_TASK_MAX_DELAY_MS; + } else if (task_delay_ms < EXAMPLE_LVGL_TASK_MIN_DELAY_MS) { + task_delay_ms = EXAMPLE_LVGL_TASK_MIN_DELAY_MS; + } + vTaskDelay(pdMS_TO_TICKS(task_delay_ms)); + } +} + #if CONFIG_EXAMPLE_LCD_IMAGE_FROM_FILE_SYSTEM void example_init_filesystem(void) { @@ -448,13 +488,16 @@ void app_main(void) lv_indev_drv_register(&indev_drv); #endif // CONFIG_EXAMPLE_LCD_TOUCH_ENABLED - ESP_LOGI(TAG, "Display LVGL animation"); - example_lvgl_demo_ui(disp); + lvgl_mux = xSemaphoreCreateRecursiveMutex(); + assert(lvgl_mux); + ESP_LOGI(TAG, "Create LVGL task"); + xTaskCreate(example_lvgl_port_task, "LVGL", EXAMPLE_LVGL_TASK_STACK_SIZE, NULL, EXAMPLE_LVGL_TASK_PRIORITY, NULL); - while (1) { - // raise the task priority of LVGL and/or reduce the handler period can improve the performance - vTaskDelay(pdMS_TO_TICKS(10)); - // The task running lv_timer_handler should have lower priority than that running `lv_tick_inc` - lv_timer_handler(); + ESP_LOGI(TAG, "Display LVGL animation"); + // Lock the mutex due to the LVGL APIs are not thread-safe + if (example_lvgl_lock(-1)) { + example_lvgl_demo_ui(disp); + // Release the mutex + example_lvgl_unlock(); } } diff --git a/examples/peripherals/lcd/rgb_panel/README.md b/examples/peripherals/lcd/rgb_panel/README.md index 44a01a8cae..087cbbe58b 100644 --- a/examples/peripherals/lcd/rgb_panel/README.md +++ b/examples/peripherals/lcd/rgb_panel/README.md @@ -5,7 +5,11 @@ [esp_lcd](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/lcd.html) supports RGB interfaced LCD panel, with one or two frame buffer(s) managed by the driver itself. -This example shows the general process of installing an RGB panel driver, and displays a scatter chart on the screen based on the LVGL library. For more information about porting the LVGL library, please refer to [official porting guide](https://docs.lvgl.io/master/porting/index.html). This example uses two kinds of **buffering mode** based on the number of frame buffers: +This example shows the general process of installing an RGB panel driver, and displays a scatter chart on the screen based on the LVGL library. + +This example uses the [esp_timer](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/esp_timer.html) to generate the ticks needed by LVGL and uses a dedicated task to run the `lv_timer_handler()`. Since the LVGL APIs are not thread-safe, this example uses a mutex which be invoked before the call of `lv_timer_handler()` and released after it. The same mutex needs to be used in other tasks and threads around every LVGL (lv_...) related function call and code. For more porting guides, please refer to [LVGL porting doc](https://docs.lvgl.io/master/porting/index.html). + +This example uses two kinds of **buffering mode** based on the number of frame buffers: | Number of Frame Buffers | LVGL buffering mode | Way to avoid tear effect | |-------------------------|---------------------|-------------------------------------------------------------------------------------------------------------| @@ -89,6 +93,8 @@ I (906) example: Initialize LVGL library I (916) example: Allocate separate LVGL draw buffers from PSRAM I (916) example: Register display driver to LVGL I (926) example: Install LVGL tick timer +I (926) example: Create LVGL task +I (926) example: Starting LVGL task I (926) example: Display LVGL Scatter Chart ... ``` diff --git a/examples/peripherals/lcd/rgb_panel/main/rgb_lcd_example_main.c b/examples/peripherals/lcd/rgb_panel/main/rgb_lcd_example_main.c index f9ebecb946..8c8599a3d3 100644 --- a/examples/peripherals/lcd/rgb_panel/main/rgb_lcd_example_main.c +++ b/examples/peripherals/lcd/rgb_panel/main/rgb_lcd_example_main.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: CC0-1.0 */ @@ -59,6 +59,12 @@ static const char *TAG = "example"; #endif // CONFIG_EXAMPLE_DOUBLE_FB #define EXAMPLE_LVGL_TICK_PERIOD_MS 2 +#define EXAMPLE_LVGL_TASK_MAX_DELAY_MS 500 +#define EXAMPLE_LVGL_TASK_MIN_DELAY_MS 1 +#define EXAMPLE_LVGL_TASK_STACK_SIZE (4 * 1024) +#define EXAMPLE_LVGL_TASK_PRIORITY 2 + +static SemaphoreHandle_t lvgl_mux = NULL; // we use two semaphores to sync the VSYNC event and the LVGL task, to avoid potential tearing effect #if CONFIG_EXAMPLE_AVOID_TEAR_EFFECT_WITH_SEM @@ -101,6 +107,39 @@ static void example_increase_lvgl_tick(void *arg) lv_tick_inc(EXAMPLE_LVGL_TICK_PERIOD_MS); } +bool example_lvgl_lock(int timeout_ms) +{ + // Convert timeout in milliseconds to FreeRTOS ticks + // If `timeout_ms` is set to -1, the program will block until the condition is met + const TickType_t timeout_ticks = (timeout_ms == -1) ? portMAX_DELAY : pdMS_TO_TICKS(timeout_ms); + return xSemaphoreTakeRecursive(lvgl_mux, timeout_ticks) == pdTRUE; +} + +void example_lvgl_unlock(void) +{ + xSemaphoreGiveRecursive(lvgl_mux); +} + +static void example_lvgl_port_task(void *arg) +{ + ESP_LOGI(TAG, "Starting LVGL task"); + uint32_t task_delay_ms = EXAMPLE_LVGL_TASK_MAX_DELAY_MS; + while (1) { + // Lock the mutex due to the LVGL APIs are not thread-safe + if (example_lvgl_lock(-1)) { + task_delay_ms = lv_timer_handler(); + // Release the mutex + example_lvgl_unlock(); + } + if (task_delay_ms > EXAMPLE_LVGL_TASK_MAX_DELAY_MS) { + task_delay_ms = EXAMPLE_LVGL_TASK_MAX_DELAY_MS; + } else if (task_delay_ms < EXAMPLE_LVGL_TASK_MIN_DELAY_MS) { + task_delay_ms = EXAMPLE_LVGL_TASK_MIN_DELAY_MS; + } + vTaskDelay(pdMS_TO_TICKS(task_delay_ms)); + } +} + void app_main(void) { static lv_disp_draw_buf_t disp_buf; // contains internal graphic buffer(s) called draw buffer(s) @@ -201,8 +240,6 @@ void app_main(void) ESP_LOGI(TAG, "Allocate separate LVGL draw buffers from PSRAM"); buf1 = heap_caps_malloc(EXAMPLE_LCD_H_RES * 100 * sizeof(lv_color_t), MALLOC_CAP_SPIRAM); assert(buf1); - buf2 = heap_caps_malloc(EXAMPLE_LCD_H_RES * 100 * sizeof(lv_color_t), MALLOC_CAP_SPIRAM); - assert(buf2); // initialize LVGL draw buffers lv_disp_draw_buf_init(&disp_buf, buf1, buf2, EXAMPLE_LCD_H_RES * 100); #endif // CONFIG_EXAMPLE_DOUBLE_FB @@ -229,13 +266,16 @@ void app_main(void) ESP_ERROR_CHECK(esp_timer_create(&lvgl_tick_timer_args, &lvgl_tick_timer)); ESP_ERROR_CHECK(esp_timer_start_periodic(lvgl_tick_timer, EXAMPLE_LVGL_TICK_PERIOD_MS * 1000)); - ESP_LOGI(TAG, "Display LVGL Scatter Chart"); - example_lvgl_demo_ui(disp); + lvgl_mux = xSemaphoreCreateRecursiveMutex(); + assert(lvgl_mux); + ESP_LOGI(TAG, "Create LVGL task"); + xTaskCreate(example_lvgl_port_task, "LVGL", EXAMPLE_LVGL_TASK_STACK_SIZE, NULL, EXAMPLE_LVGL_TASK_PRIORITY, NULL); - while (1) { - // raise the task priority of LVGL and/or reduce the handler period can improve the performance - vTaskDelay(pdMS_TO_TICKS(10)); - // The task running lv_timer_handler should have lower priority than that running `lv_tick_inc` - lv_timer_handler(); + ESP_LOGI(TAG, "Display LVGL Scatter Chart"); + // Lock the mutex due to the LVGL APIs are not thread-safe + if (example_lvgl_lock(-1)) { + example_lvgl_demo_ui(disp); + // Release the mutex + example_lvgl_unlock(); } } diff --git a/examples/peripherals/lcd/spi_lcd_touch/README.md b/examples/peripherals/lcd/spi_lcd_touch/README.md index 804abb7aef..fec1348be3 100644 --- a/examples/peripherals/lcd/spi_lcd_touch/README.md +++ b/examples/peripherals/lcd/spi_lcd_touch/README.md @@ -7,7 +7,9 @@ `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 use GC9A01 or ILI9341 display driver from Component manager in esp-idf project. These components are using API provided by `esp_lcd` component. 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). +This example shows how to use GC9A01 or ILI9341 display driver from Component manager in esp-idf project. These components are using API provided by `esp_lcd` component. This example will draw a fancy dash board with the LVGL library. + +This example uses the [esp_timer](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/esp_timer.html) to generate the ticks needed by LVGL and uses a dedicated task to run the `lv_timer_handler()`. Since the LVGL APIs are not thread-safe, this example uses a mutex which be invoked before the call of `lv_timer_handler()` and released after it. The same mutex needs to be used in other tasks and threads around every LVGL (lv_...) related function call and code. For more porting guides, please refer to [LVGL porting doc](https://docs.lvgl.io/master/porting/index.html). ## Touch controller STMPE610 @@ -83,6 +85,8 @@ I (599) example: Turn on LCD backlight I (599) example: Initialize LVGL library I (609) example: Register display driver to LVGL I (619) example: Install LVGL tick timer +I (619) example: Starting LVGL task +I (619) example: Display LVGL animation I (619) example: Display LVGL Meter Widget ... ``` diff --git a/examples/peripherals/lcd/spi_lcd_touch/main/spi_lcd_touch_example_main.c b/examples/peripherals/lcd/spi_lcd_touch/main/spi_lcd_touch_example_main.c index 4b761fc95a..03c7921e32 100644 --- a/examples/peripherals/lcd/spi_lcd_touch/main/spi_lcd_touch_example_main.c +++ b/examples/peripherals/lcd/spi_lcd_touch/main/spi_lcd_touch_example_main.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: CC0-1.0 */ @@ -7,6 +7,7 @@ #include #include "freertos/FreeRTOS.h" #include "freertos/task.h" +#include "freertos/semphr.h" #include "esp_timer.h" #include "esp_lcd_panel_io.h" #include "esp_lcd_panel_vendor.h" @@ -60,7 +61,12 @@ static const char *TAG = "example"; #define EXAMPLE_LCD_PARAM_BITS 8 #define EXAMPLE_LVGL_TICK_PERIOD_MS 2 +#define EXAMPLE_LVGL_TASK_MAX_DELAY_MS 500 +#define EXAMPLE_LVGL_TASK_MIN_DELAY_MS 1 +#define EXAMPLE_LVGL_TASK_STACK_SIZE (4 * 1024) +#define EXAMPLE_LVGL_TASK_PRIORITY 2 +static SemaphoreHandle_t lvgl_mux = NULL; #if CONFIG_EXAMPLE_LCD_TOUCH_ENABLED esp_lcd_touch_handle_t tp = NULL; @@ -164,6 +170,39 @@ static void example_increase_lvgl_tick(void *arg) lv_tick_inc(EXAMPLE_LVGL_TICK_PERIOD_MS); } +bool example_lvgl_lock(int timeout_ms) +{ + // Convert timeout in milliseconds to FreeRTOS ticks + // If `timeout_ms` is set to -1, the program will block until the condition is met + const TickType_t timeout_ticks = (timeout_ms == -1) ? portMAX_DELAY : pdMS_TO_TICKS(timeout_ms); + return xSemaphoreTakeRecursive(lvgl_mux, timeout_ticks) == pdTRUE; +} + +void example_lvgl_unlock(void) +{ + xSemaphoreGiveRecursive(lvgl_mux); +} + +static void example_lvgl_port_task(void *arg) +{ + ESP_LOGI(TAG, "Starting LVGL task"); + uint32_t task_delay_ms = EXAMPLE_LVGL_TASK_MAX_DELAY_MS; + while (1) { + // Lock the mutex due to the LVGL APIs are not thread-safe + if (example_lvgl_lock(-1)) { + task_delay_ms = lv_timer_handler(); + // Release the mutex + example_lvgl_unlock(); + } + if (task_delay_ms > EXAMPLE_LVGL_TASK_MAX_DELAY_MS) { + task_delay_ms = EXAMPLE_LVGL_TASK_MAX_DELAY_MS; + } else if (task_delay_ms < EXAMPLE_LVGL_TASK_MIN_DELAY_MS) { + task_delay_ms = EXAMPLE_LVGL_TASK_MIN_DELAY_MS; + } + vTaskDelay(pdMS_TO_TICKS(task_delay_ms)); + } +} + void app_main(void) { static lv_disp_draw_buf_t disp_buf; // contains internal graphic buffer(s) called draw buffer(s) @@ -296,13 +335,16 @@ void app_main(void) lv_indev_drv_register(&indev_drv); #endif - ESP_LOGI(TAG, "Display LVGL Meter Widget"); - example_lvgl_demo_ui(disp); + lvgl_mux = xSemaphoreCreateRecursiveMutex(); + assert(lvgl_mux); + ESP_LOGI(TAG, "Create LVGL task"); + xTaskCreate(example_lvgl_port_task, "LVGL", EXAMPLE_LVGL_TASK_STACK_SIZE, NULL, EXAMPLE_LVGL_TASK_PRIORITY, NULL); - while (1) { - // raise the task priority of LVGL and/or reduce the handler period can improve the performance - vTaskDelay(pdMS_TO_TICKS(10)); - // The task running lv_timer_handler should have lower priority than that running `lv_tick_inc` - lv_timer_handler(); + ESP_LOGI(TAG, "Display LVGL Meter Widget"); + // Lock the mutex due to the LVGL APIs are not thread-safe + if (example_lvgl_lock(-1)) { + example_lvgl_demo_ui(disp); + // Release the mutex + example_lvgl_unlock(); } }