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 <transport/transport.h>
  46
  47 extern struct command_context *global_cmd_ctx;
  48
  49 /*-----------------------------------------------------------------------*/
  50
  51 /*
  52  * Infrastructure internals
  53  */
  54
  55 /** List of transports known to OpenOCD. */
  56 static struct transport *transport_list;
  57
  58 /**
  59  * NULL-terminated Vector of names of transports which the
  60  * currently selected debug adapter supports.  This is declared
  61  * by the time that adapter is fully set up.
  62  */
  63 static const char * const *allowed_transports;
  64
  65 /** * The transport being used for the current OpenOCD session.  */
  66 static struct transport *session;
  67
  68 static int transport_select(struct command_context *ctx, const char *name)
  69 {
  70         /* name may only identify a known transport;
  71          * caller guarantees session's transport isn't yet set.*/
  72         for (struct transport *t = transport_list; t; t = t->next) {
  73                 if (strcmp(t->name, name) == 0) {
  74                         int retval = t->select(ctx);
  75                         /* select() registers commands specific to this
  76                          * transport, and may also reset the link, e.g.
  77                          * forcing it to JTAG or SWD mode.
  78                          */
  79                         if (retval == ERROR_OK)
  80                                 session = t;
  81                         else
  82                                 LOG_ERROR("Error selecting '%s' as transport", t->name);
  83                         return retval;
  84                 }
  85         }
  86
  87         LOG_ERROR("No transport named '%s' is available.", name);
  88         return ERROR_FAIL;
  89 }
  90
  91 /**
  92  * Called by debug adapter drivers, or affiliated Tcl config scripts,
  93  * to declare the set of transports supported by an adapter.  When
  94  * there is only one member of that set, it is automatically selected.
  95  */
  96 int allow_transports(struct command_context *ctx, const char * const *vector)
  97 {
  98         /* NOTE:  caller is required to provide only a list
  99          * of *valid* transport names
 100          *
 101          * REVISIT should we validate that?  and insist there's
 102          * at least one non-NULL element in that list?
 103          *
 104          * ... allow removals, e.g. external strapping prevents use
 105          * of one transport; C code should be definitive about what
 106          * can be used when all goes well.
 107          */
 108         if (allowed_transports != NULL || session) {
 109                 LOG_ERROR("Can't modify the set of allowed transports.");
 110                 return ERROR_FAIL;
 111         }
 112
 113         allowed_transports = vector;
 114
 115         /* autoselect if there's no choice ... */
 116         if (!vector[1]) {
 117                 LOG_INFO("only one transport option; autoselect '%s'", vector[0]);
 118                 return transport_select(ctx, vector[0]);
 119         }
 120
 121         return ERROR_OK;
 122 }
 123
 124 /**
 125  * Used to verify corrrect adapter driver initialization.
 126  *
 127  * @returns true iff the adapter declared one or more transports.
 128  */
 129 bool transports_are_declared(void)
 130 {
 131         return allowed_transports != NULL;
 132 }
 133
 134 /**
 135  * Registers a transport.  There are general purpose transports
 136  * (such as JTAG), as well as relatively proprietary ones which are
 137  * specific to a given chip (or chip family).
 138  *
 139  * Code implementing a transport needs to register it before it can
 140  * be selected and then activated.  This is a dynamic process, so
 141  * that chips (and families) can define transports as needed (without
 142  * nneeding error-prone static tables).
 143  *
 144  * @param new_transport the transport being registered.  On a
 145  * successful return, this memory is owned by the transport framework.
 146  *
 147  * @returns ERROR_OK on success, else a fault code.
 148  */
 149 int transport_register(struct transport *new_transport)
 150 {
 151         struct transport *t;
 152
 153         for (t = transport_list; t; t = t->next) {
 154                 if (strcmp(t->name, new_transport->name) == 0) {
 155                         LOG_ERROR("transport name already used");
 156                         return ERROR_FAIL;
 157                 }
 158         }
 159
 160         if (!new_transport->select || !new_transport->init)
 161                 LOG_ERROR("invalid transport %s", new_transport->name);
 162
 163         /* splice this into the list */
 164         new_transport->next = transport_list;
 165         transport_list = new_transport;
 166         LOG_DEBUG("register '%s'", new_transport->name);
 167
 168         return ERROR_OK;
 169 }
 170
 171 /**
 172  * Returns the transport currently being used by this debug or
 173  * programming session.
 174  *
 175  * @returns handle to the read-only transport entity.
 176  */
 177 struct transport *get_current_transport(void)
 178 {
 179         /* REVISIT -- constify */
 180         return session;
 181 }
 182
 183 /*-----------------------------------------------------------------------*/
 184
 185 /*
 186  * Infrastructure for Tcl interface to transports.
 187  */
 188
 189 /**
 190  * Makes and stores a copy of a set of transports passed as
 191  * parameters to a command.
 192  *
 193  * @param vector where the resulting copy is stored, as an argv-style
 194  *      NULL-terminated vector.
 195  */
 196 COMMAND_HELPER(transport_list_parse, char ***vector)
 197 {
 198         char **argv;
 199         unsigned n = CMD_ARGC;
 200         unsigned j = 0;
 201
 202         *vector = NULL;
 203
 204         if (n < 1)
 205                 return ERROR_COMMAND_SYNTAX_ERROR;
 206
 207         /* our return vector must be NULL terminated */
 208         argv = calloc(n + 1, sizeof(char *));
 209         if (argv == NULL)
 210                 return ERROR_FAIL;
 211
 212         for (unsigned i = 0; i < n; i++) {
 213                 struct transport *t;
 214
 215                 for (t = transport_list; t; t = t->next) {
 216                         if (strcmp(t->name, CMD_ARGV[i]) != 0)
 217                                 continue;
 218                         argv[j++] = strdup(CMD_ARGV[i]);
 219                         break;
 220                 }
 221                 if (!t) {
 222                         LOG_ERROR("no such transport '%s'", CMD_ARGV[i]);
 223                         goto fail;
 224                 }
 225         }
 226
 227         *vector = argv;
 228         return ERROR_OK;
 229
 230 fail:
 231         for (unsigned i = 0; i < n; i++)
 232                 free(argv[i]);
 233         free(argv);
 234         return ERROR_FAIL;
 235 }
 236
 237 COMMAND_HANDLER(handle_transport_init)
 238 {
 239         LOG_DEBUG("%s", __func__);
 240         if (!session) {
 241                 LOG_ERROR("session transport was not selected. Use 'transport select <transport>'");
 242
 243                 /* no session transport configured, print transports then fail */
 244                 LOG_ERROR("Transports available:");
 245                 const char * const *vector = allowed_transports;
 246                 while (*vector) {
 247                         LOG_ERROR("%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         int res;
 278         switch (argc) {
 279                 case 1: /* autoselect if necessary, then return/display current config */
 280                         if (!session) {
 281                                 if (!allowed_transports) {
 282                                         LOG_ERROR("Debug adapter does not support any transports? Check config file order.");
 283                                         return JIM_ERR;
 284                                 }
 285                                 LOG_INFO("auto-selecting first available session transport \"%s\". "
 286                                          "To override use 'transport select <transport>'.", allowed_transports[0]);
 287                                 res = transport_select(global_cmd_ctx, allowed_transports[0]);
 288                                 if (res != JIM_OK)
 289                                         return res;
 290                         }
 291                         Jim_SetResultString(interp, session->name, -1);
 292                         return JIM_OK;
 293                         break;
 294                 case 2: /* assign */
 295                         if (session) {
 296                                 if (!strcmp(session->name, argv[1]->bytes)) {
 297                                         LOG_WARNING("Transport \"%s\" was already selected", session->name);
 298                                         Jim_SetResultString(interp, session->name, -1);
 299                                         return JIM_OK;
 300                                 } else {
 301                                         LOG_ERROR("Can't change session's transport after the initial selection was made");
 302                                         return JIM_ERR;
 303                                 }
 304                         }
 305
 306                         /* Is this transport supported by our debug adapter?
 307                          * Example, "JTAG-only" means SWD is not supported.
 308                          *
 309                          * NOTE:  requires adapter to have been set up, with
 310                          * transports declared via C.
 311                          */
 312                         if (!allowed_transports) {
 313                                 LOG_ERROR("Debug adapter doesn't support any transports?");
 314                                 return JIM_ERR;
 315                         }
 316
 317                         for (unsigned i = 0; allowed_transports[i]; i++) {
 318
 319                                 if (strcmp(allowed_transports[i], argv[1]->bytes) == 0) {
 320                                         if (transport_select(global_cmd_ctx, argv[1]->bytes) == ERROR_OK) {
 321                                                 Jim_SetResultString(interp, session->name, -1);
 322                                                 return JIM_OK;
 323                                         }
 324                                         return JIM_ERR;
 325                                 }
 326                         }
 327
 328                         LOG_ERROR("Debug adapter doesn't support '%s' transport", argv[1]->bytes);
 329                         return JIM_ERR;
 330                         break;
 331                 default:
 332                         Jim_WrongNumArgs(interp, 1, argv, "[too many parameters]");
 333                         return JIM_ERR;
 334         }
 335 }
 336
 337 static const struct command_registration transport_commands[] = {
 338         {
 339                 .name = "init",
 340                 .handler = handle_transport_init,
 341                 /* this would be COMMAND_CONFIG ... except that
 342                  * it needs to trigger event handlers that may
 343                  * require COMMAND_EXEC ...
 344                  */
 345                 .mode = COMMAND_ANY,
 346                 .help = "Initialize this session's transport",
 347                 .usage = ""
 348         },
 349         {
 350                 .name = "list",
 351                 .handler = handle_transport_list,
 352                 .mode = COMMAND_ANY,
 353                 .help = "list all built-in transports",
 354                 .usage = ""
 355         },
 356         {
 357                 .name = "select",
 358                 .jim_handler = jim_transport_select,
 359                 .mode = COMMAND_ANY,
 360                 .help = "Select this session's transport",
 361                 .usage = "[transport_name]",
 362         },
 363         COMMAND_REGISTRATION_DONE
 364 };
 365
 366 static const struct command_registration transport_group[] = {
 367         {
 368                 .name = "transport",
 369                 .mode = COMMAND_ANY,
 370                 .help = "Transport command group",
 371                 .chain = transport_commands,
 372                 .usage = ""
 373         },
 374         COMMAND_REGISTRATION_DONE
 375 };
 376
 377 int transport_register_commands(struct command_context *ctx)
 378 {
 379         return register_commands(ctx, NULL, transport_group);
 380 }