| .. _gdbstub: |
| |
| GDB stub |
| ######## |
| |
| .. contents:: |
| :local: |
| :depth: 2 |
| |
| Overview |
| ******** |
| |
| The gdbstub feature provides an implementation of the GDB Remote |
| Serial Protocol (RSP) that allows you to remotely debug Zephyr |
| using GDB. |
| |
| The protocol supports different connection types: serial, UDP/IP and |
| TCP/IP. Zephyr currently supports only serial device communication. |
| |
| The GDB program acts as a client while the Zephyr gdbstub acts as a |
| server. When this feature is enabled, Zephyr stops its execution after |
| :c:func:`gdb_init` starts gdbstub service and waits for a GDB |
| connection. Once a connection is established it is possible to |
| synchronously interact with Zephyr. Note that currently it is not |
| possible to asynchronously send commands to the target. |
| |
| Features |
| ******** |
| |
| The following features are supported: |
| |
| * Add and remove breakpoints |
| * Continue and step the target |
| * Print backtrace |
| * Read or write general registers |
| * Read or write the memory |
| |
| Enabling GDB Stub |
| ***************** |
| |
| GDB stub can be enabled with the :kconfig:option:`CONFIG_GDBSTUB` option. |
| |
| Using Serial Backend |
| ==================== |
| |
| The serial backend for GDB stub can be enabled with |
| the :kconfig:option:`CONFIG_GDBSTUB_SERIAL_BACKEND` option. |
| |
| Since serial backend utilizes UART devices to send and receive GDB commands, |
| |
| * If there are spare UART devices on the board, set ``zephyr,gdbstub-uart`` |
| property of the chosen node to the spare UART device so that :c:func:`printk` |
| and log messages are not being printed to the same UART device used for GDB. |
| |
| * For boards with only one UART device, :c:func:`printk` and logging |
| must be disabled if they are also using the same UART device for output. |
| GDB related messages may interleave with log messages which may have |
| unintended consequences. Usually this can be done by disabling |
| :kconfig:option:`CONFIG_PRINTK` and :kconfig:option:`CONFIG_LOG`. |
| |
| Debugging |
| ********* |
| |
| Using Serial Backend |
| ==================== |
| |
| #. Build with GDB stub and serial backend enabled. |
| |
| #. Flash built image onto board and reset the board. |
| |
| * Execution should now be paused at :c:func:`gdb_init`. |
| |
| #. Execute GDB on development machine and connect to the GDB stub. |
| |
| .. code-block:: bash |
| |
| target remote <serial device> |
| |
| For example, |
| |
| .. code-block:: bash |
| |
| target remote /dev/ttyUSB1 |
| |
| #. GDB commands can be used to start debugging. |
| |
| Example |
| ******* |
| |
| There is a test application :zephyr_file:`tests/subsys/debug/gdbstub` with one of its |
| test cases ``debug.gdbstub.breakpoints`` demonstrating how the Zephyr GDB stub can be used. |
| The test also has a case to connect to the QEMU's GDB stub implementation (at a custom |
| port ``tcp:1235``) as a reference to validate the test script itself. |
| |
| Run the test with the following command from your :envvar:`ZEPHYR_BASE` directory: |
| |
| .. code-block:: console |
| |
| ./scripts/twister -p qemu_x86 -T tests/subsys/debug/gdbstub |
| |
| The test should run successfully, and now let's do something similar step-by-step |
| to demonstrate how the Zephyr GDB stub works from the GDB user's perspective. |
| |
| In the snippets below use and expect your appropriate directories instead of |
| ``<SDK install directory>``, ``<build_directory>``, ``<ZEPHYR_BASE>``. |
| |
| |
| #. Open two terminal windows. |
| |
| #. On the first terminal, build and run the test application: |
| |
| .. zephyr-app-commands:: |
| :zephyr-app: tests/subsys/debug/gdbstub |
| :host-os: unix |
| :board: qemu_x86 |
| :gen-args: '-DCONFIG_QEMU_EXTRA_FLAGS="-serial tcp:localhost:5678,server"' |
| :goals: build run |
| |
| Note how we set :kconfig:option:`CONFIG_QEMU_EXTRA_FLAGS` to direct QEMU serial |
| console port to the ``localhost`` TCP port ``5678`` to wait for a connection |
| from the GDB ``remote`` command we are going to do on the next steps. |
| |
| #. On the second terminal, start GDB: |
| |
| .. code-block:: bash |
| |
| <SDK install directory>/x86_64-zephyr-elf/bin/x86_64-zephyr-elf-gdb |
| |
| #. Tell GDB where to look for the built ELF file: |
| |
| .. code-block:: text |
| |
| (gdb) symbol-file <build directory>/zephyr/zephyr.elf |
| |
| Response from GDB: |
| |
| .. code-block:: text |
| |
| Reading symbols from <build directory>/zephyr/zephyr.elf... |
| |
| #. Tell GDB to connect to the Zephyr gdbstub serial backend which is exposed |
| earlier as a server through the TCP port ``-serial`` redirection at QEMU. |
| |
| .. code-block:: text |
| |
| (gdb) target remote localhost:5678 |
| |
| Response from GDB: |
| |
| .. code-block:: text |
| |
| Remote debugging using localhost:5678 |
| arch_gdb_init () at <ZEPHYR_BASE>/arch/x86/core/ia32/gdbstub.c:252 |
| 252 } |
| |
| GDB also shows where the code execution is stopped. In this case, |
| it is at :zephyr_file:`arch/x86/core/ia32/gdbstub.c`, line 252. |
| |
| #. Use command ``bt`` or ``backtrace`` to show the backtrace of stack frames. |
| |
| .. code-block:: text |
| |
| (gdb) bt |
| #0 arch_gdb_init () at <ZEPHYR_BASE>/arch/x86/core/ia32/gdbstub.c:252 |
| #1 0x00104140 in gdb_init () at <ZEPHYR_BASE>/zephyr/subsys/debug/gdbstub.c:852 |
| #2 0x00109c13 in z_sys_init_run_level (level=INIT_LEVEL_PRE_KERNEL_2) at <ZEPHYR_BASE>/kernel/init.c:360 |
| #3 0x00109e73 in z_cstart () at <ZEPHYR_BASE>/kernel/init.c:630 |
| #4 0x00104422 in z_prep_c (arg=0x1245bc <x86_cpu_boot_arg>) at <ZEPHYR_BASE>/arch/x86/core/prep_c.c:80 |
| #5 0x001000c9 in __csSet () at <ZEPHYR_BASE>/arch/x86/core/ia32/crt0.S:290 |
| #6 0x001245bc in uart_dev () |
| #7 0x00134988 in z_interrupt_stacks () |
| #8 0x00000000 in ?? () |
| |
| #. Use command ``list`` to show the source code and surroundings where |
| code execution is stopped. |
| |
| .. code-block:: text |
| |
| (gdb) list |
| 247 __asm__ volatile ("int3"); |
| 248 |
| 249 #ifdef CONFIG_GDBSTUB_TRACE |
| 250 printk("gdbstub:%s GDB is connected\n", __func__); |
| 251 #endif |
| 252 } |
| 253 |
| 254 /* Hook current IDT. */ |
| 255 _EXCEPTION_CONNECT_NOCODE(z_gdb_debug_isr, IV_DEBUG, 3); |
| 256 _EXCEPTION_CONNECT_NOCODE(z_gdb_break_isr, IV_BREAKPOINT, 3); |
| |
| #. Use command ``s`` or ``step`` to step through program until it reaches |
| a different source line. Now that it finished executing :c:func:`arch_gdb_init` |
| and is continuing in :c:func:`gdb_init`. |
| |
| .. code-block:: text |
| |
| (gdb) s |
| gdb_init () at <ZEPHYR_BASE>/subsys/debug/gdbstub.c:857 |
| 857 return 0; |
| |
| .. code-block:: text |
| |
| (gdb) list |
| 852 arch_gdb_init(); |
| 853 |
| 854 #ifdef CONFIG_GDBSTUB_TRACE |
| 855 printk("gdbstub:%s exit\n", __func__); |
| 856 #endif |
| 857 return 0; |
| 858 } |
| 859 |
| 860 #ifdef CONFIG_XTENSA |
| 861 /* |
| |
| #. Use command ``br`` or ``break`` to setup a breakpoint. For this example |
| set up a breakpoint at :c:func:`main`, and let code execution continue |
| without any intervention using command ``c`` (or ``continue``). |
| |
| .. code-block:: text |
| |
| (gdb) break main |
| Breakpoint 1 at 0x10064d: file <ZEPHYR_BASE>/tests/subsys/debug/gdbstub/src/main.c, line 27. |
| |
| .. code-block:: text |
| |
| (gdb) continue |
| Continuing. |
| |
| Once code execution reaches :c:func:`main`, execution will be stopped |
| and GDB prompt returns. |
| |
| .. code-block:: text |
| |
| Breakpoint 1, main () at <ZEPHYR_BASE>/tests/subsys/debug/gdbstub/src/main.c:27 |
| 27 printk("%s():enter\n", __func__); |
| |
| Now GDB is waiting at the beginning of :c:func:`main`: |
| |
| .. code-block:: text |
| |
| (gdb) list |
| 22 |
| 23 int main(void) |
| 24 { |
| 25 int ret; |
| 26 |
| 27 printk("%s():enter\n", __func__); |
| 28 ret = test(); |
| 29 printk("ret=%d\n", ret); |
| 30 return 0; |
| 31 } |
| |
| #. To examine the value of ``ret``, the command ``p`` or ``print`` |
| can be used. |
| |
| .. code-block:: text |
| |
| (gdb) p ret |
| $1 = 1273788 |
| |
| Since ``ret`` has not been initialized, it contains some random value. |
| |
| #. If step (``s`` or ``step``) is used here, it will continue execution |
| skipping the interior of :c:func:`test`. |
| To examine code execution inside :c:func:`test`, |
| a breakpoint can be set for :c:func:`test`, or simply using |
| ``si`` (or ``stepi``) to execute one machine instruction, where it has |
| the side effect of going into the function. The GDB command ``finish`` |
| can be used to continue execution without intervention until the function |
| returns. |
| |
| .. code-block:: text |
| |
| (gdb) finish |
| Run till exit from #0 test () at <ZEPHYR_BASE>/tests/subsys/debug/gdbstub/src/main.c:17 |
| 0x00100667 in main () at <ZEPHYR_BASE>/tests/subsys/debug/gdbstub/src/main.c:28 |
| 28 ret = test(); |
| Value returned is $2 = 30 |
| |
| #. Examine ``ret`` again which should have the return value from |
| :c:func:`test`. Sometimes, the assignment is not done until another |
| ``step`` is issued, as in this case. This is due to the assignment |
| code is done after returning from function. The assignment code is |
| generated by the toolchain as machine instructions which are not |
| visible when viewing the corresponding C source file. |
| |
| .. code-block:: text |
| |
| (gdb) p ret |
| $3 = 1273788 |
| (gdb) step |
| 29 printk("ret=%d\n", ret); |
| (gdb) p ret |
| $4 = 30 |
| |
| #. If ``continue`` is issued here, code execution will continue indefinitely |
| as there are no breakpoints to further stop execution. Breaking execution |
| in GDB via :kbd:`Ctrl-C` does not currently work as the Zephyr gdbstub does |
| not support this functionality yet. Switch to the first console with QEMU |
| running the Zephyr image and stop it manually with :kbd:`Ctrl+a x`. |
| When the same test is executed by Twister, it automatically takes care of |
| stopping the QEMU instance. |
