lcd_bus: DSIBus rotation through the PPA (ESP32-P4)

Panels on the DSI video interface cannot swap rows and columns, so a
landscape UI on a portrait panel needs the picture rotated on the way
to the frame buffer. DSIBus(rotation=90|180|270) does that with the
ESP32-P4's PPA (pixel processing accelerator): LVGL renders the rotated
(logical) picture into the bus's own screen-sized buffers, and on the
last flush of an update the whole picture is rotated by the PPA into
the panel's back buffer, which is then swapped in at the next frame
boundary (the refresh-done interrupt reports completion as before).
The panel side is always double-buffered in this mode; intermediate
areas of a multi-area update complete immediately. The angle follows
LVGL's convention, so pass the same rotation to lv_display.

Frame buffers are now allocated cache-line aligned (the PPA and the DPI
DMA both need it), the PPA driver's include path is added where the
chip has one, and rotation is refused on chips without a PPA.

Verified on the Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 (480x800 panel,
rotation=90): LVGL runs at 800x480, a forced full-screen refresh takes
~29 ms (render + PPA rotation + vsync) against ~15 ms unrotated.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: bitcoin3us

ext_mod/lcd_bus/esp32_include/dsi_bus.h

@@ -23,6 +23,10 @@
         #include "esp_lcd_mipi_dsi.h"
         #include "esp_ldo_regulator.h"
 
+        #if SOC_PPA_SUPPORTED
+            #include "driver/ppa.h"
+        #endif
+
 
         typedef struct _mp_lcd_dsi_bus_obj_t {
             // The first members mirror mp_lcd_bus_obj_t (lcd_types.h): the
@@ -55,6 +59,20 @@
             int phy_ldo_voltage_mv;
             esp_ldo_channel_handle_t phy_ldo_handle;
 
+            // rotation (0/90/180/270 degrees, LVGL's sense): LVGL renders the
+            // rotated (logical) picture into its own buffers and every update
+            // is rotated into the panel's frame buffers by the PPA
+            int rotation;
+            uint8_t bpp;
+            uint32_t lvgl_width;
+            uint32_t lvgl_height;
+            uint8_t *panel_fbs[2];
+            uint8_t back_fb_index;
+            uint32_t fb_size_aligned;
+        #if SOC_PPA_SUPPORTED
+            ppa_client_handle_t ppa_client;
+        #endif
+
         } mp_lcd_dsi_bus_obj_t;
 
         extern const mp_obj_type_t mp_lcd_dsi_bus_type;

ext_mod/lcd_bus/esp32_src/dsi_bus.c

@@ -38,6 +38,12 @@
     #include "hal/lcd_types.h"
     #include "esp_lcd_mipi_dsi.h"
     #include "esp_ldo_regulator.h"
+    #include "hal/cache_hal.h"
+    #include "hal/cache_ll.h"
+
+    #if SOC_PPA_SUPPORTED
+        #include "driver/ppa.h"
+    #endif
 
 
     // Prefix of ESP-IDF's private esp_lcd_dpi_panel_t (esp_lcd/dsi/esp_lcd_panel_dpi.c),
@@ -71,6 +77,14 @@
     }
 
 
+    // frame buffers (and the PPA's output) have to be cache-line aligned
+    static uint32_t dsi_cache_line_size(void)
+    {
+        uint32_t line = cache_hal_get_cache_line_size(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_DATA);
+        return line ? line : 64;
+    }
+
+
     // Runs from the DPI panel's end-of-frame interrupt: the DMA has just
     // restarted its scan-out from fbs[cur_fb_index]. Once that is the buffer
     // LVGL last flushed, the other buffer is free to be drawn into.
@@ -107,7 +121,8 @@
             ARG_vsync_pulse_width,
             ARG_dpi_clock_freq,
             ARG_phy_ldo_channel,
