services/debugging/coredump.html · services/debugging/coredump.rst 공식 원문 ↗

Zephyr 3.7.0 · Debugging

Core Dump

Fatal error 현장을 backend에 남기고 offline GDB에서 register, memory와 stack을 재현합니다.

Official pathservices/debugging/coredump.html
Source fileservices/debugging/coredump.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

Logging·flash backend, serial log 변환, GDB server, file·architecture·memory block format과 새 target 추가 절차를 설명합니다.

Backends

Log · Flash · Null

Blocks

File · Arch · Memory

Tool

GDB remote

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 2E6F8B5028189B405D0D0B5BA3C18E1569A7446E5B00446D992C3D6F4D972B1A
.. _coredump:

Core Dump
#########

The core dump module enables dumping the CPU registers and memory content
for offline debugging. This module is called when a fatal error is
encountered and prints or stores data according to which backends
are enabled.

Configuration
*************

Configure this module using the following options.

* ``DEBUG_COREDUMP``: enable the module.

Here are the options to enable output backends for core dump:

* ``DEBUG_COREDUMP_BACKEND_LOGGING``: use log module for core dump output.
* ``DEBUG_COREDUMP_BACKEND_FLASH_PARTITION``: use flash partition for core
  dump output.
* ``DEBUG_COREDUMP_BACKEND_NULL``: fallback core dump backend if other
  backends cannot be enabled. All output is sent to null.

Here are the choices regarding memory dump:

* ``DEBUG_COREDUMP_MEMORY_DUMP_MIN``: only dumps the stack of the exception
  thread, its thread struct, and some other bare minimal data to support
  walking the stack in the debugger. Use this only if absolute minimum of data
  dump is desired.

Additional memory can be included in a dump (even with the "DEBUG_COREDUMP_MEMORY_DUMP_MIN"
config selected) through one or more :ref:`coredump devices <coredump_device_api>`

Usage
*****

When the core dump module is enabled, during a fatal error, CPU registers
and memory content are printed or stored according to which backends
are enabled. This core dump data can fed into a custom-made GDB server as
a remote target for GDB (and other GDB compatible debuggers). CPU registers,
memory content and stack can be examined in the debugger.

This usually involves the following steps:

1. Get the core dump log from the device depending on enabled backends.
   For example, if the log module backend is used, get the log output
   from the log module backend.

2. Convert the core dump log into a binary format that can be parsed by
   the GDB server. For example,
   :zephyr_file:`scripts/coredump/coredump_serial_log_parser.py` can be used
   to convert the serial console log into a binary file.

3. Start the custom GDB server using the script
   :zephyr_file:`scripts/coredump/coredump_gdbserver.py` with the core dump
   binary log file, and the Zephyr ELF file as parameters. The GDB server
   can also be started from within GDB, see below.

4. Start the debugger corresponding to the target architecture.

.. note::
   Developers for Intel ADSP CAVS 15-25 platforms using
   ``ZEPHYR_TOOLCHAIN_VARIANT=zephyr`` should use the debugger in the
   ``xtensa-intel_apl_adsp`` toolchain of the SDK.

