Merge pull request #16911 from yarrick/esp_jtag

cpu/esp32: Add openocd programming support

boards/esp32-ethernet-kit-v1_0/Makefile.include

@@ -2,4 +2,8 @@
 # configure the serial interface
 PORT_LINUX ?= /dev/ttyUSB1
 
+ifneq (,$(filter esp_jtag,$(USEMODULE)))
+  OPENOCD_CONFIG ?= board/esp32-ethernet-kit-3.3v.cfg
+endif
+
 include $(RIOTBOARD)/common/esp32/Makefile.include

boards/esp32-ethernet-kit-v1_0/doc_common.txt

@@ -102,9 +102,22 @@ Since the USB bridge based on FDI FT2232HL provides a JTAG interface for debuggi
 
 To use the JTAG interface, the `esp_jtag` module must be used to disable the `SPI_DEV(0)` which normally uses the GPIOs for the JTAG signals.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-USEMODULE=esp_jtag make flash BOARD=esp32-ethernet-kit-v1_X ...
+USEMODULE+=esp_jtag make flash BOARD=esp32-ethernet-kit-v1_X ...
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Furthermore the function switches (DIP switches) for the JTAG signals must be set to ON.
 
+To flash using OpenOCD, install the [openocd-esp32](https://github.com/espressif/openocd-esp32) fork.
+Export where openocd is located and then flash with PROGRAMMER set:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+export OPENOCD="~/openocd-esp32/src/openocd -s ~/openocd-esp32/tcl"
+PROGRAMMER=openocd USEMODULE+=esp_jtag make flash BOARD=esp32-ethernet-kit-v1_X
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To start a debugging session (board will be reset, but not flashed):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+export OPENOCD="~/openocd-esp32/src/openocd -s ~/openocd-esp32/tcl"
+PROGRAMMER=openocd USEMODULE+=esp_jtag make debug BOARD=esp32-ethernet-kit-v1_X
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 [Back to table of contents](#esp32_ethernet_kit_toc)
  */

boards/esp32-wrover-kit/Kconfig

@@ -15,11 +15,11 @@ config BOARD_ESP32_WROVER_KIT
     select HAS_ARDUINO
     select HAS_ESP_RTC_TIMER_32K
     select HAS_ESP_SPI_RAM
-    select HAS_ESP_JTAG
     select HAS_PERIPH_ADC
     select HAS_PERIPH_I2C
     select HAS_PERIPH_PWM
     select HAS_PERIPH_SPI
     select HAS_SDCARD_SPI
+    select MODULE_ESP_JTAG
 
 source "$(RIOTBOARD)/common/esp32/Kconfig"

boards/esp32-wrover-kit/Makefile.dep

@@ -2,4 +2,7 @@ ifneq (,$(filter disp_dev,$(USEMODULE)))
   USEMODULE += ili9341
 endif
 
+# Sets up configuration for openocd
+USEMODULE += esp_jtag
+
 include $(RIOTBOARD)/common/esp32/Makefile.dep

boards/esp32-wrover-kit/Makefile.features

@@ -11,7 +11,6 @@ FEATURES_PROVIDED += periph_spi
 
 # unique features provided by the board
 FEATURES_PROVIDED += sdcard_spi
-FEATURES_PROVIDED += esp_jtag
 FEATURES_PROVIDED += esp_spi_ram
 FEATURES_PROVIDED += esp_rtc_timer_32k
 

boards/esp32-wrover-kit/Makefile.include

@@ -3,4 +3,8 @@ PSEUDOMODULES += esp32_wrover_kit_camera
 # configure the serial interface
 PORT_LINUX ?= /dev/ttyUSB1
 
+ifneq (,$(filter esp_jtag,$(USEMODULE)))
+  OPENOCD_CONFIG ?= board/esp32-wrover-kit-3.3v.cfg
+endif
+
 include $(RIOTBOARD)/common/esp32/Makefile.include

boards/esp32-wrover-kit/doc.txt

@@ -289,6 +289,25 @@ convenient way for On-Chip debugging. Please refer the
 [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html)
 for details on how to setup and how to use ESP-WROVER-KIT and OpenOCD.
 
+To use the JTAG interface, the `esp_jtag` module must be enabled.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+USEMODULE+=esp_jtag make flash BOARD=esp32-wrover-kit ...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To flash using OpenOCD, install the [openocd-esp32](https://github.com/espressif/openocd-esp32) fork.
+The OpenOCD configuration selected by default is for using JTAG via the FTDI chip.
+Export where openocd is located and then flash with PROGRAMMER set:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+export OPENOCD="~/openocd-esp32/src/openocd -s ~/openocd-esp32/tcl"
+PROGRAMMER=openocd USEMODULE+=esp_jtag make flash BOARD=esp32-wrover-kit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To start a debugging session (board will be reset, but not flashed):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+export OPENOCD="~/openocd-esp32/src/openocd -s ~/openocd-esp32/tcl"
+PROGRAMMER=openocd USEMODULE+=esp_jtag make debug BOARD=esp32-wrover-kit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 [Back to table of contents](#esp32_wrover_kit_toc)
 
 ## Other Documentation Resources  {#esp32_wrover_kit_other-resources}

cpu/esp32/Makefile.include

@@ -79,3 +79,17 @@ endif
 ifneq (,$(filter cpp,$(FEATURES_USED)))
   ARCHIVES += -lstdc++
 endif
+
+ifneq (,$(filter esp_jtag,$(USEMODULE)))
+  PROGRAMMERS_SUPPORTED += openocd
+  PARTITION_POS = 0x8000
+  OPENOCD_PRE_FLASH_CMDS = -c 'echo "Installing Bootloader at $(BOOTLOADER_POS)"' \
+    -c 'flash write_image erase "$(RIOTCPU)/$(CPU)/bin/bootloader.bin" $(BOOTLOADER_POS) bin' \
+    -c 'echo "Installing partition table at $(PARTITION_POS)"' \
+    -c 'flash write_image erase "$(BINDIR)/partitions.bin" $(PARTITION_POS) bin'
+  IMAGE_OFFSET = 0x10000
+  # Flash checksumming not supported on xtensa
+  OPENOCD_SKIP_VERIFY = yes
+  # Without resets debug target fails with 'Target not examined yet'
+  OPENOCD_DBG_EXTRA_CMD += -c 'reset halt'
+endif

cpu/esp_common/Makefile.include

@@ -108,3 +108,45 @@ PROGRAMMER ?= esptool
 
 # Add esptool in the list supported programmers
 PROGRAMMERS_SUPPORTED += esptool
+
+# The ELFFILE is defined by default in $(RIOTBASE)/Makefile.include but only
+# after this file is included, so we need ELFFILE defined earlier.
+# This is used to create new make rules in this file (based on FLASHFILE)
+# and can't be deferred.
+ELFFILE ?= $(BINDIR)/$(APPLICATION).elf
+FLASHFILE ?= $(ELFFILE).bin
+
+ESPTOOL ?= $(RIOTTOOLS)/esptool/esptool.py
+
+# This is the binary that ends up programmed in the flash.
+$(ELFFILE).bin: $(ELFFILE)
+	$(Q)$(ESPTOOL) --chip $(FLASH_CHIP) elf2image --flash_mode $(FLASH_MODE) \
+		--flash_size $(FLASH_SIZE)MB --flash_freq $(FLASH_FREQ) $(FLASH_OPTS) \
+		-o $@ $<
+
+
+# Convert .elf and .csv to .bin files at build time, but make them available for
+# tests at flash time. These can't be added to FLASHDEPS because they depend on
+# on ELFFILE and would trigger a rebuild with "flash-only".
+BUILD_FILES += $(FLASHFILE) $(BINDIR)/partitions.bin
+TEST_EXTRA_FILES += $(FLASHFILE) $(BINDIR)/partitions.bin
+
+# Default partition table with no OTA. Can be replaced with a custom partition
+# table setting PARTITION_TABLE_CSV.
+PARTITION_TABLE_CSV ?= $(BINDIR)/partitions.csv
+
+$(BINDIR)/partitions.csv: $(FLASHFILE)
+	$(Q)printf "\n" > $(BINDIR)/partitions.csv
+	$(Q)printf "nvs, data, nvs, 0x9000, 0x6000\n" >> $@
+	$(Q)printf "phy_init, data, phy, 0xf000, 0x1000\n" >> $@
+	$(Q)printf "factory, app, factory, 0x10000, " >> $@
+	$(Q)ls -l $< | awk '{ print $$5 }' >> $@
+
+$(BINDIR)/partitions.bin: $(PARTITION_TABLE_CSV)
+	$(Q)python3 $(RIOTTOOLS)/esptool/gen_esp32part.py --verify $< $@
+
+# Convert .elf and .csv to .bin files at build time, but make them available for
+# tests at flash time. These can't be added to FLASHDEPS because they depend on
+# on ELFFILE and would trigger a rebuild with "flash-only".
+BUILD_FILES += $(FLASHFILE) $(BINDIR)/partitions.bin
+TEST_EXTRA_FILES += $(FLASHFILE) $(BINDIR)/partitions.bin

dist/tools/openocd/openocd.sh

@@ -113,6 +113,8 @@
 : ${OPENOCD_CMD_RESET_RUN:="-c 'reset run'"}
 # Select core on multi-core processors.
 : ${OPENOCD_CORE:=}
+# Set to any value to skip verifying after flashing.
+: ${OPENOCD_SKIP_VERIFY:=}
 # This is an optional offset to the base address that can be used to flash an
 # image in a different location than it is linked at. This feature can be useful
 # when flashing images for firmware swapping/remapping boot loaders.
@@ -328,6 +330,9 @@ do_flash() {
             exit $RETVAL
         fi
     fi
+    if [ -z "${OPENOCD_SKIP_VERIFY}" ]; then
+        OPENOCD_VERIFY="-c 'verify_image \"${IMAGE_FILE}\" ${IMAGE_OFFSET}'"
+    fi
 
     # In case of binary file, IMAGE_OFFSET should include the flash base address
     # This allows flashing normal binary files without env configuration
@@ -358,7 +363,7 @@ do_flash() {
             ${OPENOCD_PRE_FLASH_CMDS} \
             -c 'flash write_image erase \"${IMAGE_FILE}\" ${IMAGE_OFFSET} ${IMAGE_TYPE}' \
             ${OPENOCD_PRE_VERIFY_CMDS} \
-            -c 'verify_image \"${IMAGE_FILE}\" ${IMAGE_OFFSET}' \
+            ${OPENOCD_VERIFY} \
             -c 'reset run' \
             -c 'shutdown'" &&
     echo 'Done flashing'

makefiles/tools/esptool.inc.mk

@@ -9,19 +9,6 @@ BOOTLOADER_BIN = bootloader$(BOOTLOADER_COLOR)$(BOOTLOADER_INFO).bin
 
 ESPTOOL ?= $(RIOTTOOLS)/esptool/esptool.py
 
-# The ELFFILE is defined by default in $(RIOTBASE)/Makefile.include but only
-# after the $(PROGRAMMER).inc.mk file is included, so we need ELFFILE defined
-# earlier. This is used to create new make rules in this file (based on
-# FLASHFILE) and can't be deferred.
-ELFFILE ?= $(BINDIR)/$(APPLICATION).elf
-FLASHFILE ?= $(ELFFILE).bin
-
-# Convert .elf and .csv to .bin files at build time, but make them available for
-# tests at flash time. These can't be added to FLASHDEPS because they depend on
-# on ELFFILE and would trigger a rebuild with "flash-only".
-BUILD_FILES += $(FLASHFILE) $(BINDIR)/partitions.bin
-TEST_EXTRA_FILES += $(FLASHFILE) $(BINDIR)/partitions.bin
-
 # flasher configuration
 ifneq (,$(filter esp_qemu,$(USEMODULE)))
   FLASHER =
@@ -38,26 +25,6 @@ else
   FFLAGS += 0x10000 $(FLASHFILE)
 endif
 
-# This is the binary that ends up programmed in the flash.
-$(ELFFILE).bin: $(ELFFILE)
-	$(Q)$(ESPTOOL) --chip $(FLASH_CHIP) elf2image --flash_mode $(FLASH_MODE) \
-		--flash_size $(FLASH_SIZE)MB --flash_freq $(FLASH_FREQ) $(FLASH_OPTS) \
-		-o $@ $<
-
-# Default partition table with no OTA. Can be replaced with a custom partition
-# table setting PARTITION_TABLE_CSV.
-PARTITION_TABLE_CSV ?= $(BINDIR)/partitions.csv
-
-$(BINDIR)/partitions.csv: $(FLASHFILE)
-	$(Q)printf "\n" > $(BINDIR)/partitions.csv
-	$(Q)printf "nvs, data, nvs, 0x9000, 0x6000\n" >> $@
-	$(Q)printf "phy_init, data, phy, 0xf000, 0x1000\n" >> $@
-	$(Q)printf "factory, app, factory, 0x10000, " >> $@
-	$(Q)ls -l $< | awk '{ print $$5 }' >> $@
-
-$(BINDIR)/partitions.bin: $(PARTITION_TABLE_CSV)
-	$(Q)python3 $(RIOTTOOLS)/esptool/gen_esp32part.py --verify $< $@
-
 .PHONY: esp-qemu
 
 esp-qemu:

makefiles/tools/openocd.inc.mk

@@ -49,13 +49,30 @@ ifneq (,$(OPENOCD_CMD_RESET_RUN))
   $(call target-export-variables,reset,OPENOCD_CMD_RESET_RUN)
 endif
 
-OPENOCD_FLASH_TARGETS = flash flash-only
+OPENOCD_DEBUG_TARGETS = debug debugr debug-server
+
+ifneq (,$(OPENOCD_DBG_EXTRA_CMD))
+  # Export OPENOCD_DBG_EXTRA_CMD only to the flash/flash-only target
+  $(call target-export-variables,$(OPENOCD_DEBUG_TARGETS),OPENOCD_DBG_EXTRA_CMD)
+endif
+
+OPENOCD_FLASH_TARGETS = flash flash-only flashr
+
+ifneq (,$(IMAGE_OFFSET))
+  # Export IMAGE_OFFSET only to the flash/flash-only target
+  $(call target-export-variables,$(OPENOCD_FLASH_TARGETS),IMAGE_OFFSET)
+endif
 
 ifneq (,$(OPENOCD_PRE_VERIFY_CMDS))
   # Export OPENOCD_PRE_VERIFY_CMDS only to the flash/flash-only target
   $(call target-export-variables,$(OPENOCD_FLASH_TARGETS),OPENOCD_PRE_VERIFY_CMDS)
 endif
 
+ifneq (,$(OPENOCD_SKIP_VERIFY))
+  # Export OPENOCD_SKIP_VERIFY only to the flash/flash-only target
+  $(call target-export-variables,$(OPENOCD_FLASH_TARGETS),OPENOCD_SKIP_VERIFY)
+endif
+
 ifneq (,$(OPENOCD_PRE_FLASH_CMDS))
   # Export OPENOCD_PRE_FLASH_CMDS only to the flash/flash-only targets
   $(call target-export-variables,$(OPENOCD_FLASH_TARGETS),OPENOCD_PRE_FLASH_CMDS)