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
);
Linking to existing account procedure
If you already have an account and want to add another login method
you
MUST first sign in with your existing account and
then change URL to read
https://review.openocd.org/login/?link
to get to this page again but this time it'll work for linking. Thank you.
SSH host keys fingerprints
1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=.. |
|+o.. . |
|*.o . . |
|+B . . . |
|Bo. = o S |
|Oo.+ + = |
|oB=.* = . o |
| =+=.+ + E |
|. .=o . o |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)