Skip to content

Commit

Permalink
Documentation: Document stack and backtrace dump for Espressif SoCs
Browse files Browse the repository at this point in the history 
Stack and backtrace dump for Espressif's SoCs (ESP32, ESP32-S2,
ESP32-S3, ESP32-C3, ESP32-C6 and ESP32-H2) is now documented in a
new section for each chip entry page.
  • Loading branch information
@tmedicci
tmedicci committed Sep 19, 2024
1 parent 5fa9dee commit a7a4aae
Show file tree
Hide file tree
Showing 6 changed files with 646 additions and 6 deletions.
90 changes: 89 additions & 1 deletion Documentation/platforms/risc-v/esp32c3/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -120,8 +120,13 @@ Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``./`` is
the path to the folder containing the externally-built 2nd stage bootloader for
the ESP32-C3 as explained above.

Debugging
=========

This section describes debugging techniques for the ESP32-C3.

Debugging with ``openocd`` and ``gdb``
======================================
--------------------------------------

Espressif uses a specific version of OpenOCD to support ESP32-C3: `openocd-esp32 <https://github.com/espressif/>`_.

Expand Down Expand Up @@ -189,6 +194,89 @@ whereas the content of the ``gdbinit`` file is::

Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.

Stack Dump and Backtrace Dump
-----------------------------

NuttX has a feature to dump the stack of a task and to dump the backtrace of it (and of all
the other tasks). This feature is useful to debug the system when it is not behaving as expected,
especially when it is crashing.

In order to enable this feature, the following options must be enabled in the NuttX configuration:
``CONFIG_SCHED_BACKTRACE``, ``CONFIG_DEBUG_SYMBOLS`` and, optionally, ``CONFIG_ALLSYMS``.

.. note::
The first two options enable the backtrace dump. The third option enables the backtrace dump
with the associated symbols, but increases the size of the generated NuttX binary.

Espressif also provides a tool to translate the backtrace dump into a human-readable format.
This tool is called ``btdecode.sh`` and is available at ``tools/espressif/btdecode.sh`` of NuttX
repository.

.. note::
This tool is not necessary if ``CONFIG_ALLSYMS`` is enabled. In this case, the backtrace dump
contains the function names.

Example - Crash Dump
^^^^^^^^^^^^^^^^^^^^

A typical crash dump, caused by an illegal load with ``CONFIG_SCHED_BACKTRACE`` and
``CONFIG_DEBUG_SYMBOLS`` enabled, is shown below::

riscv_exception: EXCEPTION: Store/AMO access fault. MCAUSE: 00000007, EPC: 42012df2, MT0
riscv_exception: PANIC!!! Exception = 00000007
_assert: Current Version: NuttX 10.4.0 2ae3246e40-dirty Sep 19 2024 14:34:41 risc-v
_assert: Assertion failed panic: at file: :0 task: backtrace process: backtrace 0x42012dac
up_dump_register: EPC: 42012df2
up_dump_register: A0: 0000005a A1: 3fc88a54 A2: 00000001 A3: 00000088
up_dump_register: A4: 00007fff A5: 00000001 A6: 00000000 A7: 00000000
up_dump_register: T0: 00000000 T1: 00000000 T2: ffffffff T3: 00000000
up_dump_register: T4: 00000000 T5: 00000000 T6: 00000000
up_dump_register: S0: 3fc87b16 S1: 3fc87b00 S2: 00000000 S3: 00000000
up_dump_register: S4: 00000000 S5: 00000000 S6: 00000000 S7: 00000000
up_dump_register: S8: 00000000 S9: 00000000 S10: 00000000 S11: 00000000
up_dump_register: SP: 3fc88ab0 FP: 3fc87b16 TP: 00000000 RA: 42012df2
dump_stack: User Stack:
dump_stack: base: 0x3fc87b20
dump_stack: size: 00004048
dump_stack: sp: 0x3fc88ab0
stack_dump: 0x3fc88a90: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00001800
stack_dump: 0x3fc88ab0: 00000000 3fc87718 42012dac 42006dd0 00000000 00000000 3fc87b00 00000002
stack_dump: 0x3fc88ad0: 00000000 00000000 00000000 42004d4c 00000000 00000000 00000000 00000000
stack_dump: 0x3fc88af0: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
sched_dumpstack: backtrace| 2: 0x42012df2
dump_tasks: PID GROUP PRI POLICY TYPE NPX STATE EVENT SIGMASK STACKBASE STACKSIZE COMMAND
dump_tasks: ---- --- --- -------- ------- --- ------- ---------- ---------------- 0x3fc845e0 1536 irq
dump_task: 0 0 0 FIFO Kthread - Ready 0000000000000000 0x3fc85d18 2032 Idle_Task
dump_task: 1 1 100 RR Task - Waiting Semaphore 0000000000000000 0x3fc86c30 2000 nsh_main
dump_task: 2 2 255 RR Task - Running 0000000000000000 0x3fc87b20 4048 backtrace task
sched_dumpstack: backtrace| 0: 0x42008420
sched_dumpstack: backtrace| 1: 0x420089a8
sched_dumpstack: backtrace| 2: 0x42012df2

