streamline and document helptext mode displays
authorDavid Brownell <dbrownell@users.sourceforge.net>
Sat, 2 Jan 2010 23:52:35 +0000 (15:52 -0800)
committerDavid Brownell <dbrownell@users.sourceforge.net>
Sat, 2 Jan 2010 23:52:35 +0000 (15:52 -0800)
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>
doc/openocd.texi
src/flash/nor/stellaris.c
src/helper/command.c
src/server/gdb_server.c
src/target/armv7m.c
src/target/cortex_m3.c
src/target/target.c
src/target/trace.c

index cc0edf8..3f5882c 100644 (file)
@@ -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}]
index f414ca6..8d35f9b 100644 (file)
@@ -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,
        },
index b4e31ea..ab82785 100644 (file)
@@ -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);
index cf62864..d5d7042 100644 (file)
@@ -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>",
        },
index d4f6309..d0f58de 100644 (file)
@@ -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,
        },
index edf9b6f..556928f 100644 (file)
@@ -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,
        },
index d3d1bee..73a762d 100644 (file)
@@ -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",
        },
index 99d6bae..56a18a4 100644 (file)
@@ -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,
        },