Added the options calc_checksum to the flash driver.
[fw/openocd] / src / target / arm7_9_common.c
index a9f06df0bae5e2f962463677d9cde19b9409bdb1..12ee62f94d887f88763dbf047893b0d6183628f8 100644 (file)
@@ -8,6 +8,9 @@
  *   Copyright (C) 2008 by Spencer Oliver                                  *
  *   spen@spen-soft.co.uk                                                  *
  *                                                                         *
+ *   Copyright (C) 2008 by Hongtao Zheng                                   *
+ *   hontor@126.com                                                        *
+ *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
  *   it under the terms of the GNU General Public License as published by  *
  *   the Free Software Foundation; either version 2 of the License, or     *
 #include "config.h"
 #endif
 
-#include "replacements.h"
-
 #include "embeddedice.h"
-#include "target.h"
 #include "target_request.h"
-#include "armv4_5.h"
-#include "arm_jtag.h"
-#include "jtag.h"
-#include "log.h"
 #include "arm7_9_common.h"
-#include "breakpoints.h"
 #include "time_support.h"
+#include "arm_simulator.h"
 
-#include <stdlib.h>
-#include <string.h>
-#include <unistd.h>
-
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <sys/time.h>
-#include <errno.h>
 
 int arm7_9_debug_entry(target_t *target);
 int arm7_9_enable_sw_bkpts(struct target_s *target);
@@ -62,7 +50,12 @@ int handle_arm7_9_fast_memory_access_command(struct command_context_s *cmd_ctx,
 int handle_arm7_9_dcc_downloads_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc);
 int handle_arm7_9_etm_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc);
 
-
+/**
+ * Clear watchpoints for an ARM7/9 target.
+ *
+ * @param arm7_9 Pointer to the common struct for an ARM7/9 target
+ * @return JTAG error status after executing queue
+ */
 static int arm7_9_clear_watchpoints(arm7_9_common_t *arm7_9)
 {
        embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_CONTROL_VALUE], 0x0);
@@ -75,7 +68,40 @@ static int arm7_9_clear_watchpoints(arm7_9_common_t *arm7_9)
        return jtag_execute_queue();
 }
 
-/* set up embedded ice registers */
+/**
+ * Assign a watchpoint to one of the two available hardware comparators in an
+ * ARM7 or ARM9 target.
+ *
+ * @param arm7_9 Pointer to the common struct for an ARM7/9 target
+ * @param breakpoint Pointer to the breakpoint to be used as a watchpoint
+ */
+static void arm7_9_assign_wp(arm7_9_common_t *arm7_9, breakpoint_t *breakpoint)
+{
+       if (!arm7_9->wp0_used)
+       {
+               arm7_9->wp0_used = 1;
+               breakpoint->set = 1;
+               arm7_9->wp_available--;
+       }
+       else if (!arm7_9->wp1_used)
+       {
+               arm7_9->wp1_used = 1;
+               breakpoint->set = 2;
+               arm7_9->wp_available--;
+       }
+       else
+       {
+               LOG_ERROR("BUG: no hardware comparator available");
+       }
+}
+
+/**
+ * Setup an ARM7/9 target's embedded ICE registers for software breakpoints.
+ *
+ * @param arm7_9 Pointer to common struct for ARM7/9 targets
+ * @return Error codes if there is a problem finding a watchpoint or the result
+ *         of executing the JTAG queue
+ */
 static int arm7_9_set_software_breakpoints(arm7_9_common_t *arm7_9)
 {
        if (arm7_9->sw_breakpoints_added)
@@ -130,7 +156,12 @@ static int arm7_9_set_software_breakpoints(arm7_9_common_t *arm7_9)
        return jtag_execute_queue();
 }
 
-/* set things up after a reset / on startup */
+/**
+ * Setup the common pieces for an ARM7/9 target after reset or on startup.
+ *
+ * @param target Pointer to an ARM7/9 target to setup
+ * @return Result of clearing the watchpoints on the target
+ */
 int arm7_9_setup(target_t *target)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -139,7 +170,18 @@ int arm7_9_setup(target_t *target)
        return arm7_9_clear_watchpoints(arm7_9);
 }
 
-
+/**
+ * Retrieves the architecture information pointers for ARMv4/5 and ARM7/9
+ * targets.  A return of ERROR_OK signifies that the target is a valid target
+ * and that the pointers have been set properly.
+ *
+ * @param target Pointer to the target device to get the pointers from
+ * @param armv4_5_p Pointer to be filled in with the common struct for ARMV4/5
+ *                  targets
+ * @param arm7_9_p Pointer to be filled in with the common struct for ARM7/9
+ *                 targets
+ * @return ERROR_OK if successful
+ */
 int arm7_9_get_arch_pointers(target_t *target, armv4_5_common_t **armv4_5_p, arm7_9_common_t **arm7_9_p)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -161,8 +203,16 @@ int arm7_9_get_arch_pointers(target_t *target, armv4_5_common_t **armv4_5_p, arm
        return ERROR_OK;
 }
 
