You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

364 lines
9.8 KiB

  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. * This program is distributed in the hope that it will be useful,
  9. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11. * GNU General Public License for more details.
  12. * You should have received a copy of the GNU General Public License
  13. * along with this program; if not, write to the Free Software Foundation,
  14. * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  15. */
  16. #ifdef HAVE_CONFIG_H
  17. #include "config.h"
  18. #endif
  19. /** @file
  20. * Infrastructure for specifying and managing the transport protocol
  21. * used in a given debug or programming session.
  22. *
  23. * Examples of "debug-capable" transports are JTAG or SWD.
  24. * Additionally, JTAG supports boundary scan testing.
  25. *
  26. * Examples of "programming-capable" transports include SPI or UART;
  27. * those are used (often mediated by a ROM bootloader) for ISP style
  28. * programming, to perform an initial load of code into flash, or
  29. * sometimes into SRAM. Target code could use "variant" options to
  30. * decide how to use such protocols. For example, Cortex-M3 cores
  31. * from TI/Luminary and from NXP use different protocols for for
  32. * UART or SPI based firmware loading.
  33. *
  34. * As a rule, there are protocols layered on top of the transport.
  35. * For example, different chip families use JTAG in different ways
  36. * for debugging. Also, each family that supports programming over
  37. * a UART link for initial firmware loading tends to define its own
  38. * messaging and error handling.
  39. */
  40. #include <helper/log.h>
  41. #include <transport/transport.h>
  42. extern struct command_context *global_cmd_ctx;
  43. /*-----------------------------------------------------------------------*/
  44. /*
  45. * Infrastructure internals
  46. */
  47. /** List of transports known to OpenOCD. */
  48. static struct transport *transport_list;
  49. /**
  50. * NULL-terminated Vector of names of transports which the
  51. * currently selected debug adapter supports. This is declared
  52. * by the time that adapter is fully set up.
  53. */
  54. static const char **allowed_transports;
  55. /** * The transport being used for the current OpenOCD session. */
  56. static struct transport *session;
  57. static int transport_select(struct command_context *ctx, const char *name)
  58. {
  59. /* name may only identify a known transport;
  60. * caller guarantees session's transport isn't yet set.*/
  61. for (struct transport *t = transport_list; t; t = t->next) {
  62. if (strcmp(t->name, name) == 0) {
  63. int retval = t->select(ctx);
  64. /* select() registers commands specific to this
  65. * transport, and may also reset the link, e.g.
  66. * forcing it to JTAG or SWD mode.
  67. */
  68. if (retval == ERROR_OK)
  69. session = t;
  70. else
  71. LOG_ERROR("Error selecting '%s' as transport", t->name);
  72. return retval;
  73. }
  74. }
  75. LOG_ERROR("No transport named '%s' is available.", name);
  76. return ERROR_FAIL;
  77. }
  78. /**
  79. * Called by debug adapter drivers, or affiliated Tcl config scripts,
  80. * to declare the set of transports supported by an adapter. When
  81. * there is only one member of that set, it is automatically selected.
  82. */
  83. int allow_transports(struct command_context *ctx, const char **vector)
  84. {
  85. /* NOTE: caller is required to provide only a list
  86. * of *valid* transport names
  87. *
  88. * REVISIT should we validate that? and insist there's
  89. * at least one non-NULL element in that list?
  90. *
  91. * ... allow removals, e.g. external strapping prevents use
  92. * of one transport; C code should be definitive about what
  93. * can be used when all goes well.
  94. */
  95. if (allowed_transports != NULL || session) {
  96. LOG_ERROR("Can't modify the set of allowed transports.");
  97. return ERROR_FAIL;
  98. }
  99. allowed_transports = vector;
  100. /* autoselect if there's no choice ... */
  101. if (!vector[1]) {
  102. LOG_INFO("only one transport option; autoselect '%s'", vector[0]);
  103. return transport_select(ctx, vector[0]);
  104. }
  105. return ERROR_OK;
  106. }
  107. /**
  108. * Used to verify corrrect adapter driver initialization.
  109. *
  110. * @returns true iff the adapter declared one or more transports.
  111. */
  112. bool transports_are_declared(void)
  113. {
  114. return allowed_transports != NULL;
  115. }
  116. /**
  117. * Registers a transport. There are general purpose transports
  118. * (such as JTAG), as well as relatively proprietary ones which are
  119. * specific to a given chip (or chip family).
  120. *
  121. * Code implementing a transport needs to register it before it can
  122. * be selected and then activated. This is a dynamic process, so
  123. * that chips (and families) can define transports as needed (without
  124. * nneeding error-prone static tables).
  125. *
  126. * @param new_transport the transport being registered. On a
  127. * successful return, this memory is owned by the transport framework.
  128. *
  129. * @returns ERROR_OK on success, else a fault code.
  130. */
  131. int transport_register(struct transport *new_transport)
  132. {
  133. struct transport *t;
  134. for (t = transport_list; t; t = t->next) {
  135. if (strcmp(t->name, new_transport->name) == 0) {
  136. LOG_ERROR("transport name already used");
  137. return ERROR_FAIL;
  138. }
  139. }
  140. if (!new_transport->select || !new_transport->init)
  141. LOG_ERROR("invalid transport %s", new_transport->name);
  142. /* splice this into the list */
  143. new_transport->next = transport_list;
  144. transport_list = new_transport;
  145. LOG_DEBUG("register '%s'", new_transport->name);
  146. return ERROR_OK;
  147. }
  148. /**
  149. * Returns the transport currently being used by this debug or
  150. * programming session.
  151. *
  152. * @returns handle to the read-only transport entity.
  153. */
  154. struct transport *get_current_transport(void)
  155. {
  156. /* REVISIT -- constify */
  157. return session;
  158. }
  159. /*-----------------------------------------------------------------------*/
  160. /*
  161. * Infrastructure for Tcl interface to transports.
  162. */
  163. /**
  164. * Makes and stores a copy of a set of transports passed as
  165. * parameters to a command.
  166. *
  167. * @param vector where the resulting copy is stored, as an argv-style
  168. * NULL-terminated vector.
  169. */
  170. COMMAND_HELPER(transport_list_parse, char ***vector)
  171. {
  172. char **argv;
  173. unsigned n = CMD_ARGC;
  174. unsigned j = 0;
  175. *vector = NULL;
  176. if (n < 1)
  177. return ERROR_COMMAND_SYNTAX_ERROR;
  178. /* our return vector must be NULL terminated */
  179. argv = (char **) calloc(n + 1, sizeof(char *));
  180. if (argv == NULL)
  181. return ERROR_FAIL;
  182. for (unsigned i = 0; i < n; i++) {
  183. struct transport *t;
  184. for (t = transport_list; t; t = t->next) {
  185. if (strcmp(t->name, CMD_ARGV[i]) != 0)
  186. continue;
  187. argv[j++] = strdup(CMD_ARGV[i]);
  188. break;
  189. }
  190. if (!t) {
  191. LOG_ERROR("no such transport '%s'", CMD_ARGV[i]);
  192. goto fail;
  193. }
  194. }
  195. *vector = argv;
  196. return ERROR_OK;
  197. fail:
  198. for (unsigned i = 0; i < n; i++)
  199. free(argv[i]);
  200. free(argv);
  201. return ERROR_FAIL;
  202. }
  203. COMMAND_HANDLER(handle_transport_init)
  204. {
  205. LOG_DEBUG("%s", __func__);
  206. if (!session) {
  207. LOG_ERROR("session's transport is not selected.");
  208. /* no session transport configured, print transports then fail */
  209. const char **vector = allowed_transports;
  210. while (*vector) {
  211. LOG_ERROR("allow transport '%s'", *vector);
  212. vector++;
  213. }
  214. return ERROR_FAIL;
  215. }
  216. return session->init(CMD_CTX);
  217. }
  218. COMMAND_HANDLER(handle_transport_list)
  219. {
  220. if (CMD_ARGC != 0)
  221. return ERROR_COMMAND_SYNTAX_ERROR;
  222. command_print(CMD_CTX, "The following transports are available:");
  223. for (struct transport *t = transport_list; t; t = t->next)
  224. command_print(CMD_CTX, "\t%s", t->name);
  225. return ERROR_OK;
  226. }
  227. /**
  228. * Implements the Tcl "transport select" command, choosing the
  229. * transport to be used in this debug session from among the
  230. * set supported by the debug adapter being used. Return value
  231. * is scriptable (allowing "if swd then..." etc).
  232. */
  233. static int jim_transport_select(Jim_Interp *interp, int argc, Jim_Obj * const *argv)
  234. {
  235. switch (argc) {
  236. case 1: /* return/display */
  237. if (!session) {
  238. LOG_ERROR("session's transport is not selected.");
  239. return JIM_ERR;
  240. } else {
  241. Jim_SetResultString(interp, session->name, -1);
  242. return JIM_OK;
  243. }
  244. break;
  245. case 2: /* assign */
  246. if (session) {
  247. /* can't change session's transport after-the-fact */
  248. LOG_ERROR("session's transport is already selected.");
  249. return JIM_ERR;
  250. }
  251. /* Is this transport supported by our debug adapter?
  252. * Example, "JTAG-only" means SWD is not supported.
  253. *
  254. * NOTE: requires adapter to have been set up, with
  255. * transports declared via C.
  256. */
  257. if (!allowed_transports) {
  258. LOG_ERROR("Debug adapter doesn't support any transports?");
  259. return JIM_ERR;
  260. }
  261. for (unsigned i = 0; allowed_transports[i]; i++) {
  262. if (strcmp(allowed_transports[i], argv[1]->bytes) == 0)
  263. return transport_select(global_cmd_ctx, argv[1]->bytes);
  264. }
  265. LOG_ERROR("Debug adapter doesn't support '%s' transport", argv[1]->bytes);
  266. return JIM_ERR;
  267. break;
  268. default:
  269. Jim_WrongNumArgs(interp, 1, argv, "[too many parameters]");
  270. return JIM_ERR;
  271. }
  272. }
  273. static const struct command_registration transport_commands[] = {
  274. {
  275. .name = "init",
  276. .handler = handle_transport_init,
  277. /* this would be COMMAND_CONFIG ... except that
  278. * it needs to trigger event handlers that may
  279. * require COMMAND_EXEC ...
  280. */
  281. .mode = COMMAND_ANY,
  282. .help = "Initialize this session's transport",
  283. .usage = ""
  284. },
  285. {
  286. .name = "list",
  287. .handler = handle_transport_list,
  288. .mode = COMMAND_ANY,
  289. .help = "list all built-in transports",
  290. .usage = ""
  291. },
  292. {
  293. .name = "select",
  294. .jim_handler = jim_transport_select,
  295. .mode = COMMAND_ANY,
  296. .help = "Select this session's transport",
  297. .usage = "[transport_name]",
  298. },
  299. COMMAND_REGISTRATION_DONE
  300. };
  301. static const struct command_registration transport_group[] = {
  302. {
  303. .name = "transport",
  304. .mode = COMMAND_ANY,
  305. .help = "Transport command group",
  306. .chain = transport_commands,
  307. .usage = ""
  308. },
  309. COMMAND_REGISTRATION_DONE
  310. };
  311. int transport_register_commands(struct command_context *ctx)
  312. {
  313. return register_commands(ctx, NULL, transport_group);
  314. }