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 }