jtag.h 23.7 KB
Newer Older
oharboe's avatar
oharboe committed
1
/***************************************************************************
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
*   Copyright (C) 2005 by Dominic Rath                                    *
*   Dominic.Rath@gmx.de                                                   *
*                                                                         *
*   Copyright (C) 2007,2008 Øyvind Harboe                                 *
*   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
27
#ifndef JTAG_H
#define JTAG_H

#include "types.h"
#include "binarybuffer.h"
28
#include "log.h"
oharboe's avatar
oharboe committed
29
30
31

#include "command.h"

32

33
34
35
36
#ifdef _DEBUG_JTAG_IO_
#define DEBUG_JTAG_IO(expr ...)		LOG_DEBUG(expr)
#else
#define DEBUG_JTAG_IO(expr ...)
oharboe's avatar
oharboe committed
37
38
#endif

39
#ifndef DEBUG_JTAG_IOZ
40
#define DEBUG_JTAG_IOZ 64
41
42
#endif

43

44
/* 16 Tap States, from page 21 of ASSET InterTech, Inc.'s svf.pdf
oharboe's avatar
oharboe committed
45
 */
46
47
48
49
50
enum tap_state {
	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,
mifi's avatar
mifi committed
51
52
53
	TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,

	TAP_NUM_STATES = 16, TAP_INVALID = -1,
54
55
56
57
};

typedef enum tap_state tap_state_t;

oharboe's avatar
oharboe committed
58
59
typedef struct tap_transition_s
{
60
61
	tap_state_t high;
	tap_state_t low;
oharboe's avatar
oharboe committed
62
63
} tap_transition_t;

64
65
//extern tap_transition_t tap_transitions[16];    /* describe the TAP state diagram */

66

67
68
69
70
71
72
73
74
75
76
77
/*-----<Cable Helper API>-------------------------------------------*/

/* The "Cable Helper API" is what the cable drivers can use to help implement
 * their "Cable API".  So a Cable Helper API is a set of helper functions used by
 * cable drivers, and this is different from a Cable API.  A "Cable API" is what
 * higher level code used to talk to a cable.
 */


/** implementation of wrapper function tap_set_state() */
void tap_set_state_impl(tap_state_t new_state);
oharboe's avatar
oharboe committed
78

79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
/**
 * Function tap_set_state
 * sets the state of a "state follower" which tracks the state of the TAPs connected to the
 * cable.  The state follower is hopefully always in the same state as the actual
 * TAPs in the jtag chain, and will be so if there are no bugs in the tracking logic within that
 * cable driver. All the cable drivers call this function to indicate the state they think
 * the TAPs attached to their cables are in.  Because this function can also log transitions,
 * it will be helpful to call this function with every transition that the TAPs being manipulated
 * are expected to traverse, not just end points of a multi-step state path.
 * @param new_state is the state we think the TAPs are currently in or are about to enter.
 */
#if defined(_DEBUG_JTAG_IO_)
#define tap_set_state(new_state) \
	do { \
		LOG_DEBUG( "tap_set_state(%s)", tap_state_name(new_state) ); \
		tap_set_state_impl(new_state); \
	} while (0)
#else
static inline void tap_set_state(tap_state_t new_state)
{
	tap_set_state_impl(new_state);
}
oharboe's avatar
oharboe committed
101

102
#endif
oharboe's avatar
oharboe committed
103

104
105
106
107
108
109
110
111
/**
 * Function tap_get_state
 * gets the state of the "state follower" which tracks the state of the TAPs connected to
 * the cable.
 * @see tap_set_state
 * @return tap_state_t - The state the TAPs are in now.
 */
tap_state_t tap_get_state(void);
oharboe's avatar
oharboe committed
112

113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
/**
 * Function tap_set_end_state
 * sets the state of an "end state follower" which tracks the state that any cable driver
 * thinks will be the end (resultant) state of the current TAP SIR or SDR operation.  At completion
 * of that TAP operation this value is copied into the state follower via tap_set_state().
 * @param new_end_state is that state the TAPs should enter at completion of a pending TAP operation.
 */
void        tap_set_end_state(tap_state_t new_end_state);

/**
 * Function tap_get_end_state
 * @see tap_set_end_state
 * @return tap_state_t - The state the TAPs should be in at completion of the current TAP operation.
 */
tap_state_t tap_get_end_state(void);

