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"
33 #define _DEBUG_JTAG_IO_
36 /* 16 Tap States, from page 21 of ASSET InterTech, Inc.'s svf.pdf
40 TAP_RESET
= 0x0, TAP_IDLE
= 0x8,
41 TAP_DRSELECT
= 0x1, TAP_DRCAPTURE
= 0x2, TAP_DRSHIFT
= 0x3, TAP_DREXIT1
= 0x4,
42 TAP_DRPAUSE
= 0x5, TAP_DREXIT2
= 0x6, TAP_DRUPDATE
= 0x7,
43 TAP_IRSELECT
= 0x9, TAP_IRCAPTURE
= 0xa, TAP_IRSHIFT
= 0xb, TAP_IREXIT1
= 0xc,
44 TAP_IRPAUSE
= 0xd, TAP_IREXIT2
= 0xe, TAP_IRUPDATE
= 0xf
47 typedef struct tap_transition_s
53 extern int tap_move_map
[16]; /* map 16 TAP states to 6 stable states */
54 extern u8 tap_move
[6][6]; /* value scanned to TMS to move from one of six stable states to another */
55 extern tap_transition_t tap_transitions
[16]; /* describe the TAP state diagram */
57 extern enum tap_state end_state
; /* finish DR scans in dr_end_state */
58 extern enum tap_state cur_state
; /* current TAP state */
60 extern enum tap_state cmd_queue_end_state
; /* finish DR scans in dr_end_state */
61 extern enum tap_state cmd_queue_cur_state
; /* current TAP state */
63 #define TAP_MOVE(from, to) tap_move[tap_move_map[from]][tap_move_map[to]]
65 typedef void * error_handler_t
; /* Later on we can delete error_handler_t, but keep it for now to make patches more readable */
68 typedef int (*in_handler_t
)(u8
*in_value
, void *priv
, struct scan_field_s
*field
);
70 typedef struct scan_field_s
72 jtag_tap_t
*tap
; /* tap pointer this instruction refers to */
73 int num_bits
; /* number of bits this field specifies (up to 32) */
74 u8
*out_value
; /* value to be scanned into the device */
75 u8
*out_mask
; /* only masked bits care */
76 u8
*in_value
; /* pointer to a 32-bit memory location to take data scanned out */
77 /* in_check_value/mask, in_handler_error_handler, in_handler_priv can be used by the in handler, otherwise they contain garbage */
78 u8
*in_check_value
; /* used to validate scan results */
79 u8
*in_check_mask
; /* check specified bits against check_value */
80 in_handler_t in_handler
;/* process received buffer using this handler */
81 void *in_handler_priv
; /* additional information for the in_handler */
86 /* IN: from device to host, OUT: from host to device */
87 SCAN_IN
= 1, SCAN_OUT
= 2, SCAN_IO
= 3
90 typedef struct scan_command_s
92 int ir_scan
; /* instruction/not data scan */
93 int num_fields
; /* number of fields in *fields array */
94 scan_field_t
*fields
; /* pointer to an array of data scan fields */
95 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
98 typedef struct statemove_command_s
100 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
101 } statemove_command_t
;
103 typedef struct pathmove_command_s
105 int num_states
; /* number of states in *path */
106 enum tap_state
*path
; /* states that have to be passed */
107 } pathmove_command_t
;
109 typedef struct runtest_command_s
111 int num_cycles
; /* number of cycles that should be spent in Run-Test/Idle */
112 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
115 typedef struct reset_command_s
117 int trst
; /* trst/srst 0: deassert, 1: assert, -1: don't change */
121 typedef struct end_state_command_s
123 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
124 } end_state_command_t
;
126 typedef struct sleep_command_s
128 u32 us
; /* number of microseconds to sleep */
131 typedef union jtag_command_container_u
133 scan_command_t
*scan
;
134 statemove_command_t
*statemove
;
135 pathmove_command_t
*pathmove
;
136 runtest_command_t
*runtest
;
137 reset_command_t
*reset
;
138 end_state_command_t
*end_state
;
139 sleep_command_t
*sleep
;
140 } jtag_command_container_t
;
142 enum jtag_command_type
145 JTAG_STATEMOVE
= 2, JTAG_RUNTEST
= 3,
146 JTAG_RESET
= 4, JTAG_END_STATE
= 5,
147 JTAG_PATHMOVE
= 6, JTAG_SLEEP
= 7
150 typedef struct jtag_command_s
152 jtag_command_container_t cmd
;
153 enum jtag_command_type type
;
154 struct jtag_command_s
*next
;
157 extern jtag_command_t
*jtag_command_queue
;
159 /* forward declaration */
160 typedef struct jtag_tap_event_action_s jtag_tap_event_action_t
;
162 /* this is really: typedef jtag_tap_t */
163 /* But - the typedef is done in "types.h" */
164 /* due to "forward decloration reasons" */
169 const char *dotted_name
;
170 int abs_chain_position
;
172 int ir_length
; /* size of instruction register */
173 u32 ir_capture_value
;
174 u8
*expected
; /* Capture-IR expected value */
176 u8
*expected_mask
; /* Capture-IR expected mask */
177 u32 idcode
; /* device identification code */
178 u32
*expected_ids
; /* Array of expected identification codes */
179 u8 expected_ids_cnt
;/* Number of expected identification codes */
180 u8
*cur_instr
; /* current instruction */
181 int bypass
; /* bypass register selected */
183 jtag_tap_event_action_t
*event_action
;
185 jtag_tap_t
*next_tap
;
187 extern jtag_tap_t
*jtag_AllTaps(void);
188 extern jtag_tap_t
*jtag_TapByPosition(int n
);
189 extern jtag_tap_t
*jtag_TapByPosition(int n
);
190 extern jtag_tap_t
*jtag_TapByString(const char *dotted_name
);
191 extern jtag_tap_t
*jtag_TapByJimObj(Jim_Interp
*interp
, Jim_Obj
*obj
);
192 extern jtag_tap_t
*jtag_TapByAbsPosition(int abs_position
);
193 extern int jtag_NumEnabledTaps(void);
194 extern int jtag_NumTotalTaps(void);
196 static __inline__ jtag_tap_t
*
197 jtag_NextEnabledTap( jtag_tap_t
*p
)
200 /* start at the head of list */
203 /* start *after* this one */
218 LINE_OPEN_DRAIN
= 0x0,
219 LINE_PUSH_PULL
= 0x1,
222 typedef struct jtag_interface_s
226 /* queued command execution
228 int (*execute_queue
)(void);
230 /* interface initalization
232 int (*speed
)(int speed
);
233 int (*register_commands
)(struct command_context_s
*cmd_ctx
);
236 /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
237 a failure if it can't support the KHz/RTCK.
239 WARNING!!!! if RTCK is *slow* then think carefully about
240 whether you actually want to support this in the driver.
241 Many target scripts are written to handle the absence of RTCK
242 and use a fallback kHz TCK.
244 int (*khz
)(int khz
, int *jtag_speed
);
245 /* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
246 a failure if it can't support the KHz/RTCK. */
247 int (*speed_div
)(int speed
, int *khz
);
249 /* Read and clear the power dropout flag. Note that a power dropout
250 can be transitionary, easily much less than a ms.
252 So to find out if the power is *currently* on, you must invoke
253 this method twice. Once to clear the power dropout flag and a
254 second time to read the current state.
256 Currently the default implementation is never to detect power dropout.
258 int (*power_dropout
)(int *power_dropout
);
259 /* Read and clear the srst asserted detection flag.
261 * NB!!!! like power_dropout this does *not* read the current
262 * state. srst assertion is transitionary and *can* be much
265 int (*srst_asserted
)(int *srst_asserted
);
274 extern char * jtag_event_strings
[];
278 JTAG_TAP_EVENT_ENABLE
,
279 JTAG_TAP_EVENT_DISABLE
282 extern const Jim_Nvp nvp_jtag_tap_event
[];
284 struct jtag_tap_event_action_s
{
285 enum jtag_tap_event event
;
287 jtag_tap_event_action_t
*next
;
290 extern int jtag_trst
;
291 extern int jtag_srst
;
293 typedef struct jtag_event_callback_s
295 int (*callback
)(enum jtag_event event
, void *priv
);
297 struct jtag_event_callback_s
*next
;
298 } jtag_event_callback_t
;
300 extern jtag_event_callback_t
*jtag_event_callbacks
;
302 extern jtag_interface_t
*jtag
; /* global pointer to configured JTAG interface */
303 extern enum tap_state end_state
;
304 extern enum tap_state cur_state
;
306 extern int jtag_speed
;
307 extern int jtag_speed_post_reset
;
312 RESET_HAS_TRST
= 0x1,
313 RESET_HAS_SRST
= 0x2,
314 RESET_TRST_AND_SRST
= 0x3,
315 RESET_SRST_PULLS_TRST
= 0x4,
316 RESET_TRST_PULLS_SRST
= 0x8,
317 RESET_TRST_OPEN_DRAIN
= 0x10,
318 RESET_SRST_PUSH_PULL
= 0x20,
321 extern enum reset_types jtag_reset_config
;
323 /* initialize interface upon startup. A successful no-op
324 * upon subsequent invocations
326 extern int jtag_interface_init(struct command_context_s
*cmd_ctx
);
327 /* initialize JTAG chain using only a RESET reset. If init fails,
330 extern int jtag_init(struct command_context_s
*cmd_ctx
);
331 /* reset, then initialize JTAG chain */
332 extern int jtag_init_reset(struct command_context_s
*cmd_ctx
);
333 extern int jtag_register_commands(struct command_context_s
*cmd_ctx
);
335 /* JTAG interface, can be implemented with a software or hardware fifo
337 * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states. TAP_DRSHIFT/IRSHIFT as end states
338 * can be emulated by using a larger scan.
340 * Code that is relatively insensitive to the path(as long
341 * as it is JTAG compliant) taken through state machine can use
342 * endstate for jtag_add_xxx_scan(). Otherwise the pause state must be
343 * specified as end state and a subsequent jtag_add_pathmove() must
347 extern void jtag_add_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
348 extern int interface_jtag_add_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
349 extern void jtag_add_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
350 extern int interface_jtag_add_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
351 extern void jtag_add_plain_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
352 extern int interface_jtag_add_plain_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
353 extern void jtag_add_plain_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
354 extern int interface_jtag_add_plain_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
355 /* run a TAP_RESET reset. End state is TAP_RESET, regardless
358 extern void jtag_add_tlr(void);
359 extern int interface_jtag_add_tlr(void);
360 /* Do not use jtag_add_pathmove() unless you need to, but do use it
363 * DANGER! If the target is dependent upon a particular sequence
364 * of transitions for things to work correctly(e.g. as a workaround
365 * for an errata that contradicts the JTAG standard), then pathmove
366 * must be used, even if some jtag interfaces happen to use the
367 * desired path. Worse, the jtag interface used for testing a
368 * particular implementation, could happen to use the "desired"
369 * path when transitioning to/from end
372 * A list of unambigious single clock state transitions, not
373 * all drivers can support this, but it is required for e.g.
374 * XScale and Xilinx support
376 * Note! TAP_RESET must not be used in the path!
378 * Note that the first on the list must be reachable
379 * via a single transition from the current state.
381 * All drivers are required to implement jtag_add_pathmove().
382 * However, if the pathmove sequence can not be precisely
383 * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
384 * must return an error. It is legal, but not recommended, that
385 * a driver returns an error in all cases for a pathmove if it
386 * can only implement a few transitions and therefore
387 * a partial implementation of pathmove would have little practical
390 extern void jtag_add_pathmove(int num_states
, enum tap_state
*path
);
391 extern int interface_jtag_add_pathmove(int num_states
, enum tap_state
*path
);
392 /* go to TAP_IDLE, if we're not already there and cycle
393 * precisely num_cycles in the TAP_IDLE after which move
394 * to the end state, if it is != TAP_IDLE
396 * nb! num_cycles can be 0, in which case the fn will navigate
397 * to endstate via TAP_IDLE
399 extern void jtag_add_runtest(int num_cycles
, enum tap_state endstate
);
400 extern int interface_jtag_add_runtest(int num_cycles
, enum tap_state endstate
);
401 /* A reset of the TAP state machine can be requested.
403 * Whether tms or trst reset is used depends on the capabilities of
404 * the target and jtag interface(reset_config command configures this).
406 * srst can driver a reset of the TAP state machine and vice
409 * Application code may need to examine value of jtag_reset_config
410 * to determine the proper codepath
412 * DANGER! Even though srst drives trst, trst might not be connected to
413 * the interface, and it might actually be *harmful* to assert trst in this case.
415 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
418 * only req_tlr_or_trst and srst can have a transition for a
419 * call as the effects of transitioning both at the "same time"
420 * are undefined, but when srst_pulls_trst or vice versa,
421 * then trst & srst *must* be asserted together.
423 extern void jtag_add_reset(int req_tlr_or_trst
, int srst
);
424 /* this drives the actual srst and trst pins. srst will always be 0
425 * if jtag_reset_config & RESET_SRST_PULLS_TRST != 0 and ditto for
428 * the higher level jtag_add_reset will invoke jtag_add_tlr() if
431 extern int interface_jtag_add_reset(int trst
, int srst
);
432 extern void jtag_add_end_state(enum tap_state endstate
);
433 extern int interface_jtag_add_end_state(enum tap_state endstate
);
434 extern void jtag_add_sleep(u32 us
);
435 extern int interface_jtag_add_sleep(u32 us
);
438 * For software FIFO implementations, the queued commands can be executed
439 * during this call or earlier. A sw queue might decide to push out
440 * some of the jtag_add_xxx() operations once the queue is "big enough".
442 * This fn will return an error code if any of the prior jtag_add_xxx()
443 * calls caused a failure, e.g. check failure. Note that it does not
444 * matter if the operation was executed *before* jtag_execute_queue(),
445 * jtag_execute_queue() will still return an error code.
447 * All jtag_add_xxx() calls that have in_handler!=NULL will have been
448 * executed when this fn returns, but if what has been queued only
449 * clocks data out, without reading anything back, then JTAG could
450 * be running *after* jtag_execute_queue() returns. The API does
451 * not define a way to flush a hw FIFO that runs *after*
452 * jtag_execute_queue() returns.
454 * jtag_add_xxx() commands can either be executed immediately or
455 * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
457 extern int jtag_execute_queue(void);
458 /* can be implemented by hw+sw */
459 extern int interface_jtag_execute_queue(void);
460 extern int jtag_power_dropout(int *dropout
);
461 extern int jtag_srst_asserted(int *srst_asserted
);
463 /* JTAG support functions */
464 extern void jtag_set_check_value(scan_field_t
*field
, u8
*value
, u8
*mask
, error_handler_t
*in_error_handler
);
465 extern enum scan_type
jtag_scan_type(scan_command_t
*cmd
);
466 extern int jtag_scan_size(scan_command_t
*cmd
);
467 extern int jtag_read_buffer(u8
*buffer
, scan_command_t
*cmd
);
468 extern int jtag_build_buffer(scan_command_t
*cmd
, u8
**buffer
);
470 extern void jtag_sleep(u32 us
);
471 extern int jtag_call_event_callbacks(enum jtag_event event
);
472 extern int jtag_register_event_callback(int (*callback
)(enum jtag_event event
, void *priv
), void *priv
);
474 extern int jtag_verify_capture_ir
;
476 void jtag_tap_handle_event( jtag_tap_t
* tap
, enum jtag_tap_event e
);
479 * JTAG subsystem uses codes between -100 and -199 */
481 #define ERROR_JTAG_INIT_FAILED (-100)
482 #define ERROR_JTAG_INVALID_INTERFACE (-101)
483 #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
484 #define ERROR_JTAG_TRST_ASSERTED (-103)
485 #define ERROR_JTAG_QUEUE_FAILED (-104)
486 #define ERROR_JTAG_DEVICE_ERROR (-107)
488 /* this allows JTAG devices to implement the entire jtag_xxx() layer in hw/sw */
489 #ifdef HAVE_JTAG_MINIDRIVER_H
490 /* Here a #define MINIDRIVER() and an inline version of hw fifo interface_jtag_add_dr_out can be defined */
491 #include "jtag_minidriver.h"
492 #define MINIDRIVER(a) notused ## a
494 #define MINIDRIVER(a) a
495 /* jtag_add_dr_out() is a faster version of jtag_add_dr_scan()
497 * Current or end_state can not be TAP_RESET. end_state can be -1
499 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
501 * If the device is in bypass, then that is an error condition in
502 * the caller code that is not detected by this fn, whereas jtag_add_dr_scan()
503 * does detect it. Similarly if the device is not in bypass, data must
506 * If anything fails, then jtag_error will be set and jtag_execute() will
507 * return an error. There is no way to determine if there was a failure
508 * during this function call.
510 * Note that this jtag_add_dr_out can be defined as an inline function.
512 extern void interface_jtag_add_dr_out(jtag_tap_t
*tap
,
516 enum tap_state end_state
);
519 static __inline__
void jtag_add_dr_out(jtag_tap_t
*tap
,
523 enum tap_state end_state
)
526 cmd_queue_end_state
=end_state
;
527 cmd_queue_cur_state
=cmd_queue_end_state
;
528 interface_jtag_add_dr_out(tap
, num_fields
, num_bits
, value
, cmd_queue_end_state
);
532 * Function jtag_state_name
533 * Returns a string suitable for display representing the JTAG tap_state
535 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)