target misc: help/usage updates

Provide helptext which was sometimes missing; update some of it
to be more accurate.

Usage syntax messages have the same EBNF as the User's Guide.

Don't use "&function"; functions are like arrays, their address
is their name.  Shrink some overlong lines; remove some empties.

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

3 files changed, 164 insertions, 131 deletions

diff --git a/src/target/target.c b/src/target/target.c
index 73a762d4..c29c45e4 100644
--- a/src/target/target.c
+++ b/src/target/target.c
@@ -45,8 +45,10 @@
 #include "image.h"
 
 
-static int target_array2mem(Jim_Interp *interp, struct target *target, int argc, Jim_Obj *const *argv);
-static int target_mem2array(Jim_Interp *interp, struct target *target, int argc, Jim_Obj *const *argv);
+static int target_array2mem(Jim_Interp *interp, struct target *target,
+		int argc, Jim_Obj *const *argv);
+static int target_mem2array(Jim_Interp *interp, struct target *target,
+		int argc, Jim_Obj *const *argv);
 
 /* targets */
 extern struct target_type arm7tdmi_target;
@@ -2960,7 +2962,8 @@ static void writeGmon(uint32_t *samples, uint32_t sampleNum, const char *filenam
 	fclose(f);
 }
 
-/* profiling samples the CPU PC as quickly as OpenOCD is able, which will be used as a random sampling of PC */
+/* profiling samples the CPU PC as quickly as OpenOCD is able,
+ * which will be used as a random sampling of PC */
 COMMAND_HANDLER(handle_profile_command)
 {
 	struct target *target = get_current_target(CMD_CTX);
@@ -2976,6 +2979,12 @@ COMMAND_HANDLER(handle_profile_command)
 
 	timeval_add_time(&timeout, offset, 0);
 
+	/**
+	 * @todo: Some cores let us sample the PC without the
+	 * annoying halt/resume step; for example, ARMv7 PCSR.
+	 * Provide a way to use that more efficient mechanism.
+	 */
+
 	command_print(CMD_CTX, "Starting profiling. Halting and resuming the target as often as we can...");
 
 	static const int maxSample = 10000;
@@ -3287,7 +3296,9 @@ static int jim_array2mem(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
 
 	return target_array2mem(interp,target, argc-1, argv + 1);
 }
-static int target_array2mem(Jim_Interp *interp, struct target *target, int argc, Jim_Obj *const *argv)
+
+static int target_array2mem(Jim_Interp *interp, struct target *target,
+		int argc, Jim_Obj *const *argv)
 {
 	long l;
 	uint32_t width;
@@ -3789,11 +3800,13 @@ static int target_configure(Jim_GetOptInfo *goi, struct target *target)
 	return JIM_OK;
 }
 
-static int jim_target_configure(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
+static int
+jim_target_configure(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
 {
 	Jim_GetOptInfo goi;
+
 	Jim_GetOpt_Setup(&goi, interp, argc - 1, argv + 1);
-	goi.isconfigure = strcmp(Jim_GetString(argv[0], NULL), "configure") == 0;
+	goi.isconfigure = !strcmp(Jim_GetString(argv[0], NULL), "configure");
 	int need_args = 1 + goi.isconfigure;
 	if (goi.argc < need_args)
 	{
@@ -3988,13 +4001,15 @@ static int jim_target_md(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
 	return JIM_OK;
 }
 
-static int jim_target_mem2array(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
+static int jim_target_mem2array(Jim_Interp *interp,
+		int argc, Jim_Obj *const *argv)
 {
 	struct target *target = Jim_CmdPrivData(interp);
 	return target_mem2array(interp, target, argc - 1, argv + 1);
 }
 
-static int jim_target_array2mem(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
+static int jim_target_array2mem(Jim_Interp *interp,
+		int argc, Jim_Obj *const *argv)
 {
 	struct target *target = Jim_CmdPrivData(interp);
 	return target_array2mem(interp, target, argc - 1, argv + 1);
@@ -4219,108 +4234,123 @@ static const struct command_registration target_instance_command_handlers[] = {
 	{
 		.name = "configure",
 		.mode = COMMAND_CONFIG,
-		.jim_handler = &jim_target_configure,
-		.usage = "[<target_options> ...]",
+		.jim_handler = jim_target_configure,
 		.help  = "configure a new target for use",
+		.usage = "[target_attribute ...]",
 	},
 	{
 		.name = "cget",
 		.mode = COMMAND_ANY,
-		.jim_handler = &jim_target_configure,
-		.usage = "<target_type> [<target_options> ...]",
-		.help  = "configure a new target for use",
+		.jim_handler = jim_target_configure,
+		.help  = "returns the specified target attribute",
+		.usage = "target_attribute",
 	},
 	{
 		.name = "mww",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_mw,
-		.usage = "<address> <data> [<count>]",
+		.jim_handler = jim_target_mw,
 		.help = "Write 32-bit word(s) to target memory",
+		.usage = "address data [count]",
 	},
 	{
 		.name = "mwh",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_mw,
-		.usage = "<address> <data> [<count>]",
+		.jim_handler = jim_target_mw,
 		.help = "Write 16-bit half-word(s) to target memory",
+		.usage = "address data [count]",
 	},
 	{
 		.name = "mwb",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_mw,
-		.usage = "<address> <data> [<count>]",
+		.jim_handler = jim_target_mw,
 		.help = "Write byte(s) to target memory",
+		.usage = "address data [count]",
 	},
 	{
 		.name = "mdw",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_md,
-		.usage = "<address> [<count>]",
+		.jim_handler = jim_target_md,
 		.help = "Display target memory as 32-bit words",
+		.usage = "address [count]",
 	},
 	{
 		.name = "mdh",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_md,
-		.usage = "<address> [<count>]",
+		.jim_handler = jim_target_md,
 		.help = "Display target memory as 16-bit half-words",
+		.usage = "address [count]",
 	},
 	{
 		.name = "mdb",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_md,
-		.usage = "<address> [<count>]",
+		.jim_handler = jim_target_md,
 		.help = "Display target memory as 8-bit bytes",
+		.usage = "address [count]",
 	},
 	{
 		.name = "array2mem",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_array2mem,
+		.jim_handler = jim_target_array2mem,
+		.help = "Writes Tcl array of 8/16/32 bit numbers "
+			"to target memory",
+		.usage = "arrayname bitwidth address count",
 	},
 	{
 		.name = "mem2array",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_mem2array,
+		.jim_handler = jim_target_mem2array,
+		.help = "Loads Tcl array of 8/16/32 bit numbers "
+			"from target memory",
+		.usage = "arrayname bitwidth address count",
 	},
 	{
 		.name = "eventlist",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_event_list,
+		.jim_handler = jim_target_event_list,
+		.help = "displays a table of events defined for this target",
 	},
 	{
 		.name = "curstate",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_current_state,
+		.jim_handler = jim_target_current_state,
+		.help = "displays the current state of this target",
 	},
 	{
 		.name = "arp_examine",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_examine,
+		.jim_handler = jim_target_examine,
+		.help = "used internally for reset processing",
 	},
 	{
 		.name = "arp_poll",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_poll,
+		.jim_handler = jim_target_poll,
+		.help = "used internally for reset processing",
 	},
 	{
 		.name = "arp_reset",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_reset,
+		.jim_handler = jim_target_reset,
+		.help = "used internally for reset processing",
 	},
 	{
 		.name = "arp_halt",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_halt,
+		.jim_handler = jim_target_halt,
+		.help = "used internally for reset processing",
 	},
 	{
 		.name = "arp_waitstate",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_wait_state,
+		.jim_handler = jim_target_wait_state,
+		.help = "used internally for reset processing",
 	},
 	{
 		.name = "invoke-event",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_target_invoke_event,
+		.jim_handler = jim_target_invoke_event,
+		.help = "invoke handler for specified event",
+		.usage = "event_name",
 	},
 	COMMAND_REGISTRATION_DONE
 };
@@ -4472,7 +4502,7 @@ static int target_create(Jim_GetOptInfo *goi)
 		}
 		*tpp = target;
 	}
-	
+
 	/* now - create the new target name command */
 	const const struct command_registration target_subcommands[] = {
 		{
@@ -4615,51 +4645,54 @@ static const struct command_registration target_subcommand_handlers[] = {
 	{
 		.name = "init",
 		.mode = COMMAND_CONFIG,
-		.handler = &handle_target_init_command,
+		.handler = handle_target_init_command,
 		.help = "initialize targets",
 	},
 	{
 		.name = "create",
+		/* REVISIT this should be COMMAND_CONFIG ... */
 		.mode = COMMAND_ANY,
-		.jim_handler = &jim_target_create,
-		.usage = "<name> <type> ...",
-		.help = "Returns the currently selected target",
+		.jim_handler = jim_target_create,
+		.usage = "name type '-chain-position' name [options ...]",
+		.help = "Creates and selects a new target",
 	},
 	{
 		.name = "current",
 		.mode = COMMAND_ANY,
-		.jim_handler = &jim_target_current,
+		.jim_handler = jim_target_current,
 		.help = "Returns the currently selected target",
 	},
 	{
 		.name = "types",
 		.mode = COMMAND_ANY,
-		.jim_handler = &jim_target_types,
-		.help = "Returns the available target types as a list of strings",
+		.jim_handler = jim_target_types,
+		.help = "Returns the available target types as "
+				"a list of strings",
 	},
 	{
 		.name = "names",
 		.mode = COMMAND_ANY,
-		.jim_handler = &jim_target_names,
+		.jim_handler = jim_target_names,
 		.help = "Returns the names of all targets as a list of strings",
 	},
 	{
 		.name = "number",
 		.mode = COMMAND_ANY,
-		.jim_handler = &jim_target_number,
-		.usage = "<number>",
-		.help = "Returns the name of target <n>",
+		.jim_handler = jim_target_number,
+		.usage = "number",
+		.help = "Returns the name of the numbered target "
+			"(DEPRECATED)",
 	},
 	{
 		.name = "count",
 		.mode = COMMAND_ANY,
-		.jim_handler = &jim_target_count,
-		.help = "Returns the number of targets as an integer",
+		.jim_handler = jim_target_count,
+		.help = "Returns the number of targets as an integer "
+			"(DEPRECATED)",
 	},
 	COMMAND_REGISTRATION_DONE
 };
 
-
 struct FastLoad
 {
 	uint32_t address;
@@ -4833,11 +4866,11 @@ COMMAND_HANDLER(handle_fast_load_command)
 static const struct command_registration target_command_handlers[] = {
 	{
 		.name = "targets",
-		.handler = &handle_targets_command,
+		.handler = handle_targets_command,
 		.mode = COMMAND_ANY,
-		.help = "change current command line target (one parameter) "
-			"or list targets (no parameters)",
-		.usage = "[<new_current_target>]",
+		.help = "change current default target (one parameter) "
+			"or prints table of all targets (no parameters)",
+		.usage = "[target]",
 	},
 	{
 		.name = "target",
@@ -4857,69 +4890,75 @@ int target_register_commands(struct command_context *cmd_ctx)
 static const struct command_registration target_exec_command_handlers[] = {
 	{
 		.name = "fast_load_image",
-		.handler = &handle_fast_load_image_command,
+		.handler = handle_fast_load_image_command,
 		.mode = COMMAND_ANY,
-		.help = "Load image into memory, mainly for profiling purposes",
-		.usage = "<file> <address> ['bin'|'ihex'|'elf'|'s19'] "
-			"[min_address] [max_length]",
+		.help = "Load image into server memory for later use by "
+			"fast_load; primarily for profiling",
+		.usage = "filename address ['bin'|'ihex'|'elf'|'s19'] "
+			"[min_address [max_length]]",
 	},
 	{
 		.name = "fast_load",
-		.handler = &handle_fast_load_command,
+		.handler = handle_fast_load_command,
 		.mode = COMMAND_EXEC,
 		.help = "loads active fast load image to current target "
 			"- mainly for profiling purposes",
 	},
 	{
 		.name = "profile",
-		.handler = &handle_profile_command,
+		.handler = handle_profile_command,
 		.mode = COMMAND_EXEC,
 		.help = "profiling samples the CPU PC",
 	},
 	/** @todo don't register virt2phys() unless target supports it */
 	{
 		.name = "virt2phys",
-		.handler = &handle_virt2phys_command,
+		.handler = handle_virt2phys_command,
 		.mode = COMMAND_ANY,
 		.help = "translate a virtual address into a physical address",
+		.usage = "virual_address",
 	},
-
 	{
 		.name = "reg",
-		.handler = &handle_reg_command,
+		.handler = handle_reg_command,
 		.mode = COMMAND_EXEC,
-		.help = "display or set a register",
+		.help = "display or set a register; with no arguments, "
+			"displays all registers and their values",
+		.usage = "[(register_name|register_number) [value]]",
 	},
-
 	{
 		.name = "poll",
-		.handler = &handle_poll_command,
+		.handler = handle_poll_command,
 		.mode = COMMAND_EXEC,
-		.help = "poll target state",
+		.help = "poll target state; or reconfigure background polling",
+		.usage = "['on'|'off']",
 	},
 	{
 		.name = "wait_halt",
-		.handler = &handle_wait_halt_command,
+		.handler = handle_wait_halt_command,
 		.mode = COMMAND_EXEC,
-		.help = "wait for target halt",
-		.usage = "[time (s)]",
+		.help = "wait up to the specified number of milliseconds "
+			"(default 5) for a previously requested halt",
+		.usage = "[milliseconds]",
 	},
 	{
 		.name = "halt",
-		.handler = &handle_halt_command,
+		.handler = handle_halt_command,
 		.mode = COMMAND_EXEC,
-		.help = "halt target",
+		.help = "request target to halt, then wait up to the specified"
+			"number of milliseconds (default 5) for it to complete",
+		.usage = "[milliseconds]",
 	},
 	{
 		.name = "resume",
-		.handler = &handle_resume_command,
+		.handler = handle_resume_command,
 		.mode = COMMAND_EXEC,
-		.help = "resume target",
-		.usage = "[<address>]",
+		.help =	"resume target execution from current PC or address",
+		.usage = "[address]",
 	},
 	{
 		.name = "reset",
-		.handler = &handle_reset_command,
+		.handler = handle_reset_command,
 		.mode = COMMAND_EXEC,
 		.usage = "[run|halt|init]",
 		.help = "Reset all targets into the specified mode."
@@ -4927,133 +4966,127 @@ static const struct command_registration target_exec_command_handlers[] = {
 	},
 	{
 		.name = "soft_reset_halt",
-		.handler = &handle_soft_reset_halt_command,
+		.handler = handle_soft_reset_halt_command,
 		.mode = COMMAND_EXEC,
 		.help = "halt the target and do a soft reset",
 	},
 	{
-
 		.name = "step",
-		.handler = &handle_step_command,
+		.handler = handle_step_command,
 		.mode = COMMAND_EXEC,
-		.help =	"step one instruction from current PC or [addr]",
-		.usage = "[<address>]",
+		.help =	"step one instruction from current PC or address",
+		.usage = "[address]",
 	},
 	{
-
 		.name = "mdw",
-		.handler = &handle_md_command,
+		.handler = handle_md_command,
 		.mode = COMMAND_EXEC,
 		.help = "display memory words",
-		.usage = "[phys] <addr> [count]",
+		.usage = "['phys'] address [count]",
 	},
 	{
 		.name = "mdh",
-		.handler = &handle_md_command,
+		.handler = handle_md_command,
 		.mode = COMMAND_EXEC,
 		.help = "display memory half-words",
-		.usage = "[phys] <addr> [count]",
+		.usage = "['phys'] address [count]",
 	},
 	{
 		.name = "mdb",
-		.handler = &handle_md_command,
+		.handler = handle_md_command,
 		.mode = COMMAND_EXEC,
 		.help = "display memory bytes",
-		.usage = "[phys] <addr> [count]",
+		.usage = "['phys'] address [count]",
 	},
 	{
-
 		.name = "mww",
-		.handler = &handle_mw_command,
+		.handler = handle_mw_command,
 		.mode = COMMAND_EXEC,
 		.help = "write memory word",
-		.usage = "[phys]  <addr> <value> [count]",
+		.usage = "['phys'] address value [count]",
 	},
 	{
 		.name = "mwh",
-		.handler = &handle_mw_command,
+		.handler = handle_mw_command,
 		.mode = COMMAND_EXEC,
 		.help = "write memory half-word",
-		.usage = "[phys] <addr> <value> [count]",
+		.usage = "['phys'] address value [count]",
 	},
 	{
 		.name = "mwb",
-		.handler = &handle_mw_command,
+		.handler = handle_mw_command,
 		.mode = COMMAND_EXEC,
 		.help = "write memory byte",
-		.usage = "[phys] <addr> <value> [count]",
+		.usage = "['phys'] address value [count]",
 	},
 	{
-
 		.name = "bp",
-		.handler = &handle_bp_command,
+		.handler = handle_bp_command,
 		.mode = COMMAND_EXEC,
-		.help = "list or set breakpoint",
-		.usage = "[<address> <length> [hw]]",
+		.help = "list or set hardware or software breakpoint",
+		.usage = "[address length ['hw']]",
 	},
 	{
 		.name = "rbp",
-		.handler = &handle_rbp_command,
+		.handler = handle_rbp_command,
 		.mode = COMMAND_EXEC,
 		.help = "remove breakpoint",
-		.usage = "<address>",
+		.usage = "address",
 	},
 	{
-
 		.name = "wp",
-		.handler = &handle_wp_command,
+		.handler = handle_wp_command,
 		.mode = COMMAND_EXEC,
-		.help = "list or set watchpoint",
-		.usage = "[<address> <length> <r/w/a> [value] [mask]]",
+		.help = "list (no params) or create watchpoints",
+		.usage = "[address length [('r'|'w'|'a') value [mask]]]",
 	},
 	{
 		.name = "rwp",
-		.handler = &handle_rwp_command,
+		.handler = handle_rwp_command,
 		.mode = COMMAND_EXEC,
 		.help = "remove watchpoint",
-		.usage = "<address>",
-
+		.usage = "address",
 	},
 	{
 		.name = "load_image",
-		.handler = &handle_load_image_command,
+		.handler = handle_load_image_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<file> <address> ['bin'|'ihex'|'elf'|'s19'] "
+		.usage = "filename address ['bin'|'ihex'|'elf'|'s19'] "
 			"[min_address] [max_length]",
 	},
 	{
 		.name = "dump_image",
-		.handler = &handle_dump_image_command,
+		.handler = handle_dump_image_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<file> <address> <size>",
+		.usage = "filename address size",
 	},
 	{
 		.name = "verify_image",
-		.handler = &handle_verify_image_command,
+		.handler = handle_verify_image_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<file> [offset] [type]",
+		.usage = "filename [offset [type]]",
 	},
 	{
 		.name = "test_image",
-		.handler = &handle_test_image_command,
+		.handler = handle_test_image_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<file> [offset] [type]",
+		.usage = "filename [offset [type]]",
 	},
 	{
 		.name = "ocd_mem2array",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_mem2array,
-		.help = "read memory and return as a TCL array "
+		.jim_handler = jim_mem2array,
+		.help = "read 8/16/32 bit memory and return as a TCL array "
 			"for script processing",
-		.usage = "<arrayname> <width=32|16|8> <address> <count>",
+		.usage = "arrayname bitwidth address count",
 	},
 	{
 		.name = "ocd_array2mem",
 		.mode = COMMAND_EXEC,
-		.jim_handler = &jim_array2mem,
+		.jim_handler = jim_array2mem,
 		.help = "convert a TCL array to memory locations "
-			"and write the values",
-		.usage = "<arrayname> <width=32|16|8> <address> <count>",
+			"and write the 8/16/32 bit values",
+		.usage = "arrayname bitwidth address count",
 	},
 	COMMAND_REGISTRATION_DONE
 };
diff --git a/src/target/target_request.c b/src/target/target_request.c
index d22b8a2b..ec3d48e2 100644
--- a/src/target/target_request.c
+++ b/src/target/target_request.c
@@ -303,10 +303,10 @@ COMMAND_HANDLER(handle_target_request_debugmsgs_command)
 static const struct command_registration target_req_exec_command_handlers[] = {
 	{
 		.name = "debugmsgs",
-		.handler = &handle_target_request_debugmsgs_command,
+		.handler = handle_target_request_debugmsgs_command,
 		.mode = COMMAND_EXEC,
-		.help = "set reception of debug messages from target",
-		.usage = "(enable|disable)",
+		.help = "display and/or modify reception of debug messages from target",
+		.usage = "['enable'|'charmsg'|'disable']",
 	},
 	COMMAND_REGISTRATION_DONE
 };
diff --git a/src/target/trace.c b/src/target/trace.c
index 56a18a4f..a8ec143e 100644
--- a/src/target/trace.c
+++ b/src/target/trace.c
@@ -159,18 +159,18 @@ COMMAND_HANDLER(handle_trace_history_command)
 static const struct command_registration trace_exec_command_handlers[] = {
 	{
 		.name = "history",
-		.handler = &handle_trace_history_command,
+		.handler = handle_trace_history_command,
 		.mode = COMMAND_EXEC,
-		.help = "display trace history, clear history or set [size]",
-		.usage = "[clear|<size>]",
+		.help = "display trace history, clear history or set size",
+		.usage = "['clear'|size]",
 	},
 	{
 		.name = "point",
-		.handler = &handle_trace_point_command,
+		.handler = handle_trace_point_command,
 		.mode = COMMAND_EXEC,
 		.help = "display trace points, clear list of trace points, "
-			"or add new tracepoint at [address]",
-		.usage = "[clear|<address>]",
+			"or add new tracepoint at address",
+		.usage = "['clear'|address]",
 	},
 	COMMAND_REGISTRATION_DONE
 };