Cleanup of config/includes.
[fw/openocd] / 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, see <http://www.gnu.org/licenses/>.
16  */
17
18 #ifdef HAVE_CONFIG_H
19 #include "config.h"
20 #endif
21
22 /** @file
23  * Infrastructure for specifying and managing the transport protocol
24  * used in a given debug or programming session.
25  *
26  * Examples of "debug-capable" transports are JTAG or SWD.
27  * Additionally, JTAG supports boundary scan testing.
28  *
29  * Examples of "programming-capable" transports include SPI or UART;
30  * those are used (often mediated by a ROM bootloader) for ISP style
31  * programming, to perform an initial load of code into flash, or
32  * sometimes into SRAM.  Target code could use "variant" options to
33  * decide how to use such protocols.  For example, Cortex-M3 cores
34  * from TI/Luminary and from NXP use different protocols for for
35  * UART or SPI based firmware loading.
36  *
37  * As a rule, there are protocols layered on top of the transport.
38  * For example, different chip families use JTAG in different ways
39  * for debugging.  Also, each family that supports programming over
40  * a UART link for initial firmware loading tends to define its own
41  * messaging and error handling.
42  */
43
44 #include <helper/log.h>
45 #include <helper/replacements.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 * const *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 * const *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  * Registers a transport.  There are general purpose transports
127  * (such as JTAG), as well as relatively proprietary ones which are
128  * specific to a given chip (or chip family).
129  *
130  * Code implementing a transport needs to register it before it can
131  * be selected and then activated.  This is a dynamic process, so
132  * that chips (and families) can define transports as needed (without
133  * needing error-prone static tables).
134  *
135  * @param new_transport the transport being registered.  On a
136  * successful return, this memory is owned by the transport framework.
137  *
138  * @returns ERROR_OK on success, else a fault code.
139  */
140 int transport_register(struct transport *new_transport)
141 {
142         struct transport *t;
143
144         for (t = transport_list; t; t = t->next) {
145                 if (strcmp(t->name, new_transport->name) == 0) {
146                         LOG_ERROR("transport name already used");
147                         return ERROR_FAIL;
148                 }
149         }
150
151         if (!new_transport->select || !new_transport->init)
152                 LOG_ERROR("invalid transport %s", new_transport->name);
153
154         /* splice this into the list */
155         new_transport->next = transport_list;
156         transport_list = new_transport;
157         LOG_DEBUG("register '%s'", new_transport->name);
158
159         return ERROR_OK;
160 }
161
162 /**
163  * Returns the transport currently being used by this debug or
164  * programming session.
165  *
166  * @returns handle to the read-only transport entity.
167  */
168 struct transport *get_current_transport(void)
169 {
170         /* REVISIT -- constify */
171         return session;
172 }
173
174 /*-----------------------------------------------------------------------*/
175
176 /*
177  * Infrastructure for Tcl interface to transports.
178  */
179
180 /**
181  * Makes and stores a copy of a set of transports passed as
182  * parameters to a command.
183  *
184  * @param vector where the resulting copy is stored, as an argv-style
185  *      NULL-terminated vector.
186  */
187 COMMAND_HELPER(transport_list_parse, char ***vector)
188 {
189         char **argv;
190         unsigned n = CMD_ARGC;
191         unsigned j = 0;
192
193         *vector = NULL;
194
195         if (n < 1)
196                 return ERROR_COMMAND_SYNTAX_ERROR;
197
198         /* our return vector must be NULL terminated */
199         argv = calloc(n + 1, sizeof(char *));
200         if (argv == NULL)
201                 return ERROR_FAIL;
202
203         for (unsigned i = 0; i < n; i++) {
204                 struct transport *t;
205
206                 for (t = transport_list; t; t = t->next) {
207                         if (strcmp(t->name, CMD_ARGV[i]) != 0)
208                                 continue;
209                         argv[j++] = strdup(CMD_ARGV[i]);
210                         break;
211                 }
212                 if (!t) {
213                         LOG_ERROR("no such transport '%s'", CMD_ARGV[i]);
214                         goto fail;
215                 }
216         }
217
218         *vector = argv;
219         return ERROR_OK;
220
221 fail:
222         for (unsigned i = 0; i < n; i++)
223                 free(argv[i]);
224         free(argv);
225         return ERROR_FAIL;
226 }
227
228 COMMAND_HANDLER(handle_transport_init)
229 {
230         LOG_DEBUG("%s", __func__);
231         if (!session) {
232                 LOG_ERROR("session transport was not selected. Use 'transport select <transport>'");
233
234                 /* no session transport configured, print transports then fail */
235                 LOG_ERROR("Transports available:");
236                 const char * const *vector = allowed_transports;
237                 while (*vector) {
238                         LOG_ERROR("%s", *vector);
239                         vector++;
240                 }
241                 return ERROR_FAIL;
242         }
243
244         return session->init(CMD_CTX);
245 }
246
247 COMMAND_HANDLER(handle_transport_list)
248 {
249         if (CMD_ARGC != 0)
250                 return ERROR_COMMAND_SYNTAX_ERROR;
251
252         command_print(CMD, "The following transports are available:");
253
254         for (struct transport *t = transport_list; t; t = t->next)
255                 command_print(CMD, "\t%s", t->name);
256
257         return ERROR_OK;
258 }
259
260 /**
261  * Implements the Tcl "transport select" command, choosing the
262  * transport to be used in this debug session from among the
263  * set supported by the debug adapter being used.  Return value
264  * is scriptable (allowing "if swd then..." etc).
265  */
266 static int jim_transport_select(Jim_Interp *interp, int argc, Jim_Obj * const *argv)
267 {
268         int res;
269         switch (argc) {
270                 case 1: /* autoselect if necessary, then return/display current config */
271                         if (!session) {
272                                 if (!allowed_transports) {
273                                         LOG_ERROR("Debug adapter does not support any transports? Check config file order.");
274                                         return JIM_ERR;
275                                 }
276                                 LOG_INFO("auto-selecting first available session transport \"%s\". "
277                                          "To override use 'transport select <transport>'.", allowed_transports[0]);
278                                 res = transport_select(global_cmd_ctx, allowed_transports[0]);
279                                 if (res != JIM_OK)
280                                         return res;
281                         }
282                         Jim_SetResultString(interp, session->name, -1);
283                         return JIM_OK;
284                 case 2: /* assign */
285                         if (session) {
286                                 if (!strcmp(session->name, argv[1]->bytes)) {
287                                         LOG_WARNING("Transport \"%s\" was already selected", session->name);
288                                         Jim_SetResultString(interp, session->name, -1);
289                                         return JIM_OK;
290                                 } else {
291                                         LOG_ERROR("Can't change session's transport after the initial selection was made");
292                                         return JIM_ERR;
293                                 }
294                         }
295
296                         /* Is this transport supported by our debug adapter?
297                          * Example, "JTAG-only" means SWD is not supported.
298                          *
299                          * NOTE:  requires adapter to have been set up, with
300                          * transports declared via C.
301                          */
302                         if (!allowed_transports) {
303                                 LOG_ERROR("Debug adapter doesn't support any transports?");
304                                 return JIM_ERR;
305                         }
306
307                         for (unsigned i = 0; allowed_transports[i]; i++) {
308
309                                 if (strcmp(allowed_transports[i], argv[1]->bytes) == 0) {
310                                         if (transport_select(global_cmd_ctx, argv[1]->bytes) == ERROR_OK) {
311                                                 Jim_SetResultString(interp, session->name, -1);
312                                                 return JIM_OK;
313                                         }
314                                         return JIM_ERR;
315                                 }
316                         }
317
318                         LOG_ERROR("Debug adapter doesn't support '%s' transport", argv[1]->bytes);
319                         return JIM_ERR;
320                 default:
321                         Jim_WrongNumArgs(interp, 1, argv, "[too many parameters]");
322                         return JIM_ERR;
323         }
324 }
325
326 static const struct command_registration transport_commands[] = {
327         {
328                 .name = "init",
329                 .handler = handle_transport_init,
330                 /* this would be COMMAND_CONFIG ... except that
331                  * it needs to trigger event handlers that may
332                  * require COMMAND_EXEC ...
333                  */
334                 .mode = COMMAND_ANY,
335                 .help = "Initialize this session's transport",
336                 .usage = ""
337         },
338         {
339                 .name = "list",
340                 .handler = handle_transport_list,
341                 .mode = COMMAND_ANY,
342                 .help = "list all built-in transports",
343                 .usage = ""
344         },
345         {
346                 .name = "select",
347                 .jim_handler = jim_transport_select,
348                 .mode = COMMAND_ANY,
349                 .help = "Select this session's transport",
350                 .usage = "[transport_name]",
351         },
352         COMMAND_REGISTRATION_DONE
353 };
354
355 static const struct command_registration transport_group[] = {
356         {
357                 .name = "transport",
358                 .mode = COMMAND_ANY,
359                 .help = "Transport command group",
360                 .chain = transport_commands,
361                 .usage = ""
362         },
363         COMMAND_REGISTRATION_DONE
364 };
365
366 int transport_register_commands(struct command_context *ctx)
367 {
368         return register_commands(ctx, NULL, transport_group);
369 }