esp_common.cfg

# SPDX-License-Identifier: GPL-2.0-or-later
#

set CPU_MAX_ADDRESS 0xFFFFFFFF
source [find bitsbytes.tcl]
source [find memory.tcl]
source [find mmr_helpers.tcl]

catch {[source [find target/esp_version.cfg]]}
set _OPENOCD_VER [ version ]
if { [info exists EXPECTED_VER] && [string first $EXPECTED_VER $_OPENOCD_VER] == -1 } {
    echo "WARNING!!! OpenOCD binary version ($_OPENOCD_VER) doesn't match the .cfg file version ($EXPECTED_VER)"
}

# Riscv Debug Module Registers which are used around esp configuration files.
set _RISCV_ABS_DATA0    0x04
set _RISCV_DMCONTROL    0x10
set _RISCV_HAWINDOWSEL  0x14
set _RISCV_HAWINDOW     0x15
set _RISCV_ABS_CMD      0x17
set _RISCV_SB_CS        0x38
set _RISCV_SB_ADDR0     0x39
set _RISCV_SB_DATA0     0x3C

# Common ESP chips definitions
set _RTOS "FreeRTOS"
if { [info exists ESP_RTOS] } {
	set _RTOS "$ESP_RTOS"
}

# by default current dir (when OOCD has been started)
set _SEMIHOST_BASEDIR "."
if { [info exists ESP_SEMIHOST_BASEDIR] } {
	set _SEMIHOST_BASEDIR $ESP_SEMIHOST_BASEDIR
}

set _FLASH_SIZE "auto"
if { [info exists ESP_FLASH_SIZE] } {
	set _FLASH_SIZE $ESP_FLASH_SIZE
}

set _ESP_IDF_HOST "0"
if { [info exists ESP_IDF_HOST] } {
	set _ESP_IDF_HOST $ESP_IDF_HOST
}

if { [info exists ESP_ONLYCPU] } {
	set _ONLYCPU $ESP_ONLYCPU
}


# Default values.
set _CHIP_LP_NAME       "lp"
set _LP_TAPNUM          0
# Some default values can be overridden in config files which includes this one
if { ![info exists _ESP_SMP_TARGET] } {
	set _ESP_SMP_TARGET	0
}
if { ![info exists _NO_FLASH_FORCES_HW_BPS] } {
	# TODO: Should allow to use SW breakpoints when flash support is disabled
	# by default currently only HW bps can be used when flash is disabled
	set _NO_FLASH_FORCES_HW_BPS 1
}

proc set_esp_common_variables { } {
	global _CHIPNAME _CHIP_LP_NAME _CHIP_HP_NAME _ONLYCPU _ESP_SMP_TARGET
	global _CPUNAME _CPUNAME_0 _CPUNAME_1 _TARGETNAME_LP _TARGETNAME_0 _TARGETNAME_1
	global _ESP_WDT_DISABLE _ESP_SOC_RESET _ESP_MEMPROT_IS_ENABLED

	if { $_ONLYCPU == 0x1 && $_ESP_SMP_TARGET == 0 } {
		# If we will have just one target including LP core, we can name it as <chip_name>.cpu
		set _TARGETNAME_0               $_CHIPNAME
		set _CPUNAME_0                  cpu
	} else {
		set _CPUNAME                    cpu
		set _CPUNAME_0                  cpu0
		set _CPUNAME_1                  cpu1
		set _TARGETNAME_LP              $_CHIP_LP_NAME.$_CPUNAME
		set _TARGETNAME_0               $_CHIP_HP_NAME.$_CPUNAME_0
		set _TARGETNAME_1               $_CHIP_HP_NAME.$_CPUNAME_1
	}

	set _ESP_WDT_DISABLE                "${_CHIPNAME}_wdt_disable"
	set _ESP_SOC_RESET                  "${_CHIPNAME}_soc_reset"
	set _ESP_MEMPROT_IS_ENABLED         "${_CHIPNAME}_memprot_is_enabled"
}