-/* we set up the breakpoint even if it is already set. Some action, e.g. reset
- * might have erased the values in embedded ice
+/**
+ * Set either a hardware or software breakpoint on an ARM7/9 target.  The
+ * breakpoint is set up even if it is already set.  Some actions, e.g. reset,
+ * might have erased the values in Embedded ICE.
+ *
+ * @param target Pointer to the target device to set the breakpoints on
+ * @param breakpoint Pointer to the breakpoint to be set
+ * @return For hardware breakpoints, this is the result of executing the JTAG
+ *         queue.  For software breakpoints, this will be the status of the
+ *         required memory reads and writes
  */
 int arm7_9_set_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
 {
@@ -180,6 +230,13 @@ int arm7_9_set_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
        {
                /* either an ARM (4 byte) or Thumb (2 byte) breakpoint */
                u32 mask = (breakpoint->length == 4) ? 0x3u : 0x1u;
+
+               /* reassign a hw breakpoint */
+               if (breakpoint->set==0)
+               {
+                       arm7_9_assign_wp(arm7_9, breakpoint);
+               }
+
                if (breakpoint->set==1)
                {
                        embeddedice_set_reg(&arm7_9->eice_cache->reg_list[EICE_W0_ADDR_VALUE], breakpoint->address);
@@ -227,7 +284,7 @@ int arm7_9_set_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
                                return retval;
                        }
 
-                       if ((retval = target->type->read_memory(target, breakpoint->address, 4, 1, (u8 *)&verify)) != ERROR_OK)
+                       if ((retval = target_read_u32(target, breakpoint->address, &verify)) != ERROR_OK)
                        {
                                return retval;
                        }
@@ -251,7 +308,7 @@ int arm7_9_set_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
                                return retval;
                        }
 
-                       if ((retval = target->type->read_memory(target, breakpoint->address, 2, 1, (u8 *)&verify)) != ERROR_OK)
+                       if ((retval = target_read_u16(target, breakpoint->address, &verify)) != ERROR_OK)
                        {
                                return retval;
                        }
@@ -265,9 +322,20 @@ int arm7_9_set_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
        }
 
        return retval;
-
 }
 
+/**
+ * Unsets an existing breakpoint on an ARM7/9 target.  If it is a hardware
+ * breakpoint, the watchpoint used will be freed and the Embedded ICE registers
+ * will be updated.  Otherwise, the software breakpoint will be restored to its
+ * original instruction if it hasn't already been modified.
+ *
+ * @param target Pointer to ARM7/9 target to unset the breakpoint from
+ * @param breakpoint Pointer to breakpoint to be unset
+ * @return For hardware breakpoints, this is the result of executing the JTAG
+ *         queue.  For software breakpoints, this will be the status of the
+ *         required memory reads and writes
+ */
 int arm7_9_unset_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
 {
        int retval = ERROR_OK;
@@ -287,11 +355,13 @@ int arm7_9_unset_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
                {
                        embeddedice_set_reg(&arm7_9->eice_cache->reg_list[EICE_W0_CONTROL_VALUE], 0x0);
                        arm7_9->wp0_used = 0;
+                       arm7_9->wp_available++;
                }
                else if (breakpoint->set == 2)
                {
                        embeddedice_set_reg(&arm7_9->eice_cache->reg_list[EICE_W1_CONTROL_VALUE], 0x0);
                        arm7_9->wp1_used = 0;
+                       arm7_9->wp_available++;
                }
                retval = jtag_execute_queue();
                breakpoint->set = 0;
@@ -333,6 +403,15 @@ int arm7_9_unset_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
        return retval;
 }
 
+/**
+ * Add a breakpoint to an ARM7/9 target.  This makes sure that there are no
+ * dangling breakpoints and that the desired breakpoint can be added.
+ *
+ * @param target Pointer to the target ARM7/9 device to add a breakpoint to
+ * @param breakpoint Pointer to the breakpoint to be added
+ * @return An error status if there is a problem adding the breakpoint or the
+ *         result of setting the breakpoint
+ */
 int arm7_9_add_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -366,30 +445,24 @@ int arm7_9_add_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
 
        if (breakpoint->type == BKPT_HARD)
        {
-               arm7_9->wp_available--;
-
-               if (!arm7_9->wp0_used)
-               {
-                       arm7_9->wp0_used = 1;
-                       breakpoint->set = 1;
-               }
-               else if (!arm7_9->wp1_used)
-               {
-                       arm7_9->wp1_used = 1;
-                       breakpoint->set = 2;
-               }
-               else
-               {
-                       LOG_ERROR("BUG: no hardware comparator available");
-               }
+               arm7_9_assign_wp(arm7_9, breakpoint);
        }
 
-
        arm7_9->breakpoint_count++;
 
        return arm7_9_set_breakpoint(target, breakpoint);
 }
 
+/**
+ * Removes a breakpoint from an ARM7/9 target.  This will make sure there are no
+ * dangling breakpoints and updates available watchpoints if it is a hardware
+ * breakpoint.
+ *
+ * @param target Pointer to the target to have a breakpoint removed
+ * @param breakpoint Pointer to the breakpoint to be removed
+ * @return Error status if there was a problem unsetting the breakpoint or the
+ *         watchpoints could not be cleared
+ */
 int arm7_9_remove_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
 {
        int retval = ERROR_OK;
@@ -417,6 +490,16 @@ int arm7_9_remove_breakpoint(struct target_s *target, breakpoint_t *breakpoint)
        return ERROR_OK;
 }
 
