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.
 
 
 
 
 
 

721 lines
25 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. * This program is free software; you can redistribute it and/or modify *
  9. * it under the terms of the GNU General Public License as published by *
  10. * the Free Software Foundation; either version 2 of the License, or *
  11. * (at your option) any later version. *
  12. * *
  13. * This program is distributed in the hope that it will be useful, *
  14. * but WITHOUT ANY WARRANTY; without even the implied warranty of *
  15. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
  16. * GNU General Public License for more details. *
  17. * *
  18. * You should have received a copy of the GNU General Public License *
  19. * along with this program; if not, write to the *
  20. * Free Software Foundation, Inc., *
  21. * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
  22. ***************************************************************************/
  23. #ifndef JTAG_H
  24. #define JTAG_H
  25. #include "binarybuffer.h"
  26. #include "log.h"
  27. #ifdef _DEBUG_JTAG_IO_
  28. #define DEBUG_JTAG_IO(expr ...) LOG_DEBUG(expr)
  29. #else
  30. #define DEBUG_JTAG_IO(expr ...)
  31. #endif
  32. #ifndef DEBUG_JTAG_IOZ
  33. #define DEBUG_JTAG_IOZ 64
  34. #endif
  35. /*-----<Macros>--------------------------------------------------*/
  36. /**
  37. * When given an array, compute its DIMension; in other words, the
  38. * number of elements in the array
  39. */
  40. #define DIM(x) (sizeof(x)/sizeof((x)[0]))
  41. /** Calculate the number of bytes required to hold @a n TAP scan bits */
  42. #define TAP_SCAN_BYTES(n) CEIL(n, 8)
  43. /*-----</Macros>-------------------------------------------------*/
  44. /**
  45. * Defines JTAG Test Access Port states.
  46. *
  47. * These definitions were gleaned from the ARM7TDMI-S Technical
  48. * Reference Manual and validated against several other ARM core
  49. * technical manuals. tap_get_tms_path() is sensitive to this numbering
  50. * and ordering of the TAP states; furthermore, some interfaces require
  51. * specific numbers be used, as they are handed-off directly to their
  52. * hardware implementations.
  53. */
  54. typedef enum tap_state
  55. {
  56. #if BUILD_ZY1000
  57. /* These are the old numbers. Leave as-is for now... */
  58. TAP_RESET = 0, TAP_IDLE = 8,
  59. TAP_DRSELECT = 1, TAP_DRCAPTURE = 2, TAP_DRSHIFT = 3, TAP_DREXIT1 = 4,
  60. TAP_DRPAUSE = 5, TAP_DREXIT2 = 6, TAP_DRUPDATE = 7,
  61. TAP_IRSELECT = 9, TAP_IRCAPTURE = 10, TAP_IRSHIFT = 11, TAP_IREXIT1 = 12,
  62. TAP_IRPAUSE = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,
  63. TAP_NUM_STATES = 16, TAP_INVALID = -1,
  64. #else
  65. /* Proper ARM recommended numbers */
  66. TAP_DREXIT2 = 0x0,
  67. TAP_DREXIT1 = 0x1,
  68. TAP_DRSHIFT = 0x2,
  69. TAP_DRPAUSE = 0x3,
  70. TAP_IRSELECT = 0x4,
  71. TAP_DRUPDATE = 0x5,
  72. TAP_DRCAPTURE = 0x6,
  73. TAP_DRSELECT = 0x7,
  74. TAP_IREXIT2 = 0x8,
  75. TAP_IREXIT1 = 0x9,
  76. TAP_IRSHIFT = 0xa,
  77. TAP_IRPAUSE = 0xb,
  78. TAP_IDLE = 0xc,
  79. TAP_IRUPDATE = 0xd,
  80. TAP_IRCAPTURE = 0xe,
  81. TAP_RESET = 0x0f,
  82. TAP_NUM_STATES = 0x10,
  83. TAP_INVALID = -1,
  84. #endif
  85. } tap_state_t;
  86. /**
  87. * Function tap_state_name
  88. * Returns a string suitable for display representing the JTAG tap_state
  89. */
  90. const char* tap_state_name(tap_state_t state);
  91. /// The current TAP state of the pending JTAG command queue.
  92. extern tap_state_t cmd_queue_cur_state;
  93. /**
  94. * This structure defines a single scan field in the scan. It provides
  95. * fields for the field's width and pointers to scan input and output
  96. * values.
  97. *
  98. * In addition, this structure includes a value and mask that is used by
  99. * jtag_add_dr_scan_check() to validate the value that was scanned out.
  100. *
  101. * The allocated, modified, and intmp fields are internal work space.
  102. */
  103. typedef struct scan_field_s
  104. {
  105. /// A pointer to the tap structure to which this field refers.
  106. jtag_tap_t* tap;
  107. /// The number of bits this field specifies (up to 32)
  108. int num_bits;
  109. /// A pointer to value to be scanned into the device
  110. uint8_t* out_value;
  111. /// A pointer to a 32-bit memory location for data scanned out
  112. uint8_t* in_value;
  113. /// The value used to check the data scanned out.
  114. uint8_t* check_value;
  115. /// The mask to go with check_value
  116. uint8_t* check_mask;
  117. /// in_value has been allocated for the queue
  118. int allocated;
  119. /// Indicates we modified the in_value.
  120. int modified;
  121. /// temporary storage for performing value checks synchronously
  122. uint8_t intmp[4];
  123. } scan_field_t;
  124. typedef struct jtag_tap_event_action_s jtag_tap_event_action_t;
  125. /* this is really: typedef jtag_tap_t */
  126. /* But - the typedef is done in "types.h" */
  127. /* due to "forward declaration reasons" */
  128. struct jtag_tap_s
  129. {
  130. const char* chip;
  131. const char* tapname;
  132. const char* dotted_name;
  133. int abs_chain_position;
  134. /// Is this TAP disabled after JTAG reset?
  135. bool disabled_after_reset;
  136. /// Is this TAP currently enabled?
  137. bool enabled;
  138. int ir_length; /**< size of instruction register */
  139. uint32_t ir_capture_value;
  140. uint8_t* expected; /**< Capture-IR expected value */
  141. uint32_t ir_capture_mask;
  142. uint8_t* expected_mask; /**< Capture-IR expected mask */
  143. uint32_t idcode;
  144. bool hasidcode; /* not all devices have idcode, we'll discover this during chain examination */
  145. /**< device identification code */
  146. /// Array of expected identification codes */
  147. uint32_t* expected_ids;
  148. /// Number of expected identification codes
  149. uint8_t expected_ids_cnt;
  150. /// current instruction
  151. uint8_t* cur_instr;
  152. /// Bypass register selected
  153. int bypass;
  154. jtag_tap_event_action_t *event_action;
  155. jtag_tap_t* next_tap;
  156. };
  157. void jtag_tap_init(jtag_tap_t *tap);
  158. void jtag_tap_free(jtag_tap_t *tap);
  159. extern jtag_tap_t* jtag_all_taps(void);
  160. extern const char *jtag_tap_name(const jtag_tap_t *tap);
  161. extern jtag_tap_t* jtag_tap_by_string(const char* dotted_name);
  162. extern jtag_tap_t* jtag_tap_by_jim_obj(Jim_Interp* interp, Jim_Obj* obj);
  163. extern jtag_tap_t* jtag_tap_next_enabled(jtag_tap_t* p);
  164. extern unsigned jtag_tap_count_enabled(void);
  165. extern unsigned jtag_tap_count(void);
  166. /*
  167. * There are three cases when JTAG_TRST_ASSERTED callback is invoked. The
  168. * event is invoked *after* TRST is asserted(or queued rather). It is illegal
  169. * to communicate with the JTAG interface during the callback(as there is
  170. * currently a queue being built).
  171. *
  172. * - TMS reset
  173. * - SRST pulls TRST
  174. * - TRST asserted
  175. *
  176. * TAP activation/deactivation is currently implemented outside the core
  177. * using scripted code that understands the specific router type.
  178. */
  179. enum jtag_event {
  180. JTAG_TRST_ASSERTED,
  181. JTAG_TAP_EVENT_ENABLE,
  182. JTAG_TAP_EVENT_DISABLE,
  183. JTAG_TAP_EVENT_POST_RESET,
  184. };
  185. struct jtag_tap_event_action_s
  186. {
  187. enum jtag_event event;
  188. Jim_Obj* body;
  189. jtag_tap_event_action_t* next;
  190. };
  191. /**
  192. * Defines the function signature requide for JTAG event callback
  193. * functions, which are added with jtag_register_event_callback()
  194. * and removed jtag_unregister_event_callback().
  195. * @param event The event to handle.
  196. * @param prive A pointer to data that was passed to
  197. * jtag_register_event_callback().
  198. * @returns Must return ERROR_OK on success, or an error code on failure.
  199. *
  200. * @todo Change to return void or define a use for its return code.
  201. */
  202. typedef int (*jtag_event_handler_t)(enum jtag_event event, void* priv);
  203. extern int jtag_register_event_callback(jtag_event_handler_t f, void *x);
  204. extern int jtag_unregister_event_callback(jtag_event_handler_t f, void *x);
  205. extern int jtag_call_event_callbacks(enum jtag_event event);
  206. /// @returns The current JTAG speed setting.
  207. int jtag_get_speed(void);
  208. /**
  209. * Given a @a speed setting, use the interface @c speed_div callback to
  210. * adjust the setting.
  211. * @param speed The speed setting to convert back to readable KHz.
  212. * @returns ERROR_OK if the interface has not been initialized or on success;
  213. * otherwise, the error code produced by the @c speed_div callback.
  214. */
  215. int jtag_get_speed_readable(int *speed);
  216. /**
  217. * Set the JTAG speed. This routine will call the underlying
  218. * interface @c speed callback, if the interface has been initialized.
  219. * @param speed The new speed setting.
  220. * @returns ERROR_OK during configuration or on success, or an error
  221. * code returned from the interface @c speed callback.
  222. */
  223. int jtag_config_speed(int speed);
  224. /// Attempt to configure the interface for the specified KHz.
  225. int jtag_config_khz(unsigned khz);
  226. /**
  227. * Attempt to enable RTCK/RCLK. If that fails, fallback to the
  228. * specified frequency.
  229. */
  230. int jtag_config_rclk(unsigned fallback_speed_khz);
  231. /// Retreives the clock speed of the JTAG interface in KHz.
  232. unsigned jtag_get_speed_khz(void);
  233. enum reset_types {
  234. RESET_NONE = 0x0,
  235. RESET_HAS_TRST = 0x1,
  236. RESET_HAS_SRST = 0x2,
  237. RESET_TRST_AND_SRST = 0x3,
  238. RESET_SRST_PULLS_TRST = 0x4,
  239. RESET_TRST_PULLS_SRST = 0x8,
  240. RESET_TRST_OPEN_DRAIN = 0x10,
  241. RESET_SRST_PUSH_PULL = 0x20,
  242. };
  243. enum reset_types jtag_get_reset_config(void);
  244. void jtag_set_reset_config(enum reset_types type);
  245. void jtag_set_nsrst_delay(unsigned delay);
  246. unsigned jtag_get_nsrst_delay(void);
  247. void jtag_set_ntrst_delay(unsigned delay);
  248. unsigned jtag_get_ntrst_delay(void);
  249. /// @returns The current state of TRST.
  250. int jtag_get_trst(void);
  251. /// @returns The current state of SRST.
  252. int jtag_get_srst(void);
  253. /// Enable or disable data scan verification checking.
  254. void jtag_set_verify(bool enable);
  255. /// @returns True if data scan verification will be performed.
  256. bool jtag_will_verify(void);
  257. /// Enable or disable verification of IR scan checking.
  258. void jtag_set_verify_capture_ir(bool enable);
  259. /// @returns True if IR scan verification will be performed.
  260. bool jtag_will_verify_capture_ir(void);
  261. /**
  262. * Initialize interface upon startup. Return a successful no-op upon
  263. * subsequent invocations.
  264. */
  265. extern int jtag_interface_init(struct command_context_s* cmd_ctx);
  266. /// Shutdown the JTAG interface upon program exit.
  267. extern int jtag_interface_quit(void);
  268. /**
  269. * Initialize JTAG chain using only a RESET reset. If init fails,
  270. * try reset + init.
  271. */
  272. extern int jtag_init(struct command_context_s* cmd_ctx);
  273. /// reset, then initialize JTAG chain
  274. extern int jtag_init_reset(struct command_context_s* cmd_ctx);
  275. extern int jtag_register_commands(struct command_context_s* cmd_ctx);
  276. /**
  277. * @file
  278. * The JTAG interface can be implemented with a software or hardware fifo.
  279. *
  280. * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states; however,
  281. * TAP_DRSHIFT/IRSHIFT can be emulated as end states, by using longer
  282. * scans.
  283. *
  284. * Code that is relatively insensitive to the path taken through state
  285. * machine (as long as it is JTAG compliant) can use @a endstate for
  286. * jtag_add_xxx_scan(). Otherwise, the pause state must be specified as
  287. * end state and a subsequent jtag_add_pathmove() must be issued.
  288. */
  289. /**
  290. * Generate an IR SCAN with a list of scan fields with one entry for
  291. * each enabled TAP.
  292. *
  293. * If the input field list contains an instruction value for a TAP then
  294. * that is used otherwise the TAP is set to bypass.
  295. *
  296. * TAPs for which no fields are passed are marked as bypassed for
  297. * subsequent DR SCANs.
  298. *
  299. */
  300. extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
  301. /**
  302. * The same as jtag_add_ir_scan except no verification is performed out
  303. * the output values.
  304. */
  305. extern void jtag_add_ir_scan_noverify(int num_fields, const scan_field_t *fields, tap_state_t state);
  306. /**
  307. * Duplicate the scan fields passed into the function into an IR SCAN
  308. * command. This function assumes that the caller handles extra fields
  309. * for bypassed TAPs.
  310. */
  311. extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
  312. /**
  313. * Set in_value to point to 32 bits of memory to scan into. This
  314. * function is a way to handle the case of synchronous and asynchronous
  315. * JTAG queues.
  316. *
  317. * In the event of an asynchronous queue execution the queue buffer
  318. * allocation method is used, for the synchronous case the temporary 32
  319. * bits come from the input field itself.
  320. */
  321. extern void jtag_alloc_in_value32(scan_field_t *field);
  322. /**
  323. * Generate a DR SCAN using the fields passed to the function.
  324. * For connected TAPs, the function checks in_fields and uses fields
  325. * specified there. For bypassed TAPs, the function generates a dummy
  326. * 1-bit field. The bypass status of TAPs is set by jtag_add_ir_scan().
  327. */
  328. extern void jtag_add_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
  329. /// A version of jtag_add_dr_scan() that uses the check_value/mask fields
  330. extern void jtag_add_dr_scan_check(int num_fields, scan_field_t* fields, tap_state_t endstate);
  331. /**
  332. * Duplicate the scan fields passed into the function into a DR SCAN
  333. * command. Unlike jtag_add_dr_scan(), this function assumes that the
  334. * caller handles extra fields for bypassed TAPs.
  335. */
  336. extern void jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
  337. /**
  338. * Defines the type of data passed to the jtag_callback_t interface.
  339. * The underlying type must allow storing an @c int or pointer type.
  340. */
  341. typedef intptr_t jtag_callback_data_t;
  342. /**
  343. * Defines a simple JTAG callback that can allow conversions on data
  344. * scanned in from an interface.
  345. *
  346. * This callback should only be used for conversion that cannot fail.
  347. * For conversion types or checks that can fail, use the more complete
  348. * variant: jtag_callback_t.
  349. */
  350. typedef void (*jtag_callback1_t)(jtag_callback_data_t data0);
  351. /// A simpler version of jtag_add_callback4().
  352. extern void jtag_add_callback(jtag_callback1_t, jtag_callback_data_t data0);
  353. /**
  354. * Defines the interface of the JTAG callback mechanism.
  355. *
  356. * @param in the pointer to the data clocked in
  357. * @param data1 An integer big enough to use as an @c int or a pointer.
  358. * @param data2 An integer big enough to use as an @c int or a pointer.
  359. * @param data3 An integer big enough to use as an @c int or a pointer.
  360. * @returns an error code
  361. */
  362. typedef int (*jtag_callback_t)(jtag_callback_data_t data0, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3);
  363. /**
  364. * This callback can be executed immediately the queue has been flushed.
  365. *
  366. * The JTAG queue can be executed synchronously or asynchronously.
  367. * Typically for USB, the queue is executed asynchronously. For
  368. * low-latency interfaces, the queue may be executed synchronously.
  369. *
  370. * The callback mechanism is very general and does not make many
  371. * assumptions about what the callback does or what its arguments are.
  372. * These callbacks are typically executed *after* the *entire* JTAG
  373. * queue has been executed for e.g. USB interfaces, and they are
  374. * guaranteeed to be invoked in the order that they were queued.
  375. *
  376. * If the execution of the queue fails before the callbacks, then --
  377. * depending on driver implementation -- the callbacks may or may not be
  378. * invoked. @todo Can we make this behavior consistent?
  379. *
  380. * The strange name is due to C's lack of overloading using function
  381. * arguments.
  382. *
  383. * @param f The callback function to add.
  384. * @param data0 Typically used to point to the data to operate on.
  385. * Frequently this will be the data clocked in during a shift operation.
  386. * @param data1 An integer big enough to use as an @c int or a pointer.
  387. * @param data2 An integer big enough to use as an @c int or a pointer.
  388. * @param data3 An integer big enough to use as an @c int or a pointer.
  389. *
  390. */
  391. extern void jtag_add_callback4(jtag_callback_t f, jtag_callback_data_t data0,
  392. jtag_callback_data_t data1, jtag_callback_data_t data2,
  393. jtag_callback_data_t data3);
  394. /**
  395. * Run a TAP_RESET reset where the end state is TAP_RESET,
  396. * regardless of the start state.
  397. */
  398. extern void jtag_add_tlr(void);
  399. /**
  400. * Application code *must* assume that interfaces will
  401. * implement transitions between states with different
  402. * paths and path lengths through the state diagram. The
  403. * path will vary across interface and also across versions
  404. * of the same interface over time. Even if the OpenOCD code
  405. * is unchanged, the actual path taken may vary over time
  406. * and versions of interface firmware or PCB revisions.
  407. *
  408. * Use jtag_add_pathmove() when specific transition sequences
  409. * are required.
  410. *
  411. * Do not use jtag_add_pathmove() unless you need to, but do use it
  412. * if you have to.
  413. *
  414. * DANGER! If the target is dependent upon a particular sequence
  415. * of transitions for things to work correctly(e.g. as a workaround
  416. * for an errata that contradicts the JTAG standard), then pathmove
  417. * must be used, even if some jtag interfaces happen to use the
  418. * desired path. Worse, the jtag interface used for testing a
  419. * particular implementation, could happen to use the "desired"
  420. * path when transitioning to/from end
  421. * state.
  422. *
  423. * A list of unambigious single clock state transitions, not
  424. * all drivers can support this, but it is required for e.g.
  425. * XScale and Xilinx support
  426. *
  427. * Note! TAP_RESET must not be used in the path!
  428. *
  429. * Note that the first on the list must be reachable
  430. * via a single transition from the current state.
  431. *
  432. * All drivers are required to implement jtag_add_pathmove().
  433. * However, if the pathmove sequence can not be precisely
  434. * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
  435. * must return an error. It is legal, but not recommended, that
  436. * a driver returns an error in all cases for a pathmove if it
  437. * can only implement a few transitions and therefore
  438. * a partial implementation of pathmove would have little practical
  439. * application.
  440. *
  441. * If an error occurs, jtag_error will contain one of these error codes:
  442. * - ERROR_JTAG_NOT_STABLE_STATE -- The final state was not stable.
  443. * - ERROR_JTAG_STATE_INVALID -- The path passed through TAP_RESET.
  444. * - ERROR_JTAG_TRANSITION_INVALID -- The path includes invalid
  445. * state transitions.
  446. */
  447. extern void jtag_add_pathmove(int num_states, const tap_state_t* path);
  448. /**
  449. * jtag_add_statemove() moves from the current state to @a goal_state.
  450. *
  451. * @param goal_state The final TAP state.
  452. * @return ERROR_OK on success, or an error code on failure.
  453. *
  454. * Moves from the current state to the goal \a state.
  455. *
  456. * This needs to be handled according to the xsvf spec, see the XSTATE
  457. * command description. From the XSVF spec, pertaining to XSTATE:
  458. *
  459. * For special states known as stable states (Test-Logic-Reset,
  460. * Run-Test/Idle, Pause-DR, Pause- IR), an XSVF interpreter follows
  461. * predefined TAP state paths when the starting state is a stable state
  462. * and when the XSTATE specifies a new stable state. See the STATE
  463. * command in the [Ref 5] for the TAP state paths between stable
  464. * states.
  465. *
  466. * For non-stable states, XSTATE should specify a state that is only one
  467. * TAP state transition distance from the current TAP state to avoid
  468. * undefined TAP state paths. A sequence of multiple XSTATE commands can
  469. * be issued to transition the TAP through a specific state path.
  470. *
  471. * @note Unless @c tms_bits holds a path that agrees with [Ref 5] in the
  472. * above spec, then this code is not fully conformant to the xsvf spec.
  473. * This puts a burden on tap_get_tms_path() function from the xsvf spec.
  474. * If in doubt, you should confirm that that burden is being met.
  475. *
  476. * Otherwise, @a goal_state must be immediately reachable in one clock
  477. * cycle, and does not need to be a stable state.
  478. */
  479. extern int jtag_add_statemove(tap_state_t goal_state);
  480. /**
  481. * Goes to TAP_IDLE (if we're not already there), cycle
  482. * precisely num_cycles in the TAP_IDLE state, after which move
  483. * to @a endstate (unless it is also TAP_IDLE).
  484. *
  485. * @param num_cycles Number of cycles in TAP_IDLE state. This argument
  486. * may be 0, in which case this routine will navigate to @a endstate
  487. * via TAP_IDLE.
  488. * @param endstate The final state.
  489. */
  490. extern void jtag_add_runtest(int num_cycles, tap_state_t endstate);
  491. /**
  492. * A reset of the TAP state machine can be requested.
  493. *
  494. * Whether tms or trst reset is used depends on the capabilities of
  495. * the target and jtag interface(reset_config command configures this).
  496. *
  497. * srst can driver a reset of the TAP state machine and vice
  498. * versa
  499. *
  500. * Application code may need to examine value of jtag_reset_config
  501. * to determine the proper codepath
  502. *
  503. * DANGER! Even though srst drives trst, trst might not be connected to
  504. * the interface, and it might actually be *harmful* to assert trst in this case.
  505. *
  506. * This is why combinations such as "reset_config srst_only srst_pulls_trst"
  507. * are supported.
  508. *
  509. * only req_tlr_or_trst and srst can have a transition for a
  510. * call as the effects of transitioning both at the "same time"
  511. * are undefined, but when srst_pulls_trst or vice versa,
  512. * then trst & srst *must* be asserted together.
  513. */
  514. extern void jtag_add_reset(int req_tlr_or_trst, int srst);
  515. /**
  516. * Function jtag_set_end_state
  517. *
  518. * Set a global variable to \a state if \a state != TAP_INVALID.
  519. *
  520. * Return the value of the global variable.
  521. *
  522. **/
  523. extern tap_state_t jtag_set_end_state(tap_state_t state);
  524. /**
  525. * Function jtag_get_end_state
  526. *
  527. * Return the value of the global variable for end state
  528. *
  529. **/
  530. extern tap_state_t jtag_get_end_state(void);
  531. extern void jtag_add_sleep(uint32_t us);
  532. /**
  533. * Function jtag_add_stable_clocks
  534. * first checks that the state in which the clocks are to be issued is
  535. * stable, then queues up clock_count clocks for transmission.
  536. */
  537. void jtag_add_clocks(int num_cycles);
  538. /**
  539. * For software FIFO implementations, the queued commands can be executed
  540. * during this call or earlier. A sw queue might decide to push out
  541. * some of the jtag_add_xxx() operations once the queue is "big enough".
  542. *
  543. * This fn will return an error code if any of the prior jtag_add_xxx()
  544. * calls caused a failure, e.g. check failure. Note that it does not
  545. * matter if the operation was executed *before* jtag_execute_queue(),
  546. * jtag_execute_queue() will still return an error code.
  547. *
  548. * All jtag_add_xxx() calls that have in_handler != NULL will have been
  549. * executed when this fn returns, but if what has been queued only
  550. * clocks data out, without reading anything back, then JTAG could
  551. * be running *after* jtag_execute_queue() returns. The API does
  552. * not define a way to flush a hw FIFO that runs *after*
  553. * jtag_execute_queue() returns.
  554. *
  555. * jtag_add_xxx() commands can either be executed immediately or
  556. * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
  557. */
  558. extern int jtag_execute_queue(void);
  559. /// same as jtag_execute_queue() but does not clear the error flag
  560. extern void jtag_execute_queue_noclear(void);
  561. /// @returns the number of times the scan queue has been flushed
  562. int jtag_get_flush_queue_count(void);
  563. /// Notify all TAP's about a TLR reset
  564. void jtag_notify_reset(void);
  565. /* can be implemented by hw + sw */
  566. extern int jtag_power_dropout(int* dropout);
  567. extern int jtag_srst_asserted(int* srst_asserted);
  568. /* JTAG support functions */
  569. /**
  570. * Execute jtag queue and check value with an optional mask.
  571. * @param field Pointer to scan field.
  572. * @param value Pointer to scan value.
  573. * @param mask Pointer to scan mask; may be NULL.
  574. * @returns Nothing, but calls jtag_set_error() on any error.
  575. */
  576. extern void jtag_check_value_mask(scan_field_t *field, uint8_t *value, uint8_t *mask);
  577. extern void jtag_sleep(uint32_t us);
  578. /*
  579. * The JTAG subsystem defines a number of error codes,
  580. * using codes between -100 and -199.
  581. */
  582. #define ERROR_JTAG_INIT_FAILED (-100)
  583. #define ERROR_JTAG_INVALID_INTERFACE (-101)
  584. #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
  585. #define ERROR_JTAG_TRST_ASSERTED (-103)
  586. #define ERROR_JTAG_QUEUE_FAILED (-104)
  587. #define ERROR_JTAG_NOT_STABLE_STATE (-105)
  588. #define ERROR_JTAG_DEVICE_ERROR (-107)
  589. #define ERROR_JTAG_STATE_INVALID (-108)
  590. #define ERROR_JTAG_TRANSITION_INVALID (-109)
  591. /**
  592. * jtag_add_dr_out() is a version of jtag_add_dr_scan() which
  593. * only scans data out. It operates on 32 bit integers instead
  594. * of 8 bit, which makes it a better impedance match with
  595. * the calling code which often operate on 32 bit integers.
  596. *
  597. * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
  598. *
  599. * num_bits[i] is the number of bits to clock out from value[i] LSB first.
  600. *
  601. * If the device is in bypass, then that is an error condition in
  602. * the caller code that is not detected by this fn, whereas
  603. * jtag_add_dr_scan() does detect it. Similarly if the device is not in
  604. * bypass, data must be passed to it.
  605. *
  606. * If anything fails, then jtag_error will be set and jtag_execute() will
  607. * return an error. There is no way to determine if there was a failure
  608. * during this function call.
  609. *
  610. * This is an inline fn to speed up embedded hosts. Also note that
  611. * interface_jtag_add_dr_out() can be a *small* inline function for
  612. * embedded hosts.
  613. *
  614. * There is no jtag_add_dr_outin() version of this fn that also allows
  615. * clocking data back in. Patches gladly accepted!
  616. */
  617. extern void jtag_add_dr_out(jtag_tap_t* tap,
  618. int num_fields, const int* num_bits, const uint32_t* value,
  619. tap_state_t end_state);
  620. /**
  621. * Set the current JTAG core execution error, unless one was set
  622. * by a previous call previously. Driver or application code must
  623. * use jtag_error_clear to reset jtag_error once this routine has been
  624. * called with a non-zero error code.
  625. */
  626. void jtag_set_error(int error);
  627. /// @returns The current value of jtag_error
  628. int jtag_get_error(void);
  629. /**
  630. * Resets jtag_error to ERROR_OK, returning its previous value.
  631. * @returns The previous value of @c jtag_error.
  632. */
  633. int jtag_error_clear(void);
  634. #endif /* JTAG_H */