proc create_esp_jtag { } {
	global _CHIPNAME _CPUTAPID _LP_TAPNUM _HP_TAPNUM

	set next_tap_num 0

	# LP core will be at the first tap
	if { $_LP_TAPNUM > 0 } {
		jtag newtap $_CHIPNAME tap0 -irlen 5 -expected-id $_CPUTAPID

		if { $_HP_TAPNUM > 0 } {
			set next_tap_num 1
		}
	}

	# Other cores will be at the first tap or at the next tap
	for {set i 0} {$i < $_HP_TAPNUM} {incr i} {
		jtag newtap $_CHIPNAME tap$next_tap_num -irlen 5 -expected-id $_CPUTAPID
		incr next_tap_num
	}
}

proc create_openocd_targets  { } {
	global _TARGETNAME_LP _TARGETNAME_0 _TARGETNAME_1 _RTOS _CHIPNAME
	global _ONLYCPU _ESP_SMP_TARGET _CHIP_LP_NAME _LP_TAPNUM _HP_TAPNUM _CPUNAME

	set next_tap_num 0

	if { $_LP_TAPNUM > 0 && $_HP_TAPNUM > 0 } {
		set next_tap_num 1
	}

	# First of all create main targets
	target create $_TARGETNAME_0 $_CHIPNAME -chain-position $_CHIPNAME.tap$next_tap_num -coreid 0 -rtos $_RTOS
	set next_core_id 1

	if { $_HP_TAPNUM > 1 } {
		incr next_tap_num 1
	}

	if { $_ONLYCPU & 0x02 } {
		target create $_TARGETNAME_1 $_CHIPNAME -chain-position $_CHIPNAME.tap$next_tap_num -coreid $next_core_id -rtos $_RTOS
		incr next_core_id 1
	}

	# If we have, create the LP core target. It will be at the first tap.
	if { $_ONLYCPU & 0x10 } {
		target create $_TARGETNAME_LP $_CHIPNAME -chain-position $_CHIPNAME.tap0 -coreid $next_core_id -rtos $_RTOS
	}

	if { $_ESP_SMP_TARGET == 1 } {
		if { !($_ONLYCPU & 0x10) } {
			target smp $_TARGETNAME_0 $_TARGETNAME_1
		} elseif { $_ONLYCPU & 0x02 } {
			target smp $_TARGETNAME_0 $_TARGETNAME_1 $_TARGETNAME_LP
		} else {
			target smp $_TARGETNAME_0 $_TARGETNAME_LP
		}
		# default target is cpu0
		targets $_TARGETNAME_0
	}
}

proc create_esp_target { ARCH } {
	global _ONLYCPU

	if { !($_ONLYCPU & 0x01) } {
		program_error "** Wrong usage of _ONLYCPU variable **" 1
	}

	set_esp_common_variables
	create_esp_jtag
	create_openocd_targets
	configure_esp_flash_settings
	configure_openocd_events $ARCH

	if { $ARCH == "xtensa"} {
		configure_esp_xtensa_default_settings
	} else {
		configure_esp_riscv_default_settings
	}
}

#################### Set event handlers and default settings  ####################

proc configure_event_examine_end { } {
	global _TARGETNAME_0 _TARGETNAME_1 _ONLYCPU

	$_TARGETNAME_0 configure -event examine-end {
		# Need to enable to set 'semihosting_basedir'
		arm semihosting enable
		arm semihosting_resexit enable
		if { [info exists _SEMIHOST_BASEDIR] } {
			if { $_SEMIHOST_BASEDIR != "" } {
				arm semihosting_basedir $_SEMIHOST_BASEDIR
			}
		}
	}

	if { $_ONLYCPU & 0x02 } {
		$_TARGETNAME_1 configure -event examine-end {
			# Need to enable to set 'semihosting_basedir'
			arm semihosting enable
			arm semihosting_resexit enable
			if { [info exists _SEMIHOST_BASEDIR] } {
				if { $_SEMIHOST_BASEDIR != "" } {
					arm semihosting_basedir $_SEMIHOST_BASEDIR
				}
			}
		}
	}
}

