jtag.h 25.2 KB
Newer Older
oharboe's avatar
oharboe committed
1
/***************************************************************************
2
3
4
*   Copyright (C) 2005 by Dominic Rath                                    *
*   Dominic.Rath@gmx.de                                                   *
*                                                                         *
5
*   Copyright (C) 2007,2008 Øyvind Harboe                                 *
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
*   oyvind.harboe@zylin.com                                               *
*                                                                         *
*   This program is free software; you can redistribute it and/or modify  *
*   it under the terms of the GNU General Public License as published by  *
*   the Free Software Foundation; either version 2 of the License, or     *
*   (at your option) any later version.                                   *
*                                                                         *
*   This program is distributed in the hope that it will be useful,       *
*   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
*   GNU General Public License for more details.                          *
*                                                                         *
*   You should have received a copy of the GNU General Public License     *
*   along with this program; if not, write to the                         *
*   Free Software Foundation, Inc.,                                       *
*   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
***************************************************************************/
oharboe's avatar
oharboe committed
23
24
25
26
#ifndef JTAG_H
#define JTAG_H

#include "binarybuffer.h"
27
#include "log.h"
oharboe's avatar
oharboe committed
28

29

30
31
32
33
#ifdef _DEBUG_JTAG_IO_
#define DEBUG_JTAG_IO(expr ...)		LOG_DEBUG(expr)
#else
#define DEBUG_JTAG_IO(expr ...)
oharboe's avatar
oharboe committed
34
35
#endif

36
#ifndef DEBUG_JTAG_IOZ
37
#define DEBUG_JTAG_IOZ 64
38
39
#endif

40
41
/*-----<Macros>--------------------------------------------------*/

42
43
44
45
/**
 * When given an array, compute its DIMension; in other words, the
 * number of elements in the array
 */
46
47
48
49
50
51
52
#define DIM(x)					(sizeof(x)/sizeof((x)[0]))

/** Calculate the number of bytes required to hold @a n TAP scan bits */
#define TAP_SCAN_BYTES(n)		CEIL(n, 8)

/*-----</Macros>-------------------------------------------------*/

53
54
55
56
57
58
59
60
61
/**
 * Defines JTAG Test Access Port states.
 *
 * These definitions were gleaned from the ARM7TDMI-S Technical
 * Reference Manual and validated against several other ARM core
 * technical manuals.  tap_get_tms_path() is sensitive to this numbering
 * and ordering of the TAP states; furthermore, some interfaces require
 * specific numbers be used, as they are handed-off directly to their
 * hardware implementations.
oharboe's avatar
oharboe committed
62
 */
63
64
typedef enum tap_state
{
oharboe's avatar
oharboe committed
65
#if BUILD_ZY1000
66
	/* These are the old numbers. Leave as-is for now... */
oharboe's avatar
oharboe committed
67
68
69
70
71
72
73
74
75
	TAP_RESET    = 0, TAP_IDLE = 8,
	TAP_DRSELECT = 1, TAP_DRCAPTURE = 2, TAP_DRSHIFT = 3, TAP_DREXIT1 = 4,
	TAP_DRPAUSE  = 5, TAP_DREXIT2 = 6, TAP_DRUPDATE = 7,
	TAP_IRSELECT = 9, TAP_IRCAPTURE = 10, TAP_IRSHIFT = 11, TAP_IREXIT1 = 12,
	TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,

	TAP_NUM_STATES = 16, TAP_INVALID = -1,
#else
	/* Proper ARM recommended numbers */
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
	TAP_DREXIT2 = 0x0,
	TAP_DREXIT1 = 0x1,
	TAP_DRSHIFT = 0x2,
	TAP_DRPAUSE = 0x3,
	TAP_IRSELECT = 0x4,
	TAP_DRUPDATE = 0x5,
	TAP_DRCAPTURE = 0x6,
	TAP_DRSELECT = 0x7,
	TAP_IREXIT2 = 0x8,
	TAP_IREXIT1 = 0x9,
	TAP_IRSHIFT = 0xa,
	TAP_IRPAUSE = 0xb,
	TAP_IDLE = 0xc,
	TAP_IRUPDATE = 0xd,
	TAP_IRCAPTURE = 0xe,
	TAP_RESET = 0x0f,
92

93
	TAP_NUM_STATES = 0x10,
94

95
	TAP_INVALID = -1,
oharboe's avatar
oharboe committed
96
#endif
97
} tap_state_t;
oharboe's avatar
oharboe committed
98