+/**
+ * Sets a watchpoint for an ARM7/9 target in one of the watchpoint units.  It is
+ * considered a bug to call this function when there are no available watchpoint
+ * units.
+ *
+ * @param target Pointer to an ARM7/9 target to set a watchpoint on
+ * @param watchpoint Pointer to the watchpoint to be set
+ * @return Error status if watchpoint set fails or the result of executing the
+ *         JTAG queue
+ */
 int arm7_9_set_watchpoint(struct target_s *target, watchpoint_t *watchpoint)
 {
        int retval = ERROR_OK;
@@ -481,6 +564,14 @@ int arm7_9_set_watchpoint(struct target_s *target, watchpoint_t *watchpoint)
        return ERROR_OK;
 }
 
+/**
+ * Unset an existing watchpoint and clear the used watchpoint unit.
+ *
+ * @param target Pointer to the target to have the watchpoint removed
+ * @param watchpoint Pointer to the watchpoint to be removed
+ * @return Error status while trying to unset the watchpoint or the result of
+ *         executing the JTAG queue
+ */
 int arm7_9_unset_watchpoint(struct target_s *target, watchpoint_t *watchpoint)
 {
        int retval = ERROR_OK;
@@ -522,6 +613,14 @@ int arm7_9_unset_watchpoint(struct target_s *target, watchpoint_t *watchpoint)
        return ERROR_OK;
 }
 
+/**
+ * Add a watchpoint to an ARM7/9 target.  If there are no watchpoint units
+ * available, an error response is returned.
+ *
+ * @param target Pointer to the ARM7/9 target to add a watchpoint to
+ * @param watchpoint Pointer to the watchpoint to be added
+ * @return Error status while trying to add the watchpoint
+ */
 int arm7_9_add_watchpoint(struct target_s *target, watchpoint_t *watchpoint)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -548,6 +647,14 @@ int arm7_9_add_watchpoint(struct target_s *target, watchpoint_t *watchpoint)
        return ERROR_OK;
 }
 
+/**
+ * Remove a watchpoint from an ARM7/9 target.  The watchpoint will be unset and
+ * the used watchpoint unit will be reopened.
+ *
+ * @param target Pointer to the target to remove a watchpoint from
+ * @param watchpoint Pointer to the watchpoint to be removed
+ * @return Result of trying to unset the watchpoint
+ */
 int arm7_9_remove_watchpoint(struct target_s *target, watchpoint_t *watchpoint)
 {
        int retval = ERROR_OK;
@@ -567,9 +674,15 @@ int arm7_9_remove_watchpoint(struct target_s *target, watchpoint_t *watchpoint)
        return ERROR_OK;
 }
 