-            ARG_phy_ldo_voltage_mv
+            ARG_phy_ldo_voltage_mv,
+            ARG_rotation
         };
 
         const mp_arg_t make_new_args[] = {
@@ -123,7 +138,8 @@
             { MP_QSTR_vsync_pulse_width,  MP_ARG_INT  | MP_ARG_KW_ONLY, { .u_int = 1       } },
             { MP_QSTR_dpi_clock_freq,     MP_ARG_INT  | MP_ARG_KW_ONLY, { .u_int = 0       } },  // DPI pixel clock, MHz; 0 = same number as freq
             { MP_QSTR_phy_ldo_channel,    MP_ARG_INT  | MP_ARG_KW_ONLY, { .u_int = -1      } },  // internal LDO channel powering the DSI PHY (ESP32-P4 boards: 3), -1 = not managed here
-            { MP_QSTR_phy_ldo_voltage_mv, MP_ARG_INT  | MP_ARG_KW_ONLY, { .u_int = 2500    } }
+            { MP_QSTR_phy_ldo_voltage_mv, MP_ARG_INT  | MP_ARG_KW_ONLY, { .u_int = 2500    } },
+            { MP_QSTR_rotation,           MP_ARG_INT  | MP_ARG_KW_ONLY, { .u_int = 0       } }   // 0/90/180/270 degrees (LVGL's sense); the PPA rotates every frame into the panel
         };
 
         mp_arg_val_t args[MP_ARRAY_SIZE(make_new_args)];
@@ -166,6 +182,18 @@
         self->phy_ldo_channel = (int)args[ARG_phy_ldo_channel].u_int;
         self->phy_ldo_voltage_mv = (int)args[ARG_phy_ldo_voltage_mv].u_int;
 
+        self->rotation = (int)args[ARG_rotation].u_int;
+        if (self->rotation != 0 && self->rotation != 90 && self->rotation != 180 && self->rotation != 270) {
+            mp_raise_msg_varg(&mp_type_ValueError, MP_ERROR_TEXT("rotation must be 0, 90, 180 or 270 (%d)"), self->rotation);
+            return mp_const_none;
+        }
+        #if !SOC_PPA_SUPPORTED
+        if (self->rotation != 0) {
+            mp_raise_msg(&mp_type_ValueError, MP_ERROR_TEXT("rotation needs a PPA (pixel processing accelerator), this chip has none"));
+            return mp_const_none;
+        }
+        #endif
+
         LCD_DEBUG_PRINT("bus_id=%d\n", self->bus_config.bus_id)
         LCD_DEBUG_PRINT("num_data_lanes=%d\n", self->bus_config.num_data_lanes)
         LCD_DEBUG_PRINT("lane_bit_rate_mbps=%d\n",self->bus_config.lane_bit_rate_mbps)
@@ -178,6 +206,7 @@
         LCD_DEBUG_PRINT("vsync_back_porch=%d\n", self->panel_config.video_timing.vsync_back_porch)
         LCD_DEBUG_PRINT("vsync_pulse_width=%d\n", self->panel_config.video_timing.vsync_pulse_width)
         LCD_DEBUG_PRINT("phy_ldo_channel=%d\n", self->phy_ldo_channel)
+        LCD_DEBUG_PRINT("rotation=%d\n", self->rotation)
 
         self->panel_io_handle.get_lane_count = &dsi_get_lane_count;
         self->panel_io_handle.del = &dsi_del;
@@ -234,6 +263,25 @@
 
         // LVGL renders in the frame buffers' own byte order; nothing here to swap.
         self->rgb565_byte_swap = false;
+        self->bpp = bpp;
+
+        if (self->rotation == 90 || self->rotation == 270) {
+            self->lvgl_width = (uint32_t)height;
+            self->lvgl_height = (uint32_t)width;
+        } else {
+            self->lvgl_width = (uint32_t)width;
+            self->lvgl_height = (uint32_t)height;
+        }
+
+        if (self->rotation != 0) {
+            if (bpp == 18) {
+                mp_raise_msg(&mp_type_ValueError, MP_ERROR_TEXT("rotation works with 16 and 24 bits per pixel, not 18"));
+                return LCD_ERR_INVALID_ARG;
+            }
+            // the rotated frame goes into the panel's back buffer while the
+            // front one is scanned out, whatever LVGL's own buffering is
+            self->panel_config.num_fbs = 2;
+        }
 
         self->panel_config.video_timing.h_size = (uint32_t)width;
         self->panel_config.video_timing.v_size = (uint32_t)height;
@@ -302,21 +350,45 @@
             return ret;
         }
 
-        // Point the buffers handed out by allocate_framebuffer() at the DPI
-        // panel's frame buffers and drop the interim allocations.
         dpi_panel_t *dpi_panel = __containerof((esp_lcd_panel_t *)self->panel_handle, dpi_panel_t, base);
