Re: [PATCH] doc: describe the analysis of crash dumps

25 Apr 2020

Thanks Heinrich!
On Fri, Apr 24, 2020 at 11:31:20PM +0200, Heinrich Schuchardt wrote:
...
Provide an overview of the analysis of U-Boot crash dumps.
Signed-off-by: Heinrich Schuchardt xypron.glpk@gmx.de
doc/develop/crash_dumps.rst | 122 ++++++++++++++++++++++++++++++++++++
 doc/develop/index.rst       |  10 +++
 doc/index.rst               |  11 ++++
 3 files changed, 143 insertions(+)
 create mode 100644 doc/develop/crash_dumps.rst
 create mode 100644 doc/develop/index.rst

diff --git a/doc/develop/crash_dumps.rst b/doc/develop/crash_dumps.rst
new file mode 100644
index 0000000000..5aede4a9af
--- /dev/null
+++ b/doc/develop/crash_dumps.rst
@@ -0,0 +1,122 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2020 Heinrich Schuchardt



+Analyzing crash dumps
+=====================



+When the CPU detects an instruction that it cannot execute it raises an
+interrupt. U-Boot than writes a crash dump. This chapter describes how such
+dump can be analyzed.



+Creating a crash dump voluntarily
+---------------------------------



+For describing the analysis of a crash dump we need an example. U-Boot comes
+with a command 'exception' that comes in handy here. The command is enabled
+by::


CONFIG_CMD_EXCEPTION=y


+The example output below was recorded when running qemu_arm64_defconfig on
+QEMU::


=> exception undefined
"Synchronous Abort" handler, esr 0x02000000
elr: 00000000000101fc lr : 00000000000214ec (reloc)
elr: 000000007ff291fc lr : 000000007ff3a4ec
x0 : 000000007ffbd7f8 x1 : 0000000000000000
x2 : 0000000000000001 x3 : 000000007eedce18
x4 : 000000007ff291fc x5 : 000000007eedce50
x6 : 0000000000000064 x7 : 000000007eedce10
x8 : 0000000000000000 x9 : 0000000000000004
x10: 6db6db6db6db6db7 x11: 000000000000000d
x12: 0000000000000006 x13: 000000000001869f
x14: 000000007edd7dc0 x15: 0000000000000002
x16: 000000007ff291fc x17: 0000000000000000
x18: 000000007eed8dc0 x19: 0000000000000000
x20: 000000007ffbd7f8 x21: 0000000000000000
x22: 000000007eedce10 x23: 0000000000000002
x24: 000000007ffd4c80 x25: 0000000000000000
x26: 0000000000000000 x27: 0000000000000000
x28: 000000007eedce70 x29: 000000007edd7b40

Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb)
Resetting CPU ...

resetting ...


+The first line provides us with the type of interrupt that occurred.
+(On ARMv8 a synchronous abort is an exception where the return address stored
+in the ESR register indicates the instruction that caused the exception.)



+The second line provides the contents of the elr and the lr register after
+subtracting the relocation offset. - U-Boot relocates itself after being
+loaded. - The relocation offset can also be displayed using the bdinfo command.



+After the contents of the registers we get a line indicating the machine
+code of the instructions preceding the crash and in parentheses the instruction
+leading to the dump.



+Analyzing the code location
+---------------------------



+We can convert the instructions in the line starting with 'Code:' into mnemonics
+using the objdump command. To make things easier scripts/decodecode is
+supplied::


$echo 'Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb)' | \
 CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm64 scripts/decodecode


Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb)
All code
========
  0:   b00003c0     adrp   x0, 0x79000


  4:   912ad000     add    x0, x0, #0xab4


  8:   940029d6     bl     0xa760


  c:   17ffff52     b      0xfffffffffffffd54


 10:*  e7f7defb     .inst  0xe7f7defb ; undefined <-- trapping instruction



Code starting with the faulting instruction
===========================================
  0:   e7f7defb     .inst  0xe7f7defb ; undefined




+Now lets use the locations provided by the elr and lr registers after
+subtracting the relocation offset to find out where in the code the crash
+occurred and from where it was invoked.



+File u-boot.map contains the memory layout of the U-Boot binary. Here we find
+these lines::


.text.do_undefined
             0x00000000000101fc        0xc cmd/built-in.o


.text.exception_complete
             0x0000000000010208       0x90 cmd/built-in.o


...
.text.cmd_process
             0x00000000000213b8      0x164 common/built-in.o


             0x00000000000213b8                cmd_process


.text.cmd_process_error
             0x000000000002151c       0x40 common/built-in.o


             0x000000000002151c                cmd_process_error




+So the error occurred at the start of function do_undefined() and this
+function was invoked from somewhere inside function cmd_process().



+If we want to dive deeper, we can disassemble the U-Boot binary::


$ aarch64-linux-gnu-objdump -S -D u-boot | less

00000000000101fc <do_undefined>:
{
       /*


        * 0xe7f...f.   is undefined in ARM mode


        * 0xde..       is undefined in Thumb mode


       */


       asm volatile (".word 0xe7f7defb\n");


  101fc:       e7f7defb        .inst   0xe7f7defb ; undefined


       return CMD_RET_FAILURE;


}
10200:       52800020        mov     w0, #0x1        // #1
10204:       d65f03c0        ret


+This example is based on the ARMv8 architecture but the same procedures can be
+used on other architectures as well.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
new file mode 100644
index 0000000000..072db63b5c
--- /dev/null
+++ b/doc/develop/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0+



+Develop U-Boot
+==============




+.. toctree::

:maxdepth: 2

crash_dumps

diff --git a/doc/index.rst b/doc/index.rst
index cd98be6cc5..fd9f10f28e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -26,6 +26,17 @@ trying to get it to work optimally on a given system.
build/index


+Developer-oriented documentation
+--------------------------------



+The following manuals are written for *developers* of the U-Boot - those who
+want to contribute to U-Boot.



+.. toctree::

:maxdepth: 2

develop/index


Unified Extensible Firmware (UEFI)
--
2.26.2
Acked-by: Ilias Apalodimas ilias.apalodimas@linaro.org

    