-
-
-
+/**
+ * Restarts the target by sending a RESTART instruction and moving the JTAG
+ * state to IDLE.  This includes a timeout waiting for DBGACK and SYSCOMP to be
+ * asserted by the processor.
+ *
+ * @param target Pointer to target to issue commands to
+ * @return Error status if there is a timeout or a problem while executing the
+ *         JTAG queue
+ */
 int arm7_9_execute_sys_speed(struct target_s *target)
 {
        int retval;
@@ -580,7 +693,7 @@ int arm7_9_execute_sys_speed(struct target_s *target)
        reg_t *dbg_stat = &arm7_9->eice_cache->reg_list[EICE_DBG_STAT];
 
        /* set RESTART instruction */
-       jtag_add_end_state(TAP_RTI);
+       jtag_add_end_state(TAP_IDLE);
        if (arm7_9->need_bypass_before_restart) {
                arm7_9->need_bypass_before_restart = 0;
                arm_jtag_set_instr(jtag_info, 0xf, NULL);
@@ -615,6 +728,14 @@ int arm7_9_execute_sys_speed(struct target_s *target)
        return ERROR_OK;
 }
 
+/**
+ * Restarts the target by sending a RESTART instruction and moving the JTAG
+ * state to IDLE.  This validates that DBGACK and SYSCOMP are set without
+ * waiting until they are.
+ *
+ * @param target Pointer to the target to issue commands to
+ * @return Always ERROR_OK
+ */
 int arm7_9_execute_fast_sys_speed(struct target_s *target)
 {
        static int set=0;
@@ -626,7 +747,7 @@ int arm7_9_execute_fast_sys_speed(struct target_s *target)
        reg_t *dbg_stat = &arm7_9->eice_cache->reg_list[EICE_DBG_STAT];
 
        /* set RESTART instruction */
-       jtag_add_end_state(TAP_RTI);
+       jtag_add_end_state(TAP_IDLE);
        if (arm7_9->need_bypass_before_restart) {
                arm7_9->need_bypass_before_restart = 0;
                arm_jtag_set_instr(jtag_info, 0xf, NULL);
@@ -638,32 +759,42 @@ int arm7_9_execute_fast_sys_speed(struct target_s *target)
                /* check for DBGACK and SYSCOMP set (others don't care) */
 
                /* NB! These are constants that must be available until after next jtag_execute() and
-                  we evaluate the values upon first execution in lieu of setting up these constants
-                  during early setup.
-               */
+                * we evaluate the values upon first execution in lieu of setting up these constants
+                * during early setup.
+                * */
                buf_set_u32(check_value, 0, 32, 0x9);
                buf_set_u32(check_mask, 0, 32, 0x9);
                set=1;
        }
 
        /* read debug status register */
-       embeddedice_read_reg_w_check(dbg_stat, check_value, check_value);
+       embeddedice_read_reg_w_check(dbg_stat, check_value, check_mask);
 
        return ERROR_OK;
 }
 
+/**
+ * Get some data from the ARM7/9 target.
+ *
+ * @param target Pointer to the ARM7/9 target to read data from
+ * @param size The number of 32bit words to be read
+ * @param buffer Pointer to the buffer that will hold the data
+ * @return The result of receiving data from the Embedded ICE unit
+ */
 int arm7_9_target_request_data(target_t *target, u32 size, u8 *buffer)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
        arm7_9_common_t *arm7_9 = armv4_5->arch_info;
        arm_jtag_t *jtag_info = &arm7_9->jtag_info;
        u32 *data;
-       int i, retval = ERROR_OK;
+       int retval = ERROR_OK;
+       u32 i;
 
        data = malloc(size * (sizeof(u32)));
 
        retval = embeddedice_receive(jtag_info, data, size);
 
+       /* return the 32-bit ints in the 8-bit array */
        for (i = 0; i < size; i++)
        {
                h_u32_to_le(buffer + (i * 4), data[i]);
@@ -674,6 +805,15 @@ int arm7_9_target_request_data(target_t *target, u32 size, u8 *buffer)
        return retval;
 }
 
+/**
+ * Handles requests to an ARM7/9 target.  If debug messaging is enabled, the
+ * target is running and the DCC control register has the W bit high, this will
+ * execute the request on the target.
+ *
+ * @param priv Void pointer expected to be a target_t pointer
+ * @return ERROR_OK unless there are issues with the JTAG queue or when reading
+ *                  from the Embedded ICE unit
+ */
 int arm7_9_handle_target_request(void *priv)
 {
        int retval = ERROR_OK;
@@ -685,7 +825,6 @@ int arm7_9_handle_target_request(void *priv)
        arm_jtag_t *jtag_info = &arm7_9->jtag_info;
        reg_t *dcc_control = &arm7_9->eice_cache->reg_list[EICE_COMMS_CTRL];
 
-
        if (!target->dbg_msg_enabled)
                return ERROR_OK;
 
@@ -717,6 +856,26 @@ int arm7_9_handle_target_request(void *priv)
        return ERROR_OK;
 }
 
+/**
+ * Polls an ARM7/9 target for its current status.  If DBGACK is set, the target
+ * is manipulated to the right halted state based on its current state.  This is
+ * what happens:
+ *
+ * <table>
+ *             <tr><th>State</th><th>Action</th></tr>
+ *             <tr><td>TARGET_RUNNING | TARGET_RESET</td><td>Enters debug mode.  If TARGET_RESET, pc may be checked</td></tr>
+ *             <tr><td>TARGET_UNKNOWN</td><td>Warning is logged</td></tr>
+ *             <tr><td>TARGET_DEBUG_RUNNING</td><td>Enters debug mode</td></tr>
+ *             <tr><td>TARGET_HALTED</td><td>Nothing</td></tr>
+ * </table>
+ *
+ * If the target does not end up in the halted state, a warning is produced.  If
+ * DBGACK is cleared, then the target is expected to either be running or
+ * running in debug.
+ *
+ * @param target Pointer to the ARM7/9 target to poll
+ * @return ERROR_OK or an error status if a command fails
+ */
 int arm7_9_poll(target_t *target)
 {
        int retval;
@@ -786,7 +945,7 @@ int arm7_9_poll(target_t *target)
                }
                if (target->state != TARGET_HALTED)
                {
-                       LOG_WARNING("DBGACK set, but the target did not end up in the halted stated %d", target->state);
+                       LOG_WARNING("DBGACK set, but the target did not end up in the halted state %d", target->state);
                }
        }
        else
@@ -798,14 +957,17 @@ int arm7_9_poll(target_t *target)
        return ERROR_OK;
 }
 
-/*
-  Some -S targets (ARM966E-S in the STR912 isn't affected, ARM926EJ-S
-  in the LPC3180 and AT91SAM9260 is affected) completely stop the JTAG clock
-  while the core is held in reset(SRST). It isn't possible to program the halt
-  condition once reset was asserted, hence a hook that allows the target to set
-  up its reset-halt condition prior to asserting reset.
-*/
-
+/**
+ * Asserts the reset (SRST) on an ARM7/9 target.  Some -S targets (ARM966E-S in
+ * the STR912 isn't affected, ARM926EJ-S in the LPC3180 and AT91SAM9260 is
+ * affected) completely stop the JTAG clock while the core is held in reset
+ * (SRST).  It isn't possible to program the halt condition once reset is
+ * asserted, hence a hook that allows the target to set up its reset-halt
+ * condition is setup prior to asserting reset.
+ *
+ * @param target Pointer to an ARM7/9 target to assert reset on
+ * @return ERROR_FAIL if the JTAG device does not have SRST, otherwise ERROR_OK
+ */
 int arm7_9_assert_reset(target_t *target)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -844,7 +1006,7 @@ int arm7_9_assert_reset(target_t *target)
                }
        }
 
-       /* here we should issue a srst only, but we may have to assert trst as well */
+       /* here we should issue an SRST only, but we may have to assert TRST as well */
        if (jtag_reset_config & RESET_SRST_PULLS_TRST)
        {
                jtag_add_reset(1, 1);
@@ -853,28 +1015,34 @@ int arm7_9_assert_reset(target_t *target)
                jtag_add_reset(0, 1);
        }
 
