2 * Copyright (c) 2010 by David Brownell
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software Foundation,
16 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 * Infrastructure for specifying and managing the transport protocol
25 * used in a given debug or programming session.
27 * Examples of "debug-capable" transports are JTAG or SWD.
28 * Additionally, JTAG supports boundary scan testing.
30 * Examples of "programming-capable" transports include SPI or UART;
31 * those are used (often mediated by a ROM bootloader) for ISP style
32 * programming, to perform an initial load of code into flash, or
33 * sometimes into SRAM. Target code could use "variant" options to
34 * decide how to use such protocols. For example, Cortex-M3 cores
35 * from TI/Luminary and from NXP use different protocols for for
36 * UART or SPI based firmware loading.
38 * As a rule, there are protocols layered on top of the transport.
39 * For example, different chip families use JTAG in different ways
40 * for debugging. Also, each family that supports programming over
41 * a UART link for initial firmware loading tends to define its own
42 * messaging and error handling.
45 #include <helper/log.h>
47 #include "transport.h"
49 /*-----------------------------------------------------------------------*/
52 * Infrastructure internals
55 /** List of transports known to OpenOCD. */
56 static struct transport *transport_list;
59 * NULL-terminated Vector of names of transports which the
60 * currently selected debug adapter supports. This is declared
61 * by the time that adapter is fully set up.
63 static const char **allowed_transports;
65 /** * The transport being used for the current OpenOCD session. */
66 static struct transport *session;
68 static int transport_select(struct command_context *ctx, const char *name)
70 /* name may only identify a known transport;
71 * caller guarantees session's transport isn't yet set.*/
72 for (struct transport *t = transport_list; t; t = t->next) {
73 if (strcmp(t->name, name) == 0) {
74 int retval = t->select(ctx);
75 /* select() registers commands specific to this
76 * transport, and may also reset the link, e.g.
77 * forcing it to JTAG or SWD mode.
79 if (retval == ERROR_OK)
82 LOG_ERROR("Error %d selecting '%s' as "
83 "transport", retval, t->name);
88 LOG_ERROR("No transport named '%s' is available.", name);
93 * Called by debug adapter drivers, or affiliated Tcl config scripts,
94 * to declare the set of transports supported by an adapter. When
95 * there is only one member of that set, it is automatically selected.
97 int allow_transports(struct command_context *ctx, const char **vector)
99 /* NOTE: caller is required to provide only a list
100 * of *valid* transport names
102 * REVISIT should we validate that? and insist there's
103 * at least one non-NULL element in that list?
105 if (allowed_transports != NULL || session) {
106 LOG_ERROR("Can't modify the set of allowed transports.");
111 allowed_transports = vector;
113 /* autoselect if there's no choice ... */
115 LOG_INFO("only one transport option; autoselect '%s'",
117 return transport_select(ctx, vector [0]);
120 LOG_DEBUG("allow transport '%s'", *vector++);
127 * Used to verify corrrect adapter driver initialization.
129 * @returns true iff the adapter declared one or more transports.
131 bool transports_are_declared(void)
133 return allowed_transports != NULL;
137 * Registers a transport. There are general purpose transports
138 * (such as JTAG), as well as relatively proprietary ones which are
139 * specific to a given chip (or chip family).
141 * Code implementing a transport needs to register it before it can
142 * be selected and then activated. This is a dynamic process, so
143 * that chips (and families) can define transports as needed (without
144 * nneeding error-prone static tables).
146 * @param new_transport the transport being registered. On a
147 * successful return, this memory is owned by the transport framework.
149 * @returns ERROR_OK on success, else a fault code.
151 int transport_register(struct transport *new_transport)
155 for (t = transport_list; t; t = t->next) {
156 if (strcmp(t->name, new_transport->name) == 0) {
157 LOG_ERROR("transport name already used");
162 if (!new_transport->select || !new_transport->init) {
163 LOG_ERROR("invalid transport %s", new_transport->name);
166 /* splice this into the list */
167 new_transport->next = transport_list;
168 transport_list = new_transport;
169 LOG_DEBUG("register '%s'", t->name);
175 * Returns the transport currently being used by this debug or
176 * programming session.
178 * @returns handle to the read-only transport entity.
180 struct transport *get_current_transport(void)
183 /* REVISIT -- constify */
188 /*-----------------------------------------------------------------------*/
191 * Infrastructure for Tcl interface to transports.
195 * Makes and stores a copy of a set of transports passed as
196 * parameters to a command.
198 * @param vector where the resulting copy is stored, as an argv-style
199 * NULL-terminated vector.
201 COMMAND_HELPER(transport_list_parse, char ***vector)
204 unsigned n = CMD_ARGC;
210 return ERROR_COMMAND_SYNTAX_ERROR;
212 /* our return vector must be NULL terminated */
213 argv = (char **) calloc(n + 1, sizeof(char *));
217 for (unsigned i = 0; i < n; i++) {
220 for (t = transport_list; t; t = t->next) {
221 if (strcmp(t->name, CMD_ARGV[i]) != 0)
223 argv[j++] = strdup(CMD_ARGV[i]);
227 LOG_ERROR("no such transport '%s'", CMD_ARGV[i]);
236 for (unsigned i = 0; i < n; i++)
242 COMMAND_HANDLER(handle_transport_init)
244 LOG_DEBUG("%s", __func__);
246 LOG_ERROR("session's transport is not selected.");
250 return session->init(CMD_CTX);
253 COMMAND_HANDLER(handle_transport_list)
256 return ERROR_COMMAND_SYNTAX_ERROR;
258 command_print(CMD_CTX, "The following transports are available:");
260 for (struct transport *t = transport_list; t; t = t->next)
261 command_print(CMD_CTX, "\t%s", t->name);
267 * Implements the Tcl "transport select" command, choosing the
268 * transport to be used in this debug session from among the
269 * set supported by the debug adapter being used.
271 COMMAND_HANDLER(handle_transport_select)
273 int retval = ERROR_OK;;
276 case 0: /* "select" */
280 LOG_ERROR("session's transport is not selected.");
283 case 1: /* "select FOO" */
284 if(strcmp(session->name, CMD_ARGV[0]) == 0) {
286 LOG_DEBUG("transport '%s' is already selected",
291 /* we can't change this session's transport after-the-fact */
293 LOG_ERROR("session's transport is already selected.");
299 default: /* select FOO BAR */
300 /* we only select *one* transport per session */
301 LOG_ERROR("may only select one transport!");
302 return ERROR_COMMAND_SYNTAX_ERROR;
305 /* Is this transport supported by our debug adapter?
306 * Example, "JTAG-only" means SWD is not supported.
308 * NOTE: requires adapter to have been set up, including
309 * declaring transport via C code or Tcl script.
311 if (!allowed_transports) {
312 LOG_ERROR("Debug adapter doesn't support any transports?");
315 for (unsigned i = 0; allowed_transports[i]; i++) {
317 if (strcmp(allowed_transports[i], CMD_ARGV[0]) == 0)
318 return transport_select(CMD_CTX, CMD_ARGV[0]);
321 LOG_ERROR("Debug adapter doesn't support '%s' "
322 "transport?", CMD_ARGV[0]);
327 /* report the current transport selection */
328 command_print(CMD_CTX, "%s", session->name);
332 static const struct command_registration transport_commands[] = {
335 .handler = handle_transport_init,
336 /* this would be COMMAND_CONFIG ... except that
337 * it needs to trigger event handlers that may
338 * require COMMAND_EXEC ...
341 .help = "Initialize this session's transport",
345 .handler = handle_transport_list,
347 .help = "list all built-in transports",
351 .handler = handle_transport_select,
353 .help = "Select this session's transport",
354 .usage = "[transport_name]",
356 COMMAND_REGISTRATION_DONE
359 static const struct command_registration transport_group[] = {
363 .help = "Transport command group",
364 .chain = transport_commands,
366 COMMAND_REGISTRATION_DONE
370 int transport_register_commands(struct command_context *ctx)
372 return register_commands(ctx, NULL, transport_group);