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_
37 * TLR - Test-Logic-Reset, RTI - Run-Test/Idle,
38 * SDS - Select-DR-Scan, CD - Capture-DR, SD - Shift-DR, E1D - Exit1-DR,
39 * PD - Pause-DR, E2D - Exit2-DR, UD - Update-DR,
40 * SIS - Select-IR-Scan, CI - Capture-IR, SI - Shift-IR, E1I - Exit1-IR,
41 * PI - Pause-IR, E2I - Exit2-IR, UI - Update-IR
45 TAP_TLR
= 0x0, TAP_RTI
= 0x8,
46 TAP_SDS
= 0x1, TAP_CD
= 0x2, TAP_SD
= 0x3, TAP_E1D
= 0x4,
47 TAP_PD
= 0x5, TAP_E2D
= 0x6, TAP_UD
= 0x7,
48 TAP_SIS
= 0x9, TAP_CI
= 0xa, TAP_SI
= 0xb, TAP_E1I
= 0xc,
49 TAP_PI
= 0xd, TAP_E2I
= 0xe, TAP_UI
= 0xf
52 typedef struct tap_transition_s
58 extern char* tap_state_strings
[16];
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 */
93 /* IN: from device to host, OUT: from host to device */
94 SCAN_IN
= 1, SCAN_OUT
= 2, SCAN_IO
= 3
97 typedef struct scan_command_s
99 int ir_scan
; /* instruction/not data scan */
100 int num_fields
; /* number of fields in *fields array */
101 scan_field_t
*fields
; /* pointer to an array of data scan fields */
102 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
105 typedef struct statemove_command_s
107 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
108 } statemove_command_t
;
110 typedef struct pathmove_command_s
112 int num_states
; /* number of states in *path */
113 enum tap_state
*path
; /* states that have to be passed */
114 } pathmove_command_t
;
116 typedef struct runtest_command_s
118 int num_cycles
; /* number of cycles that should be spent in Run-Test/Idle */
119 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
122 typedef struct reset_command_s
124 int trst
; /* trst/srst 0: deassert, 1: assert, -1: don't change */
128 typedef struct end_state_command_s
130 enum tap_state end_state
; /* TAP state in which JTAG commands should finish */
131 } end_state_command_t
;
133 typedef struct sleep_command_s
135 u32 us
; /* number of microseconds to sleep */
138 typedef union jtag_command_container_u
140 scan_command_t
*scan
;
141 statemove_command_t
*statemove
;
142 pathmove_command_t
*pathmove
;
143 runtest_command_t
*runtest
;
144 reset_command_t
*reset
;
145 end_state_command_t
*end_state
;
146 sleep_command_t
*sleep
;
147 } jtag_command_container_t
;
149 enum jtag_command_type
152 JTAG_STATEMOVE
= 2, JTAG_RUNTEST
= 3,
153 JTAG_RESET
= 4, JTAG_END_STATE
= 5,
154 JTAG_PATHMOVE
= 6, JTAG_SLEEP
= 7
157 typedef struct jtag_command_s
159 jtag_command_container_t cmd
;
160 enum jtag_command_type type
;
161 struct jtag_command_s
*next
;
164 extern jtag_command_t
*jtag_command_queue
;
166 // this is really: typedef jtag_tap_t
167 // But - the typedef is done in "types.h"
168 // due to "forward decloration reasons"
173 const char *dotted_name
;
174 int abs_chain_position
;
176 int ir_length
; /* size of instruction register */
177 u32 ir_capture_value
;
178 u8
*expected
; /* Capture-IR expected value */
180 u8
*expected_mask
; /* Capture-IR expected mask */
181 u32 idcode
; /* device identification code */
182 u32
*expected_ids
; /* Array of expected identification codes */
183 u8 expected_ids_cnt
;/* Number of expected identification codes */
184 u8
*cur_instr
; /* current instruction */
185 int bypass
; /* bypass register selected */
186 jtag_tap_t
*next_tap
;
188 extern jtag_tap_t
*jtag_AllTaps(void);
189 extern jtag_tap_t
*jtag_TapByPosition(int n
);
190 extern jtag_tap_t
*jtag_TapByPosition( int n
);
191 extern jtag_tap_t
*jtag_TapByString( const char *dotted_name
);
192 extern jtag_tap_t
*jtag_TapByJimObj( Jim_Interp
*interp
, Jim_Obj
*obj
);
193 extern jtag_tap_t
*jtag_TapByAbsPosition( int abs_position
);
194 extern int jtag_NumEnabledTaps(void);
195 extern int jtag_NumTotalTaps(void);
198 static __inline__ jtag_tap_t
*
199 jtag_NextEnabledTap( jtag_tap_t
*p
)
202 // start at the head of list
205 // start *after* this one
223 LINE_OPEN_DRAIN
= 0x0,
224 LINE_PUSH_PULL
= 0x1,
227 typedef struct jtag_interface_s
231 /* queued command execution
233 int (*execute_queue
)(void);
235 /* interface initalization
237 int (*speed
)(int speed
);
238 int (*register_commands
)(struct command_context_s
*cmd_ctx
);
241 /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
242 a failure if it can't support the KHz/RTCK.
244 WARNING!!!! if RTCK is *slow* then think carefully about
245 whether you actually want to support this in the driver.
246 Many target scripts are written to handle the absence of RTCK
247 and use a fallback kHz TCK.
249 int (*khz
)(int khz
, int *jtag_speed
);
250 /* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
251 a failure if it can't support the KHz/RTCK. */
252 int (*speed_div
)(int speed
, int *khz
);
254 /* Read and clear the power dropout flag. Note that a power dropout
255 can be transitionary, easily much less than a ms.
257 So to find out if the power is *currently* on, you must invoke
258 this method twice. Once to clear the power dropout flag and a
259 second time to read the current state.
261 Currently the default implementation is never to detect power dropout.
263 int (*power_dropout
)(int *power_dropout
);
264 /* Read and clear the srst asserted detection flag.
266 * NB!!!! like power_dropout this does *not* read the current
267 * state. srst assertion is transitionary and *can* be much
270 int (*srst_asserted
)(int *srst_asserted
);
279 extern char* jtag_event_strings
[];
281 extern int jtag_trst
;
282 extern int jtag_srst
;
284 typedef struct jtag_event_callback_s
286 int (*callback
)(enum jtag_event event
, void *priv
);
288 struct jtag_event_callback_s
*next
;
289 } jtag_event_callback_t
;
291 extern jtag_event_callback_t
*jtag_event_callbacks
;
293 extern jtag_interface_t
*jtag
; /* global pointer to configured JTAG interface */
294 extern enum tap_state end_state
;
295 extern enum tap_state cur_state
;
297 extern int jtag_speed
;
298 extern int jtag_speed_post_reset
;
303 RESET_HAS_TRST
= 0x1,
304 RESET_HAS_SRST
= 0x2,
305 RESET_TRST_AND_SRST
= 0x3,
306 RESET_SRST_PULLS_TRST
= 0x4,
307 RESET_TRST_PULLS_SRST
= 0x8,
308 RESET_TRST_OPEN_DRAIN
= 0x10,
309 RESET_SRST_PUSH_PULL
= 0x20,
312 extern enum reset_types jtag_reset_config
;
314 /* initialize interface upon startup. A successful no-op
315 * upon subsequent invocations
317 extern int jtag_interface_init(struct command_context_s
*cmd_ctx
);
318 /* initialize JTAG chain using only a TLR reset. If init fails,
321 extern int jtag_init(struct command_context_s
*cmd_ctx
);
322 /* reset, then initialize JTAG chain */
323 extern int jtag_init_reset(struct command_context_s
*cmd_ctx
);
324 extern int jtag_register_commands(struct command_context_s
*cmd_ctx
);
326 /* JTAG interface, can be implemented with a software or hardware fifo
328 * TAP_SD and TAP_SI are illegal end states. TAP_SD/SI as end states
329 * can be emulated by using a larger scan.
331 * Code that is relatively insensitive to the path(as long
332 * as it is JTAG compliant) taken through state machine can use
333 * endstate for jtag_add_xxx_scan(). Otherwise the pause state must be
334 * specified as end state and a subsequent jtag_add_pathmove() must
338 extern void jtag_add_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
339 extern int interface_jtag_add_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
340 extern void jtag_add_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
341 extern int interface_jtag_add_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
342 extern void jtag_add_plain_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
343 extern int interface_jtag_add_plain_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
344 extern void jtag_add_plain_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
345 extern int interface_jtag_add_plain_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
346 /* run a TAP_TLR reset. End state is TAP_TLR, regardless
349 extern void jtag_add_tlr(void);
350 extern int interface_jtag_add_tlr(void);
351 /* Do not use jtag_add_pathmove() unless you need to, but do use it
354 * DANGER! If the target is dependent upon a particular sequence
355 * of transitions for things to work correctly(e.g. as a workaround
356 * for an errata that contradicts the JTAG standard), then pathmove
357 * must be used, even if some jtag interfaces happen to use the
358 * desired path. Worse, the jtag interface used for testing a
359 * particular implementation, could happen to use the "desired"
360 * path when transitioning to/from end
363 * A list of unambigious single clock state transitions, not
364 * all drivers can support this, but it is required for e.g.
365 * XScale and Xilinx support
367 * Note! TAP_TLR must not be used in the path!
369 * Note that the first on the list must be reachable
370 * via a single transition from the current state.
372 * All drivers are required to implement jtag_add_pathmove().
373 * However, if the pathmove sequence can not be precisely
374 * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
375 * must return an error. It is legal, but not recommended, that
376 * a driver returns an error in all cases for a pathmove if it
377 * can only implement a few transitions and therefore
378 * a partial implementation of pathmove would have little practical
381 extern void jtag_add_pathmove(int num_states
, enum tap_state
*path
);
382 extern int interface_jtag_add_pathmove(int num_states
, enum tap_state
*path
);
383 /* go to TAP_RTI, if we're not already there and cycle
384 * precisely num_cycles in the TAP_RTI after which move
385 * to the end state, if it is != TAP_RTI
387 * nb! num_cycles can be 0, in which case the fn will navigate
388 * to endstate via TAP_RTI
390 extern void jtag_add_runtest(int num_cycles
, enum tap_state endstate
);
391 extern int interface_jtag_add_runtest(int num_cycles
, enum tap_state endstate
);
392 /* A reset of the TAP state machine can be requested.
394 * Whether tms or trst reset is used depends on the capabilities of
395 * the target and jtag interface(reset_config command configures this).
397 * srst can driver a reset of the TAP state machine and vice
400 * Application code may need to examine value of jtag_reset_config
401 * to determine the proper codepath
403 * DANGER! Even though srst drives trst, trst might not be connected to
404 * the interface, and it might actually be *harmful* to assert trst in this case.
406 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
409 * only req_tlr_or_trst and srst can have a transition for a
410 * call as the effects of transitioning both at the "same time"
411 * are undefined, but when srst_pulls_trst or vice versa,
412 * then trst & srst *must* be asserted together.
414 extern void jtag_add_reset(int req_tlr_or_trst
, int srst
);
415 /* this drives the actual srst and trst pins. srst will always be 0
416 * if jtag_reset_config & RESET_SRST_PULLS_TRST != 0 and ditto for
419 * the higher level jtag_add_reset will invoke jtag_add_tlr() if
422 extern int interface_jtag_add_reset(int trst
, int srst
);
423 extern void jtag_add_end_state(enum tap_state endstate
);
424 extern int interface_jtag_add_end_state(enum tap_state endstate
);
425 extern void jtag_add_sleep(u32 us
);
426 extern int interface_jtag_add_sleep(u32 us
);
431 * For software FIFO implementations, the queued commands can be executed
432 * during this call or earlier. A sw queue might decide to push out
433 * some of the jtag_add_xxx() operations once the queue is "big enough".
435 * This fn will return an error code if any of the prior jtag_add_xxx()
436 * calls caused a failure, e.g. check failure. Note that it does not
437 * matter if the operation was executed *before* jtag_execute_queue(),
438 * jtag_execute_queue() will still return an error code.
440 * All jtag_add_xxx() calls that have in_handler!=NULL will have been
441 * executed when this fn returns, but if what has been queued only
442 * clocks data out, without reading anything back, then JTAG could
443 * be running *after* jtag_execute_queue() returns. The API does
444 * not define a way to flush a hw FIFO that runs *after*
445 * jtag_execute_queue() returns.
447 * jtag_add_xxx() commands can either be executed immediately or
448 * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
450 extern int jtag_execute_queue(void);
451 /* can be implemented by hw+sw */
452 extern int interface_jtag_execute_queue(void);
453 extern int jtag_power_dropout(int *dropout
);
454 extern int jtag_srst_asserted(int *srst_asserted
);
457 /* JTAG support functions */
458 extern void jtag_set_check_value(scan_field_t
*field
, u8
*value
, u8
*mask
, error_handler_t
*in_error_handler
);
459 extern enum scan_type
jtag_scan_type(scan_command_t
*cmd
);
460 extern int jtag_scan_size(scan_command_t
*cmd
);
461 extern int jtag_read_buffer(u8
*buffer
, scan_command_t
*cmd
);
462 extern int jtag_build_buffer(scan_command_t
*cmd
, u8
**buffer
);
464 extern void jtag_sleep(u32 us
);
465 extern int jtag_call_event_callbacks(enum jtag_event event
);
466 extern int jtag_register_event_callback(int (*callback
)(enum jtag_event event
, void *priv
), void *priv
);
468 extern int jtag_verify_capture_ir
;
471 * JTAG subsystem uses codes between -100 and -199 */
473 #define ERROR_JTAG_INIT_FAILED (-100)
474 #define ERROR_JTAG_INVALID_INTERFACE (-101)
475 #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
476 #define ERROR_JTAG_TRST_ASSERTED (-103)
477 #define ERROR_JTAG_QUEUE_FAILED (-104)
478 #define ERROR_JTAG_DEVICE_ERROR (-107)
482 /* this allows JTAG devices to implement the entire jtag_xxx() layer in hw/sw */
483 #ifdef HAVE_JTAG_MINIDRIVER_H
484 /* Here a #define MINIDRIVER() and an inline version of hw fifo interface_jtag_add_dr_out can be defined */
485 #include "jtag_minidriver.h"
486 #define MINIDRIVER(a) notused ## a
488 #define MINIDRIVER(a) a
489 /* jtag_add_dr_out() is a faster version of jtag_add_dr_scan()
491 * Current or end_state can not be TAP_TLR. end_state can be -1
493 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
495 * If the device is in bypass, then that is an error condition in
496 * the caller code that is not detected by this fn, whereas jtag_add_dr_scan()
497 * does detect it. Similarly if the device is not in bypass, data must
500 * If anything fails, then jtag_error will be set and jtag_execute() will
501 * return an error. There is no way to determine if there was a failure
502 * during this function call.
504 * Note that this jtag_add_dr_out can be defined as an inline function.
506 extern void interface_jtag_add_dr_out(jtag_tap_t
*tap
,
510 enum tap_state end_state
);
516 static __inline__
void jtag_add_dr_out(jtag_tap_t
*tap
,
520 enum tap_state end_state
)
523 cmd_queue_end_state
=end_state
;
524 cmd_queue_cur_state
=cmd_queue_end_state
;
525 interface_jtag_add_dr_out(tap
, num_fields
, num_bits
, value
, cmd_queue_end_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)