/**
 * Function tap_get_tms_path
 * returns a 7 bit long "bit sequence" indicating what has to be done with TMS
 * during a sequence of seven TAP clock cycles in order to get from
 * state \a "from" to state \a "to".
 * @param from is the starting state
 * @param to is the resultant or final state
 * @return int - a 7 bit sequence, with the first bit in the sequence at bit 0.
 */
int tap_get_tms_path(tap_state_t from, tap_state_t to);

/**
 * Function tap_move_ndx
 * when given a stable state, returns an index from 0-5.  The index corresponds to a
 * sequence of stable states which are given in this order: <p>
 * { TAP_RESET, TAP_IDLE, TAP_DRSHIFT, TAP_DRPAUSE, TAP_IRSHIFT, TAP_IRPAUSE }
 * <p>
 * This sequence corresponds to look up tables which are used in some of the
 * cable drivers.
 * @param astate is the stable state to find in the sequence.  If a non stable
 *  state is passed, this may cause the program to output an error message
 *  and terminate.
 * @return int - the array (or sequence) index as described above
 */
int tap_move_ndx(tap_state_t astate);

/**
 * Function tap_is_state_stable
157
 * returns true if the \a astate is stable.
158
 */
159
bool tap_is_state_stable(tap_state_t astate);
160
161
162
163
164
165
166
167

/**
 * Function tap_state_transition
 * takes a current TAP state and returns the next state according to the tms value.
 * @param current_state is the state of a TAP currently.
 * @param tms is either zero or non-zero, just like a real TMS line in a jtag interface.
 * @return tap_state_t - the next state a TAP would enter.
 */
168
tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
169
170
171
172
173
174
175
176
177

/**
 * Function tap_state_name
 * Returns a string suitable for display representing the JTAG tap_state
 */
const char* tap_state_name(tap_state_t state);

/*-----</Cable Helper API>------------------------------------------*/

178

179
180
181
182
extern tap_state_t cmd_queue_end_state;         /* finish DR scans in dr_end_state */
extern tap_state_t cmd_queue_cur_state;         /* current TAP state */

typedef void* error_handler_t;  /* Later on we can delete error_handler_t, but keep it for now to make patches more readable */
oharboe's avatar
oharboe committed
183
184

struct scan_field_s;
185
typedef int (*in_handler_t)(u8* in_value, void* priv, struct scan_field_s* field);
oharboe's avatar
oharboe committed
186
187
188

typedef struct scan_field_s
{
189
190
191
192
193
	jtag_tap_t* tap;                /* tap pointer this instruction refers to */
	int         num_bits;           /* number of bits this field specifies (up to 32) */
	u8*         out_value;          /* value to be scanned into the device */
	u8*         out_mask;           /* only masked bits care */
	u8*         in_value;           /* pointer to a 32-bit memory location to take data scanned out */
oharboe's avatar
oharboe committed
194
	/* in_check_value/mask, in_handler_error_handler, in_handler_priv can be used by the in handler, otherwise they contain garbage  */
195
196
197
198
	u8*          in_check_value;    /* used to validate scan results */
	u8*          in_check_mask;     /* check specified bits against check_value */
	in_handler_t in_handler;        /* process received buffer using this handler */
	void*        in_handler_priv;   /* additional information for the in_handler */
oharboe's avatar
oharboe committed
199
200
} scan_field_t;

201
enum scan_type {
oharboe's avatar
oharboe committed
202
203
204
205
206
207
	/* IN: from device to host, OUT: from host to device */
	SCAN_IN = 1, SCAN_OUT = 2, SCAN_IO = 3
};

typedef struct scan_command_s
{
208
209
210
211
	int           ir_scan;      /* instruction/not data scan */
	int           num_fields;   /* number of fields in *fields array */
	scan_field_t* fields;       /* pointer to an array of data scan fields */
	tap_state_t   end_state;    /* TAP state in which JTAG commands should finish */
oharboe's avatar
oharboe committed
212
213
214
215
} scan_command_t;

typedef struct statemove_command_s
{
216
	tap_state_t end_state;   /* TAP state in which JTAG commands should finish */
oharboe's avatar
oharboe committed
217
218
219
220
} statemove_command_t;

typedef struct pathmove_command_s
{
221
222
	int          num_states;    /* number of states in *path */
	tap_state_t* path;          /* states that have to be passed */
oharboe's avatar
oharboe committed
223
224
225
226
} pathmove_command_t;