5. When ``DEBUG_COREDUMP_BACKEND_FLASH_PARTITION`` is enabled the core dump
   data is stored in the flash partition. The flash partition must be defined
   in the device tree:

	.. code-block:: devicetree

		&flash0 {
			partitions {
				coredump_partition: partition@255000 {
					label = "coredump-partition";
					reg = <0x255000 DT_SIZE_K(4)>;
				};
		};

Example
-------

This example uses the log module backend tied to serial console.
This was done on :ref:`qemu_x86` where a null pointer was dereferenced.

This is the core dump log from the serial console, and is stored
in :file:`coredump.log`:

::

   Booting from ROM..*** Booting Zephyr OS build zephyr-v2.3.0-1840-g7bba91944a63  ***
   Hello World! qemu_x86
   E: Page fault at address 0x0 (error code 0x2)
   E: Linear address not present in page tables
   E:   PDE: 0x0000000000115827 Writable, User, Execute Enabled
   E:   PTE: Non-present
   E: EAX: 0x00000000, EBX: 0x00000000, ECX: 0x00119d74, EDX: 0x000003f8
   E: ESI: 0x00000000, EDI: 0x00101aa7, EBP: 0x00119d10, ESP: 0x00119d00
   E: EFLAGS: 0x00000206 CS: 0x0008 CR3: 0x00119000
   E: call trace:
   E: EIP: 0x00100459
   E:      0x00100477 (0x0)
   E:      0x00100492 (0x0)
   E:      0x001004c8 (0x0)
   E:      0x00105465 (0x105465)
   E:      0x00101abe (0x0)
   E: >>> ZEPHYR FATAL ERROR 0: CPU exception on CPU 0
   E: Current thread: 0x00119080 (unknown)
   E: #CD:BEGIN#
   E: #CD:5a4501000100050000000000
   E: #CD:4101003800
   E: #CD:0e0000000200000000000000749d1100f803000000000000009d1100109d1100
   E: #CD:00000000a71a100059041000060200000800000000901100
   E: #CD:4d010080901100e0901100
   E: #CD:0100000000000000000000000180000000000000000000000000000000000000
   E: #CD:00000000000000000000000000000000e364100000000000000000004c9c1100
   E: #CD:000000000000000000000000b49911000004000000000000fc03000000000000
   E: #CD:4d0100b4991100b49d1100
   E: #CD:f8030000020000000200000002000000f8030000fd03000a02000000dc9e1100
   E: #CD:149a1160fd03000002000000dc9e1100249a110087201000049f11000a000000
   E: #CD:349a11000a4f1000049f11000a9e1100449a11000a8b10000200000002000000
   E: #CD:449a1100388b1000049f11000a000000549a1100ad201000049f11000a000000
   E: #CD:749a11000a201000049f11000a000000649a11000a201000049f11000a000000
   E: #CD:749a1100e8201000049f11000a000000949a1100890b10000a0000000a000000
   E: #CD:a49a1100890b10000a0000000a000000f8030000189b11000200000002000000
   E: #CD:f49a1100289b11000a000000189b1100049b11009b0710000a000000289b1100
   E: #CD:f49a110087201000049f110045000000f49a1100509011000a00000020901100
   E: #CD:f49a110060901100049f1100ffffffff0000000000000000049f1100ffffffff
   E: #CD:0000000000000000630b1000189b1100349b1100af0b1000630b1000289b1100
   E: #CD:55891000789b11000000000020901100549b1100480000004a891000609b1100
   E: #CD:649b1100d00b10004a891000709b110000000000609b11000a00000000000000
   E: #CD:849b1100709b11004a89100000000000949b1100794a10000000000058901100
   E: #CD:20901100c34a10000a00001734020000d001000000000000d49b110038000000
   E: #CD:c49b110078481000b49911000004000000000000000000000c9c11000c9c1100
   E: #CD:149c110000000000d49b110038000000f49b1100da481000b499110000040000
   E: #CD:0e0000000200000000000000744d0100b4991100b49d1100009d1100109d1100
   E: #CD:149c110099471000b4991100000400000800000000901100ad861000409c1100
   E: #CD:349c1100e94710008090110000000000349c1100b64710008086100045000000
   E: #CD:849c11002d53100000000000d09c11008090110020861000f5ffffff8c9c1100
   E: #CD:000000000000000000000000a71a1000a49c1100020200008090110000000000
   E: #CD:a49c1100020200000800000000000000a49c11001937100000000000d09c1100
   E: #CD:0c9d0000bc9c0000b49d1100b4991100c49c1100ae37100000000000d09c1100
   E: #CD:0800000000000000c888100000000000109d11005d031000d09c1100009d1100
   E: #CD:109d11000000000000000000a71a1000f803000000000000749d110002000000
   E: #CD:5904100008000000060200000e0000000202000002020000000000002c9d1100
   E: #CD:7704100000000000d00b1000c9881000549d110000000000489d110092041000
   E: #CD:00000000689d1100549d11000000000000000000689d1100c804100000000000
   E: #CD:c0881000000000007c9d110000000000749d11007c9d11006554100065541000
   E: #CD:00000000000000009c9d1100be1a100000000000000000000000000038041000
   E: #CD:08000000020200000000000000000000f4531000000000000000000000000000
   E: #CD:END#
   E: Halting system


1. Run the core dump serial log converter:

   .. code-block:: console

      ./scripts/coredump/coredump_serial_log_parser.py coredump.log coredump.bin

2. Start the custom GDB server:

   .. code-block:: console

      ./scripts/coredump/coredump_gdbserver.py build/zephyr/zephyr.elf coredump.bin

3. Start GDB:

   .. code-block:: console

      <path to SDK>/x86_64-zephyr-elf/bin/x86_64-zephyr-elf-gdb build/zephyr/zephyr.elf

4. Inside GDB, connect to the GDB server via port 1234:

   .. code-block:: console

      (gdb) target remote localhost:1234

5. Examine the CPU registers:

   .. code-block:: console

      (gdb) info registers

   Output from GDB:

   ::

      eax            0x0                 0
      ecx            0x119d74            1154420
      edx            0x3f8               1016
      ebx            0x0                 0
      esp            0x119d00            0x119d00 <z_main_stack+844>
      ebp            0x119d10            0x119d10 <z_main_stack+860>
      esi            0x0                 0
      edi            0x101aa7            1055399
      eip            0x100459            0x100459 <func_3+16>
      eflags         0x206               [ PF IF ]
      cs             0x8                 8
      ss             <unavailable>
      ds             <unavailable>
      es             <unavailable>
      fs             <unavailable>
      gs             <unavailable>

6. Examine the backtrace:

   .. code-block:: console

      (gdb) bt


   Output from GDB:

   ::

      #0  0x00100459 in func_3 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:14
      #1  0x00100477 in func_2 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:21
      #2  0x00100492 in func_1 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:28
      #3  0x001004c8 in main () at zephyr/rtos/zephyr/samples/hello_world/src/main.c:42

Starting the GDB server from within GDB
---------------------------------------

You can use ``target remote |`` to start the custom GDB server from inside
GDB, instead of in a separate shell.

1. Start GDB:

   .. code-block:: console

      <path to SDK>/x86_64-zephyr-elf/bin/x86_64-zephyr-elf-gdb build/zephyr/zephyr.elf

2. Inside GDB, start the GDB server using the ``--pipe`` option:

   .. code-block:: console

      (gdb) target remote | ./scripts/coredump/coredump_gdbserver.py --pipe build/zephyr/zephyr.elf coredump.bin


File Format
***********

The core dump binary file consists of one file header, one
architecture-specific block, and multiple memory blocks. All numbers in
the headers below are little endian.

File Header
-----------

The file header consists of the following fields:

.. list-table:: Core dump binary file header
   :widths: 2 1 7
   :header-rows: 1

   * - Field
     - Data Type
     - Description
   * - ID
     - ``char[2]``
     - ``Z``, ``E`` as identifier of file.
   * - Header version
     - ``uint16_t``
     - Identify the version of the header. This needs to be incremented
       whenever the header struct is modified. This allows parser to
       reject older header versions so it will not incorrectly parse
       the header.
   * - Target code
     - ``uint16_t``
     - Indicate which target (e.g. architecture or SoC) so the parser
       can instantiate the correct register block parser.
   * - Pointer size
     - 'uint8_t'
     - Size of ``uintptr_t`` in power of 2. (e.g. 5 for 32-bit,
       6 for 64-bit). This is needed to accommodate 32-bit and 64-bit
       target in parsing the memory block addresses.
   * - Flags
     - ``uint8_t``
     -
   * - Fatal error reason
     - ``unsigned int``
     - Reason for the fatal error, as the same in
       ``enum k_fatal_error_reason`` defined in
       :zephyr_file:`include/zephyr/fatal.h`

Architecture-specific Block
---------------------------

The architecture-specific block contains the byte stream of data specific
to the target architecture (e.g. CPU registers)

.. list-table:: Architecture-specific Block
   :widths: 2 1 7
   :header-rows: 1

   * - Field
     - Data Type
     - Description
   * - ID
     - ``char``
     - ``A`` to indicate this is a architecture-specific block.
   * - Header version
     - ``uint16_t``
     - Identify the version of this block. To be interpreted by the target
       architecture specific block parser.
   * - Number of bytes
     - ``uint16_t``
     - Number of bytes following the header which contains the byte stream
       for target data. The format of the byte stream is specific to
       the target and is only being parsed by the target parser.
   * - Register byte stream
     - ``uint8_t[]``
     - Contains target architecture specific data.

Memory Block
------------

The memory block contains the start and end addresses and the data within
the memory region.

.. list-table:: Memory Block
   :widths: 2 1 7
   :header-rows: 1

   * - Field
     - Data Type
     - Description
   * - ID
     - ``char``
     - ``M`` to indicate this is a memory block.
   * - Header version
     - ``uint16_t``
     - Identify the version of the header. This needs to be incremented
       whenever the header struct is modified. This allows parser to
       reject older header versions so it will not incorrectly parse
       the header.
   * - Start address
     - ``uintptr_t``
     - The start address of the memory region.
   * - End address
     - ``uintptr_t``
     - The end address of the memory region.
   * - Memory byte stream
     - ``uint8_t[]``
     - Contains the memory content between the start and end addresses.

Adding New Target
*****************

The architecture-specific block is target specific and requires new
dumping routine and parser for new targets. To add a new target,
the following needs to be done:

#. Add a new target code to the ``enum coredump_tgt_code`` in
   :zephyr_file:`include/zephyr/debug/coredump.h`.
#. Implement :c:func:`arch_coredump_tgt_code_get` simply to return
   the newly introduced target code.
#. Implement :c:func:`arch_coredump_info_dump` to construct
   a target architecture block and call :c:func:`coredump_buffer_output`
   to output the block to core dump backend.
#. Add a parser to the core dump GDB stub scripts under
   ``scripts/coredump/gdbstubs/``

   #. Extends the ``gdbstubs.gdbstub.GdbStub`` class.
   #. During ``__init__``, store the GDB signal corresponding to
      the exception reason in ``self.gdb_signal``.
   #. Parse the architecture-specific block from
      ``self.logfile.get_arch_data()``. This needs to match the format
      as implemented in step 3 (inside :c:func:`arch_coredump_info_dump`).
   #. Implement the abstract method ``handle_register_group_read_packet``
      where it returns the register group as GDB expected. Refer to
      GDB's code and documentation on what it is expecting for
      the new target.
   #. Optionally implement ``handle_register_single_read_packet``
      for registers not covered in the ``g`` packet.

#. Extend ``get_gdbstub()`` in
   :zephyr_file:`scripts/coredump/gdbstubs/__init__.py` to return
   the newly implemented GDB stub.

API documentation
*****************

.. doxygengroup:: coredump_apis

.. doxygengroup:: arch-coredump

Part 3

한국어 전문 번역

Core dump module은 offline debugging을 위해 CPU register와 memory content를 dump합니다. Fatal error가 발생할 때 이 module이 호출되며, enable된 backend에 따라 data를 출력하거나 저장합니다.

설정

다음 option으로 module을 설정합니다.

  • DEBUG_COREDUMP: module을 enable합니다.

Core dump output backend를 고르는 option은 다음과 같습니다.

  • DEBUG_COREDUMP_BACKEND_LOGGING: log module로 core dump를 출력합니다.
  • DEBUG_COREDUMP_BACKEND_FLASH_PARTITION: flash partition에 core dump를 저장합니다.
  • DEBUG_COREDUMP_BACKEND_NULL: 다른 backend를 enable할 수 없을 때 사용하는 fallback입니다. 모든 output을 null로 보냅니다.

Memory dump 범위를 최소화하려면 다음 option을 사용합니다.

  • DEBUG_COREDUMP_MEMORY_DUMP_MIN: exception thread의 stack과 thread structure, debugger에서 stack을 따라가는 데 필요한 최소 data만 dump합니다. 절대 최소 dump가 필요할 때만 사용합니다.

DEBUG_COREDUMP_MEMORY_DUMP_MIN을 선택한 경우에도 하나 이상의 coredump device를 통해 추가 memory를 dump에 포함할 수 있습니다.

사용법

Core dump module을 enable하면 fatal error 때 CPU register와 memory content가 backend 설정에 따라 출력되거나 저장됩니다. 이 data를 custom GDB server에 remote target으로 공급하면 GDB와 호환 debugger에서 register, memory와 stack을 조사할 수 있습니다.

  1. Enable한 backend에 맞춰 device에서 core dump log를 가져옵니다. Logging backend라면 log module output을 수집합니다.
  2. Core dump log를 GDB server가 parse할 수 있는 binary format으로 변환합니다. Serial console log는 scripts/coredump/coredump_serial_log_parser.py로 변환할 수 있습니다.
  3. scripts/coredump/coredump_gdbserver.py에 core dump binary log와 Zephyr ELF file을 전달해 custom GDB server를 시작합니다. 아래 설명처럼 GDB 안에서도 시작할 수 있습니다.
  4. Target architecture에 맞는 debugger를 시작합니다.
  1. DEBUG_COREDUMP_BACKEND_FLASH_PARTITION을 enable하면 core dump data를 flash partition에 저장합니다. Device tree에 partition을 다음처럼 정의해야 합니다.
&flash0 {
        partitions {
                coredump_partition: partition@255000 {
                        label = "coredump-partition";
                        reg = <0x255000 DT_SIZE_K(4)>;
                };
};

예제

이 예제는 serial console에 연결된 log module backend를 사용합니다. qemu_x86에서 null pointer를 dereference해 생성한 core dump log를 coredump.log에 저장했습니다.

Booting from ROM..*** Booting Zephyr OS build zephyr-v2.3.0-1840-g7bba91944a63  ***
Hello World! qemu_x86
E: Page fault at address 0x0 (error code 0x2)
E: Linear address not present in page tables
E:   PDE: 0x0000000000115827 Writable, User, Execute Enabled
E:   PTE: Non-present
E: EAX: 0x00000000, EBX: 0x00000000, ECX: 0x00119d74, EDX: 0x000003f8
E: ESI: 0x00000000, EDI: 0x00101aa7, EBP: 0x00119d10, ESP: 0x00119d00
E: EFLAGS: 0x00000206 CS: 0x0008 CR3: 0x00119000
E: call trace:
E: EIP: 0x00100459
E:      0x00100477 (0x0)
E:      0x00100492 (0x0)
E:      0x001004c8 (0x0)
E:      0x00105465 (0x105465)
E:      0x00101abe (0x0)
E: >>> ZEPHYR FATAL ERROR 0: CPU exception on CPU 0
E: Current thread: 0x00119080 (unknown)
E: #CD:BEGIN#
E: #CD:5a4501000100050000000000
E: #CD:4101003800
E: #CD:0e0000000200000000000000749d1100f803000000000000009d1100109d1100
E: #CD:00000000a71a100059041000060200000800000000901100
E: #CD:4d010080901100e0901100
E: #CD:0100000000000000000000000180000000000000000000000000000000000000
E: #CD:00000000000000000000000000000000e364100000000000000000004c9c1100
E: #CD:000000000000000000000000b49911000004000000000000fc03000000000000
E: #CD:4d0100b4991100b49d1100
E: #CD:f8030000020000000200000002000000f8030000fd03000a02000000dc9e1100
E: #CD:149a1160fd03000002000000dc9e1100249a110087201000049f11000a000000
E: #CD:349a11000a4f1000049f11000a9e1100449a11000a8b10000200000002000000
E: #CD:449a1100388b1000049f11000a000000549a1100ad201000049f11000a000000
E: #CD:749a11000a201000049f11000a000000649a11000a201000049f11000a000000
E: #CD:749a1100e8201000049f11000a000000949a1100890b10000a0000000a000000
E: #CD:a49a1100890b10000a0000000a000000f8030000189b11000200000002000000
E: #CD:f49a1100289b11000a000000189b1100049b11009b0710000a000000289b1100
E: #CD:f49a110087201000049f110045000000f49a1100509011000a00000020901100
E: #CD:f49a110060901100049f1100ffffffff0000000000000000049f1100ffffffff
E: #CD:0000000000000000630b1000189b1100349b1100af0b1000630b1000289b1100
E: #CD:55891000789b11000000000020901100549b1100480000004a891000609b1100
E: #CD:649b1100d00b10004a891000709b110000000000609b11000a00000000000000
E: #CD:849b1100709b11004a89100000000000949b1100794a10000000000058901100
E: #CD:20901100c34a10000a00001734020000d001000000000000d49b110038000000
E: #CD:c49b110078481000b49911000004000000000000000000000c9c11000c9c1100
E: #CD:149c110000000000d49b110038000000f49b1100da481000b499110000040000
E: #CD:0e0000000200000000000000744d0100b4991100b49d1100009d1100109d1100
E: #CD:149c110099471000b4991100000400000800000000901100ad861000409c1100
E: #CD:349c1100e94710008090110000000000349c1100b64710008086100045000000
E: #CD:849c11002d53100000000000d09c11008090110020861000f5ffffff8c9c1100
E: #CD:000000000000000000000000a71a1000a49c1100020200008090110000000000
E: #CD:a49c1100020200000800000000000000a49c11001937100000000000d09c1100
E: #CD:0c9d0000bc9c0000b49d1100b4991100c49c1100ae37100000000000d09c1100
E: #CD:0800000000000000c888100000000000109d11005d031000d09c1100009d1100
E: #CD:109d11000000000000000000a71a1000f803000000000000749d110002000000
E: #CD:5904100008000000060200000e0000000202000002020000000000002c9d1100
E: #CD:7704100000000000d00b1000c9881000549d110000000000489d110092041000
E: #CD:00000000689d1100549d11000000000000000000689d1100c804100000000000
E: #CD:c0881000000000007c9d110000000000749d11007c9d11006554100065541000
E: #CD:00000000000000009c9d1100be1a100000000000000000000000000038041000
E: #CD:08000000020200000000000000000000f4531000000000000000000000000000
E: #CD:END#
E: Halting system
  1. Core dump serial log converter를 실행합니다.
    ./scripts/coredump/coredump_serial_log_parser.py coredump.log coredump.bin
  2. Custom GDB server를 시작합니다.
    ./scripts/coredump/coredump_gdbserver.py build/zephyr/zephyr.elf coredump.bin
  3. GDB를 시작합니다.
    <path to SDK>/x86_64-zephyr-elf/bin/x86_64-zephyr-elf-gdb build/zephyr/zephyr.elf
  4. GDB 안에서 port 1234의 GDB server에 연결합니다.
    (gdb) target remote localhost:1234
  5. CPU register를 조사합니다.
    (gdb) info registers

    GDB output은 다음과 같습니다.

    eax            0x0                 0
    ecx            0x119d74            1154420
    edx            0x3f8               1016
    ebx            0x0                 0
    esp            0x119d00            0x119d00 <z_main_stack+844>
    ebp            0x119d10            0x119d10 <z_main_stack+860>
    esi            0x0                 0
    edi            0x101aa7            1055399
    eip            0x100459            0x100459 <func_3+16>
    eflags         0x206               [ PF IF ]
    cs             0x8                 8
    ss             <unavailable>
    ds             <unavailable>
    es             <unavailable>
    fs             <unavailable>
    gs             <unavailable>
  6. Backtrace를 조사합니다.
    (gdb) bt

    GDB output은 다음과 같습니다.

    #0  0x00100459 in func_3 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:14
    #1  0x00100477 in func_2 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:21
    #2  0x00100492 in func_1 (addr=0x0) at zephyr/rtos/zephyr/samples/hello_world/src/main.c:28
    #3  0x001004c8 in main () at zephyr/rtos/zephyr/samples/hello_world/src/main.c:42

GDB 내부에서 GDB server 시작

별도 shell 대신 GDB 안에서 custom GDB server를 시작하려면 target remote |를 사용할 수 있습니다.

  1. GDB를 시작합니다.
    <path to SDK>/x86_64-zephyr-elf/bin/x86_64-zephyr-elf-gdb build/zephyr/zephyr.elf
  2. GDB 안에서 --pipe option으로 GDB server를 시작합니다.
    (gdb) target remote | ./scripts/coredump/coredump_gdbserver.py --pipe build/zephyr/zephyr.elf coredump.bin

파일 형식

Core dump binary file은 file header 하나, architecture-specific block 하나와 여러 memory block으로 이루어집니다. 아래 header의 모든 number는 little endian입니다.

File Header

File header field는 다음과 같습니다.

Core dump binary file header
FieldData Type설명
IDchar[2]File identifier인 Z, E입니다.
Header versionuint16_tHeader version입니다. Header struct가 바뀔 때마다 증가해야 하며 parser가 오래된 version을 잘못 parse하지 않고 거부하게 합니다.
Target codeuint16_tArchitecture나 SoC 같은 target을 나타내 parser가 올바른 register block parser를 만들 수 있게 합니다.
Pointer sizeuint8_tuintptr_t 크기를 2의 지수로 나타냅니다. 예를 들어 32-bit는 5, 64-bit는 6이며 memory block address parse에 필요합니다.
Flagsuint8_tFlag field입니다.
Fatal error reasonunsigned intinclude/zephyr/fatal.h의 enum k_fatal_error_reason과 같은 fatal error reason입니다.

Architecture-specific Block

Architecture-specific block은 CPU register처럼 target architecture에 고유한 data byte stream을 담습니다.

Architecture-specific Block
FieldData Type설명
IDcharArchitecture-specific block임을 나타내는 A입니다.
Header versionuint16_tTarget architecture-specific block parser가 해석할 block version입니다.
Number of bytesuint16_tHeader 뒤에 오는 target data byte stream의 byte 수입니다. 형식은 target별로 다르며 target parser만 해석합니다.
Register byte streamuint8_t[]Target architecture에 고유한 data입니다.

Memory Block

Memory block은 memory region의 start·end address와 그 구간의 data를 담습니다.

Memory Block
FieldData Type설명
IDcharMemory block임을 나타내는 M입니다.
Header versionuint16_tHeader struct가 바뀔 때 증가하는 version입니다. Parser가 오래된 header를 잘못 해석하지 않게 합니다.
Start addressuintptr_tMemory region의 시작 address입니다.
End addressuintptr_tMemory region의 끝 address입니다.
Memory byte streamuint8_t[]Start와 end address 사이의 memory content입니다.

새 Target 추가

Architecture-specific block은 target별 dumping routine과 parser가 필요합니다. 새 target을 추가하려면 다음 작업을 수행합니다.

  1. include/zephyr/debug/coredump.h의 enum coredump_tgt_code에 target code를 추가합니다.
  2. arch_coredump_tgt_code_get을 구현해 새 target code를 반환합니다.
  3. arch_coredump_info_dump을 구현해 target architecture block을 만들고 coredump_buffer_output을 호출해 backend로 출력합니다.
  4. scripts/coredump/gdbstubs/ 아래에 core dump GDB stub parser를 추가합니다.
    1. gdbstubs.gdbstub.GdbStub class를 확장합니다.
    2. __init__에서 exception reason에 대응하는 GDB signal을 self.gdb_signal에 저장합니다.
    3. self.logfile.get_arch_data()에서 architecture-specific block을 parse합니다. 형식은 arch_coredump_info_dump 구현과 일치해야 합니다.
    4. GDB가 기대하는 register group을 반환하도록 abstract method handle_register_group_read_packet을 구현합니다.
    5. g packet에 포함되지 않는 register가 필요하다면 handle_register_single_read_packet도 구현합니다.
  5. scripts/coredump/gdbstubs/__init__.py의 get_gdbstub()을 확장해 새 GDB stub을 반환합니다.

API 문서

원문의 Doxygen group coredump_apis와 arch-coredump에는 공통 core dump API와 architecture-specific API가 수록됩니다.

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.