99
100
101
102
103
104
/**
 * Function tap_state_name
 * Returns a string suitable for display representing the JTAG tap_state
 */
const char* tap_state_name(tap_state_t state);

105
106
/// The current TAP state of the pending JTAG command queue.
extern tap_state_t cmd_queue_cur_state;
107

108
109
110
111
112
113
114
115
116
117
/**
 * This structure defines a single scan field in the scan. It provides
 * fields for the field's width and pointers to scan input and output
 * values.
 *
 * In addition, this structure includes a value and mask that is used by
 * jtag_add_dr_scan_check() to validate the value that was scanned out.
 *
 * The allocated, modified, and intmp fields are internal work space.
 */
oharboe's avatar
oharboe committed
118
119
typedef struct scan_field_s
{
120
121
122
123
124
125
	/// A pointer to the tap structure to which this field refers.
	jtag_tap_t* tap;

	/// The number of bits this field specifies (up to 32)
	int num_bits;
	/// A pointer to value to be scanned into the device
zwelch's avatar
zwelch committed
126
	uint8_t* out_value;
127
	/// A pointer to a 32-bit memory location for data scanned out
zwelch's avatar
zwelch committed
128
	uint8_t* in_value;
129
130

	/// The value used to check the data scanned out.
zwelch's avatar
zwelch committed
131
	uint8_t* check_value;
132
	/// The mask to go with check_value
zwelch's avatar
zwelch committed
133
	uint8_t* check_mask;
134
135
136
137
138
139

	/// in_value has been allocated for the queue
	int allocated;
	/// Indicates we modified the in_value.
	int modified;
	/// temporary storage for performing value checks synchronously
zwelch's avatar
zwelch committed
140
	uint8_t intmp[4];
oharboe's avatar
oharboe committed
141
142
} scan_field_t;

143
144
typedef struct jtag_tap_event_action_s jtag_tap_event_action_t;

145
146
147
/* this is really: typedef jtag_tap_t */
/* But - the typedef is done in "types.h" */
/* due to "forward decloration reasons" */
148
struct jtag_tap_s
oharboe's avatar
oharboe committed
149
{
150
151
152
	const char* chip;
	const char* tapname;
	const char* dotted_name;
153
	int abs_chain_position;
zwelch's avatar
zwelch committed
154
155
156
157
	/// Is this TAP disabled after JTAG reset?
	bool disabled_after_reset;
	/// Is this TAP currently enabled?
	bool enabled;
158
	int ir_length; /**< size of instruction register */
159
	uint32_t ir_capture_value;
zwelch's avatar
zwelch committed
160
	uint8_t* expected; /**< Capture-IR expected value */
161
	uint32_t ir_capture_mask;
zwelch's avatar
zwelch committed
162
	uint8_t* expected_mask; /**< Capture-IR expected mask */
163
	uint32_t idcode;
164
165
166
	/**< device identification code */

	/// Array of expected identification codes */
167
	uint32_t* expected_ids;
168
	/// Number of expected identification codes
zwelch's avatar
zwelch committed
169
	uint8_t expected_ids_cnt;
170
171

	/// current instruction
zwelch's avatar
zwelch committed
172
	uint8_t* cur_instr;
173
174
175
176
	/// Bypass register selected
	int bypass;

	jtag_tap_event_action_t *event_action;
177
178

	jtag_tap_t* next_tap;
179
};
zwelch's avatar
zwelch committed
180
181
182
183

