60228803342ef2ed81441f91ceeb58c3449a8630
[openocd.git] / src / jtag / transport.c
1 /*
2 * Copyright (c) 2010 by David Brownell
3 *
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.
8
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.
13
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
17 */
18
19 #ifdef HAVE_CONFIG_H
20 #include "config.h"
21 #endif
22
23 /** @file
24 * Infrastructure for specifying and managing the transport protocol
25 * used in a given debug or programming session.
26 *
27 * Examples of "debug-capable" transports are JTAG or SWD.
28 * Additionally, JTAG supports boundary scan testing.
29 *
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.
37 *
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.
43 */
44
45 #include <helper/log.h>
46
47 #include "transport.h"
48
49 extern struct command_context *global_cmd_ctx;
50
51
52 /*-----------------------------------------------------------------------*/
53
54 /*
55 * Infrastructure internals
56 */
57
58 /** List of transports known to OpenOCD. */
59 static struct transport *transport_list;
60
61 /**
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.
65 */
66 static const char **allowed_transports;
67
68 /** * The transport being used for the current OpenOCD session. */
69 static struct transport *session;
70
71 static int transport_select(struct command_context *ctx, const char *name)
72 {
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.
81 */
82 if (retval == ERROR_OK)
83 session = t;
84 else
85 LOG_ERROR("Error selecting '%s' as "
86 "transport", t->name);
87 return retval;
88 }
89 }
90
91 LOG_ERROR("No transport named '%s' is available.", name);
92 return ERROR_FAIL;
93 }
94
95 /**
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.
99 */
100 int allow_transports(struct command_context *ctx, const char **vector)
101 {
102 /* NOTE: caller is required to provide only a list
103 * of *valid* transport names
104 *
105 * REVISIT should we validate that? and insist there's
106 * at least one non-NULL element in that list?
107 *
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.
111 */
112 if (allowed_transports != NULL || session) {
113 LOG_ERROR("Can't modify the set of allowed transports.");
114 return ERROR_FAIL;
115 }
116
117
118 allowed_transports = vector;
119
120 /* autoselect if there's no choice ... */
121 if (!vector[1]) {
122 LOG_INFO("only one transport option; autoselect '%s'",
123 vector[0]);
124 return transport_select(ctx, vector [0]);
125 } else {
126 /* guard against user config errors */
127 LOG_WARNING("must select a transport.");
128 while (*vector) {
129 LOG_DEBUG("allow transport '%s'", *vector);
130 vector++;
131 }
132 return ERROR_OK;
133 }
134 }
135
136
137 /**
138 * Used to verify corrrect adapter driver initialization.
139 *
140 * @returns true iff the adapter declared one or more transports.
141 */
142 bool transports_are_declared(void)
143 {
144 return allowed_transports != NULL;
145 }
146
147 /**
148 * Registers a transport. There are general purpose transports
149 * (such as JTAG), as well as relatively proprietary ones which are
150 * specific to a given chip (or chip family).
151 *
152 * Code implementing a transport needs to register it before it can
153 * be selected and then activated. This is a dynamic process, so
154 * that chips (and families) can define transports as needed (without
155 * nneeding error-prone static tables).
156 *
157 * @param new_transport the transport being registered. On a
158 * successful return, this memory is owned by the transport framework.
159 *
160 * @returns ERROR_OK on success, else a fault code.
161 */
162 int transport_register(struct transport *new_transport)
163 {
164 struct transport *t;
165
166 for (t = transport_list; t; t = t->next) {
167 if (strcmp(t->name, new_transport->name) == 0) {
168 LOG_ERROR("transport name already used");
169 return ERROR_FAIL;
170 }
171 }
172
173 if (!new_transport->select || !new_transport->init) {
174 LOG_ERROR("invalid transport %s", new_transport->name);
175 }
176
177 /* splice this into the list */
178 new_transport->next = transport_list;
179 transport_list = new_transport;
180 LOG_DEBUG("register '%s'", new_transport->name);
181
182 return ERROR_OK;
183 }
184
185 /**
186 * Returns the transport currently being used by this debug or
187 * programming session.
188 *
189 * @returns handle to the read-only transport entity.
190 */
191 struct transport *get_current_transport(void)
192 {
193
194 /* REVISIT -- constify */
195 return session;
196 }
197
198
199 /*-----------------------------------------------------------------------*/
200
201 /*
202 * Infrastructure for Tcl interface to transports.
203 */
204
205 /**
206 * Makes and stores a copy of a set of transports passed as
207 * parameters to a command.
208 *
209 * @param vector where the resulting copy is stored, as an argv-style
210 * NULL-terminated vector.
211 */
212 COMMAND_HELPER(transport_list_parse, char ***vector)
213 {
214 char **argv;
215 unsigned n = CMD_ARGC;
216 unsigned j = 0;
217
218 *vector = NULL;
219
220 if (n < 1)
221 return ERROR_COMMAND_SYNTAX_ERROR;
222
223 /* our return vector must be NULL terminated */
224 argv = (char **) calloc(n + 1, sizeof(char *));
225 if (argv == NULL)
226 return ERROR_FAIL;
227
228 for (unsigned i = 0; i < n; i++) {
229 struct transport *t;
230
231 for (t = transport_list; t; t = t->next) {
232 if (strcmp(t->name, CMD_ARGV[i]) != 0)
233 continue;
234 argv[j++] = strdup(CMD_ARGV[i]);
235 break;
236 }
237 if (!t) {
238 LOG_ERROR("no such transport '%s'", CMD_ARGV[i]);
239 goto fail;
240 }
241 }
242
243 *vector = argv;
244 return ERROR_OK;
245
246 fail:
247 for (unsigned i = 0; i < n; i++)
248 free(argv[i]);
249 free(argv);
250 return ERROR_FAIL;
251 }
252
253 COMMAND_HANDLER(handle_transport_init)
254 {
255 LOG_DEBUG("%s", __func__);
256 if (!session) {
257 LOG_ERROR("session's transport is not selected.");
258 return ERROR_FAIL;
259 }
260
261 return session->init(CMD_CTX);
262 }
263
264 COMMAND_HANDLER(handle_transport_list)
265 {
266 if (CMD_ARGC != 0)
267 return ERROR_COMMAND_SYNTAX_ERROR;
268
269 command_print(CMD_CTX, "The following transports are available:");
270
271 for (struct transport *t = transport_list; t; t = t->next)
272 command_print(CMD_CTX, "\t%s", t->name);
273
274 return ERROR_OK;
275 }
276
277 /**
278 * Implements the Tcl "transport select" command, choosing the
279 * transport to be used in this debug session from among the
280 * set supported by the debug adapter being used. Return value
281 * is scriptable (allowing "if swd then..." etc).
282 */
283 static int jim_transport_select(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
284 {
285 switch (argc) {
286 case 1: /* return/display */
287 if (!session) {
288 LOG_ERROR("session's transport is not selected.");
289 return JIM_ERR;
290 } else {
291 Jim_SetResultString(interp, session->name, -1);
292 return JIM_OK;
293 }
294 break;
295 case 2: /* assign */
296 if (session) {
297 /* can't change session's transport after-the-fact */
298 LOG_ERROR("session's transport is already selected.");
299 return JIM_ERR;
300 }
301
302 /* Is this transport supported by our debug adapter?
303 * Example, "JTAG-only" means SWD is not supported.
304 *
305 * NOTE: requires adapter to have been set up, with
306 * transports declared via C.
307 */
308 if (!allowed_transports) {
309 LOG_ERROR("Debug adapter doesn't support any transports?");
310 return JIM_ERR;
311 }
312
313 for (unsigned i = 0; allowed_transports[i]; i++) {
314
315 if (strcmp(allowed_transports[i], argv[1]->bytes) == 0)
316 return transport_select(global_cmd_ctx, argv[1]->bytes);
317 }
318
319 LOG_ERROR("Debug adapter doesn't support '%s' "
320 "transport", argv[1]->bytes);
321 return JIM_ERR;
322 break;
323 default:
324 Jim_WrongNumArgs(interp, 1, argv, "[too many parameters]");
325 return JIM_ERR;
326 }
327 }
328
329 static const struct command_registration transport_commands[] = {
330 {
331 .name = "init",
332 .handler = handle_transport_init,
333 /* this would be COMMAND_CONFIG ... except that
334 * it needs to trigger event handlers that may
335 * require COMMAND_EXEC ...
336 */
337 .mode = COMMAND_ANY,
338 .help = "Initialize this session's transport",
339 },
340 {
341 .name = "list",
342 .handler = handle_transport_list,
343 .mode = COMMAND_ANY,
344 .help = "list all built-in transports",
345 },
346 {
347 .name = "select",
348 .jim_handler = jim_transport_select,
349 .mode = COMMAND_ANY,
350 .help = "Select this session's transport",
351 .usage = "[transport_name]",
352 },
353 COMMAND_REGISTRATION_DONE
354 };
355
356 static const struct command_registration transport_group[] = {
357 {
358 .name = "transport",
359 .mode = COMMAND_ANY,
360 .help = "Transport command group",
361 .chain = transport_commands,
362 },
363 COMMAND_REGISTRATION_DONE
364 };
365
366
367 int transport_register_commands(struct command_context *ctx)
368 {
369 return register_commands(ctx, NULL, transport_group);
370 }