proc configure_event_reset_assert_post { } {
	global _TARGETNAME_0 _TARGETNAME_1 _ONLYCPU

	$_TARGETNAME_0 configure -event reset-assert-post {
		global _ESP_SOC_RESET
		$_ESP_SOC_RESET
	}

	# just reset one core will be enough to soc reset
}

proc configure_event_halted { } {
	global _TARGETNAME_0 _TARGETNAME_1 _ONLYCPU

	$_TARGETNAME_0 configure -event halted {
		global _ESP_WDT_DISABLE
		$_ESP_WDT_DISABLE
		esp halted_event_handler
	}

	if {$_ONLYCPU & 2} {
		$_TARGETNAME_1 configure -event halted {
			esp halted_event_handler
		}
	}
}

proc configure_event_gdb_attach { } {
	global _TARGETNAME_0 _TARGETNAME_1 _ONLYCPU

	$_TARGETNAME_0 configure -event gdb-attach {
		if { $_ESP_ARCH == "xtensa" } {
			$_TARGETNAME_0 xtensa smpbreak BreakIn BreakOut
		}
		# necessary to auto-probe flash bank when GDB is connected and generate proper memory map
		halt 1000
		if { [$_ESP_MEMPROT_IS_ENABLED] } {
			# 'reset halt' to disable memory protection and allow flasher to work correctly
			echo "Memory protection is enabled. Reset target to disable it..."
			reset halt
		}

		if { $_ESP_ARCH == "riscv" } {
			# by default mask interrupts while stepping
			riscv set_maskisr steponly
		}
	}

	if { $_ONLYCPU & 0x2 } {
		$_TARGETNAME_1 configure -event gdb-attach {
			if { $_ESP_ARCH == "xtensa" } {
				$_TARGETNAME_1 xtensa smpbreak BreakIn BreakOut
			}
			# necessary to auto-probe flash bank when GDB is connected
			halt 1000
			if { [$_ESP_MEMPROT_IS_ENABLED] } {
				# 'reset halt' to disable memory protection and allow flasher to work correctly
				echo "Memory protection is enabled. Reset target to disable it..."
				reset halt
			}
		}
	}
}

# When openocd gets the shutdown signal, it first executes shutdown commands. After that, invokes the gdb_detach event
# callbacks. This is fine for the xtensa but for the riscv, command order is important. Because we will disable the DM
# within the shutdown command
proc configure_shutdown_command_riscv { } {
	lappend ::pre_shutdown_commands { esp process_lazy_breakpoints }
	# disable debug module to clear ASSIST_DEBUG_CORE_0_DEBUG_MODULE_ACTIVE register.
	lappend ::pre_shutdown_commands { riscv dmi_write 0x10 0 }
}

proc configure_openocd_events { ARCH } {
	if { $ARCH == "riscv" } {
		configure_event_halted
		configure_shutdown_command_riscv
	}
	configure_event_examine_end
	configure_event_reset_assert_post
	configure_event_gdb_attach
}

proc configure_esp_riscv_default_settings { } {
	global _FLASH_SIZE _NO_FLASH_FORCES_HW_BPS
	if { $_FLASH_SIZE == 0 && $_NO_FLASH_FORCES_HW_BPS == 1 } {
		gdb breakpoint_override hard
	}

	riscv set_reset_timeout_sec 2
	riscv set_command_timeout_sec 5
	riscv set_mem_access sysbus progbuf abstract
	riscv set_ebreakm on
	riscv set_ebreaks on
	riscv set_ebreaku on
}