void jtag_tap_init(jtag_tap_t *tap);
void jtag_tap_free(jtag_tap_t *tap);

184
extern jtag_tap_t* jtag_all_taps(void);
zwelch's avatar
zwelch committed
185
extern const char *jtag_tap_name(const jtag_tap_t *tap);
186
extern jtag_tap_t* jtag_tap_by_string(const char* dotted_name);
187
extern jtag_tap_t* jtag_tap_by_jim_obj(Jim_Interp* interp, Jim_Obj* obj);
188
extern jtag_tap_t* jtag_tap_next_enabled(jtag_tap_t* p);
189
extern unsigned jtag_tap_count_enabled(void);
190
extern unsigned jtag_tap_count(void);
191
192


zwelch's avatar
zwelch committed
193
/*
194
 * There are three cases when JTAG_TRST_ASSERTED callback is invoked. The
zwelch's avatar
zwelch committed
195
196
 * event is invoked *after* TRST is asserted(or queued rather). It is illegal
 * to communicate with the JTAG interface during the callback(as there is
197
 * currently a queue being built).
zwelch's avatar
zwelch committed
198
 *
199
200
201
 * - TMS reset
 * - SRST pulls TRST
 * - TRST asserted
zwelch's avatar
zwelch committed
202
 *
zwelch's avatar
zwelch committed
203
204
205
 * TAP activation/deactivation is currently implemented outside the core
 * using scripted code that understands the specific router type.
 */
206
enum jtag_event {
zwelch's avatar
zwelch committed
207
	JTAG_TRST_ASSERTED,
208
	JTAG_TAP_EVENT_ENABLE,
zwelch's avatar
zwelch committed
209
	JTAG_TAP_EVENT_DISABLE,
210
211
};

212
213
struct jtag_tap_event_action_s
{
zwelch's avatar
zwelch committed
214
	enum jtag_event		event;
215
216
	Jim_Obj*                 body;
	jtag_tap_event_action_t* next;
217
};
oharboe's avatar
oharboe committed
218

zwelch's avatar
zwelch committed
219
220
221
222
223
224
225
226
227
228
229
230
231
/**
 * Defines the function signature requide for JTAG event callback
 * functions, which are added with jtag_register_event_callback()
 * and removed jtag_unregister_event_callback().
 * @param event The event to handle.
 * @param prive A pointer to data that was passed to
 *	jtag_register_event_callback().
 * @returns Must return ERROR_OK on success, or an error code on failure.
 *
 * @todo Change to return void or define a use for its return code.
 */
typedef int (*jtag_event_handler_t)(enum jtag_event event, void* priv);

232
extern int jtag_register_event_callback(jtag_event_handler_t f, void *x);
zwelch's avatar
zwelch committed
233
extern int jtag_unregister_event_callback(jtag_event_handler_t f, void *x);
234
235
236

extern int jtag_call_event_callbacks(enum jtag_event event);

oharboe's avatar
oharboe committed
237

238
239
/// @returns The current JTAG speed setting.
int jtag_get_speed(void);
240
241
/**
 * Given a @a speed setting, use the interface @c speed_div callback to
zwelch's avatar
zwelch committed
242
 * adjust the setting.
243
244
245
246
247
 * @param speed The speed setting to convert back to readable KHz.
 * @returns ERROR_OK if the interface has not been initialized or on success;
 * 	otherwise, the error code produced by the @c speed_div callback.
 */
int jtag_get_speed_readable(int *speed);
248
249
250
251
252
253
254
/**
 * Set the JTAG speed. This routine will call the underlying
 * interface @c speed callback, if the interface has been initialized.
 * @param speed The new speed setting.
 * @returns ERROR_OK during configuration or on success, or an error
 *   code returned from the interface @c speed callback.
 */
255
int jtag_config_speed(int speed);
256

257
258
259

/// Attempt to configure the interface for the specified KHz.
int jtag_config_khz(unsigned khz);
260
261
262
263
264
/**
 * Attempt to enable RTCK/RCLK. If that fails, fallback to the
 * specified frequency.
 */
