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>

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 3f5882ceebbc66b6b142be0b46d0cdca685fc1cc..6057aad2c045d1efef1998b381244570677feba2 100644 (file)
--- 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 96accf3ec27b3f01ce2e7eb88b8fbf9d92b73c97..e490f2e546b8b3c809da91f2db8937a450707d6f 100644 (file)
--- 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 31538c2a854a1adb33bac1fe4b16d8786b55efc2..fe87fee45496fd78212e391ead900b2e340480ee 100644 (file)
--- 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 9d8132d43b665c635f6ad506f1f30c836f9a48de..233fb959cdf2e77a2bacff15e921412a0d5b8634 100644 (file)
--- 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 424263d0cbdb926e3b7dd7134454463314ec20d7..18edd95a9236cb0e1bda1e386cdaeeaa67945806 100644 (file)
--- 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 9685821977e0e97c6b622b98a992b6b5ebf6a34f..c6b1bb2d893df90ef4c20ee348b87f71ebc6c1b4 100644 (file)
--- 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
 };