Add standard upload method variables

targets/upload_method_cfg/K64F.cmake

@@ -3,11 +3,10 @@
 # include app.cmake and where you add mbed os as a subdirectory.
 #
 # Notes:
-# 1. PyOCD did not actually work in my testing as of Apr 2024, though this device is supposed to be supported
-# 2. Be sure to update the DAPLink firmware on the board via these instructions: https://os.mbed.com/blog/entry/DAPLink-bootloader-update/
-# 3. OpenOCD 0.12 flashes this device perfectly and can enter a debug session, but cannot hit breakpoints
-# 4. LinkServer can both flash and debug, so it's the recommended upload method for this device.
-# 5. LinkServer does appear to have a bug where it doesn't map the peripheral registers as valid memory, so you can't
+# 1. Be sure to update the DAPLink firmware on the board via these instructions: https://os.mbed.com/blog/entry/DAPLink-bootloader-update/
+# 2. OpenOCD 0.12 flashes this device perfectly and can enter a debug session, but cannot hit breakpoints
+# 3. LinkServer can both flash and debug, so it's the recommended upload method for this device.
+# 4. LinkServer does appear to have a bug where it doesn't map the peripheral registers as valid memory, so you can't
 #    inspect them.  I was able to work around this by inserting a block like this into <LinkServer install dir>/devices/FRDM-K64F.json:
 #
 #         "name": "MK64FN1M0xxx12",

tools/cmake/UploadMethodManager.cmake

@@ -2,34 +2,75 @@
 # SPDX-License-Identifier: Apache-2.0
 
 # ----------------------------------------------
-# Load the upload method that the user selects
+# Common upload method options
 
 # This variable should have been set in app.cmake or by the upload method cfg file, sanity check here
 if(NOT DEFINED UPLOAD_METHOD_DEFAULT)
 	message(FATAL_ERROR "UPLOAD_METHOD_DEFAULT not found.")
 endif()
 
+## Upload method
 set(UPLOAD_METHOD "${UPLOAD_METHOD_DEFAULT}" CACHE STRING "Method for uploading programs to the mbed")
 
-# use a higher numbered port to allow use without root on Linux/Mac
-set(GDB_PORT 23331 CACHE STRING "Port that the GDB server will be started on.")
-
-# Upload methods must be uppercase, guard against the user making a mistake (since Windows will allow opening
-# an include file with the wrong case, the error message gets confusing)
+# Upload methods must be uppercase, guard against the user making a mistake (since Windows and Mac will allow including
+# an include file with the wrong case, the error that happens later gets confusing)
 string(TOUPPER "${UPLOAD_METHOD}" UPLOAD_METHOD_UCASE)
 if(NOT "${UPLOAD_METHOD_UCASE}" STREQUAL "${UPLOAD_METHOD}")
 	message(WARNING "UPLOAD_METHOD value should be uppercase.  It has been automatically changed to \"${UPLOAD_METHOD_UCASE}\".")
 	set(UPLOAD_METHOD "${UPLOAD_METHOD_UCASE}" CACHE STRING "" FORCE)
 endif()
 