-
        target->state = TARGET_RESET;
        jtag_add_sleep(50000);
 
        armv4_5_invalidate_core_regs(target);
 
-    if ((target->reset_halt)&&((jtag_reset_config & RESET_SRST_PULLS_TRST)==0))
+       if ((target->reset_halt)&&((jtag_reset_config & RESET_SRST_PULLS_TRST)==0))
        {
                /* debug entry was already prepared in arm7_9_assert_reset() */
                target->debug_reason = DBG_REASON_DBGRQ;
        }
 
        return ERROR_OK;
-
 }
 
+/**
+ * Deassert the reset (SRST) signal on an ARM7/9 target.  If SRST pulls TRST
+ * and the target is being reset into a halt, a warning will be triggered
+ * because it is not possible to reset into a halted mode in this case.  The
+ * target is halted using the target's functions.
+ *
+ * @param target Pointer to the target to have the reset deasserted
+ * @return ERROR_OK or an error from polling or halting the target
+ */
 int arm7_9_deassert_reset(target_t *target)
 {
        int retval=ERROR_OK;
        LOG_DEBUG("target->state: %s",
-                 Jim_Nvp_value2name_simple( nvp_target_state,target->state)->name);
-
+               Jim_Nvp_value2name_simple( nvp_target_state,target->state)->name);
 
        /* deassert reset lines */
        jtag_add_reset(0, 0);
@@ -900,6 +1068,15 @@ int arm7_9_deassert_reset(target_t *target)
        return retval;
 }
 
+/**
+ * Clears the halt condition for an ARM7/9 target.  If it isn't coming out of
+ * reset and if DBGRQ is used, it is progammed to be deasserted.  If the reset
+ * vector catch was used, it is restored.  Otherwise, the control value is
+ * restored and the watchpoint unit is restored if it was in use.
+ *
+ * @param target Pointer to the ARM7/9 target to have halt cleared
+ * @return Always ERROR_OK
+ */
 int arm7_9_clear_halt(target_t *target)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -948,6 +1125,16 @@ int arm7_9_clear_halt(target_t *target)
        return ERROR_OK;
 }
 
+/**
+ * Issue a software reset and halt to an ARM7/9 target.  The target is halted
+ * and then there is a wait until the processor shows the halt.  This wait can
+ * timeout and results in an error being returned.  The software reset involves
+ * clearing the halt, updating the debug control register, changing to ARM mode,
+ * reset of the program counter, and reset of all of the registers.
+ *
+ * @param target Pointer to the ARM7/9 target to be reset and halted by software
+ * @return Error status if any of the commands fail, otherwise ERROR_OK
+ */
 int arm7_9_soft_reset_halt(struct target_s *target)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -1045,6 +1232,15 @@ int arm7_9_soft_reset_halt(struct target_s *target)
        return ERROR_OK;
 }
 
+/**
+ * Halt an ARM7/9 target.  This is accomplished by either asserting the DBGRQ
+ * line or by programming a watchpoint to trigger on any address.  It is
+ * considered a bug to call this function while the target is in the
+ * TARGET_RESET state.
+ *
+ * @param target Pointer to the ARM7/9 target to be halted
+ * @return Always ERROR_OK
+ */
 int arm7_9_halt(target_t *target)
 {
        if (target->state==TARGET_RESET)
@@ -1097,6 +1293,17 @@ int arm7_9_halt(target_t *target)
        return ERROR_OK;
 }
 
+/**
+ * Handle an ARM7/9 target's entry into debug mode.  The halt is cleared on the
+ * ARM.  The JTAG queue is then executed and the reason for debug entry is
+ * examined.  Once done, the target is verified to be halted and the processor
+ * is forced into ARM mode.  The core registers are saved for the current core
+ * mode and the program counter (register 15) is updated as needed.  The core
+ * registers and CPSR and SPSR are saved for restoration later.
+ *
+ * @param target Pointer to target that is entering debug mode
+ * @return Error code if anything fails, otherwise ERROR_OK
+ */
 int arm7_9_debug_entry(target_t *target)
 {
        int i;
@@ -1258,6 +1465,15 @@ int arm7_9_debug_entry(target_t *target)
        return ERROR_OK;
 }
 
+/**
+ * Validate the full context for an ARM7/9 target in all processor modes.  If
+ * there are any invalid registers for the target, they will all be read.  This
+ * includes the PSR.
+ *
+ * @param target Pointer to the ARM7/9 target to capture the full context from
+ * @return Error if the target is not halted, has an invalid core mode, or if
+ *         the JTAG queue fails to execute
+ */
 int arm7_9_full_context(target_t *target)
 {
        int i;
@@ -1279,7 +1495,7 @@ int arm7_9_full_context(target_t *target)
        /* iterate through processor modes (User, FIQ, IRQ, SVC, ABT, UND)
         * SYS shares registers with User, so we don't touch SYS
         */
-       for(i = 0; i < 6; i++)
+       for (i = 0; i < 6; i++)
        {
                u32 mask = 0;
                u32* reg_p[16];
@@ -1339,6 +1555,18 @@ int arm7_9_full_context(target_t *target)
        return ERROR_OK;
 }
 
+/**
+ * Restore the processor context on an ARM7/9 target.  The full processor
+ * context is analyzed to see if any of the registers are dirty on this end, but
+ * have a valid new value.  If this is the case, the processor is changed to the
+ * appropriate mode and the new register values are written out to the
+ * processor.  If there happens to be a dirty register with an invalid value, an
+ * error will be logged.
+ *
+ * @param target Pointer to the ARM7/9 target to have its context restored
+ * @return Error status if the target is not halted or the core mode in the
+ *         armv4_5 struct is invalid.
+ */
 int arm7_9_restore_context(target_t *target)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -1481,6 +1709,14 @@ int arm7_9_restore_context(target_t *target)
        return ERROR_OK;
 }
 