int jtag_config_rclk(unsigned fallback_speed_khz);
265
266
267
268
/// Retreives the clock speed of the JTAG interface in KHz.
unsigned jtag_get_speed_khz(void);


269
270
271
272
273
enum reset_types {
	RESET_NONE            = 0x0,
	RESET_HAS_TRST        = 0x1,
	RESET_HAS_SRST        = 0x2,
	RESET_TRST_AND_SRST   = 0x3,
oharboe's avatar
oharboe committed
274
275
276
	RESET_SRST_PULLS_TRST = 0x4,
	RESET_TRST_PULLS_SRST = 0x8,
	RESET_TRST_OPEN_DRAIN = 0x10,
277
	RESET_SRST_PUSH_PULL  = 0x20,
oharboe's avatar
oharboe committed
278
279
};

280
281
enum reset_types jtag_get_reset_config(void);
void jtag_set_reset_config(enum reset_types type);
oharboe's avatar
oharboe committed
282

283
284
285
286
287
288
289
290
291
292
293
void jtag_set_nsrst_delay(unsigned delay);
unsigned jtag_get_nsrst_delay(void);

void jtag_set_ntrst_delay(unsigned delay);
unsigned jtag_get_ntrst_delay(void);

/// @returns The current state of TRST.
int jtag_get_trst(void);
/// @returns The current state of SRST.
int jtag_get_srst(void);

294
295
296
297
/// Enable or disable data scan verification checking.
void jtag_set_verify(bool enable);
/// @returns True if data scan verification will be performed.
bool jtag_will_verify(void);
298

299
300
301
302
/// Enable or disable verification of IR scan checking.
void jtag_set_verify_capture_ir(bool enable);
/// @returns True if IR scan verification will be performed.
bool jtag_will_verify_capture_ir(void);
303

304
305
306
/**
 * Initialize interface upon startup.  Return a successful no-op upon
 * subsequent invocations.
307
 */
308
309
extern int  jtag_interface_init(struct command_context_s* cmd_ctx);

310
311
312
/// Shutdown the JTAG interface upon program exit.
extern int  jtag_interface_quit(void);

313
314
/**
 * Initialize JTAG chain using only a RESET reset. If init fails,
315
316
 * try reset + init.
 */
317
318
extern int  jtag_init(struct command_context_s* cmd_ctx);

319
/// reset, then initialize JTAG chain
320
321
extern int  jtag_init_reset(struct command_context_s* cmd_ctx);
extern int  jtag_register_commands(struct command_context_s* cmd_ctx);
oharboe's avatar
oharboe committed
322

323
324
325
/**
 * @file
 * The JTAG interface can be implemented with a software or hardware fifo.
326
 *
327
328
329
 * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states; however,
 * TAP_DRSHIFT/IRSHIFT can be emulated as end states, by using longer
 * scans.
330
 *
331
332
333
334
 * Code that is relatively insensitive to the path taken through state
 * machine (as long as it is JTAG compliant) can use @a endstate for
 * jtag_add_xxx_scan(). Otherwise, the pause state must be specified as
 * end state and a subsequent jtag_add_pathmove() must be issued.
335
 */
336

337
338
339
340
341
342
343
344
345
346
347
/**
 * Generate an IR SCAN with a list of scan fields with one entry for
 * each enabled TAP.
 *
 * If the input field list contains an instruction value for a TAP then
 * that is used otherwise the TAP is set to bypass.
 *
 * TAPs for which no fields are passed are marked as bypassed for
 * subsequent DR SCANs.
 *
 */
348
extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
349
350
351
352
/**
 * The same as jtag_add_ir_scan except no verification is performed out
 * the output values.
 */
353
extern void jtag_add_ir_scan_noverify(int num_fields, const scan_field_t *fields, tap_state_t state);
354
355
356
357
358
359
/**
 * Duplicate the scan fields passed into the function into an IR SCAN
 * command.  This function assumes that the caller handles extra fields
 * for bypassed TAPs.
 */
extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
360

361
362
363
364

/**
 * Set in_value to point to 32 bits of memory to scan into. This
 * function is a way to handle the case of synchronous and asynchronous
365
366
367
 * JTAG queues.
 *
 * In the event of an asynchronous queue execution the queue buffer
368
369
 * allocation method is used, for the synchronous case the temporary 32
 * bits come from the input field itself.
370
371
372
 */
extern void jtag_alloc_in_value32(scan_field_t *field);

373
374
375
376
377
378
/**
 * Generate a DR SCAN using the fields passed to the function.
 * For connected TAPs, the function checks in_fields and uses fields
 * specified there.  For bypassed TAPs, the function generates a dummy
 * 1-bit field.  The bypass status of TAPs is set by jtag_add_ir_scan().
 */
379
380
extern void jtag_add_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
/// A version of jtag_add_dr_scan() that uses the check_value/mask fields
381
extern void jtag_add_dr_scan_check(int num_fields, scan_field_t* fields, tap_state_t endstate);
382
383
384
385
386
/**
 * Duplicate the scan fields passed into the function into a DR SCAN
 * command.  Unlike jtag_add_dr_scan(), this function assumes that the
 * caller handles extra fields for bypassed TAPs.
 */
387
extern void jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
388

389
390
391
392
393
/**
 * Defines the type of data passed to the jtag_callback_t interface.
 * The underlying type must allow storing an @c int or pointer type.
 */
typedef intptr_t jtag_callback_data_t;
394

395
396
397
398
399
400
401
402
/**
 * Defines a simple JTAG callback that can allow conversions on data
 * scanned in from an interface.
 *
 * This callback should only be used for conversion that cannot fail.
 * For conversion types or checks that can fail, use the more complete
 * variant: jtag_callback_t.
 */
403
typedef void (*jtag_callback1_t)(jtag_callback_data_t data0);
404

405
/// A simpler version of jtag_add_callback4().
406
extern void jtag_add_callback(jtag_callback1_t, jtag_callback_data_t data0);
407

oharboe's avatar
oharboe committed
408

409

410
411
/**
 * Defines the interface of the JTAG callback mechanism.
412
 *
413
414
415
416
417
 * @param in the pointer to the data clocked in
 * @param data1 An integer big enough to use as an @c int or a pointer.
 * @param data2 An integer big enough to use as an @c int or a pointer.
 * @param data3 An integer big enough to use as an @c int or a pointer.
 * @returns an error code
418
 */
419
typedef int (*jtag_callback_t)(jtag_callback_data_t data0, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3);
420
421


422
423
/**
 * This callback can be executed immediately the queue has been flushed.
424
 *
425
426
427
 * The JTAG queue can be executed synchronously or asynchronously.
 * Typically for USB, the queue is executed asynchronously.  For
 * low-latency interfaces, the queue may be executed synchronously.
428
 *
429
430
431
432
433
 * The callback mechanism is very general and does not make many
 * assumptions about what the callback does or what its arguments are.
 * These callbacks are typically executed *after* the *entire* JTAG
 * queue has been executed for e.g. USB interfaces, and they are
 * guaranteeed to be invoked in the order that they were queued.
434
 *
435
436
437
 * If the execution of the queue fails before the callbacks, then --
 * depending on driver implementation -- the callbacks may or may not be
 * invoked.  @todo Can we make this behavior consistent?
438
 *
439
440
 * The strange name is due to C's lack of overloading using function
 * arguments.
441
 *
442
 * @param f The callback function to add.
443
 * @param data0 Typically used to point to the data to operate on.
444
445
446
447
 * Frequently this will be the data clocked in during a shift operation.
 * @param data1 An integer big enough to use as an @c int or a pointer.
 * @param data2 An integer big enough to use as an @c int or a pointer.
 * @param data3 An integer big enough to use as an @c int or a pointer.
448
449
 *
 */