The lines starting with ``sched_dumpstack`` show the backtrace of the tasks. By checking it, it is
possible to track the root cause of the crash. Saving this output to a file and using the ``btdecode.sh``::

./tools/espressif/btdecode.sh esp32c3 /tmp/backtrace.txt
Backtrace for task 2:
0x42012df2: assert_on_task at backtrace_main.c:158
(inlined by) backtrace_main at backtrace_main.c:194

Backtrace dump for all tasks:

Backtrace for task 2:
0x42012df2: assert_on_task at backtrace_main.c:158
(inlined by) backtrace_main at backtrace_main.c:194

Backtrace for task 1:
0x420089a8: sys_call2 at syscall.h:227
(inlined by) up_switch_context at riscv_switchcontext.c:95

Backtrace for task 0:
0x42008420: up_idle at esp_idle.c:74

The above output shows the backtrace of the tasks. By checking it, it is possible to track the
functions that were being executed when the crash occurred.

Peripheral Support
==================

Expand Down
87 changes: 86 additions & 1 deletion Documentation/platforms/risc-v/esp32c6/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,13 @@ Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``./`` is
the path to the folder containing the externally-built 2nd stage bootloader for
the ESP32-C6 as explained above.

Debugging
=========

This section describes debugging techniques for the ESP32-C6.

Debugging with ``openocd`` and ``gdb``
======================================
--------------------------------------

Espressif uses a specific version of OpenOCD to support ESP32-C6: `openocd-esp32 <https://github.com/espressif/>`_.

Expand Down Expand Up @@ -179,6 +184,86 @@ whereas the content of the ``gdbinit`` file is::

Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.

Stack Dump and Backtrace Dump
-----------------------------

NuttX has a feature to dump the stack of a task and to dump the backtrace of it (and of all
the other tasks). This feature is useful to debug the system when it is not behaving as expected,
especially when it is crashing.

In order to enable this feature, the following options must be enabled in the NuttX configuration:
``CONFIG_SCHED_BACKTRACE``, ``CONFIG_DEBUG_SYMBOLS`` and, optionally, ``CONFIG_ALLSYMS``.

.. note::
The first two options enable the backtrace dump. The third option enables the backtrace dump
with the associated symbols, but increases the size of the generated NuttX binary.

Espressif also provides a tool to translate the backtrace dump into a human-readable format.
This tool is called ``btdecode.sh`` and is available at ``tools/espressif/btdecode.sh`` of NuttX
repository.

.. note::
This tool is not necessary if ``CONFIG_ALLSYMS`` is enabled. In this case, the backtrace dump
contains the function names.

Example - Crash Dump
^^^^^^^^^^^^^^^^^^^^

A typical crash dump, caused by an illegal load with ``CONFIG_SCHED_BACKTRACE`` and
``CONFIG_DEBUG_SYMBOLS`` enabled, is shown below::

