This adds the guts of a transport framework with initialization.
Each debug adapter can declare the transports it supports, and
exactly one transport is initialized. (with its commands).
* Define a new "struct transport with initialization hooks and a few
sub commands to support it:
"list" ... list the transports configured (just "jtag" for now)
"select" ... makes the debug session use that transport
"init" ... initializes that transport
* "interface_transports" ... declares transports the current interface
can support. (Some will do this from C code instead, when there are
no hardware versioning (or other) issues to prevent it.
Eventually src/jtag should probably become src/transport, moving
jtag-specific stuff to transport/jtag.
There's currently an automagic default to selecting JTAG, if no
config script does otherwise (including implicitly, by setting up
a JTAG-only debug adapter).
====================================================================
MISSING STUFF includes target hooks (e.g. what transports does a
given target work with, setting up JTAG-or-SWD targets ("dap new"
etc) ... and other stuff that must wait until SWD works a bit.
Also missing: documentation. This works OK with a cross-section
of current JTAG-only configurations.
====================================================================
---
doc/openocd.texi | 12 +
src/jtag/Makefile.am | 2
src/jtag/core.c | 38 ++++
src/jtag/drivers/ft2232.c | 14 +
src/jtag/tcl.c | 27 +++
src/jtag/transport.c | 353 ++++++++++++++++++++++++++++++++++++++++++++
src/jtag/transport.h | 72 ++++++++
src/openocd.c | 49 +++---
8 files changed, 548 insertions(+), 19 deletions(-)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2096,6 +2096,18 @@ List the interface drivers that have bee
the running copy of OpenOCD.
@end deffn
+...@deffn Command {interface_transports} transport...
+Declares the transports which the current debug adapter
+supports. The parameters are a list of one or more
+transports, such as "jtag" for a JTAG-only debug adapter,
+or or "jtag swd" for one which also supports SWD.
+
+In many cases the adapter driver will declare that list
+directly, so no Tcl declaration should be used. This
+command may be used when there are differences
+which the adapter's driver can't detect.
+...@end deffn
+
@deffn Command {jtag interface}
Returns the name of the interface driver being used.
@end deffn
--- a/src/jtag/Makefile.am
+++ b/src/jtag/Makefile.am
@@ -57,6 +57,7 @@ libjtag_la_SOURCES = \
interface.c \
interfaces.c \
tcl.c \
+ transport.c \
$(DRIVERFILES)
noinst_HEADERS = \
@@ -65,6 +66,7 @@ noinst_HEADERS = \
interfaces.h \
minidriver.h \
jtag.h \
+ transport.h \
minidriver/minidriver_imp.h \
minidummy/jtag_minidriver.h
--- a/src/jtag/core.c
+++ b/src/jtag/core.c
@@ -33,11 +33,15 @@
#include "jtag.h"
#include "interface.h"
+#include "transport.h"
#ifdef HAVE_STRINGS_H
#include <strings.h>
#endif
+/* SVF and XSVF are higher level JTAG command sets (for boundary scan) */
+#include "svf/svf.h"
+#include "xsvf/xsvf.h"
/// The number of JTAG queue flushes (for profiling and debugging purposes).
static int jtag_flush_queue_count;
@@ -1728,3 +1732,37 @@ unsigned jtag_get_ntrst_assert_width(voi
{
return jtag_ntrst_assert_width;
}
+
+static int jtag_select(struct command_context *ctx)
+{
+ int retval;
+
+ /* NOTE: interface init must already have been done.
+ * That works with only C code ... no Tcl glue required.
+ */
+
+
+ retval = jtag_register_commands(ctx);
+
+ if (retval != ERROR_OK)
+ return retval;
+
+ retval = svf_register_commands(ctx);
+
+ if (retval != ERROR_OK)
+ return retval;
+
+ return xsvf_register_commands(ctx);
+}
+
+static struct transport jtag_transport = {
+ .name = "jtag",
+ .select = jtag_select,
+ .init = jtag_init,
+};
+
+static void jtag_constructor(void) __attribute__((constructor));
+static void jtag_constructor(void)
+{
+ transport_register(&jtag_transport);
+}
--- a/src/jtag/drivers/ft2232.c
+++ b/src/jtag/drivers/ft2232.c
@@ -69,6 +69,7 @@
/* project specific includes */
#include <jtag/interface.h>
+#include <jtag/transport.h>
#include <helper/time_support.h>
#if IS_CYGWIN == 1
@@ -155,6 +156,7 @@ struct ft2232_layout {
void (*reset)(int trst, int srst);
void (*blink)(void);
int channel;
+ const char **transports;
};
/* init procedures for supported layouts */
@@ -195,6 +197,10 @@ static void turtle_jtag_blink(void);
static void signalyzer_h_blink(void);
static void ktlink_blink(void);
+/* common transport support options */
+static const char *jtag_only[] = { "jtag", NULL };
+//static const char *jtag_and_swd[] = { "jtag", "swd", NULL };
+
static const struct ft2232_layout ft2232_layouts[] =
{
{ .name = "usbjtag",
@@ -220,10 +226,12 @@ static const struct ft2232_layout ft223
{ .name = "evb_lm3s811",
.init = usbjtag_init,
.reset = usbjtag_reset,
+// .transports = jtag_and_swd;
},
{ .name = "luminary_icdi",
.init = usbjtag_init,
.reset = usbjtag_reset,
+// .transports = jtag_and_swd;
},
{ .name = "olimex-jtag",
.init = olimex_jtag_init,
@@ -3140,7 +3148,11 @@ COMMAND_HANDLER(ft2232_handle_layout_com
for (const struct ft2232_layout *l = ft2232_layouts; l->name; l++) {
if (strcmp(l->name, CMD_ARGV[0]) == 0) {
layout = l;
- return ERROR_OK;
+ /* This may also select the transport
+ * if we only suppport one of them.
+ */
+ return allow_transports(CMD_CTX,
+ l->transports ? : jtag_only);
}
}
--- a/src/jtag/tcl.c
+++ b/src/jtag/tcl.c
@@ -35,6 +35,7 @@
#include "minidriver.h"
#include "interface.h"
#include "interfaces.h"
+#include "transport.h"
#ifdef HAVE_STRINGS_H
#include <strings.h>
@@ -1043,6 +1044,25 @@ COMMAND_HANDLER(handle_interface_command
return ERROR_JTAG_INVALID_INTERFACE;
}
+COMMAND_HANDLER(interface_transport_command)
+{
+ char **transports;
+ int retval;
+
+ retval = CALL_COMMAND_HANDLER(transport_list_parse, &transports);
+ if (retval != ERROR_OK) {
+ return retval;
+
+ retval = allow_transports(CMD_CTX, (const char **)transports);
+ if (retval != ERROR_OK) {
+ for (unsigned i = 0; transports[i]; i++)
+ free(transports[i]);
+ free(transports);
+ }
+ }
+ return retval;
+}
+
COMMAND_HANDLER(handle_scan_chain_command)
{
struct jtag_tap *tap;
@@ -1640,6 +1660,13 @@ static const struct command_registration
.usage = "driver_name",
},
{
+ .name = "interface_transports",
+ .handler = interface_transport_command,
+ .mode = COMMAND_CONFIG,
+ .help = "Declare transports the interface supports.",
+ .usage = "transport ... ",
+ },
+ {
.name = "interface_list",
.handler = handle_interface_list_command,
.mode = COMMAND_ANY,
--- /dev/null
+++ b/src/jtag/transport.c
@@ -0,0 +1,353 @@
+/*
+ * 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.
+ *
+ * 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.h"
+
+/*-----------------------------------------------------------------------*/
+
+/*
+ * 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 %d selecting '%s' as "
+ "transport", retval, 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?
+ */
+ if (allowed_transports != NULL || session) {
+ LOG_ERROR("Can't modify the set of allowed transports.");
+ return ERROR_FAIL;
+ }
+
+
+ allowed_transports = vector;
+
+ /* force one selection if there's no choice ... */
+ if (!vector[1]) {
+ LOG_INFO("only one transport option; force '%s'", vector[0]);
+ return transport_select(ctx, vector [0]);
+ } else {
+ while (*vector)
+ LOG_DEBUG("allow transport '%s'", *vector++);
+ return ERROR_OK;
+ }
+}
+
+/**
+ * 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'", t->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.
+ */
+COMMAND_HANDLER(handle_transport_select)
+{
+ int retval = ERROR_OK;;
+
+ switch (CMD_ARGC) {
+ case 0: /* "select" */
+ if (session) {
+ goto show;
+ }
+ LOG_ERROR("session's transport is not selected.");
+ return ERROR_FAIL;
+
+ case 1: /* "select FOO" */
+ /* we can't change this session's transport after-the-fact */
+ if (session) {
+ LOG_ERROR("session's transport is already selected.");
+ return ERROR_FAIL;
+ }
+ break;
+
+ default: /* select FOO BAR */
+ /* we only select *one* transport per session */
+ LOG_ERROR("may only select one transport!");
+ return ERROR_COMMAND_SYNTAX_ERROR;
+ }
+
+ /* Is this transport supported by our debug adapter?
+ * Example, "JTAG-only" means SWD is not supported.
+ *
+ * NOTE: requires adapter to have been set up, including
+ * declaring transport via C code or Tcl script.
+ */
+ if (!allowed_transports) {
+ LOG_ERROR("Debug adapter doesn't support any transports?");
+ return ERROR_FAIL;
+ }
+ for (unsigned i = 0; allowed_transports[i]; i++) {
+
+ if (strcmp(allowed_transports[i], CMD_ARGV[0]) == 0)
+ retval = transport_select(CMD_CTX, CMD_ARGV[0]);
+ else {
+ LOG_ERROR("Debug adapter doesn't support '%s' "
+ "transport?", CMD_ARGV[0]);
+ return ERROR_FAIL;
+ }
+ }
+
+
+show:
+ /* report the current transport selection */
+ command_print(CMD_CTX, "%s", session->name);
+ return retval;
+}
+
+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",
+ .handler = handle_transport_select,
+ .mode = COMMAND_CONFIG,
+ .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);
+}
--- /dev/null
+++ b/src/jtag/transport.h
@@ -0,0 +1,72 @@
+/*
+ * 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
+ */
+
+#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).
+ */
+struct transport {
+ /**
+ * Each transport has a unique name, used to select it
+ * from among the alternatives. Examples 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);
--- a/src/openocd.c
+++ b/src/openocd.c
@@ -31,10 +31,9 @@
#include "openocd.h"
#include <jtag/driver.h>
#include <jtag/jtag.h>
+#include <jtag/transport.h>
#include <helper/ioutil.h>
#include <helper/configuration.h>
-#include <xsvf/xsvf.h>
-#include <svf/svf.h>
#include <flash/nor/core.h>
#include <flash/nand/core.h>
#include <pld/pld.h>
@@ -122,20 +121,37 @@ COMMAND_HANDLER(handle_init_command)
}
LOG_DEBUG("Debug Adapter init complete");
- /* Try to initialize & examine the JTAG chain at this point,
- * but continue startup regardless. Note that platforms
- * need to be able to provide JTAG event handlers that use
- * a variety of JTAG operations in order to do that...
+ /* REVISIT can we drop the "default transport" notion?
+ * for now, we do it primarily for legacy support.
+ *
+ * NOTE: for jtag, 'jtag newtap" won't be available until JTAG
+ * selection registers those commands. Also, platforms may rely
+ * on JTAG event handlers which also use such JTAG operations.
+ *
*/
- command_context_mode(CMD_CTX, COMMAND_EXEC);
- if (command_run_line(CMD_CTX, "jtag init") == ERROR_OK)
- {
- LOG_DEBUG("Examining targets...");
- if (target_examine() != ERROR_OK)
- LOG_DEBUG("target examination failed");
+ if (get_current_transport() == NULL) {
+ LOG_WARNING("trying JTAG as default transport");
+ retval = command_run_line(CMD_CTX,
+ "transport select jtag");
+ if (retval != ERROR_OK)
+ return retval;
}
- else
- LOG_WARNING("jtag initialization failed; try 'jtag init'
again.");
+
+ /* "transport init" verifies the expected devices are present;
+ * for JTAG, it checks the list of configured TAPs against
+ * what's discoverable, possibly with help from the platform's
+ * JTAG event handlers. (which require COMMAND_EXEC)
+ */
+ command_context_mode(CMD_CTX, COMMAND_EXEC);
+
+ retval = command_run_line(CMD_CTX, "transport init");
+ if (ERROR_OK != retval)
+ return ERROR_FAIL;
+
+ LOG_DEBUG("Examining targets...");
+ if (target_examine() != ERROR_OK)
+ LOG_DEBUG("target examination failed");
+
command_context_mode(CMD_CTX, COMMAND_CONFIG);
if (command_run_line(CMD_CTX, "flash init") != ERROR_OK)
@@ -208,16 +224,13 @@ struct command_context *setup_command_ha
&server_register_commands,
&gdb_register_commands,
&log_register_commands,
+ &transport_register_commands,
&interface_register_commands,
- &jtag_register_commands,
- &xsvf_register_commands,
- &svf_register_commands,
&target_register_commands,
&flash_register_commands,
&nand_register_commands,
&pld_register_commands,
&mflash_register_commands,
- NULL
};
for (unsigned i = 0; NULL != command_registrants[i]; i++)
{
_______________________________________________
Openocd-development mailing list
[email protected]
https://lists.berlios.de/mailman/listinfo/openocd-development