+        self->panel_fbs[0] = dpi_panel->fbs[0];
+        self->panel_fbs[1] = self->panel_config.num_fbs == 2 ? dpi_panel->fbs[1] : NULL;
+
+        if (self->rotation == 0) {
+            // Point the buffers handed out by allocate_framebuffer() at the DPI
+            // panel's frame buffers and drop the interim allocations: LVGL
+            // renders straight into what the panel scans out.
+            heap_caps_free(self->view1->items);
+            self->view1->items = (void *)self->panel_fbs[0];
+            self->view1->len = self->buffer_size;
+
+            if (self->view2 != NULL) {
+                heap_caps_free(self->view2->items);
+                self->view2->items = (void *)self->panel_fbs[1];
+                self->view2->len = self->buffer_size;
+            }
+        } else {
+            #if SOC_PPA_SUPPORTED
+            // LVGL keeps its own (logical, rotated) buffers; each finished
+            // update is rotated into the panel's back buffer by the PPA.
+            ppa_client_config_t ppa_cfg = {
+                .oper_type = PPA_OPERATION_SRM,
+                .max_pending_trans_num = 1,
+            };
+            ret = ppa_register_client(&ppa_cfg, &self->ppa_client);
 
-        heap_caps_free(self->view1->items);
-        self->view1->items = (void *)dpi_panel->fbs[0];
-        self->view1->len = self->buffer_size;
+            if (ret != 0) {
+                mp_raise_msg_varg(&mp_type_ValueError, MP_ERROR_TEXT("%d(ppa_register_client)"), ret);
+                return ret;
+            }
 
-        if (self->view2 != NULL) {
-            heap_caps_free(self->view2->items);
-            self->view2->items = (void *)dpi_panel->fbs[1];
-            self->view2->len = self->buffer_size;
+            uint32_t line = dsi_cache_line_size();
+            self->fb_size_aligned = (full_frame_size + line - 1) / line * line;
+            self->back_fb_index = 1;
+            #endif
         }
 
-        LCD_DEBUG_PRINT("fb1=%p fb2=%p\n", self->view1->items, self->view2 != NULL ? self->view2->items : NULL)
+        LCD_DEBUG_PRINT("fb1=%p fb2=%p rotation=%d\n", self->view1->items, self->view2 != NULL ? self->view2->items : NULL, self->rotation)
 
         return LCD_OK;
     }
@@ -337,20 +409,35 @@
             }
             self->panel_handle = NULL;
             self->panel_started = false;
+            self->panel_fbs[0] = NULL;
+            self->panel_fbs[1] = NULL;
 
-            // the frame buffers went with the panel
+            // unrotated: the frame buffers went with the panel; rotated: they are ours
             if (self->view1 != NULL) {
+                if (self->rotation != 0) {
+                    heap_caps_free(self->view1->items);
+                }
                 self->view1->items = NULL;
                 self->view1->len = 0;
                 self->view1 = NULL;
             }
             if (self->view2 != NULL) {
+                if (self->rotation != 0) {
+                    heap_caps_free(self->view2->items);
+                }
                 self->view2->items = NULL;
                 self->view2->len = 0;
                 self->view2 = NULL;
             }
         }
 
