OpenOCD
command.h
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,2008 Øyvind Harboe *
8  * oyvind.harboe@zylin.com *
9  ***************************************************************************/
10 
11 #ifndef OPENOCD_HELPER_COMMAND_H
12 #define OPENOCD_HELPER_COMMAND_H
13 
14 #include <stdint.h>
15 #include <stdbool.h>
16 
17 #include <helper/jim-nvp.h>
18 #include <helper/list.h>
19 #include <helper/types.h>
20 
21 /* To achieve C99 printf compatibility in MinGW, gnu_printf should be
22  * used for __attribute__((format( ... ))), with GCC v4.4 or later
23  */
24 #if (defined(IS_MINGW) && (((__GNUC__ << 16) + __GNUC_MINOR__) >= 0x00040004))
25 #define PRINTF_ATTRIBUTE_FORMAT gnu_printf
26 #else
27 #define PRINTF_ATTRIBUTE_FORMAT printf
28 #endif
29 
43  COMMAND_UNKNOWN = -1, /* error condition */
44 };
45 
46 struct command_context;
47 
49 typedef int (*command_output_handler_t)(struct command_context *context,
50  const char *line);
51 
53  Jim_Interp *interp;
54  enum command_mode mode;
56  /* The target set by 'targets xx' command or the latest created */
58  /* If set overrides current_target
59  * It happens during processing of
60  * 1) a target prefixed command
61  * 2) an event handler
62  * Pay attention to reentrancy when setting override.
63  */
67 };
68 
69 struct command;
70 
78  struct command *current;
79  const char *name;
80  unsigned argc;
81  const char **argv;
82  Jim_Obj * const *jimtcl_argv;
83  Jim_Obj *output;
84 };
85 
89 bool jimcmd_is_oocd_command(Jim_Cmd *cmd);
90 
95 void *jimcmd_privdata(Jim_Cmd *cmd);
96 
102 #define __COMMAND_HANDLER(name, extra ...) \
103  int name(struct command_invocation *cmd, ## extra)
104 
118 #define CALL_COMMAND_HANDLER(name, extra ...) \
119  name(cmd, ## extra)
120 
127 #define COMMAND_HANDLER(name) \
128  static __COMMAND_HANDLER(name)
129 
135 #define COMMAND_HELPER(name, extra ...) __COMMAND_HANDLER(name, extra)
136 
141 #define CMD (cmd)
146 #define CMD_CTX (cmd->ctx)
151 #define CMD_ARGC (cmd->argc)
156 #define CMD_ARGV (cmd->argv)
161 #define CMD_JIMTCL_ARGV (cmd->jimtcl_argv)
166 #define CMD_NAME (cmd->name)
171 #define CMD_CURRENT (cmd->current)
176 #define CMD_DATA (CMD_CURRENT->jim_handler_data)
177 
195 typedef __COMMAND_HANDLER((*command_handler_t));
196 
197 struct command {
198  char *name;
199  command_handler_t handler;
200  Jim_CmdProc *jim_handler;
202  /* Command handlers can use it for any handler specific data */
204  /* Used only for target of target-prefixed cmd */
205  enum command_mode mode;
206 };
207 
208 /*
209  * Return the struct command pointer kept in private data
210  * Used to enforce check on data type
211  */
212 static inline struct command *jim_to_command(Jim_Interp *interp)
213 {
214  return Jim_CmdPrivData(interp);
215 }
216 
217 /*
218  * Commands should be registered by filling in one or more of these
219  * structures and passing them to [un]register_commands().
220  *
221  * A conventional format should be used for help strings, to provide both
222  * usage and basic information:
223  * @code
224  * "@<options@> ... - some explanation text"
225  * @endcode
226  *
227  * @param name The name of the command to register, which must not have
228  * been registered previously in the intended context.
229  * @param handler The callback function that will be called. If NULL,
230  * then the command serves as a placeholder for its children or a script.
231  * @param mode The command mode(s) in which this command may be run.
232  * @param help The help text that will be displayed to the user.
233  */
235  const char *name;
236  command_handler_t handler;
237  Jim_CmdProc *jim_handler;
238  enum command_mode mode;
239  const char *help;
241  const char *usage;
242 
250 };
251 
253 #define COMMAND_REGISTRATION_DONE { .name = NULL, .chain = NULL }
254 
255 int __register_commands(struct command_context *cmd_ctx, const char *cmd_prefix,
256  const struct command_registration *cmds, void *data,
257  struct target *override_target);
258 
274 static inline int register_commands(struct command_context *cmd_ctx, const char *cmd_prefix,
275  const struct command_registration *cmds)
276 {
277  return __register_commands(cmd_ctx, cmd_prefix, cmds, NULL, NULL);
278 }
279 
293 static inline int register_commands_override_target(struct command_context *cmd_ctx,
294  const char *cmd_prefix, const struct command_registration *cmds,
295  struct target *target)
296 {
297  return __register_commands(cmd_ctx, cmd_prefix, cmds, NULL, target);
298 }
299 
315 static inline int register_commands_with_data(struct command_context *cmd_ctx,
316  const char *cmd_prefix, const struct command_registration *cmds,
317  void *data)
318 {
319  return __register_commands(cmd_ctx, cmd_prefix, cmds, data, NULL);
320 }
321 
328 int unregister_all_commands(struct command_context *cmd_ctx,
329  const char *cmd_prefix);
330 
337 int help_del_all_commands(struct command_context *cmd_ctx);
338 
339 void command_set_output_handler(struct command_context *context,
340  command_output_handler_t output_handler, void *priv);
341 
342 
343 int command_context_mode(struct command_context *context, enum command_mode mode);
344 
345 /* Return the current command context associated with the Jim interpreter or
346  * alternatively the global default command interpreter
347  */
348 struct command_context *current_command_context(Jim_Interp *interp);
354 struct command_context *command_init(const char *startup_tcl, Jim_Interp *interp);
362 void command_exit(struct command_context *context);
371 struct command_context *copy_command_context(struct command_context *cmd_ctx);
377 void command_done(struct command_context *context);
378 
379 /*
380  * command_print() and command_print_sameline() are used to produce the TCL
381  * output of OpenOCD commands. command_print() automatically adds a '\n' at
382  * the end or the format string. Use command_print_sameline() to avoid the
383  * trailing '\n', e.g. to concatenate the command output in the same line.
384  * The very last '\n' of the command is stripped away (see run_command()).
385  * For commands that strictly require a '\n' as last output character, add
386  * it explicitly with either an empty command_print() or with a '\n' in the
387  * last command_print() and add a comment to document it.
388  */
389 void command_print(struct command_invocation *cmd, const char *format, ...)
390 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
391 void command_print_sameline(struct command_invocation *cmd, const char *format, ...)
392 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
393 
394 int command_run_line(struct command_context *context, char *line);
395 int command_run_linef(struct command_context *context, const char *format, ...)
396 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
397 void command_output_text(struct command_context *context, const char *data);
398 
399 void process_jim_events(struct command_context *cmd_ctx);
400 
401 #define ERROR_COMMAND_CLOSE_CONNECTION (-600)
402 #define ERROR_COMMAND_SYNTAX_ERROR (-601)
403 #define ERROR_COMMAND_NOTFOUND (-602)
404 #define ERROR_COMMAND_ARGUMENT_INVALID (-603)
405 #define ERROR_COMMAND_ARGUMENT_OVERFLOW (-604)
406 #define ERROR_COMMAND_ARGUMENT_UNDERFLOW (-605)
407 
408 int parse_ulong(const char *str, unsigned long *ul);
409 int parse_ullong(const char *str, unsigned long long *ul);
410 
411 int parse_long(const char *str, long *ul);
412 int parse_llong(const char *str, long long *ul);
413 
414 #define DECLARE_PARSE_WRAPPER(name, type) \
415  int parse ## name(const char *str, type * ul)
416 
417 DECLARE_PARSE_WRAPPER(_uint, unsigned);
418 DECLARE_PARSE_WRAPPER(_u64, uint64_t);
419 DECLARE_PARSE_WRAPPER(_u32, uint32_t);
420 DECLARE_PARSE_WRAPPER(_u16, uint16_t);
421 DECLARE_PARSE_WRAPPER(_u8, uint8_t);
422 
424 DECLARE_PARSE_WRAPPER(_s64, int64_t);
425 DECLARE_PARSE_WRAPPER(_s32, int32_t);
426 DECLARE_PARSE_WRAPPER(_s16, int16_t);
428 
430 
442 #define COMMAND_PARSE_NUMBER(type, in, out) \
443  do { \
444  int retval_macro_tmp = parse_ ## type(in, &(out)); \
445  if (retval_macro_tmp != ERROR_OK) { \
446  command_print(CMD, stringify(out) \
447  " option value ('%s') is not valid", in); \
448  return retval_macro_tmp; \
449  } \
450  } while (0)
451 
452 #define COMMAND_PARSE_ADDRESS(in, out) \
453  COMMAND_PARSE_NUMBER(target_addr, in, out)
454 
467 #define COMMAND_PARSE_ADDITIONAL_NUMBER(type, argn, out, name_str) \
468  do { \
469  if (argn+1 >= CMD_ARGC || CMD_ARGV[argn+1][0] == '-') { \
470  command_print(CMD, "no " name_str " given"); \
471  return ERROR_FAIL; \
472  } \
473  ++argn; \
474  COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
475  } while (0)
476 
489 #define COMMAND_PARSE_OPTIONAL_NUMBER(type, argn, out) \
490  do { \
491  if (argn+1 < CMD_ARGC && CMD_ARGV[argn+1][0] != '-') { \
492  ++argn; \
493  COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
494  } \
495  } while (0)
496 
503 #define COMMAND_PARSE_BOOL(in, out, on, off) \
504  do { \
505  bool value; \
506  int retval_macro_tmp = command_parse_bool_arg(in, &value); \
507  if (retval_macro_tmp != ERROR_OK) { \
508  command_print(CMD, stringify(out) \
509  " option value ('%s') is not valid", in); \
510  command_print(CMD, " choices are '%s' or '%s'", \
511  on, off); \
512  return retval_macro_tmp; \
513  } \
514  out = value; \
515  } while (0)
516 
517 int command_parse_bool_arg(const char *in, bool *out);
518 COMMAND_HELPER(handle_command_parse_bool, bool *out, const char *label);
519 
521 #define COMMAND_PARSE_ON_OFF(in, out) \
522  COMMAND_PARSE_BOOL(in, out, "on", "off")
524 #define COMMAND_PARSE_ENABLE(in, out) \
525  COMMAND_PARSE_BOOL(in, out, "enable", "disable")
526 
527 #endif /* OPENOCD_HELPER_COMMAND_H */
const char * label
Definition: arm_cti.c:164
enum arm_mode mode
Definition: armv4_5.c:277
struct command_context * current_command_context(Jim_Interp *interp)
Definition: command.c:157
void command_print(struct command_invocation *cmd, const char *format,...) __attribute__((format(PRINTF_ATTRIBUTE_FORMAT
int void command_output_text(struct command_context *context, const char *data)
Definition: command.c:414
int command_parse_bool_arg(const char *in, bool *out)
Definition: command.c:1348
int help_del_all_commands(struct command_context *cmd_ctx)
Unregisters the help for all commands.
Definition: command.c:988
bool jimcmd_is_oocd_command(Jim_Cmd *cmd)
Return true if the command cmd is registered by OpenOCD.
Definition: command.c:51
#define __COMMAND_HANDLER(name, extra ...)
Command handlers may be defined with more parameters than the base set provided by command....
Definition: command.h:102
int command_context_mode(struct command_context *context, enum command_mode mode)
Definition: command.c:1254
int parse_ulong(const char *str, unsigned long *ul)
static int register_commands_with_data(struct command_context *cmd_ctx, const char *cmd_prefix, const struct command_registration *cmds, void *data)
Register one or more commands, as register_commands(), plus specify a pointer to command private data...
Definition: command.h:315
#define PRINTF_ATTRIBUTE_FORMAT
Definition: command.h:27
int parse_llong(const char *str, long long *ul)
void * jimcmd_privdata(Jim_Cmd *cmd)
Return the pointer to the command's private data specified during the registration of command cmd .
Definition: command.c:56
static int register_commands_override_target(struct command_context *cmd_ctx, const char *cmd_prefix, const struct command_registration *cmds, struct target *target)
Register one or more commands, as register_commands(), plus specify that command should override the ...
Definition: command.h:293
int command_run_linef(struct command_context *context, const char *format,...) __attribute__((format(PRINTF_ATTRIBUTE_FORMAT
void process_jim_events(struct command_context *cmd_ctx)
Definition: command.c:1263
void command_done(struct command_context *context)
Frees the resources associated with a command context.
Definition: command.c:644
int parse_long(const char *str, long *ul)
void command_exit(struct command_context *context)
Shutdown a command context.
Definition: command.c:1244
void void command_print_sameline(struct command_invocation *cmd, const char *format,...) __attribute__((format(PRINTF_ATTRIBUTE_FORMAT
int unregister_all_commands(struct command_context *cmd_ctx, const char *cmd_prefix)
Unregisters all commands from the specified context.
Definition: command.c:386
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:1209
int __register_commands(struct command_context *cmd_ctx, const char *cmd_prefix, const struct command_registration *cmds, void *data, struct target *override_target)
Definition: command.c:286
int(* command_output_handler_t)(struct command_context *context, const char *line)
The type signature for command context's output handler.
Definition: command.h:49
void command_set_output_handler(struct command_context *context, command_output_handler_t output_handler, void *priv)
Definition: command.c:628
static struct command * jim_to_command(Jim_Interp *interp)
Definition: command.h:212
void void int command_run_line(struct command_context *context, char *line)
Definition: command.c:547
#define COMMAND_HELPER(name, extra ...)
Similar to COMMAND_HANDLER, except some parameters are expected.
Definition: command.h:135
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:274
#define DECLARE_PARSE_WRAPPER(name, type)
Definition: command.h:414
struct command_context * copy_command_context(struct command_context *cmd_ctx)
Creates a copy of an existing command context.
Definition: command.c:635
command_mode
OpenOCD command mode is COMMAND_CONFIG at start, then switches to COMMAND_EXEC during the execution o...
Definition: command.h:39
@ COMMAND_CONFIG
Definition: command.h:41
@ COMMAND_ANY
Definition: command.h:42
@ COMMAND_UNKNOWN
Definition: command.h:43
@ COMMAND_EXEC
Definition: command.h:40
int parse_ullong(const char *str, unsigned long long *ul)
static struct esp_usb_jtag * priv
Definition: esp_usb_jtag.c:219
struct qn908x_flash_bank __attribute__
Definition: armv8.c:932
enum command_mode mode
Definition: command.h:54
Jim_Interp * interp
Definition: command.h:53
struct list_head * help_list
Definition: command.h:66
void * output_handler_priv
Definition: command.h:65
struct target * current_target_override
Definition: command.h:57
struct target * current_target
Definition: command.h:55
command_output_handler_t output_handler
Definition: command.h:64
When run_command is called, a new instance will be created on the stack, filled with the proper value...
Definition: command.h:76
const char * name
Definition: command.h:79
Jim_Obj * output
Definition: command.h:83
struct command_context * ctx
Definition: command.h:77
struct command * current
Definition: command.h:78
unsigned argc
Definition: command.h:80
Jim_Obj *const * jimtcl_argv
Definition: command.h:82
const char ** argv
Definition: command.h:81
const char * name
Definition: command.h:235
command_handler_t handler
Definition: command.h:236
enum command_mode mode
Definition: command.h:238
Jim_CmdProc * jim_handler
Definition: command.h:237
const struct command_registration * chain
If non-NULL, the commands in chain will be registered in the same context and scope of this registrat...
Definition: command.h:249
const char * usage
a string listing the options and arguments, required or optional
Definition: command.h:241
const char * help
Definition: command.h:239
void * jim_handler_data
Definition: command.h:201
Jim_CmdProc * jim_handler
Definition: command.h:200
command_handler_t handler
Definition: command.h:199
struct target * jim_override_target
Definition: command.h:203
enum command_mode mode
Definition: command.h:205
char * name
Definition: command.h:198
Definition: list.h:40
Definition: target.h:116
uint64_t target_addr_t
Definition: types.h:335
#define NULL
Definition: usb.h:16
uint8_t cmd
Definition: vdebug.c:1