1 // SPDX-License-Identifier: GPL-2.0-or-later
4 * Copyright (c) 2010 by David Brownell
12 * Infrastructure for specifying and managing the transport protocol
13 * used in a given debug or programming session.
15 * Examples of "debug-capable" transports are JTAG or SWD.
16 * Additionally, JTAG supports boundary scan testing.
18 * Examples of "programming-capable" transports include SPI or UART;
19 * those are used (often mediated by a ROM bootloader) for ISP style
20 * programming, to perform an initial load of code into flash, or
21 * sometimes into SRAM. Target code could use "variant" options to
22 * decide how to use such protocols. For example, Cortex-M3 cores
23 * from TI/Luminary and from NXP use different protocols for for
24 * UART or SPI based firmware loading.
26 * As a rule, there are protocols layered on top of the transport.
27 * For example, different chip families use JTAG in different ways
28 * for debugging. Also, each family that supports programming over
29 * a UART link for initial firmware loading tends to define its own
30 * messaging and error handling.
33 #include <helper/log.h>
34 #include <helper/replacements.h>
35 #include <transport/transport.h>
37 extern struct command_context
*global_cmd_ctx
;
39 /*-----------------------------------------------------------------------*/
42 * Infrastructure internals
45 /** List of transports known to OpenOCD. */
46 static struct transport
*transport_list
;
49 * NULL-terminated Vector of names of transports which the
50 * currently selected debug adapter supports. This is declared
51 * by the time that adapter is fully set up.
53 static const char * const *allowed_transports
;
55 /** * The transport being used for the current OpenOCD session. */
56 static struct transport
*session
;
58 static int transport_select(struct command_context
*ctx
, const char *name
)
60 /* name may only identify a known transport;
61 * caller guarantees session's transport isn't yet set.*/
62 for (struct transport
*t
= transport_list
; t
; t
= t
->next
) {
63 if (strcmp(t
->name
, name
) == 0) {
64 int retval
= t
->select(ctx
);
65 /* select() registers commands specific to this
66 * transport, and may also reset the link, e.g.
67 * forcing it to JTAG or SWD mode.
69 if (retval
== ERROR_OK
)
72 LOG_ERROR("Error selecting '%s' as transport", t
->name
);
77 LOG_ERROR("No transport named '%s' is available.", name
);
82 * Called by debug adapter drivers, or affiliated Tcl config scripts,
83 * to declare the set of transports supported by an adapter. When
84 * there is only one member of that set, it is automatically selected.
86 int allow_transports(struct command_context
*ctx
, const char * const *vector
)
88 /* NOTE: caller is required to provide only a list
89 * of *valid* transport names
91 * REVISIT should we validate that? and insist there's
92 * at least one non-NULL element in that list?
94 * ... allow removals, e.g. external strapping prevents use
95 * of one transport; C code should be definitive about what
96 * can be used when all goes well.
98 if (allowed_transports
|| session
) {
99 LOG_ERROR("Can't modify the set of allowed transports.");
103 allowed_transports
= vector
;
105 /* autoselect if there's no choice ... */
107 LOG_INFO("only one transport option; autoselecting '%s'", vector
[0]);
108 return transport_select(ctx
, vector
[0]);
115 * Registers a transport. There are general purpose transports
116 * (such as JTAG), as well as relatively proprietary ones which are
117 * specific to a given chip (or chip family).
119 * Code implementing a transport needs to register it before it can
120 * be selected and then activated. This is a dynamic process, so
121 * that chips (and families) can define transports as needed (without
122 * needing error-prone static tables).
124 * @param new_transport the transport being registered. On a
125 * successful return, this memory is owned by the transport framework.
127 * @returns ERROR_OK on success, else a fault code.
129 int transport_register(struct transport
*new_transport
)
133 for (t
= transport_list
; t
; t
= t
->next
) {
134 if (strcmp(t
->name
, new_transport
->name
) == 0) {
135 LOG_ERROR("transport name already used");
140 if (!new_transport
->select
|| !new_transport
->init
)
141 LOG_ERROR("invalid transport %s", new_transport
->name
);
143 /* splice this into the list */
144 new_transport
->next
= transport_list
;
145 transport_list
= new_transport
;
146 LOG_DEBUG("register '%s'", new_transport
->name
);
152 * Returns the transport currently being used by this debug or
153 * programming session.
155 * @returns handle to the read-only transport entity.
157 struct transport
*get_current_transport(void)
159 /* REVISIT -- constify */
163 /*-----------------------------------------------------------------------*/
166 * Infrastructure for Tcl interface to transports.
170 * Makes and stores a copy of a set of transports passed as
171 * parameters to a command.
173 * @param vector where the resulting copy is stored, as an argv-style
174 * NULL-terminated vector.
176 COMMAND_HELPER(transport_list_parse
, char ***vector
)
179 unsigned n
= CMD_ARGC
;
185 return ERROR_COMMAND_SYNTAX_ERROR
;
187 /* our return vector must be NULL terminated */
188 argv
= calloc(n
+ 1, sizeof(char *));
192 for (unsigned i
= 0; i
< n
; i
++) {
195 for (t
= transport_list
; t
; t
= t
->next
) {
196 if (strcmp(t
->name
, CMD_ARGV
[i
]) != 0)
198 argv
[j
++] = strdup(CMD_ARGV
[i
]);
202 LOG_ERROR("no such transport '%s'", CMD_ARGV
[i
]);
211 for (unsigned i
= 0; i
< n
; i
++)
217 COMMAND_HANDLER(handle_transport_init
)
219 LOG_DEBUG("%s", __func__
);
221 LOG_ERROR("session transport was not selected. Use 'transport select <transport>'");
223 /* no session transport configured, print transports then fail */
224 LOG_ERROR("Transports available:");
225 const char * const *vector
= allowed_transports
;
227 LOG_ERROR("%s", *vector
);
233 return session
->init(CMD_CTX
);
236 COMMAND_HANDLER(handle_transport_list
)
239 return ERROR_COMMAND_SYNTAX_ERROR
;
241 command_print(CMD
, "The following transports are available:");
243 for (struct transport
*t
= transport_list
; t
; t
= t
->next
)
244 command_print(CMD
, "\t%s", t
->name
);
250 * Implements the Tcl "transport select" command, choosing the
251 * transport to be used in this debug session from among the
252 * set supported by the debug adapter being used. Return value
253 * is scriptable (allowing "if swd then..." etc).
255 COMMAND_HANDLER(handle_transport_select
)
258 return ERROR_COMMAND_SYNTAX_ERROR
;
261 /* autoselect if necessary, then return/display current config */
263 if (!allowed_transports
) {
264 command_print(CMD
, "Debug adapter does not support any transports? Check config file order.");
267 LOG_INFO("auto-selecting first available session transport \"%s\". "
268 "To override use 'transport select <transport>'.", allowed_transports
[0]);
269 int retval
= transport_select(CMD_CTX
, allowed_transports
[0]);
270 if (retval
!= ERROR_OK
)
273 command_print(CMD
, "%s", session
->name
);
277 /* assign transport */
279 if (!strcmp(session
->name
, CMD_ARGV
[0])) {
280 LOG_WARNING("Transport \"%s\" was already selected", session
->name
);
281 command_print(CMD
, "%s", session
->name
);
284 command_print(CMD
, "Can't change session's transport after the initial selection was made");
288 /* Is this transport supported by our debug adapter?
289 * Example, "JTAG-only" means SWD is not supported.
291 * NOTE: requires adapter to have been set up, with
292 * transports declared via C.
294 if (!allowed_transports
) {
295 command_print(CMD
, "Debug adapter doesn't support any transports?");
299 for (unsigned int i
= 0; allowed_transports
[i
]; i
++) {
300 if (!strcmp(allowed_transports
[i
], CMD_ARGV
[0])) {
301 int retval
= transport_select(CMD_CTX
, CMD_ARGV
[0]);
302 if (retval
!= ERROR_OK
)
304 command_print(CMD
, "%s", session
->name
);
309 command_print(CMD
, "Debug adapter doesn't support '%s' transport", CMD_ARGV
[0]);
313 static const struct command_registration transport_commands
[] = {
316 .handler
= handle_transport_init
,
317 /* this would be COMMAND_CONFIG ... except that
318 * it needs to trigger event handlers that may
319 * require COMMAND_EXEC ...
322 .help
= "Initialize this session's transport",
327 .handler
= handle_transport_list
,
329 .help
= "list all built-in transports",
334 .handler
= handle_transport_select
,
336 .help
= "Select this session's transport",
337 .usage
= "[transport_name]",
339 COMMAND_REGISTRATION_DONE
342 static const struct command_registration transport_group
[] = {
346 .help
= "Transport command group",
347 .chain
= transport_commands
,
350 COMMAND_REGISTRATION_DONE
353 int transport_register_commands(struct command_context
*ctx
)
355 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)