tools/mspdebug: fix make debug and make debugserver

The semantics of `make debug` and `make debugserver` have changed in
the years since the MSP430 integration. This brings the implementation
back into line with the current semantics

- `make debug` now starts both mspdebug and GDB, no need to
  run `make debugserver` prior to `make debug` anymore
- `make debug` no longer flashes the target to not waste flash erase
  cycles
- GDB mutliarch support is added
- support for selecting a debug adapter by its serial is added

dist/tools/mspdebug/debug.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+
+MSPDEBUG="$1"
+MSPDEBUG_PROGRAMMER="$2"
+PROTOCOL="$3"
+MSPDEBUG_TTY="$4"
+DEBUG_ADAPTER_ID="$5"
+GDBPORT="$6"
+ELFFILE="$7"
+PREFIX="$8"
+RIOTBASE="$9"
+
+# The setsid command is needed so that Ctrl+C in GDB doesn't kill mspdebug
+: "${SETSID:=setsid}"
+
+if "${PREFIX}-gdb" -v > /dev/null 2>&1; then
+    GDB="${PREFIX}-gdb"
+elif gdb-multiarch -v > /dev/null 2>&1; then
+    GDB=gdb-multiarch
+else
+    echo "Couldn't find GDB (tried ${PREFIX}-gdb and gdb-multiarch). Check \$PATH."
+    exit 1
+fi
+
+if [ -z "${MSPDEBUG_PROGRAMMER}" ]; then
+    echo "MSPDEBUG_PROGRAMMER unset, cannot use mspdebug"
+fi
+
+sleep 2
+args=()
+if [ "JTAG" = "${PROTOCOL}" ]; then
+    args+=("-j")
+elif [ "Spy-Bi-Wire" != "${PROTOCOL}" ]; then
+    echo "Debugger protocol \"${PROTOCOL}\" not supported, use JTAG or Spy-Bi-Wire"
+    exit 1
+fi
+args+=("${MSPDEBUG_PROGRAMMER}")
+if [ -n "${DEBUG_ADAPTER_ID}" ]; then
+    args+=("s" "{$DEBUG_ADAPTER_ID}")
+fi
+if [ -n "${MSPDEBUG_TTY}" ]; then
+    args+=("-d" "${MSPDEBUG_TTY}")
+fi
+args+=("gdb ${GDBPORT}")
+
+${SETSID} -w "${MSPDEBUG}" "${args[@]}" > /dev/null 2>&1 &
+echo "Please wait..."
+
+sleep 3
+exec "$GDB" \
+    -ex "target remote localhost:${GDBPORT}" \
+    -ex "monitor reset halt" "$ELFFILE" \
+    -ex "set substitute-path /data/riotbuild/riotbase $RIOTBASE"

dist/tools/mspdebug/debug_srv.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+MSPDEBUG="$1"
+MSPDEBUG_PROGRAMMER="$2"
+PROTOCOL="$3"
+MSPDEBUG_TTY="$4"
+DEBUG_ADAPTER_ID="$5"
+GDBPORT="$6"
+
+if [ -z "${MSPDEBUG_PROGRAMMER}" ]; then
+    echo "MSPDEBUG_PROGRAMMER unset, cannot use mspdebug"
+fi
+
+args=()
+if [ "JTAG" = "${PROTOCOL}" ]; then
+    args+=("-j")
+else
+    if [ "Spy-Bi-Wire" != "${PROTOCOL}" ]; then
+        echo "Debugger protocol \"${PROTOCOL}\" not supported, use JTAG or Spy-Bi-Wire"
+        exit 1
+    fi
+fi
+args+=("${MSPDEBUG_PROGRAMMER}")
+if [ -n "${DEBUG_ADAPTER_ID}" ]; then
+    args+=("s" "{$DEBUG_ADAPTER_ID}")
+fi
+if [ -n "${MSPDEBUG_TTY}" ]; then
+    args+=("-d" "${MSPDEBUG_TTY}")
+fi
+args+=("gdb ${GDBPORT}")
+
+"${MSPDEBUG}" "${args[@]}"

doc/doxygen/src/flashing.md

@@ -217,6 +217,31 @@ now, `STM32FLASH_RESET_INVERT` is by default `1`. This may change if it
 becomes evident that non-inverted TTL adapters are in fact more common than
 inverted adapters.
 