proc configure_esp_xtensa_default_settings { } {
	global _FLASH_SIZE _TARGETNAME_0 _ESP_ARCH _FLASH_VOLTAGE _CHIPNAME

	$_TARGETNAME_0 xtensa maskisr on
	if { $_ESP_ARCH == "xtensa" } {
		$_TARGETNAME_0 xtensa smpbreak BreakIn BreakOut
	}

	if { $_FLASH_SIZE == 0 && $_NO_FLASH_FORCES_HW_BPS == 1 } {
		gdb breakpoint_override hard
	}

	if { [info exists _FLASH_VOLTAGE] } {
		$_TARGETNAME_0 $_CHIPNAME flashbootstrap $_FLASH_VOLTAGE
	}
}

#################### ESP Stub flasher configuration ####################

proc configure_esp_workarea { TGT WA_ADDR WA_SZ } {
	#WARNING: be careful when selecting working ares for code and data, they should not overlap due to ESP32 physical memory mappings
	$TGT configure -work-area-phys $WA_ADDR -work-area-virt $WA_ADDR -work-area-size $WA_SZ -work-area-backup 1
}

proc configure_esp_workarea_backups { wab_list } {
	set index 0
	foreach tgt [target names] {
		$tgt configure -work-area-backup [lindex $wab_list $index]
		incr $index
	}
}

proc configure_esp_flash_bank { TGT DRV SIZE } {
	set _SIZE SIZE
	if { $SIZE == 0 } {
		echo "WARNING: ESP flash support is disabled!"
		return
	} else {
		if { $SIZE == "auto" } {
			# special value for flash driver
			set _SIZE 0
		}
	}
	# whole flash for programming purposes
	# TODO: remove it when support for GDB's 'load' comand is implemented
	flash bank $TGT.flash $DRV 0x0 $_SIZE 0 0 $TGT
	# So define mapped flash regions as separate flashes
	# OOCD creates memory map using registered flash banks
	flash bank $TGT.irom $DRV 0x0 0 0 0 $TGT
	flash bank $TGT.drom $DRV 0x0 0 0 0 $TGT
}

proc configure_esp_flash_settings { } {
	global _TARGETNAME_0 _TARGETNAME_1 _CHIPNAME _ONLYCPU
	global _WA_ADDR _WA_SIZE _FLASH_SIZE

	configure_esp_workarea $_TARGETNAME_0 $_WA_ADDR $_WA_SIZE
	configure_esp_flash_bank $_TARGETNAME_0 $_CHIPNAME $_FLASH_SIZE

	if { $_ONLYCPU & 0x2 } {
		configure_esp_flash_bank $_TARGETNAME_1 $_CHIPNAME $_FLASH_SIZE
	}
}

#################### ESP GCOV command wrapper functions ####################
proc get_openocd_env {env_name} {
    if {[info exists ::env($env_name)]} {
        return $::env($env_name)
    } else {
        return ""
    }
}

proc esp_gcov {} {
	esp gcov [get_openocd_env OPENOCD_GCOV_PREFIX] [get_openocd_env OPENOCD_GCOV_PREFIX_STRIP]
}

proc esp_gcov_dump {} {
	esp gcov dump [get_openocd_env OPENOCD_GCOV_PREFIX] [get_openocd_env OPENOCD_GCOV_PREFIX_STRIP]
}

#################### Functions to program ESP chips ####################

