transport: move files over to transport folder

as we introduce swd and jtag as two transports, we want
to start up with a new transport folder to organize the
code a bit.

3 files changed, 467 insertions, 0 deletions

diff --git a/src/transport/Makefile.am b/src/transport/Makefile.am
new file mode 100644
index 00000000..7c6224a4
--- /dev/null
+++ b/src/transport/Makefile.am
@@ -0,0 +1,11 @@
+include $(top_srcdir)/common.mk
+
+#METASOURCES = AUTO
+noinst_LTLIBRARIES = libtransport.la
+libtransport_la_SOURCES = \
+	transport.c
+
+noinst_HEADERS = \
+	transport.h
+
+MAINTAINERCLEANFILES = $(srcdir)/Makefile.in
diff --git a/src/transport/transport.c b/src/transport/transport.c
new file mode 100644
index 00000000..b5e4b900
--- /dev/null
+++ b/src/transport/transport.c
@@ -0,0 +1,370 @@
+/*
+ * Copyright (c) 2010 by David Brownell
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+/** @file
+ * Infrastructure for specifying and managing the transport protocol
+ * used in a given debug or programming session.
+ *
+ * Examples of "debug-capable" transports are JTAG or SWD.
+ * Additionally, JTAG supports boundary scan testing.
+ *
+ * Examples of "programming-capable" transports include SPI or UART;
+ * those are used (often mediated by a ROM bootloader) for ISP style
+ * programming, to perform an initial load of code into flash, or
+ * sometimes into SRAM.  Target code could use "variant" options to
+ * decide how to use such protocols.  For example, Cortex-M3 cores
+ * from TI/Luminary and from NXP use different protocols for for
+ * UART or SPI based firmware loading.
+ *
+ * As a rule, there are protocols layered on top of the transport.
+ * For example, different chip families use JTAG in different ways
+ * for debugging.  Also, each family that supports programming over
+ * a UART link for initial firmware loading tends to define its own
+ * messaging and error handling.
+ */
+
+#include <helper/log.h>
+
+#include <transport/transport.h>
+
+extern struct command_context *global_cmd_ctx;
+
+
+/*-----------------------------------------------------------------------*/
+
+/*
+ * Infrastructure internals
+ */
+
+/** List of transports known to OpenOCD. */
+static struct transport *transport_list;
+
+/**
+ * NULL-terminated Vector of names of transports which the
+ * currently selected debug adapter supports.  This is declared
+ * by the time that adapter is fully set up.
+ */
+static const char **allowed_transports;
+
+/** * The transport being used for the current OpenOCD session.  */
+static struct transport *session;
+
+static  int transport_select(struct command_context *ctx, const char *name)
+{
+	/* name may only identify a known transport;
+	 * caller guarantees session's transport isn't yet set.*/
+	for (struct transport *t = transport_list; t; t = t->next) {
+			if (strcmp(t->name, name) == 0) {
+				int retval = t->select(ctx);
+			/* select() registers commands specific to this
+			 * transport, and may also reset the link, e.g.
+			 * forcing it to JTAG or SWD mode.
+			 */
+			if (retval == ERROR_OK)
+				session = t;
+			else
+				LOG_ERROR("Error selecting '%s' as "
+					"transport", t->name);
+			return retval;
+		}
+	}
+
+	LOG_ERROR("No transport named '%s' is available.", name);
+	return ERROR_FAIL;
+}
+
+/**
+ * Called by debug adapter drivers, or affiliated Tcl config scripts,
+ * to declare the set of transports supported by an adapter.  When
+ * there is only one member of that set, it is automatically selected.
+ */
+int allow_transports(struct command_context *ctx, const char **vector)
+{
+	/* NOTE:  caller is required to provide only a list
+	 * of *valid* transport names
+	 *
+	 * REVISIT should we validate that?  and insist there's
+	 * at least one non-NULL element in that list?
+	 *
+	 * ... allow removals, e.g. external strapping prevents use
+	 * of one transport; C code should be definitive about what
+	 * can be used when all goes well.
+	 */
+	if (allowed_transports != NULL || session) {
+		LOG_ERROR("Can't modify the set of allowed transports.");
+		return ERROR_FAIL;
+	}
+
+
+	allowed_transports = vector;
+
+	/* autoselect if there's no choice ... */
+	if (!vector[1]) {
+		LOG_INFO("only one transport option; autoselect '%s'",
+				vector[0]);
+		return transport_select(ctx, vector [0]);
+	} else {
+		/* guard against user config errors */
+		LOG_WARNING("must select a transport.");
+		while (*vector) {
+			LOG_DEBUG("allow transport '%s'", *vector);
+			vector++;
+		}
+		return ERROR_OK;
+	}
+}
+
+
+/**
+ * Used to verify corrrect adapter driver initialization.
+ *
+ * @returns true iff the adapter declared one or more transports.
+ */
+bool transports_are_declared(void)
+{
+	return allowed_transports != NULL;
+}
+
+/**
+ * Registers a transport.  There are general purpose transports
+ * (such as JTAG), as well as relatively proprietary ones which are
+ * specific to a given chip (or chip family).
+ *
+ * Code implementing a transport needs to register it before it can
+ * be selected and then activated.  This is a dynamic process, so
+ * that chips (and families) can define transports as needed (without
+ * nneeding error-prone static tables).
+ *
+ * @param new_transport the transport being registered.  On a
+ * successful return, this memory is owned by the transport framework.
+ *
+ * @returns ERROR_OK on success, else a fault code.
+ */
+int transport_register(struct transport *new_transport)
+{
+	struct transport *t;
+
+	for (t = transport_list; t; t = t->next) {
+		if (strcmp(t->name, new_transport->name) == 0) {
+			LOG_ERROR("transport name already used");
+			return ERROR_FAIL;
+		}
+	}
+
+	if (!new_transport->select || !new_transport->init) {
+		LOG_ERROR("invalid transport %s", new_transport->name);
+	}
+
+	/* splice this into the list */
+	new_transport->next = transport_list;
+	transport_list = new_transport;
+	LOG_DEBUG("register '%s'", new_transport->name);
+
+	return ERROR_OK;
+}
+
+/**
+ * Returns the transport currently being used by this debug or
+ * programming session.
+ *
+ * @returns handle to the read-only transport entity.
+ */
+struct transport *get_current_transport(void)
+{
+
+	/* REVISIT -- constify */
+	return session;
+}
+
+
+/*-----------------------------------------------------------------------*/
+
+/*
+ * Infrastructure for Tcl interface to transports.
+ */
+
+/**
+ * Makes and stores a copy of a set of transports passed as
+ * parameters to a command.
+ *
+ * @param vector where the resulting copy is stored, as an argv-style
+ *	NULL-terminated vector.
+ */
+COMMAND_HELPER(transport_list_parse, char ***vector)
+{
+	char **argv;
+	unsigned n = CMD_ARGC;
+	unsigned j = 0;
+
+	*vector = NULL;
+
+	if (n < 1)
+		return ERROR_COMMAND_SYNTAX_ERROR;
+
+	/* our return vector must be NULL terminated */
+	argv = (char **) calloc(n + 1, sizeof(char *));
+	if (argv == NULL)
+		return ERROR_FAIL;
+
+	for (unsigned i = 0; i < n; i++) {
+		struct transport *t;
+
+		for (t = transport_list; t; t = t->next) {
+			if (strcmp(t->name, CMD_ARGV[i]) != 0)
+				continue;
+			argv[j++] = strdup(CMD_ARGV[i]);
+			break;
+		}
+		if (!t) {
+			LOG_ERROR("no such transport '%s'", CMD_ARGV[i]);
+			goto fail;
+		}
+	}
+
+	*vector = argv;
+	return ERROR_OK;
+
+fail:
+	for (unsigned i = 0; i < n; i++)
+		free(argv[i]);
+	free(argv);
+	return ERROR_FAIL;
+}
+
+COMMAND_HANDLER(handle_transport_init)
+{
+	LOG_DEBUG("%s", __func__);
+	if (!session) {
+		LOG_ERROR("session's transport is not selected.");
+		return ERROR_FAIL;
+	}
+
+	return session->init(CMD_CTX);
+}
+
+COMMAND_HANDLER(handle_transport_list)
+{
+	if (CMD_ARGC != 0)
+		return ERROR_COMMAND_SYNTAX_ERROR;
+
+	command_print(CMD_CTX, "The following transports are available:");
+
+	for (struct transport *t = transport_list; t; t = t->next)
+		command_print(CMD_CTX, "\t%s", t->name);
+
+	return ERROR_OK;
+}
+
+/**
+ * Implements the Tcl "transport select" command, choosing the
+ * transport to be used in this debug session from among the
+ * set supported by the debug adapter being used.  Return value
+ * is scriptable (allowing "if swd then..." etc).
+ */
+static int jim_transport_select(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
+{
+	switch (argc) {
+	case 1:			/* return/display */
+		if (!session) {
+			LOG_ERROR("session's transport is not selected.");
+			return JIM_ERR;
+		} else {
+			Jim_SetResultString(interp, session->name, -1);
+			return JIM_OK;
+		}
+		break;
+	case 2:			/* assign */
+	if (session) {
+		/* can't change session's transport after-the-fact */
+		LOG_ERROR("session's transport is already selected.");
+		return JIM_ERR;
+	}
+
+	/* Is this transport supported by our debug adapter?
+	 * Example, "JTAG-only" means SWD is not supported.
+	 *
+	 * NOTE:  requires adapter to have been set up, with
+	 * transports declared via C.
+	 */
+	if (!allowed_transports) {
+		LOG_ERROR("Debug adapter doesn't support any transports?");
+		return JIM_ERR;
+	}
+
+	for (unsigned i = 0; allowed_transports[i]; i++) {
+
+		if (strcmp(allowed_transports[i], argv[1]->bytes) == 0)
+		return transport_select(global_cmd_ctx, argv[1]->bytes);
+	}
+
+		LOG_ERROR("Debug adapter doesn't support '%s' "
+			"transport", argv[1]->bytes);
+		return JIM_ERR;
+		break;
+	default:
+		Jim_WrongNumArgs(interp, 1, argv, "[too many parameters]");
+		return JIM_ERR;
+	}
+}
+
+static const struct command_registration transport_commands[] = {
+	{
+		.name = "init",
+		.handler = handle_transport_init,
+		/* this would be COMMAND_CONFIG ... except that
+		 * it needs to trigger event handlers that may
+		 * require COMMAND_EXEC ...
+		 */
+		.mode = COMMAND_ANY,
+		.help = "Initialize this session's transport",
+	},
+	{
+		.name = "list",
+		.handler = handle_transport_list,
+		.mode = COMMAND_ANY,
+		.help = "list all built-in transports",
+	},
+	{
+		.name = "select",
+		.jim_handler = jim_transport_select,
+		.mode = COMMAND_ANY,
+		.help = "Select this session's transport",
+		.usage = "[transport_name]",
+	},
+	COMMAND_REGISTRATION_DONE
+};
+
+static const struct command_registration transport_group[] = {
+	{
+		.name = "transport",
+		.mode = COMMAND_ANY,
+		.help = "Transport command group",
+		.chain = transport_commands,
+	},
+	COMMAND_REGISTRATION_DONE
+};
+
+
+int transport_register_commands(struct command_context *ctx)
+{
+	return register_commands(ctx, NULL, transport_group);
+}
diff --git a/src/transport/transport.h b/src/transport/transport.h
new file mode 100644
index 00000000..6ece39e5
--- /dev/null
+++ b/src/transport/transport.h
@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2010 by David Brownell
+ * Copyright (C) 2011 Tomasz Boleslaw CEDRO (http://www.tomek.cedro.info)
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+#ifndef TRANSPORT_H
+#define TRANSPORT_H
+
+#include "helper/command.h"
+
+/**
+ * Wrapper for transport lifecycle operations.
+ *
+ * OpenOCD talks to targets through some kind of debugging
+ * or programming adapter, using some protocol that probably
+ * has target-specific aspects.
+ *
+ * A "transport" reflects electrical protocol to the target,
+ * e..g jtag, swd, spi, uart, ... NOT the messaging protocols
+ * layered over it (e.g. JTAG has eICE, CoreSight, Nexus, OnCE,
+ * and more).
+ *
+ * In addition to the lifecycle operations packaged by this
+ * structure, a transport also involves  an interface supported
+ * by debug adapters and used by components such as debug targets.
+ * For non-debug transports,  there may be interfaces used to
+ * write to flash chips.
+ */
+struct transport {
+	/**
+	 * Each transport has a unique name, used to select it
+	 * from among the alternatives.  Examples might include
+	 * "jtag", * "swd", "AVR_ISP" and more.
+	 */
+	const char *name;
+
+	/**
+	 * When a transport is selected, this method registers
+	 * its commands and activates the transport (e.g. resets
+	 * the link).
+	 *
+	 * After those commands are registered, they will often
+	 * be used for further configuration of the debug link.
+	 */
+	int (*select)(struct command_context *ctx);
+
+	/**
+	 * server startup uses this method to validate transport
+	 * configuration.  (For example, with JTAG this interrogates
+	 * the scan chain against the list of expected TAPs.)
+	 */
+	int (*init)(struct command_context *ctx);
+
+	/**
+	 * Transports are stored in a singly linked list.
+	 */
+	struct transport *next;
+};
+
+int transport_register(struct transport *new_transport);
+
+struct transport *get_current_transport(void);
+
+int transport_register_commands(struct command_context *ctx);
+
+COMMAND_HELPER(transport_list_parse, char ***vector);
+
+int allow_transports(struct command_context *ctx, const char **vector);
+
+bool transports_are_declared(void);
+
+#endif