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)) && !defined(__clang__)
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 int 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;
201  /* Command handlers can use it for any handler specific data */
203  /* Used only for target of target-prefixed cmd */
204  enum command_mode mode;
205 };
206 
207 /*
208  * Return the struct command pointer kept in private data
209  * Used to enforce check on data type
210  */
211 static inline struct command *jim_to_command(Jim_Interp *interp)
212 {
213  return Jim_CmdPrivData(interp);
214 }
215 
216 /*
217  * Commands should be registered by filling in one or more of these
218  * structures and passing them to [un]register_commands().
219  *
220  * A conventional format should be used for help strings, to provide both
221  * usage and basic information:
222  * @code
223  * "@<options@> ... - some explanation text"
224  * @endcode
225  *
226  * @param name The name of the command to register, which must not have
227  * been registered previously in the intended context.
228  * @param handler The callback function that will be called. If NULL,
229  * then the command serves as a placeholder for its children or a script.
230  * @param mode The command mode(s) in which this command may be run.
231  * @param help The help text that will be displayed to the user.
232  */
234  const char *name;
235  command_handler_t handler;
236  enum command_mode mode;
237  const char *help;
239  const char *usage;
240 
248 };
249 
251 #define COMMAND_REGISTRATION_DONE { .name = NULL, .chain = NULL }
252 
253 int __register_commands(struct command_context *cmd_ctx, const char *cmd_prefix,
254  const struct command_registration *cmds, void *data,
255  struct target *override_target);
256 
272 static inline int register_commands(struct command_context *cmd_ctx, const char *cmd_prefix,
273  const struct command_registration *cmds)
274 {
275  return __register_commands(cmd_ctx, cmd_prefix, cmds, NULL, NULL);
276 }
277 
291 static inline int register_commands_override_target(struct command_context *cmd_ctx,
292  const char *cmd_prefix, const struct command_registration *cmds,
293  struct target *target)
294 {
295  return __register_commands(cmd_ctx, cmd_prefix, cmds, NULL, target);
296 }
297 
313 static inline int register_commands_with_data(struct command_context *cmd_ctx,
314  const char *cmd_prefix, const struct command_registration *cmds,
315  void *data)
316 {
317  return __register_commands(cmd_ctx, cmd_prefix, cmds, data, NULL);
318 }
319 
326 int unregister_all_commands(struct command_context *cmd_ctx,
327  const char *cmd_prefix);
328 
335 int help_del_all_commands(struct command_context *cmd_ctx);
336 
337 void command_set_output_handler(struct command_context *context,
338  command_output_handler_t output_handler, void *priv);
339 
340 
341 int command_context_mode(struct command_context *context, enum command_mode mode);
342 
343 /* Return the current command context associated with the Jim interpreter or
344  * alternatively the global default command interpreter
345  */
346 struct command_context *current_command_context(Jim_Interp *interp);
352 struct command_context *command_init(const char *startup_tcl, Jim_Interp *interp);
360 void command_exit(struct command_context *context);
369 struct command_context *copy_command_context(struct command_context *cmd_ctx);
375 void command_done(struct command_context *context);
376 
377 /*
378  * command_print() and command_print_sameline() are used to produce the TCL
379  * output of OpenOCD commands. command_print() automatically adds a '\n' at
380  * the end or the format string. Use command_print_sameline() to avoid the
381  * trailing '\n', e.g. to concatenate the command output in the same line.
382  * The very last '\n' of the command is stripped away (see run_command()).
383  * For commands that strictly require a '\n' as last output character, add
384  * it explicitly with either an empty command_print() or with a '\n' in the
385  * last command_print() and add a comment to document it.
386  */
387 void command_print(struct command_invocation *cmd, const char *format, ...)
388 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
389 void command_print_sameline(struct command_invocation *cmd, const char *format, ...)
390 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
391 
392 int command_run_line(struct command_context *context, char *line);
393 int command_run_linef(struct command_context *context, const char *format, ...)
394 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
395 void command_output_text(struct command_context *context, const char *data);
396 
397 void process_jim_events(struct command_context *cmd_ctx);
398 
399 #define ERROR_COMMAND_CLOSE_CONNECTION (-600)
400 #define ERROR_COMMAND_SYNTAX_ERROR (-601)
401 #define ERROR_COMMAND_NOTFOUND (-602)
402 #define ERROR_COMMAND_ARGUMENT_INVALID (-603)
403 #define ERROR_COMMAND_ARGUMENT_OVERFLOW (-604)
404 #define ERROR_COMMAND_ARGUMENT_UNDERFLOW (-605)
405 
406 int parse_ulong(const char *str, unsigned long *ul);
407 int parse_ullong(const char *str, unsigned long long *ul);
408 
409 int parse_long(const char *str, long *ul);
410 int parse_llong(const char *str, long long *ul);
411 
412 #define DECLARE_PARSE_WRAPPER(name, type) \
413  int parse ## name(const char *str, type * ul)
414 
415 DECLARE_PARSE_WRAPPER(_uint, unsigned int);
416 DECLARE_PARSE_WRAPPER(_u64, uint64_t);
417 DECLARE_PARSE_WRAPPER(_u32, uint32_t);
418 DECLARE_PARSE_WRAPPER(_u16, uint16_t);
419 DECLARE_PARSE_WRAPPER(_u8, uint8_t);
420 
422 DECLARE_PARSE_WRAPPER(_s64, int64_t);
423 DECLARE_PARSE_WRAPPER(_s32, int32_t);
424 DECLARE_PARSE_WRAPPER(_s16, int16_t);
426 
428 
440 #define COMMAND_PARSE_NUMBER(type, in, out) \
441  do { \
442  int retval_macro_tmp = parse_ ## type(in, &(out)); \
443  if (retval_macro_tmp != ERROR_OK) { \
444  command_print(CMD, stringify(out) \
445  " option value ('%s') is not valid", in); \
446  return retval_macro_tmp; \
447  } \
448  } while (0)
449 
450 #define COMMAND_PARSE_ADDRESS(in, out) \
451  COMMAND_PARSE_NUMBER(target_addr, in, out)
452 
465 #define COMMAND_PARSE_ADDITIONAL_NUMBER(type, argn, out, name_str) \
466  do { \
467  if (argn+1 >= CMD_ARGC || CMD_ARGV[argn+1][0] == '-') { \
468  command_print(CMD, "no " name_str " given"); \
469  return ERROR_FAIL; \
470  } \
471  ++argn; \
472  COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
473  } while (0)
474 
487 #define COMMAND_PARSE_OPTIONAL_NUMBER(type, argn, out) \
488  do { \
489  if (argn+1 < CMD_ARGC && CMD_ARGV[argn+1][0] != '-') { \
490  ++argn; \
491  COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
492  } \
493  } while (0)
494 
501 #define COMMAND_PARSE_BOOL(in, out, on, off) \
502  do { \
503  bool value; \
504  int retval_macro_tmp = command_parse_bool_arg(in, &value); \
505  if (retval_macro_tmp != ERROR_OK) { \
506  command_print(CMD, stringify(out) \
507  " option value ('%s') is not valid", in); \
508  command_print(CMD, " choices are '%s' or '%s'", \
509  on, off); \
510  return retval_macro_tmp; \
511  } \
512  out = value; \
513  } while (0)
514 
515 int command_parse_bool_arg(const char *in, bool *out);
516 COMMAND_HELPER(handle_command_parse_bool, bool *out, const char *label);
517 
525 COMMAND_HELPER(command_parse_str_to_buf, const char *str, void *buf, unsigned int buf_len);
526 
528 #define COMMAND_PARSE_ON_OFF(in, out) \
529  COMMAND_PARSE_BOOL(in, out, "on", "off")
531 #define COMMAND_PARSE_ENABLE(in, out) \
532  COMMAND_PARSE_BOOL(in, out, "enable", "disable")
533 
534 #endif /* OPENOCD_HELPER_COMMAND_H */
const char * label
Definition: arm_cti.c:162
enum arm_mode mode
Definition: armv4_5.c:281
struct command_context * current_command_context(Jim_Interp *interp)
Definition: command.c:90
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:346
int command_parse_bool_arg(const char *in, bool *out)
Definition: command.c:1289
int help_del_all_commands(struct command_context *cmd_ctx)
Unregisters the help for all commands.
Definition: command.c:929
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:1195
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:313
#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:291
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:1204
void command_done(struct command_context *context)
Frees the resources associated with a command context.
Definition: command.c:573
int parse_long(const char *str, long *ul)
void command_exit(struct command_context *context)
Shutdown a command context.
Definition: command.c:1185
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:318
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:1150
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:218
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:557
static struct command * jim_to_command(Jim_Interp *interp)
Definition: command.h:211
void void int command_run_line(struct command_context *context, char *line)
Definition: command.c:476
#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:272
#define DECLARE_PARSE_WRAPPER(name, type)
Definition: command.h:412
struct command_context * copy_command_context(struct command_context *cmd_ctx)
Creates a copy of an existing command context.
Definition: command.c:564
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:1016
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
unsigned int argc
Definition: command.h:80
Jim_Obj * output
Definition: command.h:83
struct command_context * ctx
Definition: command.h:77
struct command * current
Definition: command.h:78
Jim_Obj *const * jimtcl_argv
Definition: command.h:82
const char ** argv
Definition: command.h:81
const char * name
Definition: command.h:234
command_handler_t handler
Definition: command.h:235
enum command_mode mode
Definition: command.h:236
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:247
const char * usage
a string listing the options and arguments, required or optional
Definition: command.h:239
const char * help
Definition: command.h:237
void * jim_handler_data
Definition: command.h:200
command_handler_t handler
Definition: command.h:199
struct target * jim_override_target
Definition: command.h:202
enum command_mode mode
Definition: command.h:204
char * name
Definition: command.h:198
Definition: list.h:41
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