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, see <http://www.gnu.org/licenses/>.
23 * Infrastructure for specifying and managing the transport protocol
24 * used in a given debug or programming session.
26 * Examples of "debug-capable" transports are JTAG or SWD.
27 * Additionally, JTAG supports boundary scan testing.
29 * Examples of "programming-capable" transports include SPI or UART;
30 * those are used (often mediated by a ROM bootloader) for ISP style
31 * programming, to perform an initial load of code into flash, or
32 * sometimes into SRAM. Target code could use "variant" options to
33 * decide how to use such protocols. For example, Cortex-M3 cores
34 * from TI/Luminary and from NXP use different protocols for for
35 * UART or SPI based firmware loading.
37 * As a rule, there are protocols layered on top of the transport.
38 * For example, different chip families use JTAG in different ways
39 * for debugging. Also, each family that supports programming over
40 * a UART link for initial firmware loading tends to define its own
41 * messaging and error handling.
44 #include <helper/log.h>
45 #include <helper/replacements.h>
46 #include <transport/transport.h>
48 extern struct command_context *global_cmd_ctx;
50 /*-----------------------------------------------------------------------*/
53 * Infrastructure internals
56 /** List of transports known to OpenOCD. */
57 static struct transport *transport_list;
60 * NULL-terminated Vector of names of transports which the
61 * currently selected debug adapter supports. This is declared
62 * by the time that adapter is fully set up.
64 static const char * const *allowed_transports;
66 /** * The transport being used for the current OpenOCD session. */
67 static struct transport *session;
69 static int transport_select(struct command_context *ctx, const char *name)
71 /* name may only identify a known transport;
72 * caller guarantees session's transport isn't yet set.*/
73 for (struct transport *t = transport_list; t; t = t->next) {
74 if (strcmp(t->name, name) == 0) {
75 int retval = t->select(ctx);
76 /* select() registers commands specific to this
77 * transport, and may also reset the link, e.g.
78 * forcing it to JTAG or SWD mode.
80 if (retval == ERROR_OK)
83 LOG_ERROR("Error selecting '%s' as transport", 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 * const *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 * ... allow removals, e.g. external strapping prevents use
106 * of one transport; C code should be definitive about what
107 * can be used when all goes well.
109 if (allowed_transports != NULL || session) {
110 LOG_ERROR("Can't modify the set of allowed transports.");
114 allowed_transports = vector;
116 /* autoselect if there's no choice ... */
118 LOG_INFO("only one transport option; autoselect '%s'", vector[0]);
119 return transport_select(ctx, vector[0]);
126 * Registers a transport. There are general purpose transports
127 * (such as JTAG), as well as relatively proprietary ones which are
128 * specific to a given chip (or chip family).
130 * Code implementing a transport needs to register it before it can
131 * be selected and then activated. This is a dynamic process, so
132 * that chips (and families) can define transports as needed (without
133 * needing error-prone static tables).
135 * @param new_transport the transport being registered. On a
136 * successful return, this memory is owned by the transport framework.
138 * @returns ERROR_OK on success, else a fault code.
140 int transport_register(struct transport *new_transport)
144 for (t = transport_list; t; t = t->next) {
145 if (strcmp(t->name, new_transport->name) == 0) {
146 LOG_ERROR("transport name already used");
151 if (!new_transport->select || !new_transport->init)
152 LOG_ERROR("invalid transport %s", new_transport->name);
154 /* splice this into the list */
155 new_transport->next = transport_list;
156 transport_list = new_transport;
157 LOG_DEBUG("register '%s'", new_transport->name);
163 * Returns the transport currently being used by this debug or
164 * programming session.
166 * @returns handle to the read-only transport entity.
168 struct transport *get_current_transport(void)
170 /* REVISIT -- constify */
174 /*-----------------------------------------------------------------------*/
177 * Infrastructure for Tcl interface to transports.
181 * Makes and stores a copy of a set of transports passed as
182 * parameters to a command.
184 * @param vector where the resulting copy is stored, as an argv-style
185 * NULL-terminated vector.
187 COMMAND_HELPER(transport_list_parse, char ***vector)
190 unsigned n = CMD_ARGC;
196 return ERROR_COMMAND_SYNTAX_ERROR;
198 /* our return vector must be NULL terminated */
199 argv = calloc(n + 1, sizeof(char *));
203 for (unsigned i = 0; i < n; i++) {
206 for (t = transport_list; t; t = t->next) {
207 if (strcmp(t->name, CMD_ARGV[i]) != 0)
209 argv[j++] = strdup(CMD_ARGV[i]);
213 LOG_ERROR("no such transport '%s'", CMD_ARGV[i]);
222 for (unsigned i = 0; i < n; i++)
228 COMMAND_HANDLER(handle_transport_init)
230 LOG_DEBUG("%s", __func__);
232 LOG_ERROR("session transport was not selected. Use 'transport select <transport>'");
234 /* no session transport configured, print transports then fail */
235 LOG_ERROR("Transports available:");
236 const char * const *vector = allowed_transports;
238 LOG_ERROR("%s", *vector);
244 return session->init(CMD_CTX);
247 COMMAND_HANDLER(handle_transport_list)
250 return ERROR_COMMAND_SYNTAX_ERROR;
252 command_print(CMD, "The following transports are available:");
254 for (struct transport *t = transport_list; t; t = t->next)
255 command_print(CMD, "\t%s", t->name);
261 * Implements the Tcl "transport select" command, choosing the
262 * transport to be used in this debug session from among the
263 * set supported by the debug adapter being used. Return value
264 * is scriptable (allowing "if swd then..." etc).
266 static int jim_transport_select(Jim_Interp *interp, int argc, Jim_Obj * const *argv)
270 case 1: /* autoselect if necessary, then return/display current config */
272 if (!allowed_transports) {
273 LOG_ERROR("Debug adapter does not support any transports? Check config file order.");
276 LOG_INFO("auto-selecting first available session transport \"%s\". "
277 "To override use 'transport select <transport>'.", allowed_transports[0]);
278 res = transport_select(global_cmd_ctx, allowed_transports[0]);
282 Jim_SetResultString(interp, session->name, -1);
286 if (!strcmp(session->name, argv[1]->bytes)) {
287 LOG_WARNING("Transport \"%s\" was already selected", session->name);
288 Jim_SetResultString(interp, session->name, -1);
291 LOG_ERROR("Can't change session's transport after the initial selection was made");
296 /* Is this transport supported by our debug adapter?
297 * Example, "JTAG-only" means SWD is not supported.
299 * NOTE: requires adapter to have been set up, with
300 * transports declared via C.
302 if (!allowed_transports) {
303 LOG_ERROR("Debug adapter doesn't support any transports?");
307 for (unsigned i = 0; allowed_transports[i]; i++) {
309 if (strcmp(allowed_transports[i], argv[1]->bytes) == 0) {
310 if (transport_select(global_cmd_ctx, argv[1]->bytes) == ERROR_OK) {
311 Jim_SetResultString(interp, session->name, -1);
318 LOG_ERROR("Debug adapter doesn't support '%s' transport", argv[1]->bytes);
321 Jim_WrongNumArgs(interp, 1, argv, "[too many parameters]");
326 static const struct command_registration transport_commands[] = {
329 .handler = handle_transport_init,
330 /* this would be COMMAND_CONFIG ... except that
331 * it needs to trigger event handlers that may
332 * require COMMAND_EXEC ...
335 .help = "Initialize this session's transport",
340 .handler = handle_transport_list,
342 .help = "list all built-in transports",
347 .jim_handler = jim_transport_select,
349 .help = "Select this session's transport",
350 .usage = "[transport_name]",
352 COMMAND_REGISTRATION_DONE
355 static const struct command_registration transport_group[] = {
359 .help = "Transport command group",
360 .chain = transport_commands,
363 COMMAND_REGISTRATION_DONE
366 int transport_register_commands(struct command_context *ctx)
368 return register_commands(ctx, NULL, transport_group);