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 */
183 u8
*cur_instr
; /* current instruction */
184 int bypass
; /* bypass register selected */
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_NextEnabledTap( jtag_tap_t
* );
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);
202 LINE_OPEN_DRAIN
= 0x0,
203 LINE_PUSH_PULL
= 0x1,
206 typedef struct jtag_interface_s
210 /* queued command execution
212 int (*execute_queue
)(void);
214 /* interface initalization
216 int (*speed
)(int speed
);
217 int (*register_commands
)(struct command_context_s
*cmd_ctx
);
220 /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
221 a failure if it can't support the KHz/RTCK.
223 WARNING!!!! if RTCK is *slow* then think carefully about
224 whether you actually want to support this in the driver.
225 Many target scripts are written to handle the absence of RTCK
226 and use a fallback kHz TCK.
228 int (*khz
)(int khz
, int *jtag_speed
);
229 /* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
230 a failure if it can't support the KHz/RTCK. */
231 int (*speed_div
)(int speed
, int *khz
);
233 /* Read and clear the power dropout flag. Note that a power dropout
234 can be transitionary, easily much less than a ms.
236 So to find out if the power is *currently* on, you must invoke
237 this method twice. Once to clear the power dropout flag and a
238 second time to read the current state.
240 Currently the default implementation is never to detect power dropout.
242 int (*power_dropout
)(int *power_dropout
);
243 /* Read and clear the srst asserted detection flag.
245 * NB!!!! like power_dropout this does *not* read the current
246 * state. srst assertion is transitionary and *can* be much
249 int (*srst_asserted
)(int *srst_asserted
);
258 extern char* jtag_event_strings
[];
260 extern int jtag_trst
;
261 extern int jtag_srst
;
263 typedef struct jtag_event_callback_s
265 int (*callback
)(enum jtag_event event
, void *priv
);
267 struct jtag_event_callback_s
*next
;
268 } jtag_event_callback_t
;
270 extern jtag_event_callback_t
*jtag_event_callbacks
;
272 extern jtag_interface_t
*jtag
; /* global pointer to configured JTAG interface */
273 extern enum tap_state end_state
;
274 extern enum tap_state cur_state
;
276 extern int jtag_speed
;
277 extern int jtag_speed_post_reset
;
282 RESET_HAS_TRST
= 0x1,
283 RESET_HAS_SRST
= 0x2,
284 RESET_TRST_AND_SRST
= 0x3,
285 RESET_SRST_PULLS_TRST
= 0x4,
286 RESET_TRST_PULLS_SRST
= 0x8,
287 RESET_TRST_OPEN_DRAIN
= 0x10,
288 RESET_SRST_PUSH_PULL
= 0x20,
291 extern enum reset_types jtag_reset_config
;
293 /* initialize interface upon startup. A successful no-op
294 * upon subsequent invocations
296 extern int jtag_interface_init(struct command_context_s
*cmd_ctx
);
297 /* initialize JTAG chain using only a TLR reset. If init fails,
300 extern int jtag_init(struct command_context_s
*cmd_ctx
);
301 /* reset, then initialize JTAG chain */
302 extern int jtag_init_reset(struct command_context_s
*cmd_ctx
);
303 extern int jtag_register_commands(struct command_context_s
*cmd_ctx
);
305 /* JTAG interface, can be implemented with a software or hardware fifo
307 * TAP_SD and TAP_SI are illegal end states. TAP_SD/SI as end states
308 * can be emulated by using a larger scan.
310 * Code that is relatively insensitive to the path(as long
311 * as it is JTAG compliant) taken through state machine can use
312 * endstate for jtag_add_xxx_scan(). Otherwise the pause state must be
313 * specified as end state and a subsequent jtag_add_pathmove() must
317 extern void jtag_add_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
318 extern int interface_jtag_add_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
319 extern void jtag_add_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
320 extern int interface_jtag_add_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
321 extern void jtag_add_plain_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
322 extern int interface_jtag_add_plain_ir_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
323 extern void jtag_add_plain_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
324 extern int interface_jtag_add_plain_dr_scan(int num_fields
, scan_field_t
*fields
, enum tap_state endstate
);
325 /* run a TAP_TLR reset. End state is TAP_TLR, regardless
328 extern void jtag_add_tlr(void);
329 extern int interface_jtag_add_tlr(void);
330 /* Do not use jtag_add_pathmove() unless you need to, but do use it
333 * DANGER! If the target is dependent upon a particular sequence
334 * of transitions for things to work correctly(e.g. as a workaround
335 * for an errata that contradicts the JTAG standard), then pathmove
336 * must be used, even if some jtag interfaces happen to use the
337 * desired path. Worse, the jtag interface used for testing a
338 * particular implementation, could happen to use the "desired"
339 * path when transitioning to/from end
342 * A list of unambigious single clock state transitions, not
343 * all drivers can support this, but it is required for e.g.
344 * XScale and Xilinx support
346 * Note! TAP_TLR must not be used in the path!
348 * Note that the first on the list must be reachable
349 * via a single transition from the current state.
351 * All drivers are required to implement jtag_add_pathmove().
352 * However, if the pathmove sequence can not be precisely
353 * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
354 * must return an error. It is legal, but not recommended, that
355 * a driver returns an error in all cases for a pathmove if it
356 * can only implement a few transitions and therefore
357 * a partial implementation of pathmove would have little practical
360 extern void jtag_add_pathmove(int num_states
, enum tap_state
*path
);
361 extern int interface_jtag_add_pathmove(int num_states
, enum tap_state
*path
);
362 /* go to TAP_RTI, if we're not already there and cycle
363 * precisely num_cycles in the TAP_RTI after which move
364 * to the end state, if it is != TAP_RTI
366 * nb! num_cycles can be 0, in which case the fn will navigate
367 * to endstate via TAP_RTI
369 extern void jtag_add_runtest(int num_cycles
, enum tap_state endstate
);
370 extern int interface_jtag_add_runtest(int num_cycles
, enum tap_state endstate
);
371 /* A reset of the TAP state machine can be requested.
373 * Whether tms or trst reset is used depends on the capabilities of
374 * the target and jtag interface(reset_config command configures this).
376 * srst can driver a reset of the TAP state machine and vice
379 * Application code may need to examine value of jtag_reset_config
380 * to determine the proper codepath
382 * DANGER! Even though srst drives trst, trst might not be connected to
383 * the interface, and it might actually be *harmful* to assert trst in this case.
385 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
388 * only req_tlr_or_trst and srst can have a transition for a
389 * call as the effects of transitioning both at the "same time"
390 * are undefined, but when srst_pulls_trst or vice versa,
391 * then trst & srst *must* be asserted together.
393 extern void jtag_add_reset(int req_tlr_or_trst
, int srst
);
394 /* this drives the actual srst and trst pins. srst will always be 0
395 * if jtag_reset_config & RESET_SRST_PULLS_TRST != 0 and ditto for
398 * the higher level jtag_add_reset will invoke jtag_add_tlr() if
401 extern int interface_jtag_add_reset(int trst
, int srst
);
402 extern void jtag_add_end_state(enum tap_state endstate
);
403 extern int interface_jtag_add_end_state(enum tap_state endstate
);
404 extern void jtag_add_sleep(u32 us
);
405 extern int interface_jtag_add_sleep(u32 us
);
410 * For software FIFO implementations, the queued commands can be executed
411 * during this call or earlier. A sw queue might decide to push out
412 * some of the jtag_add_xxx() operations once the queue is "big enough".
414 * This fn will return an error code if any of the prior jtag_add_xxx()
415 * calls caused a failure, e.g. check failure. Note that it does not
416 * matter if the operation was executed *before* jtag_execute_queue(),
417 * jtag_execute_queue() will still return an error code.
419 * All jtag_add_xxx() calls that have in_handler!=NULL will have been
420 * executed when this fn returns, but if what has been queued only
421 * clocks data out, without reading anything back, then JTAG could
422 * be running *after* jtag_execute_queue() returns. The API does
423 * not define a way to flush a hw FIFO that runs *after*
424 * jtag_execute_queue() returns.
426 * jtag_add_xxx() commands can either be executed immediately or
427 * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
429 extern int jtag_execute_queue(void);
430 /* can be implemented by hw+sw */
431 extern int interface_jtag_execute_queue(void);
432 extern int jtag_power_dropout(int *dropout
);
433 extern int jtag_srst_asserted(int *srst_asserted
);
436 /* JTAG support functions */
437 extern void jtag_set_check_value(scan_field_t
*field
, u8
*value
, u8
*mask
, error_handler_t
*in_error_handler
);
438 extern enum scan_type
jtag_scan_type(scan_command_t
*cmd
);
439 extern int jtag_scan_size(scan_command_t
*cmd
);
440 extern int jtag_read_buffer(u8
*buffer
, scan_command_t
*cmd
);
441 extern int jtag_build_buffer(scan_command_t
*cmd
, u8
**buffer
);
443 extern void jtag_sleep(u32 us
);
444 extern int jtag_call_event_callbacks(enum jtag_event event
);
445 extern int jtag_register_event_callback(int (*callback
)(enum jtag_event event
, void *priv
), void *priv
);
447 extern int jtag_verify_capture_ir
;
450 * JTAG subsystem uses codes between -100 and -199 */
452 #define ERROR_JTAG_INIT_FAILED (-100)
453 #define ERROR_JTAG_INVALID_INTERFACE (-101)
454 #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
455 #define ERROR_JTAG_TRST_ASSERTED (-103)
456 #define ERROR_JTAG_QUEUE_FAILED (-104)
457 #define ERROR_JTAG_DEVICE_ERROR (-107)
461 /* this allows JTAG devices to implement the entire jtag_xxx() layer in hw/sw */
462 #ifdef HAVE_JTAG_MINIDRIVER_H
463 /* Here a #define MINIDRIVER() and an inline version of hw fifo interface_jtag_add_dr_out can be defined */
464 #include "jtag_minidriver.h"
465 #define MINIDRIVER(a) notused ## a
467 #define MINIDRIVER(a) a
468 /* jtag_add_dr_out() is a faster version of jtag_add_dr_scan()
470 * Current or end_state can not be TAP_TLR. end_state can be -1
472 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
474 * If the device is in bypass, then that is an error condition in
475 * the caller code that is not detected by this fn, whereas jtag_add_dr_scan()
476 * does detect it. Similarly if the device is not in bypass, data must
479 * If anything fails, then jtag_error will be set and jtag_execute() will
480 * return an error. There is no way to determine if there was a failure
481 * during this function call.
483 * Note that this jtag_add_dr_out can be defined as an inline function.
485 extern void interface_jtag_add_dr_out(jtag_tap_t
*tap
,
489 enum tap_state end_state
);
495 static __inline__
void jtag_add_dr_out(jtag_tap_t
*tap
,
499 enum tap_state end_state
)
502 cmd_queue_end_state
=end_state
;
503 cmd_queue_cur_state
=cmd_queue_end_state
;
504 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)