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 ***************************************************************************/
27 #include "binarybuffer.h"
34 #define _DEBUG_JTAG_IO_
37 #ifndef DEBUG_JTAG_IOZ
38 #define DEBUG_JTAG_IOZ 64
42 /* 16 Tap States, from page 21 of ASSET InterTech, Inc.'s svf.pdf
44 typedef enum tap_state
46 TAP_RESET
= 0x0, TAP_IDLE
= 0x8,
47 TAP_DRSELECT
= 0x1, TAP_DRCAPTURE
= 0x2, TAP_DRSHIFT
= 0x3, TAP_DREXIT1
= 0x4,
48 TAP_DRPAUSE
= 0x5, TAP_DREXIT2
= 0x6, TAP_DRUPDATE
= 0x7,
49 TAP_IRSELECT
= 0x9, TAP_IRCAPTURE
= 0xa, TAP_IRSHIFT
= 0xb, TAP_IREXIT1
= 0xc,
50 TAP_IRPAUSE
= 0xd, TAP_IREXIT2
= 0xe, TAP_IRUPDATE
= 0xf
53 typedef struct tap_transition_s
59 extern int tap_move_map
[16]; /* map 16 TAP states to 6 stable states */
60 extern u8 tap_move
[6][6]; /* value scanned to TMS to move from one of six stable states to another */
61 extern tap_transition_t tap_transitions
[16]; /* describe the TAP state diagram */
63 extern enum tap_state end_state
; /* finish DR scans in dr_end_state */
64 extern enum tap_state cur_state
; /* current TAP state */
66 extern enum tap_state cmd_queue_end_state
; /* finish DR scans in dr_end_state */
67 extern enum tap_state cmd_queue_cur_state
; /* current TAP state */
69 #define TAP_MOVE(from, to) tap_move[tap_move_map[from]][tap_move_map[to]]
71 typedef void * error_handler_t
; /* Later on we can delete error_handler_t, but keep it for now to make patches more readable */
74 typedef int (*in_handler_t
)(u8
*in_value
, void *priv
, struct scan_field_s
*field
);
76 typedef struct scan_field_s
78 jtag_tap_t
*tap
; /* tap pointer this instruction refers to */
79 int num_bits
; /* number of bits this field specifies (up to 32) */
80 u8
*out_value
; /* value to be scanned into the device */
81 u8
*out_mask
; /* only masked bits care */
82 u8
*in_value
; /* pointer to a 32-bit memory location to take data scanned out */
83 /* in_check_value/mask, in_handler_error_handler, in_handler_priv can be used by the in handler, otherwise they contain garbage */
84 u8
*in_check_value
; /* used to validate scan results */
85 u8
*in_check_mask
; /* check specified bits against check_value */
86 in_handler_t in_handler
;/* process received buffer using this handler */
87 void *in_handler_priv
; /* additional information for the in_handler */
92 /* IN: from device to host, OUT: from host to device */
93 SCAN_IN
= 1, SCAN_OUT
= 2, SCAN_IO
= 3
96 typedef struct scan_command_s
98 int ir_scan
; /* instruction/not data scan */
99 int num_fields
; /* number of fields in *fields array */
100 scan_field_t
*fields
; /* pointer to an array of data scan fields */
101 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
104 typedef struct statemove_command_s
106 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
107 } statemove_command_t
;
109 typedef struct pathmove_command_s
111 int num_states
; /* number of states in *path */
112 enum tap_state
*path
; /* states that have to be passed */
113 } pathmove_command_t
;
115 typedef struct runtest_command_s
117 int num_cycles
; /* number of cycles that should be spent in Run-Test/Idle */
118 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
122 typedef struct stableclocks_command_s
124 int num_cycles
; /* number of clock cycles that should be sent */
125 } stableclocks_command_t
;
128 typedef struct reset_command_s
130 int trst
; /* trst/srst 0: deassert, 1: assert, -1: don't change */
134 typedef struct end_state_command_s
136 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
137 } end_state_command_t
;
139 typedef struct sleep_command_s
141 u32 us
; /* number of microseconds to sleep */
144 typedef union jtag_command_container_u
146 scan_command_t
*scan
;
147 statemove_command_t
*statemove
;
148 pathmove_command_t
*pathmove
;
149 runtest_command_t
*runtest
;
150 stableclocks_command_t
*stableclocks
;
151 reset_command_t
*reset
;
152 end_state_command_t
*end_state
;
153 sleep_command_t
*sleep
;
154 } jtag_command_container_t
;
156 enum jtag_command_type
159 JTAG_STATEMOVE
= 2, JTAG_RUNTEST
= 3,
160 JTAG_RESET
= 4, JTAG_END_STATE
= 5,
161 JTAG_PATHMOVE
= 6, JTAG_SLEEP
= 7,
162 JTAG_STABLECLOCKS
= 8
165 typedef struct jtag_command_s
167 jtag_command_container_t cmd
;
168 enum jtag_command_type type
;
169 struct jtag_command_s
*next
;
172 extern jtag_command_t
*jtag_command_queue
;
174 /* forward declaration */
175 typedef struct jtag_tap_event_action_s jtag_tap_event_action_t
;
177 /* this is really: typedef jtag_tap_t */
178 /* But - the typedef is done in "types.h" */
179 /* due to "forward decloration reasons" */
184 const char *dotted_name
;
185 int abs_chain_position
;
187 int ir_length
; /* size of instruction register */
188 u32 ir_capture_value
;
189 u8
*expected
; /* Capture-IR expected value */
191 u8
*expected_mask
; /* Capture-IR expected mask */
192 u32 idcode
; /* device identification code */
193 u32
*expected_ids
; /* Array of expected identification codes */
194 u8 expected_ids_cnt
;/* Number of expected identification codes */
195 u8
*cur_instr
; /* current instruction */
196 int bypass
; /* bypass register selected */
198 jtag_tap_event_action_t
*event_action
;
200 jtag_tap_t
*next_tap
;
202 extern jtag_tap_t
*jtag_AllTaps(void);
203 extern jtag_tap_t
*jtag_TapByPosition(int n
);
204 extern jtag_tap_t
*jtag_TapByPosition(int n
);
205 extern jtag_tap_t
*jtag_TapByString(const char *dotted_name
);
206 extern jtag_tap_t
*jtag_TapByJimObj(Jim_Interp
*interp
, Jim_Obj
*obj
);
207 extern jtag_tap_t
*jtag_TapByAbsPosition(int abs_position
);
208 extern int jtag_NumEnabledTaps(void);
209 extern int jtag_NumTotalTaps(void);
211 static __inline__ jtag_tap_t
*
212 jtag_NextEnabledTap( jtag_tap_t
*p
)
215 /* start at the head of list */
218 /* start *after* this one */
233 LINE_OPEN_DRAIN
= 0x0,
234 LINE_PUSH_PULL
= 0x1,
237 typedef struct jtag_interface_s
241 /* queued command execution
243 int (*execute_queue
)(void);
245 /* interface initalization
247 int (*speed
)(int speed
);
248 int (*register_commands
)(struct command_context_s
*cmd_ctx
);
251 /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
252 a failure if it can't support the KHz/RTCK.
254 WARNING!!!! if RTCK is *slow* then think carefully about
255 whether you actually want to support this in the driver.
256 Many target scripts are written to handle the absence of RTCK
257 and use a fallback kHz TCK.
259 int (*khz
)(int khz
, int *jtag_speed
);
260 /* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
261 a failure if it can't support the KHz/RTCK. */
262 int (*speed_div
)(int speed
, int *khz
);
264 /* Read and clear the power dropout flag. Note that a power dropout
265 can be transitionary, easily much less than a ms.
267 So to find out if the power is *currently* on, you must invoke
268 this method twice. Once to clear the power dropout flag and a
269 second time to read the current state.
271 Currently the default implementation is never to detect power dropout.
273 int (*power_dropout
)(int *power_dropout
);
274 /* Read and clear the srst asserted detection flag.
276 * NB!!!! like power_dropout this does *not* read the current
277 * state. srst assertion is transitionary and *can* be much
280 int (*srst_asserted
)(int *srst_asserted
);
289 extern char * jtag_event_strings
[];
293 JTAG_TAP_EVENT_ENABLE
,
294 JTAG_TAP_EVENT_DISABLE
297 extern const Jim_Nvp nvp_jtag_tap_event
[];
299 struct jtag_tap_event_action_s
{
300 enum jtag_tap_event event
;
302 jtag_tap_event_action_t
*next
;
305 extern int jtag_trst
;
306 extern int jtag_srst
;
308 typedef struct jtag_event_callback_s
310 int (*callback
)(enum jtag_event event
, void *priv
);
312 struct jtag_event_callback_s
*next
;
313 } jtag_event_callback_t
;
315 extern jtag_event_callback_t
*jtag_event_callbacks
;
317 extern jtag_interface_t
*jtag
; /* global pointer to configured JTAG interface */
318 extern enum tap_state end_state
;
319 extern enum tap_state cur_state
;
321 extern int jtag_speed
;
322 extern int jtag_speed_post_reset
;
327 RESET_HAS_TRST
= 0x1,
328 RESET_HAS_SRST
= 0x2,
329 RESET_TRST_AND_SRST
= 0x3,
330 RESET_SRST_PULLS_TRST
= 0x4,
331 RESET_TRST_PULLS_SRST
= 0x8,
332 RESET_TRST_OPEN_DRAIN
= 0x10,
333 RESET_SRST_PUSH_PULL
= 0x20,
336 extern enum reset_types jtag_reset_config
;
338 /* initialize interface upon startup. A successful no-op
339 * upon subsequent invocations
341 extern int jtag_interface_init(struct command_context_s
*cmd_ctx
);
342 /* initialize JTAG chain using only a RESET reset. If init fails,
345 extern int jtag_init(struct command_context_s
*cmd_ctx
);
346 /* reset, then initialize JTAG chain */
347 extern int jtag_init_reset(struct command_context_s
*cmd_ctx
);
348 extern int jtag_register_commands(struct command_context_s
*cmd_ctx
);
350 /* JTAG interface, can be implemented with a software or hardware fifo
352 * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states. TAP_DRSHIFT/IRSHIFT as end states
353 * can be emulated by using a larger scan.
355 * Code that is relatively insensitive to the path(as long
356 * as it is JTAG compliant) taken through state machine can use
357 * endstate for jtag_add_xxx_scan(). Otherwise the pause state must be
358 * specified as end state and a subsequent jtag_add_pathmove() must
362 extern void jtag_add_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
363 extern int interface_jtag_add_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
364 extern void jtag_add_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
365 extern int interface_jtag_add_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
366 extern void jtag_add_plain_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
367 extern int interface_jtag_add_plain_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
368 extern void jtag_add_plain_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
369 extern int interface_jtag_add_plain_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
370 /* run a TAP_RESET reset. End state is TAP_RESET, regardless
373 extern void jtag_add_tlr(void);
374 extern int interface_jtag_add_tlr(void);
375 /* Do not use jtag_add_pathmove() unless you need to, but do use it
378 * DANGER! If the target is dependent upon a particular sequence
379 * of transitions for things to work correctly(e.g. as a workaround
380 * for an errata that contradicts the JTAG standard), then pathmove
381 * must be used, even if some jtag interfaces happen to use the
382 * desired path. Worse, the jtag interface used for testing a
383 * particular implementation, could happen to use the "desired"
384 * path when transitioning to/from end
387 * A list of unambigious single clock state transitions, not
388 * all drivers can support this, but it is required for e.g.
389 * XScale and Xilinx support
391 * Note! TAP_RESET must not be used in the path!
393 * Note that the first on the list must be reachable
394 * via a single transition from the current state.
396 * All drivers are required to implement jtag_add_pathmove().
397 * However, if the pathmove sequence can not be precisely
398 * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
399 * must return an error. It is legal, but not recommended, that
400 * a driver returns an error in all cases for a pathmove if it
401 * can only implement a few transitions and therefore
402 * a partial implementation of pathmove would have little practical
405 extern void jtag_add_pathmove(int num_states
, enum tap_state
*path
);
406 extern int interface_jtag_add_pathmove(int num_states
, enum tap_state
*path
);
407 /* go to TAP_IDLE, if we're not already there and cycle
408 * precisely num_cycles in the TAP_IDLE after which move
409 * to the end state, if it is != TAP_IDLE
411 * nb! num_cycles can be 0, in which case the fn will navigate
412 * to endstate via TAP_IDLE
414 extern void jtag_add_runtest(int num_cycles
, enum tap_state endstate
);
415 extern int interface_jtag_add_runtest(int num_cycles
, enum tap_state endstate
);
416 /* A reset of the TAP state machine can be requested.
418 * Whether tms or trst reset is used depends on the capabilities of
419 * the target and jtag interface(reset_config command configures this).
421 * srst can driver a reset of the TAP state machine and vice
424 * Application code may need to examine value of jtag_reset_config
425 * to determine the proper codepath
427 * DANGER! Even though srst drives trst, trst might not be connected to
428 * the interface, and it might actually be *harmful* to assert trst in this case.
430 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
433 * only req_tlr_or_trst and srst can have a transition for a
434 * call as the effects of transitioning both at the "same time"
435 * are undefined, but when srst_pulls_trst or vice versa,
436 * then trst & srst *must* be asserted together.
438 extern void jtag_add_reset(int req_tlr_or_trst
, int srst
);
439 /* this drives the actual srst and trst pins. srst will always be 0
440 * if jtag_reset_config & RESET_SRST_PULLS_TRST != 0 and ditto for
443 * the higher level jtag_add_reset will invoke jtag_add_tlr() if
446 extern int interface_jtag_add_reset(int trst
, int srst
);
447 extern void jtag_add_end_state(enum tap_state endstate
);
448 extern int interface_jtag_add_end_state(enum tap_state endstate
);
449 extern void jtag_add_sleep(u32 us
);
450 extern int interface_jtag_add_sleep(u32 us
);
454 * Function jtag_add_stable_clocks
455 * first checks that the state in which the clocks are to be issued is
456 * stable, then queues up clock_count clocks for transmission.
458 void jtag_add_clocks( int num_cycles
);
459 int interface_jtag_add_clocks( int num_cycles
);
463 * For software FIFO implementations, the queued commands can be executed
464 * during this call or earlier. A sw queue might decide to push out
465 * some of the jtag_add_xxx() operations once the queue is "big enough".
467 * This fn will return an error code if any of the prior jtag_add_xxx()
468 * calls caused a failure, e.g. check failure. Note that it does not
469 * matter if the operation was executed *before* jtag_execute_queue(),
470 * jtag_execute_queue() will still return an error code.
472 * All jtag_add_xxx() calls that have in_handler!=NULL will have been
473 * executed when this fn returns, but if what has been queued only
474 * clocks data out, without reading anything back, then JTAG could
475 * be running *after* jtag_execute_queue() returns. The API does
476 * not define a way to flush a hw FIFO that runs *after*
477 * jtag_execute_queue() returns.
479 * jtag_add_xxx() commands can either be executed immediately or
480 * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
482 extern int jtag_execute_queue(void);
483 /* can be implemented by hw+sw */
484 extern int interface_jtag_execute_queue(void);
485 extern int jtag_power_dropout(int *dropout
);
486 extern int jtag_srst_asserted(int *srst_asserted
);
488 /* JTAG support functions */
489 extern void jtag_set_check_value(scan_field_t
*field
, u8
*value
, u8
*mask
, error_handler_t
*in_error_handler
);
490 extern enum scan_type
jtag_scan_type(scan_command_t
*cmd
);
491 extern int jtag_scan_size(scan_command_t
*cmd
);
492 extern int jtag_read_buffer(u8
*buffer
, scan_command_t
*cmd
);
493 extern int jtag_build_buffer(scan_command_t
*cmd
, u8
**buffer
);
495 extern void jtag_sleep(u32 us
);
496 extern int jtag_call_event_callbacks(enum jtag_event event
);
497 extern int jtag_register_event_callback(int (*callback
)(enum jtag_event event
, void *priv
), void *priv
);
499 extern int jtag_verify_capture_ir
;
501 void jtag_tap_handle_event( jtag_tap_t
* tap
, enum jtag_tap_event e
);
504 * JTAG subsystem uses codes between -100 and -199 */
506 #define ERROR_JTAG_INIT_FAILED (-100)
507 #define ERROR_JTAG_INVALID_INTERFACE (-101)
508 #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
509 #define ERROR_JTAG_TRST_ASSERTED (-103)
510 #define ERROR_JTAG_QUEUE_FAILED (-104)
511 #define ERROR_JTAG_NOT_STABLE_STATE (-105)
512 #define ERROR_JTAG_DEVICE_ERROR (-107)
515 /* this allows JTAG devices to implement the entire jtag_xxx() layer in hw/sw */
516 #ifdef HAVE_JTAG_MINIDRIVER_H
517 /* Here a #define MINIDRIVER() and an inline version of hw fifo interface_jtag_add_dr_out can be defined */
518 #include "jtag_minidriver.h"
519 #define MINIDRIVER(a) notused ## a
521 #define MINIDRIVER(a) a
522 /* jtag_add_dr_out() is a faster version of jtag_add_dr_scan()
524 * Current or end_state can not be TAP_RESET. end_state can be -1
526 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
528 * If the device is in bypass, then that is an error condition in
529 * the caller code that is not detected by this fn, whereas jtag_add_dr_scan()
530 * does detect it. Similarly if the device is not in bypass, data must
533 * If anything fails, then jtag_error will be set and jtag_execute() will
534 * return an error. There is no way to determine if there was a failure
535 * during this function call.
537 * Note that this jtag_add_dr_out can be defined as an inline function.
539 extern void interface_jtag_add_dr_out(jtag_tap_t
*tap
,
543 enum tap_state end_state
);
546 static __inline__
void jtag_add_dr_out(jtag_tap_t
*tap
,
550 enum tap_state end_state
)
553 cmd_queue_end_state
=end_state
;
554 cmd_queue_cur_state
=cmd_queue_end_state
;
555 interface_jtag_add_dr_out(tap
, num_fields
, num_bits
, value
, cmd_queue_end_state
);
559 * Function jtag_state_name
560 * Returns a string suitable for display representing the JTAG tap_state
562 const char* jtag_state_name(enum tap_state 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)