X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=src%2Ftarget%2Ftarget_type.h;h=aa87a74495a2d2fa5eb3a872a3f4c43461bf676a;hb=7e4adfe1c53aa18d4feba1e58ceb5c5aaa470775;hp=32c58abba28208deb389954041b7884220c15ebc;hpb=0f1163e823c6ca3c2a81fa296157f5dde0635fea;p=openocd.git

diff --git a/src/target/target_type.h b/src/target/target_type.h
index 32c58abba2..aa87a74495 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().
@@ -151,7 +148,7 @@ struct target_type
 	 */
 	int (*run_algorithm)(struct target *target, int num_mem_params, struct mem_param *mem_params, int num_reg_params, struct reg_param *reg_param, uint32_t entry_point, uint32_t exit_point, int timeout_ms, void *arch_info);
 
-	int (*register_commands)(struct command_context_s *cmd_ctx);
+	int (*register_commands)(struct command_context *cmd_ctx);
 
 	/* called when target is created */
 	int (*target_create)(struct target *target, Jim_Interp *interp);
@@ -165,19 +162,28 @@ 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
 	 * before the JTAG chain has been examined/verified
 	 * */
-	int (*init_target)(struct command_context_s *cmd_ctx, struct target *target);
+	int (*init_target)(struct command_context *cmd_ctx, struct target *target);
 
 	/* translate from virtual to physical address. Default implementation is successful
 	 * no-op(i.e. virtual==physical).