-# Load the upload method.  This is expected to set the following variables:
-# UPLOAD_${UPLOAD_METHOD}_FOUND - True iff the dependencies for this upload method were found
-# UPLOAD_SUPPORTS_DEBUG - True iff this upload method supports debugging
-# UPLOAD_GDBSERVER_DEBUG_COMMAND - Command to start a new GDB server
-# UPLOAD_WANTS_EXTENDED_REMOTE - True iff GDB should use "target extended-remote" to connect to the GDB server
-# UPLOAD_LAUNCH_COMMANDS - List of GDB commands to run after launching GDB.
-# UPLOAD_RESTART_COMMANDS - List of GDB commands to run when the "restart chip" function is used.
+## GDB port
+# use a higher numbered port to allow use without root on Linux/Mac
+set(MBED_GDB_PORT 23331 CACHE STRING "Port that the GDB server will be started on.")
+
+## Upload tool serial number
+set(MBED_UPLOAD_SERIAL_NUMBER "" CACHE STRING "Serial number of the Mbed board or the programming tool, for upload methods that select by serial number.")
+
+# Handle legacy per-upload-method aliases for the upload serial number
+foreach(LEGACY_VAR_NAME JLINK_USB_SERIAL_NUMBER LINKSERVER_PROBE_SN MBED_TARGET_UID OPENOCD_ADAPTER_SERIAL PYOCD_PROBE_UID STLINK_SERIAL_ARGUMENT STM32CUBE_PROBE_SN)
+    if(DEFINED ${LEGACY_VAR_NAME})
+		if(NOT "${${LEGACY_VAR_NAME}}" STREQUAL "")
+			message(WARNING "${LEGACY_VAR_NAME} is deprecated, set the MBED_UPLOAD_SERIAL_NUMBER variable instead. MBED_UPLOAD_SERIAL_NUMBER will be set to the value of ${LEGACY_VAR_NAME}.")
+			set(MBED_UPLOAD_SERIAL_NUMBER ${${LEGACY_VAR_NAME}} CACHE STRING "" FORCE)
+		endif()
+	endif()
+endforeach()
+
+## Upload base address
+if(NOT DEFINED MBED_UPLOAD_BASE_ADDR OR "${MBED_UPLOAD_BASE_ADDR}" STREQUAL "")
+	set(BASE_ADDR_DESCRIPTION "Base address for uploading code, i.e. the memory address where the first byte of the bin/hex file will get loaded to (with 0x prefix).  Generally should point to the start of the desired flash bank and defaults to the configured start of the primary ROM bank (MBED_CONFIGURED_ROM_START).")
+	if(MBED_CONFIG_DEFINITIONS MATCHES "MBED_CONFIGURED_ROM_START=(0x[0-9a-zA-Z]+)")
+		set(MBED_UPLOAD_BASE_ADDR ${CMAKE_MATCH_1} CACHE STRING ${BASE_ADDR_DESCRIPTION})
+	else()
+		if(NOT ${UPLOAD_METHOD} STREQUAL "NONE")
+			message(FATAL_ERROR "Since no ROM banks have been defined, you need to set the MBED_UPLOAD_BASE_ADDR option so we know where to upload code.  NOTE: If you upgraded from an old version of Mbed CE and are getting this error, delete and reconfigure your CMake build directory.")
+		endif()
+	endif()
+endif()
+
+
+set(MBED_UPLOAD_SERIAL_NUMBER "" CACHE STRING "Serial number of the Mbed board or the programming tool, for upload methods that select by serial number.")
+
+
+# ----------------------------------------------
+# Load the upload method.
+# Upload methods are expected to refer to the following variables:
+# - MBED_UPLOAD_SERIAL_NUMBER - USB serial number of the mbed board or of the programmer
+# - MBED_UPLOAD_BASE_ADDR - Base address of the flash where the bin file will be updated
+#
+# Upload methods are expected to set the following variables:
+# - UPLOAD_${UPLOAD_METHOD}_FOUND - True iff the dependencies for this upload method were found
+# - UPLOAD_SUPPORTS_DEBUG - True iff this upload method supports debugging
+# - UPLOAD_GDBSERVER_DEBUG_COMMAND - Command to start a new GDB server
+# - UPLOAD_WANTS_EXTENDED_REMOTE - True iff GDB should use "target extended-remote" to connect to the GDB server
+# - UPLOAD_LAUNCH_COMMANDS - List of GDB commands to run after launching GDB.
+# - UPLOAD_RESTART_COMMANDS - List of GDB commands to run when the "restart chip" function is used.
 # See here for more info: https://github.com/mbed-ce/mbed-os/wiki/Debugger-Commands-and-State-in-Upload-Methods
+#
+# WARNING: Upload method files are included during the add_subdirectory(mbed-os) call in the top-level CMakeLists.txt.  This means that
+# if you declare variables in an upload method script, you have to save them as CACHE INTERNAL (or PARENT_SCOPE) so that they are accessible
+# to code running outside of the mbed-os subdirectory.
 include(UploadMethod${UPLOAD_METHOD})
 
 if(NOT "${UPLOAD_${UPLOAD_METHOD}_FOUND}")

tools/cmake/upload_methods/UploadMethodJLINK.cmake

