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 /*-----------------------------------------------------------------------*/
  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 **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 %d selecting '%s' as "
  83                                         "transport", retval, 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         if (allowed_transports != NULL || session) {
 106                 LOG_ERROR("Can't modify the set of allowed transports.");
 107                 return ERROR_FAIL;
 108         }
 109
 110
 111         allowed_transports = vector;
 112
 113         /* autoselect if there's no choice ... */
 114         if (!vector[1]) {
 115                 LOG_INFO("only one transport option; autoselect '%s'",
 116                                 vector[0]);
 117                 return transport_select(ctx, vector [0]);
 118         } else {
 119                 while (*vector)
 120                         LOG_DEBUG("allow transport '%s'", *vector++);
 121                 return ERROR_OK;
 122         }
 123 }
 124
 125
 126 /**
 127  * Used to verify corrrect adapter driver initialization.
 128  *
 129  * @returns true iff the adapter declared one or more transports.
 130  */
 131 bool transports_are_declared(void)
 132 {
 133         return allowed_transports != NULL;
 134 }
 135
 136 /**
 137  * Registers a transport.  There are general purpose transports
 138  * (such as JTAG), as well as relatively proprietary ones which are
 139  * specific to a given chip (or chip family).
 140  *
 141  * Code implementing a transport needs to register it before it can
 142  * be selected and then activated.  This is a dynamic process, so
 143  * that chips (and families) can define transports as needed (without
 144  * nneeding error-prone static tables).
 145  *
 146  * @param new_transport the transport being registered.  On a
 147  * successful return, this memory is owned by the transport framework.
 148  *
 149  * @returns ERROR_OK on success, else a fault code.
 150  */
 151 int transport_register(struct transport *new_transport)
 152 {
 153         struct transport *t;
 154
 155         for (t = transport_list; t; t = t->next) {
 156                 if (strcmp(t->name, new_transport->name) == 0) {
 157                         LOG_ERROR("transport name already used");
 158                         return ERROR_FAIL;
 159                 }
 160         }
 161
 162         if (!new_transport->select || !new_transport->init) {
 163                 LOG_ERROR("invalid transport %s", new_transport->name);
 164         }
 165
 166         /* splice this into the list */
 167         new_transport->next = transport_list;
 168         transport_list = new_transport;
 169         LOG_DEBUG("register '%s'", t->name);
 170
 171         return ERROR_OK;
 172 }
 173
 174 /**
 175  * Returns the transport currently being used by this debug or
 176  * programming session.
 177  *
 178  * @returns handle to the read-only transport entity.
 179  */
 180 struct transport *get_current_transport(void)
 181 {
 182
 183         /* REVISIT -- constify */
 184         return session;
 185 }
 186
 187
 188 /*-----------------------------------------------------------------------*/
 189
 190 /*
 191  * Infrastructure for Tcl interface to transports.
 192  */
 193
 194 /**
 195  * Makes and stores a copy of a set of transports passed as
 196  * parameters to a command.
 197  *
 198  * @param vector where the resulting copy is stored, as an argv-style
 199  *      NULL-terminated vector.
 200  */
 201 COMMAND_HELPER(transport_list_parse, char ***vector)
 202 {
 203         char **argv;
 204         unsigned n = CMD_ARGC;
 205         unsigned j = 0;
 206
 207         *vector = NULL;
 208
 209         if (n < 1)
 210                 return ERROR_COMMAND_SYNTAX_ERROR;
 211
 212         /* our return vector must be NULL terminated */
 213         argv = (char **) calloc(n + 1, sizeof(char *));
 214         if (argv == NULL)
 215                 return ERROR_FAIL;
 216
 217         for (unsigned i = 0; i < n; i++) {
 218                 struct transport *t;
 219
 220                 for (t = transport_list; t; t = t->next) {
 221                         if (strcmp(t->name, CMD_ARGV[i]) != 0)
 222                                 continue;
 223                         argv[j++] = strdup(CMD_ARGV[i]);
 224                         break;
 225                 }
 226                 if (!t) {
 227                         LOG_ERROR("no such transport '%s'", CMD_ARGV[i]);
 228                         goto fail;
 229                 }
 230         }
 231
 232         *vector = argv;
 233         return ERROR_OK;
 234
 235 fail:
 236         for (unsigned i = 0; i < n; i++)
 237                 free(argv[i]);
 238         free(argv);
 239         return ERROR_FAIL;
 240 }
 241
 242 COMMAND_HANDLER(handle_transport_init)
 243 {
 244         LOG_DEBUG("%s", __func__);
 245         if (!session) {
 246                 LOG_ERROR("session's transport is not selected.");
 247                 return ERROR_FAIL;
 248         }
 249
 250         return session->init(CMD_CTX);
 251 }
 252
 253 COMMAND_HANDLER(handle_transport_list)
 254 {
 255         if (CMD_ARGC != 0)
 256                 return ERROR_COMMAND_SYNTAX_ERROR;
 257
 258         command_print(CMD_CTX, "The following transports are available:");
 259
 260         for (struct transport *t = transport_list; t; t = t->next)
 261                 command_print(CMD_CTX, "\t%s", t->name);
 262
 263         return ERROR_OK;
 264 }
 265
 266 /**
 267  * Implements the Tcl "transport select" command, choosing the
 268  * transport to be used in this debug session from among the
 269  * set supported by the debug adapter being used.
 270  */
 271 COMMAND_HANDLER(handle_transport_select)
 272 {
 273         int retval = ERROR_OK;;
 274
 275         switch (CMD_ARGC) {
 276         case 0:                 /* "select" */
 277                 if (session) {
 278                         goto show;
 279                 }
 280                 LOG_ERROR("session's transport is not selected.");
 281                 return ERROR_FAIL;
 282
 283         case 1:                 /* "select FOO" */
 284                 if ((session!= NULL) && strcmp(session->name, CMD_ARGV[0]) == 0) {
 285                         /* NOP */
 286                         LOG_DEBUG("transport '%s' is already selected",
 287                                         CMD_ARGV[0]);
 288                         return ERROR_OK;
 289                 } else {
 290                         /* we can't change this session's transport after-the-fact */
 291                         if (session) {
 292                                 LOG_ERROR("session's transport is already selected.");
 293                                 return ERROR_FAIL;
 294                         }
 295                 }
 296                 break;
 297
 298         default:                /* select FOO BAR */
 299                 /* we only select *one* transport per session */
 300                 LOG_ERROR("may only select one transport!");
 301                 return ERROR_COMMAND_SYNTAX_ERROR;
 302         }
 303
 304         /* Is this transport supported by our debug adapter?
 305          * Example, "JTAG-only" means SWD is not supported.
 306          *
 307          * NOTE:  requires adapter to have been set up, including
 308          * declaring transport via C code or Tcl script.
 309          */
 310         if (!allowed_transports) {
 311                 LOG_ERROR("Debug adapter doesn't support any transports?");
 312                 return ERROR_FAIL;
 313         }
 314         for (unsigned i = 0; allowed_transports[i]; i++) {
 315
 316                 if (strcmp(allowed_transports[i], CMD_ARGV[0]) == 0)
 317                         return transport_select(CMD_CTX, CMD_ARGV[0]);
 318         }
 319
 320         LOG_ERROR("Debug adapter doesn't support '%s' "
 321                         "transport?", CMD_ARGV[0]);
 322         return ERROR_FAIL;
 323
 324
 325 show:
 326         /* report the current transport selection */
 327         command_print(CMD_CTX, "%s", session->name);
 328         return retval;
 329 }
 330
 331 static const struct command_registration transport_commands[] = {
 332         {
 333                 .name = "init",
 334                 .handler = handle_transport_init,
 335                 /* this would be COMMAND_CONFIG ... except that
 336                  * it needs to trigger event handlers that may
 337                  * require COMMAND_EXEC ...
 338                  */
 339                 .mode = COMMAND_ANY,
 340                 .help = "Initialize this session's transport",
 341         },
 342         {
 343                 .name = "list",
 344                 .handler = handle_transport_list,
 345                 .mode = COMMAND_ANY,
 346                 .help = "list all built-in transports",
 347         },
 348         {
 349                 .name = "select",
 350                 .handler = handle_transport_select,
 351                 .mode = COMMAND_ANY,
 352                 .help = "Select this session's transport",
 353                 .usage = "[transport_name]",
 354         },
 355         COMMAND_REGISTRATION_DONE
 356 };
 357
 358 static const struct command_registration transport_group[] = {
 359         {
 360                 .name = "transport",
 361                 .mode = COMMAND_ANY,
 362                 .help = "Transport command group",
 363                 .chain = transport_commands,
 364         },
 365         COMMAND_REGISTRATION_DONE
 366 };
 367
 368
 369 int transport_register_commands(struct command_context *ctx)
 370 {
 371         return register_commands(ctx, NULL, transport_group);
 372 }