You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

309 lines
11 KiB

  1. /***************************************************************************
  2. * Copyright (C) 2005 by Dominic Rath *
  3. * Dominic.Rath@gmx.de *
  4. * *
  5. * Copyright (C) 2007,2008 √ėyvind Harboe *
  6. * oyvind.harboe@zylin.com *
  7. * *
  8. * Copyright (C) 2009 Zachary T Welch *
  9. * zw@superlucidity.net *
  10. * *
  11. * This program is free software; you can redistribute it and/or modify *
  12. * it under the terms of the GNU General Public License as published by *
  13. * the Free Software Foundation; either version 2 of the License, or *
  14. * (at your option) any later version. *
  15. * *
  16. * This program is distributed in the hope that it will be useful, *
  17. * but WITHOUT ANY WARRANTY; without even the implied warranty of *
  18. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
  19. * GNU General Public License for more details. *
  20. * *
  21. * You should have received a copy of the GNU General Public License *
  22. * along with this program; if not, write to the *
  23. * Free Software Foundation, Inc., *
  24. * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. *
  25. ***************************************************************************/
  26. #ifndef OPENOCD_JTAG_INTERFACE_H
  27. #define OPENOCD_JTAG_INTERFACE_H
  28. #include <jtag/jtag.h>
  29. /* @file
  30. * The "Cable Helper API" is what the cable drivers can use to help
  31. * implement their "Cable API". So a Cable Helper API is a set of
  32. * helper functions used by cable drivers, and this is different from a
  33. * Cable API. A "Cable API" is what higher level code used to talk to a
  34. * cable.
  35. */
  36. /** implementation of wrapper function tap_set_state() */
  37. void tap_set_state_impl(tap_state_t new_state);
  38. /**
  39. * This function sets the state of a "state follower" which tracks the
  40. * state of the TAPs connected to the cable. The state follower is
  41. * hopefully always in the same state as the actual TAPs in the jtag
  42. * chain, and will be so if there are no bugs in the tracking logic
  43. * within that cable driver.
  44. *
  45. * All the cable drivers call this function to indicate the state they
  46. * think the TAPs attached to their cables are in. Because this
  47. * function can also log transitions, it will be helpful to call this
  48. * function with every transition that the TAPs being manipulated are
  49. * expected to traverse, not just end points of a multi-step state path.
  50. *
  51. * @param new_state The state we think the TAPs are currently in (or
  52. * are about to enter).
  53. */
  54. #if defined(_DEBUG_JTAG_IO_)
  55. #define tap_set_state(new_state) \
  56. do { \
  57. LOG_DEBUG("tap_set_state(%s)", tap_state_name(new_state)); \
  58. tap_set_state_impl(new_state); \
  59. } while (0)
  60. #else
  61. static inline void tap_set_state(tap_state_t new_state)
  62. {
  63. tap_set_state_impl(new_state);
  64. }
  65. #endif
  66. /**
  67. * This function gets the state of the "state follower" which tracks the
  68. * state of the TAPs connected to the cable. @see tap_set_state @return
  69. * tap_state_t The state the TAPs are in now.
  70. */
  71. tap_state_t tap_get_state(void);
  72. /**
  73. * This function sets the state of an "end state follower" which tracks
  74. * the state that any cable driver thinks will be the end (resultant)
  75. * state of the current TAP SIR or SDR operation.
  76. *
  77. * At completion of that TAP operation this value is copied into the
  78. * state follower via tap_set_state().
  79. *
  80. * @param new_end_state The state the TAPs should enter at completion of
  81. * a pending TAP operation.
  82. */
  83. void tap_set_end_state(tap_state_t new_end_state);
  84. /**
  85. * For more information, @see tap_set_end_state
  86. * @return tap_state_t - The state the TAPs should be in at completion of the current TAP operation.
  87. */
  88. tap_state_t tap_get_end_state(void);
  89. /**
  90. * This function provides a "bit sequence" indicating what has to be
  91. * done with TMS during a sequence of seven TAP clock cycles in order to
  92. * get from state \a "from" to state \a "to".
  93. *
  94. * The length of the sequence must be determined with a parallel call to
  95. * tap_get_tms_path_len().
  96. *
  97. * @param from The starting state.
  98. * @param to The desired final state.
  99. * @return int The required TMS bit sequence, with the first bit in the
  100. * sequence at bit 0.
  101. */
  102. int tap_get_tms_path(tap_state_t from, tap_state_t to);
  103. /**
  104. * Function int tap_get_tms_path_len
  105. * returns the total number of bits that represents a TMS path
  106. * transition as given by the function tap_get_tms_path().
  107. *
  108. * For at least one interface (JLink) it's not OK to simply "pad" TMS
  109. * sequences to fit a whole byte. (I suspect this is a general TAP
  110. * problem within OOCD.) Padding TMS causes all manner of instability
  111. * that's not easily discovered. Using this routine we can apply
  112. * EXACTLY the state transitions required to make something work - no
  113. * more - no less.
  114. *
  115. * @param from is the starting state
  116. * @param to is the resultant or final state
  117. * @return int - the total number of bits in a transition.
  118. */
  119. int tap_get_tms_path_len(tap_state_t from, tap_state_t to);
  120. /**
  121. * Function tap_move_ndx
  122. * when given a stable state, returns an index from 0-5. The index corresponds to a
  123. * sequence of stable states which are given in this order: <p>
  124. * { TAP_RESET, TAP_IDLE, TAP_DRSHIFT, TAP_DRPAUSE, TAP_IRSHIFT, TAP_IRPAUSE }
  125. * <p>
  126. * This sequence corresponds to look up tables which are used in some of the
  127. * cable drivers.
  128. * @param astate is the stable state to find in the sequence. If a non stable
  129. * state is passed, this may cause the program to output an error message
  130. * and terminate.
  131. * @return int - the array (or sequence) index as described above
  132. */
  133. int tap_move_ndx(tap_state_t astate);
  134. /**
  135. * Function tap_is_state_stable
  136. * returns true if the \a astate is stable.
  137. */
  138. bool tap_is_state_stable(tap_state_t astate);
  139. /**
  140. * Function tap_state_transition
  141. * takes a current TAP state and returns the next state according to the tms value.
  142. * @param current_state is the state of a TAP currently.
  143. * @param tms is either zero or non-zero, just like a real TMS line in a jtag interface.
  144. * @return tap_state_t - the next state a TAP would enter.
  145. */
  146. tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
  147. /** Allow switching between old and new TMS tables. @see tap_get_tms_path */
  148. void tap_use_new_tms_table(bool use_new);
  149. /** @returns True if new TMS table is active; false otherwise. */
  150. bool tap_uses_new_tms_table(void);
  151. #ifdef _DEBUG_JTAG_IO_
  152. /**
  153. * @brief Prints verbose TAP state transitions for the given TMS/TDI buffers.
  154. * @param tms_buf must points to a buffer containing the TMS bitstream.
  155. * @param tdi_buf must points to a buffer containing the TDI bitstream.
  156. * @param tap_len must specify the length of the TMS/TDI bitstreams.
  157. * @param start_tap_state must specify the current TAP state.
  158. * @returns the final TAP state; pass as @a start_tap_state in following call.
  159. */
  160. tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf,
  161. unsigned tap_len, tap_state_t start_tap_state);
  162. #else
  163. static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
  164. const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
  165. {
  166. return start_tap_state;
  167. }
  168. #endif /* _DEBUG_JTAG_IO_ */
  169. /**
  170. * Represents a driver for a debugging interface.
  171. *
  172. * @todo Rename; perhaps "debug_driver". This isn't an interface,
  173. * it's a driver! Also, not all drivers support JTAG.
  174. *
  175. * @todo We need a per-instance structure too, and changes to pass
  176. * that structure to the driver. Instances can for example be in
  177. * either SWD or JTAG modes. This will help remove globals, and
  178. * eventually to cope with systems which have more than one such
  179. * debugging interface.
  180. */
  181. struct jtag_interface {
  182. /** The name of the JTAG interface driver. */
  183. const char * const name;
  184. /**
  185. * Bit vector listing capabilities exposed by this driver.
  186. */
  187. unsigned supported;
  188. #define DEBUG_CAP_TMS_SEQ (1 << 0)
  189. /** transports supported in C code (NULL terminated vector) */
  190. const char * const *transports;
  191. const struct swd_driver *swd;
  192. /**
  193. * Execute queued commands.
  194. * @returns ERROR_OK on success, or an error code on failure.
  195. */
  196. int (*execute_queue)(void);
  197. /**
  198. * Set the interface speed.
  199. * @param speed The new interface speed setting.
  200. * @returns ERROR_OK on success, or an error code on failure.
  201. */
  202. int (*speed)(int speed);
  203. /**
  204. * The interface driver may register additional commands to expose
  205. * additional features not covered by the standard command set.
  206. */
  207. const struct command_registration *commands;
  208. /**
  209. * Interface driver must initialize any resources and connect to a
  210. * JTAG device.
  211. *
  212. * quit() is invoked if and only if init() succeeds. quit() is always
  213. * invoked if init() succeeds. Same as malloc() + free(). Always
  214. * invoke free() if malloc() succeeds and do not invoke free()
  215. * otherwise.
  216. *
  217. * @returns ERROR_OK on success, or an error code on failure.
  218. */
  219. int (*init)(void);
  220. /**
  221. * Interface driver must tear down all resources and disconnect from
  222. * the JTAG device.
  223. *
  224. * @returns ERROR_OK on success, or an error code on failure.
  225. */
  226. int (*quit)(void);
  227. /**
  228. * Returns JTAG maxium speed for KHz. 0 = RTCK. The function returns
  229. * a failure if it can't support the KHz/RTCK.
  230. *
  231. * WARNING!!!! if RTCK is *slow* then think carefully about
  232. * whether you actually want to support this in the driver.
  233. * Many target scripts are written to handle the absence of RTCK
  234. * and use a fallback kHz TCK.
  235. * @returns ERROR_OK on success, or an error code on failure.
  236. */
  237. int (*khz)(int khz, int *jtag_speed);
  238. /**
  239. * Calculate the clock frequency (in KHz) for the given @a speed.
  240. * @param speed The desired interface speed setting.
  241. * @param khz On return, contains the speed in KHz (0 for RTCK).
  242. * @returns ERROR_OK on success, or an error code if the
  243. * interface cannot support the specified speed (KHz or RTCK).
  244. */
  245. int (*speed_div)(int speed, int *khz);
  246. /**
  247. * Read and clear the power dropout flag. Note that a power dropout
  248. * can be transitionary, easily much less than a ms.
  249. *
  250. * To find out if the power is *currently* on, one must invoke this
  251. * method twice. Once to clear the power dropout flag and a second
  252. * time to read the current state. The default implementation
  253. * never reports power dropouts.
  254. *
  255. * @returns ERROR_OK on success, or an error code on failure.
  256. */
  257. int (*power_dropout)(int *power_dropout);
  258. /**
  259. * Read and clear the srst asserted detection flag.
  260. *
  261. * Like power_dropout this does *not* read the current
  262. * state. SRST assertion is transitionary and may be much
  263. * less than 1ms, so the interface driver must watch for these
  264. * events until this routine is called.
  265. *
  266. * @param srst_asserted On return, indicates whether SRST has
  267. * been asserted.
  268. * @returns ERROR_OK on success, or an error code on failure.
  269. */
  270. int (*srst_asserted)(int *srst_asserted);
  271. };
  272. extern const char * const jtag_only[];
  273. void adapter_assert_reset(void);
  274. void adapter_deassert_reset(void);
  275. #endif /* OPENOCD_JTAG_INTERFACE_H */