boards/qn9080dk: Improve doc and add J-Link support

- document that the QN9080DK has an alternative firmware for the
  debugger/programmer that supports J-Link
- allow selecting the debugger firmware via parameter / environment
  variable
- add `JLINK_DEVICE` parameter to allow flashing via J-Link

boards/common/qn908x/Makefile.include

@@ -1,12 +1,8 @@
 # This board uses OpenOCD. Note that support for QN908x in OpenOCD at the time
 # of writing has not been merged in the tree and is only available at
-# http://openocd.zylin.com/#/c/5584/ .
+# https://review.openocd.org/c/openocd/+/5584
-PROGRAMMER ?= openocd
-PROGRAMMERS_SUPPORTED += openocd
 
-# Using dap or jlink depends on which firmware the OpenSDA debugger is running
+PROGRAMMERS_SUPPORTED += openocd
-#OPENOCD_DEBUG_ADAPTER ?= dap
-OPENOCD_DEBUG_ADAPTER ?= jlink
 
 # Use the shared OpenOCD configuration
 OPENOCD_CONFIG ?= $(RIOTBOARD)/common/qn908x/dist/openocd.cfg
@@ -16,6 +12,36 @@ OPENOCD_CONFIG ?= $(RIOTBOARD)/common/qn908x/dist/openocd.cfg
 # enabled after a 'reset halt' command.
 OPENOCD_PRE_FLASH_CMDS += "-c qn908x disable_wdog"
 
+# Using dap or jlink depends on which firmware the OpenSDA debugger is running
+ifeq (1,$(QN908X_JLINK))
+  OPENOCD_DEBUG_ADAPTER ?= jlink
+  # If port selection via ttys.py is enabled by `MOST_RECENT_PORT=1`, filter
+  # USB serials to only select the UART bridge of embedded NXP debuggers running
+  # the J-Link firmware.
+  TTY_BOARD_FILTER := --vendor SEGGER --model J-Link
+
+  # keep name of `JLINK` in sync with script jlink.sh in $(RIOTTOOLS)/jlink
+  JLINK ?= JLinkExe
+
+  # Default to J-Link as programmer if installed
+  ifneq (,$(shell command -v $(JLINK)))
+    PROGRAMMER ?= jlink
+  else
+    PROGRAMMER ?= openocd
+  endif
+else
+  OPENOCD_DEBUG_ADAPTER ?= dap
+
+  # If port selection via ttys.py is enabled by `MOST_RECENT_PORT=1`, filter
+  # USB serials to only select the UART bridge of embedded NXP debuggers running
+  # the LPC-LINK2 CMSIS-DAP firmware.
+  TTY_BOARD_FILTER := --vendor NXP --model LPC-LINK2
+
+  # Default to OpenOCD (despite downstream patches are needed) as the LPC-LINK2
+  # programmer firmware is not supported by J-Link
+  PROGRAMMER ?= openocd
+endif
+
 # In order to boot, the CPU requires that the Vector table contain a valid
 # checksum in one of the "reserved" fields. We don't generate this checksum when
 # compiling and linking the code, instead this make target computes the checksum

boards/qn9080dk/Makefile.include

@@ -4,11 +4,8 @@ CFLAGS += \
   -DCONFIG_BOARD_HAS_XTAL_32M \
   #
 
-OPENOCD_DEBUG_ADAPTER ?= dap
+QN908X_JLINK ?= $(QN9080DK_JLINK)
-
+JLINK_DEVICE ?= QN9080A
-# If port selection via ttys.py is enabled by `MOST_RECENT_PORT=1`, filter
-# USB serials to only select the UART bridge of embedded NXP debuggers.
-TTY_BOARD_FILTER := --vendor NXP --model LPC-LINK2
 
 # Include default QN908x board config
 include $(RIOTBOARD)/common/qn908x/Makefile.include

boards/qn9080dk/doc.txt