typedef struct runtest_command_s
{
227
228
	int         num_cycles;     /* number of cycles that should be spent in Run-Test/Idle */
	tap_state_t end_state;      /* TAP state in which JTAG commands should finish */
oharboe's avatar
oharboe committed
229
230
} runtest_command_t;

231
232
233

typedef struct stableclocks_command_s
{
234
	int num_cycles;             /* number of clock cycles that should be sent */
235
236
237
} stableclocks_command_t;


oharboe's avatar
oharboe committed
238
239
typedef struct reset_command_s
{
240
	int trst;           /* trst/srst 0: deassert, 1: assert, -1: don't change */
oharboe's avatar
oharboe committed
241
242
243
244
245
	int srst;
} reset_command_t;

typedef struct end_state_command_s
{
246
	tap_state_t end_state;   /* TAP state in which JTAG commands should finish */
oharboe's avatar
oharboe committed
247
248
249
250
} end_state_command_t;

typedef struct sleep_command_s
{
251
	u32 us;     /* number of microseconds to sleep */
oharboe's avatar
oharboe committed
252
253
254
255
} sleep_command_t;

typedef union jtag_command_container_u
{
256
257
258
259
260
261
262
263
	scan_command_t*         scan;
	statemove_command_t*    statemove;
	pathmove_command_t*     pathmove;
	runtest_command_t*      runtest;
	stableclocks_command_t* stableclocks;
	reset_command_t*        reset;
	end_state_command_t*    end_state;
	sleep_command_t* sleep;
oharboe's avatar
oharboe committed
264
265
} jtag_command_container_t;

266
267
268
269
270
271
272
273
enum jtag_command_type {
	JTAG_SCAN         = 1,
	JTAG_STATEMOVE    = 2,
	JTAG_RUNTEST      = 3,
	JTAG_RESET        = 4,
	JTAG_END_STATE    = 5,
	JTAG_PATHMOVE     = 6,
	JTAG_SLEEP        = 7,
274
	JTAG_STABLECLOCKS = 8
oharboe's avatar
oharboe committed
275
276
277
278
279
};

typedef struct jtag_command_s
{
	jtag_command_container_t cmd;
280
281
	enum jtag_command_type   type;
	struct jtag_command_s*   next;
oharboe's avatar
oharboe committed
282
283
} jtag_command_t;

284
extern jtag_command_t* jtag_command_queue;
oharboe's avatar
oharboe committed
285

286
/* forward declaration */
287
288
typedef struct jtag_tap_event_action_s jtag_tap_event_action_t;

289
290
291
/* this is really: typedef jtag_tap_t */
/* But - the typedef is done in "types.h" */
/* due to "forward decloration reasons" */
292
struct jtag_tap_s
oharboe's avatar
oharboe committed
293
{
294
295
296
	const char* chip;
	const char* tapname;
	const char* dotted_name;
297
	int         abs_chain_position;
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
	int         enabled;
	int         ir_length;          /* size of instruction register */
	u32         ir_capture_value;
	u8*         expected;           /* Capture-IR expected value */
	u32         ir_capture_mask;
	u8*         expected_mask;      /* Capture-IR expected mask */
	u32         idcode;             /* device identification code */
	u32*        expected_ids;       /* Array of expected identification codes */
	u8          expected_ids_cnt;   /* Number of expected identification codes */
	u8*         cur_instr;          /* current instruction */
	int         bypass;             /* bypass register selected */

	jtag_tap_event_action_t* event_action;

	jtag_tap_t* next_tap;
313
};
314
315
316
317
318
319
320
321
322
323
extern jtag_tap_t* jtag_AllTaps(void);
extern jtag_tap_t* jtag_TapByPosition(int n);
extern jtag_tap_t* jtag_TapByPosition(int n);
extern jtag_tap_t* jtag_TapByString(const char* dotted_name);
extern jtag_tap_t* jtag_TapByJimObj(Jim_Interp* interp, Jim_Obj* obj);
extern jtag_tap_t* jtag_TapByAbsPosition(int abs_position);
extern int         jtag_NumEnabledTaps(void);
extern int         jtag_NumTotalTaps(void);

