ARMv7: 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.

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

Add a couple comments about things that should change:  those
extra TCK cycles for MEM-AP reads are in the wrong place (that
might explain some problems we've seen); the DAP command tables
should be shared, not copied.

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

6 files changed, 69 insertions, 41 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 3f5882ce..6057aad2 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -6198,26 +6198,28 @@ These commands are specific to ARM architecture v7 Debug Access Port (DAP),
 included on Cortex-M3 and Cortex-A8 systems.
 They are available in addition to other core-specific commands that may be available.
 
-@deffn Command {dap info} [num]
-Displays dap info for ap @var{num}, defaulting to the currently selected AP.
+@deffn Command {dap apid} [num]
+Displays ID register from AP @var{num},
+defaulting to the currently selected AP.
 @end deffn
 
 @deffn Command {dap apsel} [num]
 Select AP @var{num}, defaulting to 0.
 @end deffn
 
-@deffn Command {dap apid} [num]
-Displays id register from AP @var{num},
+@deffn Command {dap baseaddr} [num]
+Displays debug base address from MEM-AP @var{num},
 defaulting to the currently selected AP.
 @end deffn
 
-@deffn Command {dap baseaddr} [num]
-Displays debug base address from AP @var{num},
+@deffn Command {dap info} [num]
+Displays the ROM table for MEM-AP @var{num},
 defaulting to the currently selected AP.
 @end deffn
 
 @deffn Command {dap memaccess} [value]
-Displays the number of extra tck for mem-ap memory bus access [0-255].
+Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
+memory bus access [0-255], giving additional time to respond to reads.
 If @var{value} is defined, first assigns that.
 @end deffn
 
diff --git a/src/target/arm_adi_v5.c b/src/target/arm_adi_v5.c
index 96accf3e..e490f2e5 100644
--- a/src/target/arm_adi_v5.c
+++ b/src/target/arm_adi_v5.c
@@ -101,6 +101,10 @@ static int adi_jtag_dp_scan(struct swjdp_common *swjdp,
 	arm_jtag_set_instr(jtag_info, instr, NULL);
 
 	/* Add specified number of tck clocks before accessing memory bus */
+
+	/* REVISIT these TCK cycles should be *AFTER*  updating APACC, since
+	 * they provide more time for the (MEM) AP to complete the read ...
+	 */
 	if ((instr == JTAG_DP_APACC)
 			&& ((reg_addr == AP_REG_DRW)
 				|| ((reg_addr & 0xF0) == AP_REG_BD0))
@@ -137,6 +141,10 @@ static int adi_jtag_dp_scan_u32(struct swjdp_common *swjdp,
 	arm_jtag_set_instr(jtag_info, instr, NULL);
 
 	/* Add specified number of tck clocks before accessing memory bus */
+
+	/* REVISIT these TCK cycles should be *AFTER*  updating APACC, since
+	 * they provide more time for the (MEM) AP to complete the read ...
+	 */
 	if ((instr == JTAG_DP_APACC)
 			&& ((reg_addr == AP_REG_DRW)
 				|| ((reg_addr & 0xF0) == AP_REG_BD0))
diff --git a/src/target/armv7a.c b/src/target/armv7a.c
index 31538c2a..fe87fee4 100644
--- a/src/target/armv7a.c
+++ b/src/target/armv7a.c
@@ -174,40 +174,49 @@ COMMAND_HANDLER(handle_dap_info_command)
 	return dap_info_command(CMD_CTX, swjdp, apsel);
 }
 
+/* FIXME this table should be part of generic DAP support, and
+ * be shared by the ARMv7-A/R and ARMv7-M support ...
+ */
 static const struct command_registration armv7a_exec_command_handlers[] = {
 	{
 		.name = "info",
-		.handler = &handle_dap_info_command,
+		.handler = handle_dap_info_command,
 		.mode = COMMAND_EXEC,
-		.help = "dap info for ap [num], "
-			"default currently selected AP",
+		.help = "display ROM table for MEM-AP "
+			"(default currently selected AP)",
+		.usage = "[ap_num]",
 	},
 	{
 		.name = "apsel",
-		.handler = &handle_dap_apsel_command,
+		.handler = handle_dap_apsel_command,
 		.mode = COMMAND_EXEC,
-		.help = "select a different AP [num] (default 0)",
+		.help = "Set the currently selected AP (default 0) "
+			"and display the result",
+		.usage = "[ap_num]",
 	},
 	{
 		.name = "apid",
-		.handler = &handle_dap_apid_command,
+		.handler = handle_dap_apid_command,
 		.mode = COMMAND_EXEC,
-		.help = "return id reg from AP [num], "
-			"default currently selected AP",
+		.help = "return ID register from AP "
+			"(default currently selected AP)",
+		.usage = "[ap_num]",
 	},
 	{
 		.name = "baseaddr",
-		.handler = &handle_dap_baseaddr_command,
+		.handler = handle_dap_baseaddr_command,
 		.mode = COMMAND_EXEC,
-		.help = "return debug base address from AP [num], "
-			"default currently selected AP",
+		.help = "return debug base address from MEM-AP "
+			"(default currently selected AP)",
+		.usage = "[ap_num]",
 	},
 	{
 		.name = "memaccess",
-		.handler = &handle_dap_memaccess_command,
+		.handler = handle_dap_memaccess_command,
 		.mode = COMMAND_EXEC,
-		.help = "set/get number of extra tck for mem-ap memory "
+		.help = "set/get number of extra tck for MEM-AP memory "
 			"bus access [0-255]",
+		.usage = "[cycles]",
 	},
 	COMMAND_REGISTRATION_DONE
 };
diff --git a/src/target/armv7m.c b/src/target/armv7m.c
index 9d8132d4..233fb959 100644
--- a/src/target/armv7m.c
+++ b/src/target/armv7m.c
@@ -799,40 +799,49 @@ COMMAND_HANDLER(handle_dap_info_command)
 	return dap_info_command(CMD_CTX, swjdp, apsel);
 }
 
+/* FIXME this table should be part of generic DAP support, and
+ * be shared by the ARMv7-A/R and ARMv7-M support ...
+ */
 static const struct command_registration armv7m_exec_command_handlers[] = {
 	{
 		.name = "info",
-		.handler = &handle_dap_info_command,
+		.handler = handle_dap_info_command,
 		.mode = COMMAND_EXEC,
-		.help = "dap info for ap [num], "
-			"default currently selected AP",
+		.help = "display ROM table for MEM-AP "
+			"(default currently selected AP)",
+		.usage = "[ap_num]",
 	},
 	{
 		.name = "apsel",
-		.handler = &handle_dap_apsel_command,
+		.handler = handle_dap_apsel_command,
 		.mode = COMMAND_EXEC,
-		.help = "select a different AP [num] (default 0)",
+		.help = "Set the currently selected AP (default 0) "
+			"and display the result",
+		.usage = "[ap_num]",
 	},
 	{
 		.name = "apid",
-		.handler = &handle_dap_apid_command,
+		.handler = handle_dap_apid_command,
 		.mode = COMMAND_EXEC,
-		.help = "return id reg from AP [num], "
-			"default currently selected AP",
+		.help = "return ID register from AP "
+			"(default currently selected AP)",
+		.usage = "[ap_num]",
 	},
 	{
 		.name = "baseaddr",
-		.handler = &handle_dap_baseaddr_command,
+		.handler = handle_dap_baseaddr_command,
 		.mode = COMMAND_EXEC,
-		.help = "return debug base address from AP [num], "
-			"default currently selected AP",
+		.help = "return debug base address from MEM-AP "
+			"(default currently selected AP)",
+		.usage = "[ap_num]",
 	},
 	{
 		.name = "memaccess",
-		.handler = &handle_dap_memaccess_command,
+		.handler = handle_dap_memaccess_command,
 		.mode = COMMAND_EXEC,
-		.help = "set/get number of extra tck for mem-ap memory "
+		.help = "set/get number of extra tck for MEM-AP memory "
 			"bus access [0-255]",
+		.usage = "[cycles]",
 	},
 	COMMAND_REGISTRATION_DONE
 };
diff --git a/src/target/cortex_a8.c b/src/target/cortex_a8.c
index 424263d0..18edd95a 100644
--- a/src/target/cortex_a8.c
+++ b/src/target/cortex_a8.c
@@ -1642,13 +1642,13 @@ COMMAND_HANDLER(cortex_a8_handle_dbginit_command)
 static const struct command_registration cortex_a8_exec_command_handlers[] = {
 	{
 		.name = "cache_info",
-		.handler = &cortex_a8_handle_cache_info_command,
+		.handler = cortex_a8_handle_cache_info_command,
 		.mode = COMMAND_EXEC,
 		.help = "display information about target caches",
 	},
 	{
 		.name = "dbginit",
-		.handler = &cortex_a8_handle_dbginit_command,
+		.handler = cortex_a8_handle_dbginit_command,
 		.mode = COMMAND_EXEC,
 		.help = "Initialize core debug",
 	},
diff --git a/src/target/cortex_m3.c b/src/target/cortex_m3.c
index 96858219..c6b1bb2d 100644
--- a/src/target/cortex_m3.c
+++ b/src/target/cortex_m3.c
@@ -1989,24 +1989,24 @@ COMMAND_HANDLER(handle_cortex_m3_mask_interrupts_command)
 static const struct command_registration cortex_m3_exec_command_handlers[] = {
 	{
 		.name = "disassemble",
-		.handler = &handle_cortex_m3_disassemble_command,
+		.handler = handle_cortex_m3_disassemble_command,
 		.mode = COMMAND_EXEC,
 		.help = "disassemble Thumb2 instructions",
-		.usage = "<address> [<count>]",
+		.usage = "address [count]",
 	},
 	{
 		.name = "maskisr",
-		.handler = &handle_cortex_m3_mask_interrupts_command,
+		.handler = handle_cortex_m3_mask_interrupts_command,
 		.mode = COMMAND_EXEC,
 		.help = "mask cortex_m3 interrupts",
 		.usage = "['on'|'off']",
 	},
 	{
 		.name = "vector_catch",
-		.handler = &handle_cortex_m3_vector_catch_command,
+		.handler = handle_cortex_m3_vector_catch_command,
 		.mode = COMMAND_EXEC,
-		.help = "catch hardware vectors",
-		.usage = "['all'|'none'|<list>]",
+		.help = "configure hardware vectors to trigger debug entry",
+		.usage = "['all'|'none'|('bus_err'|'chk_err'|...)*]",
 	},
 	COMMAND_REGISTRATION_DONE
 };