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>

1 files changed, 20 insertions, 14 deletions

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