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 extern struct command_context
*global_cmd_ctx
;
52 /*-----------------------------------------------------------------------*/
55 * Infrastructure internals
58 /** List of transports known to OpenOCD. */
59 static struct transport
*transport_list
;
62 * NULL-terminated Vector of names of transports which the
63 * currently selected debug adapter supports. This is declared
64 * by the time that adapter is fully set up.
66 static const char **allowed_transports
;
68 /** * The transport being used for the current OpenOCD session. */
69 static struct transport
*session
;
71 static int transport_select(struct command_context
*ctx
, const char *name
)
73 /* name may only identify a known transport;
74 * caller guarantees session's transport isn't yet set.*/
75 for (struct transport
*t
= transport_list
; t
; t
= t
->next
) {
76 if (strcmp(t
->name
, name
) == 0) {
77 int retval
= t
->select(ctx
);
78 /* select() registers commands specific to this
79 * transport, and may also reset the link, e.g.
80 * forcing it to JTAG or SWD mode.
82 if (retval
== ERROR_OK
)
85 LOG_ERROR("Error selecting '%s' as "
86 "transport", t
->name
);
91 LOG_ERROR("No transport named '%s' is available.", name
);
96 * Called by debug adapter drivers, or affiliated Tcl config scripts,
97 * to declare the set of transports supported by an adapter. When
98 * there is only one member of that set, it is automatically selected.
100 int allow_transports(struct command_context
*ctx
, const char **vector
)
102 /* NOTE: caller is required to provide only a list
103 * of *valid* transport names
105 * REVISIT should we validate that? and insist there's
106 * at least one non-NULL element in that list?
108 * ... allow removals, e.g. external strapping prevents use
109 * of one transport; C code should be definitive about what
110 * can be used when all goes well.
112 if (allowed_transports
!= NULL
|| session
) {
113 LOG_ERROR("Can't modify the set of allowed transports.");
118 allowed_transports
= vector
;
120 /* autoselect if there's no choice ... */
122 LOG_INFO("only one transport option; autoselect '%s'",
124 return transport_select(ctx
, vector
[0]);
126 /* guard against user config errors */
127 LOG_WARNING("must select a transport.");
129 LOG_DEBUG("allow transport '%s'", *vector
++);
136 * Used to verify corrrect adapter driver initialization.
138 * @returns true iff the adapter declared one or more transports.
140 bool transports_are_declared(void)
142 return allowed_transports
!= NULL
;
146 * Registers a transport. There are general purpose transports
147 * (such as JTAG), as well as relatively proprietary ones which are
148 * specific to a given chip (or chip family).
150 * Code implementing a transport needs to register it before it can
151 * be selected and then activated. This is a dynamic process, so
152 * that chips (and families) can define transports as needed (without
153 * nneeding error-prone static tables).
155 * @param new_transport the transport being registered. On a
156 * successful return, this memory is owned by the transport framework.
158 * @returns ERROR_OK on success, else a fault code.
160 int transport_register(struct transport
*new_transport
)
164 for (t
= transport_list
; t
; t
= t
->next
) {
165 if (strcmp(t
->name
, new_transport
->name
) == 0) {
166 LOG_ERROR("transport name already used");
171 if (!new_transport
->select
|| !new_transport
->init
) {
172 LOG_ERROR("invalid transport %s", new_transport
->name
);
175 /* splice this into the list */
176 new_transport
->next
= transport_list
;
177 transport_list
= new_transport
;
178 LOG_DEBUG("register '%s'", new_transport
->name
);
184 * Returns the transport currently being used by this debug or
185 * programming session.
187 * @returns handle to the read-only transport entity.
189 struct transport
*get_current_transport(void)
192 /* REVISIT -- constify */
197 /*-----------------------------------------------------------------------*/
200 * Infrastructure for Tcl interface to transports.
204 * Makes and stores a copy of a set of transports passed as
205 * parameters to a command.
207 * @param vector where the resulting copy is stored, as an argv-style
208 * NULL-terminated vector.
210 COMMAND_HELPER(transport_list_parse
, char ***vector
)
213 unsigned n
= CMD_ARGC
;
219 return ERROR_COMMAND_SYNTAX_ERROR
;
221 /* our return vector must be NULL terminated */
222 argv
= (char **) calloc(n
+ 1, sizeof(char *));
226 for (unsigned i
= 0; i
< n
; i
++) {
229 for (t
= transport_list
; t
; t
= t
->next
) {
230 if (strcmp(t
->name
, CMD_ARGV
[i
]) != 0)
232 argv
[j
++] = strdup(CMD_ARGV
[i
]);
236 LOG_ERROR("no such transport '%s'", CMD_ARGV
[i
]);
245 for (unsigned i
= 0; i
< n
; i
++)
251 COMMAND_HANDLER(handle_transport_init
)
253 LOG_DEBUG("%s", __func__
);
255 LOG_ERROR("session's transport is not selected.");
259 return session
->init(CMD_CTX
);
262 COMMAND_HANDLER(handle_transport_list
)
265 return ERROR_COMMAND_SYNTAX_ERROR
;
267 command_print(CMD_CTX
, "The following transports are available:");
269 for (struct transport
*t
= transport_list
; t
; t
= t
->next
)
270 command_print(CMD_CTX
, "\t%s", t
->name
);
276 * Implements the Tcl "transport select" command, choosing the
277 * transport to be used in this debug session from among the
278 * set supported by the debug adapter being used. Return value
279 * is scriptable (allowing "if swd then..." etc).
281 static int jim_transport_select(Jim_Interp
*interp
, int argc
, Jim_Obj
*const *argv
)
284 case 1: /* return/display */
286 LOG_ERROR("session's transport is not selected.");
289 Jim_SetResultString(interp
, session
->name
, -1);
295 /* can't change session's transport after-the-fact */
296 LOG_ERROR("session's transport is already selected.");
300 /* Is this transport supported by our debug adapter?
301 * Example, "JTAG-only" means SWD is not supported.
303 * NOTE: requires adapter to have been set up, with
304 * transports declared via C.
306 if (!allowed_transports
) {
307 LOG_ERROR("Debug adapter doesn't support any transports?");
311 for (unsigned i
= 0; allowed_transports
[i
]; i
++) {
313 if (strcmp(allowed_transports
[i
], argv
[0]->bytes
) == 0)
314 return transport_select(global_cmd_ctx
, argv
[0]->bytes
);
317 LOG_ERROR("Debug adapter doesn't support '%s' "
318 "transport", argv
[0]->bytes
);
322 Jim_WrongNumArgs(interp
, 1, argv
, "[too many parameters]");
327 static const struct command_registration transport_commands
[] = {
330 .handler
= handle_transport_init
,
331 /* this would be COMMAND_CONFIG ... except that
332 * it needs to trigger event handlers that may
333 * require COMMAND_EXEC ...
336 .help
= "Initialize this session's transport",
340 .handler
= handle_transport_list
,
342 .help
= "list all built-in transports",
346 .jim_handler
= jim_transport_select
,
348 .help
= "Select this session's transport",
349 .usage
= "[transport_name]",
351 COMMAND_REGISTRATION_DONE
354 static const struct command_registration transport_group
[] = {
358 .help
= "Transport command group",
359 .chain
= transport_commands
,
361 COMMAND_REGISTRATION_DONE
365 int transport_register_commands(struct command_context
*ctx
)
367 return register_commands(ctx
, NULL
, transport_group
);