From 6d9ed994aa26f11d543a50fab3bdb4ec94d08dcd Mon Sep 17 00:00:00 2001 From: Anas Nashif Date: Sat, 7 Jan 2017 13:22:21 -0500 Subject: build: use target 'debugserver' for Qemu debugging Use the existing debugserver target also for Qemu debugging. Qemu should be maintained as one of many emulation/simulations platforms and emulation should be abstracted in the Makefiles and not tied to Qemu. qemugdb will still work, it is however being deprecated. Change-Id: I0cd10fb66debb939b8f7f1304bf2ef4605da6a1d Signed-off-by: Anas Nashif --- Makefile | 14 +++-- Makefile.inc | 10 ++-- boards/arc/arduino_101_sss/Makefile.board | 2 + .../arc/quark_se_c1000_ss_devboard/Makefile.board | 1 + boards/arm/frdm_k64f/Makefile.board | 1 + boards/arm/nucleo_f103rb/Makefile.board | 1 + boards/arm/nucleo_f411re/Makefile.board | 1 + boards/arm/qemu_cortex_m3/Makefile.board | 5 ++ boards/nios2/altera_max10/Makefile.board | 1 + boards/nios2/qemu_nios2/Makefile.board | 5 +- boards/x86/arduino_101/Makefile.board | 1 + boards/x86/qemu_x86/Makefile.board | 5 ++ boards/x86/quark_d2000_crb/Makefile.board | 1 + boards/x86/quark_se_c1000_devboard/Makefile.board | 1 + doc/application/application.rst | 62 ++++++++++++---------- scripts/support/qemu.sh | 16 ++++++ 16 files changed, 89 insertions(+), 38 deletions(-) create mode 100644 boards/arm/qemu_cortex_m3/Makefile.board create mode 100644 boards/x86/qemu_x86/Makefile.board create mode 100755 scripts/support/qemu.sh diff --git a/Makefile b/Makefile index 0ed598b5f..fc3aa450d 100644 --- a/Makefile +++ b/Makefile @@ -1138,6 +1138,7 @@ help: @echo ' qemugdb - Same as 'qemu' but start a GDB server on port 1234' @echo ' flash - Build and flash an application' @echo ' debug - Build and debug an application using GDB' + @echo ' debugserver - Build and start a GDB server (port 1234 for Qemu targets)' @echo ' ram_report - Build and create RAM usage report' @echo ' rom_report - Build and create ROM usage report' @echo '' @@ -1256,22 +1257,25 @@ qemu: zephyr $(if $(CONFIG_X86_IAMCU),python $(ZEPHYR_BASE)/scripts/qemu-machine-hack.py $(KERNEL_ELF_NAME)) $(Q)$(QEMU) $(QEMU_FLAGS) $(QEMU_EXTRA_FLAGS) -kernel $(KERNEL_ELF_NAME) -qemugdb: QEMU_EXTRA_FLAGS += -s -S -qemugdb: qemu +# FIXME: Deprecated +qemugdb: debugserver -include $(srctree)/boards/$(ARCH)/$(BOARD_NAME)/Makefile.board ifneq ($(FLASH_SCRIPT),) flash: zephyr @echo "Flashing $(BOARD_NAME)" $(Q)$(CONFIG_SHELL) $(srctree)/scripts/support/$(FLASH_SCRIPT) flash - -debug: zephyr - $(Q)$(CONFIG_SHELL) $(srctree)/scripts/support/$(FLASH_SCRIPT) debug else flash: FORCE @echo Flashing not supported with this board. @echo Please check the documentation for alternate instructions. +endif +ifneq ($(DEBUG_SCRIPT),) +debug: zephyr + $(Q)$(CONFIG_SHELL) $(srctree)/scripts/support/$(DEBUG_SCRIPT) debug + +else debug: FORCE @echo Debugging not supported with this board. @echo Please check the documentation for alternate instructions. diff --git a/Makefile.inc b/Makefile.inc index 0feaaa8a4..4ebb4ea23 100644 --- a/Makefile.inc +++ b/Makefile.inc @@ -83,18 +83,19 @@ all: $(DOTCONFIG) ifeq ($(findstring qemu_,$(BOARD)),) qemu: - @echo "Emulation not available for this platform" + @echo "Emulation not available for this board." qemugdb: qemu else qemu: $(DOTCONFIG) $(Q)$(call zephyrmake,$(O),$@) -qemugdb: $(DOTCONFIG) - $(Q)$(call zephyrmake,$(O),$@) +qemugdb: debugserver + @echo "This target is deprecated, please use debugserver instead" endif debug: $(DOTCONFIG) $(Q)$(call zephyrmake,$(O),$@) + flash: $(DOTCONFIG) $(Q)$(call zephyrmake,$(O),$@) @@ -105,8 +106,9 @@ ARCH = $(notdir $(subst /$(BOARD),,$(wildcard $(ZEPHYR_BASE)/boards/*/$(BOARD))) BOARD_NAME = $(BOARD) export BOARD_NAME endif + debugserver: FORCE - $(Q)$(CONFIG_SHELL) $(ZEPHYR_BASE)/scripts/support/$(FLASH_SCRIPT) debugserver + $(Q)$(CONFIG_SHELL) $(ZEPHYR_BASE)/scripts/support/$(DEBUG_SCRIPT) debugserver initconfig outputexports: $(DOTCONFIG) diff --git a/boards/arc/arduino_101_sss/Makefile.board b/boards/arc/arduino_101_sss/Makefile.board index d2e80b981..6d09ebb1f 100644 --- a/boards/arc/arduino_101_sss/Makefile.board +++ b/boards/arc/arduino_101_sss/Makefile.board @@ -1,4 +1,6 @@ FLASH_SCRIPT = openocd.sh +DEBUG_SCRIPT = openocd.sh + OPENOCD_PRE_CMD = "-c targets 1" OPENOCD_LOAD_CMD = "load_image ${O}/${KERNEL_BIN_NAME} $(CONFIG_FLASH_BASE_ADDRESS)" OPENOCD_VERIFY_CMD = "verify_image ${O}/${KERNEL_BIN_NAME} $(CONFIG_FLASH_BASE_ADDRESS)" diff --git a/boards/arc/quark_se_c1000_ss_devboard/Makefile.board b/boards/arc/quark_se_c1000_ss_devboard/Makefile.board index 5c7a11f60..2c7ad79a9 100644 --- a/boards/arc/quark_se_c1000_ss_devboard/Makefile.board +++ b/boards/arc/quark_se_c1000_ss_devboard/Makefile.board @@ -1,4 +1,5 @@ FLASH_SCRIPT = openocd.sh +DEBUG_SCRIPT = openocd.sh OPENOCD_PRE_CMD = "-c targets 1" OPENOCD_LOAD_CMD = "load_image ${O}/${KERNEL_BIN_NAME} $(CONFIG_FLASH_BASE_ADDRESS)" OPENOCD_VERIFY_CMD = "verify_image ${O}/${KERNEL_BIN_NAME} $(CONFIG_FLASH_BASE_ADDRESS)" diff --git a/boards/arm/frdm_k64f/Makefile.board b/boards/arm/frdm_k64f/Makefile.board index 7d02aa388..e47333183 100644 --- a/boards/arm/frdm_k64f/Makefile.board +++ b/boards/arm/frdm_k64f/Makefile.board @@ -1,4 +1,5 @@ FLASH_SCRIPT = openocd.sh +DEBUG_SCRIPT = openocd.sh OPENOCD_LOAD_CMD = "flash write_image erase ${O}/${KERNEL_BIN_NAME} ${CONFIG_FLASH_BASE_ADDRESS}" OPENOCD_VERIFY_CMD = "verify_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_FLASH_BASE_ADDRESS}" diff --git a/boards/arm/nucleo_f103rb/Makefile.board b/boards/arm/nucleo_f103rb/Makefile.board index 7d02aa388..e47333183 100644 --- a/boards/arm/nucleo_f103rb/Makefile.board +++ b/boards/arm/nucleo_f103rb/Makefile.board @@ -1,4 +1,5 @@ FLASH_SCRIPT = openocd.sh +DEBUG_SCRIPT = openocd.sh OPENOCD_LOAD_CMD = "flash write_image erase ${O}/${KERNEL_BIN_NAME} ${CONFIG_FLASH_BASE_ADDRESS}" OPENOCD_VERIFY_CMD = "verify_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_FLASH_BASE_ADDRESS}" diff --git a/boards/arm/nucleo_f411re/Makefile.board b/boards/arm/nucleo_f411re/Makefile.board index 7d02aa388..e47333183 100644 --- a/boards/arm/nucleo_f411re/Makefile.board +++ b/boards/arm/nucleo_f411re/Makefile.board @@ -1,4 +1,5 @@ FLASH_SCRIPT = openocd.sh +DEBUG_SCRIPT = openocd.sh OPENOCD_LOAD_CMD = "flash write_image erase ${O}/${KERNEL_BIN_NAME} ${CONFIG_FLASH_BASE_ADDRESS}" OPENOCD_VERIFY_CMD = "verify_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_FLASH_BASE_ADDRESS}" diff --git a/boards/arm/qemu_cortex_m3/Makefile.board b/boards/arm/qemu_cortex_m3/Makefile.board new file mode 100644 index 000000000..be023b20f --- /dev/null +++ b/boards/arm/qemu_cortex_m3/Makefile.board @@ -0,0 +1,5 @@ + +DEBUG_SCRIPT = qemu.sh + +debugserver: QEMU_EXTRA_FLAGS += -s -S +debugserver: qemu diff --git a/boards/nios2/altera_max10/Makefile.board b/boards/nios2/altera_max10/Makefile.board index b9bafa5bb..be1867366 100644 --- a/boards/nios2/altera_max10/Makefile.board +++ b/boards/nios2/altera_max10/Makefile.board @@ -1,2 +1,3 @@ FLASH_SCRIPT = nios2.sh +DEBUG_SCRIPT = nios2.sh diff --git a/boards/nios2/qemu_nios2/Makefile.board b/boards/nios2/qemu_nios2/Makefile.board index b9bafa5bb..be023b20f 100644 --- a/boards/nios2/qemu_nios2/Makefile.board +++ b/boards/nios2/qemu_nios2/Makefile.board @@ -1,2 +1,5 @@ -FLASH_SCRIPT = nios2.sh +DEBUG_SCRIPT = qemu.sh + +debugserver: QEMU_EXTRA_FLAGS += -s -S +debugserver: qemu diff --git a/boards/x86/arduino_101/Makefile.board b/boards/x86/arduino_101/Makefile.board index 95d138c5d..f1e40f4e7 100644 --- a/boards/x86/arduino_101/Makefile.board +++ b/boards/x86/arduino_101/Makefile.board @@ -1,4 +1,5 @@ FLASH_SCRIPT = openocd.sh +DEBUG_SCRIPT = openocd.sh OPENOCD_PRE_CMD = "-c targets 1" OPENOCD_LOAD_CMD = "load_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_PHYS_LOAD_ADDR}" OPENOCD_VERIFY_CMD = "verify_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_PHYS_LOAD_ADDR}" diff --git a/boards/x86/qemu_x86/Makefile.board b/boards/x86/qemu_x86/Makefile.board new file mode 100644 index 000000000..be023b20f --- /dev/null +++ b/boards/x86/qemu_x86/Makefile.board @@ -0,0 +1,5 @@ + +DEBUG_SCRIPT = qemu.sh + +debugserver: QEMU_EXTRA_FLAGS += -s -S +debugserver: qemu diff --git a/boards/x86/quark_d2000_crb/Makefile.board b/boards/x86/quark_d2000_crb/Makefile.board index af482d995..a60842004 100644 --- a/boards/x86/quark_d2000_crb/Makefile.board +++ b/boards/x86/quark_d2000_crb/Makefile.board @@ -1,4 +1,5 @@ FLASH_SCRIPT = openocd.sh +DEBUG_SCRIPT = openocd.sh OPENOCD_LOAD_CMD = "load_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_PHYS_LOAD_ADDR}" OPENOCD_VERIFY_CMD = "verify_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_PHYS_LOAD_ADDR}" diff --git a/boards/x86/quark_se_c1000_devboard/Makefile.board b/boards/x86/quark_se_c1000_devboard/Makefile.board index cac65483f..fd6d2f84b 100644 --- a/boards/x86/quark_se_c1000_devboard/Makefile.board +++ b/boards/x86/quark_se_c1000_devboard/Makefile.board @@ -1,4 +1,5 @@ FLASH_SCRIPT = openocd.sh +DEBUG_SCRIPT = openocd.sh OPENOCD_PRE_CMD = "-c targets 1" OPENOCD_LOAD_CMD = "load_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_PHYS_LOAD_ADDR}" OPENOCD_VERIFY_CMD = "verify_image ${O}/${KERNEL_BIN_NAME} ${CONFIG_PHYS_LOAD_ADDR}" diff --git a/doc/application/application.rst b/doc/application/application.rst index 462985374..d6e0300ea 100644 --- a/doc/application/application.rst +++ b/doc/application/application.rst @@ -678,55 +678,54 @@ application with QEMU. Most content in this section is already covered on .. _GNU_Debugger: http://www.gnu.org/software/gdb -In this quick reference you find shortcuts, specific environmental variables -and parameters that can help you to quickly set up your debugging -environment. +In this quick reference you find shortcuts, specific environmental variables and +parameters that can help you to quickly set up your debugging environment. The simplest way to debug an application running in QEMU is using the GNU -Debugger and setting a local GDB server in your development system -through QEMU. +Debugger and setting a local GDB server in your development system through QEMU. -You will need an ELF binary image for debugging purposes. -The build system generates the image in the output directory. -By default, the kernel binary name is :file:`zephyr.elf`. The name can be -changed using a Kconfig option. +You will need an ELF binary image for debugging purposes. The build system +generates the image in the output directory. By default, the kernel binary name +is :file:`zephyr.elf`. The name can be changed using a Kconfig option. We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)` server instance. This port number can be changed for a port that best suits the -development system. +development environment. -QEMU is the supported emulation system of the kernel. QEMU must be invoked -with the -s and -S options. +You can run Qemu to listen for a "gdb connection" before it starts executing any +code to debug it. + +.. code-block:: bash + + qemu -s -S + +will setup Qemu to listen on port 1234 and wait for a GDB connection to it. + +The options used above have the following meaning: * ``-S`` Do not start CPU at startup; rather, you must type 'c' in the monitor. * ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on TCP port 1234. -The build system can build the elf binary and call the QEMU process with -the :makevar:`qemu` target. The QEMU debug options can be set using the -environment variable :envvar:`QEMU_EXTRA_FLAGS`. To set the ``-s`` and -``-S`` options: - -.. code-block:: bash - - export QEMU_EXTRA_FLAGS="-s -S" - -The build and emulation processes are called with the Makefile ``qemu`` -target: +To debug with QEMU and to start a GDB server and wait for a remote connect, run +the following inside an application: .. code-block:: bash - make qemu + make BOARD=qemu_x86 debugserver The build system will start a QEMU instance with the CPU halted at startup and with a GDB server instance listening at the TCP port 1234. -The :file:`.gdbinit` will help initialize your GDB instance on every run. +Using a local GDB configuration :file:`.gdbinit` can help initialize your GDB +instance on every run. In this example, the initialization file points to the GDB server instance. It configures a connection to a remote target at the local host on the TCP port 1234. The initialization sets the kernel's root directory as a -reference. The :file:`.gdbinit` file contains the following lines: +reference. + +The :file:`.gdbinit` file contains the following lines: .. code-block:: bash @@ -746,14 +745,21 @@ corresponds to :file:`zephyr.elf` file: .. code-block:: bash - gdb --tui zephyr.elf + $ gdb --tui zephyr.elf .. note:: The GDB version on the development system might not support the --tui option. -Finally, this command connects to the GDB server using the Data +If you are not using a .gdbinit file, issue the following command inside GDB to +connect to the remove GDB server on port 1234: + +.. code-block:: bash + + (gdb) target remote localhost:1234 + +Finally, The command below connects to the GDB server using the Data Displayer Debugger (:file:`ddd`). The command loads the symbol table from the elf binary file, in this instance, the :file:`zephyr.elf` file. diff --git a/scripts/support/qemu.sh b/scripts/support/qemu.sh new file mode 100755 index 000000000..3a0e2fdea --- /dev/null +++ b/scripts/support/qemu.sh @@ -0,0 +1,16 @@ +#!/bin/sh + +# Just a place holder for any custimizations. + +do_debugserver() { + echo "Detached GDB server" +} + +CMD="$1" +shift + +case "${CMD}" in + debugserver) + do_debugserver "$@" + ;; +esac -- cgit v1.2.3