src/helper: usage/help updates

Make "usage" messages use the same EBNF as the User's Guide;
no angle brackets.  Improve and correct various helptexts.

Don't use "&function"; a function's name is its address.
Fix some whitespace glitches, shrink a few overlong lines.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

diff --git a/src/helper/command.c b/src/helper/command.c
index 0ddcd019c1fd3055849f648ae370dd12aa3c57b5..288ed72af49dc81a49e59c251ae885bb61a2b807 100644 (file)
--- a/src/helper/command.c
+++ b/src/helper/command.c
@@ -1087,6 +1087,7 @@ static int jim_command_mode(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
 {
        struct command_context *cmd_ctx = current_command_context(interp);
        enum command_mode mode;
+
        if (argc > 1)
        {
                struct command *c = cmd_ctx->commands;
@@ -1223,7 +1224,7 @@ COMMAND_HANDLER(handle_help_add_command)
        return help_add_command(CMD_CTX, c, cmd_name, help, usage);
 }
 
-/* sleep command sleeps for <n> miliseconds
+/* sleep command sleeps for <n> milliseconds
  * this is useful in target startup scripts
  */
 COMMAND_HANDLER(handle_sleep_command)
@@ -1263,19 +1264,22 @@ static const struct command_registration command_subcommand_handlers[] = {
        {
                .name = "mode",
                .mode = COMMAND_ANY,
-               .jim_handler = &jim_command_mode,
-               .usage = "[<name> ...]",
+               .jim_handler = jim_command_mode,
+               .usage = "[command_name ...]",
                .help = "Returns the command modes allowed by a  command:"
                        "'any', 'config', or 'exec'.  If no command is"
-                       "specified, returns the current command mode.",
+                       "specified, returns the current command mode.  "
+                       "Returns 'unknown' if an unknown command is given. "
+                       "Command can be multiple tokens.",
        },
        {
                .name = "type",
                .mode = COMMAND_ANY,
-               .jim_handler = &jim_command_type,
-               .usage = "<name> ...",
+               .jim_handler = jim_command_type,
+               .usage = "command_name [...]",
                .help = "Returns the type of built-in command:"
-                       "'native', 'simple', 'group', or 'unknown'",
+                       "'native', 'simple', 'group', or 'unknown'. "
+                       "Command can be multiple tokens.",
        },
        COMMAND_REGISTRATION_DONE
 };
@@ -1283,39 +1287,43 @@ static const struct command_registration command_subcommand_handlers[] = {
 static const struct command_registration command_builtin_handlers[] = {
        {
                .name = "add_help_text",
-               .handler = &handle_help_add_command,
+               .handler = handle_help_add_command,
                .mode = COMMAND_ANY,
-               .help = "add new command help text",
-               .usage = "<command> [...] <help_text>]",
+               .help = "Add new command help text; "
+                       "Command can be multiple tokens.",
+               .usage = "command_name helptext_string",
        },
        {
                .name = "add_usage_text",
-               .handler = &handle_help_add_command,
+               .handler = handle_help_add_command,
                .mode = COMMAND_ANY,
-               .help = "add new command usage text",
-               .usage = "<command> [...] <usage_text>]",
+               .help = "Add new command usage text; "
+                       "command can be multiple tokens.",
+               .usage = "command_name usage_string",
        },
        {
                .name = "sleep",
-               .handler = &handle_sleep_command,
+               .handler = handle_sleep_command,
                .mode = COMMAND_ANY,
-               .help = "sleep for n milliseconds.  "
-                       "\"busy\" will busy wait",
-               .usage = "<n> [busy]",
+               .help = "Sleep for specified number of milliseconds.  "
+                       "\"busy\" will busy wait instead (avoid this).",
+               .usage = "milliseconds ['busy']",
        },
        {
                .name = "help",
-               .handler = &handle_help_command,
+               .handler = handle_help_command,
                .mode = COMMAND_ANY,
-               .help = "show full command help",
-               .usage = "[<command> ...]",
+               .help = "Show full command help; "
+                       "command can be multiple tokens.",
+               .usage = "[command_name]",
        },
        {
                .name = "usage",
-               .handler = &handle_help_command,
+               .handler = handle_help_command,
                .mode = COMMAND_ANY,
-               .help = "show basic command usage",
-               .usage = "[<command> ...]",
+               .help = "Show basic command usage; "
+                       "command can be multiple tokens.",
+               .usage = "[command_name]",
        },
        {
                .name = "command",

diff --git a/src/helper/ioutil.c b/src/helper/ioutil.c
index 27bffad33687667c298238624616b3b4c0fc9f6f..14f6e91dbb4685de4c4be687d6380cc3dda2df67 100644 (file)
--- a/src/helper/ioutil.c
+++ b/src/helper/ioutil.c
@@ -191,6 +191,7 @@ COMMAND_HANDLER(handle_append_command)
 
        int retval = ERROR_FAIL;
        FILE *config_file = NULL;
+
        config_file = fopen(CMD_ARGV[0], "a");
        if (config_file != NULL)
        {
@@ -199,7 +200,8 @@ COMMAND_HANDLER(handle_append_command)
                unsigned i;
                for (i = 1; i < CMD_ARGC; i++)
                {
-                       if (fwrite(CMD_ARGV[i], 1, strlen(CMD_ARGV[i]), config_file) != strlen(CMD_ARGV[i]))
+                       if (fwrite(CMD_ARGV[i], 1, strlen(CMD_ARGV[i]),
+                                       config_file) != strlen(CMD_ARGV[i]))
                                break;
                        if (i != CMD_ARGC - 1)
                        {
@@ -208,9 +210,8 @@ COMMAND_HANDLER(handle_append_command)
                        }
                }
                if ((i == CMD_ARGC) && (fwrite("\n", 1, 1, config_file) == 1))
-               {
                        retval = ERROR_OK;
-               }
+
                fclose(config_file);
        }
 
@@ -619,76 +620,86 @@ static int zylinjtag_Jim_Command_mac(Jim_Interp *interp, int argc,
 static const struct command_registration ioutil_command_handlers[] = {
        {
                .name = "cat",
-               .handler = &handle_cat_command,
+               .handler = handle_cat_command,
                .mode = COMMAND_ANY,
-               .help = "display file content",
-               .usage= "<file_name>",
+               .help = "display text file content",
+               .usage= "file_name",
        },
        {
                .name = "trunc",
-               .handler = &handle_trunc_command,
+               .handler = handle_trunc_command,
                .mode = COMMAND_ANY,
-               .help = "truncate a file 0 size",
-               .usage= "<file_name>",
+               .help = "truncate a file to zero length",
+               .usage= "file_name",
        },
        {
                .name = "cp",
-               .handler = &handle_cp_command,
+               .handler = handle_cp_command,
                .mode = COMMAND_ANY,
                .help = "copy a file",
-               .usage = "<src> <dst>",
+               .usage = "src_file_name dst_file_name",
        },
        {
                .name = "append_file",
-               .handler = &handle_append_command,
+               .handler = handle_append_command,
                .mode = COMMAND_ANY,
                .help = "append a variable number of strings to a file",
-               .usage= "<file_name> [<string> ...]",
+               .usage= "file_name [string ...]",
        },
        {
                .name = "meminfo",
-               .handler = &handle_meminfo_command,
+               .handler = handle_meminfo_command,
                .mode = COMMAND_ANY,
-               .help = "display available ram memory",
+               .help = "display free heap space",
        },
        {
                .name = "rm",
                .mode = COMMAND_ANY,
-               .handler = &handle_rm_command,
-               .help = "remove a file",
-               .usage = "<file>",
+               .handler = handle_rm_command,
+               .help = "remove a directory or file",
+               .usage = "file_name",
        },
+
+       /*
+        * REVISIT shouldn't most, or all, these zylinjtag_*()
+        * entries be #ifdef ZY1000?  If not, why so they have
+        * those names?
+        *
+        * Peek and poke are security holes -- they manipulate
+        * server-internal addresses.
+        */
+
        // jim handlers
        {
                .name = "peek",
                .mode = COMMAND_ANY,
-               .jim_handler = &zylinjtag_Jim_Command_peek,
+               .jim_handler = zylinjtag_Jim_Command_peek,
                .help = "peek at a memory address",
-               .usage = "<addr>",
+               .usage = "address",
        },
        {
                .name = "poke",
                .mode = COMMAND_ANY,
-               .jim_handler = &zylinjtag_Jim_Command_poke,
+               .jim_handler = zylinjtag_Jim_Command_poke,
                .help = "poke at a memory address",
-               .usage = "<addr> <value>",
+               .usage = "address value",
        },
        {
                .name = "ls",
                .mode = COMMAND_ANY,
-               .jim_handler = &zylinjtag_Jim_Command_ls,
+               .jim_handler = zylinjtag_Jim_Command_ls,
                .help = "show a listing of files",
-               .usage = "<dir>",
+               .usage = "dirname",
        },
        {
                .name = "mac",
                .mode = COMMAND_ANY,
-               .jim_handler = &zylinjtag_Jim_Command_mac,
+               .jim_handler = zylinjtag_Jim_Command_mac,
                .help = "show MAC address",
        },
        {
                .name = "ip",
-               .jim_handler = &zylinjtag_Jim_Command_ip,
+               .jim_handler = zylinjtag_Jim_Command_ip,
                .mode = COMMAND_ANY,
                .help = "show IP address",
        },

diff --git a/src/helper/log.c b/src/helper/log.c
index 6adde4b9dc7f8575791241396b11160f0d45ac2d..7450fef50b1d4e1e664fbf074e144e0a55898a0b 100644 (file)
--- a/src/helper/log.c
+++ b/src/helper/log.c
@@ -286,13 +286,16 @@ COMMAND_HANDLER(handle_debug_level_command)
 
        if (debug_level >= LOG_LVL_DEBUG && server_use_pipes == 1)
        {
-               /* if we are enabling debug info then we need to write to a log file
-                * otherwise the pipe will get full and cause issues with gdb */
+               /* if we are enabling debug info then we need to write to a
+                * log file otherwise the pipe will get full and cause issues
+                * with gdb
+                */
                FILE* file = fopen("openocd.log", "w");
                if (file)
                {
                        log_output = file;
-                       LOG_WARNING("enabling log output as we are using pipes");
+                       LOG_WARNING("enabling logfile output because "
+                               "we are using pipes to talk to GDB.");
                }
        }
 
@@ -319,17 +322,19 @@ COMMAND_HANDLER(handle_log_output_command)
 static struct command_registration log_command_handlers[] = {
        {
                .name = "log_output",
-               .handler = &handle_log_output_command,
+               .handler = handle_log_output_command,
                .mode = COMMAND_ANY,
                .help = "redirect logging to a file (default: stderr)",
-               .usage = "<file_name>",
+               .usage = "file_name",
        },
        {
                .name = "debug_level",
-               .handler = &handle_debug_level_command,
+               .handler = handle_debug_level_command,
                .mode = COMMAND_ANY,
-               .help = "sets the verbosity level of debugging output",
-               .usage = "<level:0-3>",
+               .help = "Sets the verbosity level of debugging output. "
+                       "0 shows errors only; 1 adds warnings; "
+                       "2 (default) adds other info; 3 adds debugging.",
+               .usage = "number",
        },
        COMMAND_REGISTRATION_DONE
 };