From e5760b35a5c107654884dac31f7fad3ac1addf16 Mon Sep 17 00:00:00 2001 From: Peter Dragun Date: Thu, 4 Apr 2024 11:07:49 +0200 Subject: [PATCH 1/3] docs(tools/coredump): add information about standalone tool for advanced users Closes https://github.com/espressif/esp-idf/issues/13433 --- .gitlab/CODEOWNERS | 1 + docs/en/api-guides/core_dump.rst | 13 +++++++++++++ 2 files changed, 14 insertions(+) diff --git a/.gitlab/CODEOWNERS b/.gitlab/CODEOWNERS index 9ae29cd8f2..7c8a7dd05b 100644 --- a/.gitlab/CODEOWNERS +++ b/.gitlab/CODEOWNERS @@ -153,6 +153,7 @@ /docs/ @esp-idf-codeowners/docs /docs/**/api-guides/tools/ @esp-idf-codeowners/tools +/docs/en/api-guides/core_dump.rst @esp-idf-codeowners/debugging /docs/en/api-guides/jtag-debugging/ @esp-idf-codeowners/debugging /docs/**/api-reference/bluetooth/ @esp-idf-codeowners/bluetooth /docs/**/api-reference/network/ @esp-idf-codeowners/network @esp-idf-codeowners/wifi diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index d163a33f9c..e8867f5604 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -98,6 +98,11 @@ or idf.py coredump-debug +.. note:: + + The ``idf.py coredump-info`` and ``idf.py coredump-debug`` commands are wrappers around the `esp-coredump` tool for easier use in the ESP-IDF environment. For more information see :ref:`core_dump_commands` section. + + Core Dump to UART ----------------- @@ -184,6 +189,8 @@ or idf.py coredump-debug -c +.. _core_dump_commands: + Core Dump Commands ------------------ @@ -192,6 +199,12 @@ ESP-IDF provides special commands to help to retrieve and analyze core dumps: * ``idf.py coredump-info`` - prints crashed task's registers, call stack, list of available tasks in the system, memory regions, and contents of memory stored in core dump (TCBs and stacks). * ``idf.py coredump-debug`` - creates core dump ELF file and runs GDB debug session with this file. You can examine memory, variables, and task states manually. Note that since not all memory is saved in the core dump, only the values of variables allocated on the stack are meaningful. +For advanced users who want to pass additional arguments or use custom ELF files, it is possible to use the `esp-coredump `_ tool directly. For more information, use in ESP-IDF environment: + +.. code-block:: bash + + esp-coredump --help + ROM Functions in Backtraces --------------------------- From 1830f589206f7752da25c2a1c56b0a118e619fc7 Mon Sep 17 00:00:00 2001 From: Peter Dragun Date: Thu, 4 Apr 2024 13:38:24 +0200 Subject: [PATCH 2/3] docs(tools/coredump): add warning about core dump usage with encrypted parttion Closes https://github.com/espressif/esp-coredump/issues/8 --- docs/en/api-guides/core_dump.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index e8867f5604..c544ab9827 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -77,7 +77,8 @@ The core dump partition is automatically declared when using the default partiti .. important:: - If :doc:`../security/flash-encryption` is enabled on the device, please add an ``encrypted`` flag to the core dump partition declaration. + If :doc:`../security/flash-encryption` is enabled on the device, please add an ``encrypted`` flag to the core dump partition declaration. Please note that the core dump cannot be read from encrypted partitions using ``idf.py coredump-info`` or ``idf.py coredump-debug`` commands. + It is recommended to read the core dump from ESP which will automatically decrypt the partition and send it for analysis, which can be done by running e.g. ``idf.py coredump-info -c ``. .. code-block:: none From c86952ed9d910903dfdd440421e9d902785b036f Mon Sep 17 00:00:00 2001 From: Wang Fang Date: Thu, 11 Apr 2024 14:12:55 +0800 Subject: [PATCH 3/3] docs: Updated CN translation for coredump --- docs/zh_CN/api-guides/core_dump.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/zh_CN/api-guides/core_dump.rst b/docs/zh_CN/api-guides/core_dump.rst index 335fee835c..83e4e8af77 100644 --- a/docs/zh_CN/api-guides/core_dump.rst +++ b/docs/zh_CN/api-guides/core_dump.rst @@ -77,7 +77,8 @@ ELF 格式具备扩展特性，支持在发生崩溃时保存更多关于错误 .. important:: - 如果设备启用了 :doc:`../security/flash-encryption`，请在核心转储分区中添加 ``encrypted`` 标志。 + 如果设备启用了 :doc:`../security/flash-encryption`，请在核心转储分区中添加 ``encrypted`` 标志。请注意，使用 ``idf.py coredump-info`` 或 ``idf.py coredump-debug`` 命令无法从加密分区读取核心转储。 + 建议使用 ``idf.py coredump-info -c `` 命令从 ESP 设备侧读取核心转储，ESP 设备会自动解密分区并发送到相应位置用于分析。 .. code-block:: none @@ -98,6 +99,11 @@ ELF 格式具备扩展特性，支持在发生崩溃时保存更多关于错误 idf.py coredump-debug +.. note:: + + ``idf.py coredump-info`` 命令和 ``idf.py coredump-debug`` 命令对 `esp-coredump` 工具进行了封装，可以在 ESP-IDF 环境中轻松使用。更多信息，请参考 :ref:`core_dump_commands`。 + + 将核心转储保存到 UART ----------------------- @@ -184,6 +190,8 @@ ELF 格式具备扩展特性，支持在发生崩溃时保存更多关于错误 idf.py coredump-debug -c +.. _core_dump_commands: + 核心转储命令 ------------------ @@ -192,6 +200,12 @@ ESP-IDF 提供了一些特殊命令，有助于检索和分析核心转储： * ``idf.py coredump-info`` - 打印崩溃任务的寄存器、调用栈、系统可用任务列表、内存区域以及核心转储中存储的内存内容（包括 TCB 和栈）。 * ``idf.py coredump-debug`` - 创建核心转储 ELF 文件，并使用该文件运行 GDB 调试会话。你可以手动检查内存、变量和任务状态。请注意，由于并未将所有内存保存在核心转储中，因此只有在栈上分配的变量的值才有意义。 +高阶用户如果需要传递额外参数或使用自定义 ELF 文件，可直接使用 `esp-coredump `_ 工具。如果在 ESP-IDF 环境中使用该工具，可运行如下命令查询更多信息： + +.. code-block:: bash + + esp-coredump --help + 回溯中的 ROM 函数 ---------------------------