OpenOCD
openocd.c
Go to the documentation of this file.
1 // SPDX-License-Identifier: GPL-2.0-or-later
2 
3 /***************************************************************************
4  * Copyright (C) 2005 by Dominic Rath *
5  * Dominic.Rath@gmx.de *
6  * *
7  * Copyright (C) 2007-2010 Øyvind Harboe *
8  * oyvind.harboe@zylin.com *
9  * *
10  * Copyright (C) 2008 Richard Missenden *
11  * richard.missenden@googlemail.com *
12  ***************************************************************************/
13 
14 #ifdef HAVE_CONFIG_H
15 #include "config.h"
16 #endif
17 
18 #include "openocd.h"
19 #include <jtag/adapter.h>
20 #include <jtag/jtag.h>
21 #include <transport/transport.h>
22 #include <helper/util.h>
23 #include <helper/configuration.h>
24 #include <flash/nor/core.h>
25 #include <flash/nand/core.h>
26 #include <pld/pld.h>
27 #include <target/arm_cti.h>
28 #include <target/arm_adi_v5.h>
29 #include <target/arm_tpiu_swo.h>
30 #include <rtt/rtt.h>
31 
32 #include <server/server.h>
33 #include <server/gdb_server.h>
34 #include <server/rtt_server.h>
35 
36 #ifdef HAVE_STRINGS_H
37 #include <strings.h>
38 #endif
39 
40 #ifdef PKGBLDDATE
41 #define OPENOCD_VERSION \
42  "Open On-Chip Debugger " VERSION RELSTR " (" PKGBLDDATE ")"
43 #else
44 #define OPENOCD_VERSION \
45  "Open On-Chip Debugger " VERSION RELSTR
46 #endif
47 
48 static const char openocd_startup_tcl[] = {
49 #include "startup_tcl.inc"
50 0 /* Terminate with zero */
51 };
52 
53 /* Give scripts and TELNET a way to find out what version this is */
54 static int jim_version_command(Jim_Interp *interp, int argc,
55  Jim_Obj * const *argv)
56 {
57  if (argc > 2)
58  return JIM_ERR;
59  const char *str = "";
60  char *version_str;
61  version_str = OPENOCD_VERSION;
62 
63  if (argc == 2)
64  str = Jim_GetString(argv[1], NULL);
65 
66  if (strcmp("git", str) == 0)
67  version_str = GITVERSION;
68 
69  Jim_SetResult(interp, Jim_NewStringObj(interp, version_str, -1));
70 
71  return JIM_OK;
72 }
73 
75  enum target_event event,
76  void *priv)
77 {
78  switch (event) {
80  target->verbose_halt_msg = false;
81  break;
83  target->verbose_halt_msg = true;
84  break;
86  if (target->verbose_halt_msg) {
87  /* do not display information when debugger caused the halt */
89  }
90  break;
91  default:
92  break;
93  }
94 
95  return ERROR_OK;
96 }
97 
98 static bool init_at_startup = true;
99 
100 COMMAND_HANDLER(handle_noinit_command)
101 {
102  if (CMD_ARGC != 0)
104  init_at_startup = false;
105  return ERROR_OK;
106 }
107 
108 /* OpenOCD can't really handle failure of this command. Patches welcome! :-) */
109 COMMAND_HANDLER(handle_init_command)
110 {
111 
112  if (CMD_ARGC != 0)
114 
115  int retval;
116  static int initialized;
117  if (initialized)
118  return ERROR_OK;
119 
120  initialized = 1;
121 
122  bool save_poll_mask = jtag_poll_mask();
123 
124  retval = command_run_line(CMD_CTX, "target init");
125  if (retval != ERROR_OK)
126  return ERROR_FAIL;
127 
128  retval = adapter_init(CMD_CTX);
129  if (retval != ERROR_OK) {
130  /* we must be able to set up the debug adapter */
131  return retval;
132  }
133 
134  LOG_DEBUG("Debug Adapter init complete");
135 
136  /* "transport init" verifies the expected devices are present;
137  * for JTAG, it checks the list of configured TAPs against
138  * what's discoverable, possibly with help from the platform's
139  * JTAG event handlers. (which require COMMAND_EXEC)
140  */
142 
143  retval = command_run_line(CMD_CTX, "transport init");
144  if (retval != ERROR_OK)
145  return ERROR_FAIL;
146 
147  retval = command_run_line(CMD_CTX, "dap init");
148  if (retval != ERROR_OK)
149  return ERROR_FAIL;
150 
151  LOG_DEBUG("Examining targets...");
152  if (target_examine() != ERROR_OK)
153  LOG_DEBUG("target examination failed");
154 
156 
157  if (command_run_line(CMD_CTX, "flash init") != ERROR_OK)
158  return ERROR_FAIL;
159 
160  if (command_run_line(CMD_CTX, "nand init") != ERROR_OK)
161  return ERROR_FAIL;
162 
163  if (command_run_line(CMD_CTX, "pld init") != ERROR_OK)
164  return ERROR_FAIL;
166 
167  /* in COMMAND_EXEC, after target_examine(), only tpiu or only swo */
168  if (command_run_line(CMD_CTX, "tpiu init") != ERROR_OK)
169  return ERROR_FAIL;
170 
171  jtag_poll_unmask(save_poll_mask);
172 
173  /* initialize telnet subsystem */
175 
177 
178  if (command_run_line(CMD_CTX, "_run_post_init_commands") != ERROR_OK)
179  return ERROR_FAIL;
180 
181  return ERROR_OK;
182 }
183 
184 COMMAND_HANDLER(handle_add_script_search_dir_command)
185 {
186  if (CMD_ARGC != 1)
188 
190 
191  return ERROR_OK;
192 }
193 
194 static const struct command_registration openocd_command_handlers[] = {
195  {
196  .name = "version",
197  .jim_handler = jim_version_command,
198  .mode = COMMAND_ANY,
199  .help = "show program version",
200  },
201  {
202  .name = "noinit",
203  .handler = &handle_noinit_command,
204  .mode = COMMAND_CONFIG,
205  .help = "Prevent 'init' from being called at startup.",
206  .usage = ""
207  },
208  {
209  .name = "init",
210  .handler = &handle_init_command,
211  .mode = COMMAND_ANY,
212  .help = "Initializes configured targets and servers. "
213  "Changes command mode from CONFIG to EXEC. "
214  "Unless 'noinit' is called, this command is "
215  "called automatically at the end of startup.",
216  .usage = ""
217  },
218  {
219  .name = "add_script_search_dir",
220  .handler = &handle_add_script_search_dir_command,
221  .mode = COMMAND_ANY,
222  .help = "dir to search for config files and scripts",
223  .usage = "<directory>"
224  },
226 };
227 
228 static int openocd_register_commands(struct command_context *cmd_ctx)
229 {
231 }
232 
233 /*
234  * TODO: to be removed after v0.12.0
235  * workaround for syntax change of "expr" in jimtcl 0.81
236  * replace "expr" with openocd version that prints the deprecated msg
237  */
239  void *token;
240  Jim_Obj *filename_obj;
241  int len;
243  int in_use;
245  int linenr;
246  int missing;
247 };
248 
249 static int jim_expr_command(Jim_Interp *interp, int argc, Jim_Obj * const *argv)
250 {
251  if (argc == 2)
252  return Jim_EvalExpression(interp, argv[1]);
253 
254  if (argc > 2) {
255  Jim_Obj *obj = Jim_ConcatObj(interp, argc - 1, argv + 1);
256  Jim_IncrRefCount(obj);
257  const char *s = Jim_String(obj);
258  struct jim_scriptobj *script = Jim_GetIntRepPtr(interp->currentScriptObj);
259  if (interp->currentScriptObj == interp->emptyObj ||
260  strcmp(interp->currentScriptObj->typePtr->name, "script") ||
261  script->subst_flags ||
262  script->filename_obj == interp->emptyObj)
263  LOG_WARNING("DEPRECATED! use 'expr { %s }' not 'expr %s'", s, s);
264  else
265  LOG_WARNING("DEPRECATED! (%s:%d) use 'expr { %s }' not 'expr %s'",
266  Jim_String(script->filename_obj), script->linenr, s, s);
267  int retcode = Jim_EvalExpression(interp, obj);
268  Jim_DecrRefCount(interp, obj);
269  return retcode;
270  }
271 
272  Jim_WrongNumArgs(interp, 1, argv, "expression ?...?");
273  return JIM_ERR;
274 }
275 
276 static const struct command_registration expr_handler[] = {
277  {
278  .name = "expr",
279  .jim_handler = jim_expr_command,
280  .mode = COMMAND_ANY,
281  .help = "",
282  .usage = "",
283  },
285 };
286 
287 static int workaround_for_jimtcl_expr(struct command_context *cmd_ctx)
288 {
289  return register_commands(cmd_ctx, NULL, expr_handler);
290 }
291 
293 
294 static struct command_context *setup_command_handler(Jim_Interp *interp)
295 {
296  log_init();
297  LOG_DEBUG("log_init: complete");
298 
300 
301  /* register subsystem commands */
302  typedef int (*command_registrant_t)(struct command_context *cmd_ctx_value);
303  static const command_registrant_t command_registrants[] = {
319  NULL
320  };
321  for (unsigned i = 0; command_registrants[i]; i++) {
322  int retval = (*command_registrants[i])(cmd_ctx);
323  if (retval != ERROR_OK) {
324  command_done(cmd_ctx);
325  return NULL;
326  }
327  }
328  LOG_DEBUG("command registration: complete");
329 
331  "Licensed under GNU GPL v2\n");
332 
333  global_cmd_ctx = cmd_ctx;
334 
335  return cmd_ctx;
336 }
337 
342 static int openocd_thread(int argc, char *argv[], struct command_context *cmd_ctx)
343 {
344  int ret;
345 
346  if (parse_cmdline_args(cmd_ctx, argc, argv) != ERROR_OK)
347  return ERROR_FAIL;
348 
349  if (server_preinit() != ERROR_OK)
350  return ERROR_FAIL;
351 
352  ret = parse_config_file(cmd_ctx);
353  if (ret == ERROR_COMMAND_CLOSE_CONNECTION) {
354  server_quit(); /* gdb server may be initialized by -c init */
355  return ERROR_OK;
356  } else if (ret != ERROR_OK) {
357  server_quit(); /* gdb server may be initialized by -c init */
358  return ERROR_FAIL;
359  }
360 
361  ret = server_init(cmd_ctx);
362  if (ret != ERROR_OK)
363  return ERROR_FAIL;
364 
365  if (init_at_startup) {
366  ret = command_run_line(cmd_ctx, "init");
367  if (ret != ERROR_OK) {
368  server_quit();
369  return ERROR_FAIL;
370  }
371  }
372 
373  ret = server_loop(cmd_ctx);
374 
375  int last_signal = server_quit();
376  if (last_signal != ERROR_OK)
377  return last_signal;
378 
379  if (ret != ERROR_OK)
380  return ERROR_FAIL;
381  return ERROR_OK;
382 }
383 
384 /* normally this is the main() function entry, but if OpenOCD is linked
385  * into application, then this fn will not be invoked, but rather that
386  * application will have it's own implementation of main(). */
387 int openocd_main(int argc, char *argv[])
388 {
389  int ret;
390 
391  /* initialize commandline interface */
392  struct command_context *cmd_ctx;
393 
394  cmd_ctx = setup_command_handler(NULL);
395 
396  if (util_init(cmd_ctx) != ERROR_OK)
397  return EXIT_FAILURE;
398 
399  if (rtt_init() != ERROR_OK)
400  return EXIT_FAILURE;
401 
402  LOG_OUTPUT("For bug reports, read\n\t"
403  "http://openocd.org/doc/doxygen/bugs.html"
404  "\n");
405 
408 
410 
411  /* Start the executable meat that can evolve into thread in future. */
412  ret = openocd_thread(argc, argv, cmd_ctx);
413 
417  server_free();
418 
419  unregister_all_commands(cmd_ctx, NULL);
420  help_del_all_commands(cmd_ctx);
421 
422  /* free all DAP and CTI objects */
424  dap_cleanup_all();
425 
426  adapter_quit();
427 
429 
430  /* Shutdown commandline interface */
431  command_exit(cmd_ctx);
432 
433  rtt_exit();
434  free_config();
435 
436  log_exit();
437 
438  if (ret == ERROR_FAIL)
439  return EXIT_FAILURE;
440  else if (ret != ERROR_OK)
441  exit_on_signal(ret);
442 
443  return ret;
444 }
int adapter_quit(void)
Shutdown the debug adapter upon program exit.
Definition: adapter.c:186
int adapter_register_commands(struct command_context *ctx)
Register the commands which deal with arbitrary debug adapter drivers.
Definition: adapter.c:1212
int adapter_init(struct command_context *cmd_ctx)
Do low-level setup like initializing registers, output signals, and clocking.
Definition: adapter.c:123
This defines formats and data structures used to talk to ADIv5 entities.
int dap_cleanup_all(void)
Definition: arm_dap.c:153
int dap_register_commands(struct command_context *cmd_ctx)
Definition: arm_dap.c:536
int cti_register_commands(struct command_context *cmd_ctx)
Definition: arm_cti.c:574
int arm_cti_cleanup_all(void)
Definition: arm_cti.c:210
int arm_tpiu_swo_register_commands(struct command_context *cmd_ctx)
int arm_tpiu_swo_cleanup_all(void)
Definition: arm_tpiu_swo.c:208
int help_del_all_commands(struct command_context *cmd_ctx)
Unregisters the help for all commands.
Definition: command.c:1024
void command_done(struct command_context *cmd_ctx)
Frees the resources associated with a command context.
Definition: command.c:651
void command_exit(struct command_context *context)
Shutdown a command context.
Definition: command.c:1280
struct command_context * command_init(const char *startup_tcl, Jim_Interp *interp)
Creates a new command context using the startup TCL provided and the existing Jim interpreter,...
Definition: command.c:1245
int command_context_mode(struct command_context *cmd_ctx, enum command_mode mode)
Definition: command.c:1290
void command_set_output_handler(struct command_context *context, command_output_handler_t output_handler, void *priv)
Definition: command.c:635
int unregister_all_commands(struct command_context *context, const char *cmd_prefix)
Unregisters all commands from the specified context.
Definition: command.c:416
int command_run_line(struct command_context *context, char *line)
Definition: command.c:554
#define CMD_ARGV
Use this macro to access the arguments for the command being handled, rather than accessing the varia...
Definition: command.h:155
#define ERROR_COMMAND_SYNTAX_ERROR
Definition: command.h:385
#define ERROR_COMMAND_CLOSE_CONNECTION
Definition: command.h:384
#define CMD_ARGC
Use this macro to access the number of arguments for the command being handled, rather than accessing...
Definition: command.h:150
#define CMD_CTX
Use this macro to access the context of the command being handled, rather than accessing the variable...
Definition: command.h:145
#define COMMAND_REGISTRATION_DONE
Use this as the last entry in an array of command_registration records.
Definition: command.h:247
static int register_commands(struct command_context *cmd_ctx, const char *cmd_prefix, const struct command_registration *cmds)
Register one or more commands in the specified context, as children of parent (or top-level commends,...
Definition: command.h:268
@ COMMAND_CONFIG
Definition: command.h:41
@ COMMAND_ANY
Definition: command.h:42
@ COMMAND_EXEC
Definition: command.h:40
int parse_config_file(struct command_context *cmd_ctx)
void add_script_search_dir(const char *dir)
Definition: configuration.c:25
void free_config(void)
Definition: configuration.c:45
int parse_cmdline_args(struct command_context *cmd_ctx, int argc, char *argv[])
Definition: options.c:265
int configuration_output_handler(struct command_context *cmd_ctx, const char *line)
Definition: options.c:50
static struct esp_usb_jtag * priv
Definition: esp_usb_jtag.c:219
void flash_free_all_banks(void)
Deallocates all flash banks.
int gdb_register_commands(struct command_context *cmd_ctx)
Definition: gdb_server.c:4099
int gdb_target_add_all(struct target *target)
Definition: gdb_server.c:3865
void gdb_service_free(void)
Definition: gdb_server.c:4106
void jtag_poll_unmask(bool saved)
Restore saved mask for polling.
Definition: jtag/core.c:177
bool jtag_poll_mask(void)
Mask (disable) polling and return the current mask status that should be feed to jtag_poll_unmask() t...
Definition: jtag/core.c:170
The JTAG interface can be implemented with a software or hardware fifo.
int log_register_commands(struct command_context *cmd_ctx)
Definition: log.c:264
void log_init(void)
Initialize logging module.
Definition: log.c:269
void log_exit(void)
Definition: log.c:289
#define LOG_OUTPUT(expr ...)
Definition: log.h:132
#define LOG_WARNING(expr ...)
Definition: log.h:120
#define ERROR_FAIL
Definition: log.h:161
#define LOG_DEBUG(expr ...)
Definition: log.h:109
#define ERROR_OK
Definition: log.h:155
int nand_register_commands(struct command_context *cmd_ctx)
Upper level NOR flash interfaces.
int flash_register_commands(struct command_context *cmd_ctx)
Registers the 'flash' subsystem commands.
static const struct command_registration openocd_command_handlers[]
Definition: openocd.c:194
struct command_context * global_cmd_ctx
Definition: openocd.c:292
#define OPENOCD_VERSION
Definition: openocd.c:44
COMMAND_HANDLER(handle_noinit_command)
Definition: openocd.c:100
static int openocd_thread(int argc, char *argv[], struct command_context *cmd_ctx)
OpenOCD runtime meat that can become single-thread in future.
Definition: openocd.c:342
static int log_target_callback_event_handler(struct target *target, enum target_event event, void *priv)
Definition: openocd.c:74
static bool init_at_startup
Definition: openocd.c:98
static int workaround_for_jimtcl_expr(struct command_context *cmd_ctx)
Definition: openocd.c:287
static struct command_context * setup_command_handler(Jim_Interp *interp)
Definition: openocd.c:294
static int jim_expr_command(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
Definition: openocd.c:249
static int jim_version_command(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
Definition: openocd.c:54
static int openocd_register_commands(struct command_context *cmd_ctx)
Definition: openocd.c:228
static const char openocd_startup_tcl[]
Definition: openocd.c:48
static const struct command_registration expr_handler[]
Definition: openocd.c:276
int openocd_main(int argc, char *argv[])
Different applications can define this entry point to override the default openocd main function.
Definition: openocd.c:387
int pld_register_commands(struct command_context *cmd_ctx)
Definition: pld.c:225
int rtt_init(void)
Initialize Real-Time Transfer (RTT).
Definition: rtt/rtt.c:48
int rtt_exit(void)
Shutdown Real-Time Transfer (RTT).
Definition: rtt/rtt.c:65
int rtt_server_register_commands(struct command_context *ctx)
Definition: rtt_server.c:190
void exit_on_signal(int sig)
Definition: server.c:721
int server_preinit(void)
Definition: server.c:660
static int last_signal
Definition: server.c:48
int server_host_os_close(void)
Definition: server.c:652
void server_free(void)
Definition: server.c:712
int server_host_os_entry(void)
Definition: server.c:632
int server_loop(struct command_context *command_context)
Definition: server.c:421
int server_quit(void)
Definition: server.c:697
int server_register_commands(struct command_context *cmd_ctx)
Definition: server.c:828
int server_init(struct command_context *cmd_ctx)
Definition: server.c:680
Jim_Interp * interp
Definition: command.h:53
const char * name
Definition: command.h:229
void * token
Definition: openocd.c:239
int firstline
Definition: openocd.c:244
int subst_flags
Definition: openocd.c:242
Jim_Obj * filename_obj
Definition: openocd.c:240
Definition: target.h:120
bool verbose_halt_msg
Definition: target.h:173
struct target * all_targets
Definition: target.c:154
int target_register_event_callback(int(*callback)(struct target *target, enum target_event event, void *priv), void *priv)
Definition: target.c:1661
int target_arch_state(struct target *target)
Definition: target.c:2325
int target_register_commands(struct command_context *cmd_ctx)
Definition: target.c:6757
int target_examine(void)
Definition: target.c:784
target_event
Definition: target.h:241
@ TARGET_EVENT_HALTED
Definition: target.h:253
@ TARGET_EVENT_GDB_START
Definition: target.h:260
@ TARGET_EVENT_GDB_END
Definition: target.h:261
int transport_register_commands(struct command_context *ctx)
Definition: transport.c:355
#define NULL
Definition: usb.h:16
int util_init(struct command_context *cmd_ctx)
Definition: util.c:45