1 /***************************************************************************
2 * Copyright (C) 2005 by Dominic Rath *
3 * Dominic.Rath@gmx.de *
5 * Copyright (C) 2007,2008 Øyvind Harboe *
6 * oyvind.harboe@zylin.com *
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. *
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. *
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 ***************************************************************************/
26 #include "binarybuffer.h"
30 #ifdef _DEBUG_JTAG_IO_
31 #define DEBUG_JTAG_IO(expr ...) LOG_DEBUG(expr)
33 #define DEBUG_JTAG_IO(expr ...)
36 #ifndef DEBUG_JTAG_IOZ
37 #define DEBUG_JTAG_IOZ 64
40 /*-----<Macros>--------------------------------------------------*/
42 /** When given an array, compute its DIMension, i.e. number of elements in the array */
43 #define DIM(x) (sizeof(x)/sizeof((x)[0]))
45 /** Calculate the number of bytes required to hold @a n TAP scan bits */
46 #define TAP_SCAN_BYTES(n) CEIL(n, 8)
48 /*-----</Macros>-------------------------------------------------*/
53 * Tap states from ARM7TDMI-S Technical reference manual.
54 * Also, validated against several other ARM core technical manuals.
56 * N.B. tap_get_tms_path() was changed to reflect this corrected
57 * numbering and ordering of the TAP states.
59 * DANGER!!!! some interfaces care about the actual numbers used
60 * as they are handed off directly to hardware implementations.
63 typedef enum tap_state
66 /* These are the old numbers. Leave as-is for now... */
67 TAP_RESET
= 0, TAP_IDLE
= 8,
68 TAP_DRSELECT
= 1, TAP_DRCAPTURE
= 2, TAP_DRSHIFT
= 3, TAP_DREXIT1
= 4,
69 TAP_DRPAUSE
= 5, TAP_DREXIT2
= 6, TAP_DRUPDATE
= 7,
70 TAP_IRSELECT
= 9, TAP_IRCAPTURE
= 10, TAP_IRSHIFT
= 11, TAP_IREXIT1
= 12,
71 TAP_IRPAUSE
= 13, TAP_IREXIT2
= 14, TAP_IRUPDATE
= 15,
73 TAP_NUM_STATES
= 16, TAP_INVALID
= -1,
75 /* Proper ARM recommended numbers */
93 TAP_NUM_STATES
= 0x10,
100 * Function tap_state_name
101 * Returns a string suitable for display representing the JTAG tap_state
103 const char* tap_state_name(tap_state_t state
);
105 typedef struct tap_transition_s
111 //extern tap_transition_t tap_transitions[16]; /* describe the TAP state diagram */
115 extern tap_state_t cmd_queue_end_state
; /* finish DR scans in dr_end_state */
116 extern tap_state_t cmd_queue_cur_state
; /* current TAP state */
118 typedef struct scan_field_s
120 jtag_tap_t
* tap
; /* tap pointer this instruction refers to */
121 int num_bits
; /* number of bits this field specifies (up to 32) */
122 u8
* out_value
; /* value to be scanned into the device */
123 u8
* in_value
; /* pointer to a 32-bit memory location to take data scanned out */
125 u8
* check_value
; /* Used together with jtag_add_dr_scan_check() to check data clocked
127 u8
* check_mask
; /* mask to go with check_value */
129 /* internal work space */
130 int allocated
; /* in_value has been allocated for the queue */
131 int modified
; /* did we modify the in_value? */
132 u8 intmp
[4]; /* temporary storage for checking synchronously */
135 #ifdef INCLUDE_JTAG_INTERFACE_H
138 /* IN: from device to host, OUT: from host to device */
139 SCAN_IN
= 1, SCAN_OUT
= 2, SCAN_IO
= 3
142 typedef struct scan_command_s
144 bool ir_scan
; /* instruction/not data scan */
145 int num_fields
; /* number of fields in *fields array */
146 scan_field_t
* fields
; /* pointer to an array of data scan fields */
147 tap_state_t end_state
; /* TAP state in which JTAG commands should finish */
150 typedef struct statemove_command_s
152 tap_state_t end_state
; /* TAP state in which JTAG commands should finish */
153 } statemove_command_t
;
155 typedef struct pathmove_command_s
157 int num_states
; /* number of states in *path */
158 tap_state_t
* path
; /* states that have to be passed */
159 } pathmove_command_t
;
161 typedef struct runtest_command_s
163 int num_cycles
; /* number of cycles that should be spent in Run-Test/Idle */
164 tap_state_t end_state
; /* TAP state in which JTAG commands should finish */
168 typedef struct stableclocks_command_s
170 int num_cycles
; /* number of clock cycles that should be sent */
171 } stableclocks_command_t
;
174 typedef struct reset_command_s
176 int trst
; /* trst/srst 0: deassert, 1: assert, -1: don't change */
180 typedef struct end_state_command_s
182 tap_state_t end_state
; /* TAP state in which JTAG commands should finish */
183 } end_state_command_t
;
185 typedef struct sleep_command_s
187 u32 us
; /* number of microseconds to sleep */
190 typedef union jtag_command_container_u
192 scan_command_t
* scan
;
193 statemove_command_t
* statemove
;
194 pathmove_command_t
* pathmove
;
195 runtest_command_t
* runtest
;
196 stableclocks_command_t
* stableclocks
;
197 reset_command_t
* reset
;
198 end_state_command_t
* end_state
;
199 sleep_command_t
* sleep
;
200 } jtag_command_container_t
;
202 enum jtag_command_type
{
209 JTAG_STABLECLOCKS
= 8
212 typedef struct jtag_command_s
214 jtag_command_container_t cmd
;
215 enum jtag_command_type type
;
216 struct jtag_command_s
* next
;
219 extern jtag_command_t
* jtag_command_queue
;
221 extern void* cmd_queue_alloc(size_t size
);
222 extern void cmd_queue_free(void);
224 extern void jtag_queue_command(jtag_command_t
*cmd
);
225 extern void jtag_command_queue_reset(void);
227 #include "interface.h"
229 #endif // INCLUDE_JTAG_INTERFACE_H
231 /* forward declaration */
232 typedef struct jtag_tap_event_action_s jtag_tap_event_action_t
;
234 /* this is really: typedef jtag_tap_t */
235 /* But - the typedef is done in "types.h" */
236 /* due to "forward decloration reasons" */
241 const char* dotted_name
;
242 int abs_chain_position
;
244 int ir_length
; /* size of instruction register */
245 u32 ir_capture_value
;
246 u8
* expected
; /* Capture-IR expected value */
248 u8
* expected_mask
; /* Capture-IR expected mask */
249 u32 idcode
; /* device identification code */
250 u32
* expected_ids
; /* Array of expected identification codes */
251 u8 expected_ids_cnt
; /* Number of expected identification codes */
252 u8
* cur_instr
; /* current instruction */
253 int bypass
; /* bypass register selected */
255 jtag_tap_event_action_t
* event_action
;
257 jtag_tap_t
* next_tap
;
259 extern jtag_tap_t
* jtag_AllTaps(void);
260 extern jtag_tap_t
* jtag_TapByPosition(int n
);
261 extern jtag_tap_t
* jtag_TapByString(const char* dotted_name
);
262 extern jtag_tap_t
* jtag_TapByJimObj(Jim_Interp
* interp
, Jim_Obj
* obj
);
263 extern jtag_tap_t
* jtag_TapByAbsPosition(int abs_position
);
264 extern int jtag_NumEnabledTaps(void);
265 extern int jtag_NumTotalTaps(void);
267 static __inline__ jtag_tap_t
* jtag_NextEnabledTap(jtag_tap_t
* p
)
271 /* start at the head of list */
276 /* start *after* this one */
295 enum reset_line_mode
{
296 LINE_OPEN_DRAIN
= 0x0,
297 LINE_PUSH_PULL
= 0x1,
304 extern char* jtag_event_strings
[];
306 enum jtag_tap_event
{
307 JTAG_TAP_EVENT_ENABLE
,
308 JTAG_TAP_EVENT_DISABLE
311 extern const Jim_Nvp nvp_jtag_tap_event
[];
313 struct jtag_tap_event_action_s
315 enum jtag_tap_event event
;
317 jtag_tap_event_action_t
* next
;
320 extern int jtag_trst
;
321 extern int jtag_srst
;
323 typedef struct jtag_event_callback_s
325 int (*callback
)(enum jtag_event event
, void* priv
);
327 struct jtag_event_callback_s
* next
;
328 } jtag_event_callback_t
;
330 extern jtag_event_callback_t
* jtag_event_callbacks
;
332 extern int jtag_speed
;
333 extern int jtag_speed_post_reset
;
337 RESET_HAS_TRST
= 0x1,
338 RESET_HAS_SRST
= 0x2,
339 RESET_TRST_AND_SRST
= 0x3,
340 RESET_SRST_PULLS_TRST
= 0x4,
341 RESET_TRST_PULLS_SRST
= 0x8,
342 RESET_TRST_OPEN_DRAIN
= 0x10,
343 RESET_SRST_PUSH_PULL
= 0x20,
346 extern enum reset_types jtag_reset_config
;
348 /* initialize interface upon startup. A successful no-op
349 * upon subsequent invocations
351 extern int jtag_interface_init(struct command_context_s
* cmd_ctx
);
353 /// Shutdown the JTAG interface upon program exit.
354 extern int jtag_interface_quit(void);
356 /* initialize JTAG chain using only a RESET reset. If init fails,
359 extern int jtag_init(struct command_context_s
* cmd_ctx
);
361 /* reset, then initialize JTAG chain */
362 extern int jtag_init_reset(struct command_context_s
* cmd_ctx
);
363 extern int jtag_register_commands(struct command_context_s
* cmd_ctx
);
365 /* JTAG interface, can be implemented with a software or hardware fifo
367 * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states. TAP_DRSHIFT/IRSHIFT as end states
368 * can be emulated by using a larger scan.
370 * Code that is relatively insensitive to the path(as long
371 * as it is JTAG compliant) taken through state machine can use
372 * endstate for jtag_add_xxx_scan(). Otherwise the pause state must be
373 * specified as end state and a subsequent jtag_add_pathmove() must
377 extern void jtag_add_ir_scan(int num_fields
, scan_field_t
* fields
, tap_state_t endstate
);
378 /* same as jtag_add_ir_scan except no verify is performed */
379 extern void jtag_add_ir_scan_noverify(int num_fields
, const scan_field_t
*fields
, tap_state_t state
);
380 extern void jtag_add_dr_scan(int num_fields
, const scan_field_t
* fields
, tap_state_t endstate
);
382 /* set in_value to point to 32 bits of memory to scan into. This function
383 * is a way to handle the case of synchronous and asynchronous
386 * In the event of an asynchronous queue execution the queue buffer
387 * allocation method is used, for the synchronous case the temporary 32 bits come
388 * from the input field itself.
390 extern void jtag_alloc_in_value32(scan_field_t
*field
);
392 /* This version of jtag_add_dr_scan() uses the check_value/mask fields */
393 extern void jtag_add_dr_scan_check(int num_fields
, scan_field_t
* fields
, tap_state_t endstate
);
394 extern void jtag_add_plain_ir_scan(int num_fields
, const scan_field_t
* fields
, tap_state_t endstate
);
395 extern void jtag_add_plain_dr_scan(int num_fields
, const scan_field_t
* fields
, tap_state_t endstate
);
398 /* Simplest/typical callback - do some conversion on the data clocked in.
399 * This callback is for such conversion that can not fail.
400 * For conversion types or checks that can
401 * fail, use the jtag_callback_t variant */
402 typedef void (*jtag_callback1_t
)(u8
*in
);
404 /* A simpler version of jtag_add_callback4 */
405 extern void jtag_add_callback(jtag_callback1_t
, u8
*in
);
408 /* This type can store an integer safely by a normal cast on 64 and
410 typedef intptr_t jtag_callback_data_t
;
412 /* The generic callback mechanism.
414 * The callback is invoked with three arguments. The first argument is
415 * the pointer to the data clocked in.
417 typedef int (*jtag_callback_t
)(u8
*in
, jtag_callback_data_t data1
, jtag_callback_data_t data2
, jtag_callback_data_t data3
);
420 /* This callback can be executed immediately the queue has been flushed. Note that
421 * the JTAG queue can either be executed synchronously or asynchronously. Typically
422 * for USB the queue is executed asynchronously. For low latency interfaces, the
423 * queue may be executed synchronously.
425 * These callbacks are typically executed *after* the *entire* JTAG queue has been
426 * executed for e.g. USB interfaces.
428 * The callbacks are guaranteeed to be invoked in the order that they were queued.
430 * The strange name is due to C's lack of overloading using function arguments
432 * The callback mechansim is very general and does not really make any assumptions
433 * about what the callback does and what the arguments are.
435 * in - typically used to point to the data to operate on. More often than not
436 * this will be the data clocked in during a shift operation
438 * data1 - an integer that is big enough to be used either as an 'int' or
439 * cast to/from a pointer
441 * data2 - an integer that is big enough to be used either as an 'int' or
442 * cast to/from a pointer
444 * Why stop at 'data2' for arguments? Somewhat historical reasons. This is
445 * sufficient to implement the jtag_check_value_mask(), besides the
446 * line is best drawn somewhere...
448 * If the execution of the queue fails before the callbacks, then the
449 * callbacks may or may not be invoked depending on driver implementation.
451 extern void jtag_add_callback4(jtag_callback_t
, u8
*in
,
452 jtag_callback_data_t data1
, jtag_callback_data_t data2
,
453 jtag_callback_data_t data3
);
456 /* run a TAP_RESET reset. End state is TAP_RESET, regardless
459 extern void jtag_add_tlr(void);
461 /* Application code *must* assume that interfaces will
462 * implement transitions between states with different
463 * paths and path lengths through the state diagram. The
464 * path will vary across interface and also across versions
465 * of the same interface over time. Even if the OpenOCD code
466 * is unchanged, the actual path taken may vary over time
467 * and versions of interface firmware or PCB revisions.
469 * Use jtag_add_pathmove() when specific transition sequences
472 * Do not use jtag_add_pathmove() unless you need to, but do use it
475 * DANGER! If the target is dependent upon a particular sequence
476 * of transitions for things to work correctly(e.g. as a workaround
477 * for an errata that contradicts the JTAG standard), then pathmove
478 * must be used, even if some jtag interfaces happen to use the
479 * desired path. Worse, the jtag interface used for testing a
480 * particular implementation, could happen to use the "desired"
481 * path when transitioning to/from end
484 * A list of unambigious single clock state transitions, not
485 * all drivers can support this, but it is required for e.g.
486 * XScale and Xilinx support
488 * Note! TAP_RESET must not be used in the path!
490 * Note that the first on the list must be reachable
491 * via a single transition from the current state.
493 * All drivers are required to implement jtag_add_pathmove().
494 * However, if the pathmove sequence can not be precisely
495 * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
496 * must return an error. It is legal, but not recommended, that
497 * a driver returns an error in all cases for a pathmove if it
498 * can only implement a few transitions and therefore
499 * a partial implementation of pathmove would have little practical
502 extern void jtag_add_pathmove(int num_states
, const tap_state_t
* path
);
504 /* go to TAP_IDLE, if we're not already there and cycle
505 * precisely num_cycles in the TAP_IDLE after which move
506 * to the end state, if it is != TAP_IDLE
508 * nb! num_cycles can be 0, in which case the fn will navigate
509 * to endstate via TAP_IDLE
511 extern void jtag_add_runtest(int num_cycles
, tap_state_t endstate
);
513 /* A reset of the TAP state machine can be requested.
515 * Whether tms or trst reset is used depends on the capabilities of
516 * the target and jtag interface(reset_config command configures this).
518 * srst can driver a reset of the TAP state machine and vice
521 * Application code may need to examine value of jtag_reset_config
522 * to determine the proper codepath
524 * DANGER! Even though srst drives trst, trst might not be connected to
525 * the interface, and it might actually be *harmful* to assert trst in this case.
527 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
530 * only req_tlr_or_trst and srst can have a transition for a
531 * call as the effects of transitioning both at the "same time"
532 * are undefined, but when srst_pulls_trst or vice versa,
533 * then trst & srst *must* be asserted together.
535 extern void jtag_add_reset(int req_tlr_or_trst
, int srst
);
537 extern void jtag_add_end_state(tap_state_t endstate
);
538 extern void jtag_add_sleep(u32 us
);
542 * Function jtag_add_stable_clocks
543 * first checks that the state in which the clocks are to be issued is
544 * stable, then queues up clock_count clocks for transmission.
546 void jtag_add_clocks(int num_cycles
);
550 * For software FIFO implementations, the queued commands can be executed
551 * during this call or earlier. A sw queue might decide to push out
552 * some of the jtag_add_xxx() operations once the queue is "big enough".
554 * This fn will return an error code if any of the prior jtag_add_xxx()
555 * calls caused a failure, e.g. check failure. Note that it does not
556 * matter if the operation was executed *before* jtag_execute_queue(),
557 * jtag_execute_queue() will still return an error code.
559 * All jtag_add_xxx() calls that have in_handler!=NULL will have been
560 * executed when this fn returns, but if what has been queued only
561 * clocks data out, without reading anything back, then JTAG could
562 * be running *after* jtag_execute_queue() returns. The API does
563 * not define a way to flush a hw FIFO that runs *after*
564 * jtag_execute_queue() returns.
566 * jtag_add_xxx() commands can either be executed immediately or
567 * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
569 extern int jtag_execute_queue(void);
571 /* same as jtag_execute_queue() but does not clear the error flag */
572 extern void jtag_execute_queue_noclear(void);
574 /* this flag is set when an error occurs while executing the queue. cleared
575 * by jtag_execute_queue()
577 * this flag can also be set from application code if some error happens
578 * during processing that should be reported during jtag_execute_queue().
580 extern int jtag_error
;
582 static __inline__
void jtag_set_error(int error
)
584 if ((error
==ERROR_OK
)||(jtag_error
!=ERROR_OK
))
586 /* keep first error */
594 /* can be implemented by hw+sw */
595 extern int jtag_power_dropout(int* dropout
);
596 extern int jtag_srst_asserted(int* srst_asserted
);
598 /* JTAG support functions */
600 /* execute jtag queue and check value and use mask if mask is != NULL. invokes
601 * jtag_set_error() with any error. */
602 extern void jtag_check_value_mask(scan_field_t
*field
, u8
*value
, u8
*mask
);
604 #ifdef INCLUDE_JTAG_INTERFACE_H
605 extern enum scan_type
jtag_scan_type(const scan_command_t
* cmd
);
606 extern int jtag_scan_size(const scan_command_t
* cmd
);
607 extern int jtag_read_buffer(u8
* buffer
, const scan_command_t
* cmd
);
608 extern int jtag_build_buffer(const scan_command_t
* cmd
, u8
** buffer
);
609 #endif // INCLUDE_JTAG_INTERFACE_H
611 extern void jtag_sleep(u32 us
);
612 extern int jtag_call_event_callbacks(enum jtag_event event
);
613 extern int jtag_register_event_callback(int (* callback
)(enum jtag_event event
, void* priv
), void* priv
);
615 extern int jtag_verify_capture_ir
;
617 void jtag_tap_handle_event(jtag_tap_t
* tap
, enum jtag_tap_event e
);
620 * JTAG subsystem uses codes between -100 and -199 */
622 #define ERROR_JTAG_INIT_FAILED (-100)
623 #define ERROR_JTAG_INVALID_INTERFACE (-101)
624 #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
625 #define ERROR_JTAG_TRST_ASSERTED (-103)
626 #define ERROR_JTAG_QUEUE_FAILED (-104)
627 #define ERROR_JTAG_NOT_STABLE_STATE (-105)
628 #define ERROR_JTAG_DEVICE_ERROR (-107)
630 /* jtag_add_dr_out() is a version of jtag_add_dr_scan() which
631 * only scans data out. It operates on 32 bit integers instead
632 * of 8 bit, which makes it a better impedance match with
633 * the calling code which often operate on 32 bit integers.
635 * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
637 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
639 * If the device is in bypass, then that is an error condition in
640 * the caller code that is not detected by this fn, whereas jtag_add_dr_scan()
641 * does detect it. Similarly if the device is not in bypass, data must
644 * If anything fails, then jtag_error will be set and jtag_execute() will
645 * return an error. There is no way to determine if there was a failure
646 * during this function call.
648 * This is an inline fn to speed up embedded hosts. Also note that
649 * interface_jtag_add_dr_out() can be a *small* inline function for
652 * There is no jtag_add_dr_outin() version of this fn that also allows
653 * clocking data back in. Patches gladly accepted!
655 extern void jtag_add_dr_out(jtag_tap_t
* tap
,
656 int num_fields
, const int* num_bits
, const u32
* value
,
657 tap_state_t end_state
);
661 * Function jtag_add_statemove
662 * moves from the current state to the goal \a state. This needs
663 * to be handled according to the xsvf spec, see the XSTATE command
666 extern int jtag_add_statemove(tap_state_t goal_state
);
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)