From: David Brownell Date: Sat, 2 Jan 2010 23:52:35 +0000 (-0800) Subject: streamline and document helptext mode displays X-Git-Tag: v0.4.0-rc2~163 X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=commitdiff_plain;h=b3bf1d12b2fdfba1c1cbee3e1afbfbb27cbd1a26 streamline and document helptext mode displays Most commands are usable only at runtime; so don't bother saying that, it's noise. Moreover, tokens like EXEC are cryptic. Be more clear: highlight only the commands which may (also) be used during the config stage, thus matching the docs more closely. There are - Configuration commands (per documentation) - And also some commands that valid at *any* time. Update the docs to note that "help" now shows this mode info. This also highlighted a few mistakes in command configuration, mostly commands listed as "valid at any time" which shouldn't have been. This just fixes ones I noted when sanity testing. Signed-off-by: David Brownell --- diff --git a/doc/openocd.texi b/doc/openocd.texi index cc0edf8d5d..3f5882ceeb 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -1630,9 +1630,14 @@ supported. When the OpenOCD server process starts up, it enters a @emph{configuration stage} which is the only time that certain commands, @emph{configuration commands}, may be issued. +Normally, configuration commands are only available +inside startup scripts. + In this manual, the definition of a configuration command is presented as a @emph{Config Command}, not as a @emph{Command} which may be issued interactively. +The runtime @command{help} command also highlights configuration +commands, and those which may be issued at any time. Those configuration commands include declaration of TAPs, flash banks, @@ -5093,13 +5098,15 @@ port is 5555. Exits the current telnet session. @end deffn -@c note EXTREMELY ANNOYING word wrap at column 75 -@c even when lines are e.g. 100+ columns ... -@c coded in startup.tcl @deffn {Command} help [string] With no parameters, prints help text for all commands. Otherwise, prints each helptext containing @var{string}. Not every command provides helptext. + +Configuration commands, and commands valid at any time, are +explicitly noted in parenthesis. +In most cases, no such restriction is listed; this indicates commands +which are only available after the configuration stage has completed. @end deffn @deffn Command sleep msec [@option{busy}] diff --git a/src/flash/nor/stellaris.c b/src/flash/nor/stellaris.c index f414ca6f1f..8d35f9b10f 100644 --- a/src/flash/nor/stellaris.c +++ b/src/flash/nor/stellaris.c @@ -1182,7 +1182,7 @@ static const struct command_registration stellaris_exec_command_handlers[] = { static const struct command_registration stellaris_command_handlers[] = { { .name = "stellaris", - .mode = COMMAND_ANY, + .mode = COMMAND_EXEC, .help = "Stellaris flash command group", .chain = stellaris_exec_command_handlers, }, diff --git a/src/helper/command.c b/src/helper/command.c index b4e31ea1a7..ab827859f7 100644 --- a/src/helper/command.c +++ b/src/helper/command.c @@ -914,7 +914,7 @@ static COMMAND_HELPER(command_help_show, struct command *c, unsigned n, bool is_match = (strstr(cmd_name, match) != NULL) || ((c->usage != NULL) && (strstr(c->usage, match) != NULL)) || ((c->help != NULL) && (strstr(c->help, match) != NULL)); - + if (is_match) { command_help_show_indent(n); @@ -934,15 +934,27 @@ static COMMAND_HELPER(command_help_show, struct command *c, unsigned n, if (is_match && show_help) { - const char *stage_msg; - switch (c->mode) { - case COMMAND_CONFIG: stage_msg = "CONFIG"; break; - case COMMAND_EXEC: stage_msg = "EXEC"; break; - case COMMAND_ANY: stage_msg = "CONFIG or EXEC"; break; - default: stage_msg = "***UNKNOWN***"; break; - } - char *msg = alloc_printf("%s%sValid Modes: %s", - c->help ? : "", c->help ? " " : "", stage_msg); + char *msg; + + /* Normal commands are runtime-only; highlight exceptions */ + if (c->mode != COMMAND_EXEC) { + const char *stage_msg = ""; + + switch (c->mode) { + case COMMAND_CONFIG: + stage_msg = " (configuration command)"; + break; + case COMMAND_ANY: + stage_msg = " (command valid any time)"; + break; + default: + stage_msg = " (?mode error?)"; + break; + } + msg = alloc_printf("%s%s", c->help ? : "", stage_msg); + } else + msg = alloc_printf("%s", c->help ? : ""); + if (NULL != msg) { command_help_show_wrap(msg, n + 3, n + 3); diff --git a/src/server/gdb_server.c b/src/server/gdb_server.c index cf62864188..d5d7042cd5 100644 --- a/src/server/gdb_server.c +++ b/src/server/gdb_server.c @@ -2272,6 +2272,7 @@ static int gdb_target_start(struct target *target, uint16_t port) return ERROR_OK; } +/* FIXME static */ int gdb_target_add_one(struct target *target) { if (gdb_port == 0 && server_use_pipes == 0) @@ -2420,7 +2421,7 @@ static const struct command_registration gdb_command_handlers[] = { { .name = "gdb_port", .handler = &handle_gdb_port_command, - .mode = COMMAND_ANY, + .mode = COMMAND_CONFIG, .help = "daemon configuration command gdb_port", .usage = "", }, diff --git a/src/target/armv7m.c b/src/target/armv7m.c index d4f6309ff6..d0f58deecc 100644 --- a/src/target/armv7m.c +++ b/src/target/armv7m.c @@ -834,7 +834,7 @@ static const struct command_registration armv7m_exec_command_handlers[] = { const struct command_registration armv7m_command_handlers[] = { { .name = "dap", - .mode = COMMAND_ANY, + .mode = COMMAND_EXEC, .help = "Cortex DAP command group", .chain = armv7m_exec_command_handlers, }, diff --git a/src/target/cortex_m3.c b/src/target/cortex_m3.c index edf9b6f09c..556928f826 100644 --- a/src/target/cortex_m3.c +++ b/src/target/cortex_m3.c @@ -2003,7 +2003,7 @@ static const struct command_registration cortex_m3_command_handlers[] = { }, { .name = "cortex_m3", - .mode = COMMAND_ANY, + .mode = COMMAND_EXEC, .help = "Cortex-M3 command group", .chain = cortex_m3_exec_command_handlers, }, diff --git a/src/target/target.c b/src/target/target.c index d3d1beee08..73a762d499 100644 --- a/src/target/target.c +++ b/src/target/target.c @@ -4866,7 +4866,7 @@ static const struct command_registration target_exec_command_handlers[] = { { .name = "fast_load", .handler = &handle_fast_load_command, - .mode = COMMAND_ANY, + .mode = COMMAND_EXEC, .help = "loads active fast load image to current target " "- mainly for profiling purposes", }, diff --git a/src/target/trace.c b/src/target/trace.c index 99d6bae3bf..56a18a4f9f 100644 --- a/src/target/trace.c +++ b/src/target/trace.c @@ -177,7 +177,7 @@ static const struct command_registration trace_exec_command_handlers[] = { static const struct command_registration trace_command_handlers[] = { { .name = "trace", - .mode = COMMAND_ANY, + .mode = COMMAND_EXEC, .help = "trace command group", .chain = trace_exec_command_handlers, },