450
extern void jtag_add_callback4(jtag_callback_t f, jtag_callback_data_t data0,
451
452
		jtag_callback_data_t data1, jtag_callback_data_t data2,
		jtag_callback_data_t data3);
453
454


455
456
457
/**
 * Run a TAP_RESET reset where the end state is TAP_RESET,
 * regardless of the start state.
458
 */
oharboe's avatar
oharboe committed
459
extern void jtag_add_tlr(void);
460

461
462
/**
 * Application code *must* assume that interfaces will
oharboe's avatar
oharboe committed
463
464
465
466
467
468
 * implement transitions between states with different
 * paths and path lengths through the state diagram. The
 * path will vary across interface and also across versions
 * of the same interface over time. Even if the OpenOCD code
 * is unchanged, the actual path taken may vary over time
 * and versions of interface firmware or PCB revisions.
469
 *
oharboe's avatar
oharboe committed
470
471
 * Use jtag_add_pathmove() when specific transition sequences
 * are required.
472
 *
oharboe's avatar
oharboe committed
473
 * Do not use jtag_add_pathmove() unless you need to, but do use it
474
 * if you have to.
oharboe's avatar
oharboe committed
475
 *
476
 * DANGER! If the target is dependent upon a particular sequence
477
478
479
480
481
 * of transitions for things to work correctly(e.g. as a workaround
 * for an errata that contradicts the JTAG standard), then pathmove
 * must be used, even if some jtag interfaces happen to use the
 * desired path. Worse, the jtag interface used for testing a
 * particular implementation, could happen to use the "desired"
482
483
 * path when transitioning to/from end
 * state.
oharboe's avatar
oharboe committed
484
 *
485
 * A list of unambigious single clock state transitions, not
oharboe's avatar
oharboe committed
486
487
 * all drivers can support this, but it is required for e.g.
 * XScale and Xilinx support
488
 *
489
 * Note! TAP_RESET must not be used in the path!
490
491
492
 *
 * Note that the first on the list must be reachable
 * via a single transition from the current state.
493
494
495
496
497
498
499
500
501
 *
 * All drivers are required to implement jtag_add_pathmove().
 * However, if the pathmove sequence can not be precisely
 * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
 * must return an error. It is legal, but not recommended, that
 * a driver returns an error in all cases for a pathmove if it
 * can only implement a few transitions and therefore
 * a partial implementation of pathmove would have little practical
 * application.
502
503
504
505
506
507
 *
 * If an error occurs, jtag_error will contain one of these error codes:
 *   - ERROR_JTAG_NOT_STABLE_STATE -- The final state was not stable.
 *   - ERROR_JTAG_STATE_INVALID -- The path passed through TAP_RESET.
 *   - ERROR_JTAG_TRANSITION_INVALID -- The path includes invalid
 *     state transitions.
oharboe's avatar
oharboe committed
508
 */
509
extern void jtag_add_pathmove(int num_states, const tap_state_t* path);
510

511
512
513
514
515
516
/**
 * jtag_add_statemove() moves from the current state to @a goal_state.
 *
 * @param goal_state The final TAP state.
 * @return ERROR_OK on success, or an error code on failure.
 *
zwelch's avatar
zwelch committed
517
 * Moves from the current state to the goal \a state.
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
 *
 * This needs to be handled according to the xsvf spec, see the XSTATE
 * command description.  From the XSVF spec, pertaining to XSTATE:
 *
 * For special states known as stable states (Test-Logic-Reset,
 * Run-Test/Idle, Pause-DR, Pause- IR), an XSVF interpreter follows
 * predefined TAP state paths when the starting state is a stable state
 * and when the XSTATE specifies a new stable state.  See the STATE
 * command in the [Ref 5] for the TAP state paths between stable
 * states.
 *
 * For non-stable states, XSTATE should specify a state that is only one
 * TAP state transition distance from the current TAP state to avoid
 * undefined TAP state paths. A sequence of multiple XSTATE commands can
 * be issued to transition the TAP through a specific state path.
 *
 * @note Unless @c tms_bits holds a path that agrees with [Ref 5] in the
 * above spec, then this code is not fully conformant to the xsvf spec.
 * This puts a burden on tap_get_tms_path() function from the xsvf spec.
 * If in doubt, you should confirm that that burden is being met.
 *
 * Otherwise, @a goal_state must be immediately reachable in one clock
 * cycle, and does not need to be a stable state.
 */
