1Core Dump
2=========
3
4{IDF_TARGET_ROM_ELF:default="https://dl.espressif.com/dl/esp32_rom.elf", esp32="https://dl.espressif.com/dl/esp32_rom.elf", esp32s2="https://dl.espressif.com/dl/esp32s2_rom.elf", esp32s3="https://dl.espressif.com/dl/esp32s3_rom.elf", esp32c3="https://dl.espressif.com/dl/esp32c3_rev3_rom.elf"}
5
6Overview
7--------
8
9ESP-IDF provides support to generate core dumps on unrecoverable software errors. This useful technique allows post-mortem analysis of software state at the moment of failure.
10Upon the crash system enters panic state, prints some information and halts or reboots depending configuration. User can choose to generate core dump in order to analyse
11the reason of failure on PC later on. Core dump contains snapshots of all tasks in the system at the moment of failure. Snapshots include tasks control blocks (TCB) and stacks.
12So it is possible to find out what task, at what instruction (line of code) and what callstack of that task lead to the crash. It is also possible dumping variables content on
13demand if previously attributed accordingly.
14ESP-IDF provides special script `espcoredump.py` to help users to retrieve and analyse core dumps. This tool provides two commands for core dumps analysis:
15
16* ``info_corefile`` - prints crashed task's registers, callstack, list of available tasks in the system, memory regions and contents of memory stored in core dump (TCBs and stacks)
17* ``dbg_corefile`` - creates core dump ELF file and runs GDB debug session with this file. User can examine memory, variables and tasks states manually. Note that since not all memory is saved in core dump only values of variables allocated on stack will be meaningful
18
19For more information about core dump internals see the - :doc:`Core dump internals <core_dump_internals>`
20
21Configurations
22--------------
23
24There are a number of core dump related configuration options which user can choose in project configuration menu (``idf.py menuconfig``).
25
26**Core dump data destination (Components -> Core dump -> Data destination)**
27
28   * Save core dump to Flash (Flash)
29   * Print core dump to UART (UART)
30   * Disable core dump generation (None)
31
32**Core dump data format (Components -> Core dump -> Core dump data format)**
33
34   * ELF format (Executable and Linkable Format file for core dump)
35   * Binary format (Basic binary format for core dump)
36
37   The ELF format contains extended features and allow to save more information about broken tasks and crashed software but it requires more space in the flash memory.
38   This format of core dump is recommended for new software designs and is flexible enough to extend saved information for future revisions.
39
40   The Binary format is kept for compatibility standpoint, it uses less space in the memory to keep data and provides better performance.
41
42**Core dump data integrity check (Components -> Core dump -> Core dump data integrity check)**
43
44   .. only:: esp32
45
46      * Use CRC32 for core dump integrity verification
47      * Use SHA256 for core dump integrity verification (only work in ELF format)
48
49      The CRC32 option provides better calculation performance and consumes less memory for storage.
50
51      The SHA256 hash algorithm provides greater probability of detecting corruption than a CRC32 with multiple bit errors.
52
53   .. only:: not esp32
54
55      * Use CRC32 for core dump integrity verification
56
57**Maximum number of tasks snapshots in core dump (Components -> Core dump -> Maximum number of tasks)**
58
59**Delay before core dump is printed to UART (Components -> Core dump -> Delay before print to UART)**
60
61   The value is in ms.
62
63**Handling of UART core dumps in IDF Monitor (Components -> Core dump -> Delay before print to UART)**
64
65   The value is base64 encoded.
66
67   * Decode and show summary (info_corefile)
68   * Don't decode
69
70.. only:: esp32c3
71
72   **Reserved stack size (Components -> Core dump -> Reserved stack size)**
73
74      Size of the memory to be reserved for core dump stack. If 0 core dump process will run on the stack of crashed task/ISR, otherwise special stack will be allocated.
75      To ensure that core dump itself will not overflow task/ISR stack set this to the value above 800.
76
77Save core dump to flash
78-----------------------
79
80When this option is selected core dumps are saved to special partition on flash. When using default partition table files which are provided with ESP-IDF it automatically
81allocates necessary space on flash, But if user wants to use its own layout file together with core dump feature it should define separate partition for core dump
82as it is shown below::
83
84   # Name,   Type, SubType, Offset,  Size
85   # Note: if you have increased the bootloader size, make sure to update the offsets to avoid overlap
86   nvs,      data, nvs,     0x9000,  0x6000
87   phy_init, data, phy,     0xf000,  0x1000
88   factory,  app,  factory, 0x10000, 1M
89   coredump, data, coredump,,        64K
90
91There are no special requirements for partition name. It can be chosen according to the user application needs, but partition type should be 'data' and
92sub-type should be 'coredump'. Also when choosing partition size note that core dump data structure introduces constant overhead of 20 bytes and per-task overhead of 12 bytes.
93This overhead does not include size of TCB and stack for every task. So partition size should be at least 20 + max tasks number x (12 + TCB size + max task stack size) bytes.
94
95The example of generic command to analyze core dump from flash is: ``espcoredump.py -p </path/to/serial/port> info_corefile </path/to/program/elf/file>``
96or ``espcoredump.py -p </path/to/serial/port> dbg_corefile </path/to/program/elf/file>``
97
98Print core dump to UART
99-----------------------
100
101When this option is selected base64-encoded core dumps are printed on UART upon system panic. In this case user should save core dump text body to some file manually and
102then run the following command: ``espcoredump.py --chip <target_chip_type> info_corefile -t b64 -c </path/to/saved/base64/text> </path/to/program/elf/file>``
103or ``espcoredump.py --chip <target_chip_type> dbg_corefile -t b64 -c </path/to/saved/base64/text> </path/to/program/elf/file>``
104
105Base64-encoded body of core dump will be between the following header and footer::
106
107   ================= CORE DUMP START =================
108   <body of base64-encoded core dump, save it to file on disk>
109   ================= CORE DUMP END ===================
110
111The ``CORE DUMP START`` and ``CORE DUMP END`` lines must not be included in core dump text file.
112
113ROM Functions in Backtraces
114---------------------------
115
116It is possible situation that at the moment of crash some tasks or/and crashed task itself have one or more ROM functions in their callstacks.
117Since ROM is not part of the program ELF it will be impossible for GDB to parse such callstacks, because it tries to analyse functions' prologues to accomplish that.
118In that case callstack printing will be broken with error message at the first ROM function.
119To overcome this issue you can use ROM ELF provided by Espressif ({IDF_TARGET_ROM_ELF}) and pass it to 'espcoredump.py'.
120
121Dumping variables on demand
122---------------------------
123
124Sometimes you want to read the last value of a variable to understand the root cause of a crash.
125Core dump supports retrieving variable data over GDB by attributing special notations declared variables.
126
127Supported notations and RAM regions
128^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
129
130* ``COREDUMP_DRAM_ATTR`` places variable into DRAM area which will be included into dump.
131* ``COREDUMP_RTC_ATTR`` places variable into RTC area which will be included into dump.
132* ``COREDUMP_RTC_FAST_ATTR`` places variable into RTC_FAST area which will be included into dump.
133
134Example
135^^^^^^^
136
1371. In :ref:`project-configuration-menu`, enable :ref:`COREDUMP TO FLASH <CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART>`, then save and exit.
138
1392. In your project, create a global variable in DRAM area as such as:
140
141.. code-block:: bash
142
143   // uint8_t global_var;
144   COREDUMP_DRAM_ATTR uint8_t global_var;
145
1463. In main application, set the variable to any value and ``assert(0)`` to cause a crash.
147
148.. code-block:: bash
149
150   global_var = 25;
151   assert(0);
152
1534. Build, flash and run the application on a target device and wait for the dumping information.
154
1555. Run the command below to start core dumping in GDB, where ``PORT`` is the device USB port:
156
157.. code-block:: bash
158
159   espcoredump.py -p PORT dbg_corefile <path/to/elf>
160
1616. In GDB shell, type ``p global_var`` to get the variable content:
162
163.. code-block:: bash
164
165   (gdb) p global_var
166   $1 = 25 '\031'
167
168Running ``espcoredump.py``
169--------------------------
170
171Generic command syntax: ``espcoredump.py [options] command [args]``
172
173:Script Options:
174
175   --chip {auto,esp32,esp32s2,esp32s3,esp32c3}
176                     Target chip type. Default value is "auto"
177
178   --port PORT, -p PORT  Serial port device. Either "chip" or "port" need to be specified to determine the port when you have multi-target connected at the same time.
179
180   --baud BAUD, -b BAUD  Serial port baud rate used when flashing/reading
181
182   --gdb-timeout-sec GDB_TIMEOUT_SEC
183                     Overwrite the default internal delay for gdb responses
184
185:Commands:
186
187   **dbg_corefile**     Starts GDB debugging session with specified corefile
188
189   **info_corefile**    Print core dump info from file
190
191:Command Arguments:
192
193   --debug DEBUG, -d DEBUG
194                     Log level (0..3)
195
196   --gdb GDB, -g GDB     Path to gdb
197
198   --core CORE, -c CORE  Path to core dump file (if skipped core dump will be read from flash)
199
200   --core-format {b64,elf,raw}, -t {b64,elf,raw}
201                     File specified with "-c" is an ELF ("elf"), raw (raw) or base64-encoded (b64) binary
202
203   --off OFF, -o OFF     Offset of coredump partition in flash (type "make partition_table" to see).
204
205   --save-core SAVE_CORE, -s SAVE_CORE
206                     Save core to file. Otherwise temporary core file will be deleted. Does not work with "-c"
207
208   --rom-elf ROM_ELF, -r ROM_ELF
209                     Path to ROM ELF file. Will use "<target>_rom.elf" if not specified
210
211   --print-mem, -m       Print memory dump. Only valid when info_corefile.
212
213   **<prog>**            Path to program ELF file.
214