From ebd3f88798902be229d00f95ece5ba250db8efba Mon Sep 17 00:00:00 2001 From: zwelch Date: Fri, 22 May 2009 02:27:30 +0000 Subject: [PATCH] Submitted by Dean Glazeski : Add doxygen comments in arm7_9_common source and header files. git-svn-id: svn://svn.berlios.de/openocd/trunk@1880 b42882b7-edfa-0310-969c-e2dbd0fdcd60 --- src/target/arm7_9_common.c | 150 ++++++++++++++++++++++++++++++++++--- src/target/arm7_9_common.h | 61 ++++++++------- 2 files changed, 172 insertions(+), 39 deletions(-) diff --git a/src/target/arm7_9_common.c b/src/target/arm7_9_common.c index 707dfdc82..12ee62f94 100644 --- a/src/target/arm7_9_common.c +++ b/src/target/arm7_9_common.c @@ -773,6 +773,14 @@ int arm7_9_execute_fast_sys_speed(struct target_s *target) 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; @@ -786,6 +794,7 @@ int arm7_9_target_request_data(target_t *target, u32 size, u8 *buffer) 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]); @@ -796,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; @@ -838,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: + * + * + * + * + * + * + * + *
StateAction
TARGET_RUNNING | TARGET_RESETEnters debug mode. If TARGET_RESET, pc may be checked
TARGET_UNKNOWNWarning is logged
TARGET_DEBUG_RUNNINGEnters debug mode
TARGET_HALTEDNothing
+ * + * 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; @@ -907,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 @@ -919,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; @@ -965,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); @@ -988,6 +1029,15 @@ int arm7_9_assert_reset(target_t *target) 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; @@ -1018,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; @@ -1066,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; @@ -1163,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) @@ -1215,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; @@ -1376,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; @@ -1457,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; @@ -1599,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; @@ -1617,6 +1735,12 @@ int arm7_9_restart_core(struct target_s *target) 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; @@ -1629,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; diff --git a/src/target/arm7_9_common.h b/src/target/arm7_9_common.h index 04e29e058..5eba205f6 100644 --- a/src/target/arm7_9_common.h +++ b/src/target/arm7_9_common.h @@ -32,52 +32,55 @@ #include "breakpoints.h" #include "etm.h" -#define ARM7_9_COMMON_MAGIC 0x0a790a79 +#define ARM7_9_COMMON_MAGIC 0x0a790a79 /**< */ +/** + * Structure for items that are common between both ARM7 and ARM9 targets. + */ typedef struct arm7_9_common_s { u32 common_magic; - arm_jtag_t jtag_info; - reg_cache_t *eice_cache; + arm_jtag_t jtag_info; /**< JTAG information for target */ + reg_cache_t *eice_cache; /**< Embedded ICE register cache */ - u32 arm_bkpt; - u16 thumb_bkpt; - int sw_breakpoints_added; - int breakpoint_count; - int wp_available; - int wp_available_max; - int wp0_used; - int wp1_used; - int wp1_used_default; + u32 arm_bkpt; /**< ARM breakpoint instruction */ + u16 thumb_bkpt; /**< Thumb breakpoint instruction */ + int sw_breakpoints_added; /**< Specifies which watchpoint software breakpoints are setup on */ + int breakpoint_count; /**< Current number of set breakpoints */ + int wp_available; /**< Current number of available watchpoint units */ + int wp_available_max; /**< Maximum number of available watchpoint units */ + int wp0_used; /**< Specifies if and how watchpoint unit 0 is used */ + int wp1_used; /**< Specifies if and how watchpoint unit 1 is used */ + int wp1_used_default; /**< Specifies if and how watchpoint unit 1 is used by default */ int force_hw_bkpts; - int dbgreq_adjust_pc; - int use_dbgrq; - int need_bypass_before_restart; + int dbgreq_adjust_pc; /**< Amount of PC adjustment caused by a DBGREQ */ + int use_dbgrq; /**< Specifies if DBGRQ should be used to halt the target */ + int need_bypass_before_restart; /**< Specifies if there should be a bypass before a JTAG restart */ etm_context_t *etm_ctx; int has_single_step; int has_monitor_mode; - int has_vector_catch; + int has_vector_catch; /**< Specifies if the target has a reset vector catch */ - int debug_entry_from_reset; + int debug_entry_from_reset; /**< Specifies if debug entry was from a reset */ struct working_area_s *dcc_working_area; int fast_memory_access; int dcc_downloads; - int (*examine_debug_reason)(target_t *target); + int (*examine_debug_reason)(target_t *target); /**< Function for determining why debug state was entered */ - void (*change_to_arm)(target_t *target, u32 *r0, u32 *pc); + void (*change_to_arm)(target_t *target, u32 *r0, u32 *pc); /**< Function for changing from Thumb to ARM mode */ - void (*read_core_regs)(target_t *target, u32 mask, u32 *core_regs[16]); + void (*read_core_regs)(target_t *target, u32 mask, u32 *core_regs[16]); /**< Function for reading the core registers */ void (*read_core_regs_target_buffer)(target_t *target, u32 mask, void *buffer, int size); - void (*read_xpsr)(target_t *target, u32 *xpsr, int spsr); + void (*read_xpsr)(target_t *target, u32 *xpsr, int spsr); /**< Function for reading CPSR or SPSR */ - void (*write_xpsr)(target_t *target, u32 xpsr, int spsr); - void (*write_xpsr_im8)(target_t *target, u8 xpsr_im, int rot, int spsr); + void (*write_xpsr)(target_t *target, u32 xpsr, int spsr); /**< Function for writing to CPSR or SPSR */ + void (*write_xpsr_im8)(target_t *target, u8 xpsr_im, int rot, int spsr); /**< Function for writing an immediate value to CPSR or SPSR */ void (*write_core_regs)(target_t *target, u32 mask, u32 core_regs[16]); void (*load_word_regs)(target_t *target, u32 mask); @@ -88,20 +91,20 @@ typedef struct arm7_9_common_s void (*store_hword_reg)(target_t *target, int num); void (*store_byte_reg)(target_t *target, int num); - void (*write_pc)(target_t *target, u32 pc); + void (*write_pc)(target_t *target, u32 pc); /**< Function for writing to the program counter */ void (*branch_resume)(target_t *target); void (*branch_resume_thumb)(target_t *target); void (*enable_single_step)(target_t *target, u32 next_pc); void (*disable_single_step)(target_t *target); - void (*set_special_dbgrq)(target_t *target); + void (*set_special_dbgrq)(target_t *target); /**< Function for setting DBGRQ if the normal way won't work */ - void (*pre_debug_entry)(target_t *target); - void (*post_debug_entry)(target_t *target); + void (*pre_debug_entry)(target_t *target); /**< Callback function called before entering debug mode */ + void (*post_debug_entry)(target_t *target); /**< Callback function called after entering debug mode */ - void (*pre_restore_context)(target_t *target); - void (*post_restore_context)(target_t *target); + void (*pre_restore_context)(target_t *target); /**< Callback function called before restoring the processor context */ + void (*post_restore_context)(target_t *target); /**< Callback function called after restoring the processor context */ armv4_5_common_t armv4_5_common; void *arch_info;