1 // SPDX-License-Identifier: GPL-2.0-or-later
3 /***************************************************************************
5 * Copyright (C) 2010 by David Brownell
6 ***************************************************************************/
10 * Utilities to support ARM "Serial Wire Debug" (SWD), a low pin-count debug
11 * link protocol used in cases where JTAG is not wanted. This is coupled to
12 * recent versions of ARM's "CoreSight" debug framework. This specific code
13 * is a transport level interface, with "target/arm_adi_v5.[hc]" code
14 * understanding operation semantics, shared with the JTAG transport.
16 * Single-DAP support only.
18 * for details, see "ARM IHI 0031A"
19 * ARM Debug Interface v5 Architecture Specification
20 * especially section 5.3 for SWD protocol
21 * and "ARM IHI 0074C" ARM Debug Interface Architecture Specification ADIv6.0
23 * On many chips (most current Cortex-M3 parts) SWD is a run-time alternative
24 * to JTAG. Boards may support one or both. There are also SWD-only chips,
25 * (using SW-DP not SWJ-DP).
27 * Even boards that also support JTAG can benefit from SWD support, because
28 * usually there's no way to access the SWO trace view mechanism in JTAG mode.
29 * That is, trace access may require SWD support.
38 #include "arm_adi_v5.h"
39 #include <helper/time_support.h>
41 #include <transport/transport.h>
42 #include <jtag/interface.h>
46 /* for debug, set do_sync to true to force synchronous transfers */
49 static struct adiv5_dap *swd_multidrop_selected_dap;
52 static int swd_queue_dp_write_inner(struct adiv5_dap *dap, unsigned int reg,
56 static int swd_send_sequence(struct adiv5_dap *dap, enum swd_special_seq seq)
58 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
61 return swd->switch_seq(seq);
64 static void swd_finish_read(struct adiv5_dap *dap)
66 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
68 swd->read_reg(swd_cmd(true, false, DP_RDBUFF), dap->last_read, 0);
69 dap->last_read = NULL;
73 static void swd_clear_sticky_errors(struct adiv5_dap *dap)
75 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
78 swd->write_reg(swd_cmd(false, false, DP_ABORT),
79 STKCMPCLR | STKERRCLR | WDERRCLR | ORUNERRCLR, 0);
82 static int swd_run_inner(struct adiv5_dap *dap)
84 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
89 if (retval != ERROR_OK) {
91 dap->do_reconnect = true;
97 static inline int check_sync(struct adiv5_dap *dap)
99 return do_sync ? swd_run_inner(dap) : ERROR_OK;
102 /** Select the DP register bank matching bits 7:4 of reg. */
103 static int swd_queue_dp_bankselect(struct adiv5_dap *dap, unsigned int reg)
105 /* Only register address 0 and 4 are banked. */
109 uint64_t sel = (reg & 0x000000F0) >> 4;
110 if (dap->select != DP_SELECT_INVALID)
111 sel |= dap->select & ~0xfULL;
113 if (sel == dap->select)
118 int retval = swd_queue_dp_write_inner(dap, DP_SELECT, (uint32_t)sel);
119 if (retval != ERROR_OK)
120 dap->select = DP_SELECT_INVALID;
125 static int swd_queue_dp_read_inner(struct adiv5_dap *dap, unsigned int reg,
128 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
131 int retval = swd_queue_dp_bankselect(dap, reg);
132 if (retval != ERROR_OK)
135 swd->read_reg(swd_cmd(true, false, reg), data, 0);
137 return check_sync(dap);
140 static int swd_queue_dp_write_inner(struct adiv5_dap *dap, unsigned int reg,
144 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
147 swd_finish_read(dap);
149 if (reg == DP_SELECT) {
150 dap->select = data & (DP_SELECT_APSEL | DP_SELECT_APBANK | DP_SELECT_DPBANK);
152 swd->write_reg(swd_cmd(false, false, reg), data, 0);
154 retval = check_sync(dap);
155 if (retval != ERROR_OK)
156 dap->select = DP_SELECT_INVALID;
161 retval = swd_queue_dp_bankselect(dap, reg);
162 if (retval != ERROR_OK)
165 swd->write_reg(swd_cmd(false, false, reg), data, 0);
167 return check_sync(dap);
171 static int swd_multidrop_select_inner(struct adiv5_dap *dap, uint32_t *dpidr_ptr,
172 uint32_t *dlpidr_ptr, bool clear_sticky)
175 uint32_t dpidr, dlpidr;
177 assert(dap_is_multidrop(dap));
179 swd_send_sequence(dap, LINE_RESET);
180 /* From ARM IHI 0074C ADIv6.0, chapter B4.3.3 "Connection and line reset
182 * - line reset sets DP_SELECT_DPBANK to zero;
183 * - read of DP_DPIDR takes the connection out of reset;
184 * - write of DP_TARGETSEL keeps the connection in reset;
185 * - other accesses return protocol error (SWDIO not driven by target).
187 * Read DP_DPIDR to get out of reset. Initialize dap->select to zero to
188 * skip the write to DP_SELECT, avoiding the protocol error. Set again
189 * dap->select to DP_SELECT_INVALID because the rest of the register is
190 * unknown after line reset.
194 retval = swd_queue_dp_write_inner(dap, DP_TARGETSEL, dap->multidrop_targetsel);
195 if (retval != ERROR_OK)
198 retval = swd_queue_dp_read_inner(dap, DP_DPIDR, &dpidr);
199 if (retval != ERROR_OK)
203 /* Clear all sticky errors (including ORUN) */
204 swd_clear_sticky_errors(dap);
206 /* Ideally just clear ORUN flag which is set by reset */
207 retval = swd_queue_dp_write_inner(dap, DP_ABORT, ORUNERRCLR);
208 if (retval != ERROR_OK)
212 dap->select = DP_SELECT_INVALID;
214 retval = swd_queue_dp_read_inner(dap, DP_DLPIDR, &dlpidr);
215 if (retval != ERROR_OK)
218 retval = swd_run_inner(dap);
219 if (retval != ERROR_OK)
222 if ((dpidr & DP_DPIDR_VERSION_MASK) < (2UL << DP_DPIDR_VERSION_SHIFT)) {
223 LOG_INFO("Read DPIDR 0x%08" PRIx32
224 " has version < 2. A non multidrop capable device connected?",
229 /* TODO: check TARGETID if DLIPDR is same for more than one DP */
230 uint32_t expected_dlpidr = DP_DLPIDR_PROTVSN |
231 (dap->multidrop_targetsel & DP_TARGETSEL_INSTANCEID_MASK);
232 if (dlpidr != expected_dlpidr) {
233 LOG_INFO("Read incorrect DLPIDR 0x%08" PRIx32
234 " (possibly CTRL/STAT value)",
239 LOG_DEBUG_IO("Selected DP_TARGETSEL 0x%08" PRIx32, dap->multidrop_targetsel);
240 swd_multidrop_selected_dap = dap;
246 *dlpidr_ptr = dlpidr;
251 static int swd_multidrop_select(struct adiv5_dap *dap)
253 if (!dap_is_multidrop(dap))
256 if (swd_multidrop_selected_dap == dap)
259 int retval = ERROR_OK;
260 for (unsigned int retry = 0; ; retry++) {
261 bool clear_sticky = retry > 0;
263 retval = swd_multidrop_select_inner(dap, NULL, NULL, clear_sticky);
264 if (retval == ERROR_OK)
267 swd_multidrop_selected_dap = NULL;
269 LOG_ERROR("Failed to select multidrop %s", adiv5_dap_name(dap));
273 LOG_DEBUG("Failed to select multidrop %s, retrying...",
274 adiv5_dap_name(dap));
280 static int swd_connect_multidrop(struct adiv5_dap *dap)
283 uint32_t dpidr = 0xdeadbeef;
284 uint32_t dlpidr = 0xdeadbeef;
285 int64_t timeout = timeval_ms() + 500;
288 swd_send_sequence(dap, JTAG_TO_DORMANT);
289 swd_send_sequence(dap, DORMANT_TO_SWD);
291 /* Clear link state, including the SELECT cache. */
292 dap->do_reconnect = false;
293 dap_invalidate_cache(dap);
294 swd_multidrop_selected_dap = NULL;
296 retval = swd_multidrop_select_inner(dap, &dpidr, &dlpidr, true);
297 if (retval == ERROR_OK)
302 } while (timeval_ms() < timeout);
304 if (retval != ERROR_OK) {
305 swd_multidrop_selected_dap = NULL;
306 LOG_ERROR("Failed to connect multidrop %s", adiv5_dap_name(dap));
310 LOG_INFO("SWD DPIDR 0x%08" PRIx32 ", DLPIDR 0x%08" PRIx32,
316 static int swd_connect_single(struct adiv5_dap *dap)
319 uint32_t dpidr = 0xdeadbeef;
320 int64_t timeout = timeval_ms() + 500;
323 if (dap->switch_through_dormant) {
324 swd_send_sequence(dap, JTAG_TO_DORMANT);
325 swd_send_sequence(dap, DORMANT_TO_SWD);
327 swd_send_sequence(dap, JTAG_TO_SWD);
330 /* Clear link state, including the SELECT cache. */
331 dap->do_reconnect = false;
332 dap_invalidate_cache(dap);
334 /* The sequences to enter in SWD (JTAG_TO_SWD and DORMANT_TO_SWD) end
335 * with a SWD line reset sequence (50 clk with SWDIO high).
336 * From ARM IHI 0074C ADIv6.0, chapter B4.3.3 "Connection and line reset
338 * - line reset sets DP_SELECT_DPBANK to zero;
339 * - read of DP_DPIDR takes the connection out of reset;
340 * - write of DP_TARGETSEL keeps the connection in reset;
341 * - other accesses return protocol error (SWDIO not driven by target).
343 * Read DP_DPIDR to get out of reset. Initialize dap->select to zero to
344 * skip the write to DP_SELECT, avoiding the protocol error. Set again
345 * dap->select to DP_SELECT_INVALID because the rest of the register is
346 * unknown after line reset.
349 retval = swd_queue_dp_read_inner(dap, DP_DPIDR, &dpidr);
350 if (retval == ERROR_OK) {
351 retval = swd_run_inner(dap);
352 if (retval == ERROR_OK)
358 dap->switch_through_dormant = !dap->switch_through_dormant;
359 } while (timeval_ms() < timeout);
361 dap->select = DP_SELECT_INVALID;
363 if (retval != ERROR_OK) {
364 LOG_ERROR("Error connecting DP: cannot read IDR");
368 LOG_INFO("SWD DPIDR 0x%08" PRIx32, dpidr);
371 dap->do_reconnect = false;
373 /* force clear all sticky faults */
374 swd_clear_sticky_errors(dap);
376 retval = swd_run_inner(dap);
377 if (retval != ERROR_WAIT)
382 } while (timeval_ms() < timeout);
387 static int swd_connect(struct adiv5_dap *dap)
391 /* FIXME validate transport config ... is the
392 * configured DAP present (check IDCODE)?
395 /* Check if we should reset srst already when connecting, but not if reconnecting. */
396 if (!dap->do_reconnect) {
397 enum reset_types jtag_reset_config = jtag_get_reset_config();
399 if (jtag_reset_config & RESET_CNCT_UNDER_SRST) {
400 if (jtag_reset_config & RESET_SRST_NO_GATING)
401 adapter_assert_reset();
403 LOG_WARNING("\'srst_nogate\' reset_config option is required");
407 if (dap_is_multidrop(dap))
408 status = swd_connect_multidrop(dap);
410 status = swd_connect_single(dap);
413 * "A WAIT response must not be issued to the ...
414 * ... writes to the ABORT register"
415 * swd_clear_sticky_errors() writes to the ABORT register only.
417 * Unfortunately at least Microchip SAMD51/E53/E54 returns WAIT
418 * in a corner case. Just try if ABORT resolves the problem.
420 if (status == ERROR_WAIT) {
421 LOG_WARNING("Connecting DP: stalled AP operation, issuing ABORT");
423 dap->do_reconnect = false;
425 status = swd_queue_dp_write_inner(dap, DP_ABORT,
426 DAPABORT | STKCMPCLR | STKERRCLR | WDERRCLR | ORUNERRCLR);
428 if (status == ERROR_OK)
429 status = swd_run_inner(dap);
432 if (status == ERROR_OK)
433 status = dap_dp_init(dap);
438 static int swd_check_reconnect(struct adiv5_dap *dap)
440 if (dap->do_reconnect)
441 return swd_connect(dap);
446 static int swd_queue_ap_abort(struct adiv5_dap *dap, uint8_t *ack)
448 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
451 /* TODO: Send DAPABORT in swd_multidrop_select_inner()
452 * in the case the multidrop dap is not selected?
453 * swd_queue_ap_abort() is not currently used anyway...
455 int retval = swd_multidrop_select(dap);
456 if (retval != ERROR_OK)
459 swd->write_reg(swd_cmd(false, false, DP_ABORT),
460 DAPABORT | STKCMPCLR | STKERRCLR | WDERRCLR | ORUNERRCLR, 0);
461 return check_sync(dap);
464 static int swd_queue_dp_read(struct adiv5_dap *dap, unsigned reg,
467 int retval = swd_check_reconnect(dap);
468 if (retval != ERROR_OK)
471 retval = swd_multidrop_select(dap);
472 if (retval != ERROR_OK)
475 return swd_queue_dp_read_inner(dap, reg, data);
478 static int swd_queue_dp_write(struct adiv5_dap *dap, unsigned reg,
481 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
484 int retval = swd_check_reconnect(dap);
485 if (retval != ERROR_OK)
488 retval = swd_multidrop_select(dap);
489 if (retval != ERROR_OK)
492 return swd_queue_dp_write_inner(dap, reg, data);
495 /** Select the AP register bank matching bits 7:4 of reg. */
496 static int swd_queue_ap_bankselect(struct adiv5_ap *ap, unsigned reg)
499 struct adiv5_dap *dap = ap->dap;
503 sel = ap->ap_num | (reg & 0x00000FF0);
504 if (sel == (dap->select & ~0xfULL))
507 if (dap->select != DP_SELECT_INVALID)
508 sel |= dap->select & 0xf;
510 LOG_DEBUG("AP BANKSEL: %" PRIx64, sel);
512 retval = swd_queue_dp_write(dap, DP_SELECT, (uint32_t)sel);
514 if (retval == ERROR_OK && dap->asize > 32)
515 retval = swd_queue_dp_write(dap, DP_SELECT1, (uint32_t)(sel >> 32));
517 if (retval != ERROR_OK)
518 dap->select = DP_SELECT_INVALID;
524 sel = (ap->ap_num << 24) | (reg & 0x000000F0);
525 if (dap->select != DP_SELECT_INVALID)
526 sel |= dap->select & DP_SELECT_DPBANK;
528 if (sel == dap->select)
533 retval = swd_queue_dp_write_inner(dap, DP_SELECT, sel);
534 if (retval != ERROR_OK)
535 dap->select = DP_SELECT_INVALID;
540 static int swd_queue_ap_read(struct adiv5_ap *ap, unsigned reg,
543 struct adiv5_dap *dap = ap->dap;
544 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
547 int retval = swd_check_reconnect(dap);
548 if (retval != ERROR_OK)
551 retval = swd_multidrop_select(dap);
552 if (retval != ERROR_OK)
555 retval = swd_queue_ap_bankselect(ap, reg);
556 if (retval != ERROR_OK)
559 swd->read_reg(swd_cmd(true, true, reg), dap->last_read, ap->memaccess_tck);
560 dap->last_read = data;
562 return check_sync(dap);
565 static int swd_queue_ap_write(struct adiv5_ap *ap, unsigned reg,
568 struct adiv5_dap *dap = ap->dap;
569 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
572 int retval = swd_check_reconnect(dap);
573 if (retval != ERROR_OK)
576 retval = swd_multidrop_select(dap);
577 if (retval != ERROR_OK)
580 swd_finish_read(dap);
582 retval = swd_queue_ap_bankselect(ap, reg);
583 if (retval != ERROR_OK)
586 swd->write_reg(swd_cmd(false, true, reg), data, ap->memaccess_tck);
588 return check_sync(dap);
591 /** Executes all queued DAP operations. */
592 static int swd_run(struct adiv5_dap *dap)
594 int retval = swd_multidrop_select(dap);
595 if (retval != ERROR_OK)
598 swd_finish_read(dap);
600 return swd_run_inner(dap);
603 /** Put the SWJ-DP back to JTAG mode */
604 static void swd_quit(struct adiv5_dap *dap)
606 const struct swd_driver *swd = adiv5_dap_swd_driver(dap);
609 /* There is no difference if the sequence is sent at the last
610 * or the first swd_quit() call, send it just once */
615 if (dap_is_multidrop(dap)) {
616 swd->switch_seq(SWD_TO_DORMANT);
618 * Leaving DPs in dormant state was tested and offers some safety
619 * against DPs mismatch in case of unintentional use of non-multidrop SWD.
620 * To put SWJ-DPs to power-on state issue
621 * swd->switch_seq(DORMANT_TO_JTAG);
624 if (dap->switch_through_dormant) {
625 swd->switch_seq(SWD_TO_DORMANT);
626 swd->switch_seq(DORMANT_TO_JTAG);
628 swd->switch_seq(SWD_TO_JTAG);
632 /* flush the queue to shift out the sequence before exit */
636 const struct dap_ops swd_dap_ops = {
637 .connect = swd_connect,
638 .send_sequence = swd_send_sequence,
639 .queue_dp_read = swd_queue_dp_read,
640 .queue_dp_write = swd_queue_dp_write,
641 .queue_ap_read = swd_queue_ap_read,
642 .queue_ap_write = swd_queue_ap_write,
643 .queue_ap_abort = swd_queue_ap_abort,
648 static const struct command_registration swd_commands[] = {
651 * Set up SWD and JTAG targets identically, unless/until
652 * infrastructure improves ... meanwhile, ignore all
653 * JTAG-specific stuff like IR length for SWD.
655 * REVISIT can we verify "just one SWD DAP" here/early?
658 .jim_handler = jim_jtag_newtap,
659 .mode = COMMAND_CONFIG,
660 .help = "declare a new SWD DAP"
662 COMMAND_REGISTRATION_DONE
665 static const struct command_registration swd_handlers[] = {
669 .help = "SWD command group",
670 .chain = swd_commands,
673 COMMAND_REGISTRATION_DONE
676 static int swd_select(struct command_context *ctx)
678 /* FIXME: only place where global 'adapter_driver' is still needed */
679 extern struct adapter_driver *adapter_driver;
680 const struct swd_driver *swd = adapter_driver->swd_ops;
683 retval = register_commands(ctx, NULL, swd_handlers);
684 if (retval != ERROR_OK)
687 /* be sure driver is in SWD mode; start
688 * with hardware default TRN (1), it can be changed later
690 if (!swd || !swd->read_reg || !swd->write_reg || !swd->init) {
691 LOG_DEBUG("no SWD driver?");
695 retval = swd->init();
696 if (retval != ERROR_OK) {
697 LOG_DEBUG("can't init SWD driver");
704 static int swd_init(struct command_context *ctx)
706 /* nothing done here, SWD is initialized
707 * together with the DAP */
711 static struct transport swd_transport = {
713 .select = swd_select,
717 static void swd_constructor(void) __attribute__((constructor));
718 static void swd_constructor(void)
720 transport_register(&swd_transport);
723 /** Returns true if the current debug session
724 * is using SWD as its transport.
726 bool transport_is_swd(void)
728 return get_current_transport() == &swd_transport;