riscv_exception: EXCEPTION: Store/AMO access fault. MCAUSE: 00000007, EPC: 420168ac, MT0
riscv_exception: PANIC!!! Exception = 00000007
_assert: Current Version: NuttX 10.4.0 2ae3246e40-dirty Sep 19 2024 14:47:41 risc-v
_assert: Assertion failed panic: at file: :0 task: backtrace process: backtrace 0x42016866
up_dump_register: EPC: 420168ac
up_dump_register: A0: 0000005a A1: 40809fc4 A2: 00000001 A3: 00000088
up_dump_register: A4: 00007fff A5: 00000001 A6: 00000000 A7: 00000000
up_dump_register: T0: 00000000 T1: 00000000 T2: ffffffff T3: 00000000
up_dump_register: T4: 00000000 T5: 00000000 T6: 00000000
up_dump_register: S0: 4080908e S1: 40809078 S2: 00000000 S3: 00000000
up_dump_register: S4: 00000000 S5: 00000000 S6: 00000000 S7: 00000000
up_dump_register: S8: 00000000 S9: 00000000 S10: 00000000 S11: 00000000
up_dump_register: SP: 4080a020 FP: 4080908e TP: 00000000 RA: 420168ac
dump_stack: User Stack:
dump_stack: base: 0x40809098
dump_stack: size: 00004040
dump_stack: sp: 0x4080a020
stack_dump: 0x4080a000: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00001880
stack_dump: 0x4080a020: 00000000 40808c90 42016866 42006e06 00000000 00000000 40809078 00000002
stack_dump: 0x4080a040: 00000000 00000000 00000000 42004d72 00000000 00000000 00000000 00000000
stack_dump: 0x4080a060: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
sched_dumpstack: backtrace| 2: 0x420168ac
dump_tasks: PID GROUP PRI POLICY TYPE NPX STATE EVENT SIGMASK STACKBASE STACKSIZE COMMAND
dump_tasks: ---- --- --- -------- ------- --- ------- ---------- ---------------- 0x40805a90 2048 irq
dump_task: 0 0 0 FIFO Kthread - Ready 0000000000000000 0x40807290 2032 Idle_Task
dump_task: 1 1 100 RR Task - Waiting Semaphore 0000000000000000 0x408081a8 1992 nsh_main
dump_task: 2 2 255 RR Task - Running 0000000000000000 0x40809098 4040 backtrace task
sched_dumpstack: backtrace| 0: 0x42008420
sched_dumpstack: backtrace| 1: 0x420089a2
sched_dumpstack: backtrace| 2: 0x420168ac

The lines starting with ``sched_dumpstack`` show the backtrace of the tasks. By checking it, it is
possible to track the root cause of the crash. Saving this output to a file and using the ``btdecode.sh``::

./tools/espressif/btdecode.sh esp32c6 /tmp/backtrace.txt
Backtrace for task 2:
0x420168ac: assert_on_task at backtrace_main.c:158
(inlined by) backtrace_main at backtrace_main.c:194

Backtrace dump for all tasks:

Backtrace for task 2:
0x420168ac: assert_on_task at backtrace_main.c:158
(inlined by) backtrace_main at backtrace_main.c:194

Backtrace for task 1:
0x420089a2: sys_call2 at syscall.h:227
(inlined by) up_switch_context at riscv_switchcontext.c:95

Backtrace for task 0:
0x42008420: up_idle at esp_idle.c:74

Peripheral Support
==================

Expand Down
87 changes: 86 additions & 1 deletion Documentation/platforms/risc-v/esp32h2/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,13 @@ Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``./`` is
the path to the folder containing the externally-built 2nd stage bootloader for
the ESP32-H2 as explained above.

Debugging
=========

This section describes debugging techniques for the ESP32-H2.

Debugging with ``openocd`` and ``gdb``
======================================
--------------------------------------

Espressif uses a specific version of OpenOCD to support ESP32-H2: `openocd-esp32 <https://github.com/espressif/>`_.

Expand Down Expand Up @@ -179,6 +184,86 @@ whereas the content of the ``gdbinit`` file is::

Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.

Stack Dump and Backtrace Dump
-----------------------------

NuttX has a feature to dump the stack of a task and to dump the backtrace of it (and of all
the other tasks). This feature is useful to debug the system when it is not behaving as expected,
especially when it is crashing.

In order to enable this feature, the following options must be enabled in the NuttX configuration:
``CONFIG_SCHED_BACKTRACE``, ``CONFIG_DEBUG_SYMBOLS`` and, optionally, ``CONFIG_ALLSYMS``.

