From: David Brownell Date: Sat, 9 Jan 2010 21:32:08 +0000 (-0800) Subject: src/helper: usage/help updates X-Git-Tag: v0.4.0-rc2~114 X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=commitdiff_plain;h=1dd5277ba3eb8c5938832b41c2bf6cb5bf19146e 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 --- diff --git a/src/helper/command.c b/src/helper/command.c index 0ddcd019c1..288ed72af4 100644 --- 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 miliseconds +/* sleep command sleeps for 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 = "[ ...]", + .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 = " ...", + .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 = " [...] ]", + .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 = " [...] ]", + .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 = " [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 = "[ ...]", + .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 = "[ ...]", + .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 27bffad336..14f6e91dbb 100644 --- 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= "", + .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= "", + .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 = " ", + .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= " [ ...]", + .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 = "", + .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 = "", + .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 = " ", + .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 = "", + .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 6adde4b9dc..7450fef50b 100644 --- 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 = "", + .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 = "", + .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 };