# special function to program ESP chip, it differs from the original 'program' that
# it verifies written image by reading flash directly, instead of reading memory mapped flash regions
proc program_esp {filename args} {
	set exit 0
	set compress 0
	set clock_boost 1
	set restore_clock 0
	set encrypt 0

	set flash_list_size [llength [flash list]]
	if { $flash_list_size == 0} {
		program_error "** ESP flash programming is not supported yet! **" $exit
	}

	echo "** program_esp input args <$args> **"

	# Place quotes around the path in case it contains spaces
	set filename "\"$filename\""

	set start_time [clock milliseconds]

	foreach arg $args {
		if {[string equal $arg "verify"]} {
			set verify 1
		} elseif {[string equal $arg "reset"]} {
			set reset 1
		} elseif {[string equal $arg "exit"]} {
			set exit 1
		} elseif {[string equal $arg "compress"]} {
			set compress 1
		} elseif {[string equal $arg "no_clock_boost"]} {
			set clock_boost 0
		} elseif {[string equal $arg "restore_clock"]} {
			set restore_clock 1
		} elseif {[string equal $arg "encrypt"]} {
			set encrypt 1
		} else {
			set address $arg
		}
	}

	if {$clock_boost == 0} {
		set restore_clock 0
	}

	# make sure init is called
	if {[catch {init}] != 0} {
		program_error "** OpenOCD init failed **" 1
	}

	# reset target and call any init scripts
	if {[catch {reset init}] != 0} {
		program_error "** Unable to reset target **" $exit
	}

	set wab_list {}
	foreach tgt [target names] {
		lappend wab_list [$tgt cget -work-area-backup]
		$tgt configure -work-area-backup 0
	}

	if {$compress == 1} {
		eval esp compression "on"
	} else {
		eval esp compression "off"
	}

	# If encrypt == 1, binary encryption will be handled by the chip.
	# Otherwise binary will be written as plaintext.
	if {$encrypt == 1} {
		eval esp encrypt_binary "yes"
	} else {
		eval esp encrypt_binary "no"
	}

	# start programming phase
	echo "** Programming Started **"
	if {[info exists address]} {
		set flash_args "$filename $address"
	} else {
		set flash_args "$filename"
	}

	if {$clock_boost == 1} {
		if {[catch {eval esp flash_stub_clock_boost "on"}] != 0} {
			program_error "** Clock configuration set failed **" $exit
		}
	}

	if {[catch {eval flash write_image erase $flash_args}] == 0} {
		set stop_time [expr {[clock milliseconds] - $start_time}]
		echo "** Programming Finished in $stop_time ms **"
		if {[info exists verify]} {
			# verify phase
			echo "** Verify Started **"
			if {[catch {eval esp verify_bank_hash 0 $flash_args}] == 0} {
				echo "** Verify OK **"
			} else {
				configure_esp_workarea_backups $wab_list
				if {$restore_clock == 1} {
					eval esp flash_stub_clock_boost "off"
				}
				program_error "** Verify Failed **" $exit
			}
		}

		configure_esp_workarea_backups $wab_list

		if {$restore_clock == 1} {
			if {[catch {eval esp flash_stub_clock_boost "off"}] != 0} {
				program_error "** Clock configuration restore failed **" $exit
			}
		}

		if {[info exists reset]} {
			# reset target if requested
			echo "** Resetting Target **"
			reset run
		}
	} else {
		configure_esp_workarea_backups $wab_list
		if {$restore_clock == 1} {
			eval esp flash_stub_clock_boost "off"
		}
		program_error "** Programming Failed **" $exit
	}

	if {$exit == 1} {
		shutdown
	}
	return
}

add_help_text program_esp "write an image to flash, address is only required for binary images. verify, reset, exit, compress, restore_clock and encrypt are optional"
add_usage_text program_esp "<filename> \[address\] \[verify\] \[reset\] \[exit\] \[compress\] \[no_clock_boost\] \[restore_clock\] \[encrypt\]"

