Edgar Grimberg sharpened the str912 target script.

[openocd] / src / target / target.h

diff --git a/src/target/target.h b/src/target/target.h
index 29de1e98043ad97daa80e6c67286583754534b2f..fa83949b3b77652cbcd03e14e52ad1d4a7d44c49 100644 (file)
--- a/src/target/target.h
+++ b/src/target/target.h
@@ -33,7 +33,16 @@
 
 struct reg_s;
 struct command_context_s;
-
+/*
+TARGET_UNKNOWN = 0: we don't know anything about the target yet
+TARGET_RUNNING = 1: the target is executing user code
+TARGET_HALTED  = 2: the target is not executing code, and ready to talk to the
+debugger. on an xscale it means that the debug handler is executing
+TARGET_RESET   = 3: the target is being held in reset (only a temporary state,
+not sure how this is used with all the recent changes)
+TARGET_DEBUG_RUNNING = 4: the target is running, but it is executing code on
+behalf of the debugger (e.g. algorithm for flashing)
+*/
 enum target_state
 {
        TARGET_UNKNOWN = 0,
@@ -69,7 +78,8 @@ enum target_debug_reason
        DBG_REASON_WATCHPOINT = 2,
        DBG_REASON_WPTANDBKPT = 3,
        DBG_REASON_SINGLESTEP = 4,
-       DBG_REASON_NOTHALTED = 5
+       DBG_REASON_NOTHALTED = 5,
+       DBG_REASON_UNDEFINED = 6
 };
 
 extern char *target_debug_reason_strings[];
@@ -98,14 +108,15 @@ typedef struct target_type_s
        char *name;
 
        /* poll current target status */
-       enum target_state (*poll)(struct target_s *target);
-       /* architecture specific status reply */
-       int (*arch_state)(struct target_s *target, char *buf, int buf_size);
+       int (*poll)(struct target_s *target);
+       /* Invoked only from target_arch_state().
+        * Issue USER() w/architecture specific status.  */
+       int (*arch_state)(struct target_s *target);
 
        /* target request support */
        int (*target_request_data)(struct target_s *target, u32 size, u8 *buffer);
 
-       /* target execution control */
+       /* halt will log a warning, but return ERROR_OK if the target is already halted. */
        int (*halt)(struct target_s *target);
        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);
@@ -116,7 +127,15 @@ typedef struct target_type_s
        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 
@@ -220,9 +239,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);
@@ -253,10 +279,12 @@ int target_write_u32(struct target_s *target, u32 address, u32 value);
 int target_write_u16(struct target_s *target, u32 address, u16 value);
 int target_write_u8(struct target_s *target, u32 address, u8 value);
 
+/* Issues USER() statements with target state information */
+int target_arch_state(struct target_s *target);
+
 #define ERROR_TARGET_INVALID   (-300)
 #define ERROR_TARGET_INIT_FAILED (-301)
 #define ERROR_TARGET_TIMEOUT   (-302)
-#define ERROR_TARGET_ALREADY_HALTED (-303)
 #define ERROR_TARGET_NOT_HALTED (-304)
 #define ERROR_TARGET_FAILURE   (-305)
 #define ERROR_TARGET_UNALIGNED_ACCESS  (-306)