extern int jtag_add_statemove(tap_state_t goal_state);

544
545
546
547
548
549
550
551
552
/**
 * Goes to TAP_IDLE (if we're not already there), cycle
 * precisely num_cycles in the TAP_IDLE state, after which move
 * to @a endstate (unless it is also TAP_IDLE).
 *
 * @param num_cycles Number of cycles in TAP_IDLE state.  This argument
 * 	may be 0, in which case this routine will navigate to @a endstate
 * 	via TAP_IDLE.
 * @param endstate The final state.
oharboe's avatar
oharboe committed
553
 */
554
555
extern void jtag_add_runtest(int num_cycles, tap_state_t endstate);

556
557
/**
 * A reset of the TAP state machine can be requested.
558
559
 *
 * Whether tms or trst reset is used depends on the capabilities of
560
 * the target and jtag interface(reset_config  command configures this).
561
 *
562
563
 * srst can driver a reset of the TAP state machine and vice
 * versa
564
 *
565
566
 * Application code may need to examine value of jtag_reset_config
 * to determine the proper codepath
567
 *
568
569
 * DANGER! Even though srst drives trst, trst might not be connected to
 * the interface, and it might actually be *harmful* to assert trst in this case.
570
 *
571
 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
572
 * are supported.
573
 *
574
 * only req_tlr_or_trst and srst can have a transition for a
575
 * call as the effects of transitioning both at the "same time"
576
577
 * are undefined, but when srst_pulls_trst or vice versa,
 * then trst & srst *must* be asserted together.
578
 */
579
extern void jtag_add_reset(int req_tlr_or_trst, int srst);
580

581
582

/**
583
 * Function jtag_set_end_state
584
585
586
587
588
589
 *
 * Set a global variable to \a state if \a state != TAP_INVALID.
 *
 * Return the value of the global variable.
 *
 **/
590
extern tap_state_t jtag_set_end_state(tap_state_t state);
591
592
593
594
595
596
597
/**
 * Function jtag_get_end_state
 *
 * Return the value of the global variable for end state
 *
 **/
extern tap_state_t jtag_get_end_state(void);
598
extern void jtag_add_sleep(uint32_t us);
599

600
601
602
603
604
605

/**
 * Function jtag_add_stable_clocks
 * first checks that the state in which the clocks are to be issued is
 * stable, then queues up clock_count clocks for transmission.
 */
606
void jtag_add_clocks(int num_cycles);
607
608


609
/**
610
 * For software FIFO implementations, the queued commands can be executed
oharboe's avatar
oharboe committed
611
612
 * during this call or earlier. A sw queue might decide to push out
 * some of the jtag_add_xxx() operations once the queue is "big enough".
613
614
 *
 * This fn will return an error code if any of the prior jtag_add_xxx()
oharboe's avatar
oharboe committed
615
616
 * calls caused a failure, e.g. check failure. Note that it does not
 * matter if the operation was executed *before* jtag_execute_queue(),
617
618
 * jtag_execute_queue() will still return an error code.
 *
zwelch's avatar
zwelch committed
619
 * All jtag_add_xxx() calls that have in_handler != NULL will have been
620
621
622
623
624
625
626
627
 * executed when this fn returns, but if what has been queued only
 * clocks data out, without reading anything back, then JTAG could
 * be running *after* jtag_execute_queue() returns. The API does
 * not define a way to flush a hw FIFO that runs *after*
 * jtag_execute_queue() returns.
 *
 * jtag_add_xxx() commands can either be executed immediately or
 * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
oharboe's avatar
oharboe committed
628
 */
629
extern int jtag_execute_queue(void);
630

