From: David Brownell <dbrownell@users.sourceforge.net>
Date: Fri, 8 Jan 2010 00:21:10 +0000 (-0800)
Subject: ARM11: help/usage updates
X-Git-Tag: v0.4.0-rc2~131
X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=commitdiff_plain;h=199abf49ea02f03aedd1239b6ef3928d35f5dbb7

ARM11: help/usage updates

Usage syntax messages have the same EBNF as the User's Guide;
there should be no angle brackets in either place.

Uupdate some helptext to be more accurate.

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.

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

diff --git a/doc/openocd.texi b/doc/openocd.texi
index b91e75400f..a6fb970717 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -6162,27 +6162,29 @@ Without arguments, the current settings are displayed.
 @subsection ARM11 specific commands
 @cindex ARM11
 
-@deffn Command {arm11 memwrite burst} [value]
+@deffn Command {arm11 memwrite burst} [@option{enable}|@option{disable}]
 Displays the value of the memwrite burst-enable flag,
-which is enabled by default. Burst writes are only used
-for memory writes larger than 1 word. Single word writes
-are likely to be from reset init scripts and those writes
-are often to non-memory locations which could easily have
-many wait states, which could easily break burst writes.
-If @var{value} is defined, first assigns that.
+which is enabled by default.
+If a boolean parameter is provided, first assigns that flag.
+Burst writes are only used for memory writes larger than 1 word.
+They improve performance by assuming that the CPU has read each data
+word over JTAG and completed its write before the next word arrives,
+instead of polling for a status flag to verify that completion.
+This is usually safe, because JTAG runs much slower than the CPU.
 @end deffn
 
-@deffn Command {arm11 memwrite error_fatal} [value]
+@deffn Command {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
 Displays the value of the memwrite error_fatal flag,
 which is enabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that flag.
+When set, certain memory write errors cause earlier transfer termination.
 @end deffn
 
-@deffn Command {arm11 step_irq_enable}  [value]
+@deffn Command {arm11 step_irq_enable} [@option{enable}|@option{disable}]
 Displays the value of the flag controlling whether
 IRQs are enabled during single stepping;
 they are disabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that.
 @end deffn
 
 @deffn Command {arm11 vcr} [value]
diff --git a/src/target/arm11.c b/src/target/arm11.c
index 67a8409549..082930a906 100644
--- a/src/target/arm11.c
+++ b/src/target/arm11.c
@@ -1318,17 +1318,20 @@ COMMAND_HANDLER(arm11_handle_vcr)
 static const struct command_registration arm11_mw_command_handlers[] = {
 	{
 		.name = "burst",
-		.handler = &arm11_handle_bool_memwrite_burst,
+		.handler = arm11_handle_bool_memwrite_burst,
 		.mode = COMMAND_ANY,
-		.help = "Enable/Disable potentially risky fast burst mode"
-			" (default: enabled)",
+		.help = "Display or modify flag controlling potentially "
+			"risky fast burst mode (default: enabled)",
+		.usage = "['enable'|'disable']",
 	},
 	{
 		.name = "error_fatal",
-		.handler = &arm11_handle_bool_memwrite_error_fatal,
+		.handler = arm11_handle_bool_memwrite_error_fatal,
 		.mode = COMMAND_ANY,
-		.help = "Terminate program if transfer error was found"
+		.help = "Display or modify flag controlling transfer "
+			"termination on transfer errors"
 			" (default: enabled)",
+		.usage = "['enable'|'disable']",
 	},
 	COMMAND_REGISTRATION_DONE
 };
@@ -1338,11 +1341,11 @@ static const struct command_registration arm11_any_command_handlers[] = {
 		 * simulate + breakpoint implementation is broken.
 		 * TEMPORARY! NOT DOCUMENTED! */
 		.name = "hardware_step",
-		.handler = &arm11_handle_bool_hardware_step,
+		.handler = arm11_handle_bool_hardware_step,
 		.mode = COMMAND_ANY,
 		.help = "DEBUG ONLY - Hardware single stepping"
 			" (default: disabled)",
-		.usage = "(enable|disable)",
+		.usage = "['enable'|'disable']",
 	},
 	{
 		.name = "memwrite",
@@ -1352,16 +1355,18 @@ static const struct command_registration arm11_any_command_handlers[] = {
 	},
 	{
 		.name = "step_irq_enable",
-		.handler = &arm11_handle_bool_step_irq_enable,
+		.handler = arm11_handle_bool_step_irq_enable,
 		.mode = COMMAND_ANY,
-		.help = "Enable interrupts while stepping"
-			" (default: disabled)",
+		.help = "Display or modify flag controlling interrupt "
+			"enable while stepping (default: disabled)",
+		.usage = "['enable'|'disable']",
 	},
 	{
 		.name = "vcr",
-		.handler = &arm11_handle_vcr,
+		.handler = arm11_handle_vcr,
 		.mode = COMMAND_ANY,
-		.help = "Control (Interrupt) Vector Catch Register",
+		.help = "Display or modify Vector Catch Register",
+		.usage = "[value]",
 	},
 	COMMAND_REGISTRATION_DONE
 };