add more command_handler conversion macros
[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, write to the *
20 * Free Software Foundation, Inc., *
21 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
22 ***************************************************************************/
23 #ifndef COMMAND_H
24 #define COMMAND_H
25
26 #include "types.h"
27
28 /* Integrate the JIM TCL interpretor into the command processing. */
29 #if BUILD_ECOSBOARD
30 #include <stdio.h>
31 #include <stdarg.h>
32 /* Jim is provied by eCos */
33 #include <cyg/jimtcl/jim.h>
34 #else
35 #include "jim.h"
36 #endif
37
38 /* To achieve C99 printf compatibility in MinGW, gnu_printf should be
39 * used for __attribute__((format( ... ))), with GCC v4.4 or later
40 */
41 #if (defined(IS_MINGW) && (((__GNUC__ << 16) + __GNUC_MINOR__) >= 0x00040004))
42 #define PRINTF_ATTRIBUTE_FORMAT gnu_printf
43 #else
44 #define PRINTF_ATTRIBUTE_FORMAT printf
45 #endif
46
47 enum command_mode
48 {
49 COMMAND_EXEC,
50 COMMAND_CONFIG,
51 COMMAND_ANY,
52 };
53
54 struct command_context;
55
56 /// The type signature for command context's output handler.
57 typedef int (*command_output_handler_t)(struct command_context *context,
58 const char* line);
59
60 struct command_context
61 {
62 enum command_mode mode;
63 struct command *commands;
64 int current_target;
65 /* Execute a command.
66 *
67 * If the command fails, it *MUST* return a value != ERROR_OK
68 * (many commands break this rule, patches welcome!)
69 *
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.
75 *
76 * Returning ERROR_COMMAND_SYNTAX_ERROR will have the effect of
77 * printing out the syntax of the command.
78 */
79 command_output_handler_t output_handler;
80 void *output_handler_priv;
81 };
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_context *cmd_ctx, \
91 const char *args[], unsigned argc, ##extra)
92
93 /**
94 * Use this to macro to call a command helper (or a nested handler).
95 * It provides command handler authors protection against reordering or
96 * removal of unused parameters.
97 *
98 * @b Note: This macro uses lexical capture to provide some arguments.
99 * As a result, this macro should be used @b only within functions
100 * defined by the COMMAND_HANDLER or COMMAND_HELPER macros. Those
101 * macros provide the expected lexical context captured by this macro.
102 * Furthermore, it should be used only from the top-level of handler or
103 * helper function, or care must be taken to avoid redefining the same
104 * variables in intervening scope(s) by accident.
105 */
106 #define CALL_COMMAND_HANDLER(name, extra...) \
107 name(cmd_ctx, args, argc, ##extra)
108
109 /**
110 * Always use this macro to define new command handler functions.
111 * It ensures the parameters are ordered, typed, and named properly, so
112 * they be can be used by other macros (e.g. COMMAND_PARSE_NUMBER).
113 * All command handler functions must be defined as static in scope.
114 */
115 #define COMMAND_HANDLER(name) 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 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 args
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_ARGV[-1]
144
145
146 /// The type signature for commands' handler functions.
147 typedef __COMMAND_HANDLER((*command_handler_t));
148
149 struct command
150 {
151 char *name;
152 struct command *parent;
153 struct command *children;
154 command_handler_t handler;
155 enum command_mode mode;
156 struct command *next;
157 };
158
159 /**
160 * @param c The command to be named.
161 * @param delim The character to place between command names.
162 * @returns A malloc'd string containing the full command name,
163 * which may include one or more ancestor components. Multiple names
164 * are separated by single spaces. The caller must free() the string
165 * when done with it.
166 */
167 char *command_name(struct command *c, char delim);
168
169 struct command* register_command(struct command_context *context,
170 struct command *parent, char *name, command_handler_t handler,
171 enum command_mode mode, char *help);
172
173 int unregister_command(struct command_context *context, char *name);
174 int unregister_all_commands(struct command_context *context);
175
176 void command_set_output_handler(struct command_context* context,
177 command_output_handler_t output_handler, void *priv);
178
179 struct command_context* copy_command_context(struct command_context* context);
180
181 int command_context_mode(struct command_context *context, enum command_mode mode);
182
183 struct command_context* command_init(void);
184 int command_done(struct command_context *context);
185
186 void command_print(struct command_context *context, const char *format, ...)
187 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
188 void command_print_sameline(struct command_context *context, const char *format, ...)
189 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
190 int command_run_line(struct command_context *context, char *line);
191 int command_run_linef(struct command_context *context, const char *format, ...)
192 __attribute__ ((format (PRINTF_ATTRIBUTE_FORMAT, 2, 3)));
193 void command_output_text(struct command_context *context, const char *data);
194
195 void process_jim_events(void);
196
197 #define ERROR_COMMAND_CLOSE_CONNECTION (-600)
198 #define ERROR_COMMAND_SYNTAX_ERROR (-601)
199 #define ERROR_COMMAND_NOTFOUND (-602)
200 #define ERROR_COMMAND_ARGUMENT_INVALID (-603)
201 #define ERROR_COMMAND_ARGUMENT_OVERFLOW (-604)
202 #define ERROR_COMMAND_ARGUMENT_UNDERFLOW (-605)
203
204 extern int fast_and_dangerous;
205
206 extern Jim_Interp *interp;
207
208 void register_jim(struct command_context *context, const char *name,
209 Jim_CmdProc cmd, const char *help);
210
211 long jim_global_long(const char *variable);
212
213 int parse_ulong(const char *str, unsigned long *ul);
214 int parse_ullong(const char *str, unsigned long long *ul);
215
216 int parse_long(const char *str, long *ul);
217 int parse_llong(const char *str, long long *ul);
218
219 #define DECLARE_PARSE_WRAPPER(name, type) \
220 int parse##name(const char *str, type *ul)
221
222 DECLARE_PARSE_WRAPPER(_uint, unsigned);
223 DECLARE_PARSE_WRAPPER(_u32, uint32_t);
224 DECLARE_PARSE_WRAPPER(_u16, uint16_t);
225 DECLARE_PARSE_WRAPPER(_u8, uint8_t);
226
227 DECLARE_PARSE_WRAPPER(_int, int);
228 DECLARE_PARSE_WRAPPER(_s32, int32_t);
229 DECLARE_PARSE_WRAPPER(_s16, int16_t);
230 DECLARE_PARSE_WRAPPER(_s8, int8_t);
231
232 /**
233 * @brief parses the string @a in into @a out as a @a type, or prints
234 * a command error and passes the error code to the caller. If an error
235 * does occur, the calling function will return the error code produced
236 * by the parsing function (one of ERROR_COMMAND_ARGUMENT_*).
237 *
238 * This function may cause the calling function to return immediately,
239 * so it should be used carefully to avoid leaking resources. In most
240 * situations, parsing should be completed in full before proceding
241 * to allocate resources, and this strategy will most prevents leaks.
242 */
243 #define COMMAND_PARSE_NUMBER(type, in, out) \
244 do { \
245 int retval = parse_##type(in, &(out)); \
246 if (ERROR_OK != retval) { \
247 command_print(cmd_ctx, stringify(out) \
248 " option value ('%s') is not valid", in); \
249 return retval; \
250 } \
251 } while (0)
252
253 void script_debug(Jim_Interp *interp, const char *cmd,
254 unsigned argc, Jim_Obj *const *argv);
255
256 #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)