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 *output;
83 };
84 
88 bool jimcmd_is_oocd_command(Jim_Cmd *cmd);
89 
94 void *jimcmd_privdata(Jim_Cmd *cmd);
95 
101 #define __COMMAND_HANDLER(name, extra ...) \
102  int name(struct command_invocation *cmd, ## extra)
103 
117 #define CALL_COMMAND_HANDLER(name, extra ...) \
118  name(cmd, ## extra)
119 
126 #define COMMAND_HANDLER(name) \
127  static __COMMAND_HANDLER(name)
128 
134 #define COMMAND_HELPER(name, extra ...) __COMMAND_HANDLER(name, extra)
135 
140 #define CMD (cmd)
145 #define CMD_CTX (cmd->ctx)
150 #define CMD_ARGC (cmd->argc)
155 #define CMD_ARGV (cmd->argv)
160 #define CMD_NAME (cmd->name)
165 #define CMD_CURRENT (cmd->current)
170 #define CMD_DATA (CMD_CURRENT->jim_handler_data)
171 
189 typedef __COMMAND_HANDLER((*command_handler_t));
190 
191 struct command {
192  char *name;
193  command_handler_t handler;
194  Jim_CmdProc *jim_handler;
196  /* Command handlers can use it for any handler specific data */
198  /* Used only for target of target-prefixed cmd */
199  enum command_mode mode;
200 };
201 
202 /*
203  * Return the struct command pointer kept in private data
204  * Used to enforce check on data type
205  */
206 static inline struct command *jim_to_command(Jim_Interp *interp)
207 {
208  return Jim_CmdPrivData(interp);
209 }
210 
211 /*
212  * Commands should be registered by filling in one or more of these
213  * structures and passing them to [un]register_commands().
214  *
215  * A conventional format should be used for help strings, to provide both
216  * usage and basic information:
217  * @code
218  * "@<options@> ... - some explanation text"
219  * @endcode
220  *
221  * @param name The name of the command to register, which must not have
222  * been registered previously in the intended context.
223  * @param handler The callback function that will be called. If NULL,
224  * then the command serves as a placeholder for its children or a script.
225  * @param mode The command mode(s) in which this command may be run.
226  * @param help The help text that will be displayed to the user.
227  */
229  const char *name;
230  command_handler_t handler;
231  Jim_CmdProc *jim_handler;
232  enum command_mode mode;
233  const char *help;
235  const char *usage;
236 
244 };
245 
247 #define COMMAND_REGISTRATION_DONE { .name = NULL, .chain = NULL }
248 
249 int __register_commands(struct command_context *cmd_ctx, const char *cmd_prefix,
250  const struct command_registration *cmds, void *data,
251  struct target *override_target);
252 
268 static inline int register_commands(struct command_context *cmd_ctx, const char *cmd_prefix,
269  const struct command_registration *cmds)
270 {
271  return __register_commands(cmd_ctx, cmd_prefix, cmds, NULL, NULL);
272 }
273 
287 static inline int register_commands_override_target(struct command_context *cmd_ctx,
288  const char *cmd_prefix, const struct command_registration *cmds,
289  struct target *target)
290 {
291  return __register_commands(cmd_ctx, cmd_prefix, cmds, NULL, target);
292 }
293 
309 static inline int register_commands_with_data(struct command_context *cmd_ctx,
310  const char *cmd_prefix, const struct command_registration *cmds,
311  void *data)
312 {
313  return __register_commands(cmd_ctx, cmd_prefix, cmds, data, NULL);
314 }
315 
322 int unregister_all_commands(struct command_context *cmd_ctx,
323  const char *cmd_prefix);
324 
331 int help_del_all_commands(struct command_context *cmd_ctx);
332 
333 void command_set_output_handler(struct command_context *context,
334  command_output_handler_t output_handler, void *priv);
335 
336 
337 int command_context_mode(struct command_context *context, enum command_mode mode);
338 
339 /* Return the current command context associated with the Jim interpreter or
340  * alternatively the global default command interpreter
341  */
342 struct command_context *current_command_context(Jim_Interp *interp);
348 struct command_context *command_init(const char *startup_tcl, Jim_Interp *interp);
356 void command_exit(struct command_context *context);
365 struct command_context *copy_command_context(struct command_context *cmd_ctx);
371 void command_done(struct command_context *context);
372 
373 void command_print(struct command_invocation *cmd, const char *format, ...)
374 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
375 void command_print_sameline(struct command_invocation *cmd, const char *format, ...)
376 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
377 int command_run_line(struct command_context *context, char *line);
378 int command_run_linef(struct command_context *context, const char *format, ...)
379 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
380 void command_output_text(struct command_context *context, const char *data);
381 
382 void process_jim_events(struct command_context *cmd_ctx);
383 
384 #define ERROR_COMMAND_CLOSE_CONNECTION (-600)
385 #define ERROR_COMMAND_SYNTAX_ERROR (-601)
386 #define ERROR_COMMAND_NOTFOUND (-602)
387 #define ERROR_COMMAND_ARGUMENT_INVALID (-603)
388 #define ERROR_COMMAND_ARGUMENT_OVERFLOW (-604)
389 #define ERROR_COMMAND_ARGUMENT_UNDERFLOW (-605)
390 
391 int parse_ulong(const char *str, unsigned long *ul);
392 int parse_ullong(const char *str, unsigned long long *ul);
393 
394 int parse_long(const char *str, long *ul);
395 int parse_llong(const char *str, long long *ul);
396 
397 #define DECLARE_PARSE_WRAPPER(name, type) \
398  int parse ## name(const char *str, type * ul)
399 
400 DECLARE_PARSE_WRAPPER(_uint, unsigned);
401 DECLARE_PARSE_WRAPPER(_u64, uint64_t);
402 DECLARE_PARSE_WRAPPER(_u32, uint32_t);
403 DECLARE_PARSE_WRAPPER(_u16, uint16_t);
404 DECLARE_PARSE_WRAPPER(_u8, uint8_t);
405 
407 DECLARE_PARSE_WRAPPER(_s64, int64_t);
408 DECLARE_PARSE_WRAPPER(_s32, int32_t);
409 DECLARE_PARSE_WRAPPER(_s16, int16_t);
411 
413 
425 #define COMMAND_PARSE_NUMBER(type, in, out) \
426  do { \
427  int retval_macro_tmp = parse_ ## type(in, &(out)); \
428  if (retval_macro_tmp != ERROR_OK) { \
429  command_print(CMD, stringify(out) \
430  " option value ('%s') is not valid", in); \
431  return retval_macro_tmp; \
432  } \
433  } while (0)
434 
435 #define COMMAND_PARSE_ADDRESS(in, out) \
436  COMMAND_PARSE_NUMBER(target_addr, in, out)
437 
450 #define COMMAND_PARSE_ADDITIONAL_NUMBER(type, argn, out, name_str) \
451  do { \
452  if (argn+1 >= CMD_ARGC || CMD_ARGV[argn+1][0] == '-') { \
453  command_print(CMD, "no " name_str " given"); \
454  return ERROR_FAIL; \
455  } \
456  ++argn; \
457  COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
458  } while (0)
459 
472 #define COMMAND_PARSE_OPTIONAL_NUMBER(type, argn, out) \
473  do { \
474  if (argn+1 < CMD_ARGC && CMD_ARGV[argn+1][0] != '-') { \
475  ++argn; \
476  COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
477  } \
478  } while (0)
479 
486 #define COMMAND_PARSE_BOOL(in, out, on, off) \
487  do { \
488  bool value; \
489  int retval_macro_tmp = command_parse_bool_arg(in, &value); \
490  if (retval_macro_tmp != ERROR_OK) { \
491  command_print(CMD, stringify(out) \
492  " option value ('%s') is not valid", in); \
493  command_print(CMD, " choices are '%s' or '%s'", \
494  on, off); \
495  return retval_macro_tmp; \
496  } \
497  out = value; \
498  } while (0)
499 
500 int command_parse_bool_arg(const char *in, bool *out);
501 COMMAND_HELPER(handle_command_parse_bool, bool *out, const char *label);
502 
504 #define COMMAND_PARSE_ON_OFF(in, out) \
505  COMMAND_PARSE_BOOL(in, out, "on", "off")
507 #define COMMAND_PARSE_ENABLE(in, out) \
508  COMMAND_PARSE_BOOL(in, out, "enable", "disable")
509 
510 #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:187
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:444
int command_parse_bool_arg(const char *in, bool *out)
Definition: command.c:1384
int help_del_all_commands(struct command_context *cmd_ctx)
Unregisters the help for all commands.
Definition: command.c:1024
bool jimcmd_is_oocd_command(Jim_Cmd *cmd)
Return true if the command cmd is registered by OpenOCD.
Definition: command.c:54
#define __COMMAND_HANDLER(name, extra ...)
Command handlers may be defined with more parameters than the base set provided by command....
Definition: command.h:101
int command_context_mode(struct command_context *context, enum command_mode mode)
Definition: command.c:1290
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:309
#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:59
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:287
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:1299
void command_done(struct command_context *context)
Frees the resources associated with a command context.
Definition: command.c:651
int parse_long(const char *str, long *ul)
void command_exit(struct command_context *context)
Shutdown a command context.
Definition: command.c:1280
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:416
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 __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:316
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:635
static struct command * jim_to_command(Jim_Interp *interp)
Definition: command.h:206
void void int command_run_line(struct command_context *context, char *line)
Definition: command.c:554
#define COMMAND_HELPER(name, extra ...)
Similar to COMMAND_HANDLER, except some parameters are expected.
Definition: command.h:134
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
#define DECLARE_PARSE_WRAPPER(name, type)
Definition: command.h:397
struct command_context * copy_command_context(struct command_context *cmd_ctx)
Creates a copy of an existing command context.
Definition: command.c:642
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 esp_usb_jtag __attribute__
Definition: armv8.c:804
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:82
struct command_context * ctx
Definition: command.h:77
struct command * current
Definition: command.h:78
unsigned argc
Definition: command.h:80
const char ** argv
Definition: command.h:81
const char * name
Definition: command.h:229
command_handler_t handler
Definition: command.h:230
enum command_mode mode
Definition: command.h:232
Jim_CmdProc * jim_handler
Definition: command.h:231
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:243
const char * usage
a string listing the options and arguments, required or optional
Definition: command.h:235
const char * help
Definition: command.h:233
void * jim_handler_data
Definition: command.h:195
Jim_CmdProc * jim_handler
Definition: command.h:194
command_handler_t handler
Definition: command.h:193
struct target * jim_override_target
Definition: command.h:197
enum command_mode mode
Definition: command.h:199
char * name
Definition: command.h:192
Definition: list.h:26
Definition: target.h:120
uint64_t target_addr_t
Definition: types.h:335
#define NULL
Definition: usb.h:16
uint8_t cmd
Definition: vdebug.c:1