Message ID | 20240626104718.74965-1-ada@thorsis.com |
---|---|
State | Accepted, archived |
Delegated to: | Heinrich Schuchardt |
Headers | show |
Series | [next] doc: develop: Add a general section on gdb usage | expand |
On 6/26/24 12:47, Alexander Dahl wrote: > Mashed up from different sources linked below, including the now gone > Wiki and doc/README.arm-relocation file. Tested on a custom board with > AT91 SAMA5D2 SoC and Segger J-Link Base adapter. This is only generic > advice here, the usage is not board specific. Some board docs have more > specific instructions on using gdb with a particular board. > > Link: https://www.slideshare.net/slideshow/embedded-recipes-2019-introduction-to-jtag-debugging/177511981 > Link: https://boundarydevices.com/debugging-using-segger-j-link-jtag/ > Link: https://web.archive.org/web/20141224200032/http://www.denx.de/wiki/view/DULG/DebuggingUBoot > Link: https://web.archive.org/web/20141206064148/http://www.denx.de/wiki/view/DULG/GDBScripts1 > Suggested-by: Marek Vasut <marex@denx.de> > Signed-off-by: Alexander Dahl <ada@thorsis.com> > --- > doc/develop/gdb.rst | 154 ++++++++++++++++++++++++++++++++++++++++++ > doc/develop/index.rst | 1 + > 2 files changed, 155 insertions(+) > create mode 100644 doc/develop/gdb.rst > > diff --git a/doc/develop/gdb.rst b/doc/develop/gdb.rst > new file mode 100644 > index 00000000000..18d97857ce1 > --- /dev/null > +++ b/doc/develop/gdb.rst > @@ -0,0 +1,154 @@ > +.. SPDX-License-Identifier: GPL-2.0+ > +.. Copyright (c) 2024 Alexander Dahl > + > +Debugging U-Boot with gdb > +========================= > + > +Using a JTAG adapter it is possible to debug a running U-Boot with gdb. > +A common way is to connect a debug adapter to the JTAG connector of your > +board, run gdbserver, connect gdb to gdbserver, and use gdb as usual. > + > +Preparing build > +--------------- > + > +Building U-Boot with debug symbols and without optimizations is > +recommended for easier debugging:: > + > + CONFIG_CC_OPTIMIZE_FOR_DEBUG=y > + > +Otherwise build, install, and run U-Boot as usual. > + > +Using OpenOCD as GDB server > +--------------------------- > + > +[OpenOCD]_ is a FOSS tool supporting hardware debug probes, and > +providing a GDB interface. > +It is readily available in major Linux distributions or you can build it > +from source. > +Example for starting OpenOCD from Debian with a J-Link adapter and a > +board using an AT91 SAMA5D2 SoC: > + > +.. code-block:: console > + > + % openocd -f interface/jlink.cfg -f target/at91sama5d2.cfg -c 'adapter speed 4000' > + Open On-Chip Debugger 0.12.0 > + Licensed under GNU GPL v2 > + For bug reports, read > + http://openocd.org/doc/doxygen/bugs.html > + Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'. > + adapter speed: 4000 kHz > + > + Info : Listening on port 6666 for tcl connections > + Info : Listening on port 4444 for telnet connections > + Info : J-Link V10 compiled Jan 30 2023 11:28:07 > + Info : Hardware version: 10.10 > + Info : VTarget = 3.244 V > + Info : clock speed 4000 kHz > + Info : JTAG tap: at91sama5d2.cpu tap/device found: 0x5ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x5) > + Info : at91sama5d2.cpu_a5.0: hardware has 3 breakpoints, 2 watchpoints > + Info : at91sama5d2.cpu_a5.0: MPIDR level2 0, cluster 0, core 0, mono core, no SMT > + Info : starting gdb server for at91sama5d2.cpu_a5.0 on 3333 > + Info : Listening on port 3333 for gdb connections > + > +Notice the port 3333 the OpenOCD server is listening on for gdb > +connections. > + > +Running a gdb session > +---------------------- > + > +You need a gdb suited for your target. > +This can be gdb coming with your toolchain or *gdb-multiarch* available > +in your Linux distribution. > + > +.. code-block:: console > + > + % gdb-multiarch u-boot > + GNU gdb (Debian 13.1-3) 13.1 > + Copyright (C) 2023 Free Software Foundation, Inc. > + License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> > + This is free software: you are free to change and redistribute it. > + There is NO WARRANTY, to the extent permitted by law. > + Type "show copying" and "show warranty" for details. > + This GDB was configured as "x86_64-linux-gnu". > + Type "show configuration" for configuration details. > + For bug reporting instructions, please see: > + <https://www.gnu.org/software/gdb/bugs/>. > + Find the GDB manual and other documentation resources online at: > + <http://www.gnu.org/software/gdb/documentation/>. > + > + For help, type "help". > + Type "apropos word" to search for commands related to "word"... > + Reading symbols from u-boot... > + (gdb) > + > +Notice in the above command-line *u-boot* is the binary file from your > +build folder, for which you might need to adapt the path when calling > +gdb. > + > +Connect to the gdb server then: Thank you for this helpful document. Please add: .. code-block:: bash gdb-multiarch u-boot -ex 'target remote localhost:3333' Please, mention that the same debug port can be exposed on QEMU with parameter '-gdb tcp::3333', e.g. qemu-system-riscv64 -M virt -nographic -gdb tcp::3333 -kernel u-boot > + > +.. code-block:: console > + > + (gdb) target extended-remote :3333 > + Remote debugging using :3333 > + 0x27fa9ac6 in ?? () > + (gdb) > + > +This is fine for running before U-Boot relocates itself. > +For debugging U-Boot after relocation you need to tell gdb. > +You can get the relocation address from U-Boot shell with the command > +*bdinfo* like this: Please, consider that often users want to debug drivers after relocation but before reaching the command line. On most architectures (not sandbox, x86) gd is stored in a fixed register. See arch/*/include/asm/global_data.h. arc: r25 arm: r9 arm64: x18 m68k: d7 microblaze: r31 mips: k0 nios2: gp powerpc: r2 riscv: gp sh: r13 You can use (on RISC-V) .. code-block:: console (gdb) p/x (*(struct global_data*)$gp)->relocaddr $1 = 0x8771e000 to show the relocation address. Best regards Heinrich > + > +.. code-block:: console > + > + U-Boot> bdinfo > + boot_params = 0x20000100 > + DRAM bank = 0x00000000 > + -> start = 0x20000000 > + -> size = 0x08000000 > + flashstart = 0x00000000 > + flashsize = 0x00000000 > + flashoffset = 0x00000000 > + baudrate = 115200 bps > + relocaddr = 0x27f7a000 > + reloc off = 0x0607a000 > + Build = 32-bit > + current eth = ethernet@f8008000 > + ethaddr = 00:50:c2:31:58:d4 > + IP addr = <NULL> > + fdt_blob = 0x27b36060 > + new_fdt = 0x27b36060 > + fdt_size = 0x00003e40 > + lmb_dump_all: > + memory.cnt = 0x1 / max = 0x10 > + memory[0] [0x20000000-0x27ffffff], 0x08000000 bytes flags: 0 > + reserved.cnt = 0x1 / max = 0x10 > + reserved[0] [0x27b31d00-0x27ffffff], 0x004ce300 bytes flags: 0 > + devicetree = separate > + arch_number = 0x00000000 > + TLB addr = 0x27ff0000 > + irq_sp = 0x27b36050 > + sp start = 0x27b36040 > + Early malloc usage: cd8 / 2000 > + > +Look out for the line starting with *relocaddr* which has the address > +you need, ``0x27f7a000`` in this case. > +In gdb shell discard the previously loaded symbol file and add it once > +again with that relocation address like this: > + > +.. code-block:: console > + > + (gdb) symbol-file > + Discard symbol table from `/home/adahl/build/u-boot/v2024.04.x/u-boot'? (y or n) y > + No symbol file now. > + (gdb) add-symbol-file u-boot 0x27f7a000 > + add symbol table from file "u-boot" at > + .text_addr = 0x27f7a000 > + (y or n) y > + Reading symbols from u-boot... > + (gdb) > + > +You can now use gdb as usual, setting breakpoints, printing backtraces, > +inspecting variables, stepping through the code, etc. > + > +.. [OpenOCD] https://openocd.org/ > diff --git a/doc/develop/index.rst b/doc/develop/index.rst > index f82e148b101..f9c4bf839ee 100644 > --- a/doc/develop/index.rst > +++ b/doc/develop/index.rst > @@ -60,6 +60,7 @@ Debugging > :maxdepth: 1 > > crash_dumps > + gdb > trace > > Packaging > > base-commit: a7eada24327a40f7ef6c55c220e119839c9d4227
diff --git a/doc/develop/gdb.rst b/doc/develop/gdb.rst new file mode 100644 index 00000000000..18d97857ce1 --- /dev/null +++ b/doc/develop/gdb.rst @@ -0,0 +1,154 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2024 Alexander Dahl + +Debugging U-Boot with gdb +========================= + +Using a JTAG adapter it is possible to debug a running U-Boot with gdb. +A common way is to connect a debug adapter to the JTAG connector of your +board, run gdbserver, connect gdb to gdbserver, and use gdb as usual. + +Preparing build +--------------- + +Building U-Boot with debug symbols and without optimizations is +recommended for easier debugging:: + + CONFIG_CC_OPTIMIZE_FOR_DEBUG=y + +Otherwise build, install, and run U-Boot as usual. + +Using OpenOCD as GDB server +--------------------------- + +[OpenOCD]_ is a FOSS tool supporting hardware debug probes, and +providing a GDB interface. +It is readily available in major Linux distributions or you can build it +from source. +Example for starting OpenOCD from Debian with a J-Link adapter and a +board using an AT91 SAMA5D2 SoC: + +.. code-block:: console + + % openocd -f interface/jlink.cfg -f target/at91sama5d2.cfg -c 'adapter speed 4000' + Open On-Chip Debugger 0.12.0 + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'. + adapter speed: 4000 kHz + + Info : Listening on port 6666 for tcl connections + Info : Listening on port 4444 for telnet connections + Info : J-Link V10 compiled Jan 30 2023 11:28:07 + Info : Hardware version: 10.10 + Info : VTarget = 3.244 V + Info : clock speed 4000 kHz + Info : JTAG tap: at91sama5d2.cpu tap/device found: 0x5ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x5) + Info : at91sama5d2.cpu_a5.0: hardware has 3 breakpoints, 2 watchpoints + Info : at91sama5d2.cpu_a5.0: MPIDR level2 0, cluster 0, core 0, mono core, no SMT + Info : starting gdb server for at91sama5d2.cpu_a5.0 on 3333 + Info : Listening on port 3333 for gdb connections + +Notice the port 3333 the OpenOCD server is listening on for gdb +connections. + +Running a gdb session +---------------------- + +You need a gdb suited for your target. +This can be gdb coming with your toolchain or *gdb-multiarch* available +in your Linux distribution. + +.. code-block:: console + + % gdb-multiarch u-boot + GNU gdb (Debian 13.1-3) 13.1 + Copyright (C) 2023 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + Type "show copying" and "show warranty" for details. + This GDB was configured as "x86_64-linux-gnu". + Type "show configuration" for configuration details. + For bug reporting instructions, please see: + <https://www.gnu.org/software/gdb/bugs/>. + Find the GDB manual and other documentation resources online at: + <http://www.gnu.org/software/gdb/documentation/>. + + For help, type "help". + Type "apropos word" to search for commands related to "word"... + Reading symbols from u-boot... + (gdb) + +Notice in the above command-line *u-boot* is the binary file from your +build folder, for which you might need to adapt the path when calling +gdb. + +Connect to the gdb server then: + +.. code-block:: console + + (gdb) target extended-remote :3333 + Remote debugging using :3333 + 0x27fa9ac6 in ?? () + (gdb) + +This is fine for running before U-Boot relocates itself. +For debugging U-Boot after relocation you need to tell gdb. +You can get the relocation address from U-Boot shell with the command +*bdinfo* like this: + +.. code-block:: console + + U-Boot> bdinfo + boot_params = 0x20000100 + DRAM bank = 0x00000000 + -> start = 0x20000000 + -> size = 0x08000000 + flashstart = 0x00000000 + flashsize = 0x00000000 + flashoffset = 0x00000000 + baudrate = 115200 bps + relocaddr = 0x27f7a000 + reloc off = 0x0607a000 + Build = 32-bit + current eth = ethernet@f8008000 + ethaddr = 00:50:c2:31:58:d4 + IP addr = <NULL> + fdt_blob = 0x27b36060 + new_fdt = 0x27b36060 + fdt_size = 0x00003e40 + lmb_dump_all: + memory.cnt = 0x1 / max = 0x10 + memory[0] [0x20000000-0x27ffffff], 0x08000000 bytes flags: 0 + reserved.cnt = 0x1 / max = 0x10 + reserved[0] [0x27b31d00-0x27ffffff], 0x004ce300 bytes flags: 0 + devicetree = separate + arch_number = 0x00000000 + TLB addr = 0x27ff0000 + irq_sp = 0x27b36050 + sp start = 0x27b36040 + Early malloc usage: cd8 / 2000 + +Look out for the line starting with *relocaddr* which has the address +you need, ``0x27f7a000`` in this case. +In gdb shell discard the previously loaded symbol file and add it once +again with that relocation address like this: + +.. code-block:: console + + (gdb) symbol-file + Discard symbol table from `/home/adahl/build/u-boot/v2024.04.x/u-boot'? (y or n) y + No symbol file now. + (gdb) add-symbol-file u-boot 0x27f7a000 + add symbol table from file "u-boot" at + .text_addr = 0x27f7a000 + (y or n) y + Reading symbols from u-boot... + (gdb) + +You can now use gdb as usual, setting breakpoints, printing backtraces, +inspecting variables, stepping through the code, etc. + +.. [OpenOCD] https://openocd.org/ diff --git a/doc/develop/index.rst b/doc/develop/index.rst index f82e148b101..f9c4bf839ee 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -60,6 +60,7 @@ Debugging :maxdepth: 1 crash_dumps + gdb trace Packaging
Mashed up from different sources linked below, including the now gone Wiki and doc/README.arm-relocation file. Tested on a custom board with AT91 SAMA5D2 SoC and Segger J-Link Base adapter. This is only generic advice here, the usage is not board specific. Some board docs have more specific instructions on using gdb with a particular board. Link: https://www.slideshare.net/slideshow/embedded-recipes-2019-introduction-to-jtag-debugging/177511981 Link: https://boundarydevices.com/debugging-using-segger-j-link-jtag/ Link: https://web.archive.org/web/20141224200032/http://www.denx.de/wiki/view/DULG/DebuggingUBoot Link: https://web.archive.org/web/20141206064148/http://www.denx.de/wiki/view/DULG/GDBScripts1 Suggested-by: Marek Vasut <marex@denx.de> Signed-off-by: Alexander Dahl <ada@thorsis.com> --- doc/develop/gdb.rst | 154 ++++++++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 155 insertions(+) create mode 100644 doc/develop/gdb.rst base-commit: a7eada24327a40f7ef6c55c220e119839c9d4227