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>

8 files changed, 39 insertions, 19 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index cc0edf8d..3f5882ce 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 f414ca6f..8d35f9b1 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 b4e31ea1..ab827859 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 cf628641..d5d7042c 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 = "<port>",
 	},
diff --git a/src/target/armv7m.c b/src/target/armv7m.c
index d4f6309f..d0f58dee 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 edf9b6f0..556928f8 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 d3d1beee..73a762d4 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 99d6bae3..56a18a4f 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,
 	},