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>--------------------------------------------------*/
43 * When given an array, compute its DIMension; in other words, the
44 * number of elements in the array
46 #define DIM(x) (sizeof(x)/sizeof((x)[0]))
48 /** Calculate the number of bytes required to hold @a n TAP scan bits */
49 #define TAP_SCAN_BYTES(n) CEIL(n, 8)
51 /*-----</Macros>-------------------------------------------------*/
54 * Defines JTAG Test Access Port states.
56 * These definitions were gleaned from the ARM7TDMI-S Technical
57 * Reference Manual and validated against several other ARM core
58 * technical manuals. tap_get_tms_path() is sensitive to this numbering
59 * and ordering of the TAP states; furthermore, some interfaces require
60 * specific numbers be used, as they are handed-off directly to their
61 * 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 /// The current TAP state of the pending JTAG command queue.
106 extern tap_state_t cmd_queue_cur_state
;
107 /// The TAP state in which DR scans should end.
108 extern tap_state_t cmd_queue_end_state
;
111 * This structure defines a single scan field in the scan. It provides
112 * fields for the field's width and pointers to scan input and output
115 * In addition, this structure includes a value and mask that is used by
116 * jtag_add_dr_scan_check() to validate the value that was scanned out.
118 * The allocated, modified, and intmp fields are internal work space.
120 typedef struct scan_field_s
122 /// A pointer to the tap structure to which this field refers.
125 /// The number of bits this field specifies (up to 32)
127 /// A pointer to value to be scanned into the device
129 /// A pointer to a 32-bit memory location for data scanned out
132 /// The value used to check the data scanned out.
134 /// The mask to go with check_value
137 /// in_value has been allocated for the queue
139 /// Indicates we modified the in_value.
141 /// temporary storage for performing value checks synchronously
145 #ifdef INCLUDE_JTAG_INTERFACE_H
148 * The inferred type of a scan_command_s structure, indicating whether
149 * the command has the host scan in from the device, the host scan out
150 * to the device, or both.
153 /// From device to host,
155 /// From host to device,
157 /// Full-duplex scan.
162 * The scan_command provide a means of encapsulating a set of scan_field_s
163 * structures that should be scanned in/out to the device.
165 typedef struct scan_command_s
167 /// instruction/not data scan
169 /// number of fields in *fields array
171 /// pointer to an array of data scan fields
172 scan_field_t
* fields
;
173 /// state in which JTAG commands should finish
174 tap_state_t end_state
;
177 typedef struct statemove_command_s
179 /// state in which JTAG commands should finish
180 tap_state_t end_state
;
181 } statemove_command_t
;
183 typedef struct pathmove_command_s
185 /// number of states in *path
187 /// states that have to be passed
189 } pathmove_command_t
;
191 typedef struct runtest_command_s
193 /// number of cycles to spend in Run-Test/Idle state
195 /// state in which JTAG commands should finish
196 tap_state_t end_state
;
200 typedef struct stableclocks_command_s
202 /// number of clock cycles that should be sent
204 } stableclocks_command_t
;
207 typedef struct reset_command_s
209 /// Set TRST output: 0=deassert, 1=assert, -1=no change
211 /// Set SRST output: 0=deassert, 1=assert, -1=no change
215 typedef struct end_state_command_s
217 /// state in which JTAG commands should finish
218 tap_state_t end_state
;
219 } end_state_command_t
;
221 typedef struct sleep_command_s
223 /// number of microseconds to sleep
228 * Defines a container type that hold a pointer to a JTAG command
229 * structure of any defined type.
231 typedef union jtag_command_container_u
233 scan_command_t
* scan
;
234 statemove_command_t
* statemove
;
235 pathmove_command_t
* pathmove
;
236 runtest_command_t
* runtest
;
237 stableclocks_command_t
* stableclocks
;
238 reset_command_t
* reset
;
239 end_state_command_t
* end_state
;
240 sleep_command_t
* sleep
;
241 } jtag_command_container_t
;
244 * The type of the @c jtag_command_container_u contained by a
245 * @c jtag_command_s structure.
247 enum jtag_command_type
{
254 JTAG_STABLECLOCKS
= 8
257 typedef struct jtag_command_s
259 jtag_command_container_t cmd
;
260 enum jtag_command_type type
;
261 struct jtag_command_s
* next
;
264 /// The current queue of jtag_command_s structures.
265 extern jtag_command_t
* jtag_command_queue
;
267 extern void* cmd_queue_alloc(size_t size
);
268 extern void cmd_queue_free(void);
270 extern void jtag_queue_command(jtag_command_t
*cmd
);
271 extern void jtag_command_queue_reset(void);
273 #endif // INCLUDE_JTAG_INTERFACE_H
275 typedef struct jtag_tap_event_action_s jtag_tap_event_action_t
;
277 /* this is really: typedef jtag_tap_t */
278 /* But - the typedef is done in "types.h" */
279 /* due to "forward decloration reasons" */
284 const char* dotted_name
;
285 int abs_chain_position
;
286 /// Is this TAP enabled?
288 int ir_length
; /**< size of instruction register */
289 u32 ir_capture_value
;
290 u8
* expected
; /**< Capture-IR expected value */
292 u8
* expected_mask
; /**< Capture-IR expected mask */
294 /**< device identification code */
296 /// Array of expected identification codes */
298 /// Number of expected identification codes
301 /// current instruction
303 /// Bypass register selected
306 jtag_tap_event_action_t
*event_action
;
308 jtag_tap_t
* next_tap
;
310 extern jtag_tap_t
* jtag_AllTaps(void);
311 extern jtag_tap_t
* jtag_TapByPosition(int n
);
312 extern jtag_tap_t
* jtag_TapByString(const char* dotted_name
);
313 extern jtag_tap_t
* jtag_TapByJimObj(Jim_Interp
* interp
, Jim_Obj
* obj
);
314 extern jtag_tap_t
* jtag_TapByAbsPosition(int abs_position
);
315 extern int jtag_NumEnabledTaps(void);
316 extern int jtag_NumTotalTaps(void);
318 static __inline__ jtag_tap_t
* jtag_NextEnabledTap(jtag_tap_t
* p
)
322 /* start at the head of list */
327 /* start *after* this one */
346 enum reset_line_mode
{
347 LINE_OPEN_DRAIN
= 0x0,
348 LINE_PUSH_PULL
= 0x1,
355 extern char* jtag_event_strings
[];
357 enum jtag_tap_event
{
358 JTAG_TAP_EVENT_ENABLE
,
359 JTAG_TAP_EVENT_DISABLE
362 extern const Jim_Nvp nvp_jtag_tap_event
[];
364 struct jtag_tap_event_action_s
366 enum jtag_tap_event event
;
368 jtag_tap_event_action_t
* next
;
371 extern int jtag_trst
;
372 extern int jtag_srst
;
374 typedef struct jtag_event_callback_s
376 int (*callback
)(enum jtag_event event
, void* priv
);
378 struct jtag_event_callback_s
* next
;
379 } jtag_event_callback_t
;
381 extern jtag_event_callback_t
* jtag_event_callbacks
;
383 extern int jtag_speed
;
384 extern int jtag_speed_post_reset
;
388 RESET_HAS_TRST
= 0x1,
389 RESET_HAS_SRST
= 0x2,
390 RESET_TRST_AND_SRST
= 0x3,
391 RESET_SRST_PULLS_TRST
= 0x4,
392 RESET_TRST_PULLS_SRST
= 0x8,
393 RESET_TRST_OPEN_DRAIN
= 0x10,
394 RESET_SRST_PUSH_PULL
= 0x20,
397 extern enum reset_types jtag_reset_config
;
400 * Initialize interface upon startup. Return a successful no-op upon
401 * subsequent invocations.
403 extern int jtag_interface_init(struct command_context_s
* cmd_ctx
);
405 /// Shutdown the JTAG interface upon program exit.
406 extern int jtag_interface_quit(void);
409 * Initialize JTAG chain using only a RESET reset. If init fails,
412 extern int jtag_init(struct command_context_s
* cmd_ctx
);
414 /// reset, then initialize JTAG chain
415 extern int jtag_init_reset(struct command_context_s
* cmd_ctx
);
416 extern int jtag_register_commands(struct command_context_s
* cmd_ctx
);
420 * The JTAG interface can be implemented with a software or hardware fifo.
422 * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states; however,
423 * TAP_DRSHIFT/IRSHIFT can be emulated as end states, by using longer
426 * Code that is relatively insensitive to the path taken through state
427 * machine (as long as it is JTAG compliant) can use @a endstate for
428 * jtag_add_xxx_scan(). Otherwise, the pause state must be specified as
429 * end state and a subsequent jtag_add_pathmove() must be issued.
432 extern void jtag_add_ir_scan(int num_fields
, scan_field_t
* fields
, tap_state_t endstate
);
434 * The same as jtag_add_ir_scan except no verification is performed out
437 extern void jtag_add_ir_scan_noverify(int num_fields
, const scan_field_t
*fields
, tap_state_t state
);
441 * Set in_value to point to 32 bits of memory to scan into. This
442 * function is a way to handle the case of synchronous and asynchronous
445 * In the event of an asynchronous queue execution the queue buffer
446 * allocation method is used, for the synchronous case the temporary 32
447 * bits come from the input field itself.
449 extern void jtag_alloc_in_value32(scan_field_t
*field
);
451 extern void jtag_add_dr_scan(int num_fields
, const scan_field_t
* fields
, tap_state_t endstate
);
452 /// A version of jtag_add_dr_scan() that uses the check_value/mask fields
453 extern void jtag_add_dr_scan_check(int num_fields
, scan_field_t
* fields
, tap_state_t endstate
);
454 extern void jtag_add_plain_ir_scan(int num_fields
, const scan_field_t
* fields
, tap_state_t endstate
);
455 extern void jtag_add_plain_dr_scan(int num_fields
, const scan_field_t
* fields
, tap_state_t endstate
);
459 * Defines a simple JTAG callback that can allow conversions on data
460 * scanned in from an interface.
462 * This callback should only be used for conversion that cannot fail.
463 * For conversion types or checks that can fail, use the more complete
464 * variant: jtag_callback_t.
466 typedef void (*jtag_callback1_t
)(u8
*in
);
468 /// A simpler version of jtag_add_callback4().
469 extern void jtag_add_callback(jtag_callback1_t
, u8
*in
);
473 * Defines the type of data passed to the jtag_callback_t interface.
474 * The underlying type must allow storing an @c int or pointer type.
476 typedef intptr_t jtag_callback_data_t
;
479 * Defines the interface of the JTAG callback mechanism.
481 * @param in the pointer to the data clocked in
482 * @param data1 An integer big enough to use as an @c int or a pointer.
483 * @param data2 An integer big enough to use as an @c int or a pointer.
484 * @param data3 An integer big enough to use as an @c int or a pointer.
485 * @returns an error code
487 typedef int (*jtag_callback_t
)(u8
*in
, jtag_callback_data_t data1
, jtag_callback_data_t data2
, jtag_callback_data_t data3
);
491 * This callback can be executed immediately the queue has been flushed.
493 * The JTAG queue can be executed synchronously or asynchronously.
494 * Typically for USB, the queue is executed asynchronously. For
495 * low-latency interfaces, the queue may be executed synchronously.
497 * The callback mechanism is very general and does not make many
498 * assumptions about what the callback does or what its arguments are.
499 * These callbacks are typically executed *after* the *entire* JTAG
500 * queue has been executed for e.g. USB interfaces, and they are
501 * guaranteeed to be invoked in the order that they were queued.
503 * If the execution of the queue fails before the callbacks, then --
504 * depending on driver implementation -- the callbacks may or may not be
505 * invoked. @todo Can we make this behavior consistent?
507 * The strange name is due to C's lack of overloading using function
510 * @param f The callback function to add.
511 * @param in Typically used to point to the data to operate on.
512 * Frequently this will be the data clocked in during a shift operation.
513 * @param data1 An integer big enough to use as an @c int or a pointer.
514 * @param data2 An integer big enough to use as an @c int or a pointer.
515 * @param data3 An integer big enough to use as an @c int or a pointer.
518 extern void jtag_add_callback4(jtag_callback_t
, u8
*in
,
519 jtag_callback_data_t data1
, jtag_callback_data_t data2
,
520 jtag_callback_data_t data3
);
524 * Run a TAP_RESET reset where the end state is TAP_RESET,
525 * regardless of the start state.
527 extern void jtag_add_tlr(void);
530 * Application code *must* assume that interfaces will
531 * implement transitions between states with different
532 * paths and path lengths through the state diagram. The
533 * path will vary across interface and also across versions
534 * of the same interface over time. Even if the OpenOCD code
535 * is unchanged, the actual path taken may vary over time
536 * and versions of interface firmware or PCB revisions.
538 * Use jtag_add_pathmove() when specific transition sequences
541 * Do not use jtag_add_pathmove() unless you need to, but do use it
544 * DANGER! If the target is dependent upon a particular sequence
545 * of transitions for things to work correctly(e.g. as a workaround
546 * for an errata that contradicts the JTAG standard), then pathmove
547 * must be used, even if some jtag interfaces happen to use the
548 * desired path. Worse, the jtag interface used for testing a
549 * particular implementation, could happen to use the "desired"
550 * path when transitioning to/from end
553 * A list of unambigious single clock state transitions, not
554 * all drivers can support this, but it is required for e.g.
555 * XScale and Xilinx support
557 * Note! TAP_RESET must not be used in the path!
559 * Note that the first on the list must be reachable
560 * via a single transition from the current state.
562 * All drivers are required to implement jtag_add_pathmove().
563 * However, if the pathmove sequence can not be precisely
564 * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
565 * must return an error. It is legal, but not recommended, that
566 * a driver returns an error in all cases for a pathmove if it
567 * can only implement a few transitions and therefore
568 * a partial implementation of pathmove would have little practical
571 extern void jtag_add_pathmove(int num_states
, const tap_state_t
* path
);
574 * Goes to TAP_IDLE (if we're not already there), cycle
575 * precisely num_cycles in the TAP_IDLE state, after which move
576 * to @a endstate (unless it is also TAP_IDLE).
578 * @param num_cycles Number of cycles in TAP_IDLE state. This argument
579 * may be 0, in which case this routine will navigate to @a endstate
581 * @param endstate The final state.
583 extern void jtag_add_runtest(int num_cycles
, tap_state_t endstate
);
586 * A reset of the TAP state machine can be requested.
588 * Whether tms or trst reset is used depends on the capabilities of
589 * the target and jtag interface(reset_config command configures this).
591 * srst can driver a reset of the TAP state machine and vice
594 * Application code may need to examine value of jtag_reset_config
595 * to determine the proper codepath
597 * DANGER! Even though srst drives trst, trst might not be connected to
598 * the interface, and it might actually be *harmful* to assert trst in this case.
600 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
603 * only req_tlr_or_trst and srst can have a transition for a
604 * call as the effects of transitioning both at the "same time"
605 * are undefined, but when srst_pulls_trst or vice versa,
606 * then trst & srst *must* be asserted together.
608 extern void jtag_add_reset(int req_tlr_or_trst
, int srst
);
610 extern void jtag_add_end_state(tap_state_t endstate
);
611 extern void jtag_add_sleep(u32 us
);
615 * Function jtag_add_stable_clocks
616 * first checks that the state in which the clocks are to be issued is
617 * stable, then queues up clock_count clocks for transmission.
619 void jtag_add_clocks(int num_cycles
);
623 * For software FIFO implementations, the queued commands can be executed
624 * during this call or earlier. A sw queue might decide to push out
625 * some of the jtag_add_xxx() operations once the queue is "big enough".
627 * This fn will return an error code if any of the prior jtag_add_xxx()
628 * calls caused a failure, e.g. check failure. Note that it does not
629 * matter if the operation was executed *before* jtag_execute_queue(),
630 * jtag_execute_queue() will still return an error code.
632 * All jtag_add_xxx() calls that have in_handler!=NULL will have been
633 * executed when this fn returns, but if what has been queued only
634 * clocks data out, without reading anything back, then JTAG could
635 * be running *after* jtag_execute_queue() returns. The API does
636 * not define a way to flush a hw FIFO that runs *after*
637 * jtag_execute_queue() returns.
639 * jtag_add_xxx() commands can either be executed immediately or
640 * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
642 extern int jtag_execute_queue(void);
644 /* same as jtag_execute_queue() but does not clear the error flag */
645 extern void jtag_execute_queue_noclear(void);
648 * The jtag_error variable is set when an error occurs while executing
651 * This flag can also be set from application code, if an error happens
652 * during processing that should be reported during jtag_execute_queue().
654 * It is cleared by jtag_execute_queue().
656 extern int jtag_error
;
658 static __inline__
void jtag_set_error(int error
)
660 if ((error
==ERROR_OK
)||(jtag_error
!=ERROR_OK
))
662 /* keep first error */
670 /* can be implemented by hw+sw */
671 extern int jtag_power_dropout(int* dropout
);
672 extern int jtag_srst_asserted(int* srst_asserted
);
674 /* JTAG support functions */
677 * Execute jtag queue and check value with an optional mask.
678 * @param field Pointer to scan field.
679 * @param value Pointer to scan value.
680 * @param mask Pointer to scan mask; may be NULL.
681 * @returns Nothing, but calls jtag_set_error() on any error.
683 extern void jtag_check_value_mask(scan_field_t
*field
, u8
*value
, u8
*mask
);
685 #ifdef INCLUDE_JTAG_INTERFACE_H
686 extern enum scan_type
jtag_scan_type(const scan_command_t
* cmd
);
687 extern int jtag_scan_size(const scan_command_t
* cmd
);
688 extern int jtag_read_buffer(u8
* buffer
, const scan_command_t
* cmd
);
689 extern int jtag_build_buffer(const scan_command_t
* cmd
, u8
** buffer
);
690 #endif // INCLUDE_JTAG_INTERFACE_H
692 extern void jtag_sleep(u32 us
);
693 extern int jtag_call_event_callbacks(enum jtag_event event
);
694 extern int jtag_register_event_callback(int (* callback
)(enum jtag_event event
, void* priv
), void* priv
);
696 extern int jtag_verify_capture_ir
;
698 void jtag_tap_handle_event(jtag_tap_t
* tap
, enum jtag_tap_event e
);
701 * The JTAG subsystem defines a number of error codes,
702 * using codes between -100 and -199.
704 #define ERROR_JTAG_INIT_FAILED (-100)
705 #define ERROR_JTAG_INVALID_INTERFACE (-101)
706 #define ERROR_JTAG_NOT_IMPLEMENTED (-102)
707 #define ERROR_JTAG_TRST_ASSERTED (-103)
708 #define ERROR_JTAG_QUEUE_FAILED (-104)
709 #define ERROR_JTAG_NOT_STABLE_STATE (-105)
710 #define ERROR_JTAG_DEVICE_ERROR (-107)
713 * jtag_add_dr_out() is a version of jtag_add_dr_scan() which
714 * only scans data out. It operates on 32 bit integers instead
715 * of 8 bit, which makes it a better impedance match with
716 * the calling code which often operate on 32 bit integers.
718 * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
720 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
722 * If the device is in bypass, then that is an error condition in
723 * the caller code that is not detected by this fn, whereas
724 * jtag_add_dr_scan() does detect it. Similarly if the device is not in
725 * bypass, data must be passed to it.
727 * If anything fails, then jtag_error will be set and jtag_execute() will
728 * return an error. There is no way to determine if there was a failure
729 * during this function call.
731 * This is an inline fn to speed up embedded hosts. Also note that
732 * interface_jtag_add_dr_out() can be a *small* inline function for
735 * There is no jtag_add_dr_outin() version of this fn that also allows
736 * clocking data back in. Patches gladly accepted!
738 extern void jtag_add_dr_out(jtag_tap_t
* tap
,
739 int num_fields
, const int* num_bits
, const u32
* value
,
740 tap_state_t end_state
);
744 * jtag_add_statemove() moves from the current state to @a goal_state.
746 * This function was originally designed to handle the XSTATE command
747 * from the XSVF specification.
749 * @param goal_state The final TAP state.
750 * @return ERROR_OK on success, or an error code on failure.
752 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)