1.. _coredump: 2 3Core Dump 4######### 5 6The core dump module enables dumping the CPU registers and memory content 7for offline debugging. This module is called when a fatal error is 8encountered and prints or stores data according to which backends 9are enabled. 10 11Configuration 12************* 13 14Configure this module using the following options. 15 16* ``DEBUG_COREDUMP``: enable the module. 17 18Here are the options to enable output backends for core dump: 19 20* ``DEBUG_COREDUMP_BACKEND_LOGGING``: use log module for core dump output. 21* ``DEBUG_COREDUMP_BACKEND_FLASH_PARTITION``: use flash partition for core 22 dump output. 23* ``DEBUG_COREDUMP_BACKEND_NULL``: fallback core dump backend if other 24 backends cannot be enabled. All output is sent to null. 25 26Here are the choices regarding memory dump: 27 28* ``DEBUG_COREDUMP_MEMORY_DUMP_MIN``: only dumps the stack of the exception 29 thread, its thread struct, and some other bare minimal data to support 30 walking the stack in the debugger. Use this only if absolute minimum of data 31 dump is desired. 32 33* ``DEBUG_COREDUMP_MEMORY_DUMP_THREADS``: Dumps the thread struct and stack of all 34 threads and all data required to debug threads. 35 36* ``DEBUG_COREDUMP_MEMORY_DUMP_LINKER_RAM``: Dumps the memory region between 37 _image_ram_start[] and _image_ram_end[]. This includes at least data, noinit, 38 and BSS sections. This is the default. 39 40Additional memory can be included in a dump (even with the "DEBUG_COREDUMP_MEMORY_DUMP_MIN" 41config selected) through one or more :ref:`coredump devices <coredump_device_api>` 42 43Usage 44***** 45 46When the core dump module is enabled, during a fatal error, CPU registers 47and memory content are printed or stored according to which backends 48are enabled. This core dump data can be fed into a custom-made GDB server as 49a remote target for GDB (and other GDB compatible debuggers). CPU registers, 50memory content and stack can be examined in the debugger. 51 52This usually involves the following steps: 53 541. Get the core dump log from the device depending on enabled backends. 55 For example, if the log module backend is used, get the log output 56 from the log module backend. 57 582. Convert the core dump log into a binary format that can be parsed by 59 the GDB server. For example, 60 :zephyr_file:`scripts/coredump/coredump_serial_log_parser.py` can be used 61 to convert the serial console log into a binary file. 62 633. Start the custom GDB server using the script 64 :zephyr_file:`scripts/coredump/coredump_gdbserver.py` with the core dump 65 binary log file, and the Zephyr ELF file as parameters. The GDB server 66 can also be started from within GDB, see below. 67 684. Start the debugger corresponding to the target architecture. 69 70.. note:: 71 Developers for Intel ADSP CAVS 15-25 platforms using 72 ``ZEPHYR_TOOLCHAIN_VARIANT=zephyr`` should use the debugger in the 73 ``xtensa-intel_apl_adsp`` toolchain of the SDK. 74 755. When ``DEBUG_COREDUMP_BACKEND_FLASH_PARTITION`` is enabled the core dump 76 data is stored in the flash partition. The flash partition must be defined 77 in the device tree: 78 79 .. code-block:: devicetree 80 81 &flash0 { 82 partitions { 83 coredump_partition: partition@255000 { 84 label = "coredump-partition"; 85 reg = <0x255000 DT_SIZE_K(4)>; 86 }; 87 }; 88 89Example 90------- 91 92This example uses the log module backend tied to serial console. 93This was done on :zephyr:board:`qemu_x86` where a null pointer was dereferenced. 94 95This is the core dump log from the serial console, and is stored 96in :file:`coredump.log`: 97 98:: 99 100 Booting from ROM..*** Booting Zephyr OS build zephyr-v2.3.0-1840-g7bba91944a63 *** 101 Hello World! qemu_x86 102 E: Page fault at address 0x0 (error code 0x2) 103 E: Linear address not present in page tables 104 E: PDE: 0x0000000000115827 Writable, User, Execute Enabled 105 E: PTE: Non-present 106 E: EAX: 0x00000000, EBX: 0x00000000, ECX: 0x00119d74, EDX: 0x000003f8 107 E: ESI: 0x00000000, EDI: 0x00101aa7, EBP: 0x00119d10, ESP: 0x00119d00 108 E: EFLAGS: 0x00000206 CS: 0x0008 CR3: 0x00119000 109 E: call trace: 110 E: EIP: 0x00100459 111 E: 0x00100477 (0x0) 112 E: 0x00100492 (0x0) 113 E: 0x001004c8 (0x0) 114 E: 0x00105465 (0x105465) 115 E: 0x00101abe (0x0) 116 E: >>> ZEPHYR FATAL ERROR 0: CPU exception on CPU 0 117 E: Current thread: 0x00119080 (unknown) 118 E: #CD:BEGIN# 119 E: #CD:5a4501000100050000000000 120 E: #CD:4101003800 121 E: #CD:0e0000000200000000000000749d1100f803000000000000009d1100109d1100 122 E: #CD:00000000a71a100059041000060200000800000000901100 123 E: #CD:4d010080901100e0901100 124 E: #CD:0100000000000000000000000180000000000000000000000000000000000000 125 E: #CD:00000000000000000000000000000000e364100000000000000000004c9c1100 126 E: #CD:000000000000000000000000b49911000004000000000000fc03000000000000 127 E: #CD:4d0100b4991100b49d1100 128 E: #CD:f8030000020000000200000002000000f8030000fd03000a02000000dc9e1100 129 E: #CD:149a1160fd03000002000000dc9e1100249a110087201000049f11000a000000 130 E: #CD:349a11000a4f1000049f11000a9e1100449a11000a8b10000200000002000000 131 E: #CD:449a1100388b1000049f11000a000000549a1100ad201000049f11000a000000 132 E: #CD:749a11000a201000049f11000a000000649a11000a201000049f11000a000000 133 E: #CD:749a1100e8201000049f11000a000000949a1100890b10000a0000000a000000 134 E: #CD:a49a1100890b10000a0000000a000000f8030000189b11000200000002000000 135 E: #CD:f49a1100289b11000a000000189b1100049b11009b0710000a000000289b1100 136 E: #CD:f49a110087201000049f110045000000f49a1100509011000a00000020901100 137 E: #CD:f49a110060901100049f1100ffffffff0000000000000000049f1100ffffffff 138 E: #CD:0000000000000000630b1000189b1100349b1100af0b1000630b1000289b1100 139 E: #CD:55891000789b11000000000020901100549b1100480000004a891000609b1100 140 E: #CD:649b1100d00b10004a891000709b110000000000609b11000a00000000000000 141 E: #CD:849b1100709b11004a89100000000000949b1100794a10000000000058901100 142 E: #CD:20901100c34a10000a00001734020000d001000000000000d49b110038000000 143 E: #CD:c49b110078481000b49911000004000000000000000000000c9c11000c9c1100 144 E: #CD:149c110000000000d49b110038000000f49b1100da481000b499110000040000 145 E: #CD:0e0000000200000000000000744d0100b4991100b49d1100009d1100109d1100 146 E: #CD:149c110099471000b4991100000400000800000000901100ad861000409c1100 147 E: #CD:349c1100e94710008090110000000000349c1100b64710008086100045000000 148 E: #CD:849c11002d53100000000000d09c11008090110020861000f5ffffff8c9c1100 149 E: #CD:000000000000000000000000a71a1000a49c1100020200008090110000000000 150 E: #CD:a49c1100020200000800000000000000a49c11001937100000000000d09c1100 151 E: #CD:0c9d0000bc9c0000b49d1100b4991100c49c1100ae37100000000000d09c1100 152 E: #CD:0800000000000000c888100000000000109d11005d031000d09c1100009d1100 153 E: #CD:109d11000000000000000000a71a1000f803000000000000749d110002000000 154 E: #CD:5904100008000000060200000e0000000202000002020000000000002c9d1100 155 E: #CD:7704100000000000d00b1000c9881000549d110000000000489d110092041000 156 E: #CD:00000000689d1100549d11000000000000000000689d1100c804100000000000 157 E: #CD:c0881000000000007c9d110000000000749d11007c9d11006554100065541000 158 E: #CD:00000000000000009c9d1100be1a100000000000000000000000000038041000 159 E: #CD:08000000020200000000000000000000f4531000000000000000000000000000 160 E: #CD:END# 161 E: Halting system 162 163 1641. Run the core dump serial log converter: 165 166 .. code-block:: console 167 168 ./scripts/coredump/coredump_serial_log_parser.py coredump.log coredump.bin 169 1702. Start the custom GDB server: 171 172 .. code-block:: console 173 174 ./scripts/coredump/coredump_gdbserver.py build/zephyr/zephyr.elf coredump.bin 175 1763. Start GDB: 177 178 .. code-block:: console 179 180 <path to SDK>/x86_64-zephyr-elf/bin/x86_64-zephyr-elf-gdb build/zephyr/zephyr.elf 181 1824. Inside GDB, connect to the GDB server via port 1234: 183 184 .. code-block:: console 185 186 (gdb) target remote localhost:1234 187 1885. Examine the CPU registers: 189 190 .. code-block:: console 191 192 (gdb) info registers 193 194 Output from GDB: 195 196 :: 197 198 eax 0x0 0 199 ecx 0x119d74 1154420 200 edx 0x3f8 1016 201 ebx 0x0 0 202 esp 0x119d00 0x119d00 <z_main_stack+844> 203 ebp 0x119d10 0x119d10 <z_main_stack+860> 204 esi 0x0 0 205 edi 0x101aa7 1055399 206 eip 0x100459 0x100459 <func_3+16> 207 eflags 0x206 [ PF IF ] 208 cs 0x8 8 209 ss <unavailable> 210 ds <unavailable> 211 es <unavailable> 212 fs <unavailable> 213 gs <unavailable> 214 2156. Examine the backtrace: 216 217 .. code-block:: console 218 219 (gdb) bt 220 221 222 Output from GDB: 223 224 :: 225 226 #0 0x00100459 in func_3 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:14 227 #1 0x00100477 in func_2 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:21 228 #2 0x00100492 in func_1 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:28 229 #3 0x001004c8 in main () at zephyr/rtos/zephyr/samples/hello_world/src/main.c:42 230 231Starting the GDB server from within GDB 232--------------------------------------- 233 234You can use ``target remote |`` to start the custom GDB server from inside 235GDB, instead of in a separate shell. 236 2371. Start GDB: 238 239 .. code-block:: console 240 241 <path to SDK>/x86_64-zephyr-elf/bin/x86_64-zephyr-elf-gdb build/zephyr/zephyr.elf 242 2432. Inside GDB, start the GDB server using the ``--pipe`` option: 244 245 .. code-block:: console 246 247 (gdb) target remote | ./scripts/coredump/coredump_gdbserver.py --pipe build/zephyr/zephyr.elf coredump.bin 248 249 250File Format 251*********** 252 253The core dump binary file consists of one file header, one 254architecture-specific block, zero or one threads metadata block(s), 255and multiple memory blocks. All numbers in 256the headers below are little endian. 257 258File Header 259----------- 260 261The file header consists of the following fields: 262 263.. list-table:: Core dump binary file header 264 :widths: 2 1 7 265 :header-rows: 1 266 267 * - Field 268 - Data Type 269 - Description 270 * - ID 271 - ``char[2]`` 272 - ``Z``, ``E`` as identifier of file. 273 * - Header version 274 - ``uint16_t`` 275 - Identify the version of the header. This needs to be incremented 276 whenever the header struct is modified. This allows parser to 277 reject older header versions so it will not incorrectly parse 278 the header. 279 * - Target code 280 - ``uint16_t`` 281 - Indicate which target (e.g. architecture or SoC) so the parser 282 can instantiate the correct register block parser. 283 * - Pointer size 284 - 'uint8_t' 285 - Size of ``uintptr_t`` in power of 2. (e.g. 5 for 32-bit, 286 6 for 64-bit). This is needed to accommodate 32-bit and 64-bit 287 target in parsing the memory block addresses. 288 * - Flags 289 - ``uint8_t`` 290 - 291 * - Fatal error reason 292 - ``unsigned int`` 293 - Reason for the fatal error, as the same in 294 ``enum k_fatal_error_reason`` defined in 295 :zephyr_file:`include/zephyr/fatal.h` 296 297Architecture-specific Block 298--------------------------- 299 300The architecture-specific block contains the byte stream of data specific 301to the target architecture (e.g. CPU registers) 302 303.. list-table:: Architecture-specific Block 304 :widths: 2 1 7 305 :header-rows: 1 306 307 * - Field 308 - Data Type 309 - Description 310 * - ID 311 - ``char`` 312 - ``A`` to indicate this is a architecture-specific block. 313 * - Header version 314 - ``uint16_t`` 315 - Identify the version of this block. To be interpreted by the target 316 architecture specific block parser. 317 * - Number of bytes 318 - ``uint16_t`` 319 - Number of bytes following the header which contains the byte stream 320 for target data. The format of the byte stream is specific to 321 the target and is only being parsed by the target parser. 322 * - Register byte stream 323 - ``uint8_t[]`` 324 - Contains target architecture specific data. 325 326Threads Metadata Block 327--------------------------- 328 329The threads metadata block contains the byte stream of data necessary 330for debugging threads. 331 332.. list-table:: Threads Metadata Block 333 :widths: 2 1 7 334 :header-rows: 1 335 336 * - Field 337 - Data Type 338 - Description 339 * - ID 340 - ``char`` 341 - ``T`` to indicate this is a threads metadata block. 342 * - Header version 343 - ``uint16_t`` 344 - Identify the version of the header. This needs to be incremented 345 whenever the header struct is modified. This allows parser to 346 reject older header versions so it will not incorrectly parse 347 the header. 348 * - Number of bytes 349 - ``uint16_t`` 350 - Number of bytes following the header which contains the byte stream 351 for target data. 352 * - Byte stream 353 - ``uint8_t[]`` 354 - Contains data necessary for debugging threads. 355 356Memory Block 357------------ 358 359The memory block contains the start and end addresses and the data within 360the memory region. 361 362.. list-table:: Memory Block 363 :widths: 2 1 7 364 :header-rows: 1 365 366 * - Field 367 - Data Type 368 - Description 369 * - ID 370 - ``char`` 371 - ``M`` to indicate this is a memory block. 372 * - Header version 373 - ``uint16_t`` 374 - Identify the version of the header. This needs to be incremented 375 whenever the header struct is modified. This allows parser to 376 reject older header versions so it will not incorrectly parse 377 the header. 378 * - Start address 379 - ``uintptr_t`` 380 - The start address of the memory region. 381 * - End address 382 - ``uintptr_t`` 383 - The end address of the memory region. 384 * - Memory byte stream 385 - ``uint8_t[]`` 386 - Contains the memory content between the start and end addresses. 387 388Adding New Target 389***************** 390 391The architecture-specific block is target specific and requires new 392dumping routine and parser for new targets. To add a new target, 393the following needs to be done: 394 395#. Add a new target code to the ``enum coredump_tgt_code`` in 396 :zephyr_file:`include/zephyr/debug/coredump.h`. 397#. Implement :c:func:`arch_coredump_tgt_code_get` simply to return 398 the newly introduced target code. 399#. Implement :c:func:`arch_coredump_info_dump` to construct 400 a target architecture block and call :c:func:`coredump_buffer_output` 401 to output the block to core dump backend. 402#. Add a parser to the core dump GDB stub scripts under 403 ``scripts/coredump/gdbstubs/`` 404 405 #. Extends the ``gdbstubs.gdbstub.GdbStub`` class. 406 #. During ``__init__``, store the GDB signal corresponding to 407 the exception reason in ``self.gdb_signal``. 408 #. Parse the architecture-specific block from 409 ``self.logfile.get_arch_data()``. This needs to match the format 410 as implemented in step 3 (inside :c:func:`arch_coredump_info_dump`). 411 #. Implement the abstract method ``handle_register_group_read_packet`` 412 where it returns the register group as GDB expected. Refer to 413 GDB's code and documentation on what it is expecting for 414 the new target. 415 #. Optionally implement ``handle_register_single_read_packet`` 416 for registers not covered in the ``g`` packet. 417 418#. Extend ``get_gdbstub()`` in 419 :zephyr_file:`scripts/coredump/gdbstubs/__init__.py` to return 420 the newly implemented GDB stub. 421 422API documentation 423***************** 424 425.. doxygengroup:: coredump_apis 426 427.. doxygengroup:: arch-coredump 428
