1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3 /***************************************************************************
4 * ESP32 target API for OpenOCD *
5 * Copyright (C) 2016-2019 Espressif Systems Ltd. *
6 ***************************************************************************/
12 #include <helper/time_support.h>
13 #include <target/target.h>
14 #include <target/target_type.h>
15 #include <target/smp.h>
16 #include <target/semihosting_common.h>
18 #include "esp_xtensa_smp.h"
21 This is a JTAG driver for the ESP32, the are two Tensilica cores inside
22 the ESP32 chip. For more information please have a look into ESP32 target
26 /* ESP32 memory map */
27 #define ESP32_DRAM_LOW 0x3ffae000
28 #define ESP32_DRAM_HIGH 0x40000000
29 #define ESP32_IROM_MASK_LOW 0x40000000
30 #define ESP32_IROM_MASK_HIGH 0x40064f00
31 #define ESP32_IRAM_LOW 0x40070000
32 #define ESP32_IRAM_HIGH 0x400a0000
33 #define ESP32_RTC_IRAM_LOW 0x400c0000
34 #define ESP32_RTC_IRAM_HIGH 0x400c2000
35 #define ESP32_RTC_DRAM_LOW 0x3ff80000
36 #define ESP32_RTC_DRAM_HIGH 0x3ff82000
37 #define ESP32_RTC_DATA_LOW 0x50000000
38 #define ESP32_RTC_DATA_HIGH 0x50002000
39 #define ESP32_EXTRAM_DATA_LOW 0x3f800000
40 #define ESP32_EXTRAM_DATA_HIGH 0x3fc00000
41 #define ESP32_DR_REG_LOW 0x3ff00000
42 #define ESP32_DR_REG_HIGH 0x3ff71000
43 #define ESP32_SYS_RAM_LOW 0x60000000UL
44 #define ESP32_SYS_RAM_HIGH (ESP32_SYS_RAM_LOW + 0x20000000UL)
45 #define ESP32_RTC_SLOW_MEM_BASE ESP32_RTC_DATA_LOW
48 #define ESP32_WDT_WKEY_VALUE 0x50d83aa1
49 #define ESP32_TIMG0_BASE 0x3ff5f000
50 #define ESP32_TIMG1_BASE 0x3ff60000
51 #define ESP32_TIMGWDT_CFG0_OFF 0x48
52 #define ESP32_TIMGWDT_PROTECT_OFF 0x64
53 #define ESP32_TIMG0WDT_CFG0 (ESP32_TIMG0_BASE + ESP32_TIMGWDT_CFG0_OFF)
54 #define ESP32_TIMG1WDT_CFG0 (ESP32_TIMG1_BASE + ESP32_TIMGWDT_CFG0_OFF)
55 #define ESP32_TIMG0WDT_PROTECT (ESP32_TIMG0_BASE + ESP32_TIMGWDT_PROTECT_OFF)
56 #define ESP32_TIMG1WDT_PROTECT (ESP32_TIMG1_BASE + ESP32_TIMGWDT_PROTECT_OFF)
57 #define ESP32_RTCCNTL_BASE 0x3ff48000
58 #define ESP32_RTCWDT_CFG_OFF 0x8C
59 #define ESP32_RTCWDT_PROTECT_OFF 0xA4
60 #define ESP32_RTCWDT_CFG (ESP32_RTCCNTL_BASE + ESP32_RTCWDT_CFG_OFF)
61 #define ESP32_RTCWDT_PROTECT (ESP32_RTCCNTL_BASE + ESP32_RTCWDT_PROTECT_OFF)
63 #define ESP32_TRACEMEM_BLOCK_SZ 0x4000
65 /* ESP32 dport regs */
66 #define ESP32_DR_REG_DPORT_BASE ESP32_DR_REG_LOW
67 #define ESP32_DPORT_APPCPU_CTRL_B_REG (ESP32_DR_REG_DPORT_BASE + 0x030)
68 #define ESP32_DPORT_APPCPU_CLKGATE_EN BIT(0)
70 #define ESP32_RTC_CNTL_SW_CPU_STALL_REG (ESP32_RTCCNTL_BASE + 0xac)
71 #define ESP32_RTC_CNTL_SW_CPU_STALL_DEF 0x0
73 /* 0 - don't care, 1 - TMS low, 2 - TMS high */
74 enum esp32_flash_bootstrap {
81 struct esp_xtensa_smp_common esp_xtensa_smp;
82 enum esp32_flash_bootstrap flash_bootstrap;
85 static inline struct esp32_common *target_to_esp32(struct target *target)
87 return container_of(target->arch_info, struct esp32_common, esp_xtensa_smp);
90 /* Reset ESP32 peripherals.
91 * Postconditions: all peripherals except RTC_CNTL are reset, CPU's PC is undefined, PRO CPU is halted,
94 * 0. make sure target is halted; if not, try to halt it; if that fails, try to reset it (via OCD) and then halt
95 * 1. set CPU initial PC to 0x50000000 (ESP32_SMP_RTC_DATA_LOW) by clearing RTC_CNTL_{PRO,APP}CPU_STAT_VECTOR_SEL
96 * 2. load stub code into ESP32_SMP_RTC_DATA_LOW; once executed, stub code will disable watchdogs and
97 * make CPU spin in an idle loop.
98 * 3. trigger SoC reset using RTC_CNTL_SW_SYS_RST bit
99 * 4. wait for the OCD to be reset
100 * 5. halt the target and wait for it to be halted (at this point CPU is in the idle loop)
101 * 6. restore initial PC and the contents of ESP32_SMP_RTC_DATA_LOW
102 * TODO: some state of RTC_CNTL is not reset during SW_SYS_RST. Need to reset that manually. */
104 static const uint8_t esp32_reset_stub_code[] = {
105 #include "../../../contrib/loaders/reset/espressif/esp32/cpu_reset_handler_code.inc"
108 static int esp32_soc_reset(struct target *target)
111 struct target_list *head;
112 struct xtensa *xtensa;
115 /* In order to write to peripheral registers, target must be halted first */
116 if (target->state != TARGET_HALTED) {
117 LOG_DEBUG("Target not halted before SoC reset, trying to halt it first");
119 res = target_wait_state(target, TARGET_HALTED, 1000);
120 if (res != ERROR_OK) {
121 LOG_DEBUG("Couldn't halt target before SoC reset, trying to do reset-halt");
122 res = xtensa_assert_reset(target);
123 if (res != ERROR_OK) {
125 "Couldn't halt target before SoC reset! (xtensa_assert_reset returned %d)",
131 bool reset_halt_save = target->reset_halt;
132 target->reset_halt = true;
133 res = xtensa_deassert_reset(target);
134 target->reset_halt = reset_halt_save;
135 if (res != ERROR_OK) {
137 "Couldn't halt target before SoC reset! (xtensa_deassert_reset returned %d)",
144 res = target_wait_state(target, TARGET_HALTED, 1000);
145 if (res != ERROR_OK) {
146 LOG_ERROR("Couldn't halt target before SoC reset");
153 foreach_smp_target(head, target->smp_targets) {
154 xtensa = target_to_xtensa(head->target);
155 /* if any of the cores is stalled unstall them */
156 if (xtensa_dm_core_is_stalled(&xtensa->dbg_mod)) {
157 LOG_TARGET_DEBUG(head->target, "Unstall CPUs before SW reset!");
158 res = target_write_u32(target,
159 ESP32_RTC_CNTL_SW_CPU_STALL_REG,
160 ESP32_RTC_CNTL_SW_CPU_STALL_DEF);
161 if (res != ERROR_OK) {
162 LOG_TARGET_ERROR(head->target, "Failed to unstall CPUs before SW reset!");
165 break; /* both cores are unstalled now, so exit the loop */
170 LOG_DEBUG("Loading stub code into RTC RAM");
171 uint8_t slow_mem_save[sizeof(esp32_reset_stub_code)];
173 /* Save contents of RTC_SLOW_MEM which we are about to overwrite */
174 res = target_read_buffer(target, ESP32_RTC_SLOW_MEM_BASE, sizeof(slow_mem_save), slow_mem_save);
175 if (res != ERROR_OK) {
176 LOG_ERROR("Failed to save contents of RTC_SLOW_MEM (%d)!", res);
180 /* Write stub code into RTC_SLOW_MEM */
181 res = target_write_buffer(target, ESP32_RTC_SLOW_MEM_BASE, sizeof(esp32_reset_stub_code), esp32_reset_stub_code);
182 if (res != ERROR_OK) {
183 LOG_ERROR("Failed to write stub (%d)!", res);
187 LOG_DEBUG("Resuming the target");
188 xtensa = target_to_xtensa(target);
189 xtensa->suppress_dsr_errors = true;
190 res = xtensa_resume(target, 0, ESP32_RTC_SLOW_MEM_BASE + 4, 0, 0);
191 xtensa->suppress_dsr_errors = false;
192 if (res != ERROR_OK) {
193 LOG_ERROR("Failed to run stub (%d)!", res);
196 LOG_DEBUG("resume done, waiting for the target to come alive");
198 /* Wait for SoC to reset */
200 int64_t timeout = timeval_ms() + 100;
201 bool get_timeout = false;
202 while (target->state != TARGET_RESET && target->state != TARGET_RUNNING) {
205 if (timeval_ms() >= timeout) {
206 LOG_TARGET_ERROR(target, "Timed out waiting for CPU to be reset, target state=%d",
213 /* Halt the CPU again */
214 LOG_DEBUG("halting the target");
216 res = target_wait_state(target, TARGET_HALTED, 1000);
217 if (res == ERROR_OK) {
218 LOG_DEBUG("restoring RTC_SLOW_MEM");
219 res = target_write_buffer(target, ESP32_RTC_SLOW_MEM_BASE, sizeof(slow_mem_save), slow_mem_save);
221 LOG_TARGET_ERROR(target, "Failed to restore contents of RTC_SLOW_MEM (%d)!", res);
223 LOG_TARGET_ERROR(target, "Timed out waiting for CPU to be halted after SoC reset");
226 return get_timeout ? ERROR_TARGET_TIMEOUT : res;
229 static int esp32_disable_wdts(struct target *target)
232 int res = target_write_u32(target, ESP32_TIMG0WDT_PROTECT, ESP32_WDT_WKEY_VALUE);
233 if (res != ERROR_OK) {
234 LOG_ERROR("Failed to write ESP32_TIMG0WDT_PROTECT (%d)!", res);
237 res = target_write_u32(target, ESP32_TIMG0WDT_CFG0, 0);
238 if (res != ERROR_OK) {
239 LOG_ERROR("Failed to write ESP32_TIMG0WDT_CFG0 (%d)!", res);
243 res = target_write_u32(target, ESP32_TIMG1WDT_PROTECT, ESP32_WDT_WKEY_VALUE);
244 if (res != ERROR_OK) {
245 LOG_ERROR("Failed to write ESP32_TIMG1WDT_PROTECT (%d)!", res);
248 res = target_write_u32(target, ESP32_TIMG1WDT_CFG0, 0);
249 if (res != ERROR_OK) {
250 LOG_ERROR("Failed to write ESP32_TIMG1WDT_CFG0 (%d)!", res);
254 res = target_write_u32(target, ESP32_RTCWDT_PROTECT, ESP32_WDT_WKEY_VALUE);
255 if (res != ERROR_OK) {
256 LOG_ERROR("Failed to write ESP32_RTCWDT_PROTECT (%d)!", res);
259 res = target_write_u32(target, ESP32_RTCWDT_CFG, 0);
260 if (res != ERROR_OK) {
261 LOG_ERROR("Failed to write ESP32_RTCWDT_CFG (%d)!", res);
267 static int esp32_on_halt(struct target *target)
269 return esp32_disable_wdts(target);
272 static int esp32_arch_state(struct target *target)
277 static int esp32_virt2phys(struct target *target,
278 target_addr_t virtual, target_addr_t *physical)
287 /* The TDI pin is also used as a flash Vcc bootstrap pin. If we reset the CPU externally, the last state of the TDI pin
288 * can allow the power to an 1.8V flash chip to be raised to 3.3V, or the other way around. Users can use the
289 * esp32 flashbootstrap command to set a level, and this routine will make sure the tdi line will return to
290 * that when the jtag port is idle. */
292 static void esp32_queue_tdi_idle(struct target *target)
294 struct esp32_common *esp32 = target_to_esp32(target);
295 static uint32_t value;
296 uint8_t t[4] = { 0, 0, 0, 0 };
298 if (esp32->flash_bootstrap == FBS_TMSLOW)
299 /* Make sure tdi is 0 at the exit of queue execution */
301 else if (esp32->flash_bootstrap == FBS_TMSHIGH)
302 /* Make sure tdi is 1 at the exit of queue execution */
307 /* Scan out 1 bit, do not move from IRPAUSE after we're done. */
308 buf_set_u32(t, 0, 1, value);
309 jtag_add_plain_ir_scan(1, t, NULL, TAP_IRPAUSE);
312 static int esp32_target_init(struct command_context *cmd_ctx, struct target *target)
314 return esp_xtensa_smp_target_init(cmd_ctx, target);
317 static const struct xtensa_debug_ops esp32_dbg_ops = {
318 .queue_enable = xtensa_dm_queue_enable,
319 .queue_reg_read = xtensa_dm_queue_reg_read,
320 .queue_reg_write = xtensa_dm_queue_reg_write
323 static const struct xtensa_power_ops esp32_pwr_ops = {
324 .queue_reg_read = xtensa_dm_queue_pwr_reg_read,
325 .queue_reg_write = xtensa_dm_queue_pwr_reg_write
328 static const struct esp_xtensa_smp_chip_ops esp32_chip_ops = {
329 .reset = esp32_soc_reset,
330 .on_halt = esp32_on_halt
333 static const struct esp_semihost_ops esp32_semihost_ops = {
334 .prepare = esp32_disable_wdts
337 static int esp32_target_create(struct target *target, Jim_Interp *interp)
339 struct xtensa_debug_module_config esp32_dm_cfg = {
340 .dbg_ops = &esp32_dbg_ops,
341 .pwr_ops = &esp32_pwr_ops,
343 .queue_tdi_idle = esp32_queue_tdi_idle,
344 .queue_tdi_idle_arg = target
347 struct esp32_common *esp32 = calloc(1, sizeof(struct esp32_common));
349 LOG_ERROR("Failed to alloc memory for arch info!");
353 int ret = esp_xtensa_smp_init_arch_info(target, &esp32->esp_xtensa_smp,
354 &esp32_dm_cfg, &esp32_chip_ops, &esp32_semihost_ops);
355 if (ret != ERROR_OK) {
356 LOG_ERROR("Failed to init arch info!");
360 esp32->flash_bootstrap = FBS_DONTCARE;
362 /* Assume running target. If different, the first poll will fix this. */
363 target->state = TARGET_RUNNING;
364 target->debug_reason = DBG_REASON_NOTHALTED;
368 static COMMAND_HELPER(esp32_cmd_flashbootstrap_do, struct esp32_common *esp32)
374 state = esp32->flash_bootstrap;
375 if (state == FBS_DONTCARE)
377 else if (state == FBS_TMSLOW)
379 else if (state == FBS_TMSHIGH)
383 command_print(CMD, "Current idle tms state: %s", st);
387 if (!strcasecmp(CMD_ARGV[0], "none"))
388 state = FBS_DONTCARE;
389 else if (!strcasecmp(CMD_ARGV[0], "1.8"))
391 else if (!strcasecmp(CMD_ARGV[0], "3.3"))
393 else if (!strcasecmp(CMD_ARGV[0], "high"))
395 else if (!strcasecmp(CMD_ARGV[0], "low"))
400 "Argument unknown. Please pick one of none, high, low, 1.8 or 3.3");
403 esp32->flash_bootstrap = state;
407 COMMAND_HANDLER(esp32_cmd_flashbootstrap)
409 struct target *target = get_current_target(CMD_CTX);
412 struct target_list *head;
414 foreach_smp_target(head, target->smp_targets) {
416 int ret = CALL_COMMAND_HANDLER(esp32_cmd_flashbootstrap_do,
417 target_to_esp32(curr));
423 return CALL_COMMAND_HANDLER(esp32_cmd_flashbootstrap_do,
424 target_to_esp32(target));
427 static const struct command_registration esp32_any_command_handlers[] = {
429 .name = "flashbootstrap",
430 .handler = esp32_cmd_flashbootstrap,
433 "Set the idle state of the TMS pin, which at reset also is the voltage selector for the flash chip.",
434 .usage = "none|1.8|3.3|high|low",
436 COMMAND_REGISTRATION_DONE
439 static const struct command_registration esp32_command_handlers[] = {
441 .chain = esp_xtensa_smp_command_handlers,
446 .chain = smp_command_handlers,
451 .chain = esp32_any_command_handlers,
456 .help = "ARM Command Group",
458 .chain = semihosting_common_handlers
460 COMMAND_REGISTRATION_DONE
463 /** Holds methods for Xtensa targets. */
464 struct target_type esp32_target = {
467 .poll = esp_xtensa_smp_poll,
468 .arch_state = esp32_arch_state,
471 .resume = esp_xtensa_smp_resume,
472 .step = esp_xtensa_smp_step,
474 .assert_reset = esp_xtensa_smp_assert_reset,
475 .deassert_reset = esp_xtensa_smp_deassert_reset,
476 .soft_reset_halt = esp_xtensa_smp_soft_reset_halt,
478 .virt2phys = esp32_virt2phys,
479 .mmu = xtensa_mmu_is_enabled,
480 .read_memory = xtensa_read_memory,
481 .write_memory = xtensa_write_memory,
483 .read_buffer = xtensa_read_buffer,
484 .write_buffer = xtensa_write_buffer,
486 .checksum_memory = xtensa_checksum_memory,
488 .get_gdb_arch = xtensa_get_gdb_arch,
489 .get_gdb_reg_list = xtensa_get_gdb_reg_list,
491 .add_breakpoint = esp_xtensa_breakpoint_add,
492 .remove_breakpoint = esp_xtensa_breakpoint_remove,
494 .add_watchpoint = esp_xtensa_smp_watchpoint_add,
495 .remove_watchpoint = esp_xtensa_smp_watchpoint_remove,
497 .target_create = esp32_target_create,
498 .init_target = esp32_target_init,
499 .examine = xtensa_examine,
500 .deinit_target = esp_xtensa_target_deinit,
502 .commands = esp32_command_handlers,