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 <dbrownell@users.sourceforge.net>

diff --git a/doc/openocd.texi b/doc/openocd.texi
index cc0edf8d5d89b9ebf1f43560565810cc5f53975b..3f5882ceebbc66b6b142be0b46d0cdca685fc1cc 100644 (file)
--- 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 f414ca6f1f0e1582ca821c2ab411b4090f1e66bb..8d35f9b10f1d158f07725ffefa9cff145bf185fa 100644 (file)
--- 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 b4e31ea1a7e1d2a3a975ad5515999dcd1fd14306..ab827859f754caf2a613f2bdbbcc68f64006bb53 100644 (file)
--- 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 cf62864188feffda109dc007d92ed083479a7cbf..d5d7042cd5ced097ac68236df6dd13096119458f 100644 (file)
--- 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 = "<port>",
        },

diff --git a/src/target/armv7m.c b/src/target/armv7m.c
index d4f6309ff6f021cbfe5a882583a95c21f78dc91b..d0f58deecc4dccd879452e6c2b09e1fb65b19afe 100644 (file)
--- 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 edf9b6f09cc134c71b553a8aad201060837db401..556928f826044954916fe21e45c46930fe82729c 100644 (file)
--- 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 d3d1beee08bd00a181145252cf2c609cd7fb9f8e..73a762d4990a82df9a3cd619385ab48f461989da 100644 (file)
--- 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 99d6bae3bfd7918f067c265f344594eb77685b20..56a18a4f9fe3de5d1bc0baa6def514ef72e03168 100644 (file)
--- 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,
        },