diff --git a/docs/_static/core_dump_format_bin.png b/docs/_static/core_dump_format_bin.png new file mode 100644 index 000000000..db3728bcb Binary files /dev/null and b/docs/_static/core_dump_format_bin.png differ diff --git a/docs/_static/core_dump_format_elf.png b/docs/_static/core_dump_format_elf.png new file mode 100644 index 000000000..9bcb0e0a7 Binary files /dev/null and b/docs/_static/core_dump_format_elf.png differ diff --git a/docs/_static/core_dump_impl.png b/docs/_static/core_dump_impl.png new file mode 100644 index 000000000..45f733d91 Binary files /dev/null and b/docs/_static/core_dump_impl.png differ diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index 0b14acd53..c144b0767 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -19,6 +19,8 @@ ESP-IDF provides special script `espcoredump.py` to help users to retrieve and a * 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) * 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 meaningfull +For more information about core dump internals see the - :doc:`Core dump internals ` + Configuration ------------- diff --git a/docs/en/api-guides/core_dump_internals.rst b/docs/en/api-guides/core_dump_internals.rst new file mode 100644 index 000000000..d335d374d --- /dev/null +++ b/docs/en/api-guides/core_dump_internals.rst @@ -0,0 +1,40 @@ +:orphan: + +Anatomy of core dump image +-------------------------- + +Core dump component can be configured to use old legacy binary format or the new ELF one. The ELF format is recommended for new designs. It provides more information about the CPU and memory state of a program at the moment when panic handler is entered. +The memory state embeds a snapshot of all tasks mapped in the memory space of the program. The CPU state contains register values when the core dump has been generated. Core dump file uses a subset of the ELF structures to register these information. +Loadable ELF segments are used for the memory state of the process while ELF notes (ELF.PT_NOTE) are used for process metadata (pid, registers, signal, ...). Especially, the CPU status is stored in a note with a special name and type (``CORE``, ``NT_PRSTATUS type``). + +Here is an overview of coredump layout: + +.. figure:: ../../_static/core_dump_format_elf.png + :align: center + :alt: Core dump image format + :figclass: align-center + + Core dump ELF image format + +.. figure:: ../../_static/core_dump_format_bin.png + :align: center + :alt: Core dump binary image format + :figclass: align-center + + Core dump binary image format + +Note: The format of image file showed on the above pictures represents current version of image and can be changed in future releases. + +Overview of implementation +-------------------------- + +The figure below describes some basic aspects related to implementation of core dump: + +.. figure:: ../../_static/core_dump_impl.png + :align: center + :alt: Core dump implementation overview + :figclass: align-center + + Core dump implementation overview + +Note: The diagram above hide some details and represents current implementation of the core dump and can be changed later. \ No newline at end of file diff --git a/docs/zh_CN/api-guides/core_dump_internals.rst b/docs/zh_CN/api-guides/core_dump_internals.rst new file mode 100644 index 000000000..3de3b65ed --- /dev/null +++ b/docs/zh_CN/api-guides/core_dump_internals.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/core_dump_internals.rst \ No newline at end of file