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 <[email protected]>

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.

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)

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)"

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)"

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}"

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}"

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}"

boards/arm/qemu_cortex_m3/Makefile.board

@@ -0,0 +1,5 @@
+
+DEBUG_SCRIPT = qemu.sh
+
+debugserver: QEMU_EXTRA_FLAGS += -s -S
+debugserver: qemu

boards/nios2/altera_max10/Makefile.board

@@ -1,2 +1,3 @@
 FLASH_SCRIPT = nios2.sh
+DEBUG_SCRIPT = nios2.sh
 

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

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}"

boards/x86/qemu_x86/Makefile.board

@@ -0,0 +1,5 @@
+
+DEBUG_SCRIPT = qemu.sh
+
+debugserver: QEMU_EXTRA_FLAGS += -s -S
+debugserver: qemu

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}"
 

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}"

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 <image>
+
+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.
 

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