+        #if SOC_PPA_SUPPORTED
+        if (self->ppa_client != NULL) {
+            ppa_unregister_client(self->ppa_client);
+            self->ppa_client = NULL;
+        }
+        #endif
+
         if (self->panel_io_handle.panel_io != NULL) {
             ret = esp_lcd_panel_io_del(self->panel_io_handle.panel_io);
             if (ret != 0) {
@@ -450,7 +537,7 @@
         // A real buffer for now, so the memoryview is always valid; once the
         // bus is initialized it is repointed at the frame buffer the DPI panel
         // driver allocated itself and this one is freed again (dsi_init).
-        void *buf = heap_caps_calloc(1, size, caps);
+        void *buf = heap_caps_aligned_calloc(dsi_cache_line_size(), 1, size, caps);
 
         if (buf == NULL) {
             mp_raise_msg_varg(&mp_type_MemoryError, MP_ERROR_TEXT("Not enough memory available (%lu)"), size);
@@ -502,6 +589,90 @@
             self->panel_started = true;
         }
 
+        #if SOC_PPA_SUPPORTED
+        if (self->rotation != 0) {
+            if (!last_update) {
+                // more areas of this update follow; LVGL's buffer is complete
+                // only after the last one, nothing to rotate yet
+                self->trans_done = true;
+
+                if (self->callback != mp_const_none && mp_obj_is_callable(self->callback)) {
+                    mp_call_function_n_kw(self->callback, 0, 0, NULL);
+                }
+                return LCD_OK;
+            }
+
+            // LVGL's buffer (the one this area lives in) holds the whole
+            // logical picture: rotate all of it into the panel's back buffer.
+            const uint8_t *base = NULL;
+            if (self->view1 != NULL && dsi_buf_in_fb(self, (const uint8_t *)self->view1->items, color)) {
+                base = (const uint8_t *)self->view1->items;
+            } else if (self->view2 != NULL && dsi_buf_in_fb(self, (const uint8_t *)self->view2->items, color)) {
+                base = (const uint8_t *)self->view2->items;
+            } else {
+                mp_raise_msg(&mp_type_ValueError, MP_ERROR_TEXT("flushed buffer is not a DSIBus frame buffer"));
+                return LCD_ERR_INVALID_ARG;
+            }
+
+            uint8_t *dst = self->panel_fbs[self->back_fb_index];
+            ppa_srm_color_mode_t cm = self->bpp == 16 ? PPA_SRM_COLOR_MODE_RGB565 : PPA_SRM_COLOR_MODE_RGB888;
+
+            ppa_srm_oper_config_t op = { 0 };
+            op.in.buffer = base;
+            op.in.pic_w = self->lvgl_width;
+            op.in.pic_h = self->lvgl_height;
+            op.in.block_w = self->lvgl_width;
+            op.in.block_h = self->lvgl_height;
+            op.in.block_offset_x = 0;
+            op.in.block_offset_y = 0;
+            op.in.srm_cm = cm;
+            op.out.buffer = dst;
+            op.out.buffer_size = self->fb_size_aligned;
+            op.out.pic_w = self->panel_config.video_timing.h_size;
+            op.out.pic_h = self->panel_config.video_timing.v_size;
+            op.out.block_offset_x = 0;
+            op.out.block_offset_y = 0;
+            op.out.srm_cm = cm;
+            // LVGL's rotation and the PPA's are both counter-clockwise
+            op.rotation_angle = self->rotation == 90 ? PPA_SRM_ROTATION_ANGLE_90 :
+                                self->rotation == 180 ? PPA_SRM_ROTATION_ANGLE_180 :
+                                PPA_SRM_ROTATION_ANGLE_270;
+            op.scale_x = 1.0f;
+            op.scale_y = 1.0f;
+            op.mode = PPA_TRANS_MODE_BLOCKING;
+
+            ret = ppa_do_scale_rotate_mirror(self->ppa_client, &op);
+
+            if (ret != 0) {
+                mp_raise_msg_varg(&mp_type_ValueError, MP_ERROR_TEXT("%d(ppa_do_scale_rotate_mirror)"), ret);
+                return ret;
+            }
+
+            self->trans_done = false;
+            self->transmitting_buf = NULL;
+
+            // whole-buffer "draw": cache write-back plus the swap to this buffer
+            // at the next frame boundary; the refresh-done interrupt reports it
+            ret = esp_lcd_panel_draw_bitmap(
+                self->panel_handle,
+                0,
+                0,
+                (int)self->panel_config.video_timing.h_size,
+                (int)self->panel_config.video_timing.v_size,
+                dst
+            );
+
+            if (ret != 0) {
+                mp_raise_msg_varg(&mp_type_ValueError, MP_ERROR_TEXT("%d(esp_lcd_panel_draw_bitmap)"), ret);
+                return ret;
+            }
+
+            self->transmitting_buf = dst;
+            self->back_fb_index ^= 1;
+            return LCD_OK;
+        }
+        #endif
+
         self->trans_done = false;
         self->transmitting_buf = NULL;
 

ext_mod/lcd_bus/micropython.cmake

@@ -32,6 +32,17 @@ if(ESP_PLATFORM)
         list(APPEND LCD_INCLUDES ${ESP_LCD_INCLUDES})
     endif()
 
+    # the DSI bus rotates with the PPA where the chip has one (ESP32-P4)
+    if(CONFIG_SOC_PPA_SUPPORTED)
+        idf_component_get_property(ESP_PPA_INCLUDES esp_driver_ppa INCLUDE_DIRS)
+        idf_component_get_property(ESP_PPA_DIR esp_driver_ppa COMPONENT_DIR)
+
+        if(ESP_PPA_INCLUDES)
+            list(TRANSFORM ESP_PPA_INCLUDES PREPEND ${ESP_PPA_DIR}/)
+            list(APPEND LCD_INCLUDES ${ESP_PPA_INCLUDES})
+        endif()
+    endif()
+
 else()
     set(LCD_INCLUDES
         ${CMAKE_CURRENT_LIST_DIR}