initial SWD transport (SWD infrastructure #2)

This piggy backs on JTAG so it's not yet pretty, but that
seems unavoidable so far given today's OpenOCD internals.

SWD init and data transfer  are unfinished and untested, but
that should cause no regressions, and will be addressed by
the time drivers start using this infrastructure.  Checking
in whould get the code working better sooner, and turn up any
structural/architectural issues while they're easier to fix.

The debug adapter drivers will provide simple SWD driver
structs with methods that kick in as needed (instead of JTAG).
So far just one adapter driver has been updated (not yet
ready to use or circulate).

The biggest issues are probably
  - fault handling, where the ARM Debug Interface V5 pipelining
    needs work in both JTAG and SWD modes and
  - missing  rewrite of block I/O code to work on both of our
Cortex-ready transports (Current code is  hard-wired to JTAG);
relates also to the pipelining issue.
  - omitted support to activate/deactivate SWO/SWV trace (this is
    technically trivial, but configuring what to trace is NOT.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
----

 doc/openocd.texi        |   17 ++
 src/jtag/core.c         |    3
 src/jtag/interface.h    |    4
 src/jtag/jtag.h         |    2
 src/jtag/swd.h          |  114 +++++++++++++++++++
 src/jtag/tcl.c          |    2
 src/target/adi_v5_swd.c |  281 ++++++++++++++++++++++++++++++++++++++++++++++--
 src/target/arm_adi_v5.c |    8 +
 src/target/arm_adi_v5.h |    3
 9 files changed, 425 insertions(+), 9 deletions(-)

9 files changed, 425 insertions, 9 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index a65244a6..8ee328bd 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2462,6 +2462,7 @@ No arguments: print status.
 @end deffn
 
 @section Transport Configuration
+@cindex Transport
 As noted earlier, depending on the version of OpenOCD you use,
 and the debug adapter you are using,
 several transports may be available to
@@ -2479,6 +2480,7 @@ No arguments: returns name of session's selected transport.
 @end deffn
 
 @subsection JTAG Transport
+@cindex JTAG
 JTAG is the original transport supported by OpenOCD, and most
 of the OpenOCD commands support it.
 JTAG transports expose a chain of one or more Test Access Points (TAPs),
@@ -2486,13 +2488,28 @@ each of which must be explicitly declared.
 JTAG supports both debugging and boundary scan testing.
 Flash programming support is built on top of debug support.
 @subsection SWD Transport
+@cindex SWD
+@cindex Serial Wire Debug
 SWD (Serial Wire Debug) is an ARM-specific transport which exposes one
 Debug Access Point (DAP, which must be explicitly declared.
 (SWD uses fewer signal wires than JTAG.)
 SWD is debug-oriented, and does not support  boundary scan testing.
 Flash programming support is built on top of debug support.
 (Some processors support both JTAG and SWD.)
+@deffn Command {swd newdap} ...
+Declares a single DAP which uses SWD transport.
+Parameters are currently the same as "jtag newtap" but this is
+expected to change.
+@end deffn
+@deffn Command {swd wcr trn prescale}
+Updates TRN (turnaraound delay) and prescaling.fields of the
+Wire Control Register (WCR).
+No parameters: displays current settings.
+@end deffn
+
 @subsection SPI Transport
+@cindex SPI
+@cindex Serial Peripheral Interface
 The Serial Peripheral Interface (SPI) is a general purpose transport
 which uses four wire signaling.  Some processors use it as part of a
 solution for flash programming.
diff --git a/src/jtag/core.c b/src/jtag/core.c
index dfedc172..6e923bd4 100644
--- a/src/jtag/core.c
+++ b/src/jtag/core.c
@@ -129,6 +129,9 @@ static int jtag_speed = 0;
 
 static struct jtag_interface *jtag = NULL;
 
+
+const struct swd_driver *swd = NULL;
+
 /* configuration */
 struct jtag_interface *jtag_interface = NULL;
 
diff --git a/src/jtag/interface.h b/src/jtag/interface.h
index 3226944e..958af8f5 100644
--- a/src/jtag/interface.h
+++ b/src/jtag/interface.h
@@ -209,6 +209,8 @@ struct jtag_interface {
 	/** transports supported in C code (NULL terminated vector) */
 	const char **transports;
 
+	const struct swd_driver *swd;
+
 	/**
 	 * Execute queued commands.
 	 * @returns ERROR_OK on success, or an error code on failure.
@@ -294,4 +296,6 @@ struct jtag_interface {
 
 extern const char *jtag_only[];
 
+extern const struct swd_driver *swd;
+
 #endif // OPENOCD_JTAG_INTERFACE_H
diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h
index db7cd5c9..df015376 100644
--- a/src/jtag/jtag.h
+++ b/src/jtag/jtag.h
@@ -695,4 +695,6 @@ void jtag_poll_set_enabled(bool value);
 
 bool transport_is_jtag(void);
 
+int jim_jtag_newtap(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
+
 #endif /* JTAG_H */
diff --git a/src/jtag/swd.h b/src/jtag/swd.h
new file mode 100644
index 00000000..1931c4a9
--- /dev/null
+++ b/src/jtag/swd.h
@@ -0,0 +1,114 @@
+//
+
+/* Bits in SWD command packets, written from host to target
+ * first bit on the wire is START
+ */
+#define SWD_CMD_START	(1 << 0)	/* always set */
+#define SWD_CMD_APnDP	(1 << 1)	/* set only for AP access */
+#define SWD_CMD_RnW	(1 << 2)	/* set only for read access */
+#define SWD_CMD_A32	(3 << 3)	/* bits A[3:2] of register addr */
+#define SWD_CMD_PARITY	(1 << 5)	/* parity of APnDP|RnW|A32 */
+#define SWD_CMD_STOP	(0 << 6)	/* always clear for synch SWD */
+#define SWD_CMD_PARK	(0 << 7)	/* not driven by host (pull high) */
+/* followed by TRN, 3-bits of ACK, TRN */
+
+/* pbit16 holds precomputed parity bits for each nibble */
+#define pbit(parity, nibble) (parity << nibble)
+
+static const uint16_t pbit16 =
+	pbit(0, 0) | pbit(1, 1) | pbit(1, 2) | pbit(0, 3)
+	| pbit(1, 4) | pbit(0, 5) | pbit(0, 6) | pbit(1, 7)
+	| pbit(1, 8) | pbit(0, 9) | pbit(0, 0xa) | pbit(1, 0xb)
+	| pbit(0, 0xc) | pbit(1, 0xd) | pbit(1, 0xe) | pbit(0, 0xf);
+
+#define nibble_parity(nibble) (pbit16 & pbit(1, nibble))
+
+/**
+ * Construct a "cmd" byte, in lSB bit order, which swd_driver.read_reg()
+ * and swd_driver.write_reg() methods will use directly.
+ */
+static inline uint8_t swd_cmd(bool is_read, bool is_ap, uint8_t regnum)
+{
+	uint8_t cmd = (is_ap ? SWD_CMD_APnDP : 0)
+		| (is_read ? SWD_CMD_RnW : 0)
+		| ((regnum & 0xc) << 1);
+
+	//8 cmd bits 4:1 may be set
+	if (nibble_parity(cmd >> 1))
+		cmd |= SWD_CMD_PARITY;
+
+	/* driver handles START, STOP, and TRN */
+
+	return cmd;
+}
+
+/* SWD_ACK_* bits are defined in <target/arm_adi_v5.h> */
+
+/*
+ * FOR NOW  ... SWD driver ops are synchronous and return ACK
+ * status ... no quueueing.
+ *
+ * Individual ops are request/response, and fast-fail permits much
+ * better fault handling.  Upper layers may queue if desired.
+ */
+
+struct swd_driver {
+	/**
+	 * Initialize the debug link so it can perform
+	 * synchronous SWD operations.
+	 * @param trn value from WCR: how many clocks
+	 * to not drive the SWDIO line at certain points in
+	 * the SWD protocol (at least 1 clock).
+	 *
+	 * As an example, this would switch a dual-mode debug adapter
+	 * into SWD mode and out of JTAG mode.
+	  *
+	  * @return ERROR_OK on success, else a negative fault code.
+	 */
+	int (*init)(uint8_t trn);
+
+
+	 /**
+	  * Synchronous read of an AP or DP register.
+	  *
+	  * @param cmd with APnDP/RnW/addr/parity bits
+	  * @param where to store value to read from register
+	  *
+	  * @return SWD_ACK_* code for the transaction
+	  * 	or (negative) fault code
+	  */
+	 int (*read_reg)(uint8_t cmd, uint32_t *value);
+
+	 /**
+	  * Synchronous write of an AP or DP register.
+	  *
+	  * @param cmd with APnDP/RnW/addr/parity bits
+	  * @param value to be written to the register
+	  *
+	  * @return SWD_ACK_* code for the transaction
+	  * 	or (negative) fault code
+	  */
+	 int (*write_reg)(uint8_t cmd, uint32_t value);
+
+	/* XXX START WITH enough to:
+	 *	init (synch mode, WCR)
+	 *		for async, TRN > 1
+	 *	read IDCODE from DP
+	 */
+
+	/**
+	 * Configures data collection from the Single-wire
+	 * trace (SWO) signal.
+	 * @param swo true if SWO data collection should be routed.
+	 *
+	 * For example,  some debug adapters include a UART which
+	 * is normally connected to a microcontroller's UART TX,
+	 * but which may instead be connected to SWO for use in
+	 * collecting ITM (and possibly ETM) trace data.
+	  *
+	  * @return ERROR_OK on success, else a negative fault code.
+	 */
+	int *(*trace)(bool swo);
+};
+
+bool transport_is_swd(void);
diff --git a/src/jtag/tcl.c b/src/jtag/tcl.c
index 89b405c9..a1f4435b 100644
--- a/src/jtag/tcl.c
+++ b/src/jtag/tcl.c
@@ -715,7 +715,7 @@ static int jim_jtag_arp_init_reset(Jim_Interp *interp, int argc, Jim_Obj *const
 	return JIM_OK;
 }
 
-static int jim_jtag_newtap(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
+int jim_jtag_newtap(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
 {
 	Jim_GetOptInfo goi;
 	Jim_GetOpt_Setup(&goi, interp, argc-1, argv + 1);
diff --git a/src/target/adi_v5_swd.c b/src/target/adi_v5_swd.c
index f103e4b0..39f38572 100644
--- a/src/target/adi_v5_swd.c
+++ b/src/target/adi_v5_swd.c
@@ -20,8 +20,26 @@
 
 /**
  * @file
- * This file implements SWD transport support for cores implementing
- the ARM Debug Interface version 5 (ADIv5).
+ * Utilities to support ARM "Serial Wire Debug" (SWD), a low pin-count debug
+ * link protocol used in cases where JTAG is not wanted.  This is coupled to
+ * recent versions of ARM's "CoreSight" debug framework.  This specific code
+ * is a transport level interface, with "target/arm_adi_v5.[hc]" code
+ * understanding operation semantics, shared with the JTAG transport.
+ *
+ * Single-DAP support only.
+ *
+ * for details, see "ARM IHI 0031A"
+ * ARM Debug Interface v5 Architecture Specification
+ * especially section 5.3 for SWD protocol
+ *
+ * On many chips (most current Cortex-M3 parts) SWD is a run-time alternative
+ * to JTAG.  Boards may support one or both.  There are also SWD-only chips,
+ * (using SW-DP not SWJ-DP).
+ *
+ * Even boards that also support JTAG can benefit from SWD support, because
+ * usually there's no way to access the SWO trace view mechanism in JTAG mode.
+ * That is, trace access may require SWD support.
+ *
  */
 
 #ifdef HAVE_CONFIG_H
@@ -32,6 +50,83 @@
 #include "arm_adi_v5.h"
 #include <helper/time_support.h>
 
+#include <jtag/transport.h>
+#include <jtag/interface.h>
+
+#include <jtag/swd.h>
+
+
+
+static int swd_queue_dp_read(struct adiv5_dap *dap, unsigned reg,
+		uint32_t *data)
+{
+	// REVISIT status return vs ack ...
+	return swd->read_reg(swd_cmd(true,  false, reg), data);
+}
+
+static int swd_queue_idcode_read(struct adiv5_dap *dap,
+		uint8_t *ack, uint32_t *data)
+{
+	int status = swd_queue_dp_read(dap, DP_IDCODE, data);
+	if (status < 0)
+		return status;
+	*ack = status;
+	// ??
+	return ERROR_OK;
+}
+
+static int (swd_queue_dp_write)(struct adiv5_dap *dap, unsigned reg,
+		uint32_t data)
+{
+	// REVISIT status return vs ack ...
+	return swd->write_reg(swd_cmd(false,  false, reg), data);
+}
+
+
+static int (swd_queue_ap_read)(struct adiv5_dap *dap, unsigned reg,
+		uint32_t *data)
+{
+	// REVISIT  APSEL ...
+	// REVISIT status return ...
+	return swd->read_reg(swd_cmd(true,  true, reg), data);
+}
+
+static int (swd_queue_ap_write)(struct adiv5_dap *dap, unsigned reg,
+		uint32_t data)
+{
+	// REVISIT  APSEL ...
+	// REVISIT status return ...
+	return swd->write_reg(swd_cmd(false,  true, reg), data);
+}
+
+static int (swd_queue_ap_abort)(struct adiv5_dap *dap, uint8_t *ack)
+{
+	return ERROR_FAIL;
+}
+
+/** Executes all queued DAP operations. */
+static int swd_run(struct adiv5_dap *dap)
+{
+	/* for now the SWD interface hard-wires a zero-size queue.  */
+
+	/* FIXME but we still need to check and scrub
+	 * any hardware errors ...
+	 */
+	return ERROR_OK;
+}
+
+const struct dap_ops swd_dap_ops = {
+	.is_swd = true,
+
+	.queue_idcode_read = swd_queue_idcode_read,
+	.queue_dp_read = swd_queue_dp_read,
+	.queue_dp_write = swd_queue_dp_write,
+	.queue_ap_read = swd_queue_ap_read,
+	.queue_ap_write = swd_queue_ap_write,
+	.queue_ap_abort = swd_queue_ap_abort,
+	.run = swd_run,
+};
+
 /*
  * This represents the bits which must be sent out on TMS/SWDIO to
  * switch a DAP implemented using an SWJ-DP module into SWD mode.
@@ -48,7 +143,7 @@ static const uint8_t jtag2swd_bitseq[] = {
 	0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 	/* Switching sequence enables SWD and disables JTAG
 	 * NOTE: bits in the DP's IDCODE may expose the need for
-	 * an old/deprecated sequence (0xb6 0xed).
+	 * an old/obsolete/deprecated sequence (0xb6 0xed).
 	 */
 	0x9e, 0xe7,
 	/* More than 50 TCK/SWCLK cycles with TMS/SWDIO high,
@@ -72,12 +167,13 @@ static const uint8_t jtag2swd_bitseq[] = {
  */
 int dap_to_swd(struct target *target)
 {
+	struct arm *arm = target_to_arm(target);
 	int retval;
 
 	LOG_DEBUG("Enter SWD mode");
 
-	/* REVISIT it's nasty to need to make calls to a "jtag"
-	 * subsystem if the link isn't in JTAG mode...
+	/* REVISIT it's ugly to need to make calls to a "jtag"
+	 * subsystem if the link may not be in JTAG mode...
 	 */
 
 	retval =  jtag_add_tms_seq(8 * sizeof(jtag2swd_bitseq),
@@ -85,8 +181,181 @@ int dap_to_swd(struct target *target)
 	if (retval == ERROR_OK)
 		retval = jtag_execute_queue();
 
-	/* REVISIT set up the DAP's ops vector for SWD mode. */
+	/* set up the DAP's ops vector for SWD mode. */
+	arm->dap->ops = &swd_dap_ops;
 
 	return retval;
 }
 
+
+
+COMMAND_HANDLER(handle_swd_wcr)
+{
+	int retval;
+	struct target *target = get_current_target(CMD_CTX);
+	struct arm *arm = target_to_arm(target);
+struct adiv5_dap *dap = arm->dap;
+	uint32_t wcr;
+	unsigned trn, scale = 0;
+
+
+	switch (CMD_ARGC) {
+	/* no-args: just dump state */
+	case 0:
+		//retval = swd_queue_dp_read(dap, DP_WCR, &wcr);
+		retval = dap_queue_dp_read(dap, DP_WCR, &wcr);
+		if (retval == ERROR_OK)
+			dap->ops->run(dap);
+		if (retval != ERROR_OK) {
+			LOG_ERROR("can't read WCR?");
+			return retval;
+		}
+
+		command_print(CMD_CTX,
+			"turnaround=%d, prescale=%d",
+			WCR_TO_TRN(wcr),
+			WCR_TO_PRESCALE(wcr));
+	return ERROR_OK;
+
+	case 2:		/* TRN and prescale */
+		COMMAND_PARSE_NUMBER(uint, CMD_ARGV[1], scale);
+		if (scale > 7) {
+			LOG_ERROR("prescale %d is too big", scale);
+			return ERROR_FAIL;
+		}
+		/* FALL THROUGH */
+
+	case 1:		/* TRN only */
+		COMMAND_PARSE_NUMBER(uint, CMD_ARGV[0], trn);
+		if (trn < 1 || trn > 4) {
+			LOG_ERROR("turnaround %d is invalid", trn);
+			return ERROR_FAIL;
+		}
+
+		wcr = ((trn - 1) << 8) | scale;
+		/* FIXME
+		 * write WCR ...
+		 * then, re-init adapter with new TRN
+		 */
+		LOG_ERROR("can't yet modify WCR");
+		return ERROR_FAIL;
+
+	default:	/* too many arguments */
+		return ERROR_COMMAND_SYNTAX_ERROR;
+	}
+}
+
+static const struct command_registration swd_commands[] = {
+	{
+		/*
+		 * Set up SWD and JTAG targets identically, unless/until
+		 * infrastructure improves ...  meanwhile, ignore all
+		 * JTAG-specific stuff like IR length for SWD.
+		 *
+		 * REVISIT can we verify "just one SWD DAP" here/early?
+		 */
+		.name = "newdap",
+		.jim_handler = jim_jtag_newtap,
+		.mode = COMMAND_CONFIG,
+		.help = "declare a new SWD DAP"
+	},
+	{
+		.name = "wcr",
+		.handler = handle_swd_wcr,
+		.mode = COMMAND_ANY,
+		.help = "display or update DAP's WCR register",
+		.usage = "turnaround (1..4), prescale (0..7)",
+	},
+
+	/* REVISIT -- add a command for SWV trace on/off */
+	COMMAND_REGISTRATION_DONE
+};
+
+static const struct command_registration swd_handlers[] = {
+	{
+		.name = "swd",
+		.mode = COMMAND_ANY,
+		.help = "SWD command group",
+		.chain = swd_commands,
+	},
+	COMMAND_REGISTRATION_DONE
+};
+
+static int swd_select(struct command_context *ctx)
+{
+	struct target *target = get_current_target(ctx);
+	int retval;
+
+	retval = register_commands(ctx, NULL, swd_handlers);
+
+	if (retval != ERROR_OK)
+		return retval;
+
+	 /* be sure driver is in SWD mode; start
+	  * with hardware default TRN (1), it can be changed later
+	  */
+	if (!swd || !swd->read_reg || !swd->write_reg || !swd->init) {
+		LOG_DEBUG("no SWD driver?");
+		return ERROR_FAIL;
+	}
+
+	 retval = swd->init(1);
+	if (retval != ERROR_OK) {
+		LOG_DEBUG("can't init SWD driver");
+		return retval;
+	}
+
+	/* force DAP into SWD mode (not JTAG) */
+	retval = dap_to_swd(target);
+
+	return retval;
+}
+
+static int swd_init(struct command_context *ctx)
+{
+	struct target *target = get_current_target(ctx);
+	struct arm *arm = target_to_arm(target);
+struct adiv5_dap *dap = arm->dap;
+	uint32_t idcode;
+	int status;
+
+
+	/* FIXME validate transport config ... is the
+	 * configured DAP present (check IDCODE)?
+	 * Is *only* one DAP configured?
+	 *
+	 * MUST READ IDCODE
+	 */
+
+ /* Note, debugport_init() does setup too */
+
+	uint8_t ack;
+
+	status = swd_queue_idcode_read(dap, &ack, &idcode);
+
+	if (status == ERROR_OK)
+		LOG_INFO("SWD IDCODE %#8.8x", idcode);
+
+	return status;
+
+}
+
+static struct transport swd_transport = {
+	.name = "swd",
+	.select = swd_select,
+	.init = swd_init,
+};
+
+static void swd_constructor(void) __attribute__((constructor));
+static void swd_constructor(void)
+{
+	transport_register(&swd_transport);
+}
+
+/** Returns true if the current debug session
+ * is using SWD as its transport.
+ */
+bool transport_is_swd(void)
+{
+	return get_current_transport() == &swd_transport;
+}
diff --git a/src/target/arm_adi_v5.c b/src/target/arm_adi_v5.c
index 81edba4e..69a3ce7a 100644
--- a/src/target/arm_adi_v5.c
+++ b/src/target/arm_adi_v5.c
@@ -913,8 +913,12 @@ int ahbap_debugport_init(struct adiv5_dap *dap)
 
 	LOG_DEBUG(" ");
 
-	/* JTAG-DP or SWJ-DP, in JTAG mode */
-	dap->ops = &jtag_dp_ops;
+	/* JTAG-DP or SWJ-DP, in JTAG mode
+	 * ... for SWD mode this is patched as part
+	 * of link switchover
+	 */
+	if (!dap->ops)
+		dap->ops = &jtag_dp_ops;
 
 	/* Default MEM-AP setup.
 	 *
diff --git a/src/target/arm_adi_v5.h b/src/target/arm_adi_v5.h
index 6c1808a5..f64f7c84 100644
--- a/src/target/arm_adi_v5.h
+++ b/src/target/arm_adi_v5.h
@@ -59,6 +59,9 @@
 #define DP_SELECT		0x8		/* JTAG: r/w; SWD: write */
 #define DP_RDBUFF		0xC		/* read-only */
 
+#define WCR_TO_TRN(wcr) (1 + (3 & ((wcr)) >> 8))	/* 1..4 clocks */
+#define WCR_TO_PRESCALE(wcr) (7 & ((wcr)))		/* impl defined */
+
 /* Fields of the DP's AP ABORT register */
 #define DAPABORT		(1 << 0)
 #define STKCMPCLR		(1 << 1)	/* SWD-only */