@@ -7,7 +7,6 @@
 # JLINK_CLOCK_SPEED - Speed to run the J-Link at, in KHz.
 # JLINK_CPU_NAME - Name of CPU to pass to J-Link
 #   This method has the following options:
-# JLINK_USB_SERIAL_NUMBER - Use a J-Link connected over USB with the specified serial number.
 # JLINK_NETWORK_ADDRESS - Use a J-Link connected over the network with the given <ip addr>[:port]
 # JLINK_NO_GUI - If set to true, suppress GUI dialog boxes from the J-Link software.
 #
@@ -19,14 +18,13 @@ find_package(JLINK)
 set(UPLOAD_JLINK_FOUND ${JLINK_FOUND})
 
 ### Setup options
-set(JLINK_USB_SERIAL_NUMBER "" CACHE STRING "Use a J-Link connected over USB with the specified serial number.")
 set(JLINK_NETWORK_ADDRESS "" CACHE STRING "Use a J-Link connected over the network with the given <ip addr>[:port]")
 
 # Figure out -select option.  See here: https://wiki.segger.com/J-Link_GDB_Server#-select
-if((NOT "${JLINK_USB_SERIAL_NUMBER}" STREQUAL "") AND (NOT "${JLINK_NETWORK_ADDRESS}" STREQUAL ""))
-	message(FATAL_ERROR "Cannot use both JLINK_USB_SERIAL_NUMBER and JLINK_NETWORK_ADDRESS at the same time!")
-elseif(NOT "${JLINK_USB_SERIAL_NUMBER}" STREQUAL "")
-	set(JLINK_SELECT_ARG -Select usb=${JLINK_USB_SERIAL_NUMBER} CACHE INTERNAL "" FORCE)
+if((NOT "${MBED_UPLOAD_SERIAL_NUMBER}" STREQUAL "") AND (NOT "${JLINK_NETWORK_ADDRESS}" STREQUAL ""))
+	message(FATAL_ERROR "Cannot use both MBED_UPLOAD_SERIAL_NUMBER and JLINK_NETWORK_ADDRESS at the same time!")
+elseif(NOT "${MBED_UPLOAD_SERIAL_NUMBER}" STREQUAL "")
+	set(JLINK_SELECT_ARG -Select usb=${MBED_UPLOAD_SERIAL_NUMBER} CACHE INTERNAL "" FORCE)
 elseif(NOT "${JLINK_NETWORK_ADDRESS}" STREQUAL "")
 	set(JLINK_SELECT_ARG -Select ip=${JLINK_NETWORK_ADDRESS} CACHE INTERNAL "" FORCE)
 else()
@@ -51,8 +49,11 @@ function(gen_upload_target TARGET_NAME BINARY_FILE)
 
 	# create command file for j-link
 	set(COMMAND_FILE_PATH ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/flash-${TARGET_NAME}.jlink)
+
+	# Note: loadfile currently only honors the base address for .bin files.  For hex files it uses the offset read
+	# from the hex file.  Unsure if that will be an issue or not...
 	file(GENERATE OUTPUT ${COMMAND_FILE_PATH} CONTENT
-"loadfile ${BINARY_FILE}
+"loadfile ${BINARY_FILE} ${MBED_UPLOAD_BASE_ADDR}
 r
 go
 exit

tools/cmake/upload_methods/UploadMethodLINKSERVER.cmake

@@ -4,18 +4,15 @@
 ### NXP LinkServer Upload Method
 # This method needs the following parameters:
 # LINKSERVER_DEVICE - Chip name and board to connect to, separated by a colon.
-# LINKSERVER_PROBE_SN - Serial number, or serial number substring, of the debug probe to connect to.  If blank, will connect to any probe.
 
 set(UPLOAD_SUPPORTS_DEBUG TRUE)
 
 ### Handle options
-set(LINKSERVER_PROBE_SN "" CACHE STRING "Serial number, or serial number substring, of the debug probe to connect to.  If blank, will connect to any probe.")
-
-if("${LINKSERVER_PROBE_SN}" STREQUAL "")
+if("${MBED_UPLOAD_SERIAL_NUMBER}" STREQUAL "")
 	# This argument causes Redlink to connect to the first available debug probe
 	set(LINKSERVER_PROBE_ARGS "" CACHE INTERNAL "" FORCE)
 else()
-	set(LINKSERVER_PROBE_ARGS --probe ${LINKSERVER_PROBE_SN} CACHE INTERNAL "" FORCE)
+	set(LINKSERVER_PROBE_ARGS --probe ${MBED_UPLOAD_SERIAL_NUMBER} CACHE INTERNAL "" FORCE)
 endif()
 
 if("${LINKSERVER_DEVICE}" STREQUAL "")
@@ -37,7 +34,8 @@ function(gen_upload_target TARGET_NAME BINARY_FILE)
 			${LINKSERVER_PROBE_ARGS}
 			${LINKSERVER_DEVICE}
 			load
-			$<TARGET_FILE:${TARGET_NAME}>)
+			--addr ${MBED_UPLOAD_BASE_ADDR}
+			${BINARY_FILE})
 
 	add_dependencies(flash-${TARGET_NAME} ${TARGET_NAME})
 