+/**
+ * Restart the core of an ARM7/9 target.  A RESTART command is sent to the
+ * instruction register and the JTAG state is set to TAP_IDLE causing a core
+ * restart.
+ *
+ * @param target Pointer to the ARM7/9 target to be restarted
+ * @return Result of executing the JTAG queue
+ */
 int arm7_9_restart_core(struct target_s *target)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -1488,17 +1724,23 @@ int arm7_9_restart_core(struct target_s *target)
        arm_jtag_t *jtag_info = &arm7_9->jtag_info;
 
        /* set RESTART instruction */
-       jtag_add_end_state(TAP_RTI);
+       jtag_add_end_state(TAP_IDLE);
        if (arm7_9->need_bypass_before_restart) {
                arm7_9->need_bypass_before_restart = 0;
                arm_jtag_set_instr(jtag_info, 0xf, NULL);
        }
        arm_jtag_set_instr(jtag_info, 0x4, NULL);
 
-       jtag_add_runtest(1, TAP_RTI);
+       jtag_add_runtest(1, TAP_IDLE);
        return jtag_execute_queue();
 }
 
+/**
+ * Enable the watchpoints on an ARM7/9 target.  The target's watchpoints are
+ * iterated through and are set on the target if they aren't already set.
+ *
+ * @param target Pointer to the ARM7/9 target to enable watchpoints on
+ */
 void arm7_9_enable_watchpoints(struct target_s *target)
 {
        watchpoint_t *watchpoint = target->watchpoints;
@@ -1511,6 +1753,12 @@ void arm7_9_enable_watchpoints(struct target_s *target)
        }
 }
 
+/**
+ * Enable the breakpoints on an ARM7/9 target.  The target's breakpoints are
+ * iterated through and are set on the target.
+ *
+ * @param target Pointer to the ARM7/9 target to enable breakpoints on
+ */
 void arm7_9_enable_breakpoints(struct target_s *target)
 {
        breakpoint_t *breakpoint = target->breakpoints;
@@ -1523,7 +1771,6 @@ void arm7_9_enable_breakpoints(struct target_s *target)
        }
 }
 
-
 int arm7_9_resume(struct target_s *target, int current, u32 address, int handle_breakpoints, int debug_execution)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
@@ -1549,6 +1796,9 @@ int arm7_9_resume(struct target_s *target, int current, u32 address, int handle_
        if (!current)
                buf_set_u32(armv4_5->core_cache->reg_list[15].value, 0, 32, address);
 
+       u32 current_pc;
+       current_pc = buf_get_u32(armv4_5->core_cache->reg_list[15].value, 0, 32);
+
        /* the front-end may request us not to handle breakpoints */
        if (handle_breakpoints)
        {
@@ -1560,8 +1810,18 @@ int arm7_9_resume(struct target_s *target, int current, u32 address, int handle_
                                return retval;
                        }
 
+                       /* calculate PC of next instruction */
+                       u32 next_pc;
+                       if ((retval = arm_simulate_step(target, &next_pc)) != ERROR_OK)
+                       {
+                               u32 current_opcode;
+                               target_read_u32(target, current_pc, &current_opcode);
+                               LOG_ERROR("BUG: couldn't calculate PC of next instruction, current opcode was 0x%8.8x", current_opcode);
+                               return retval;
+                       }
+
                        LOG_DEBUG("enable single-step");
-                       arm7_9->enable_single_step(target);
+                       arm7_9->enable_single_step(target, next_pc);
 
                        target->debug_reason = DBG_REASON_SINGLESTEP;
 
@@ -1671,24 +1931,42 @@ int arm7_9_resume(struct target_s *target, int current, u32 address, int handle_
        return ERROR_OK;
 }
 
-void arm7_9_enable_eice_step(target_t *target)
+void arm7_9_enable_eice_step(target_t *target, u32 next_pc)
 {
        armv4_5_common_t *armv4_5 = target->arch_info;
        arm7_9_common_t *arm7_9 = armv4_5->arch_info;
 
-       /* setup an inverse breakpoint on the current PC
-       * - comparator 1 matches the current address
-       * - rangeout from comparator 1 is connected to comparator 0 rangein
-       * - comparator 0 matches any address, as long as rangein is low */
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_ADDR_MASK], 0xffffffff);
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_DATA_MASK], 0xffffffff);
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_CONTROL_VALUE], EICE_W_CTRL_ENABLE);
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_CONTROL_MASK], ~(EICE_W_CTRL_RANGE|EICE_W_CTRL_nOPC) & 0xff);
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_ADDR_VALUE], buf_get_u32(armv4_5->core_cache->reg_list[15].value, 0, 32));
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_ADDR_MASK], 0);
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_DATA_MASK], 0xffffffff);
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_CONTROL_VALUE], 0x0);
-       embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_CONTROL_MASK], ~EICE_W_CTRL_nOPC & 0xff);
+       u32 current_pc;
+       current_pc = buf_get_u32(armv4_5->core_cache->reg_list[15].value, 0, 32);
+
+       if(next_pc != current_pc)
+       {
+               /* setup an inverse breakpoint on the current PC
+               * - comparator 1 matches the current address
+               * - rangeout from comparator 1 is connected to comparator 0 rangein
+               * - comparator 0 matches any address, as long as rangein is low */
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_ADDR_MASK], 0xffffffff);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_DATA_MASK], 0xffffffff);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_CONTROL_VALUE], EICE_W_CTRL_ENABLE);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_CONTROL_MASK], ~(EICE_W_CTRL_RANGE|EICE_W_CTRL_nOPC) & 0xff);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_ADDR_VALUE], current_pc);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_ADDR_MASK], 0);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_DATA_MASK], 0xffffffff);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_CONTROL_VALUE], 0x0);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_CONTROL_MASK], ~EICE_W_CTRL_nOPC & 0xff);
+       }
+       else
+       {
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_ADDR_MASK], 0xffffffff);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_DATA_MASK], 0xffffffff);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_CONTROL_VALUE], 0x0);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W0_CONTROL_MASK], 0xff);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_ADDR_VALUE], next_pc);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_ADDR_MASK], 0);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_DATA_MASK], 0xffffffff);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_CONTROL_VALUE], EICE_W_CTRL_ENABLE);
+               embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_W1_CONTROL_MASK], ~EICE_W_CTRL_nOPC & 0xff);
+       }
 }
 
 void arm7_9_disable_eice_step(target_t *target)
