1 /***************************************************************************
2 * Copyright (C) 2005 by Dominic Rath *
3 * Dominic.Rath@gmx.de *
5 * Copyright (C) 2007,2008 Øyvind Harboe *
6 * oyvind.harboe@zylin.com *
8 * This program is free software; you can redistribute it and/or modify *
9 * it under the terms of the GNU General Public License as published by *
10 * the Free Software Foundation; either version 2 of the License, or *
11 * (at your option) any later version. *
13 * This program is distributed in the hope that it will be useful, *
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
16 * GNU General Public License for more details. *
18 * You should have received a copy of the GNU General Public License *
19 * along with this program. If not, see <http://www.gnu.org/licenses/>. *
20 ***************************************************************************/
22 #ifndef OPENOCD_HELPER_COMMAND_H
23 #define OPENOCD_HELPER_COMMAND_H
29 #include <helper/list.h>
30 #include <helper/types.h>
32 /* To achieve C99 printf compatibility in MinGW, gnu_printf should be
33 * used for __attribute__((format( ... ))), with GCC v4.4 or later
35 #if (defined(IS_MINGW) && (((__GNUC__ << 16) + __GNUC_MINOR__) >= 0x00040004))
36 #define PRINTF_ATTRIBUTE_FORMAT gnu_printf
38 #define PRINTF_ATTRIBUTE_FORMAT printf
45 COMMAND_UNKNOWN
= -1, /* error condition */
48 struct command_context
;
50 /** The type signature for command context's output handler. */
51 typedef int (*command_output_handler_t
)(struct command_context
*context
,
54 struct command_context
{
56 enum command_mode mode
;
57 struct target
*current_target
;
58 /* The target set by 'targets xx' command or the latest created */
59 struct target
*current_target_override
;
60 /* If set overrides current_target
61 * It happens during processing of
62 * 1) a target prefixed command
64 * Pay attention to reentrancy when setting override.
66 command_output_handler_t output_handler
;
67 void *output_handler_priv
;
68 struct list_head
*help_list
;
74 * When run_command is called, a new instance will be created on the
75 * stack, filled with the proper values, and passed by reference to the
76 * required COMMAND_HANDLER routine.
78 struct command_invocation
{
79 struct command_context
*ctx
;
80 struct command
*current
;
88 * Return true if the command @c cmd is registered by OpenOCD.
90 bool jimcmd_is_oocd_command(Jim_Cmd
*cmd
);
93 * Return the pointer to the command's private data specified during the
94 * registration of command @a cmd .
96 void *jimcmd_privdata(Jim_Cmd
*cmd
);
99 * Command handlers may be defined with more parameters than the base
100 * set provided by command.c. This macro uses C99 magic to allow
101 * defining all such derivative types using this macro.
103 #define __COMMAND_HANDLER(name, extra ...) \
104 int name(struct command_invocation *cmd, ## extra)
107 * Use this to macro to call a command helper (or a nested handler).
108 * It provides command handler authors protection against reordering or
109 * removal of unused parameters.
111 * @b Note: This macro uses lexical capture to provide some arguments.
112 * As a result, this macro should be used @b only within functions
113 * defined by the COMMAND_HANDLER or COMMAND_HELPER macros. Those
114 * macros provide the expected lexical context captured by this macro.
115 * Furthermore, it should be used only from the top-level of handler or
116 * helper function, or care must be taken to avoid redefining the same
117 * variables in intervening scope(s) by accident.
119 #define CALL_COMMAND_HANDLER(name, extra ...) \
123 * Always use this macro to define new command handler functions.
124 * It ensures the parameters are ordered, typed, and named properly, so
125 * they be can be used by other macros (e.g. COMMAND_PARSE_NUMBER).
126 * All command handler functions must be defined as static in scope.
128 #define COMMAND_HANDLER(name) \
129 static __COMMAND_HANDLER(name)
132 * Similar to COMMAND_HANDLER, except some parameters are expected.
133 * A helper is globally-scoped because it may be shared between several
134 * source files (e.g. the s3c24xx device command helper).
136 #define COMMAND_HELPER(name, extra ...) __COMMAND_HANDLER(name, extra)
139 * Use this macro to access the command being handled,
140 * rather than accessing the variable directly. It may be moved.
144 * Use this macro to access the context of the command being handled,
145 * rather than accessing the variable directly. It may be moved.
147 #define CMD_CTX (cmd->ctx)
149 * Use this macro to access the number of arguments for the command being
150 * handled, rather than accessing the variable directly. It may be moved.
152 #define CMD_ARGC (cmd->argc)
154 * Use this macro to access the arguments for the command being handled,
155 * rather than accessing the variable directly. It may be moved.
157 #define CMD_ARGV (cmd->argv)
159 * Use this macro to access the name of the command being handled,
160 * rather than accessing the variable directly. It may be moved.
162 #define CMD_NAME (cmd->name)
164 * Use this macro to access the current command being handled,
165 * rather than accessing the variable directly. It may be moved.
167 #define CMD_CURRENT (cmd->current)
169 * Use this macro to access the invoked command handler's data pointer,
170 * rather than accessing the variable directly. It may be moved.
172 #define CMD_DATA (CMD_CURRENT->jim_handler_data)
175 * The type signature for command handling functions. They are
176 * usually registered as part of command_registration, providing
177 * a high-level means for executing a command.
179 * If the command fails, it *MUST* return a value != ERROR_OK
180 * (many commands break this rule, patches welcome!)
182 * This is *especially* important for commands such as writing
183 * to flash or verifying memory. The reason is that those commands
184 * can be used by programs to determine if the operation succeeded
185 * or not. If the operation failed, then a program can try
186 * an alternative approach.
188 * Returning ERROR_COMMAND_SYNTAX_ERROR will have the effect of
189 * printing out the syntax of the command.
191 typedef __COMMAND_HANDLER((*command_handler_t
));
195 command_handler_t handler
;
196 Jim_CmdProc
*jim_handler
;
197 void *jim_handler_data
;
198 /* Command handlers can use it for any handler specific data */
199 struct target
*jim_override_target
;
200 /* Used only for target of target-prefixed cmd */
201 enum command_mode mode
;
205 * Return the struct command pointer kept in private data
206 * Used to enforce check on data type
208 static inline struct command
*jim_to_command(Jim_Interp
*interp
)
210 return Jim_CmdPrivData(interp
);
214 * Commands should be registered by filling in one or more of these
215 * structures and passing them to [un]register_commands().
217 * A conventional format should be used for help strings, to provide both
218 * usage and basic information:
220 * "@<options@> ... - some explanation text"
223 * @param name The name of the command to register, which must not have
224 * been registered previously in the intended context.
225 * @param handler The callback function that will be called. If NULL,
226 * then the command serves as a placeholder for its children or a script.
227 * @param mode The command mode(s) in which this command may be run.
228 * @param help The help text that will be displayed to the user.
230 struct command_registration
{
232 command_handler_t handler
;
233 Jim_CmdProc
*jim_handler
;
234 enum command_mode mode
;
236 /** a string listing the options and arguments, required or optional */
240 * If non-NULL, the commands in @c chain will be registered in
241 * the same context and scope of this registration record.
242 * This allows modules to inherit lists commands from other
245 const struct command_registration
*chain
;
248 /** Use this as the last entry in an array of command_registration records. */
249 #define COMMAND_REGISTRATION_DONE { .name = NULL, .chain = NULL }
251 int __register_commands(struct command_context
*cmd_ctx
, const char *cmd_prefix
,
252 const struct command_registration
*cmds
, void *data
,
253 struct target
*override_target
);
256 * Register one or more commands in the specified context, as children
257 * of @c parent (or top-level commends, if NULL). In a registration's
258 * record contains a non-NULL @c chain member and name is NULL, the
259 * commands on the chain will be registered in the same context.
260 * Otherwise, the chained commands are added as children of the command.
262 * @param cmd_ctx The command_context in which to register the command.
263 * @param cmd_prefix Register this command as a child of this, or NULL to
264 * register a top-level command.
265 * @param cmds Pointer to an array of command_registration records that
266 * contains the desired command parameters. The last record must have
267 * NULL for all fields.
268 * @returns ERROR_OK on success; ERROR_FAIL if any registration fails.
270 static inline int register_commands(struct command_context
*cmd_ctx
, const char *cmd_prefix
,
271 const struct command_registration
*cmds
)
273 return __register_commands(cmd_ctx
, cmd_prefix
, cmds
, NULL
, NULL
);
277 * Register one or more commands, as register_commands(), plus specify
278 * that command should override the current target
280 * @param cmd_ctx The command_context in which to register the command.
281 * @param cmd_prefix Register this command as a child of this, or NULL to
282 * register a top-level command.
283 * @param cmds Pointer to an array of command_registration records that
284 * contains the desired command parameters. The last record must have
285 * NULL for all fields.
286 * @param target The target that has to override current target.
287 * @returns ERROR_OK on success; ERROR_FAIL if any registration fails.
289 static inline int register_commands_override_target(struct command_context
*cmd_ctx
,
290 const char *cmd_prefix
, const struct command_registration
*cmds
,
291 struct target
*target
)
293 return __register_commands(cmd_ctx
, cmd_prefix
, cmds
, NULL
, target
);
297 * Register one or more commands, as register_commands(), plus specify
298 * a pointer to command private data that would be accessible through
299 * the macro CMD_DATA. The private data will not be freed when command
302 * @param cmd_ctx The command_context in which to register the command.
303 * @param cmd_prefix Register this command as a child of this, or NULL to
304 * register a top-level command.
305 * @param cmds Pointer to an array of command_registration records that
306 * contains the desired command parameters. The last record must have
307 * NULL for all fields.
308 * @param data The command private data.
309 * @returns ERROR_OK on success; ERROR_FAIL if any registration fails.
311 static inline int register_commands_with_data(struct command_context
*cmd_ctx
,
312 const char *cmd_prefix
, const struct command_registration
*cmds
,
315 return __register_commands(cmd_ctx
, cmd_prefix
, cmds
, data
, NULL
);
319 * Unregisters all commands from the specified context.
320 * @param cmd_ctx The context that will be cleared of registered commands.
321 * @param cmd_prefix If given, only clear commands from under this one command.
322 * @returns ERROR_OK on success, or an error code.
324 int unregister_all_commands(struct command_context
*cmd_ctx
,
325 const char *cmd_prefix
);
328 * Unregisters the help for all commands. Used at exit to remove the help
329 * added through the commands 'add_help_text' and 'add_usage_text'.
330 * @param cmd_ctx The context that will be cleared of registered helps.
331 * @returns ERROR_OK on success, or an error code.
333 int help_del_all_commands(struct command_context
*cmd_ctx
);
335 void command_set_output_handler(struct command_context
*context
,
336 command_output_handler_t output_handler
, void *priv
);
339 int command_context_mode(struct command_context
*context
, enum command_mode mode
);
341 /* Return the current command context associated with the Jim interpreter or
342 * alternatively the global default command interpreter
344 struct command_context
*current_command_context(Jim_Interp
*interp
);
346 * Creates a new command context using the startup TCL provided and
347 * the existing Jim interpreter, if any. If interp == NULL, then command_init
348 * creates a command interpreter.
350 struct command_context
*command_init(const char *startup_tcl
, Jim_Interp
*interp
);
352 * Shutdown a command context.
354 * Free the command context and the associated Jim interpreter.
356 * @param context The command_context that will be destroyed.
358 void command_exit(struct command_context
*context
);
360 * Creates a copy of an existing command context. This does not create
361 * a deep copy of the command list, so modifications in one context will
362 * affect all shared contexts. The caller must track reference counting
363 * and ensure the commands are freed before destroying the last instance.
364 * @param cmd_ctx The command_context that will be copied.
365 * @returns A new command_context with the same state as the original.
367 struct command_context
*copy_command_context(struct command_context
*cmd_ctx
);
369 * Frees the resources associated with a command context. The commands
370 * are not removed, so unregister_all_commands() must be called first.
371 * @param context The command_context that will be destroyed.
373 void command_done(struct command_context
*context
);
375 void command_print(struct command_invocation
*cmd
, const char *format
, ...)
376 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT
, 2, 3)));
377 void command_print_sameline(struct command_invocation
*cmd
, const char *format
, ...)
378 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT
, 2, 3)));
379 int command_run_line(struct command_context
*context
, char *line
);
380 int command_run_linef(struct command_context
*context
, const char *format
, ...)
381 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT
, 2, 3)));
382 void command_output_text(struct command_context
*context
, const char *data
);
384 void process_jim_events(struct command_context
*cmd_ctx
);
386 #define ERROR_COMMAND_CLOSE_CONNECTION (-600)
387 #define ERROR_COMMAND_SYNTAX_ERROR (-601)
388 #define ERROR_COMMAND_NOTFOUND (-602)
389 #define ERROR_COMMAND_ARGUMENT_INVALID (-603)
390 #define ERROR_COMMAND_ARGUMENT_OVERFLOW (-604)
391 #define ERROR_COMMAND_ARGUMENT_UNDERFLOW (-605)
393 int parse_ulong(const char *str
, unsigned long *ul
);
394 int parse_ullong(const char *str
, unsigned long long *ul
);
396 int parse_long(const char *str
, long *ul
);
397 int parse_llong(const char *str
, long long *ul
);
399 #define DECLARE_PARSE_WRAPPER(name, type) \
400 int parse ## name(const char *str, type * ul)
402 DECLARE_PARSE_WRAPPER(_uint
, unsigned);
403 DECLARE_PARSE_WRAPPER(_u64
, uint64_t);
404 DECLARE_PARSE_WRAPPER(_u32
, uint32_t);
405 DECLARE_PARSE_WRAPPER(_u16
, uint16_t);
406 DECLARE_PARSE_WRAPPER(_u8
, uint8_t);
408 DECLARE_PARSE_WRAPPER(_int
, int);
409 DECLARE_PARSE_WRAPPER(_s64
, int64_t);
410 DECLARE_PARSE_WRAPPER(_s32
, int32_t);
411 DECLARE_PARSE_WRAPPER(_s16
, int16_t);
412 DECLARE_PARSE_WRAPPER(_s8
, int8_t);
414 DECLARE_PARSE_WRAPPER(_target_addr
, target_addr_t
);
417 * @brief parses the string @a in into @a out as a @a type, or prints
418 * a command error and passes the error code to the caller. If an error
419 * does occur, the calling function will return the error code produced
420 * by the parsing function (one of ERROR_COMMAND_ARGUMENT_*).
422 * This function may cause the calling function to return immediately,
423 * so it should be used carefully to avoid leaking resources. In most
424 * situations, parsing should be completed in full before proceeding
425 * to allocate resources, and this strategy will most prevents leaks.
427 #define COMMAND_PARSE_NUMBER(type, in, out) \
429 int retval_macro_tmp = parse_ ## type(in, &(out)); \
430 if (retval_macro_tmp != ERROR_OK) { \
431 command_print(CMD, stringify(out) \
432 " option value ('%s') is not valid", in); \
433 return retval_macro_tmp; \
437 #define COMMAND_PARSE_ADDRESS(in, out) \
438 COMMAND_PARSE_NUMBER(target_addr, in, out)
441 * @brief parses the command argument at position @a argn into @a out
442 * as a @a type, or prints a command error referring to @a name_str
443 * and passes the error code to the caller. @a argn will be incremented
444 * if no error occurred. Otherwise the calling function will return
445 * the error code produced by the parsing function.
447 * This function may cause the calling function to return immediately,
448 * so it should be used carefully to avoid leaking resources. In most
449 * situations, parsing should be completed in full before proceeding
450 * to allocate resources, and this strategy will most prevents leaks.
452 #define COMMAND_PARSE_ADDITIONAL_NUMBER(type, argn, out, name_str) \
454 if (argn+1 >= CMD_ARGC || CMD_ARGV[argn+1][0] == '-') { \
455 command_print(CMD, "no " name_str " given"); \
459 COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
463 * @brief parses the command argument at position @a argn into @a out
464 * as a @a type if the argument @a argn does not start with '-'.
465 * and passes the error code to the caller. @a argn will be incremented
466 * if no error occurred. Otherwise the calling function will return
467 * the error code produced by the parsing function.
469 * This function may cause the calling function to return immediately,
470 * so it should be used carefully to avoid leaking resources. In most
471 * situations, parsing should be completed in full before proceeding
472 * to allocate resources, and this strategy will most prevents leaks.
474 #define COMMAND_PARSE_OPTIONAL_NUMBER(type, argn, out) \
476 if (argn+1 < CMD_ARGC && CMD_ARGV[argn+1][0] != '-') { \
478 COMMAND_PARSE_NUMBER(type, CMD_ARGV[argn], out); \
483 * Parse the string @c as a binary parameter, storing the boolean value
484 * in @c out. The strings @c on and @c off are used to match different
485 * strings for true and false options (e.g. "on" and "off" or
486 * "enable" and "disable").
488 #define COMMAND_PARSE_BOOL(in, out, on, off) \
491 int retval_macro_tmp = command_parse_bool_arg(in, &value); \
492 if (retval_macro_tmp != ERROR_OK) { \
493 command_print(CMD, stringify(out) \
494 " option value ('%s') is not valid", in); \
495 command_print(CMD, " choices are '%s' or '%s'", \
497 return retval_macro_tmp; \
502 int command_parse_bool_arg(const char *in
, bool *out
);
503 COMMAND_HELPER(handle_command_parse_bool
, bool *out
, const char *label
);
505 /** parses an on/off command argument */
506 #define COMMAND_PARSE_ON_OFF(in, out) \
507 COMMAND_PARSE_BOOL(in, out, "on", "off")
508 /** parses an enable/disable command argument */
509 #define COMMAND_PARSE_ENABLE(in, out) \
510 COMMAND_PARSE_BOOL(in, out, "enable", "disable")
512 #endif /* OPENOCD_HELPER_COMMAND_H */
Linking to existing account procedure
If you already have an account and want to add another login method
you
MUST first sign in with your existing account and
then change URL to read
https://review.openocd.org/login/?link
to get to this page again but this time it'll work for linking. Thank you.
SSH host keys fingerprints
1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=.. |
|+o.. . |
|*.o . . |
|+B . . . |
|Bo. = o S |
|Oo.+ + = |
|oB=.* = . o |
| =+=.+ + E |
|. .=o . o |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)