tools/cmake/upload_methods/UploadMethodMBED.cmake

@@ -2,7 +2,6 @@
 # This method needs the following parameters:
 # MBED_RESET_BAUDRATE - Serial baudrate to connect to the target at when resetting it.
 # This method creates the following options:
-# MBED_TARGET_UID - Probe UID to pass to commands. You can get the UIDs from `python -m pyocd list`.
 
 set(UPLOAD_SUPPORTS_DEBUG FALSE)
 
@@ -13,8 +12,6 @@ if(NOT DEFINED MBED_RESET_BAUDRATE)
 	set(MBED_RESET_BAUDRATE 9600)
 endif()
 
-set(MBED_TARGET_UID "" CACHE STRING "UID of mbed target to upload to if there are multiple connected.  You can get the UIDs from `python -m pyocd list`")
-
 ### Function to generate upload target
 function(gen_upload_target TARGET_NAME BINARY_FILE)
 
@@ -23,7 +20,7 @@ function(gen_upload_target TARGET_NAME BINARY_FILE)
 			${BINARY_FILE}
 			${MBED_TARGET}
 			${MBED_RESET_BAUDRATE}
-			${MBED_TARGET_UID}
+			${MBED_UPLOAD_SERIAL_NUMBER}
 		WORKING_DIRECTORY
 			${mbed-os_SOURCE_DIR}/tools/python
 		VERBATIM)

tools/cmake/upload_methods/UploadMethodOPENOCD.cmake

@@ -4,8 +4,9 @@
 ### OpenOCD Upload Method
 # This method needs the following parameters:
 # OPENOCD_CHIP_CONFIG_COMMANDS - Specifies all OpenOCD commands needed to configure openocd for your target processor.
+# OPENOCD_LOAD_ADDRESS - Address where the bin or hex file will be loaded to memory, e.g. 0x8000000.  If not set, will default to
+#     the configured address of the first ROM bank (MBED_CONFIGURED_ROM_START)
 # This method creates the following options:
-# OPENOCD_ADAPTER_SERIAL - Serial number of the debug adapter to select for OpenOCD.  Set to empty to detect any matching adapter.
 # OPENOCD_VERSION_RANGE - Acceptable version range of OpenOCD.  This may be a single version, in which case it is treated as
 #   a minimum, or a versionMin...<versionMax constraint, e.g. 0.12...<0.13, to accept any 0.12.x version but not 0.13 or higher.
 
@@ -15,12 +16,9 @@ set(UPLOAD_SUPPORTS_DEBUG TRUE)
 find_package(OpenOCD ${OPENOCD_VERSION_RANGE})
 set(UPLOAD_OPENOCD_FOUND ${OpenOCD_FOUND})
 
-### Setup options
-set(OPENOCD_ADAPTER_SERIAL "" CACHE STRING "Serial number of the debug adapter to select for OpenOCD.  Set to empty to detect any matching adapter.")
-
 ### Function to generate upload target
 set(OPENOCD_ADAPTER_SERIAL_COMMAND "" CACHE INTERNAL "" FORCE)
