trans_size field in lvgl_port_display_cfg_t is unused in LVGL9 — PSRAM framebuffers fail on SPI panels (BSP-783)

[orioncode-eu]

Board

Waveshare Development Board With 3.49inch IPS

Hardware Description

ESP32-S3 High-Performance Development Board With 3.49inch IPS Capacitive Touch Display, 172 × 640 Resolution, Integrated With ESP32-S3R8 Dual-core Processor
ESP32-S3 with QSPI LCD panel (AXS15231B 172×640), 8MB PSRAM

IDE Name

VSCode, esp_lvgl_port 2.7.1, LVGL 9.4.0, ESP-IDF 5.5.2

Operating System

Windows 10

Description

The lvgl_port_display_cfg_t struct exposes a trans_size field:
uint32_t trans_size; /*!< Allocated buffer will be in SRAM to move framebuf (optional) */
In the LVGL8 version (esp_lvgl_port_disp.c), this field is used to:

1. Allocate a DMA-capable SRAM buffer (trans_buf) via heap_caps_malloc(..., MALLOC_CAP_DMA)
2. In the flush callback, copy framebuffer data from PSRAM to trans_buf in chunks, calling draw_bitmap per chunk with semaphore synchronization between transfers

In the LVGL9 version (esp_lvgl_port_disp.c), this field is completely ignored. The lvgl_port_display_ctx_t struct does not contain trans_buf or trans_size. The flush callback passes the entire PSRAM buffer directly to esp_lcd_panel_draw_bitmap() in a single call.

Impact:
For SPI-connected panels with full-screen PSRAM buffers (e.g., 172×640×2 = 220KB for full_refresh mode), the single draw_bitmap call attempts a 220KB SPI DMA transfer from PSRAM, which fails:
panel_io_spi_tx_color(395): spi transmit (queue) color failed

LVGL then hangs in wait_for_flushing and the watchdog triggers every 5 seconds.

Users setting trans_size to enable chunking get no error, no warning — the code compiles and runs, but trans_size has no effect whatsoever.

Workaround:
A panel wrapper that intercepts draw_bitmap, copies chunks from PSRAM to a small DMA-capable SRAM buffer via memcpy, and calls the real panel's draw_bitmap per chunk. The wrapper also manually calls lv_disp_flush_ready() after the last chunk and disables the auto-registered on_color_trans_done callback.

Expected behavior:
Either:

1. Implement trans_size chunking in the LVGL9 flush callback (port the LVGL8 logic), or
2. Remove the trans_size field from the config struct and document that PSRAM framebuffers require a custom panel wrapper for SPI panels, or
3. Emit a warning at runtime when trans_size > 0 and LVGL9 is used, so users know it's not implemented
   Option 1 would be ideal — the LVGL8 implementation already works and the pattern is straightforward.

Sketch

.

Other Steps to Reproduce

No response

I have checked existing issues, README.md and ESP32 Forum

• I confirm I have checked existing issues, online documentation and Troubleshooting guide.

[github-actions]

Hi @orioncode-eu! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

You’re correct that trans_size is documented and present in lvgl_port_display_cfg_t, and that it is used in the LVGL8 implementation to support a PSRAM framebuffer + small DMA-capable SRAM “transfer buffer” pattern. [esp_lvgl_port usage][usb_extend_screen readme]

In the LVGL8-based code, the intended usage is exactly what you described:

const lvgl_port_display_cfg_t disp_cfg = {
    ...
    .buffer_size = DISP_WIDTH * DISP_HEIGHT, // in PSRAM, not DMA-capable
    .trans_size = size,                      // in SRAM, DMA-capable
    .flags = {
        .buff_spiram = true,
        .buff_dma = false,
        ...
    }
};

This is also the pattern recommended in the FAQ for ESP32‑S3 when internal RAM is insufficient: use PSRAM as framebuffer and a small SRAM buffer to transfer in batches, because SPI DMA cannot directly transfer from PSRAM. [LCD FAQ][SPI/QSPI note]

