Encapsulate the jtag_trst and jtag_srst variables:

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

diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h
index bab2731bdc618ccc0aa83f055098ecfdb0d43ee5..40639dce63fee70788028d4a4e213bb555e1f795 100644 (file)
--- a/src/jtag/jtag.h
+++ b/src/jtag/jtag.h
@@ -177,10 +177,9 @@ struct jtag_tap_s
 };
 extern jtag_tap_t* jtag_all_taps(void);
 extern const char *jtag_tap_name(const jtag_tap_t *tap);
-extern jtag_tap_t* jtag_tap_by_position(int n);
 extern jtag_tap_t* jtag_tap_by_string(const char* dotted_name);
 extern jtag_tap_t* jtag_tap_by_jim_obj(Jim_Interp* interp, Jim_Obj* obj);
-extern jtag_tap_t* jtag_tap_by_abs_position(unsigned abs_position);
+extern jtag_tap_t* jtag_tap_by_position(unsigned abs_position);
 extern unsigned jtag_tap_count_enabled(void);
 extern unsigned jtag_tap_count(void);
 
@@ -232,15 +231,11 @@ enum jtag_event {
        JTAG_TRST_ASSERTED
 };
 
-extern char* jtag_event_strings[];
-
 enum jtag_tap_event {
        JTAG_TAP_EVENT_ENABLE,
        JTAG_TAP_EVENT_DISABLE
 };
 
-extern const Jim_Nvp nvp_jtag_tap_event[];
-
 struct jtag_tap_event_action_s
 {
        enum jtag_tap_event      event;
@@ -248,8 +243,10 @@ struct jtag_tap_event_action_s
        jtag_tap_event_action_t* next;
 };
 
-extern int jtag_trst;
-extern int jtag_srst;
+/// @returns The current state of TRST.
+int jtag_get_trst(void);
+/// @returns The current state of SRST.
+int jtag_get_srst(void);
 
 typedef struct jtag_event_callback_s
 {
@@ -309,12 +306,29 @@ extern int  jtag_register_commands(struct command_context_s* cmd_ctx);
  * end state and a subsequent jtag_add_pathmove() must be issued.
  */
 
+/**
+ * Generate an IR SCAN with a list of scan fields with one entry for
+ * each enabled TAP.
+ *
+ * If the input field list contains an instruction value for a TAP then
+ * that is used otherwise the TAP is set to bypass.
+ *
+ * TAPs for which no fields are passed are marked as bypassed for
+ * subsequent DR SCANs.
+ *
+ */
 extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 /**
  * The same as jtag_add_ir_scan except no verification is performed out
  * the output values.
  */
 extern void jtag_add_ir_scan_noverify(int num_fields, const scan_field_t *fields, tap_state_t state);
+/**
+ * Duplicate the scan fields passed into the function into an IR SCAN
+ * command.  This function assumes that the caller handles extra fields
+ * for bypassed TAPs.
+ */
+extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
 
 
 /**
@@ -328,10 +342,20 @@ extern void jtag_add_ir_scan_noverify(int num_fields, const scan_field_t *fields
  */
 extern void jtag_alloc_in_value32(scan_field_t *field);
 
+/**
+ * Generate a DR SCAN using the fields passed to the function.
+ * For connected TAPs, the function checks in_fields and uses fields
+ * specified there.  For bypassed TAPs, the function generates a dummy
+ * 1-bit field.  The bypass status of TAPs is set by jtag_add_ir_scan().
+ */
 extern void jtag_add_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
 /// A version of jtag_add_dr_scan() that uses the check_value/mask fields
 extern void jtag_add_dr_scan_check(int num_fields, scan_field_t* fields, tap_state_t endstate);
-extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
+/**
+ * Duplicate the scan fields passed into the function into a DR SCAN
+ * command.  Unlike jtag_add_dr_scan(), this function assumes that the
+ * caller handles extra fields for bypassed TAPs.
+ */
 extern void jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
 
 
@@ -649,16 +673,36 @@ extern void jtag_add_dr_out(jtag_tap_t* tap,
 /**
  * jtag_add_statemove() moves from the current state to @a goal_state.
  *
- * This function was originally designed to handle the XSTATE command
- * from the XSVF specification.
- *
  * @param goal_state The final TAP state.
  * @return ERROR_OK on success, or an error code on failure.
+ *
+ * Moves from the current state to the goal \a state. 
+ *
+ * This needs to be handled according to the xsvf spec, see the XSTATE
+ * command description.  From the XSVF spec, pertaining to XSTATE:
+ *
+ * For special states known as stable states (Test-Logic-Reset,
+ * Run-Test/Idle, Pause-DR, Pause- IR), an XSVF interpreter follows
+ * predefined TAP state paths when the starting state is a stable state
+ * and when the XSTATE specifies a new stable state.  See the STATE
+ * command in the [Ref 5] for the TAP state paths between stable
+ * states.
+ *
+ * For non-stable states, XSTATE should specify a state that is only one
+ * TAP state transition distance from the current TAP state to avoid
+ * undefined TAP state paths. A sequence of multiple XSTATE commands can
+ * be issued to transition the TAP through a specific state path.
+ *
+ * @note Unless @c tms_bits holds a path that agrees with [Ref 5] in the
+ * above spec, then this code is not fully conformant to the xsvf spec.
+ * This puts a burden on tap_get_tms_path() function from the xsvf spec.
+ * If in doubt, you should confirm that that burden is being met.
+ *
+ * Otherwise, @a goal_state must be immediately reachable in one clock
+ * cycle, and does not need to be a stable state.
  */
 extern int jtag_add_statemove(tap_state_t goal_state);
 
-
-
 /// @returns the number of times the scan queue has been flushed
 int jtag_get_flush_queue_count(void);