static __inline__ jtag_tap_t* jtag_NextEnabledTap(jtag_tap_t* p)
oharboe's avatar
oharboe committed
324
{
325
326
	if (p == NULL)
	{
327
		/* start at the head of list */
oharboe's avatar
oharboe committed
328
		p = jtag_AllTaps();
329
330
331
	}
	else
	{
332
		/* start *after* this one */
oharboe's avatar
oharboe committed
333
334
		p = p->next_tap;
	}
335
336
337
338
	while (p)
	{
		if (p->enabled)
		{
oharboe's avatar
oharboe committed
339
			break;
340
341
342
		}
		else
		{
oharboe's avatar
oharboe committed
343
344
345
			p = p->next_tap;
		}
	}
346

oharboe's avatar
oharboe committed
347
348
349
	return p;
}

350
351

enum reset_line_mode {
oharboe's avatar
oharboe committed
352
	LINE_OPEN_DRAIN = 0x0,
353
	LINE_PUSH_PULL  = 0x1,
oharboe's avatar
oharboe committed
354
355
356
357
358
};

typedef struct jtag_interface_s
{
	char* name;
359

oharboe's avatar
oharboe committed
360
361
362
	/* queued command execution
	 */
	int (*execute_queue)(void);
363

oharboe's avatar
oharboe committed
364
365
366
	/* interface initalization
	 */
	int (*speed)(int speed);
367
	int (*register_commands)(struct command_context_s* cmd_ctx);
oharboe's avatar
oharboe committed
368
369
	int (*init)(void);
	int (*quit)(void);
370

oharboe's avatar
oharboe committed
371
	/* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
372
373
374
375
376
377
378
379
380
	 *  a failure if it can't support the KHz/RTCK.
	 *
	 *  WARNING!!!! if RTCK is *slow* then think carefully about
	 *  whether you actually want to support this in the driver.
	 *  Many target scripts are written to handle the absence of RTCK
	 *  and use a fallback kHz TCK.
	 */
	int (*khz)(int khz, int* jtag_speed);

381
	/* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
382
383
	 *  a failure if it can't support the KHz/RTCK. */
	int (*speed_div)(int speed, int* khz);
384
385

	/* Read and clear the power dropout flag. Note that a power dropout
386
387
388
389
390
391
392
393
394
	 *  can be transitionary, easily much less than a ms.
	 *
	 *  So to find out if the power is *currently* on, you must invoke
	 *  this method twice. Once to clear the power dropout flag and a
	 *  second time to read the current state.
	 *
	 *  Currently the default implementation is never to detect power dropout.
	 */
	int (*power_dropout)(int* power_dropout);
395
396
397
398
399
400
401

	/* Read and clear the srst asserted detection flag.
	 *
	 * NB!!!! like power_dropout this does *not* read the current
	 * state. srst assertion is transitionary and *can* be much
	 * less than 1ms.
	 */
402
	int (*srst_asserted)(int* srst_asserted);
oharboe's avatar
oharboe committed
403
404
} jtag_interface_t;

405
enum jtag_event {
406
	JTAG_TRST_ASSERTED
oharboe's avatar
oharboe committed
407
408
};

409
extern char* jtag_event_strings[];
410

411
enum jtag_tap_event {
412
413
414
415
416
417
	JTAG_TAP_EVENT_ENABLE,
	JTAG_TAP_EVENT_DISABLE
};

extern const Jim_Nvp nvp_jtag_tap_event[];

418
419
420
421
422
struct jtag_tap_event_action_s
{
	enum jtag_tap_event      event;
	Jim_Obj*                 body;
	jtag_tap_event_action_t* next;
423
};
oharboe's avatar
oharboe committed
424
425
426
427
428
429

extern int jtag_trst;
extern int jtag_srst;

typedef struct jtag_event_callback_s
{
430
431
432
	int (*callback)(enum jtag_event event, void* priv);
	void*                         priv;
	struct jtag_event_callback_s* next;
oharboe's avatar
oharboe committed
433
434
} jtag_event_callback_t;

435
extern jtag_event_callback_t* jtag_event_callbacks;
oharboe's avatar
oharboe committed
436

437
extern jtag_interface_t*      jtag; /* global pointer to configured JTAG interface */
oharboe's avatar
oharboe committed
438
439

extern int jtag_speed;
440
extern int jtag_speed_post_reset;
oharboe's avatar
oharboe committed
441