-if(NOT "${OPENOCD_ADAPTER_SERIAL}" STREQUAL "")
+if(NOT "${MBED_UPLOAD_SERIAL_NUMBER}" STREQUAL "")
 
 	# Generate script file that tells OpenOCD how to find the correct debug adapter.
 	file(GENERATE OUTPUT ${CMAKE_BINARY_DIR}/openocd_adapter_config.cfg CONTENT
@@ -29,7 +27,7 @@ if(NOT "${OPENOCD_ADAPTER_SERIAL}" STREQUAL "")
 
 # There's supposed to be a standard command to select the adapter serial ('adapter serial'), but it seems
 # like not all adapters support this yet so extra work is needed.
-set adapter_serial \"${OPENOCD_ADAPTER_SERIAL}\"
+set adapter_serial \"${MBED_UPLOAD_SERIAL_NUMBER}\"
 if { [adapter name] == \"hla\" } {
 	hla_serial $adapter_serial
 } elseif { [adapter name] == \"cmsis-dap\" } {
@@ -50,7 +48,7 @@ function(gen_upload_target TARGET_NAME BINARY_FILE)
 		${OPENOCD_CHIP_CONFIG_COMMANDS}
 		${OPENOCD_ADAPTER_SERIAL_COMMAND}
 		-c "gdb_port disabled" # Don't start a GDB server when just programming
-		-c "program ${BINARY_FILE} reset exit"
+		-c "program ${BINARY_FILE} ${MBED_UPLOAD_BASE_ADDR} reset exit"
 		VERBATIM)
 
 	add_dependencies(flash-${TARGET_NAME} ${TARGET_NAME})

tools/cmake/upload_methods/UploadMethodPYOCD.cmake

@@ -5,8 +5,6 @@
 # This method needs the following parameters:
 # PYOCD_TARGET_NAME - Name of your processor as passed to the -t option of pyOCD. This is usually the full or partial model number.
 # PYOCD_CLOCK_SPEED - Clock speed of the JTAG or SWD connection. Default is in Hz, but can use k and M suffixes for MHz and GHz
-# This method creates the following options:
-# PYOCD_PROBE_UID - Probe UID to pass to pyOCD commands. You can get the UIDs from `python -m pyocd list`.  Set to empty to detect any probe.
 
 set(UPLOAD_SUPPORTS_DEBUG TRUE)
 
@@ -15,13 +13,10 @@ include(CheckPythonPackage)
 check_python_package(pyocd HAVE_PYOCD)
 set(UPLOAD_PYOCD_FOUND ${HAVE_PYOCD})
 
-### Setup options
-set(PYOCD_PROBE_UID "" CACHE STRING "Probe UID to pass to pyOCD commands. You can get the UIDs from `python -m pyocd list`.  Set to empty to detect any probe.")
-
 ### Function to generate upload target
 set(PYOCD_PROBE_ARGS "" CACHE INTERNAL "" FORCE)
-if(NOT "${PYOCD_PROBE_UID}" STREQUAL "")
-	set(PYOCD_PROBE_ARGS --probe ${PYOCD_PROBE_UID} CACHE INTERNAL "" FORCE)
+if(NOT "${MBED_UPLOAD_SERIAL_NUMBER}" STREQUAL "")
+	set(PYOCD_PROBE_ARGS --probe ${MBED_UPLOAD_SERIAL_NUMBER} CACHE INTERNAL "" FORCE)
 endif()
 
 function(gen_upload_target TARGET_NAME BINARY_FILE)
@@ -36,6 +31,7 @@ function(gen_upload_target TARGET_NAME BINARY_FILE)
 		-f ${PYOCD_CLOCK_SPEED}
 		-t ${PYOCD_TARGET_NAME}
 		${PYOCD_PROBE_ARGS}
+		--base-address ${MBED_UPLOAD_BASE_ADDR}
 		${BINARY_FILE})
 
 	add_dependencies(flash-${TARGET_NAME} ${TARGET_NAME})

tools/cmake/upload_methods/UploadMethodSTLINK.cmake

@@ -15,8 +15,8 @@ if(stlink_FOUND AND (stlink_VERSION VERSION_LESS 1.7.0))
 endif()
 
 ### Figure out --serial argument
