Merge pull request #9847 from aabadie/pr/tools/pyocd

dist/tools: add support for PyOCD programmer/debugger

boards/microbit/Makefile.include

@@ -19,6 +19,8 @@ ifeq (fscopy,$(PROGRAMMER))
 else ifeq (openocd,$(PROGRAMMER))
   # this board uses a daplink adapter by default
   DEBUG_ADAPTER = dap
+else ifeq (pyocd, $(PROGRAMMER))
+  include $(RIOTMAKE)/tools/pyocd.inc.mk
 endif
 
 # include nrf51 boards common configuration

boards/nrf51dk/Makefile.include

@@ -11,6 +11,8 @@ PROGRAMMER ?= openocd
 # dap debug adapter is required for openocd
 ifeq (openocd,$(PROGRAMMER))
   DEBUG_ADAPTER = dap
+else ifeq (pyocd, $(PROGRAMMER)) # this boards is also supported by PyOCD
+  include $(RIOTMAKE)/tools/pyocd.inc.mk
 endif
 
 # include nrf51 boards common configuration

dist/tools/pyocd/pyocd.sh

+#!/bin/sh
+#
+# PyOCD script for RIOT. Only versions >= 0.14.1 are supported.
+#
+# This script is supposed to be called from RIOTs make system,
+# as it depends on certain environment variables.
+#
+# The script supports the following actions:
+#
+# flash:        flash <hex_file>
+#               flash given file to the target.
+#
+#               options:
+#               <hex_file>:   Filename of the hex file that will be flashed
+#               FLASH_TARGET_TYPE: CPU target type (nrf52, nrf51, etc)
+#
+# debug:        debug <elfile>
+#               starts pyocd-gdbserver as GDB server in the background and
+#               connects to the server with the GDB client specified by
+#               the board.
+#
+#               options:
+#               <elffile>:      path to the file to debug, must be in a format
+#                               recognized by GDB (preferably ELF, it will not
+#                               work with .bin, .hex because they lack
+#                               symbol information)
+#               GDB_PORT:       port opened for GDB connections
+#               TELNET_PORT:    port opened for telnet connections
+#               DBG:            debugger client command, default: 'gdb -q'
+#               TUI:            if TUI!=null, the -tui option will be used
+#
+# debug-server: starts pyocd-gdbserver as GDB server, but does not connect to
+#               to it with any frontend. This might be useful when using
+#               IDEs.
+#
+#               options:
+#               GDB_PORT:       port opened for GDB connections
+#               TELNET_PORT:    port opened for telnet connections
+#
+# reset:        triggers a hardware reset of the target board
+#
+# @author       Alexandre Abadie <alexandre.abadie@inria.fr>
+# @author       Hauke Peteresen <hauke.petersen@fu-berlin.de>
+# @author       Joakim Nohlgård <joakim.nohlgard@eistec.se>
+
+# Default GDB port, set to 0 to disable, required != 0 for debug and
+# debug-server targets
+: ${GDB_PORT:=3333}
+# Default telnet port, set to 0 to disable.
+: ${TELNET_PORT:=4444}
+# Default PyOCD commands.
+: ${PYOCD_CMD:=pyocd}
+: ${PYOCD_FLASH:=${PYOCD_CMD} flash}
+: ${PYOCD_GDBSERVER:=${PYOCD_CMD} gdbserver}
+# The setsid command is needed so that Ctrl+C in GDB doesn't kill PyOCD.
+: ${SETSID:=setsid}
+# GDB command, usually a separate command for each platform (e.g.
+# arm-none-eabi-gdb).
+: ${GDB:=gdb}
+# Debugger client command, can be used to wrap GDB in a front-end.
+: ${DBG:=${GDB}}
+# Default debugger flags.
+: ${DBG_DEFAULT_FLAGS:=-q -ex \"tar ext :${GDB_PORT}\"}
+# Extra debugger flags, added by the user.
+: ${DBG_EXTRA_FLAGS:=}
+# Debugger flags, will be passed to sh -c, remember to escape any quotation
+# signs. Use ${DBG_DEFAULT_FLAGS} to insert the default flags anywhere in the
+# string.
+: ${DBG_FLAGS:=${DBG_DEFAULT_FLAGS} ${DBG_EXTRA_FLAGS}}
+# CPU Target type.
+# Use `-t` followed by value. Example: -t nrf51
+: ${FLASH_TARGET_TYPE:=}
+
+#
+# Examples of alternative debugger configurations
+#
+
+# Using the GDB text UI:
+# DBG_EXTRA_FLAGS=-tui make debug
+# or to always use TUI, put in your .profile:
+# export DBG_EXTRA_FLAGS=-tui
+
+# Wrapping GDB inside DDD (https://www.gnu.org/software/ddd/)
+# DBG=ddd DBG_FLAGS='--debugger "${GDB} ${DBG_DEFAULT_FLAGS}"' make debug
+# Alternatively, to always use DDD, put the following in your .profile or similar:
+# export DBG=ddd
+# export DBG_FLAGS='--debugger "${GDB} ${DBG_DEFAULT_FLAGS}"'
+# The single quotes are important on the line above, or it will not work.
+
+#
+# a couple of tests for certain configuration options
+#
+test_elffile() {
+    if [ ! -f "${ELFFILE}" ]; then
+        echo "Error: Unable to locate ELFFILE"
+        echo "       (${ELFFILE})"
+        exit 1
+    fi
+}
+
+test_hexfile() {
+    if [ ! -f "${HEX_FILE}" ]; then
+        echo "Error: Unable to locate HEX_FILE"
+        echo "       (${HEX_FILE})"
+        exit 1
+    fi
+}
+
+#
+# now comes the actual actions
+#
+do_flash() {
+    HEX_FILE=$1
+    test_hexfile
+    # flash device
+    sh -c "${PYOCD_FLASH} ${FLASH_TARGET_TYPE} \"${HEX_FILE}\"" &&
+    echo 'Done flashing'
+}
+
+do_debug() {
+    ELFFILE=$1
+    test_elffile
+    # temporary file that saves PyOCD pid
+    OCD_PIDFILE=$(mktemp -t "pyocd_pid.XXXXXXXXXX")
+    # will be called by trap
+    cleanup() {
+        OCD_PID="$(cat $OCD_PIDFILE)"
+        kill ${OCD_PID}
+        rm -f "$OCD_PIDFILE"
+        exit 0
+    }
+    # cleanup after script terminates
+    trap "cleanup ${OCD_PIDFILE}" EXIT
+    # don't trap on Ctrl+C, because GDB keeps running
+    trap '' INT
+    # start PyOCD as GDB server
+    ${SETSID} sh -c "${PYOCD_GDBSERVER} \
+            ${FLASH_TARGET_TYPE} \
+            -p ${GDB_PORT} \
+            -T ${TELNET_PORT} & \
+            echo \$! > $OCD_PIDFILE" &
+    # Export to be able to access these from the sh -c command lines, may be
+    # useful when using a frontend for GDB
+    export ELFFILE
+    export GDB
+    export GDB_PORT
+    export DBG_FLAGS
+    # Start the debugger and connect to the GDB server
+    sh -c "${DBG} ${DBG_FLAGS} ${ELFFILE}"
+}
+
+do_debugserver() {
+    # start PyOCD as GDB server
+    sh -c "${PYOCD_GDBSERVER} \
+            ${FLASH_TARGET_TYPE} \
+            -p ${GDB_PORT} \
+            -T ${TELNET_PORT}"
+}
+
+do_reset() {
+    # start PyOCD and invoke board reset
+    sh -c "${PYOCD_CMD} cmd -c reset ${FLASH_TARGET_TYPE}"
+}
+
+#
+# parameter dispatching
+#
+ACTION="$1"
+shift # pop $1 from $@
+
+case "${ACTION}" in
+  flash)
+    echo "### Flashing Target ###"
+    do_flash "$@"
+    ;;
+  debug)
+    echo "### Starting Debugging ###"
+    do_debug "$@"
+    ;;
+  debug-server)
+    echo "### Starting GDB Server ###"
+    do_debugserver
+    ;;
+  reset)
+    echo "### Resetting Target ###"
+    do_reset
+    ;;
+  *)
+    echo "Usage: $0 {flash|debug|debug-server|reset}"
+    exit 2
+    ;;
+esac

makefiles/tools/pyocd.inc.mk

+export FLASHER ?= $(RIOTBASE)/dist/tools/pyocd/pyocd.sh
+export DEBUGGER = $(RIOTBASE)/dist/tools/pyocd/pyocd.sh
+export DEBUGSERVER = $(RIOTBASE)/dist/tools/pyocd/pyocd.sh
+export RESET ?= $(RIOTBASE)/dist/tools/pyocd/pyocd.sh
+
+export OFLAGS ?= -O ihex
+export FFLAGS ?= flash $(HEXFILE)
+export DEBUGGER_FLAGS ?= debug $(ELFFILE)
+export DEBUGSERVER_FLAGS ?= debug-server
+export RESET_FLAGS ?= reset