+MSPDEBUG Configuration                         {#flashing-configuration-mspdebug}
+----------------------
+
+All options can be passed as environment variables or as make arguments.
+All options except for `DEBUGSERVER_PORT` apply to both debugging and flashing
+alike.
+
+`MSPDEBUG_PROGRAMMER` is used to set the hardware programmer/debugger to use
+for programming and debugging. See `mspdebug --help` or `man mspdebug` for a
+list of programmers.
+
+`MSPDEBUG_PROTOCOL` is used to specify the debugger protocol. It is typically
+set by the board used. Only JTAG and Spi-Bi-Wire are supported.
+
+`MSPDEBUG_TTY` is used to connect via TTY interface instead of directly via
+USB to the debugger. Usually, this is not required.
+
+`DEBUG_ADAPTER_ID` is used to select the debugger/programmer by its serial. If
+not set, `mspdebug` will select the first device with matching vendor and
+product ID. Unless multiple debuggers of the same type are connected, this
+options is typically not needed.
+
+`DEBUGSERVER_PORT` is used to specify the TCP port to listen for GDB to
+connect to. It defaults to 2000.
+
 Handling Multiple Boards With UDEV-Rules                {#multiple-boards-udev}
 ========================================
 

makefiles/docker.inc.mk

@@ -47,8 +47,8 @@ export DOCKER_ENV_VARS += \
   CXXUWFLAGS \
   $(DOCKER_RIOT_CONFIG_VARIABLES) \
   ELFFILE \
-  HEXFILE \
   FLASHFILE \
+  HEXFILE \
   IOTLAB_NODE \
   LINK \
   LINKFLAGPREFIX \
@@ -57,20 +57,20 @@ export DOCKER_ENV_VARS += \
   OBJCOPY \
   OFLAGS \
   PARTICLE_MONOFIRMWARE \
-  PREFIX \
-  QUIET \
-  WERROR \
   PICOLIBC \
+  PREFIX \
   PROGRAMMER \
+  QUIET \
   RIOT_CI_BUILD \
   RIOT_VERSION \
   RIOT_VERSION_CODE \
   SCANBUILD_ARGS \
   SCANBUILD_OUTPUTDIR \
   SIZE \
-  TOOLCHAIN \
   TEST_KCONFIG \
+  TOOLCHAIN \
   UNDEF \
+  WERROR \
   #
 
 # List of all exported environment variables that shall be passed on to the

makefiles/tools/mspdebug.inc.mk

@@ -1,17 +1,27 @@
-MSPDEBUGFLAGS += -j $(MSPDEBUG_PROGRAMMER)
-ifeq ($(strip $(MSPDEBUG_PROGRAMMER)),uif)
-  MSPDEBUGFLAGS += -d $(PROG_DEV)
-endif
 FLASHER ?= mspdebug
 FLASHFILE ?= $(HEXFILE)
-FFLAGS = $(MSPDEBUGFLAGS) "prog $(FLASHFILE)"
+MSPDEBUG_PROGRAMMER ?= olimex
 
-# setup debugger
-DEBUGSERVER = $(FLASHER)
-DEBUGSERVER_FLAGS = $(MSPDEBUGFLAGS) gdb
-DEBUGGER = $(PREFIX)gdb
-DEBUGGER_FLAGS = --ex="target remote localhost:2000" --ex "monitor reset halt" --ex load -ex "monitor reset halt"  $(DEBUG_ELFFILE)
+DEBUGSERVER_PORT ?= 2000
+DEBUGGER := $(RIOTTOOLS)/mspdebug/debug.sh
+MSPDEBUG_PROTOCOL ?= JTAG
+MSPDEBUG_TTY ?=
+
+ifeq (JTAG,$(strip $(MSPDEBUG_PROTOCOL)))
+  FFLAGS += -j
+endif
+ifneq (,$(strip $(MSPDEBUG_TTY)))
+  FFLAGS += -d "$(MSPDEBUG_TTY)"
+endif
+ifneq (,$(strip $(DEBUG_ADAPTER_ID)))
+  FFLAGS += -s "$(DEBUG_ADAPTER_ID)"
+endif
+FFLAGS += $(MSPDEBUG_PROGRAMMER) "prog $(FLASHFILE)"
+
+DEBUGGER_FLAGS = $(FLASHER) $(MSPDEBUG_PROGRAMMER) $(MSPDEBUG_PROTOCOL) "$(MSPDEBUG_TTY)" "$(DEBUG_ADAPTER_ID)" $(DEBUGSERVER_PORT) $(ELFFILE) $(PREFIX) $(RIOTBASE)
+DEBUGSERVER := $(RIOTTOOLS)/mspdebug/debug_srv.sh
+DEBUGSERVER_FLAGS = $(FLASHER) $(MSPDEBUG_PROGRAMMER) $(MSPDEBUG_PROTOCOL) "$(MSPDEBUG_TTY)" "$(DEBUG_ADAPTER_ID)" $(DEBUGSERVER_PORT)
 
 # setup reset tool
 RESET ?= mspdebug
-RESET_FLAGS ?= $(MSPDEBUGFLAGS) reset
+RESET_FLAGS ?= -j $(MSPDEBUG_PROGRAMMER) reset