@@ -1724,6 +2002,9 @@ int arm7_9_step(struct target_s *target, int current, u32 address, int handle_br
        if (!current)
                buf_set_u32(armv4_5->core_cache->reg_list[15].value, 0, 32, address);
 
+       u32 current_pc;
+       current_pc = buf_get_u32(armv4_5->core_cache->reg_list[15].value, 0, 32);
+
        /* the front-end may request us not to handle breakpoints */
        if (handle_breakpoints)
                if ((breakpoint = breakpoint_find(target, buf_get_u32(armv4_5->core_cache->reg_list[15].value, 0, 32))))
@@ -1734,12 +2015,22 @@ int arm7_9_step(struct target_s *target, int current, u32 address, int handle_br
 
        target->debug_reason = DBG_REASON_SINGLESTEP;
 
+       /* calculate PC of next instruction */
+       u32 next_pc;
+       if ((retval = arm_simulate_step(target, &next_pc)) != ERROR_OK)
+       {
+               u32 current_opcode;
+               target_read_u32(target, current_pc, &current_opcode);
+               LOG_ERROR("BUG: couldn't calculate PC of next instruction, current opcode was 0x%8.8x", current_opcode);
+               return retval;
+       }
+
        if ((retval = arm7_9_restore_context(target)) != ERROR_OK)
        {
                return retval;
        }
 
-       arm7_9->enable_single_step(target);
+       arm7_9->enable_single_step(target, next_pc);
 
        if (armv4_5->core_state == ARMV4_5_STATE_ARM)
        {
@@ -1785,7 +2076,6 @@ int arm7_9_step(struct target_s *target, int current, u32 address, int handle_br
                }
 
        return err;
-
 }
 
 int arm7_9_read_core_reg(struct target_s *target, int num, enum armv4_5_mode mode)
@@ -1852,7 +2142,6 @@ int arm7_9_read_core_reg(struct target_s *target, int num, enum armv4_5_mode mod
        }
 
        return ERROR_OK;
-
 }
 
 int arm7_9_write_core_reg(struct target_s *target, int num, enum armv4_5_mode mode, u32 value)
@@ -1922,7 +2211,7 @@ int arm7_9_read_memory(struct target_s *target, u32 address, u32 size, u32 count
        arm7_9_common_t *arm7_9 = armv4_5->arch_info;
 
        u32 reg[16];
-       int num_accesses = 0;
+       u32 num_accesses = 0;
        int thisrun_accesses;
        int i;
        u32 cpsr;
@@ -1968,9 +2257,11 @@ int arm7_9_read_memory(struct target_s *target, u32 address, u32 size, u32 count
                                 * from a sufficiently high clock (32 kHz is usually too slow)
                                 */
                                if (arm7_9->fast_memory_access)
-                                       arm7_9_execute_fast_sys_speed(target);
+                                       retval = arm7_9_execute_fast_sys_speed(target);
                                else
-                                       arm7_9_execute_sys_speed(target);
+                                       retval = arm7_9_execute_sys_speed(target);
+                               if (retval != ERROR_OK)
+                                       return retval;
 
                                arm7_9->read_core_regs_target_buffer(target, reg_list, buffer, 4);
 
@@ -2097,7 +2388,7 @@ int arm7_9_write_memory(struct target_s *target, u32 address, u32 size, u32 coun
        reg_t *dbg_ctrl = &arm7_9->eice_cache->reg_list[EICE_DBG_CTRL];
 
        u32 reg[16];
-       int num_accesses = 0;
+       u32 num_accesses = 0;
        int thisrun_accesses;
        int i;
        u32 cpsr;
@@ -2276,7 +2567,6 @@ int arm7_9_write_memory(struct target_s *target, u32 address, u32 size, u32 coun
 static int dcc_count;
 static u8 *dcc_buffer;
 
-
 static int arm7_9_dcc_completion(struct target_s *target, u32 exit_point, int timeout_ms, void *arch_info)
 {
        int retval = ERROR_OK;
@@ -2292,16 +2582,16 @@ static int arm7_9_dcc_completion(struct target_s *target, u32 exit_point, int ti
        if (count>2)
        {
                /* Handle first & last using standard embeddedice_write_reg and the middle ones w/the
-                  core function repeated.
-                */
+                * core function repeated. */
                embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_COMMS_DATA], fast_target_buffer_get_u32(buffer, little));
                buffer+=4;
 
                embeddedice_reg_t *ice_reg = arm7_9->eice_cache->reg_list[EICE_COMMS_DATA].arch_info;
                u8 reg_addr = ice_reg->addr & 0x1f;
-               int chain_pos = ice_reg->jtag_info->chain_pos;
+               jtag_tap_t *tap;
+               tap = ice_reg->jtag_info->tap;
 
-               embeddedice_write_dcc(chain_pos, reg_addr, buffer, little, count-2);
+               embeddedice_write_dcc(tap, reg_addr, buffer, little, count-2);
                buffer += (count-2)*4;
 
                embeddedice_write_reg(&arm7_9->eice_cache->reg_list[EICE_COMMS_DATA], fast_target_buffer_get_u32(buffer, little));
@@ -2322,7 +2612,6 @@ static int arm7_9_dcc_completion(struct target_s *target, u32 exit_point, int ti
        return target_wait_state(target, TARGET_HALTED, 500);
 }
 
-
 static const u32 dcc_code[] =
 {
        /* MRC      TST         BNE         MRC         STR         B */
@@ -2331,7 +2620,6 @@ static const u32 dcc_code[] =
 
 int armv4_5_run_algorithm_inner(struct target_s *target, int num_mem_params, mem_param_t *mem_params, int num_reg_params, reg_param_t *reg_params, u32 entry_point, u32 exit_point, int timeout_ms, void *arch_info, int (*run_it)(struct target_s *target, u32 exit_point, int timeout_ms, void *arch_info));
 
-
 int arm7_9_bulk_write_memory(target_t *target, u32 address, u32 count, u8 *buffer)
 {
        int retval;
@@ -2378,8 +2666,6 @@ int arm7_9_bulk_write_memory(target_t *target, u32 address, u32 count, u8 *buffe
 
        buf_set_u32(reg_params[0].value, 0, 32, address);
 
-       //armv4_5_run_algorithm_inner(struct target_s *target, int num_mem_params, mem_param_t *mem_params,
-       // int num_reg_params, reg_param_t *reg_params, u32 entry_point, u32 exit_point, int timeout_ms, void *arch_info, int (*run_it)(struct target_s *target, u32 exit_point, int timeout_ms, void *arch_info))
        dcc_count=count;
        dcc_buffer=buffer;
        retval = armv4_5_run_algorithm_inner(target, 0, NULL, 1, reg_params,
@@ -2435,7 +2721,7 @@ int arm7_9_checksum_memory(struct target_s *target, u32 address, u32 count, u32*
                0x04C11DB7                              /* CRC32XOR:    .word 0x04C11DB7 */
        };
 
-       int i;
+       u32 i;
 
        if (target_alloc_working_area(target, sizeof(arm7_9_crc_code), &crc_algorithm) != ERROR_OK)
        {
@@ -2487,7 +2773,7 @@ int arm7_9_blank_check_memory(struct target_s *target, u32 address, u32 count, u
        reg_param_t reg_params[3];
        armv4_5_algorithm_t armv4_5_info;
        int retval;
-       int i;
+       u32 i;
 
        u32 erase_check_code[] =
        {
@@ -2560,10 +2846,8 @@ int arm7_9_register_commands(struct command_context_s *cmd_ctx)
 
        register_command(cmd_ctx, arm7_9_cmd, "dbgrq", handle_arm7_9_dbgrq_command,
                COMMAND_ANY, "use EmbeddedICE dbgrq instead of breakpoint for target halt requests <enable|disable>");
-       register_command(cmd_ctx, arm7_9_cmd, "fast_writes", handle_arm7_9_fast_memory_access_command,
-                COMMAND_ANY, "(deprecated, see: arm7_9 fast_memory_access)");
        register_command(cmd_ctx, arm7_9_cmd, "fast_memory_access", handle_arm7_9_fast_memory_access_command,
-                COMMAND_ANY, "use fast memory accesses instead of slower but potentially unsafe slow accesses <enable|disable>");
+                COMMAND_ANY, "use fast memory accesses instead of slower but potentially safer accesses <enable|disable>");
        register_command(cmd_ctx, arm7_9_cmd, "dcc_downloads", handle_arm7_9_dcc_downloads_command,
                COMMAND_ANY, "use DCC downloads for larger memory writes <enable|disable>");
 
@@ -2692,10 +2976,8 @@ int handle_arm7_9_write_core_reg_command(struct command_context_s *cmd_ctx, char
        value = strtoul(args[2], NULL, 0);
 
        return arm7_9_write_core_reg(target, num, mode, value);
-
 }
 
-
 int handle_arm7_9_dbgrq_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
 {
        target_t *target = get_current_target(cmd_ctx);