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>
__archive__
David Brownell 2010-01-02 15:52:35 -08:00
parent 9d167d62f2
commit b3bf1d12b2
8 changed files with 39 additions and 19 deletions

View 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}]

View 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,
},

View File

@ -934,15 +934,27 @@ static COMMAND_HELPER(command_help_show, struct command *c, unsigned n,
if (is_match && show_help)
{
const char *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 = "CONFIG"; break;
case COMMAND_EXEC: stage_msg = "EXEC"; break;
case COMMAND_ANY: stage_msg = "CONFIG or EXEC"; break;
default: stage_msg = "***UNKNOWN***"; break;
case COMMAND_CONFIG:
stage_msg = " (configuration command)";
break;
case COMMAND_ANY:
stage_msg = " (command valid any time)";
break;
default:
stage_msg = " (?mode error?)";
break;
}
char *msg = alloc_printf("%s%sValid Modes: %s",
c->help ? : "", c->help ? " " : "", stage_msg);
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);

View 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>",
},

View 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,
},

View 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,
},

View 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",
},

View 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,
},