1# Debugging Tips
2
3For general debugging info see the [Fuchsia Debugging Workflow][fuchsia-debugging-doc].
4
5## Generating debug info
6
7There are several make variables used to control the generation of debug info.
8
9### GLOBAL_DEBUGFLAGS
10
11GLOBAL\_DEBUGFLAGS specifies level of debug info to generate.
12The default is -g.
13A useful value for getting less debug info usable in backtraces is -g1.
14
15### BOOTFS_DEBUG_MODULES
16
17BOOTFS\_DEBUG\_INFO\_FILES allows one to specify which modules
18(apps,libs,tests) have their associated debug info included
19in the boot image.
20
21The value is a comma-separated list of "module short names"
22which are generally `parent_directory/module_directory`.
23E.g., `ulib/launchpad,utest/debugger`
24Make-style patterns (%) are allowed, e.g., `ulib/%,utest/debugger`.
25
26The default is empty (meaning none).
27
28## Adding debug info to boot image
29
30By default the boot image does not contain debug info as it
31can require a lot of extra space. Adding debug info is useful when
32using tools like debuggers natively. Note that this does not apply
33to cross debugging where the debugger is running on separate machine.
34Adding debug info to the boot image is for when you are running debugging
35tools on zircon itself.
36
37Example:
38```
39$ make -j10 x86 BOOTFS_DEBUG_MODULES=ulib/%,utest/debugger GLOBAL_DEBUGFLAGS=-g1
40```
41
42This example will include in the boot image debug info files for all
43shared libraries and for the "debugger" test program. To reduce the amount
44of debug info to just that usable in backtraces `GLOBAL_DEBUGFLAGS=-g1`
45is passed.
46
47## Debugging the kernel with QEMU+GDB.
48
49See "Debugging the kernel with GDB" in [QEMU](../qemu.md) for
50documentation on debugging zircon with QEMU+GDB.
51
52[fuchsia-debugging-doc]: https://fuchsia.googlesource.com/docs/+/master/development/workflows/debugging.md
53
54## Symbolizing the backtraces
55
56To automatically symbolize the backtraces when running zircon, pass the logs
57through the symbolizer as follows:
58
59```
60$ ./scripts/run-zircon -a (x64|arm64) | ./scripts/symbolize
61...
62> crasher
63...
64[00021.715] 01044.01212> devmgr: crash_analyzer_listener: analyzing exception type 0x108
65[00021.721] 01102.01116> <== fatal exception: process crasher[2853] thread initial-thread[2867]
66[00021.721] 01102.01116> <== fatal page fault, PC at 0x38ed815cdbd7
67[00021.721] 01102.01116>  CS:                   0 RIP:     0x38ed815cdbd7 EFL:              0x246 CR2:                  0
68[00021.721] 01102.01116>  RAX:                  0 RBX:                0x1 RCX:                0x1 RDX:     0x75dec26db264
69[00021.722] 01102.01116>  RSI:                  0 RDI:                  0 RBP:      0x5663cdc3f90 RSP:      0x5663cdc3f80
70[00021.722] 01102.01116>   R8:                  0  R9:                  0 R10:                  0 R11:              0x206
71[00021.722] 01102.01116>  R12:     0x6a3f40970d70 R13:     0x6a3f40970db0 R14:               0x16 R15:         0x7986f4ef
72[00021.722] 01102.01116>  errc:               0x6
73[00021.722] 01102.01116> bottom of user stack:
74[00021.723] 01102.01116> 0x000005663cdc3f80: 40970d70 00006a3f 9af1eb38 00006fea |p..@?j..8....o..|
75[00021.724] 01102.01116> 0x000005663cdc3f90: 3cdc3fd0 00000566 815cdba7 000038ed |.?.<f.....\..8..|
76[00021.724] 01102.01116> 0x000005663cdc3fa0: 00000008 00000000 9af1eb38 00006fea |........8....o..|
77[00021.724] 01102.01116> 0x000005663cdc3fb0: 40970f70 00006a3f 40970f70 00006a3f |p..@?j..p..@?j..|
78[00021.724] 01102.01116> 0x000005663cdc3fc0: c26db570 000075de 40970db0 00006a3f |p.m..u.....@?j..|
79[00021.724] 01102.01116> 0x000005663cdc3fd0: 3cdc3ff0 00000566 c261cdef 000075de |.?.<f.....a..u..|
80[00021.724] 01102.01116> 0x000005663cdc3fe0: 00000054 00000000 40970f70 00006a3f |T.......p..@?j..|
81[00021.724] 01102.01116> 0x000005663cdc3ff0: 40970fe0 00006a3f 00000000 00000000 |...@?j..........|
82[00021.724] 01102.01116> arch: x86_64
83[00021.728] 01102.01116> dso: id=31c12edecfd596b0be787e782f896efadf23e3da base=0x75dec2603000 name=libc.so
84[00021.728] 01102.01116> dso: id=b4f9333e0d1bb7e79370905f90299d1da94e4271 base=0x51d5c67da000 name=<vDSO>
85[00021.728] 01102.01116> dso: id=a0106c6ceae6a63d35eb7e8923ebc1a62a8df3e8 base=0x38ed815cd000 name=app:crasher
86[00021.728] 01102.01116> dso: id=881704361e6af74805ab9e2a236ccf2962cdecc9 base=0x2ce98f7b2000 name=libfdio.so
87[00021.738] 01102.01116> bt#01: pc 0x38ed815cdbd7 sp 0x5663cdc3f80 (app:crasher,0xbd7)
88[00021.746] 01102.01116> bt#02: pc 0x38ed815cdba7 sp 0x5663cdc3fa0 (app:crasher,0xba7)
89[00021.747] 01102.01116> bt#03: pc 0x75dec261cdef sp 0x5663cdc3fe0 (libc.so,0x19def)
90[00021.749] 01102.01116> bt#04: pc 0 sp 0x5663cdc4000
91[00021.749] 01102.01116> bt#05: end
92
93start of symbolized stack:
94#01: blind_write at ./system/uapp/crasher/crasher.c:21
95#02: main at ./system/uapp/crasher/crasher.c:137
96#03: start_main at ./third_party/ulib/musl/src/env/__libc_start_main.c:49
97#04: unknown, can't find pc, sp or app/library in line
98end of symbolized stack
99```
100