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 * 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  * 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 = 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 transport was not selected. Use 'transport select <transport>'");
 243
 244                 /* no session transport configured, print transports then fail */
 245                 LOG_ERROR("Transports available:");
 246                 const char * const *vector = allowed_transports;
 247                 while (*vector) {
 248                         LOG_ERROR("%s", *vector);
 249                         vector++;
 250                 }
 251                 return ERROR_FAIL;
 252         }
 253
 254         return session->init(CMD_CTX);
 255 }
 256
 257 COMMAND_HANDLER(handle_transport_list)
 258 {
 259         if (CMD_ARGC != 0)
 260                 return ERROR_COMMAND_SYNTAX_ERROR;
 261
 262         command_print(CMD_CTX, "The following transports are available:");
 263
 264         for (struct transport *t = transport_list; t; t = t->next)
 265                 command_print(CMD_CTX, "\t%s", t->name);
 266
 267         return ERROR_OK;
 268 }
 269
 270 /**
 271  * Implements the Tcl "transport select" command, choosing the
 272  * transport to be used in this debug session from among the
 273  * set supported by the debug adapter being used.  Return value
 274  * is scriptable (allowing "if swd then..." etc).
 275  */
 276 static int jim_transport_select(Jim_Interp *interp, int argc, Jim_Obj * const *argv)
 277 {
 278         switch (argc) {
 279                 case 1:         /* return/display */
 280                         if (!session) {
 281                                 LOG_ERROR("session transport was not selected. Use 'transport select <transport>'");
 282                                 return JIM_ERR;
 283                         } else {
 284                                 Jim_SetResultString(interp, session->name, -1);
 285                                 return JIM_OK;
 286                         }
 287                         break;
 288                 case 2:         /* assign */
 289                         if (session) {
 290                                 if (!strcmp(session->name, argv[1]->bytes)) {
 291                                         LOG_WARNING("Transport \"%s\" was already selected", session->name);
 292                                         return JIM_OK;
 293                                 } else {
 294                                         LOG_ERROR("Can't change session's transport after the initial selection was made");
 295                                         return JIM_ERR;
 296                                 }
 297                         }
 298
 299                         /* Is this transport supported by our debug adapter?
 300                          * Example, "JTAG-only" means SWD is not supported.
 301                          *
 302                          * NOTE:  requires adapter to have been set up, with
 303                          * transports declared via C.
 304                          */
 305                         if (!allowed_transports) {
 306                                 LOG_ERROR("Debug adapter doesn't support any transports?");
 307                                 return JIM_ERR;
 308                         }
 309
 310                         for (unsigned i = 0; allowed_transports[i]; i++) {
 311
 312                                 if (strcmp(allowed_transports[i], argv[1]->bytes) == 0)
 313                                         return transport_select(global_cmd_ctx, argv[1]->bytes);
 314                         }
 315
 316                         LOG_ERROR("Debug adapter doesn't support '%s' transport", argv[1]->bytes);
 317                         return JIM_ERR;
 318                         break;
 319                 default:
 320                         Jim_WrongNumArgs(interp, 1, argv, "[too many parameters]");
 321                         return JIM_ERR;
 322         }
 323 }
 324
 325 static const struct command_registration transport_commands[] = {
 326         {
 327                 .name = "init",
 328                 .handler = handle_transport_init,
 329                 /* this would be COMMAND_CONFIG ... except that
 330                  * it needs to trigger event handlers that may
 331                  * require COMMAND_EXEC ...
 332                  */
 333                 .mode = COMMAND_ANY,
 334                 .help = "Initialize this session's transport",
 335                 .usage = ""
 336         },
 337         {
 338                 .name = "list",
 339                 .handler = handle_transport_list,
 340                 .mode = COMMAND_ANY,
 341                 .help = "list all built-in transports",
 342                 .usage = ""
 343         },
 344         {
 345                 .name = "select",
 346                 .jim_handler = jim_transport_select,
 347                 .mode = COMMAND_ANY,
 348                 .help = "Select this session's transport",
 349                 .usage = "[transport_name]",
 350         },
 351         COMMAND_REGISTRATION_DONE
 352 };
 353
 354 static const struct command_registration transport_group[] = {
 355         {
 356                 .name = "transport",
 357                 .mode = COMMAND_ANY,
 358                 .help = "Transport command group",
 359                 .chain = transport_commands,
 360                 .usage = ""
 361         },
 362         COMMAND_REGISTRATION_DONE
 363 };
 364
 365 int transport_register_commands(struct command_context *ctx)
 366 {
 367         return register_commands(ctx, NULL, transport_group);
 368 }