ARM7/ARM9: 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;
there should be no angle brackets in either place.

Fix the User's Guide in a few places to be more consistent (mostly
to use brackets not parentheses) and to recognize that parameter may
be entirely optional (in which case the command just displays output,
and changes nothing).  Also reference NXP, not Philips, for LPC chips.

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

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

2 files changed, 29 insertions, 19 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 6057aad2..b91e7540 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2501,7 +2501,7 @@ signal implementations.
 The default behaviour if no option given is @option{separate},
 indicating everything behaves normally.
 @option{srst_pulls_trst} states that the
-test logic is reset together with the reset of the system (e.g. Philips
+test logic is reset together with the reset of the system (e.g. NXP
 LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
 the system is reset together with the test logic (only hypothetical, I
 haven't seen hardware with such a bug, and can be worked around).
@@ -5867,26 +5867,36 @@ ARM9TDMI, ARM920T or ARM926EJ-S.
 They are available in addition to the ARM commands,
 and any other core-specific commands that may be available.
 
-@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
-Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
-instead of breakpoints.  This should be
-safe for all but ARM7TDMI--S cores (like Philips LPC).
+@deffn Command {arm7_9 dbgrq} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of the
+the EmbeddedIce DBGRQ signal to force entry into debug mode,
+instead of breakpoints.
+If a boolean parameter is provided, first assigns that flag.
+
+This should be
+safe for all but ARM7TDMI-S cores (like NXP LPC).
 This feature is enabled by default on most ARM9 cores,
 including ARM9TDMI, ARM920T, and ARM926EJ-S.
 @end deffn
 
-@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
+@deffn Command {arm7_9 dcc_downloads} [@option{enable}|@option{disable}]
 @cindex DCC
-Control the use of the debug communications channel (DCC) to write larger (>128 byte)
-amounts of memory. DCC downloads offer a huge speed increase, but might be
+Displays the value of the flag controlling use of the debug communications
+channel (DCC) to write larger (>128 byte) amounts of memory.
+If a boolean parameter is provided, first assigns that flag.
+
+DCC downloads offer a huge speed increase, but might be
 unsafe, especially with targets running at very low speeds. This command was introduced
 with OpenOCD rev. 60, and requires a few bytes of working area.
 @end deffn
 
 @anchor{arm7_9 fast_memory_access}
-@deffn Command {arm7_9 fast_memory_access} (@option{enable}|@option{disable})
-Enable or disable memory writes and reads that don't check completion of
-the operation. This provides a huge speed increase, especially with USB JTAG
+@deffn Command {arm7_9 fast_memory_access} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of memory writes and reads
+that don't check completion of the operation.
+If a boolean parameter is provided, first assigns that flag.
+
+This provides a huge speed increase, especially with USB JTAG
 cables (FT2232), but might be unsafe if used with targets running at very low
 speeds, like the 32kHz startup clock of an AT91RM9200.
 @end deffn
diff --git a/src/target/arm7_9_common.c b/src/target/arm7_9_common.c
index a09b0ad9..2f4c408c 100644
--- a/src/target/arm7_9_common.c
+++ b/src/target/arm7_9_common.c
@@ -2864,32 +2864,32 @@ int arm7_9_init_arch_info(struct target *target, struct arm7_9_common *arm7_9)
 static const struct command_registration arm7_9_any_command_handlers[] = {
 	{
 		"dbgrq",
-		.handler = &handle_arm7_9_dbgrq_command,
+		.handler = handle_arm7_9_dbgrq_command,
 		.mode = COMMAND_ANY,
-		.usage = "<enable|disable>",
+		.usage = "['enable'|'disable']",
 		.help = "use EmbeddedICE dbgrq instead of breakpoint "
 			"for target halt requests",
 	},
 	{
 		"fast_memory_access",
-		.handler = &handle_arm7_9_fast_memory_access_command,
+		.handler = handle_arm7_9_fast_memory_access_command,
 		.mode = COMMAND_ANY,
-		.usage = "<enable|disable>",
+		.usage = "['enable'|'disable']",
 		.help = "use fast memory accesses instead of slower "
 			"but potentially safer accesses",
 	},
 	{
 		"dcc_downloads",
-		.handler = &handle_arm7_9_dcc_downloads_command,
+		.handler = handle_arm7_9_dcc_downloads_command,
 		.mode = COMMAND_ANY,
-		.usage = "<enable | disable>",
+		.usage = "['enable'|'disable']",
 		.help = "use DCC downloads for larger memory writes",
 	},
 	{
 		"semihosting",
-		.handler = &handle_arm7_9_semihosting_command,
+		.handler = handle_arm7_9_semihosting_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<enable | disable>",
+		.usage = "['enable'|'disable']",
 		.help = "activate support for semihosting operations",
 	},
 	COMMAND_REGISTRATION_DONE