.. note::
The first two options enable the backtrace dump. The third option enables the backtrace dump
with the associated symbols, but increases the size of the generated NuttX binary.

Espressif also provides a tool to translate the backtrace dump into a human-readable format.
This tool is called ``btdecode.sh`` and is available at ``tools/espressif/btdecode.sh`` of NuttX
repository.

.. note::
This tool is not necessary if ``CONFIG_ALLSYMS`` is enabled. In this case, the backtrace dump
contains the function names.

Example - Crash Dump
^^^^^^^^^^^^^^^^^^^^

A typical crash dump, caused by an illegal load with ``CONFIG_SCHED_BACKTRACE`` and
``CONFIG_DEBUG_SYMBOLS`` enabled, is shown below::

riscv_exception: EXCEPTION: Store/AMO access fault. MCAUSE: 00000007, EPC: 42012df0, MT0
riscv_exception: PANIC!!! Exception = 00000007
_assert: Current Version: NuttX 10.4.0 2ae3246e40-dirty Sep 19 2024 14:53:33 risc-v
_assert: Assertion failed panic: at file: :0 task: backtrace process: backtrace 0x42012daa
up_dump_register: EPC: 42012df0
up_dump_register: A0: 0000005a A1: 408095e4 A2: 00000001 A3: 00000088
up_dump_register: A4: 00007fff A5: 00000001 A6: 00000000 A7: 00000000
up_dump_register: T0: 00000000 T1: 00000000 T2: ffffffff T3: 00000000
up_dump_register: T4: 00000000 T5: 00000000 T6: 00000000
up_dump_register: S0: 408086ae S1: 40808698 S2: 00000000 S3: 00000000
up_dump_register: S4: 00000000 S5: 00000000 S6: 00000000 S7: 00000000
up_dump_register: S8: 00000000 S9: 00000000 S10: 00000000 S11: 00000000
up_dump_register: SP: 40809640 FP: 408086ae TP: 00000000 RA: 42012df0
dump_stack: User Stack:
dump_stack: base: 0x408086b8
dump_stack: size: 00004040
dump_stack: sp: 0x40809640
stack_dump: 0x40809620: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00001880
stack_dump: 0x40809640: 00000000 408082b0 42012daa 42006e1e 00000000 00000000 40808698 00000002
stack_dump: 0x40809660: 00000000 00000000 00000000 42004d8a 00000000 00000000 00000000 00000000
stack_dump: 0x40809680: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
sched_dumpstack: backtrace| 2: 0x42012df0
dump_tasks: PID GROUP PRI POLICY TYPE NPX STATE EVENT SIGMASK STACKBASE STACKSIZE COMMAND
dump_tasks: ---- --- --- -------- ------- --- ------- ---------- ---------------- 0x40805120 2048 irq
dump_task: 0 0 0 FIFO Kthread - Ready 0000000000000000 0x408068b0 2032 Idle_Task
dump_task: 1 1 100 RR Task - Waiting Semaphore 0000000000000000 0x408077c8 1992 nsh_main
dump_task: 2 2 255 RR Task - Running 0000000000000000 0x408086b8 4040 backtrace task
sched_dumpstack: backtrace| 0: 0x42008420
sched_dumpstack: backtrace| 1: 0x420089a2
sched_dumpstack: backtrace| 2: 0x42012df0

The lines starting with ``sched_dumpstack`` show the backtrace of the tasks. By checking it, it is
possible to track the root cause of the crash. Saving this output to a file and using the ``btdecode.sh``::

./tools/espressif/btdecode.sh esp32h2 /tmp/backtrace.txt
Backtrace for task 2:
0x42012df0: assert_on_task at backtrace_main.c:158
(inlined by) backtrace_main at backtrace_main.c:194

Backtrace dump for all tasks:

Backtrace for task 2:
0x42012df0: assert_on_task at backtrace_main.c:158
(inlined by) backtrace_main at backtrace_main.c:194

Backtrace for task 1:
0x420089a2: sys_call2 at syscall.h:227
(inlined by) up_switch_context at riscv_switchcontext.c:95

Backtrace for task 0:
0x42008420: up_idle at esp_idle.c:74

Peripheral Support
==================

Expand Down
Loading

0 comments on commit a7a4aae

Please sign in to comment.