442
443
444
445
446
enum reset_types {
	RESET_NONE            = 0x0,
	RESET_HAS_TRST        = 0x1,
	RESET_HAS_SRST        = 0x2,
	RESET_TRST_AND_SRST   = 0x3,
oharboe's avatar
oharboe committed
447
448
449
	RESET_SRST_PULLS_TRST = 0x4,
	RESET_TRST_PULLS_SRST = 0x8,
	RESET_TRST_OPEN_DRAIN = 0x10,
450
	RESET_SRST_PUSH_PULL  = 0x20,
oharboe's avatar
oharboe committed
451
452
453
454
};

extern enum reset_types jtag_reset_config;

455
/* initialize interface upon startup. A successful no-op
456
457
 * upon subsequent invocations
 */
458
459
extern int  jtag_interface_init(struct command_context_s* cmd_ctx);

460
/* initialize JTAG chain using only a RESET reset. If init fails,
461
462
 * try reset + init.
 */
463
464
extern int  jtag_init(struct command_context_s* cmd_ctx);

465
/* reset, then initialize JTAG chain */
466
467
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
468

469
/* JTAG interface, can be implemented with a software or hardware fifo
470
 *
471
 * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states. TAP_DRSHIFT/IRSHIFT as end states
472
473
474
 * can be emulated by using a larger scan.
 *
 * Code that is relatively insensitive to the path(as long
475
476
477
478
 * as it is JTAG compliant) taken through state machine can use
 * 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.
479
 *
480
 */
481
482
483
484
485
486
487
488
489
extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
extern int  interface_jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
extern void jtag_add_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
extern int  interface_jtag_add_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
extern void jtag_add_plain_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
extern int  interface_jtag_add_plain_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
extern void jtag_add_plain_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
extern int  interface_jtag_add_plain_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);

490
/* run a TAP_RESET reset. End state is TAP_RESET, regardless
491
492
 * of start state.
 */
oharboe's avatar
oharboe committed
493
extern void jtag_add_tlr(void);
494
495
extern int  interface_jtag_add_tlr(void);

496
/* Do not use jtag_add_pathmove() unless you need to, but do use it
497
 * if you have to.
oharboe's avatar
oharboe committed
498
 *
499
 * DANGER! If the target is dependent upon a particular sequence
500
501
502
503
504
 * 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"
505
506
 * path when transitioning to/from end
 * state.
oharboe's avatar
oharboe committed
507
 *
508
 * A list of unambigious single clock state transitions, not
oharboe's avatar
oharboe committed
509
510
 * all drivers can support this, but it is required for e.g.
 * XScale and Xilinx support
511
 *
512
 * Note! TAP_RESET must not be used in the path!
513
514
515
 *
 * Note that the first on the list must be reachable
 * via a single transition from the current state.
516
517
518
519
520
521
522
523
524
 *
 * 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.
oharboe's avatar
oharboe committed
525
 */
526
527
528
extern void jtag_add_pathmove(int num_states, tap_state_t* path);
extern int  interface_jtag_add_pathmove(int num_states, tap_state_t* path);

529
530
531
/* go to TAP_IDLE, if we're not already there and cycle
 * precisely num_cycles in the TAP_IDLE after which move
 * to the end state, if it is != TAP_IDLE
532
 *
oharboe's avatar
oharboe committed
533
 * nb! num_cycles can be 0, in which case the fn will navigate
534
 * to endstate via TAP_IDLE
oharboe's avatar
oharboe committed
535
 */
536
537
538
extern void jtag_add_runtest(int num_cycles, tap_state_t endstate);
extern int  interface_jtag_add_runtest(int num_cycles, tap_state_t endstate);

539
/* A reset of the TAP state machine can be requested.
540
541
 *
 * Whether tms or trst reset is used depends on the capabilities of
542
 * the target and jtag interface(reset_config  command configures this).
543
 *
544
545
 * srst can driver a reset of the TAP state machine and vice
 * versa
546
 *
547
548
 * Application code may need to examine value of jtag_reset_config
 * to determine the proper codepath
549
 *
550
551
 * 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.
552
 *
553
 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
554
 * are supported.
555
 *
556
 * only req_tlr_or_trst and srst can have a transition for a
557
 * call as the effects of transitioning both at the "same time"
558
559
 * are undefined, but when srst_pulls_trst or vice versa,
 * then trst & srst *must* be asserted together.
560
 */
561
extern void jtag_add_reset(int req_tlr_or_trst, int srst);
562