@@ -3,7 +3,9 @@
 @ingroup     boards
 @brief       Support for the QN9080DK base board.
 
-### General information
+### General Information
+
+@image html "https://lv.farnell.com/productimages/large/en_GB/2775176-40.jpg" "Top View of the QN9080DK V1.2" width=80%
 
 The QN9080DK is the developer board reference from NXP for the QN908x CPUs.
 The developer kit comes with two boards: a larger PCB with a QFN "module"
@@ -28,9 +30,9 @@ For more information visit NXP's product description page for the
 [QN9080-DK](https://www.nxp.com/QN9080DK) where you can find the User's
 Guide.
 
-### User Interface
+### Pinout
 
-Buttons:
+#### Buttons:
 
 | Label | RIOT OS macro | MCU PIN  | Function  |
 |:----- |:------------- |:-------- |:--------- |
@@ -39,7 +41,7 @@ Buttons:
 | SW3   |               | nRESET   | QN9080 reset |
 
 
-One RGB led, controlled by three GPIOs
+#### One RGB led, controlled by three GPIOs
 
 | Label | RIOT OS macro | MCU PIN  |
 |:----- |:------------- |:-------- |
@@ -47,16 +49,72 @@ One RGB led, controlled by three GPIOs
 | green | LED_GREEN_PIN | PA25     |
 | blue  | LED_BLUE_PIN  | PA13     |
 
-### Pinout
+#### SPI Flash
 
-Button1:
+| Name  | MCU Pin   |
+|:----- |:--------- |
+| MISO  | PA05      |
+| MOSI  | PA04      |
+| SSEL  | PA03      |
+| SCK   | PA30      |
 
-### Flash the board
+#### USB
 
-The board can be flashed using the internal LPC4322 JTAG/SWD debugger or an
+| Name  | MCU Pin   |
-external debugger connected to P1, selected using JP2.
+|:----- |:--------- |
+| D+    | PA26      |
+| D-    | PA27      |
 
-OpenOCD support for the QN908x is experimental and available as pending
+#### I2C / MMA8652FC G-Sensor
-[patch](http://openocd.zylin.com/#/c/5584/).
+
+@note   The jumper JP11 needs to be in place to connect the I2C sensor to the
+        pins. This is the default when freshly unboxed.
+
+| Name  | MCU Pin   |
+|:----- |:--------- |
+| SCL   | PA06      |
+| SDA   | PA07      |
+
+The MMA8652 sensor has I2C address 0x1d.
+
+
+### Flashing the Board
+
+The integrated programmer by default comes with an "LPC-LINK2" firmware that
+provides a CMSIS DAP compatible interface. The programmer can be flashed with
+a Segger J-Link firmware via DFU, see the [LPCSCrypt User Guide][LPCScrypt] for
+details. It seems that the J-Link firmware is indeed a bit more reliable, so
+if you run into issues during debugging and/or flashing, switching to the
+J-Link firmware is an option.
+
+[LPCScrypt]: https://web.archive.org/web/20220225151231/https://www.nxp.com/docs/en/user-guide/LPCScrypt_User_Guide.pdf
+
+#### Using the Internal Programmer with Default Firmware
+
+In the application directory, run:
+
+```
+make BOARD=qn9080dk flash
+```
+
+OpenOCD support for the QN908x flash is experimental and available as pending
+[patch](https://review.openocd.org/c/openocd/+/5584).
+
+#### Using the Internal Programmer with J-Link Firmware
+
+In the application directory, run:
+
+```
+make BOARD=qn9080dk QN9080DK_JLINK=1 flash
+```
+
+@note Instead of passing `QN9080DK_JLINK=1` every time, it can also be exported
+      as environment variable.
+
+#### Using an External Programmer
+
+By setting the jumper at `JP2` to `EXT` the internal LPC4322 debugger/programmer
+is disconnect and an external programmer can be connected at header `P1` using
+a standard 10 pin 1.27 mm debug connector.
 
  */