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