proc program_esp_bins {build_dir filename args} {
	set exit 0
	set compress 0
	set clock_boost 1
	set restore_clock 0

	foreach arg $args {
		if {[string equal $arg "reset"]} {
			set reset 1
		} elseif {[string equal $arg "verify"]} {
			set verify 1
		} elseif {[string equal $arg "exit"]} {
			set exit 1
		} elseif {[string equal $arg "compress"]} {
			set compress 1
		} elseif {[string equal $arg "no_clock_boost"]} {
			set clock_boost 0
		} elseif {[string equal $arg "restore_clock"]} {
			set restore_clock 1
		} else {
			echo "** Unsupported arg $arg, skipping **"
		}
	}

	# Open and Read file
	set fp [open [file join $build_dir $filename] r]
	set file_data [read $fp]
	close $fp

	# Decode JSON to dict
	set flasher_args [json::decode $file_data]
	set flasher_args_keys [dict keys $flasher_args]
	set flash_files [dict get $flasher_args flash_files]

	set start_time [clock milliseconds]

	foreach addr [dict keys $flash_files] {
		set bin_file [dict get $flash_files $addr]
		set bin_file_path [file join $build_dir $bin_file]

		# Place quotes around the path in case it contains spaces
		set bin_file_path "\"$bin_file_path\""

		echo "Flashing $bin_file_path at $addr"

		if {[info exists verify]} {
			set flash_args "$bin_file_path $addr verify"
		} else {
			set flash_args "$bin_file_path $addr"
		}

		if {$compress == 1} {
			append flash_args " compress"
		}

		if {$clock_boost == 0} {
			append flash_args " no_clock_boost"
		}

		if {$restore_clock == 1} {
			append flash_args " restore_clock"
		}

		# Search inner 'offset' key in all json objects.
		# If (offset:address) is matched, get 'encrypted' value from the matched json object.
		foreach key $flasher_args_keys {
			if {[dict exists $flasher_args $key offset]} {
				if { $addr == [dict get $flasher_args $key offset] } {
					set partition_encrypted false
					if { [dict exists $flasher_args $key encrypted] } {
						set partition_encrypted [dict get $flasher_args $key encrypted]
					}
					# If partition->encrypted is true, then stub code must call flash_write_encrypted()
					# To do so, encrypt command set to be yes.
					# We can set it here or better send it as a parameter to the "program_esp" to avoid duplication.
					if { $partition_encrypted == true } {
						append flash_args " encrypt"
					}
				}
			}
		}

		set t1 [clock milliseconds]
		if {[ catch { eval program_esp  $flash_args} ] == 0} {
			set t2 [expr {[clock milliseconds] - $t1}]
			echo "** Flashing done for $bin_file in $t2 ms **"
		} else {
			echo "** Flashing Failed **"
			return -1
		}
	}
	set stop_time [expr {[clock milliseconds] - $start_time}]
	echo "** Total programming time $stop_time ms **"

	# Reset
	if {[info exists reset]} {
		echo "** Resetting Target **"
		reset run
	}

	# Exit
	if {$exit == 1} {
		shutdown
	}

	return 0
}

add_help_text program_esp_bins "write all the images at address specified in flasher_args.json generated while building idf project"
add_usage_text program_esp_bins "<build_dir> flasher_args.json \[verify\] \[reset\] \[exit\] \[compress\] \[no_clock_boost\] \[restore_clock\]"

proc esp_get_mac {args} {
	global _ESP_EFUSE_MAC_ADDR_REG _ESP_ARCH

	foreach arg $args {
		if {[string equal $arg "format"]} {
			set format 1
		}
	}

	if { $_ESP_ARCH == "xtensa" } {
		xtensa set_permissive 1
		set mac_list [read_memory $_ESP_EFUSE_MAC_ADDR_REG 8 6]
		xtensa set_permissive 0
	} else {
		set mac_list [read_memory $_ESP_EFUSE_MAC_ADDR_REG 8 6]
	}

	set i 0
	foreach n $mac_list {
		set mac($i) $n
		incr i
	}

	if {[info exists format]}  {
		format %02x:%02x:%02x:%02x:%02x:%02x $mac(5) $mac(4) $mac(3) $mac(2) $mac(1) $mac(0)
	} else {
		format 0x0000%02x%02x%02x%02x%02x%02x $mac(5) $mac(4) $mac(3) $mac(2) $mac(1) $mac(0)
	}
}

add_help_text esp_get_mac "Print MAC address of the chip. Use a `format` argument to return formatted MAC value"
add_usage_text esp_get_mac "\[format\]"

# arm semihosting must be enabled before calling this function
proc esp_semihost_basedir {dir} {
	foreach tgt [target names] {
		$tgt arm semihosting_basedir $dir
	}
}