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, write to the *
20 * Free Software Foundation, Inc., *
21 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
22 ***************************************************************************/
28 /* Integrate the JIM TCL interpretor into the command processing. */
32 /* Jim is provied by eCos */
33 #include <cyg/jimtcl/jim.h>
38 /* To achieve C99 printf compatibility in MinGW, gnu_printf should be
39 * used for __attribute__((format( ... ))), with GCC v4.4 or later
41 #if (defined(IS_MINGW) && (((__GNUC__ << 16) + __GNUC_MINOR__) >= 0x00040004))
42 #define PRINTF_ATTRIBUTE_FORMAT gnu_printf
44 #define PRINTF_ATTRIBUTE_FORMAT printf
54 struct command_context
;
56 /// The type signature for command context's output handler.
57 typedef int (*command_output_handler_t
)(struct command_context
*context
,
60 struct command_context
62 enum command_mode mode
;
63 struct command
*commands
;
67 * If the command fails, it *MUST* return a value != ERROR_OK
68 * (many commands break this rule, patches welcome!)
70 * This is *especially* important for commands such as writing
71 * to flash or verifying memory. The reason is that those commands
72 * can be used by programs to determine if the operation succeded
73 * or not. If the operation failed, then a program can try
74 * an alternative approach.
76 * Returning ERROR_COMMAND_SYNTAX_ERROR will have the effect of
77 * printing out the syntax of the command.
79 command_output_handler_t output_handler
;
80 void *output_handler_priv
;
84 * When run_command is called, a new instance will be created on the
85 * stack, filled with the proper values, and passed by reference to the
86 * required COMMAND_HANDLER routine.
88 struct command_invocation
{
89 struct command_context
*ctx
;
96 * Command handlers may be defined with more parameters than the base
97 * set provided by command.c. This macro uses C99 magic to allow
98 * defining all such derivative types using this macro.
100 #define __COMMAND_HANDLER(name, extra...) \
101 int name(struct command_invocation *cmd, ##extra)
104 * Use this to macro to call a command helper (or a nested handler).
105 * It provides command handler authors protection against reordering or
106 * removal of unused parameters.
108 * @b Note: This macro uses lexical capture to provide some arguments.
109 * As a result, this macro should be used @b only within functions
110 * defined by the COMMAND_HANDLER or COMMAND_HELPER macros. Those
111 * macros provide the expected lexical context captured by this macro.
112 * Furthermore, it should be used only from the top-level of handler or
113 * helper function, or care must be taken to avoid redefining the same
114 * variables in intervening scope(s) by accident.
116 #define CALL_COMMAND_HANDLER(name, extra...) \
120 * Always use this macro to define new command handler functions.
121 * It ensures the parameters are ordered, typed, and named properly, so
122 * they be can be used by other macros (e.g. COMMAND_PARSE_NUMBER).
123 * All command handler functions must be defined as static in scope.
125 #define COMMAND_HANDLER(name) static __COMMAND_HANDLER(name)
128 * Similar to COMMAND_HANDLER, except some parameters are expected.
129 * A helper is globally-scoped because it may be shared between several
130 * source files (e.g. the s3c24xx device command helper).
132 #define COMMAND_HELPER(name, extra...) __COMMAND_HANDLER(name, extra)
135 * Use this macro to access the context of the command being handled,
136 * rather than accessing the variable directly. It may be moved.
138 #define CMD_CTX cmd->ctx
140 * Use this macro to access the number of arguments for the command being
141 * handled, rather than accessing the variable directly. It may be moved.
143 #define CMD_ARGC cmd->argc
145 * Use this macro to access the arguments for the command being handled,
146 * rather than accessing the variable directly. It may be moved.
148 #define CMD_ARGV cmd->argv
150 * Use this macro to access the name of the command being handled,
151 * rather than accessing the variable directly. It may be moved.
153 #define CMD_NAME cmd->name
156 /// The type signature for commands' handler functions.
157 typedef __COMMAND_HANDLER((*command_handler_t
));
164 struct command
*parent
;
165 struct command
*children
;
166 command_handler_t handler
;
167 Jim_CmdProc jim_handler
;
168 void *jim_handler_data
;
169 enum command_mode mode
;
170 struct command
*next
;
174 * @param c The command to be named.
175 * @param delim The character to place between command names.
176 * @returns A malloc'd string containing the full command name,
177 * which may include one or more ancestor components. Multiple names
178 * are separated by single spaces. The caller must free() the string
181 char *command_name(struct command
*c
, char delim
);
184 * Commands should be registered by filling in one or more of these
185 * structures and passing them to register_command().
187 * A conventioal format should be used for help strings, to provide both
188 * usage and basic information:
190 * "@<options@> ... - some explanation text"
193 * @param name The name of the command to register, which must not have
194 * been registered previously in the intended context.
195 * @param handler The callback function that will be called. If NULL,
196 * then the command serves as a placeholder for its children or a script.
197 * @param mode The command mode(s) in which this command may be run.
198 * @param help The help text that will be displayed to the user.
200 struct command_registration
{
202 command_handler_t handler
;
203 Jim_CmdProc jim_handler
;
204 void *jim_handler_data
;
205 enum command_mode mode
;
207 /// a string listing the options and arguments, required or optional
211 * If non-NULL, the commands in @c chain will be registered in
212 * the same context and scope of this registration record.
213 * This allows modules to inherit lists commands from other
216 const struct command_registration
*chain
;
219 /// Use this as the last entry in an array of command_registration records.
220 #define COMMAND_REGISTRATION_DONE { .name = NULL, .chain = NULL }
223 * Register a command @c handler that can be called from scripts during
224 * the execution @c mode specified.
226 * If @c parent is non-NULL, the new command will be registered as a
227 * sub-command under it; otherwise, it will be available as a top-level
230 * @param cmd_ctx The command_context in which to register the command.
231 * @param parent Register this command as a child of this, or NULL to
232 * register a top-level command.
233 * @param rec A command_registration record that contains the desired
234 * command parameters.
235 * @returns The new command, if successful; otherwise, NULL.
237 struct command
* register_command(struct command_context
*cmd_ctx
,
238 struct command
*parent
, const struct command_registration
*rec
);
240 #define COMMAND_REGISTER(_cmd_ctx, _parent, _name, _handler, _mode, _help) \
242 struct command_registration cr = { \
244 .handler = _handler, \
248 register_command(_cmd_ctx, _parent, &cr); \
252 * Register one or more commands in the specified context, as children
253 * of @c parent (or top-level commends, if NULL). In a registration's
254 * record contains a non-NULL @c chain member and name is NULL, the
255 * commands on the chain will be registered in the same context.
256 * Otherwise, the chained commands are added as children of the command.
258 * @param cmd_ctx The command_context in which to register the command.
259 * @param parent Register this command as a child of this, or NULL to
260 * register a top-level command.
261 * @param cmds Pointer to an array of command_registration records that
262 * contains the desired command parameters. The last record must have
263 * NULL for all fields.
264 * @returns ERROR_OK on success; ERROR_FAIL if any registration fails.
266 int register_commands(struct command_context
*cmd_ctx
, struct command
*parent
,
267 const struct command_registration
*cmds
);
271 * Unregisters command @c name from the given context, @c cmd_ctx.
272 * @param cmd_ctx The context of the registered command.
273 * @param parent The parent of the given command, or NULL.
274 * @param name The name of the command to unregister.
275 * @returns ERROR_OK on success, or an error code.
277 int unregister_command(struct command_context
*cmd_ctx
,
278 struct command
*parent
, const char *name
);
280 * Unregisters all commands from the specfied context.
281 * @param cmd_ctx The context that will be cleared of registered commands.
282 * @param parent If given, only clear commands from under this one command.
283 * @returns ERROR_OK on success, or an error code.
285 int unregister_all_commands(struct command_context
*cmd_ctx
,
286 struct command
*parent
);
288 struct command
*command_find_in_context(struct command_context
*cmd_ctx
,
290 struct command
*command_find_in_parent(struct command
*parent
,
293 void command_set_output_handler(struct command_context
* context
,
294 command_output_handler_t output_handler
, void *priv
);
296 struct command_context
* copy_command_context(struct command_context
* context
);
298 int command_context_mode(struct command_context
*context
, enum command_mode mode
);
301 * Creates a new command context using the startup TCL provided.
303 struct command_context
* command_init(const char *startup_tcl
);
304 int command_done(struct command_context
*context
);
306 void command_print(struct command_context
*context
, const char *format
, ...)
307 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT
, 2, 3)));
308 void command_print_sameline(struct command_context
*context
, const char *format
, ...)
309 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT
, 2, 3)));
310 int command_run_line(struct command_context
*context
, char *line
);
311 int command_run_linef(struct command_context
*context
, const char *format
, ...)
312 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT
, 2, 3)));
313 void command_output_text(struct command_context
*context
, const char *data
);
315 void process_jim_events(void);
317 #define ERROR_COMMAND_CLOSE_CONNECTION (-600)
318 #define ERROR_COMMAND_SYNTAX_ERROR (-601)
319 #define ERROR_COMMAND_NOTFOUND (-602)
320 #define ERROR_COMMAND_ARGUMENT_INVALID (-603)
321 #define ERROR_COMMAND_ARGUMENT_OVERFLOW (-604)
322 #define ERROR_COMMAND_ARGUMENT_UNDERFLOW (-605)
324 extern Jim_Interp
*interp
;
326 int parse_ulong(const char *str
, unsigned long *ul
);
327 int parse_ullong(const char *str
, unsigned long long *ul
);
329 int parse_long(const char *str
, long *ul
);
330 int parse_llong(const char *str
, long long *ul
);
332 #define DECLARE_PARSE_WRAPPER(name, type) \
333 int parse##name(const char *str, type *ul)
335 DECLARE_PARSE_WRAPPER(_uint
, unsigned);
336 DECLARE_PARSE_WRAPPER(_u32
, uint32_t);
337 DECLARE_PARSE_WRAPPER(_u16
, uint16_t);
338 DECLARE_PARSE_WRAPPER(_u8
, uint8_t);
340 DECLARE_PARSE_WRAPPER(_int
, int);
341 DECLARE_PARSE_WRAPPER(_s32
, int32_t);
342 DECLARE_PARSE_WRAPPER(_s16
, int16_t);
343 DECLARE_PARSE_WRAPPER(_s8
, int8_t);
346 * @brief parses the string @a in into @a out as a @a type, or prints
347 * a command error and passes the error code to the caller. If an error
348 * does occur, the calling function will return the error code produced
349 * by the parsing function (one of ERROR_COMMAND_ARGUMENT_*).
351 * This function may cause the calling function to return immediately,
352 * so it should be used carefully to avoid leaking resources. In most
353 * situations, parsing should be completed in full before proceding
354 * to allocate resources, and this strategy will most prevents leaks.
356 #define COMMAND_PARSE_NUMBER(type, in, out) \
358 int retval = parse_##type(in, &(out)); \
359 if (ERROR_OK != retval) { \
360 command_print(CMD_CTX, stringify(out) \
361 " option value ('%s') is not valid", in); \
367 * Parse the string @c as a binary parameter, storing the boolean value
368 * in @c out. The strings @c on and @c off are used to match different
369 * strings for true and false options (e.g. "on" and "off" or
370 * "enable" and "disable").
372 #define COMMAND_PARSE_BOOL(in, out, on, off) \
375 int retval = command_parse_bool_arg(in, &value); \
376 if (ERROR_OK != retval) { \
377 command_print(CMD_CTX, stringify(out) \
378 " option value ('%s') is not valid", in); \
379 command_print(CMD_CTX, " choices are '%s' or '%s'", \
386 int command_parse_bool_arg(const char *in
, bool *out
);
387 COMMAND_HELPER(handle_command_parse_bool
, bool *out
, const char *label
);
389 /// parses an on/off command argument
390 #define COMMAND_PARSE_ON_OFF(in, out) \
391 COMMAND_PARSE_BOOL(in, out, "on", "off")
392 /// parses an enable/disable command argument
393 #define COMMAND_PARSE_ENABLE(in, out) \
394 COMMAND_PARSE_BOOL(in, out, "enable", "disable")
396 void script_debug(Jim_Interp
*interp
, const char *cmd
,
397 unsigned argc
, Jim_Obj
*const *argv
);
399 #endif /* 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)