helper/command.h: Add missing #include for target_addr_t
[openocd.git] / src / helper / command.h
1 /***************************************************************************
2 * Copyright (C) 2005 by Dominic Rath *
3 * Dominic.Rath@gmx.de *
4 * *
5 * Copyright (C) 2007,2008 √ėyvind Harboe *
6 * oyvind.harboe@zylin.com *
7 * *
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. *
12 * *
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. *
17 * *
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 ***************************************************************************/
21
22 #ifndef OPENOCD_HELPER_COMMAND_H
23 #define OPENOCD_HELPER_COMMAND_H
24
25 #include <stdint.h>
26 #include <stdbool.h>
27 #include <jim-nvp.h>
28
29 #include <helper/types.h>
30
31 /* To achieve C99 printf compatibility in MinGW, gnu_printf should be
32 * used for __attribute__((format( ... ))), with GCC v4.4 or later
33 */
34 #if (defined(IS_MINGW) && (((__GNUC__ << 16) + __GNUC_MINOR__) >= 0x00040004))
35 #define PRINTF_ATTRIBUTE_FORMAT gnu_printf
36 #else
37 #define PRINTF_ATTRIBUTE_FORMAT printf
38 #endif
39
40 enum command_mode {
41 COMMAND_EXEC,
42 COMMAND_CONFIG,
43 COMMAND_ANY,
44 };
45
46 struct command_context;
47
48 /** The type signature for command context's output handler. */
49 typedef int (*command_output_handler_t)(struct command_context *context,
50 const char *line);
51
52 struct command_context {
53 Jim_Interp *interp;
54 enum command_mode mode;
55 struct command *commands;
56 struct target *current_target;
57 /* The target set by 'targets xx' command or the latest created */
58 struct target *current_target_override;
59 /* If set overrides current_target
60 * It happens during processing of
61 * 1) a target prefixed command
62 * 2) an event handler
63 * Pay attention to reentrancy when setting override.
64 */
65 command_output_handler_t output_handler;
66 void *output_handler_priv;
67 };
68
69 struct command;
70
71 /**
72 * When run_command is called, a new instance will be created on the
73 * stack, filled with the proper values, and passed by reference to the
74 * required COMMAND_HANDLER routine.
75 */
76 struct command_invocation {
77 struct command_context *ctx;
78 struct command *current;
79 const char *name;
80 unsigned argc;
81 const char **argv;
82 };
83
84 /**
85 * Command handlers may be defined with more parameters than the base
86 * set provided by command.c. This macro uses C99 magic to allow
87 * defining all such derivative types using this macro.
88 */
89 #define __COMMAND_HANDLER(name, extra ...) \
90 int name(struct command_invocation *cmd, ## extra)
91
92 /**
93 * Use this to macro to call a command helper (or a nested handler).
94 * It provides command handler authors protection against reordering or
95 * removal of unused parameters.
96 *
97 * @b Note: This macro uses lexical capture to provide some arguments.
98 * As a result, this macro should be used @b only within functions
99 * defined by the COMMAND_HANDLER or COMMAND_HELPER macros. Those
100 * macros provide the expected lexical context captured by this macro.
101 * Furthermore, it should be used only from the top-level of handler or
102 * helper function, or care must be taken to avoid redefining the same
103 * variables in intervening scope(s) by accident.
104 */
105 #define CALL_COMMAND_HANDLER(name, extra ...) \
106 name(cmd, ## extra)
107
108 /**
109 * Always use this macro to define new command handler functions.
110 * It ensures the parameters are ordered, typed, and named properly, so
111 * they be can be used by other macros (e.g. COMMAND_PARSE_NUMBER).
112 * All command handler functions must be defined as static in scope.
113 */
114 #define COMMAND_HANDLER(name) \
115 static __COMMAND_HANDLER(name)
116
117 /**
118 * Similar to COMMAND_HANDLER, except some parameters are expected.
119 * A helper is globally-scoped because it may be shared between several
120 * source files (e.g. the s3c24xx device command helper).
121 */
122 #define COMMAND_HELPER(name, extra ...) __COMMAND_HANDLER(name, extra)
123
124 /**
125 * Use this macro to access the context of the command being handled,
126 * rather than accessing the variable directly. It may be moved.
127 */
128 #define CMD_CTX (cmd->ctx)
129 /**
130 * Use this macro to access the number of arguments for the command being
131 * handled, rather than accessing the variable directly. It may be moved.
132 */
133 #define CMD_ARGC (cmd->argc)
134 /**
135 * Use this macro to access the arguments for the command being handled,
136 * rather than accessing the variable directly. It may be moved.
137 */
138 #define CMD_ARGV (cmd->argv)
139 /**
140 * Use this macro to access the name of the command being handled,
141 * rather than accessing the variable directly. It may be moved.
142 */
143 #define CMD_NAME (cmd->name)
144 /**
145 * Use this macro to access the current command being handled,
146 * rather than accessing the variable directly. It may be moved.
147 */
148 #define CMD_CURRENT (cmd->current)
149 /**
150 * Use this macro to access the invoked command handler's data pointer,
151 * rather than accessing the variable directly. It may be moved.
152 */
153 #define CMD_DATA (CMD_CURRENT->jim_handler_data)
154
155 /**
156 * The type signature for command handling functions. They are
157 * usually registered as part of command_registration, providing
158 * a high-level means for executing a command.
159 *
160 * If the command fails, it *MUST* return a value != ERROR_OK
161 * (many commands break this rule, patches welcome!)
162 *
163 * This is *especially* important for commands such as writing
164 * to flash or verifying memory. The reason is that those commands
165 * can be used by programs to determine if the operation succeded
166 * or not. If the operation failed, then a program can try
167 * an alternative approach.
168 *
169 * Returning ERROR_COMMAND_SYNTAX_ERROR will have the effect of
170 * printing out the syntax of the command.
171 */
172 typedef __COMMAND_HANDLER((*command_handler_t));
173
174 struct command {
175 char *name;
176 char *help;
177 char *usage;
178 struct command *parent;
179 struct command *children;
180 command_handler_t handler;
181 Jim_CmdProc *jim_handler;
182 void *jim_handler_data;
183 /* Currently used only for target of target-prefixed cmd.
184 * Native OpenOCD commands use jim_handler_data exclusively
185 * as a target override.
186 * Jim handlers outside of target cmd tree can use
187 * jim_handler_data for any handler specific data */
188 enum command_mode mode;
189 struct command *next;
190 };
191
192 /**
193 * @param c The command to be named.
194 * @param delim The character to place between command names.
195 * @returns A malloc'd string containing the full command name,
196 * which may include one or more ancestor components. Multiple names
197 * are separated by single spaces. The caller must free() the string
198 * when done with it.
199 */
200 char *command_name(struct command *c, char delim);
201
202 /*
203 * Commands should be registered by filling in one or more of these
204 * structures and passing them to register_command().
205 *
206 * A conventioal format should be used for help strings, to provide both
207 * usage and basic information:
208 * @code
209 * "@<options@> ... - some explanation text"
210 * @endcode
211 *
212 * @param name The name of the command to register, which must not have
213 * been registered previously in the intended context.
214 * @param handler The callback function that will be called. If NULL,
215 * then the command serves as a placeholder for its children or a script.
216 * @param mode The command mode(s) in which this command may be run.
217 * @param help The help text that will be displayed to the user.
218 */
219 struct command_registration {
220 const char *name;
221 command_handler_t handler;
222 Jim_CmdProc *jim_handler;
223 void *jim_handler_data;
224 enum command_mode mode;
225 const char *help;
226 /** a string listing the options and arguments, required or optional */
227 const char *usage;
228
229 /**
230 * If non-NULL, the commands in @c chain will be registered in
231 * the same context and scope of this registration record.
232 * This allows modules to inherit lists commands from other
233 * modules.
234 */
235 const struct command_registration *chain;
236 };
237
238 /** Use this as the last entry in an array of command_registration records. */
239 #define COMMAND_REGISTRATION_DONE { .name = NULL, .chain = NULL }
240
241 /**
242 * Register a command @c handler that can be called from scripts during
243 * the execution @c mode specified.
244 *
245 * If @c parent is non-NULL, the new command will be registered as a
246 * sub-command under it; otherwise, it will be available as a top-level
247 * command.
248 *
249 * @param cmd_ctx The command_context in which to register the command.
250 * @param parent Register this command as a child of this, or NULL to
251 * register a top-level command.
252 * @param rec A command_registration record that contains the desired
253 * command parameters.
254 * @returns The new command, if successful; otherwise, NULL.
255 */
256 struct command *register_command(struct command_context *cmd_ctx,
257 struct command *parent, const struct command_registration *rec);
258
259 /**
260 * Register one or more commands in the specified context, as children
261 * of @c parent (or top-level commends, if NULL). In a registration's
262 * record contains a non-NULL @c chain member and name is NULL, the
263 * commands on the chain will be registered in the same context.
264 * Otherwise, the chained commands are added as children of the command.
265 *
266 * @param cmd_ctx The command_context in which to register the command.
267 * @param parent Register this command as a child of this, or NULL to
268 * register a top-level command.
269 * @param cmds Pointer to an array of command_registration records that
270 * contains the desired command parameters. The last record must have
271 * NULL for all fields.
272 * @returns ERROR_OK on success; ERROR_FAIL if any registration fails.
273 */
274 int register_commands(struct command_context *cmd_ctx, struct command *parent,
275 const struct command_registration *cmds);
276
277
278 /**
279 * Unregisters command @c name from the given context, @c cmd_ctx.
280 * @param cmd_ctx The context of the registered command.
281 * @param parent The parent of the given command, or NULL.
282 * @param name The name of the command to unregister.
283 * @returns ERROR_OK on success, or an error code.
284 */
285 int unregister_command(struct command_context *cmd_ctx,
286 struct command *parent, const char *name);
287 /**
288 * Unregisters all commands from the specfied context.
289 * @param cmd_ctx The context that will be cleared of registered commands.
290 * @param parent If given, only clear commands from under this one command.
291 * @returns ERROR_OK on success, or an error code.
292 */
293 int unregister_all_commands(struct command_context *cmd_ctx,
294 struct command *parent);
295
296 struct command *command_find_in_context(struct command_context *cmd_ctx,
297 const char *name);
298 struct command *command_find_in_parent(struct command *parent,
299 const char *name);
300
301 /**
302 * Update the private command data field for a command and all descendents.
303 * This is used when creating a new heirarchy of commands that depends
304 * on obtaining a dynamically created context. The value will be available
305 * in command handlers by using the CMD_DATA macro.
306 * @param c The command (group) whose data pointer(s) will be updated.
307 * @param p The new data pointer to use for the command or its descendents.
308 */
309 void command_set_handler_data(struct command *c, void *p);
310
311 void command_set_output_handler(struct command_context *context,
312 command_output_handler_t output_handler, void *priv);
313
314
315 int command_context_mode(struct command_context *context, enum command_mode mode);
316
317 /* Return the current command context associated with the Jim interpreter or
318 * alternatively the global default command interpreter
319 */
320 struct command_context *current_command_context(Jim_Interp *interp);
321 /**
322 * Creates a new command context using the startup TCL provided and
323 * the existing Jim interpreter, if any. If interp == NULL, then command_init
324 * creates a command interpreter.
325 */
326 struct command_context *command_init(const char *startup_tcl, Jim_Interp *interp);
327 /**
328 * Shutdown a command context.
329 *
330 * Free the command context and the associated Jim interpreter.
331 *
332 * @param context The command_context that will be destroyed.
333 */
334 void command_exit(struct command_context *context);
335 /**
336 * Creates a copy of an existing command context. This does not create
337 * a deep copy of the command list, so modifications in one context will
338 * affect all shared contexts. The caller must track reference counting
339 * and ensure the commands are freed before destroying the last instance.
340 * @param cmd_ctx The command_context that will be copied.
341 * @returns A new command_context with the same state as the original.
342 */
343 struct command_context *copy_command_context(struct command_context *cmd_ctx);
344 /**
345 * Frees the resources associated with a command context. The commands
346 * are not removed, so unregister_all_commands() must be called first.
347 * @param context The command_context that will be destroyed.
348 */
349 void command_done(struct command_context *context);
350
351 void command_print(struct command_context *context, const char *format, ...)
352 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
353 void command_print_sameline(struct command_context *context, const char *format, ...)
354 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
355 int command_run_line(struct command_context *context, char *line);
356 int command_run_linef(struct command_context *context, const char *format, ...)
357 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
358 void command_output_text(struct command_context *context, const char *data);
359
360 void process_jim_events(struct command_context *cmd_ctx);
361
362 #define ERROR_COMMAND_CLOSE_CONNECTION (-600)
363 #define ERROR_COMMAND_SYNTAX_ERROR (-601)
364 #define ERROR_COMMAND_NOTFOUND (-602)
365 #define ERROR_COMMAND_ARGUMENT_INVALID (-603)
366 #define ERROR_COMMAND_ARGUMENT_OVERFLOW (-604)
367 #define ERROR_COMMAND_ARGUMENT_UNDERFLOW (-605)
368
369 int parse_ulong(const char *str, unsigned long *ul);
370 int parse_ullong(const char *str, unsigned long long *ul);
371
372 int parse_long(const char *str, long *ul);
373 int parse_llong(const char *str, long long *ul);
374
375 #define DECLARE_PARSE_WRAPPER(name, type) \
376 int parse ## name(const char *str, type * ul)
377
378 DECLARE_PARSE_WRAPPER(_uint, unsigned);
379 DECLARE_PARSE_WRAPPER(_u64, uint64_t);
380 DECLARE_PARSE_WRAPPER(_u32, uint32_t);
381 DECLARE_PARSE_WRAPPER(_u16, uint16_t);
382 DECLARE_PARSE_WRAPPER(_u8, uint8_t);
383
384 DECLARE_PARSE_WRAPPER(_int, int);
385 DECLARE_PARSE_WRAPPER(_s64, int64_t);
386 DECLARE_PARSE_WRAPPER(_s32, int32_t);
387 DECLARE_PARSE_WRAPPER(_s16, int16_t);
388 DECLARE_PARSE_WRAPPER(_s8, int8_t);
389
390 DECLARE_PARSE_WRAPPER(_target_addr, target_addr_t);
391
392 /**
393 * @brief parses the string @a in into @a out as a @a type, or prints
394 * a command error and passes the error code to the caller. If an error
395 * does occur, the calling function will return the error code produced
396 * by the parsing function (one of ERROR_COMMAND_ARGUMENT_*).
397 *
398 * This function may cause the calling function to return immediately,
399 * so it should be used carefully to avoid leaking resources. In most
400 * situations, parsing should be completed in full before proceding
401 * to allocate resources, and this strategy will most prevents leaks.
402 */
403 #define COMMAND_PARSE_NUMBER(type, in, out) \
404 do { \
405 int retval_macro_tmp = parse_ ## type(in, &(out)); \
406 if (ERROR_OK != retval_macro_tmp) { \
407 command_print(CMD_CTX, stringify(out) \
408 " option value ('%s') is not valid", in); \
409 return retval_macro_tmp; \
410 } \
411 } while (0)
412
413 #define COMMAND_PARSE_ADDRESS(in, out) \
414 COMMAND_PARSE_NUMBER(target_addr, in, out)
415
416 /**
417 * Parse the string @c as a binary parameter, storing the boolean value
418 * in @c out. The strings @c on and @c off are used to match different
419 * strings for true and false options (e.g. "on" and "off" or
420 * "enable" and "disable").
421 */
422 #define COMMAND_PARSE_BOOL(in, out, on, off) \
423 do { \
424 bool value; \
425 int retval_macro_tmp = command_parse_bool_arg(in, &value); \
426 if (ERROR_OK != retval_macro_tmp) { \
427 command_print(CMD_CTX, stringify(out) \
428 " option value ('%s') is not valid", in); \
429 command_print(CMD_CTX, " choices are '%s' or '%s'", \
430 on, off); \
431 return retval_macro_tmp; \
432 } \
433 out = value; \
434 } while (0)
435
436 int command_parse_bool_arg(const char *in, bool *out);
437 COMMAND_HELPER(handle_command_parse_bool, bool *out, const char *label);
438
439 /** parses an on/off command argument */
440 #define COMMAND_PARSE_ON_OFF(in, out) \
441 COMMAND_PARSE_BOOL(in, out, "on", "off")
442 /** parses an enable/disable command argument */
443 #define COMMAND_PARSE_ENABLE(in, out) \
444 COMMAND_PARSE_BOOL(in, out, "enable", "disable")
445
446 void script_debug(Jim_Interp *interp, const char *cmd,
447 unsigned argc, Jim_Obj * const *argv);
448
449 #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)