[makefile] extend GDB target (#634)

docs/datasheet/software.adoc

@@ -83,7 +83,6 @@ The NEORV32 project provides a set of pre-defined C libraries that allow an easy
 |=======================
 | C source file       | C header file          | Description
 | -                   | `neorv32.h`            | Main NEORV32 library file
-| -                   | `neorv32_buskeeper.h`  | <<_internal_bus_monitor_buskeeper>> HAL
 | `neorv32_cfs.c`     | `neorv32_cfs.h`        | <<_custom_functions_subsystem_cfs>> HAL
 | `neorv32_crc.c`     | `neorv32_crc.h`        | <<_cyclic_redundancy_check_crc>> HAL
 | `neorv32_cpu.c`     | `neorv32_cpu.h`        | <<_neorv32_central_processing_unit_cpu>> HAL
@@ -157,7 +156,7 @@ Make sure to add the bin folder of RISC-V GCC to your PATH variable.
  help       - show this text
  check      - check toolchain
  info       - show makefile/toolchain configuration
- gdb        - run GNU debugger
+ gdb        - run GNU debugging session
  asm        - compile and generate <main.asm> assembly listing file for manual debugging
  elf        - compile and generate <main.elf> ELF file
  bin        - compile and generate <neorv32_raw_exe.bin> RAW executable file (binary file, no header)
@@ -182,6 +181,7 @@ Make sure to add the bin folder of RISC-V GCC to your PATH variable.
  ASM_INC      - ASM include folder(s) [append only], default "-I ."
  RISCV_PREFIX - Toolchain prefix, default "riscv32-unknown-elf-"
  NEORV32_HOME - NEORV32 home folder, default "../../.."
+ GDB_ARGS     - GDB (connection) arguments: "-ex target extended-remote localhost:3333"
 ----
 
 
@@ -222,6 +222,8 @@ USER_FLAGS ?=
 USER_LIBS ?=
 # Relative or absolute path to the NEORV32 home folder
 NEORV32_HOME ?= ../../..
+# GDB arguments
+GDB_ARGS ?= -ex "target extended-remote localhost:3333"
 # *****************************************************************************
 ----
 
@@ -239,6 +241,7 @@ NEORV32_HOME ?= ../../..
 | `USER_FLAGS`   | Additional flags that will be forwarded to the compiler tools
 | `USER_LIBS`    | Additional libraries to include during linking (`*.a`)
 | `NEORV32_HOME` | Relative or absolute path to the NEORV32 project home folder; adapt this if the makefile/project is not in the project's default `sw/example` folder
+| `GDB_ARGS`     | Default GDB arguments when running the `gdb` target
 |=======================
 
 :sectnums:

docs/userguide/debugging_with_ocd.adoc

@@ -7,6 +7,12 @@ host machine. The general flow is independent of the host machine's operating sy
 Windows and Linux (Ubuntu on Windows / WSL) in parallel running the upstream version of OpenOCD and the
 RISC-V _GNU debugger_ `gdb`.
 
+.TLDR
+[TIP]
+You can start a pre-configured debug session (using default `main.elf` as executable and
+`target extended-remote localhost:3333` as gdb connection configuration) by using the **gdb** makefile target
+(i.e. `make gdb`).
+
 [NOTE]
 See datasheet section https://stnolting.github.io/neorv32/#_on_chip_debugger_ocd[On Chip Debugger (OCD)]
 for more information regarding the actual hardware.
@@ -16,9 +22,6 @@ The on-chip debugger is only implemented if the _ON_CHIP_DEBUGGER_EN_ generic is
 the `Zicsr` and `Zifencei` CPU extension to be implemented (top generics _CPU_EXTENSION_RISCV_Zicsr_ = _true_
 and _CPU_EXTENSION_RISCV_Zifencei_ = _true_).
 
-[TIP]
-<<_segger_embedded_studio>> can also be used to develop and debug applications for the NEORV32 using the on-chip debugger.
-
 
 :sectnums:
 === Hardware Requirements

sw/common/common.mk

@@ -61,6 +61,9 @@ USER_FLAGS ?=
 NEORV32_HOME ?= ../../..
 NEORV32_LOCAL_RTL ?= $(NEORV32_HOME)/rtl
 
+# GDB arguments
+GDB_ARGS ?= -ex "target extended-remote localhost:3333"
+
 
 # -----------------------------------------------------------------------------
 # NEORV32 framework
@@ -300,8 +303,8 @@ elf_info: $(APP_ELF)
 # -----------------------------------------------------------------------------
 # Run GDB
 # -----------------------------------------------------------------------------
-gdb: 
-	@$(GDB)
+gdb:
+	@$(GDB) $(APP_ELF) $(GDB_ARGS)
 
 
 # -----------------------------------------------------------------------------
@@ -318,46 +321,62 @@ clean_all: clean
 # Show configuration
 # -----------------------------------------------------------------------------
 info:
-	@echo "---------------- Info: Project ----------------"
+	@echo "------------------------------------------------------"
+	@echo "-- Project"
+	@echo "------------------------------------------------------"
 	@echo "Project folder:        $(shell basename $(CURDIR))"
 	@echo "Source files:          $(APP_SRC)"
 	@echo "Include folder(s):     $(APP_INC)"
 	@echo "ASM include folder(s): $(ASM_INC)"
-	@echo "---------------- Info: NEORV32 ----------------"
+	@echo "------------------------------------------------------"
+	@echo "-- NEORV32"
+	@echo "------------------------------------------------------"
 	@echo "NEORV32 home folder (NEORV32_HOME): $(NEORV32_HOME)"
 	@echo "IMAGE_GEN: $(IMAGE_GEN)"
 	@echo "Core source files:"
 	@echo "$(CORE_SRC)"
 	@echo "Core include folder:"
 	@echo "$(NEORV32_INC_PATH)"
-	@echo "---------------- Info: Objects ----------------"
+	@echo "------------------------------------------------------"
+	@echo "-- Objects"
+	@echo "------------------------------------------------------"
 	@echo "Project object files:"
 	@echo "$(OBJ)"
-	@echo "---------------- Info: RISC-V CPU ----------------"
+	@echo "------------------------------------------------------"
+	@echo "-- RISC-V CPU"
+	@echo "------------------------------------------------------"
 	@echo "MARCH:      $(MARCH)"
 	@echo "MABI:       $(MABI)"
-	@echo "---------------- Info: Toolchain ----------------"
+	@echo "------------------------------------------------------"
+	@echo "-- Toolchain"
+	@echo "------------------------------------------------------"
 	@echo "Toolchain:  $(RISCV_TOLLCHAIN)"
 	@echo "CC:         $(CC)"
 	@echo "OBJDUMP:    $(OBJDUMP)"
 	@echo "OBJCOPY:    $(OBJCOPY)"
 	@echo "SIZE:       $(SIZE)"
 	@echo "DEBUGGER:   $(GDB)"
-	@echo "---------------- Info: Compiler Configuration ----------------"
-	@$(CC) -v
-	@echo "---------------- Info: Compiler Libraries ----------------"
+	@echo "------------------------------------------------------"
+	@echo "-- GDB Arguments"
+	@echo "------------------------------------------------------"
+	@echo "GDB_ARGS:   $(GDB_ARGS)"
+	@echo "------------------------------------------------------"
+	@echo "-- Libraries"
+	@echo "------------------------------------------------------"
 	@echo "LIBGCC:"
 	@$(CC) -print-libgcc-file-name
 	@echo "SEARCH-DIRS:"
 	@$(CC) -print-search-dirs
-	@echo "---------------- Info: Flags ----------------"
+	@echo "------------------------------------------------------"
+	@echo "-- Flags"
+	@echo "------------------------------------------------------"
 	@echo "USER_FLAGS: $(USER_FLAGS)"
 	@echo "CC_OPTS:    $(CC_OPTS)"
-	@echo "---------------- Info: Libraries ----------------"
+	@echo "------------------------------------------------------"
+	@echo "-- Libraries"
+	@echo "------------------------------------------------------"
 	@echo "USER_LIBS: $(USER_LIBS)"
 	@echo "LD_LIBS:   $(LD_LIBS)"
-	@echo "---------------- Info: Host Native GCC Flags ----------------"
-	@echo "CC_X86:     $(CC_X86)"
 
 
 # -----------------------------------------------------------------------------
@@ -371,7 +390,7 @@ help:
 	@echo " help       - show this text"
 	@echo " check      - check toolchain"
 	@echo " info       - show makefile/toolchain configuration"
-	@echo " gdb        - run GNU debugger"
+	@echo " gdb        - run GNU debugging session"
 	@echo " asm        - compile and generate <$(APP_ASM)> assembly listing file for manual debugging"
 	@echo " elf        - compile and generate <$(APP_ELF)> ELF file"
 	@echo " exe        - compile and generate <$(APP_EXE)> executable for upload via default bootloader (binary file, with header)"
@@ -397,4 +416,5 @@ help:
 	@echo " ASM_INC      - ASM include folder(s) [append only]: \"$(ASM_INC)\""
 	@echo " RISCV_PREFIX - Toolchain prefix: \"$(RISCV_PREFIX)\""
 	@echo " NEORV32_HOME - NEORV32 home folder: \"$(NEORV32_HOME)\""
+	@echo " GDB_ARGS     - GDB (connection) arguments: \"$(GDB_ARGS)\""
 	@echo ""