1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3 /***************************************************************************
4 * Copyright (C) 2005 by Dominic Rath *
5 * Dominic.Rath@gmx.de *
7 * Copyright (C) 2007-2010 Øyvind Harboe *
8 * oyvind.harboe@zylin.com *
9 ***************************************************************************/
11 #ifndef OPENOCD_JTAG_JTAG_H
12 #define OPENOCD_JTAG_JTAG_H
14 #include <helper/binarybuffer.h>
15 #include <helper/command.h>
16 #include <helper/log.h>
17 #include <helper/replacements.h>
19 #ifndef DEBUG_JTAG_IOZ
20 #define DEBUG_JTAG_IOZ 64
23 /*-----</Macros>-------------------------------------------------*/
26 * Defines JTAG Test Access Port states.
28 * These definitions were gleaned from the ARM7TDMI-S Technical
29 * Reference Manual and validated against several other ARM core
32 * FIXME some interfaces require specific numbers be used, as they
33 * are handed-off directly to their hardware implementations.
34 * Fix those drivers to map as appropriate ... then pick some
35 * sane set of numbers here (where 0/uninitialized == INVALID).
37 typedef enum tap_state
{
40 /* Proper ARM recommended numbers */
60 * Defines arguments for reset functions
62 #define SRST_DEASSERT 0
64 #define TRST_DEASSERT 0
68 * Function tap_state_name
69 * Returns a string suitable for display representing the JTAG tap_state
71 const char *tap_state_name(tap_state_t state
);
73 /** Provides user-friendly name lookup of TAP states. */
74 tap_state_t
tap_state_by_name(const char *name
);
76 /** The current TAP state of the pending JTAG command queue. */
77 extern tap_state_t cmd_queue_cur_state
;
80 * This structure defines a single scan field in the scan. It provides
81 * fields for the field's width and pointers to scan input and output
84 * In addition, this structure includes a value and mask that is used by
85 * jtag_add_dr_scan_check() to validate the value that was scanned out.
88 /** The number of bits this field specifies */
90 /** A pointer to value to be scanned into the device */
91 const uint8_t *out_value
;
92 /** A pointer to a 32-bit memory location for data scanned out */
95 /** The value used to check the data scanned out. */
97 /** The mask to go with check_value */
105 int abs_chain_position
;
106 /** Is this TAP disabled after JTAG reset? */
107 bool disabled_after_reset
;
108 /** Is this TAP currently enabled? */
110 int ir_length
; /**< size of instruction register */
111 uint32_t ir_capture_value
;
112 uint8_t *expected
; /**< Capture-IR expected value */
113 uint32_t ir_capture_mask
;
114 uint8_t *expected_mask
; /**< Capture-IR expected mask */
115 uint32_t idcode
; /**< device identification code */
116 /** not all devices have idcode,
117 * we'll discover this during chain examination */
120 /** Array of expected identification codes */
121 uint32_t *expected_ids
;
122 /** Number of expected identification codes */
123 uint8_t expected_ids_cnt
;
125 /** Flag saying whether to ignore version field in expected_ids[] */
128 /** Flag saying whether to ignore the bypass bit in the code */
131 /** current instruction */
133 /** Bypass register selected */
136 /** Bypass instruction value */
137 uint64_t ir_bypass_value
;
139 struct jtag_tap_event_action
*event_action
;
141 struct jtag_tap
*next_tap
;
142 /* private pointer to support none-jtag specific functions */
146 void jtag_tap_init(struct jtag_tap
*tap
);
147 void jtag_tap_free(struct jtag_tap
*tap
);
149 struct jtag_tap
*jtag_all_taps(void);
150 const char *jtag_tap_name(const struct jtag_tap
*tap
);
151 struct jtag_tap
*jtag_tap_by_string(const char *dotted_name
);
152 struct jtag_tap
*jtag_tap_by_jim_obj(Jim_Interp
*interp
, Jim_Obj
*obj
);
153 struct jtag_tap
*jtag_tap_by_position(unsigned abs_position
);
154 struct jtag_tap
*jtag_tap_next_enabled(struct jtag_tap
*p
);
155 unsigned jtag_tap_count_enabled(void);
156 unsigned jtag_tap_count(void);
159 * - TRST_ASSERTED triggers two sets of callbacks, after operations to
160 * reset the scan chain -- via TMS+TCK signaling, or deasserting the
161 * nTRST signal -- are queued:
163 * + Callbacks in C code fire first, patching internal state
164 * + Then post-reset event scripts fire ... activating JTAG circuits
165 * via TCK cycles, exiting SWD mode via TMS sequences, etc
167 * During those callbacks, scan chain contents have not been validated.
168 * JTAG operations that address a specific TAP (primarily DR/IR scans)
169 * must *not* be queued.
171 * - TAP_EVENT_SETUP is reported after TRST_ASSERTED, and after the scan
172 * chain has been validated. JTAG operations including scans that
173 * target specific TAPs may be performed.
175 * - TAP_EVENT_ENABLE and TAP_EVENT_DISABLE implement TAP activation and
176 * deactivation outside the core using scripted code that understands
177 * the specific JTAG router type. They might be triggered indirectly
178 * from EVENT_SETUP operations.
182 JTAG_TAP_EVENT_SETUP
,
183 JTAG_TAP_EVENT_ENABLE
,
184 JTAG_TAP_EVENT_DISABLE
,
187 struct jtag_tap_event_action
{
188 /** The event for which this action will be triggered. */
189 enum jtag_event event
;
190 /** The interpreter to use for evaluating the @c body. */
192 /** Contains a script to 'eval' when the @c event is triggered. */
194 /* next action in linked list */
195 struct jtag_tap_event_action
*next
;
199 * Defines the function signature required for JTAG event callback
200 * functions, which are added with jtag_register_event_callback()
201 * and removed jtag_unregister_event_callback().
202 * @param event The event to handle.
203 * @param priv A pointer to data that was passed to
204 * jtag_register_event_callback().
205 * @returns Must return ERROR_OK on success, or an error code on failure.
207 * @todo Change to return void or define a use for its return code.
209 typedef int (*jtag_event_handler_t
)(enum jtag_event event
, void *priv
);
211 int jtag_register_event_callback(jtag_event_handler_t f
, void *x
);
212 int jtag_unregister_event_callback(jtag_event_handler_t f
, void *x
);
214 int jtag_call_event_callbacks(enum jtag_event event
);
218 RESET_HAS_TRST
= 0x1,
219 RESET_HAS_SRST
= 0x2,
220 RESET_TRST_AND_SRST
= 0x3,
221 RESET_SRST_PULLS_TRST
= 0x4,
222 RESET_TRST_PULLS_SRST
= 0x8,
223 RESET_TRST_OPEN_DRAIN
= 0x10,
224 RESET_SRST_PUSH_PULL
= 0x20,
225 RESET_SRST_NO_GATING
= 0x40,
226 RESET_CNCT_UNDER_SRST
= 0x80
229 enum reset_types
jtag_get_reset_config(void);
230 void jtag_set_reset_config(enum reset_types type
);
232 void jtag_set_nsrst_delay(unsigned delay
);
233 unsigned jtag_get_nsrst_delay(void);
235 void jtag_set_ntrst_delay(unsigned delay
);
236 unsigned jtag_get_ntrst_delay(void);
238 void jtag_set_nsrst_assert_width(unsigned delay
);
239 unsigned jtag_get_nsrst_assert_width(void);
241 void jtag_set_ntrst_assert_width(unsigned delay
);
242 unsigned jtag_get_ntrst_assert_width(void);
244 /** @returns The current state of TRST. */
245 int jtag_get_trst(void);
246 /** @returns The current state of SRST. */
247 int jtag_get_srst(void);
249 /** Enable or disable data scan verification checking. */
250 void jtag_set_verify(bool enable
);
251 /** @returns True if data scan verification will be performed. */
252 bool jtag_will_verify(void);
254 /** Enable or disable verification of IR scan checking. */
255 void jtag_set_verify_capture_ir(bool enable
);
256 /** @returns True if IR scan verification will be performed. */
257 bool jtag_will_verify_capture_ir(void);
259 /** Set ms to sleep after jtag_execute_queue() flushes queue. Debug purposes. */
260 void jtag_set_flush_queue_sleep(int ms
);
263 * Initialize JTAG chain using only a RESET reset. If init fails,
266 int jtag_init(struct command_context
*cmd_ctx
);
268 /** reset, then initialize JTAG chain */
269 int jtag_init_reset(struct command_context
*cmd_ctx
);
270 int jtag_register_commands(struct command_context
*cmd_ctx
);
271 int jtag_init_inner(struct command_context
*cmd_ctx
);
275 * The JTAG interface can be implemented with a software or hardware fifo.
277 * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states; however,
278 * TAP_DRSHIFT/IRSHIFT can be emulated as end states, by using longer
281 * Code that is relatively insensitive to the path taken through state
282 * machine (as long as it is JTAG compliant) can use @a endstate for
283 * jtag_add_xxx_scan(). Otherwise, the pause state must be specified as
284 * end state and a subsequent jtag_add_pathmove() must be issued.
288 * Generate an IR SCAN with a list of scan fields with one entry for
291 * If the input field list contains an instruction value for a TAP then
292 * that is used otherwise the TAP is set to bypass.
294 * TAPs for which no fields are passed are marked as bypassed for
295 * subsequent DR SCANs.
298 void jtag_add_ir_scan(struct jtag_tap
*tap
,
299 struct scan_field
*fields
, tap_state_t endstate
);
301 * The same as jtag_add_ir_scan except no verification is performed out
304 void jtag_add_ir_scan_noverify(struct jtag_tap
*tap
,
305 const struct scan_field
*fields
, tap_state_t state
);
307 * Scan out the bits in ir scan mode.
309 * If in_bits == NULL, discard incoming bits.
311 void jtag_add_plain_ir_scan(int num_bits
, const uint8_t *out_bits
, uint8_t *in_bits
,
312 tap_state_t endstate
);
315 * Generate a DR SCAN using the fields passed to the function.
316 * For connected TAPs, the function checks in_fields and uses fields
317 * specified there. For bypassed TAPs, the function generates a dummy
318 * 1-bit field. The bypass status of TAPs is set by jtag_add_ir_scan().
320 void jtag_add_dr_scan(struct jtag_tap
*tap
, int num_fields
,
321 const struct scan_field
*fields
, tap_state_t endstate
);
322 /** A version of jtag_add_dr_scan() that uses the check_value/mask fields */
323 void jtag_add_dr_scan_check(struct jtag_tap
*tap
, int num_fields
,
324 struct scan_field
*fields
, tap_state_t endstate
);
326 * Scan out the bits in ir scan mode.
328 * If in_bits == NULL, discard incoming bits.
330 void jtag_add_plain_dr_scan(int num_bits
,
331 const uint8_t *out_bits
, uint8_t *in_bits
, tap_state_t endstate
);
334 * Defines the type of data passed to the jtag_callback_t interface.
335 * The underlying type must allow storing an @c int or pointer type.
337 typedef intptr_t jtag_callback_data_t
;
340 * Defines a simple JTAG callback that can allow conversions on data
341 * scanned in from an interface.
343 * This callback should only be used for conversion that cannot fail.
344 * For conversion types or checks that can fail, use the more complete
345 * variant: jtag_callback_t.
347 typedef void (*jtag_callback1_t
)(jtag_callback_data_t data0
);
349 /** A simpler version of jtag_add_callback4(). */
350 void jtag_add_callback(jtag_callback1_t f
, jtag_callback_data_t data0
);
354 * Defines the interface of the JTAG callback mechanism. Such
355 * callbacks can be executed once the queue has been flushed.
357 * The JTAG queue can be executed synchronously or asynchronously.
358 * Typically for USB, the queue is executed asynchronously. For
359 * low-latency interfaces, the queue may be executed synchronously.
361 * The callback mechanism is very general and does not make many
362 * assumptions about what the callback does or what its arguments are.
363 * These callbacks are typically executed *after* the *entire* JTAG
364 * queue has been executed for e.g. USB interfaces, and they are
365 * guaranteed to be invoked in the order that they were queued.
367 * If the execution of the queue fails before the callbacks, then --
368 * depending on driver implementation -- the callbacks may or may not be
371 * @todo Make that behavior consistent.
373 * @param data0 Typically used to point to the data to operate on.
374 * Frequently this will be the data clocked in during a shift operation.
375 * @param data1 An integer big enough to use as an @c int or a pointer.
376 * @param data2 An integer big enough to use as an @c int or a pointer.
377 * @param data3 An integer big enough to use as an @c int or a pointer.
378 * @returns an error code
380 typedef int (*jtag_callback_t
)(jtag_callback_data_t data0
,
381 jtag_callback_data_t data1
,
382 jtag_callback_data_t data2
,
383 jtag_callback_data_t data3
);
386 * Run a TAP_RESET reset where the end state is TAP_RESET,
387 * regardless of the start state.
389 void jtag_add_tlr(void);
392 * Application code *must* assume that interfaces will
393 * implement transitions between states with different
394 * paths and path lengths through the state diagram. The
395 * path will vary across interface and also across versions
396 * of the same interface over time. Even if the OpenOCD code
397 * is unchanged, the actual path taken may vary over time
398 * and versions of interface firmware or PCB revisions.
400 * Use jtag_add_pathmove() when specific transition sequences
403 * Do not use jtag_add_pathmove() unless you need to, but do use it
406 * DANGER! If the target is dependent upon a particular sequence
407 * of transitions for things to work correctly(e.g. as a workaround
408 * for an errata that contradicts the JTAG standard), then pathmove
409 * must be used, even if some jtag interfaces happen to use the
410 * desired path. Worse, the jtag interface used for testing a
411 * particular implementation, could happen to use the "desired"
412 * path when transitioning to/from end
415 * A list of unambiguous single clock state transitions, not
416 * all drivers can support this, but it is required for e.g.
417 * XScale and Xilinx support
419 * Note! TAP_RESET must not be used in the path!
421 * Note that the first on the list must be reachable
422 * via a single transition from the current state.
424 * All drivers are required to implement jtag_add_pathmove().
425 * However, if the pathmove sequence can not be precisely
426 * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
427 * must return an error. It is legal, but not recommended, that
428 * a driver returns an error in all cases for a pathmove if it
429 * can only implement a few transitions and therefore
430 * a partial implementation of pathmove would have little practical
433 * If an error occurs, jtag_error will contain one of these error codes:
434 * - ERROR_JTAG_NOT_STABLE_STATE -- The final state was not stable.
435 * - ERROR_JTAG_STATE_INVALID -- The path passed through TAP_RESET.
436 * - ERROR_JTAG_TRANSITION_INVALID -- The path includes invalid
439 void jtag_add_pathmove(int num_states
, const tap_state_t
*path
);
442 * jtag_add_statemove() moves from the current state to @a goal_state.
444 * @param goal_state The final TAP state.
445 * @return ERROR_OK on success, or an error code on failure.
447 * Moves from the current state to the goal \a state.
448 * Both states must be stable.
450 int jtag_add_statemove(tap_state_t goal_state
);
453 * Goes to TAP_IDLE (if we're not already there), cycle
454 * precisely num_cycles in the TAP_IDLE state, after which move
455 * to @a endstate (unless it is also TAP_IDLE).
457 * @param num_cycles Number of cycles in TAP_IDLE state. This argument
458 * may be 0, in which case this routine will navigate to @a endstate
460 * @param endstate The final state.
462 void jtag_add_runtest(int num_cycles
, tap_state_t endstate
);
465 * A reset of the TAP state machine can be requested.
467 * Whether tms or trst reset is used depends on the capabilities of
468 * the target and jtag interface(reset_config command configures this).
470 * srst can driver a reset of the TAP state machine and vice
473 * Application code may need to examine value of jtag_reset_config
474 * to determine the proper codepath
476 * DANGER! Even though srst drives trst, trst might not be connected to
477 * the interface, and it might actually be *harmful* to assert trst in this case.
479 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
482 * only req_tlr_or_trst and srst can have a transition for a
483 * call as the effects of transitioning both at the "same time"
484 * are undefined, but when srst_pulls_trst or vice versa,
485 * then trst & srst *must* be asserted together.
487 void jtag_add_reset(int req_tlr_or_trst
, int srst
);
489 void jtag_add_sleep(uint32_t us
);
491 int jtag_add_tms_seq(unsigned nbits
, const uint8_t *seq
, enum tap_state t
);
494 * Function jtag_add_clocks
495 * first checks that the state in which the clocks are to be issued is
496 * stable, then queues up num_cycles clocks for transmission.
498 void jtag_add_clocks(int num_cycles
);
501 * For software FIFO implementations, the queued commands can be executed
502 * during this call or earlier. A sw queue might decide to push out
503 * some of the jtag_add_xxx() operations once the queue is "big enough".
505 * This fn will return an error code if any of the prior jtag_add_xxx()
506 * calls caused a failure, e.g. check failure. Note that it does not
507 * matter if the operation was executed *before* jtag_execute_queue(),
508 * jtag_execute_queue() will still return an error code.
510 * All jtag_add_xxx() calls that have in_handler != NULL will have been
511 * executed when this fn returns, but if what has been queued only
512 * clocks data out, without reading anything back, then JTAG could
513 * be running *after* jtag_execute_queue() returns. The API does
514 * not define a way to flush a hw FIFO that runs *after*
515 * jtag_execute_queue() returns.
517 * jtag_add_xxx() commands can either be executed immediately or
518 * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
520 int jtag_execute_queue(void);
522 /** same as jtag_execute_queue() but does not clear the error flag */
523 void jtag_execute_queue_noclear(void);
525 /** @returns the number of times the scan queue has been flushed */
526 int jtag_get_flush_queue_count(void);
528 /** Report Tcl event to all TAPs */
529 void jtag_notify_event(enum jtag_event
);
531 /* can be implemented by hw + sw */
532 int jtag_power_dropout(int *dropout
);
533 int jtag_srst_asserted(int *srst_asserted
);
535 /* JTAG support functions */
538 * Execute jtag queue and check value with an optional mask.
539 * @param field Pointer to scan field.
540 * @param value Pointer to scan value.
541 * @param mask Pointer to scan mask; may be NULL.
543 * returns Nothing, but calls jtag_set_error() on any error.
545 void jtag_check_value_mask(struct scan_field
*field
, uint8_t *value
, uint8_t *mask
);
547 void jtag_sleep(uint32_t us
);
550 * The JTAG subsystem defines a number of error codes,
551 * using codes between -100 and -199.
553 #define ERROR_JTAG_INIT_FAILED (-100)
554 #define ERROR_JTAG_INVALID_INTERFACE (-101)
555 #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
556 #define ERROR_JTAG_TRST_ASSERTED (-103)
557 #define ERROR_JTAG_QUEUE_FAILED (-104)
558 #define ERROR_JTAG_NOT_STABLE_STATE (-105)
559 #define ERROR_JTAG_DEVICE_ERROR (-107)
560 #define ERROR_JTAG_STATE_INVALID (-108)
561 #define ERROR_JTAG_TRANSITION_INVALID (-109)
562 #define ERROR_JTAG_INIT_SOFT_FAIL (-110)
565 * Set the current JTAG core execution error, unless one was set
566 * by a previous call previously. Driver or application code must
567 * use jtag_error_clear to reset jtag_error once this routine has been
568 * called with a non-zero error code.
570 void jtag_set_error(int error
);
572 * Resets jtag_error to ERROR_OK, returning its previous value.
573 * @returns The previous value of @c jtag_error.
575 int jtag_error_clear(void);
578 * Return true if it's safe for a background polling task to access the
579 * JTAG scan chain. Polling may be explicitly disallowed, and is also
580 * unsafe while nTRST is active or the JTAG clock is gated off.
582 bool is_jtag_poll_safe(void);
585 * Return flag reporting whether JTAG polling is disallowed.
587 bool jtag_poll_get_enabled(void);
590 * Assign flag reporting whether JTAG polling is disallowed.
592 void jtag_poll_set_enabled(bool value
);
595 * Mask (disable) polling and return the current mask status that should be
596 * feed to jtag_poll_unmask() to restore it.
597 * Multiple nested calls to jtag_poll_mask() are allowed, each balanced with
598 * its call to jtag_poll_unmask().
600 bool jtag_poll_mask(void);
603 * Restore saved mask for polling.
605 void jtag_poll_unmask(bool saved
);
607 #include <jtag/minidriver.h>
609 __COMMAND_HANDLER(handle_jtag_newtap
);
611 #endif /* OPENOCD_JTAG_JTAG_H */
Linking to existing account procedure
If you already have an account and want to add another login method
you
MUST first sign in with your existing account and
then change URL to read
https://review.openocd.org/login/?link
to get to this page again but this time it'll work for linking. Thank you.
SSH host keys fingerprints
1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=.. |
|+o.. . |
|*.o . . |
|+B . . . |
|Bo. = o S |
|Oo.+ + = |
|oB=.* = . o |
| =+=.+ + E |
|. .=o . o |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)