services/debugging/gdbstub.html · services/debugging/gdbstub.rst 공식 원문 ↗

Zephyr 3.7.0 · Debugging

GDB Stub

Zephyr가 GDB RSP server가 되어 breakpoint, register, memory와 stack을 원격으로 제어합니다.

Official pathservices/debugging/gdbstub.html
Source fileservices/debugging/gdbstub.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

UART 분리 조건, QEMU TCP redirection과 GDB command 흐름을 실제 output 20개와 함께 보존합니다.

Protocol

GDB RSP

Backend

Serial UART

Commands

break · step · bt

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 2EDA2D8DDEE0EA049AB2581EC94FAC7AE9337716B0F57DA920C61AB62F315E7D
.. _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.

Part 3

한국어 전문 번역

개요

GDB stub은 GDB Remote Serial Protocol(RSP)을 구현해 GDB에서 Zephyr를 원격 debug할 수 있게 합니다.

Protocol은 serial, UDP/IP와 TCP/IP connection을 지원하지만 현재 Zephyr는 serial device communication만 지원합니다.

GDB program은 client이고 Zephyr gdbstub은 server입니다. 기능을 enable하면 gdb_init이 service를 시작한 뒤 Zephyr 실행을 멈추고 GDB connection을 기다립니다. 연결되면 Zephyr와 synchronous하게 상호 작용할 수 있습니다. 현재 target에 asynchronous command를 보내는 기능은 지원하지 않습니다.

기능

  • Breakpoint 추가와 제거
  • Target continue와 single-step
  • Backtrace 출력
  • General register 읽기와 쓰기
  • Memory 읽기와 쓰기

GDB Stub enable

CONFIG_GDBSTUB option으로 GDB stub을 enable합니다.

Serial backend 사용

CONFIG_GDBSTUB_SERIAL_BACKEND option으로 serial backend를 enable합니다. 이 backend는 UART device로 GDB command를 송수신합니다.

  • Board에 여분 UART가 있다면 chosen node의 zephyr,gdbstub-uart property를 해당 UART로 설정해 printk와 log message가 GDB용 UART에 출력되지 않게 합니다.
  • UART가 하나뿐이고 printk와 logging이 같은 UART를 사용한다면 둘을 disable해야 합니다. GDB message와 log가 섞이면 의도하지 않은 결과가 생길 수 있습니다. 보통 CONFIG_PRINTK와 CONFIG_LOG를 disable합니다.

Debugging

Serial backend 사용

  1. GDB stub과 serial backend를 enable해 build합니다.
  2. Build한 image를 board에 flash하고 reset합니다. 실행은 gdb_init에서 멈춰야 합니다.
  3. Development machine에서 GDB를 실행하고 GDB stub에 연결합니다.
    target remote <serial device>

    예:

    target remote /dev/ttyUSB1
  4. GDB command로 debugging을 시작합니다.

예제

Test application tests/subsys/debug/gdbstub의 debug.gdbstub.breakpoints test case가 Zephyr GDB stub 사용법을 보여 줍니다. Test script 자체를 검증하기 위한 reference로 custom port tcp:1235의 QEMU GDB stub에 연결하는 case도 있습니다.

ZEPHYR_BASE directory에서 다음 command로 test를 실행합니다.

./scripts/twister -p qemu_x86 -T tests/subsys/debug/gdbstub

Test가 성공하면 아래 절차로 GDB 사용자 관점에서 같은 흐름을 직접 확인할 수 있습니다. 예제의 <SDK install directory>, <build directory>, <ZEPHYR_BASE>는 실제 directory로 바꿉니다.

  1. Terminal window 두 개를 엽니다.
  2. 첫 terminal에서 test application을 build하고 실행합니다.
    # From the root of the zephyr repository
    west build -b qemu_x86 tests/subsys/debug/gdbstub -- '-DCONFIG_QEMU_EXTRA_FLAGS="-serial tcp:localhost:5678,server"'
    west build -t run

    CONFIG_QEMU_EXTRA_FLAGS가 QEMU serial console을 localhost:5678 TCP port로 redirect해 다음 단계의 GDB remote connection을 기다리게 합니다.

  3. 두 번째 terminal에서 GDB를 시작합니다.
    <SDK install directory>/x86_64-zephyr-elf/bin/x86_64-zephyr-elf-gdb
    1. Build한 ELF file 위치를 GDB에 알려 줍니다.
      (gdb) symbol-file <build directory>/zephyr/zephyr.elf

      응답:

      Reading symbols from <build directory>/zephyr/zephyr.elf...
    2. QEMU의 -serial redirect로 노출한 Zephyr gdbstub serial backend에 연결합니다.
      (gdb) target remote localhost:5678

      응답:

      Remote debugging using localhost:5678
      arch_gdb_init () at <ZEPHYR_BASE>/arch/x86/core/ia32/gdbstub.c:252
      252     }

      GDB는 실행이 멈춘 위치도 표시합니다. 이 예에서는 arch/x86/core/ia32/gdbstub.c 252행입니다.

    3. bt 또는 backtrace로 stack frame backtrace를 봅니다.
      (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 ?? ()
    4. list로 현재 실행 위치 주변 source를 봅니다.
      (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);
    5. s 또는 step으로 다른 source line까지 진행합니다. arch_gdb_init을 끝내고 gdb_init으로 이동합니다.
      (gdb) s
      gdb_init () at <ZEPHYR_BASE>/subsys/debug/gdbstub.c:857
      857     return 0;
      (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     /*
    6. br 또는 break로 main에 breakpoint를 설정하고 c 또는 continue로 실행합니다.
      (gdb) break main
      Breakpoint 1 at 0x10064d: file <ZEPHYR_BASE>/tests/subsys/debug/gdbstub/src/main.c, line 27.
      (gdb) continue
      Continuing.

      실행이 main에 도달하면 멈추고 GDB prompt가 돌아옵니다.

      Breakpoint 1, main () at <ZEPHYR_BASE>/tests/subsys/debug/gdbstub/src/main.c:27
      27              printk("%s():enter\n", __func__);

      GDB는 main 시작에서 대기합니다.

      (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      }
    7. p 또는 print로 ret 값을 조사합니다.
      (gdb) p ret
      $1 = 1273788

      ret이 아직 초기화되지 않아 임의 값이 들어 있습니다.

    8. 여기서 s나 step을 쓰면 test 내부를 건너뛸 수 있습니다. 내부를 보려면 test에 breakpoint를 두거나 si/stepi로 machine instruction 하나를 실행합니다. finish는 현재 function이 return할 때까지 실행합니다.
      (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
    9. ret을 다시 확인합니다. Function return 뒤 assignment machine instruction이 실행되어야 값이 반영되므로 이 예처럼 step이 한 번 더 필요할 수 있습니다.
      (gdb) p ret
      $3 = 1273788
      (gdb) step
      29              printk("ret=%d\n", ret);
      (gdb) p ret
      $4 = 30

여기서 continue하면 추가 breakpoint가 없어 실행이 계속됩니다. Zephyr gdbstub은 아직 GDB의 Ctrl-C 중단을 지원하지 않습니다. QEMU terminal로 전환해 Ctrl+a x로 직접 멈춰야 합니다. Twister가 같은 test를 실행할 때는 QEMU 종료를 자동으로 처리합니다.

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.