OpenOCD
jtag.h
Go to the documentation of this file.
1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 
3 /***************************************************************************
4 * Copyright (C) 2005 by Dominic Rath *
5 * Dominic.Rath@gmx.de *
6 * *
7 * Copyright (C) 2007-2010 Øyvind Harboe *
8 * oyvind.harboe@zylin.com *
9 ***************************************************************************/
10 
11 #ifndef OPENOCD_JTAG_JTAG_H
12 #define OPENOCD_JTAG_JTAG_H
13 
14 #include <helper/binarybuffer.h>
15 #include <helper/log.h>
16 #include <helper/replacements.h>
17 
18 #ifndef DEBUG_JTAG_IOZ
19 #define DEBUG_JTAG_IOZ 64
20 #endif
21 
22 /*-----</Macros>-------------------------------------------------*/
23 
36 typedef enum tap_state {
38 
39  /* Proper ARM recommended numbers */
40  TAP_DREXIT2 = 0x0,
41  TAP_DREXIT1 = 0x1,
42  TAP_DRSHIFT = 0x2,
43  TAP_DRPAUSE = 0x3,
44  TAP_IRSELECT = 0x4,
45  TAP_DRUPDATE = 0x5,
47  TAP_DRSELECT = 0x7,
48  TAP_IREXIT2 = 0x8,
49  TAP_IREXIT1 = 0x9,
50  TAP_IRSHIFT = 0xa,
51  TAP_IRPAUSE = 0xb,
52  TAP_IDLE = 0xc,
53  TAP_IRUPDATE = 0xd,
55  TAP_RESET = 0x0f,
57 
61 #define SRST_DEASSERT 0
62 #define SRST_ASSERT 1
63 #define TRST_DEASSERT 0
64 #define TRST_ASSERT 1
65 
70 const char *tap_state_name(tap_state_t state);
71 
74 
77 
86 struct scan_field {
88  int num_bits;
90  const uint8_t *out_value;
92  uint8_t *in_value;
93 
95  uint8_t *check_value;
97  uint8_t *check_mask;
98 };
99 
100 struct jtag_tap {
101  char *chip;
102  char *tapname;
103  char *dotted_name;
108  bool enabled;
109  int ir_length;
111  uint8_t *expected;
112  uint32_t ir_capture_mask;
113  uint8_t *expected_mask;
114  uint32_t idcode;
117  bool hasidcode;
118 
120  uint32_t *expected_ids;
123 
126 
129 
131  uint8_t *cur_instr;
133  int bypass;
134 
136 
138  /* private pointer to support none-jtag specific functions */
139  void *priv;
140 };
141 
142 void jtag_tap_init(struct jtag_tap *tap);
143 void jtag_tap_free(struct jtag_tap *tap);
144 
145 struct jtag_tap *jtag_all_taps(void);
146 const char *jtag_tap_name(const struct jtag_tap *tap);
147 struct jtag_tap *jtag_tap_by_string(const char *dotted_name);
148 struct jtag_tap *jtag_tap_by_jim_obj(Jim_Interp *interp, Jim_Obj *obj);
149 struct jtag_tap *jtag_tap_by_position(unsigned abs_position);
150 struct jtag_tap *jtag_tap_next_enabled(struct jtag_tap *p);
151 unsigned jtag_tap_count_enabled(void);
152 unsigned jtag_tap_count(void);
153 
154 /*
155  * - TRST_ASSERTED triggers two sets of callbacks, after operations to
156  * reset the scan chain -- via TMS+TCK signaling, or deasserting the
157  * nTRST signal -- are queued:
158  *
159  * + Callbacks in C code fire first, patching internal state
160  * + Then post-reset event scripts fire ... activating JTAG circuits
161  * via TCK cycles, exiting SWD mode via TMS sequences, etc
162  *
163  * During those callbacks, scan chain contents have not been validated.
164  * JTAG operations that address a specific TAP (primarily DR/IR scans)
165  * must *not* be queued.
166  *
167  * - TAP_EVENT_SETUP is reported after TRST_ASSERTED, and after the scan
168  * chain has been validated. JTAG operations including scans that
169  * target specific TAPs may be performed.
170  *
171  * - TAP_EVENT_ENABLE and TAP_EVENT_DISABLE implement TAP activation and
172  * deactivation outside the core using scripted code that understands
173  * the specific JTAG router type. They might be triggered indirectly
174  * from EVENT_SETUP operations.
175  */
181 };
182 
185  enum jtag_event event;
187  Jim_Interp *interp;
189  Jim_Obj *body;
190  /* next action in linked list */
192 };
193 
205 typedef int (*jtag_event_handler_t)(enum jtag_event event, void *priv);
206 
209 
211 
213  RESET_NONE = 0x0,
222  RESET_CNCT_UNDER_SRST = 0x80
223 };
224 
227 
228 void jtag_set_nsrst_delay(unsigned delay);
229 unsigned jtag_get_nsrst_delay(void);
230 
231 void jtag_set_ntrst_delay(unsigned delay);
232 unsigned jtag_get_ntrst_delay(void);
233 
234 void jtag_set_nsrst_assert_width(unsigned delay);
235 unsigned jtag_get_nsrst_assert_width(void);
236 
237 void jtag_set_ntrst_assert_width(unsigned delay);
238 unsigned jtag_get_ntrst_assert_width(void);
239 
241 int jtag_get_trst(void);
243 int jtag_get_srst(void);
244 
246 void jtag_set_verify(bool enable);
248 bool jtag_will_verify(void);
249 
251 void jtag_set_verify_capture_ir(bool enable);
253 bool jtag_will_verify_capture_ir(void);
254 
256 void jtag_set_flush_queue_sleep(int ms);
257 
262 int jtag_init(struct command_context *cmd_ctx);
263 
265 int jtag_init_reset(struct command_context *cmd_ctx);
266 int jtag_register_commands(struct command_context *cmd_ctx);
267 int jtag_init_inner(struct command_context *cmd_ctx);
268 
294 void jtag_add_ir_scan(struct jtag_tap *tap,
295  struct scan_field *fields, tap_state_t endstate);
300 void jtag_add_ir_scan_noverify(struct jtag_tap *tap,
301  const struct scan_field *fields, tap_state_t state);
307 void jtag_add_plain_ir_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits,
308  tap_state_t endstate);
309 
316 void jtag_add_dr_scan(struct jtag_tap *tap, int num_fields,
317  const struct scan_field *fields, tap_state_t endstate);
319 void jtag_add_dr_scan_check(struct jtag_tap *tap, int num_fields,
320  struct scan_field *fields, tap_state_t endstate);
326 void jtag_add_plain_dr_scan(int num_bits,
327  const uint8_t *out_bits, uint8_t *in_bits, tap_state_t endstate);
328 
333 typedef intptr_t jtag_callback_data_t;
334 
343 typedef void (*jtag_callback1_t)(jtag_callback_data_t data0);
344 
347 
348 
377  jtag_callback_data_t data1,
378  jtag_callback_data_t data2,
379  jtag_callback_data_t data3);
380 
385 void jtag_add_tlr(void);
386 
435 void jtag_add_pathmove(int num_states, const tap_state_t *path);
436 
446 int jtag_add_statemove(tap_state_t goal_state);
447 
458 void jtag_add_runtest(int num_cycles, tap_state_t endstate);
459 
483 void jtag_add_reset(int req_tlr_or_trst, int srst);
484 
485 void jtag_add_sleep(uint32_t us);
486 
487 int jtag_add_tms_seq(unsigned nbits, const uint8_t *seq, enum tap_state t);
488 
494 void jtag_add_clocks(int num_cycles);
495 
516 int jtag_execute_queue(void);
517 
519 void jtag_execute_queue_noclear(void);
520 
523 
525 void jtag_notify_event(enum jtag_event);
526 
527 /* can be implemented by hw + sw */
528 int jtag_power_dropout(int *dropout);
530 
531 /* JTAG support functions */
532 
541 void jtag_check_value_mask(struct scan_field *field, uint8_t *value, uint8_t *mask);
542 
543 void jtag_sleep(uint32_t us);
544 
545 /*
546  * The JTAG subsystem defines a number of error codes,
547  * using codes between -100 and -199.
548  */
549 #define ERROR_JTAG_INIT_FAILED (-100)
550 #define ERROR_JTAG_INVALID_INTERFACE (-101)
551 #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
552 #define ERROR_JTAG_TRST_ASSERTED (-103)
553 #define ERROR_JTAG_QUEUE_FAILED (-104)
554 #define ERROR_JTAG_NOT_STABLE_STATE (-105)
555 #define ERROR_JTAG_DEVICE_ERROR (-107)
556 #define ERROR_JTAG_STATE_INVALID (-108)
557 #define ERROR_JTAG_TRANSITION_INVALID (-109)
558 #define ERROR_JTAG_INIT_SOFT_FAIL (-110)
559 
566 void jtag_set_error(int error);
571 int jtag_error_clear(void);
572 
578 bool is_jtag_poll_safe(void);
579 
583 bool jtag_poll_get_enabled(void);
584 
588 void jtag_poll_set_enabled(bool value);
589 
596 bool jtag_poll_mask(void);
597 
601 void jtag_poll_unmask(bool saved);
602 
603 #include <jtag/minidriver.h>
604 
605 int jim_jtag_newtap(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
606 
607 #endif /* OPENOCD_JTAG_JTAG_H */
const char * name
Definition: armv4_5.c:76
Support functions to access arbitrary bits in a byte array.
int mask
Definition: esirisc.c:1698
uint8_t type
Definition: esp_usb_jtag.c:0
static struct esp_usb_jtag * priv
Definition: esp_usb_jtag.c:219
void jtag_set_error(int error)
Set the current JTAG core execution error, unless one was set by a previous call previously.
Definition: jtag/core.c:123
int jtag_register_commands(struct command_context *cmd_ctx)
Definition: jtag/tcl.c:1369
void jtag_poll_unmask(bool saved)
Restore saved mask for polling.
Definition: jtag/core.c:177
void jtag_add_ir_scan_noverify(struct jtag_tap *tap, const struct scan_field *fields, tap_state_t state)
The same as jtag_add_ir_scan except no verification is performed out the output values.
Definition: jtag/core.c:356
int jtag_init_inner(struct command_context *cmd_ctx)
Definition: jtag/core.c:1503
void jtag_execute_queue_noclear(void)
same as jtag_execute_queue() but does not clear the error flag
Definition: jtag/core.c:1018
int(* jtag_event_handler_t)(enum jtag_event event, void *priv)
Defines the function signature required for JTAG event callback functions, which are added with jtag_...
Definition: jtag.h:205
int(* jtag_callback_t)(jtag_callback_data_t data0, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3)
Defines the interface of the JTAG callback mechanism.
Definition: jtag.h:376
tap_state
Defines JTAG Test Access Port states.
Definition: jtag.h:36
@ TAP_IRCAPTURE
Definition: jtag.h:54
@ TAP_RESET
Definition: jtag.h:55
@ TAP_DRCAPTURE
Definition: jtag.h:46
@ TAP_DRSELECT
Definition: jtag.h:47
@ TAP_DREXIT1
Definition: jtag.h:41
@ TAP_IREXIT1
Definition: jtag.h:49
@ TAP_DRPAUSE
Definition: jtag.h:43
@ TAP_IRSELECT
Definition: jtag.h:44
@ TAP_IRUPDATE
Definition: jtag.h:53
@ TAP_IREXIT2
Definition: jtag.h:48
@ TAP_IRSHIFT
Definition: jtag.h:50
@ TAP_DREXIT2
Definition: jtag.h:40
@ TAP_IDLE
Definition: jtag.h:52
@ TAP_DRSHIFT
Definition: jtag.h:42
@ TAP_IRPAUSE
Definition: jtag.h:51
@ TAP_DRUPDATE
Definition: jtag.h:45
@ TAP_INVALID
Definition: jtag.h:37
void jtag_set_ntrst_assert_width(unsigned delay)
Definition: jtag/core.c:1778
int jtag_unregister_event_callback(jtag_event_handler_t f, void *x)
Definition: jtag/core.c:303
struct jtag_tap * jtag_tap_by_position(unsigned abs_position)
Definition: jtag/core.c:227
int jtag_get_trst(void)
Definition: jtag/core.c:1743
const char * tap_state_name(tap_state_t state)
Function tap_state_name Returns a string suitable for display representing the JTAG tap_state.
Definition: interface.c:344
void jtag_add_pathmove(int num_states, const tap_state_t *path)
Application code must assume that interfaces will implement transitions between states with different...
Definition: jtag/core.c:517
void jtag_set_ntrst_delay(unsigned delay)
Definition: jtag/core.c:1760
void jtag_add_runtest(int num_cycles, tap_state_t endstate)
Goes to TAP_IDLE (if we're not already there), cycle precisely num_cycles in the TAP_IDLE state,...
Definition: jtag/core.c:592
int jtag_init(struct command_context *cmd_ctx)
Initialize JTAG chain using only a RESET reset.
Definition: jtag/core.c:1664
void jtag_poll_set_enabled(bool value)
Assign flag reporting whether JTAG polling is disallowed.
Definition: jtag/core.c:165
int jtag_srst_asserted(int *srst_asserted)
Definition: jtag/core.c:1725
struct jtag_tap * jtag_tap_by_string(const char *dotted_name)
Definition: jtag/core.c:237
void jtag_add_clocks(int num_cycles)
Function jtag_add_clocks first checks that the state in which the clocks are to be issued is stable,...
Definition: jtag/core.c:599
void jtag_add_plain_dr_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits, tap_state_t endstate)
Scan out the bits in ir scan mode.
Definition: jtag/core.c:465
int jtag_execute_queue(void)
For software FIFO implementations, the queued commands can be executed during this call or earlier.
Definition: jtag/core.c:1037
unsigned jtag_tap_count_enabled(void)
Definition: jtag/core.c:200
unsigned jtag_get_ntrst_delay(void)
Definition: jtag/core.c:1764
void jtag_add_dr_scan(struct jtag_tap *tap, int num_fields, const struct scan_field *fields, tap_state_t endstate)
Generate a DR SCAN using the fields passed to the function.
Definition: jtag/core.c:451
void jtag_set_flush_queue_sleep(int ms)
Set ms to sleep after jtag_execute_queue() flushes queue.
Definition: jtag/core.c:118
bool is_jtag_poll_safe(void)
Return true if it's safe for a background polling task to access the JTAG scan chain.
Definition: jtag/core.c:142
const char * jtag_tap_name(const struct jtag_tap *tap)
Definition: jtag/core.c:276
struct jtag_tap * jtag_all_taps(void)
Definition: jtag/core.c:184
jtag_event
Definition: jtag.h:176
@ JTAG_TAP_EVENT_ENABLE
Definition: jtag.h:179
@ JTAG_TAP_EVENT_SETUP
Definition: jtag.h:178
@ JTAG_TRST_ASSERTED
Definition: jtag.h:177
@ JTAG_TAP_EVENT_DISABLE
Definition: jtag.h:180
int jtag_power_dropout(int *dropout)
Definition: jtag/core.c:1710
tap_state_t cmd_queue_cur_state
The current TAP state of the pending JTAG command queue.
Definition: jtag/core.c:88
int jtag_add_tms_seq(unsigned nbits, const uint8_t *seq, enum tap_state t)
If supported by the underlying adapter, this clocks a raw bit sequence onto TMS for switching between...
Definition: jtag/core.c:502
int jtag_add_statemove(tap_state_t goal_state)
jtag_add_statemove() moves from the current state to goal_state.
Definition: jtag/core.c:551
void jtag_add_callback(jtag_callback1_t f, jtag_callback_data_t data0)
A simpler version of jtag_add_callback4().
void jtag_set_nsrst_assert_width(unsigned delay)
Definition: jtag/core.c:1770
int jtag_get_flush_queue_count(void)
Definition: jtag/core.c:1032
unsigned jtag_get_nsrst_delay(void)
Definition: jtag/core.c:1756
int jtag_init_reset(struct command_context *cmd_ctx)
reset, then initialize JTAG chain
Definition: jtag/core.c:1600
void jtag_add_reset(int req_tlr_or_trst, int srst)
A reset of the TAP state machine can be requested.
Definition: jtag/core.c:758
struct jtag_tap * jtag_tap_next_enabled(struct jtag_tap *p)
Definition: jtag/core.c:265
void jtag_add_tlr(void)
Run a TAP_RESET reset where the end state is TAP_RESET, regardless of the start state.
Definition: jtag/core.c:478
void jtag_set_nsrst_delay(unsigned delay)
Definition: jtag/core.c:1752
unsigned jtag_tap_count(void)
Definition: jtag/core.c:189
bool jtag_poll_get_enabled(void)
Return flag reporting whether JTAG polling is disallowed.
Definition: jtag/core.c:160
bool jtag_will_verify(void)
Definition: jtag/core.c:1695
int jtag_call_event_callbacks(enum jtag_event event)
Definition: jtag/core.c:324
int jtag_get_srst(void)
Definition: jtag/core.c:1747
unsigned jtag_get_ntrst_assert_width(void)
Definition: jtag/core.c:1782
reset_types
Definition: jtag.h:212
@ RESET_NONE
Definition: jtag.h:213
@ RESET_SRST_NO_GATING
Definition: jtag.h:221
@ RESET_HAS_SRST
Definition: jtag.h:215
@ RESET_HAS_TRST
Definition: jtag.h:214
@ RESET_TRST_PULLS_SRST
Definition: jtag.h:218
@ RESET_CNCT_UNDER_SRST
Definition: jtag.h:222
@ RESET_SRST_PULLS_TRST
Definition: jtag.h:217
@ RESET_TRST_OPEN_DRAIN
Definition: jtag.h:219
@ RESET_TRST_AND_SRST
Definition: jtag.h:216
@ RESET_SRST_PUSH_PULL
Definition: jtag.h:220
void jtag_set_verify_capture_ir(bool enable)
Enable or disable verification of IR scan checking.
Definition: jtag/core.c:1700
enum tap_state tap_state_t
Defines JTAG Test Access Port states.
void jtag_add_sleep(uint32_t us)
Definition: jtag/core.c:870
bool jtag_will_verify_capture_ir(void)
Definition: jtag/core.c:1705
void jtag_tap_free(struct jtag_tap *tap)
Definition: jtag/core.c:1481
int jtag_register_event_callback(jtag_event_handler_t f, void *x)
Definition: jtag/core.c:282
tap_state_t tap_state_by_name(const char *name)
Provides user-friendly name lookup of TAP states.
Definition: interface.c:355
void jtag_add_ir_scan(struct jtag_tap *tap, struct scan_field *fields, tap_state_t endstate)
Generate an IR SCAN with a list of scan fields with one entry for each enabled TAP.
Definition: jtag/core.c:374
struct jtag_tap * jtag_tap_by_jim_obj(Jim_Interp *interp, Jim_Obj *obj)
Definition: jtag/tcl.c:51
void jtag_check_value_mask(struct scan_field *field, uint8_t *value, uint8_t *mask)
Execute jtag queue and check value with an optional mask.
Definition: jtag/core.c:917
void jtag_sleep(uint32_t us)
Definition: jtag/core.c:1062
unsigned jtag_get_nsrst_assert_width(void)
Definition: jtag/core.c:1774
void jtag_add_dr_scan_check(struct jtag_tap *tap, int num_fields, struct scan_field *fields, tap_state_t endstate)
A version of jtag_add_dr_scan() that uses the check_value/mask fields.
Definition: jtag/core.c:439
void jtag_tap_init(struct jtag_tap *tap)
Definition: jtag/core.c:1446
void jtag_set_reset_config(enum reset_types type)
Definition: jtag/core.c:1738
int jtag_error_clear(void)
Resets jtag_error to ERROR_OK, returning its previous value.
Definition: jtag/core.c:130
enum reset_types jtag_get_reset_config(void)
Definition: jtag/core.c:1734
int jim_jtag_newtap(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
Definition: jtag/tcl.c:715
void jtag_add_plain_ir_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits, tap_state_t endstate)
Scan out the bits in ir scan mode.
Definition: jtag/core.c:392
void jtag_notify_event(enum jtag_event)
Report Tcl event to all TAPs.
Definition: jtag/tcl.c:940
intptr_t jtag_callback_data_t
Defines the type of data passed to the jtag_callback_t interface.
Definition: jtag.h:333
bool jtag_poll_mask(void)
Mask (disable) polling and return the current mask status that should be feed to jtag_poll_unmask() t...
Definition: jtag/core.c:170
void(* jtag_callback1_t)(jtag_callback_data_t data0)
Defines a simple JTAG callback that can allow conversions on data scanned in from an interface.
Definition: jtag.h:343
void jtag_set_verify(bool enable)
Enable or disable data scan verification checking.
Definition: jtag/core.c:1690
struct jtag_tap_event_action * next
Definition: jtag.h:191
enum jtag_event event
The event for which this action will be triggered.
Definition: jtag.h:185
Jim_Obj * body
Contains a script to 'eval' when the event is triggered.
Definition: jtag.h:189
Jim_Interp * interp
The interpreter to use for evaluating the body.
Definition: jtag.h:187
Definition: jtag.h:100
uint32_t ir_capture_value
Definition: jtag.h:110
int abs_chain_position
Definition: jtag.h:104
uint8_t * expected_mask
Capture-IR expected mask.
Definition: jtag.h:113
char * chip
Definition: jtag.h:101
bool ignore_version
Flag saying whether to ignore version field in expected_ids[].
Definition: jtag.h:125
bool disabled_after_reset
Is this TAP disabled after JTAG reset?
Definition: jtag.h:106
struct jtag_tap_event_action * event_action
Definition: jtag.h:135
uint8_t * cur_instr
current instruction
Definition: jtag.h:131
int ir_length
size of instruction register
Definition: jtag.h:109
void * priv
Definition: jtag.h:139
uint8_t * expected
Capture-IR expected value.
Definition: jtag.h:111
uint32_t ir_capture_mask
Definition: jtag.h:112
uint8_t expected_ids_cnt
Number of expected identification codes.
Definition: jtag.h:122
bool hasidcode
not all devices have idcode, we'll discover this during chain examination
Definition: jtag.h:117
char * tapname
Definition: jtag.h:102
bool ignore_bypass
Flag saying whether to ignore the bypass bit in the code.
Definition: jtag.h:128
bool enabled
Is this TAP currently enabled?
Definition: jtag.h:108
uint32_t * expected_ids
Array of expected identification codes.
Definition: jtag.h:120
struct jtag_tap * next_tap
Definition: jtag.h:137
int bypass
Bypass register selected.
Definition: jtag.h:133
uint32_t idcode
device identification code
Definition: jtag.h:114
char * dotted_name
Definition: jtag.h:103
This structure defines a single scan field in the scan.
Definition: jtag.h:86
int num_bits
The number of bits this field specifies.
Definition: jtag.h:88
uint8_t * in_value
A pointer to a 32-bit memory location for data scanned out.
Definition: jtag.h:92
uint8_t * check_value
The value used to check the data scanned out.
Definition: jtag.h:95
const uint8_t * out_value
A pointer to value to be scanned into the device.
Definition: jtag.h:90
uint8_t * check_mask
The mask to go with check_value.
Definition: jtag.h:97
static int srst_asserted
Definition: target.c:2916
uint8_t state[4]
Definition: vdebug.c:21