- added "init" command. "init" and "reset" at end of startup script is equivalent

[openocd.git] / src / target / target.h

diff --git a/src/target/target.h b/src/target/target.h
index 8d70e77ebc9f3ac1cb2263dd742676804e74bfca..d95c4aa76572b333a41a0a70ac0bf52519480ba0 100644 (file)
--- a/src/target/target.h
+++ b/src/target/target.h
@@ -54,14 +54,6 @@ enum target_state
 
 extern char *target_state_strings[];
 
-enum daemon_startup_mode
-{
-       DAEMON_ATTACH,          /* simply attach to the target */
-       DAEMON_RESET,           /* reset target (behaviour defined by reset_mode */
-};
-
-extern enum daemon_startup_mode startup_mode;
-
 enum target_reset_mode
 {
        RESET_RUN = 0,          /* reset and let target run */
@@ -121,13 +113,34 @@ typedef struct target_type_s
        int (*resume)(struct target_s *target, int current, u32 address, int handle_breakpoints, int debug_execution);
        int (*step)(struct target_s *target, int current, u32 address, int handle_breakpoints);
        
-       /* target reset control */
+       /* target reset control. assert reset can be invoked when OpenOCD and
+        * the target is out of sync.
+        * 
+        * A typical example is that the target was power cycled while OpenOCD
+        * thought the target was halted or running.
+        * 
+        * assert_reset() can therefore make no assumptions whatsoever about the
+        * state of the target 
+        * 
+        * Before assert_reset() for the target is invoked, a TRST/tms and
+        * chain validation is executed. TRST should not be asserted
+        * during target assert unless there is no way around it due to
+        * the way reset's are configured.
+        * 
+        */
        int (*assert_reset)(struct target_s *target);
        int (*deassert_reset)(struct target_s *target);
        int (*soft_reset_halt)(struct target_s *target);
-       int (*prepare_reset_halt)(struct target_s *target);
        
-       /* target register access for gdb */
+       /* target register access for gdb.
+        * 
+        * Danger! this function will succeed even if the target is running
+        * and return a register list with dummy values.
+        * 
+        * The reason is that GDB connection will fail without a valid register
+        * list, however it is after GDB is connected that monitor commands can
+        * be run to properly initialize the target
+        */
        int (*get_gdb_reg_list)(struct target_s *target, struct reg_s **reg_list[], int *reg_list_size);
        
        /* target memory access 
@@ -231,9 +244,16 @@ extern int target_register_event_callback(int (*callback)(struct target_s *targe
 extern int target_unregister_event_callback(int (*callback)(struct target_s *target, enum target_event event, void *priv), void *priv);
 extern int target_call_event_callbacks(target_t *target, enum target_event event);
 
+/* The period is very approximate, the callback can happen much more often 
+ * or much more rarely than specified
+ */
 extern int target_register_timer_callback(int (*callback)(void *priv), int time_ms, int periodic, void *priv);
 extern int target_unregister_timer_callback(int (*callback)(void *priv), void *priv);
 extern int target_call_timer_callbacks();
+/* invoke this to ensure that e.g. polling timer callbacks happen before
+ * a syncrhonous command completes.
+ */
+extern int target_call_timer_callbacks_now();
 
 extern target_t* get_current_target(struct command_context_s *cmd_ctx);
 extern int get_num_by_target(target_t *query_target);
@@ -243,9 +263,23 @@ extern int target_write_buffer(struct target_s *target, u32 address, u32 size, u
 extern int target_read_buffer(struct target_s *target, u32 address, u32 size, u8 *buffer);
 extern int target_checksum_memory(struct target_s *target, u32 address, u32 size, u32* crc);
 
+/* DANGER!!!!!
+ * 
+ * if "area" passed in to target_alloc_working_area() points to a memory
+ * location that goes out of scope (e.g. a pointer on the stack), then
+ * the caller of target_alloc_working_area() is responsible for invoking
+ * target_free_working_area() before "area" goes out of scope.
+ * 
+ * target_free_all_working_areas() will NULL out the "area" pointer
+ * upon resuming or resetting the CPU.
+ * 
+ */
 extern int target_alloc_working_area(struct target_s *target, u32 size, working_area_t **area);
 extern int target_free_working_area(struct target_s *target, working_area_t *area);
+extern int target_free_working_area_restore(struct target_s *target, working_area_t *area, int restore);
 extern int target_free_all_working_areas(struct target_s *target);
+extern int target_free_all_working_areas_restore(struct target_s *target, int restore);
+
 
 extern target_t *targets;