target: make "examined" flag be per-target

Previously this flag was stored in "target_type", so that for example
if there were two ARM7TDMI targets in a scan chain, both would claim
to have been examined although only the first one actually had its
examine() method called.

Move this state to where it should have been in the first place, and
hide a method that didn't need exposure ... the flag is write-once.

Provide some doxygen.  The examine() method is confusing, since it
isn't separating one-time setup from the after-each-reset stuff.  And
the ARM7/ARM9 version is, somewhat undesirably, not leaving the debug
state alone after reset ... probably more of an issue for trace setup
than for watchpoints and breakpoints.

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

5 files changed, 53 insertions, 44 deletions

diff --git a/src/target/arm11.c b/src/target/arm11.c
index 7a30bc7f..a88d597d 100644
--- a/src/target/arm11.c
+++ b/src/target/arm11.c
@@ -1906,12 +1906,6 @@ static int arm11_examine(struct target *target)
 		retval = etm_setup(target);
 	}
 
-	/* FIXME this sets a flag in the (shared) arm11_target structure,
-	 * not in the (per-cpu) "target" structure ... so it's clearly
-	 * wrong in the case of e.g. two different ARM11 chips on the
-	 * same board.  (Maybe ARM11 MPCore works though.)  Whoever calls
-	 * the examine() method should set a target-specific flag...
-	 */
 	target_set_examined(target);
 
 	return ERROR_OK;
diff --git a/src/target/cortex_a8.c b/src/target/cortex_a8.c
index 730cd33e..da5e84be 100644
--- a/src/target/cortex_a8.c
+++ b/src/target/cortex_a8.c
@@ -1297,11 +1297,11 @@ static int cortex_a8_dcc_read(struct swjdp_common *swjdp, uint8_t *value, uint8_
 static int cortex_a8_handle_target_request(void *priv)
 {
 	struct target *target = priv;
-	if (!target->type->examined)
-		return ERROR_OK;
 	struct armv7a_common *armv7a = target_to_armv7a(target);
 	struct swjdp_common *swjdp = &armv7a->swjdp_info;
 
+	if (!target_was_examined(target))
+		return ERROR_OK;
 	if (!target->dbg_msg_enabled)
 		return ERROR_OK;
 
@@ -1424,7 +1424,7 @@ static int cortex_a8_examine(struct target *target)
 	/* Configure core debug access */
 	cortex_a8_init_debug_access(target);
 
-	target->type->examined = 1;
+	target_set_examined(target);
 
 	return retval;
 }
diff --git a/src/target/target.c b/src/target/target.c
index 2385d0f6..f7e2ad64 100644
--- a/src/target/target.c
+++ b/src/target/target.c
@@ -644,20 +644,13 @@ int target_run_algorithm(struct target *target,
 			entry_point, exit_point, timeout_ms, arch_info);
 }
 
-/// @returns @c true if the target has been examined.
-bool target_was_examined(struct target *target)
-{
-	return target->type->examined;
-}
-/// Sets the @c examined flag for the given target.
-void target_set_examined(struct target *target)
-{
-	target->type->examined = true;
-}
-// Reset the @c examined flag for the given target.
-void target_reset_examined(struct target *target)
+/**
+ * Reset the @c examined flag for the given target.
+ * Pure paranoia -- targets are zeroed on allocation.
+ */
+static void target_reset_examined(struct target *target)
 {
-	target->type->examined = false;
+	target->examined = false;
 }
 
 
diff --git a/src/target/target.h b/src/target/target.h
index 914d62fd..e4de2c7c 100644
--- a/src/target/target.h
+++ b/src/target/target.h
@@ -129,7 +129,16 @@ struct target
 	const char *cmd_name;				/* tcl Name of target */
 	int target_number;					/* DO NOT USE!  field to be removed in 2010 */
 	struct jtag_tap *tap;					/* where on the jtag chain is this */
-	const char *variant;				/* what varient of this chip is it? */
+	const char *variant;				/* what variant of this chip is it? */
+
+	/**
+	 * Indicates whether this target has been examined.
+	 *
+	 * Do @b not access this field directly, use target_was_examined()
+	 * or target_set_examined().
+	 */
+	bool examined;
+
 	struct target_event_action *event_action;
 
 	int reset_halt;						/* attempt resetting the CPU into the halted mode? */
@@ -289,18 +298,25 @@ struct target *get_target(const char *id);
 const char *target_get_name(struct target *target);
 
 /**
- * Examine the specified @a target.
+ * Examine the specified @a target, letting it perform any
+ * initialization that requires JTAG access.
  *
  * This routine is a wrapper for target->type->examine.
  */
 int target_examine_one(struct target *target);
-/// @returns @c true if the target has been examined.
-bool target_was_examined(struct target *target);
-/// Sets the @c examined flag for the given target.
-void target_set_examined(struct target *target);
-/// Reset the @c examined flag for the given target.
-void target_reset_examined(struct target *target);
 
+/// @returns @c true if target_set_examined() has been called.
+static inline bool target_was_examined(struct target *target)
+{
+	return target->examined;
+}
+
+/// Sets the @c examined flag for the given target.
+/// Use in target->type->examine() after one-time setup is done.
+static inline void target_set_examined(struct target *target)
+{
+	target->examined = true;
+}
 
 /**
  * Add the @a breakpoint for @a target.
diff --git a/src/target/target_type.h b/src/target/target_type.h
index f601b191..aa87a744 100644
--- a/src/target/target_type.h
+++ b/src/target/target_type.h
@@ -30,22 +30,19 @@
 
 struct target;
 
+/**
+ * This holds methods shared between all instances of a given target
+ * type.  For example, all Cortex-M3 targets on a scan chain share
+ * the same method table.
+ */
 struct target_type
 {
 	/**
-	 * Name of the target.  Do @b not access this field directly, use
-	 * target_get_name() instead.
+	 * Name of this type of target.  Do @b not access this
+	 * field directly, use target_get_name() instead.
 	 */
 	char *name;
 
-	/**
-	 * Indicates whether this target has been examined.
-	 *
-	 * Do @b not access this field directly, use target_was_examined()
-	 * target_set_examined(), and target_reset_examined().
-	 */
-	int examined;
-
 	/* poll current target status */
 	int (*poll)(struct target *target);
 	/* Invoked only from target_arch_state().
@@ -165,13 +162,22 @@ struct target_type
 	/* returns JIM_OK, or JIM_ERR, or JIM_CONTINUE - if option not understood */
 	int (*target_jim_commands)(struct target *target, Jim_GetOptInfo *goi);
 
-	/* invoked after JTAG chain has been examined & validated. During
-	 * this stage the target is examined and any additional setup is
-	 * performed.
+	/**
+	 * This method is used to perform target setup that requires
+	 * JTAG access.
+	 *
+	 * This may be called multiple times.  It is called after the
+	 * scan chain is initially validated, or later after the target
+	 * is enabled by a JRC.  It may also be called during some
+	 * parts of the reset sequence.
 	 *
-	 * invoked every time after the jtag chain has been validated/examined
+	 * For one-time initialization tasks, use target_was_examined()
+	 * and target_set_examined().  For example, probe the hardware
+	 * before setting up chip-specific state, and then set that
+	 * flag so you don't do that again.
 	 */
 	int (*examine)(struct target *target);
+
 	/* Set up structures for target.
 	 *
 	 * It is illegal to talk to the target at this stage as this fn is invoked