563
564
565
/* this drives the actual srst and trst pins. srst will always be 0
 * if jtag_reset_config & RESET_SRST_PULLS_TRST != 0 and ditto for
 * trst.
566
567
 *
 * the higher level jtag_add_reset will invoke jtag_add_tlr() if
568
 * approperiate
569
 */
570
571
572
extern int  interface_jtag_add_reset(int trst, int srst);
extern void jtag_add_end_state(tap_state_t endstate);
extern int  interface_jtag_add_end_state(tap_state_t endstate);
573
extern void jtag_add_sleep(u32 us);
574
extern int  interface_jtag_add_sleep(u32 us);
575

576
577
578
579
580
581

/**
 * 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.
 */
582
583
void jtag_add_clocks(int num_cycles);
int  interface_jtag_add_clocks(int num_cycles);
584
585


oharboe's avatar
oharboe committed
586
/*
587
 * For software FIFO implementations, the queued commands can be executed
oharboe's avatar
oharboe committed
588
589
 * 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".
590
591
 *
 * This fn will return an error code if any of the prior jtag_add_xxx()
oharboe's avatar
oharboe committed
592
593
 * calls caused a failure, e.g. check failure. Note that it does not
 * matter if the operation was executed *before* jtag_execute_queue(),
594
595
 * jtag_execute_queue() will still return an error code.
 *
oharboe's avatar
oharboe committed
596
 * All jtag_add_xxx() calls that have in_handler!=NULL will have been
597
598
599
600
601
602
603
604
 * 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
605
 */
606
607
extern int            jtag_execute_queue(void);

oharboe's avatar
oharboe committed
608
/* can be implemented by hw+sw */
609
610
611
extern int            interface_jtag_execute_queue(void);
extern int            jtag_power_dropout(int* dropout);
extern int            jtag_srst_asserted(int* srst_asserted);
612

oharboe's avatar
oharboe committed
613
/* JTAG support functions */
614
615
616
617
618
extern void           jtag_set_check_value(scan_field_t* field, u8* value, u8* mask, error_handler_t* in_error_handler);
extern enum scan_type jtag_scan_type(scan_command_t* cmd);
extern int            jtag_scan_size(scan_command_t* cmd);
extern int            jtag_read_buffer(u8* buffer, scan_command_t* cmd);
extern int            jtag_build_buffer(scan_command_t* cmd, u8** buffer);
619

620
621
622
extern void           jtag_sleep(u32 us);
extern int            jtag_call_event_callbacks(enum jtag_event event);
extern int            jtag_register_event_callback(int (* callback)(enum jtag_event event, void* priv), void* priv);
oharboe's avatar
oharboe committed
623
624
625

extern int jtag_verify_capture_ir;

626
void jtag_tap_handle_event(jtag_tap_t* tap, enum jtag_tap_event e);
627

oharboe's avatar
oharboe committed
628
629
630
/* error codes
 * JTAG subsystem uses codes between -100 and -199 */

631
632
633
634
635
636
637
#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)
oharboe's avatar
oharboe committed
638

639

640
641
642
643
/* this allows JTAG devices to implement the entire jtag_xxx() layer in hw/sw */
#ifdef HAVE_JTAG_MINIDRIVER_H
/* Here a #define MINIDRIVER() and an inline version of hw fifo interface_jtag_add_dr_out can be defined */
#include "jtag_minidriver.h"
644
#define MINIDRIVER(a) notused ## a
645
646
#else
#define MINIDRIVER(a) a
647

648
649
/* jtag_add_dr_out() is a faster version of jtag_add_dr_scan()
 *
mifi's avatar
mifi committed
650
 * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
651
 *
652
 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
653
 *
654
655
656
 * If the device is in bypass, then that is an error condition in
 * 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
657
658
 * be passed to it.
 *
659
660
661
 * 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.
662
 *
663
 * Note that this jtag_add_dr_out can be defined as an inline function.
664
 */
665
666
667
extern void interface_jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int* num_bits, const u32* value,
		tap_state_t end_state);

668
669
#endif

670
671
static __inline__ void jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int* num_bits, const u32* value,
		tap_state_t end_state)
672
{
mifi's avatar
mifi committed
673
	if (end_state != TAP_INVALID)
674
675
		cmd_queue_end_state = end_state;
	cmd_queue_cur_state = cmd_queue_end_state;
676
	interface_jtag_add_dr_out(tap, num_fields, num_bits, value, cmd_queue_end_state);
677
678
}

679

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