However, in the LVGL9 implementation of esp_lvgl_port:

• The provided knowledge sources do not show any LVGL9-specific esp_lvgl_port_disp.c implementation.
• They only show:
  • The changelog for esp_lvgl_port (which mentions LVGL9 support but does not mention trans_size). [esp_lvgl_port changelog][bsp changelog]
  • The LVGL8-style “Using PSRAM canvas” example that relies on trans_size. [esp_lvgl_port usage][esp_lvgl_port readme]

From these documents alone, I cannot confirm how trans_size is handled internally in the LVGL9 code path, nor see any explicit note that it is ignored. The behavior you describe (single esp_lcd_panel_draw_bitmap() from PSRAM, SPI DMA failure, and LVGL hang) is consistent with the known limitation that SPI DMA cannot directly send PSRAM data and will fall back to allocating a large temporary SRAM buffer, which can fail for full-screen transfers. [SPI LCD intro][SPI/QSPI note]

Given the limitations of the available documentation:

• I cannot verify from these sources whether the LVGL9 esp_lvgl_port implementation is intended to support trans_size and simply has a bug, or whether support was dropped but the field and docs were not updated.
• I also cannot see any documented runtime warning or deprecation note for trans_size in LVGL9.

What is clearly documented:

1. PSRAM + SPI DMA constraint

   • SPI driver cannot directly DMA from PSRAM; it will allocate temporary DMA-capable SRAM buffers and copy from PSRAM, which can fail or exhaust SRAM for large transfers (e.g., full-screen RGB565 frame). [SPI LCD intro][SPI/QSPI note]

2. Recommended pattern for PSRAM framebuffers

   • Use PSRAM as framebuffer and a small SRAM buffer to transfer in multiple batches; this is exactly what trans_size + buff_spiram + buff_dma=false were designed to support in LVGL8. [LCD FAQ][esp_lvgl_port usage]

3. Your workaround (panel wrapper) matches the documented approach

   • Copying from PSRAM to a small DMA-capable SRAM buffer in chunks and calling esp_lcd_panel_draw_bitmap() per chunk is aligned with the recommended “PSRAM canvas + small trans buffer” design. [LCD FAQ]

Given this, the only safe, documentation-backed guidance I can provide for the GitHub issue is:

1. Acknowledge the problem

   • The public docs still show trans_size as the way to implement a PSRAM framebuffer + SRAM transfer buffer, but the user’s observation is that in LVGL9 this field has no effect and full-screen PSRAM buffers on SPI panels fail with large DMA transfers.
   • The available documentation does not clarify LVGL9 behavior of trans_size, nor does it document any deprecation or change in semantics.

2. Recommend a supported workaround

   • Until the LVGL9 esp_lvgl_port implementation is updated or clarified, users of SPI/QSPI panels with PSRAM framebuffers should:
     • Keep the framebuffer in PSRAM.
     • Use a small DMA-capable SRAM buffer.
     • Manually chunk transfers from PSRAM to SRAM and call esp_lcd_panel_draw_bitmap() per chunk, as you are already doing in your wrapper. [LCD FAQ][SPI/QSPI note]

3. Next steps (for maintainers)

   Based on the documentation and your report, the following actions on the component side would be reasonable:

   • Revisit the LVGL9 esp_lvgl_port display implementation to:
     • Either reintroduce trans_size-based chunking for PSRAM framebuffers on SPI/QSPI panels (mirroring the LVGL8 logic), or
     • Explicitly deprecate/remove trans_size for LVGL9 and update the README/FAQ to state that SPI PSRAM framebuffers require a custom panel/wrapper.
   • If trans_size remains unused in LVGL9, add a runtime warning when trans_size > 0 is configured, so users are not misled by the existing documentation.

Because the internal LVGL9 implementation is not included in the provided knowledge sources, I cannot supply a patch or confirm the exact cause in code; I can only confirm that your use case and workaround are consistent with Espressif’s documented SPI+PSRAM constraints and the original trans_size design.