-if(DEFINED STLINK_PROBE_SN AND NOT "${STLINK_PROBE_SN}" STREQUAL "")
-	set(STLINK_SERIAL_ARGUMENT --serial ${STLINK_PROBE_SN} CACHE INTERNAL "" FORCE)
+if(DEFINED MBED_UPLOAD_SERIAL_NUMBER AND NOT "${MBED_UPLOAD_SERIAL_NUMBER}" STREQUAL "")
+	set(STLINK_SERIAL_ARGUMENT --serial ${MBED_UPLOAD_SERIAL_NUMBER} CACHE INTERNAL "" FORCE)
 else()
 	set(STLINK_SERIAL_ARGUMENT "" CACHE INTERNAL "" FORCE)
 endif()
@@ -30,7 +30,7 @@ function(gen_upload_target TARGET_NAME BINARY_FILE)
 		--reset # Reset chip after flashing
 		${STLINK_SERIAL_ARGUMENT}
 		${STLINK_ARGS}
-		write ${BINARY_FILE} ${STLINK_LOAD_ADDRESS})
+		write ${BINARY_FILE} ${MBED_UPLOAD_BASE_ADDR})
 
 	add_dependencies(flash-${TARGET_NAME} ${TARGET_NAME})
 endfunction(gen_upload_target)

tools/cmake/upload_methods/UploadMethodSTM32CUBE.cmake

@@ -5,10 +5,6 @@
 # This method needs the following parameters:
 # STM32CUBE_CONNECT_COMMAND - "Connect" (-c) command to pass to the programmer
 # STM32CUBE_GDBSERVER_ARGS - Arguments to pass to the ST-Link gdbserver.
-# This method creates the following options:
-# STM32CUBE_PROBE_SN - Serial number of the ST-Link probe to connect to.  If blank, will connect to any probe.
-
-set(STM32CUBE_PROBE_SN "" CACHE STRING "Serial number of the ST-Link probe to connect to.  If blank, will connect to any probe.")
 
 ### Check if upload method can be enabled on this machine
 find_package(STLINKTools COMPONENTS STM32CubeProg OPTIONAL_COMPONENTS STLINK_gdbserver)
@@ -25,9 +21,9 @@ endif()
 set(STM32CUBE_UPLOAD_PROBE_ARGS "" CACHE INTERNAL "" FORCE)
 set(STM32CUBE_GDB_PROBE_ARGS "" CACHE INTERNAL "" FORCE)
 
-if(NOT "${STM32CUBE_PROBE_SN}" STREQUAL "")
-	set(STM32CUBE_UPLOAD_PROBE_ARGS sn=${STM32CUBE_PROBE_SN} CACHE INTERNAL "" FORCE)
-	set(STM32CUBE_GDB_PROBE_ARGS --serial-number ${STM32CUBE_PROBE_SN} CACHE INTERNAL "" FORCE)
+if(NOT "${MBED_UPLOAD_SERIAL_NUMBER}" STREQUAL "")
+	set(STM32CUBE_UPLOAD_PROBE_ARGS sn=${MBED_UPLOAD_SERIAL_NUMBER} CACHE INTERNAL "" FORCE)
+	set(STM32CUBE_GDB_PROBE_ARGS --serial-number ${MBED_UPLOAD_SERIAL_NUMBER} CACHE INTERNAL "" FORCE)
 endif()
 
 function(gen_upload_target TARGET_NAME BINARY_FILE)
@@ -37,7 +33,7 @@ function(gen_upload_target TARGET_NAME BINARY_FILE)
 		COMMAND ${STM32CubeProg_COMMAND}
 		${STM32CUBE_CONNECT_COMMAND}
 		${STM32CUBE_UPLOAD_PROBE_ARGS} # probe arg must be immediately after -c command as it gets appended to -c
-		-w "$<TARGET_FILE:${TARGET_NAME}>"
+		-w ${BINARY_FILE} ${MBED_UPLOAD_BASE_ADDR}
 		-rst)
 
 	add_dependencies(flash-${TARGET_NAME} ${TARGET_NAME})