Dick Hollenbeck <dick@softplc.com> Collect some macros, add DIM()

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

diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h
index 895afe1fb2ca5a4e5d46bf6201b571265b1c8b41..434320b49546b5e119f7911b697b971366b39d0a 100644 (file)
--- a/src/jtag/jtag.h
+++ b/src/jtag/jtag.h
@@ -29,25 +29,75 @@
 
 #include "command.h"
 
-#if 0
-#define _DEBUG_JTAG_IO_
+
+#ifdef _DEBUG_JTAG_IO_
+#define DEBUG_JTAG_IO(expr ...)                LOG_DEBUG(expr)
+#else
+#define DEBUG_JTAG_IO(expr ...)
 #endif
 
 #ifndef DEBUG_JTAG_IOZ
 #define DEBUG_JTAG_IOZ 64
 #endif
 
-/* 16 Tap States, from page 21 of ASSET InterTech, Inc.'s svf.pdf
+/*-----<Macros>--------------------------------------------------*/
+
+/** When given an array, compute its DIMension, i.e. number of elements in the array */
+#define DIM(x)                                 (sizeof(x)/sizeof((x)[0]))
+
+/** Calculate the number of bytes required to hold @a n TAP scan bits */
+#define TAP_SCAN_BYTES(n)              CEIL(n, 8)
+
+/*-----</Macros>-------------------------------------------------*/
+
+
+
+/*
+ * Tap states from ARM7TDMI-S Technical reference manual.
+ * Also, validated against several other ARM core technical manuals.
+ *
+ * N.B. tap_get_tms_path() was changed to reflect this corrected
+ * numbering and ordering of the TAP states.
+ *
+ * DANGER!!!! some interfaces care about the actual numbers used
+ * as they are handed off directly to hardware implementations.
  */
-enum tap_state {
+
+typedef enum tap_state
+{
+#if BUILD_ECOSBOARD
+/* These are the old numbers. Leave as-is for now... */
        TAP_RESET    = 0, TAP_IDLE = 8,
        TAP_DRSELECT = 1, TAP_DRCAPTURE = 2, TAP_DRSHIFT = 3, TAP_DREXIT1 = 4,
        TAP_DRPAUSE  = 5, TAP_DREXIT2 = 6, TAP_DRUPDATE = 7,
        TAP_IRSELECT = 9, TAP_IRCAPTURE = 10, TAP_IRSHIFT = 11, TAP_IREXIT1 = 12,
-       TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15
-};
+       TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,
 
-typedef enum tap_state tap_state_t;
+       TAP_NUM_STATES = 16, TAP_INVALID = -1,
+#else
+       /* Proper ARM recommended numbers */
+       TAP_DREXIT2 = 0x0,
+       TAP_DREXIT1 = 0x1,
+       TAP_DRSHIFT = 0x2,
+       TAP_DRPAUSE = 0x3,
+       TAP_IRSELECT = 0x4,
+       TAP_DRUPDATE = 0x5,
+       TAP_DRCAPTURE = 0x6,
+       TAP_DRSELECT = 0x7,
+       TAP_IREXIT2 = 0x8,
+       TAP_IREXIT1 = 0x9,
+       TAP_IRSHIFT = 0xa,
+       TAP_IRPAUSE = 0xb,
+       TAP_IDLE = 0xc,
+       TAP_IRUPDATE = 0xd,
+       TAP_IRCAPTURE = 0xe,
+       TAP_RESET = 0x0f,
+
+       TAP_NUM_STATES = 0x10,
+
+       TAP_INVALID = -1,
+#endif
+} tap_state_t;
 
 typedef struct tap_transition_s
 {
@@ -57,6 +107,7 @@ typedef struct tap_transition_s
 
 //extern tap_transition_t tap_transitions[16];    /* describe the TAP state diagram */
 
+
 /*-----<Cable Helper API>-------------------------------------------*/
 
 /* The "Cable Helper API" is what the cable drivers can use to help implement
@@ -147,9 +198,9 @@ int tap_move_ndx(tap_state_t astate);
 
 /**
  * Function tap_is_state_stable
- * returns TRUE if the \a astate is stable.
+ * returns true if the \a astate is stable.
  */
-int tap_is_state_stable(tap_state_t astate);
+bool tap_is_state_stable(tap_state_t astate);
 
 /**
  * Function tap_state_transition
@@ -158,7 +209,7 @@ int tap_is_state_stable(tap_state_t astate);
  * @param tms is either zero or non-zero, just like a real TMS line in a jtag interface.
  * @return tap_state_t - the next state a TAP would enter.
  */
-tap_state_t tap_state_transition(tap_state_t current_state, int tms);
+tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
 
 /**
  * Function tap_state_name
@@ -166,8 +217,28 @@ tap_state_t tap_state_transition(tap_state_t current_state, int tms);
  */
 const char* tap_state_name(tap_state_t state);
 
+#ifdef _DEBUG_JTAG_IO_
+/**
+ * @brief Prints verbose TAP state transitions for the given TMS/TDI buffers.
+ * @param tms_buf must points to a buffer containing the TMS bitstream.
+ * @param tdi_buf must points to a buffer containing the TDI bitstream.
+ * @param tap_len must specify the length of the TMS/TDI bitstreams.
+ * @param start_tap_state must specify the current TAP state.
+ * @returns the final TAP state; pass as @a start_tap_state in following call.
+ */
+tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf,
+               unsigned tap_len, tap_state_t start_tap_state);
+#else
+static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
+               const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
+{
+       return start_tap_state;
+}
+#endif // _DEBUG_JTAG_IO_
+
 /*-----</Cable Helper API>------------------------------------------*/
 
+
 extern tap_state_t cmd_queue_end_state;         /* finish DR scans in dr_end_state */
 extern tap_state_t cmd_queue_cur_state;         /* current TAP state */
 
@@ -639,7 +710,7 @@ void jtag_tap_handle_event(jtag_tap_t* tap, enum jtag_tap_event e);
 
 /* jtag_add_dr_out() is a faster version of jtag_add_dr_scan()
  *
- * Current or end_state can not be TAP_RESET. end_state can be -1
+ * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
  *
  * num_bits[i] is the number of bits to clock out from value[i] LSB first.
  *
@@ -662,7 +733,7 @@ extern void interface_jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int
 static __inline__ void jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int* num_bits, const u32* value,
                tap_state_t end_state)
 {
-       if (end_state != -1)
+       if (end_state != TAP_INVALID)
                cmd_queue_end_state = end_state;
        cmd_queue_cur_state = cmd_queue_end_state;
        interface_jtag_add_dr_out(tap, num_fields, num_bits, value, cmd_queue_end_state);