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 <anas.nashif@intel.com>
diff --git a/Makefile b/Makefile
index 0ed598b..fc3aa45 100644
--- a/Makefile
+++ b/Makefile
@@ -1138,6 +1138,7 @@
@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 @@
$(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 0feaaa8..4ebb4ea 100644
--- a/Makefile.inc
+++ b/Makefile.inc
@@ -83,18 +83,19 @@
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 @@
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 d2e80b9..6d09ebb 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 5c7a11f..2c7ad79 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 7d02aa3..e473331 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 7d02aa3..e473331 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 7d02aa3..e473331 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 0000000..be023b2
--- /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 b9bafa5..be18673 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 b9bafa5..be023b2 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 95d138c..f1e40f4 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 0000000..be023b2
--- /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 af482d9..a608420 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 cac6548..fd6d2f8 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 4629853..d6e0300 100644
--- a/doc/application/application.rst
+++ b/doc/application/application.rst
@@ -678,55 +678,54 @@
.. _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:
+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
- export QEMU_EXTRA_FLAGS="-s -S"
-
-The build and emulation processes are called with the Makefile ``qemu``
-target:
-
-.. 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 @@
.. 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 0000000..3a0e2fd
--- /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