631
/// same as jtag_execute_queue() but does not clear the error flag
oharboe's avatar
oharboe committed
632
633
extern void jtag_execute_queue_noclear(void);

634
635
636
637
/// @returns the number of times the scan queue has been flushed
int jtag_get_flush_queue_count(void);


zwelch's avatar
zwelch committed
638
/* can be implemented by hw + sw */
639
640
extern int jtag_power_dropout(int* dropout);
extern int jtag_srst_asserted(int* srst_asserted);
641

oharboe's avatar
oharboe committed
642
/* JTAG support functions */
oharboe's avatar
oharboe committed
643

644
645
646
647
648
649
650
/**
 * Execute jtag queue and check value with an optional mask.
 * @param field Pointer to scan field.
 * @param value Pointer to scan value.
 * @param mask Pointer to scan mask; may be NULL.
 * @returns Nothing, but calls jtag_set_error() on any error.
 */
zwelch's avatar
zwelch committed
651
extern void jtag_check_value_mask(scan_field_t *field, uint8_t *value, uint8_t *mask);
652

653
extern void jtag_sleep(uint32_t us);
oharboe's avatar
oharboe committed
654

655
656
657
658
/*
 * The JTAG subsystem defines a number of error codes,
 * using codes between -100 and -199.
 */
659
660
661
662
663
664
665
#define ERROR_JTAG_INIT_FAILED       (-100)
#define ERROR_JTAG_INVALID_INTERFACE (-101)
#define ERROR_JTAG_NOT_IMPLEMENTED   (-102)
#define ERROR_JTAG_TRST_ASSERTED     (-103)
#define ERROR_JTAG_QUEUE_FAILED      (-104)
#define ERROR_JTAG_NOT_STABLE_STATE  (-105)
#define ERROR_JTAG_DEVICE_ERROR      (-107)
666
667
#define ERROR_JTAG_STATE_INVALID     (-108)
#define ERROR_JTAG_TRANSITION_INVALID (-109)
oharboe's avatar
oharboe committed
668

669
670
/**
 * jtag_add_dr_out() is a version of jtag_add_dr_scan() which
671
672
673
 * only scans data out. It operates on 32 bit integers instead
 * of 8 bit, which makes it a better impedance match with
 * the calling code which often operate on 32 bit integers.
674
 *
mifi's avatar
mifi committed
675
 * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
676
 *
677
 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
678
 *
679
 * If the device is in bypass, then that is an error condition in
680
681
682
 * the caller code that is not detected by this fn, whereas
 * jtag_add_dr_scan() does detect it. Similarly if the device is not in
 * bypass, data must be passed to it.
683
 *
684
685
686
 * If anything fails, then jtag_error will be set and jtag_execute() will
 * return an error. There is no way to determine if there was a failure
 * during this function call.
687
 *
688
689
690
691
692
693
 * This is an inline fn to speed up embedded hosts. Also note that
 * interface_jtag_add_dr_out() can be a *small* inline function for
 * embedded hosts.
 *
 * There is no jtag_add_dr_outin() version of this fn that also allows
 * clocking data back in. Patches gladly accepted!
694
 */
zwelch's avatar
zwelch committed
695
extern void jtag_add_dr_out(jtag_tap_t* tap,
696
		int num_fields, const int* num_bits, const uint32_t* value,
zwelch's avatar
zwelch committed
697
		tap_state_t end_state);
698
699


700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
/**
 * Set the current JTAG core execution error, unless one was set
 * by a previous call previously.  Driver or application code must
 * use jtag_error_clear to reset jtag_error once this routine has been
 * called with a non-zero error code.
 */
void jtag_set_error(int error);
/// @returns The current value of jtag_error
int jtag_get_error(void);
/**
 * Resets jtag_error to ERROR_OK, returning its previous value.
 * @returns The previous value of @c jtag_error.
 */
int jtag_error_clear(void);

oharboe's avatar
oharboe committed
715
#endif /* JTAG_H */