From eb429c95d41708d9aef95ceef2409368357e898d Mon Sep 17 00:00:00 2001
From: Chen Jichang <chenjichang@espressif.com>
Date: Fri, 15 May 2026 15:27:16 +0800
Subject: [PATCH] feat(idf_drivers_gdb): provide a gdb extension to dump buffer

---
 docs/en/api-reference/peripherals/lcd/index.rst    | 9 +++++++++
 docs/zh_CN/api-reference/peripherals/lcd/index.rst | 9 +++++++++
 tools/cmake/gdbinit.cmake                          | 7 ++++++-
 tools/requirements/requirements.core.txt           | 1 +
 4 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/en/api-reference/peripherals/lcd/index.rst b/docs/en/api-reference/peripherals/lcd/index.rst
index dbf7b5e2688..f5703c163de 100644
--- a/docs/en/api-reference/peripherals/lcd/index.rst
+++ b/docs/en/api-reference/peripherals/lcd/index.rst
@@ -55,6 +55,15 @@ LCD Data Panel Operations
 * :cpp:func:`esp_lcd_panel_draw_bitmap` is the function which does the magic to flush the user draw buffer to the LCD screen, where the target draw window is configurable. Please note, this function expects that the draw buffer is a 1-D array and there's no stride in between each lines.
 * :cpp:func:`esp_lcd_panel_draw_bitmap_2d` is the function which does the magic to flush the user draw buffer to the LCD screen, where the source and target draw windows are configurable. Please note, the draw buffer can be a 2-D array or a 1-D array with no stride in between each lines.
 
+Advanced Frame Buffer Debugging
+-------------------------------
+
+For advanced debugging, ESP-IDF can load the ``idf-drivers-gdb`` Python package in a GDB session. This package provides the ``framebuffer_display`` command, which reads LCD frame buffer memory from the target and renders it on the host side.
+
+This is useful when the panel does not show the expected image and you need to check whether the frame buffer content is already wrong, or whether the problem is in the LCD interface timing, GPIO routing, panel initialization, or color format configuration.
+
+For installation steps, supported pixel formats, command syntax, examples, and troubleshooting tips, see the `idf-drivers-gdb package documentation <https://pypi.org/project/idf-drivers-gdb/>`__.
+
 .. _steps_add_manufacture_init:
 
 Steps to Add Manufacturer Specific Initialization
diff --git a/docs/zh_CN/api-reference/peripherals/lcd/index.rst b/docs/zh_CN/api-reference/peripherals/lcd/index.rst
index fd154b80109..8120d42570d 100644
--- a/docs/zh_CN/api-reference/peripherals/lcd/index.rst
+++ b/docs/zh_CN/api-reference/peripherals/lcd/index.rst
@@ -55,6 +55,15 @@ LCD 数据面板操作
 * :cpp:func:`esp_lcd_panel_draw_bitmap` 可以将绘制 buffer 刷新到 LCD 屏幕上，其中目标绘制窗口是可配置的。请注意，使用该函数需要确保绘制 buffer 是一维数组，且每行像素数据之间没有跨距。
 * :cpp:func:`esp_lcd_panel_draw_bitmap_2d` 可以绘制部分位图到 LCD 屏幕上，源窗口和目标绘制窗口都是可配置的。请注意，此时绘制 buffer 可以是二维数组，也可以是每行像素数据之间没有跨距的一维数组。
 
+高级帧 Buffer 调试
+------------------
+
+对于高级调试场景，ESP-IDF 可以在 GDB 会话中加载 ``idf-drivers-gdb`` Python 包。该包提供 ``framebuffer_display`` 命令，可以从目标芯片读取 LCD 帧 buffer 内存，并在主机侧渲染。
+
+当屏幕显示不符合预期时，该命令可用于判断帧 buffer 内容本身是否已经异常，或者问题是否更可能来自 LCD 接口时序、GPIO 路由、面板初始化或颜色格式配置。
+
+有关安装方式、支持的像素格式、命令语法、示例和排障建议，请参阅 `idf-drivers-gdb 包文档 <https://pypi.org/project/idf-drivers-gdb/>`__。
+
 .. _steps_add_manufacture_init:
 
 添加特定制造商的初始化设置
diff --git a/tools/cmake/gdbinit.cmake b/tools/cmake/gdbinit.cmake
index 1aed4dbbbd3..ceda997694f 100644
--- a/tools/cmake/gdbinit.cmake
+++ b/tools/cmake/gdbinit.cmake
@@ -22,10 +22,15 @@ function(__generate_gdbinit)
     set(gdbinit_py_extensions
         "# Add Python GDB extensions\n"
         "python\n"
+        "import sys\n"
         "try:\n"
         "    import freertos_gdb\n"
         "except ModuleNotFoundError:\n"
-        "    print('warning: python extension \"freertos_gdb\" not found.')\n"
+        "    print('warning: python extension \"freertos_gdb\" not found.', file=sys.stderr)\n"
+        "try:\n"
+        "    import idf_drivers_gdb\n"
+        "except ModuleNotFoundError:\n"
+        "    print('warning: python extension \"idf_drivers_gdb\" not found.', file=sys.stderr)\n"
         "end\n")
 
     # Define paths
diff --git a/tools/requirements/requirements.core.txt b/tools/requirements/requirements.core.txt
index 1586433c564..aef6c3e9a7e 100644
--- a/tools/requirements/requirements.core.txt
+++ b/tools/requirements/requirements.core.txt
@@ -32,3 +32,4 @@ tree_sitter_c
 
 # gdb extensions dependencies
 freertos_gdb
+idf_drivers_gdb