feat(esp_lvgl_port): Use display flush wait callback with semaphore

In the current implementation LVGL spins in a busy loop until
lv_disp_flush_ready() is called. This commit utilizes the flush wait
callback mechanism is used instead. lvgl_port_flush_wait_smphr_callback()
waits on a semaphore allowing other FreeRTOS tasks to run. CPU usage by
LVGL task is reduced by 2-3%.

This feature is not avalable for RGB interface - I don't know exactly how
flushing works in this case. The task notification and waking up in
lvgl_port_flush_gsync_ready_callback() is confusing. Also
lvgl_port_flush_ready() is untouched.

Author: Trigger239

components/esp_lvgl_port/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [Unreleased]
+
+### Features
+- Added display flush wait callback support
+
 ## 2.6.2
 
 - Changed minimum IDF version to IDF5.1

components/esp_lvgl_port/priv_include/esp_lvgl_port_priv.h

@@ -29,6 +29,7 @@ typedef enum {
  */
 typedef struct {
     unsigned int avoid_tearing: 1;    /*!< Use internal RGB buffers as a LVGL draw buffers to avoid tearing effect */
+    unsigned int use_flush_smphr: 1;  /*!< Use semaphore to signal LCD panel flush done */
 } lvgl_port_disp_priv_cfg_t;
 
 /**

components/esp_lvgl_port/src/lvgl9/esp_lvgl_port_disp.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -59,6 +59,7 @@ typedef struct {
     uint8_t                   *oled_buffer;
     lv_display_t              *disp_drv;      /* LVGL display driver */
     lv_display_rotation_t     current_rotation;
+    SemaphoreHandle_t         flush_smphr;    /* LCD panel Flush Done semaphore (NULL if lv_disp_flush_ready() is used) */
     SemaphoreHandle_t         trans_sem;      /* Idle transfer mutex */
 #if LVGL_PORT_PPA
     lvgl_port_ppa_handle_t    ppa_handle;
@@ -85,6 +86,7 @@ static bool lvgl_port_flush_rgb_vsync_ready_callback(esp_lcd_panel_handle_t pane
 static bool lvgl_port_flush_dpi_panel_ready_callback(esp_lcd_panel_handle_t panel_io, esp_lcd_dpi_panel_event_data_t *edata, void *user_ctx);
 static bool lvgl_port_flush_dpi_vsync_ready_callback(esp_lcd_panel_handle_t panel_io, esp_lcd_dpi_panel_event_data_t *edata, void *user_ctx);
 #endif
+static void lvgl_port_flush_wait_smphr_callback(lv_display_t *drv);
 #endif
 static void lvgl_port_flush_callback(lv_display_t *drv, const lv_area_t *area, uint8_t *color_map);
 static void lvgl_port_disp_size_update_callback(lv_event_t *e);
@@ -98,7 +100,14 @@ static void lvgl_port_display_invalidate_callback(lv_event_t *e);
 lv_display_t *lvgl_port_add_disp(const lvgl_port_display_cfg_t *disp_cfg)
 {
     lvgl_port_lock(0);
-    lv_disp_t *disp = lvgl_port_add_disp_priv(disp_cfg, NULL);
+    const lvgl_port_disp_priv_cfg_t priv_cfg = {
+#if LVGL_PORT_HANDLE_FLUSH_READY
+        .use_flush_smphr = 1, /* Always use semaphore for now */
+#else
+        .use_flush_smphr = 0, /* Don't need semaphore if not handling flush ready */
+#endif
+    };
+    lv_disp_t *disp = lvgl_port_add_disp_priv(disp_cfg, &priv_cfg);
 
     if (disp != NULL) {
         lvgl_port_display_ctx_t *disp_ctx = (lvgl_port_display_ctx_t *)lv_display_get_driver_data(disp);
@@ -113,6 +122,11 @@ lv_display_t *lvgl_port_add_disp(const lvgl_port_display_cfg_t *disp_cfg)
         };
         /* Register done callback */
         esp_lcd_panel_io_register_event_callbacks(disp_ctx->io_handle, &cbs, disp);
+
+        /* Register wait callback if using semaphore */
+        if (disp_ctx->flush_smphr) {
+            lv_display_set_flush_wait_cb(disp, lvgl_port_flush_wait_smphr_callback);
+        }
 #endif
 
         /* Apply rotation from initial display configuration */
@@ -128,6 +142,7 @@ lv_display_t *lvgl_port_add_disp_dsi(const lvgl_port_display_cfg_t *disp_cfg, co
     assert(dsi_cfg != NULL);
     const lvgl_port_disp_priv_cfg_t priv_cfg = {
         .avoid_tearing = dsi_cfg->flags.avoid_tearing,
+        .use_flush_smphr = 1, /* Always use semaphore for now */
     };
     lvgl_port_lock(0);
     lv_disp_t *disp = lvgl_port_add_disp_priv(disp_cfg, &priv_cfg);
@@ -147,6 +162,11 @@ lv_display_t *lvgl_port_add_disp_dsi(const lvgl_port_display_cfg_t *disp_cfg, co
         /* Register done callback */
         esp_lcd_dpi_panel_register_event_callbacks(disp_ctx->panel_handle, &cbs, disp);
 
+        /* Register wait callback if using semaphore */
+        if (disp_ctx->flush_smphr) {
+            lv_display_set_flush_wait_cb(disp, lvgl_port_flush_wait_smphr_callback);
+        }
+
         /* Apply rotation from initial display configuration */
         lvgl_port_disp_rotation_update(disp_ctx);
 
@@ -232,6 +252,10 @@ esp_err_t lvgl_port_remove_disp(lv_display_t *disp)
     if (disp_ctx->trans_sem) {
         vSemaphoreDelete(disp_ctx->trans_sem);
     }
+
+    if (disp_ctx->flush_smphr) {
+        vSemaphoreDelete(disp_ctx->flush_smphr);
+    }
 #if LVGL_PORT_PPA
     if (disp_ctx->ppa_handle) {
         lvgl_port_ppa_delete(disp_ctx->ppa_handle);
@@ -261,6 +285,7 @@ static lv_display_t *lvgl_port_add_disp_priv(const lvgl_port_display_cfg_t *disp
     lv_color_t *buf2 = NULL;
     uint32_t buffer_size = 0;
     SemaphoreHandle_t trans_sem = NULL;
+    SemaphoreHandle_t flush_sem = NULL;
     assert(disp_cfg != NULL);
     assert(disp_cfg->panel_handle != NULL);
     assert(disp_cfg->buffer_size > 0);
@@ -341,6 +366,13 @@ static lv_display_t *lvgl_port_add_disp_priv(const lvgl_port_display_cfg_t *disp
         disp_ctx->draw_buffs[1] = buf2;
     }
 
+    /* Use semaphore to signal LCD panel flush done */
+    if (priv_cfg && priv_cfg->use_flush_smphr) {
+        flush_sem = xSemaphoreCreateBinary();
+        ESP_GOTO_ON_FALSE(flush_sem, ESP_ERR_NO_MEM, err, TAG, "Failed to create flush Semaphore");
+        disp_ctx->flush_smphr = flush_sem;
+    }
+
     disp = lv_display_create(disp_cfg->hres, disp_cfg->vres);
 
     /* Set display color format */
@@ -441,6 +473,9 @@ static lv_display_t *lvgl_port_add_disp_priv(const lvgl_port_display_cfg_t *disp
         if (trans_sem) {
             vSemaphoreDelete(trans_sem);
         }
+        if (flush_sem) {
+            vSemaphoreDelete(flush_sem);
+        }
     }
 
     return disp;
@@ -449,19 +484,47 @@ static lv_display_t *lvgl_port_add_disp_priv(const lvgl_port_display_cfg_t *disp
 #if LVGL_PORT_HANDLE_FLUSH_READY
 static bool lvgl_port_flush_io_ready_callback(esp_lcd_panel_io_handle_t panel_io, esp_lcd_panel_io_event_data_t *edata, void *user_ctx)
 {
+    BaseType_t need_yield = pdFALSE;
+
     lv_display_t *disp_drv = (lv_display_t *)user_ctx;
     assert(disp_drv != NULL);
-    lv_disp_flush_ready(disp_drv);
-    return false;
+    lvgl_port_display_ctx_t *disp_ctx = lv_display_get_user_data(disp_drv);
+    assert(disp_ctx != NULL);
+
+    if (disp_ctx->flush_smphr) {
+        if (xPortInIsrContext() == pdTRUE) {
+            need_yield = xSemaphoreGiveFromISR(disp_ctx->flush_smphr, &need_yield);
+        } else {
+            xSemaphoreGive(disp_ctx->flush_smphr);
+        }
+    } else {
+        lv_disp_flush_ready(disp_drv);
+    }
+
+    return (need_yield == pdTRUE);
 }
 
 #if (CONFIG_IDF_TARGET_ESP32P4 && ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 0))
 static bool lvgl_port_flush_dpi_panel_ready_callback(esp_lcd_panel_handle_t panel_io, esp_lcd_dpi_panel_event_data_t *edata, void *user_ctx)
 {
+    BaseType_t need_yield = pdFALSE;
+
     lv_display_t *disp_drv = (lv_display_t *)user_ctx;
     assert(disp_drv != NULL);
-    lv_disp_flush_ready(disp_drv);
-    return false;
+    lvgl_port_display_ctx_t *disp_ctx = lv_display_get_user_data(disp_drv);
+    assert(disp_ctx != NULL);
+
+    if (disp_ctx->flush_smphr) {
+        if (xPortInIsrContext() == pdTRUE) {
+            need_yield = xSemaphoreGiveFromISR(disp_ctx->flush_smphr, &need_yield);
+        } else {
+            xSemaphoreGive(disp_ctx->flush_smphr);
+        }
+    } else {
+        lv_disp_flush_ready(disp_drv);
+    }
+
+    return (need_yield == pdTRUE);
 }
 
 static bool lvgl_port_flush_dpi_vsync_ready_callback(esp_lcd_panel_handle_t panel_io, esp_lcd_dpi_panel_event_data_t *edata, void *user_ctx)
@@ -498,6 +561,16 @@ static bool lvgl_port_flush_rgb_vsync_ready_callback(esp_lcd_panel_handle_t pane
     return (need_yield == pdTRUE);
 }
 #endif
+
+static void lvgl_port_flush_wait_smphr_callback(lv_display_t *drv)
+{
+    assert(drv != NULL);
+
+    lvgl_port_display_ctx_t *disp_ctx = lv_display_get_driver_data(drv);
+    assert(disp_ctx != NULL);
+    assert(disp_ctx->flush_smphr != NULL); /* This callback should only be used with semaphore */
+    xSemaphoreTake(disp_ctx->flush_smphr, portMAX_DELAY);
+}
 #endif
 
 static void _lvgl_port_transform_monochrome(lv_display_t *display, const lv_area_t *area, uint8_t **color_map)