jtag.h 29.6 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
#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
42
43
44
45
46
47
48
49
50
/*-----<Macros>--------------------------------------------------*/

/** When given an array, compute its DIMension, i.e. number of elements in the array */
#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>-------------------------------------------------*/


51

52
53
54
55
56
57
/*
 * Tap states from ARM7TDMI-S Technical reference manual.
 * Also, validated against several other ARM core technical manuals.
 *
 * N.B. tap_get_tms_path() was changed to reflect this corrected
 * numbering and ordering of the TAP states.
oharboe's avatar
oharboe committed
58
59
60
 *
 * DANGER!!!! some interfaces care about the actual numbers used
 * as they are handed off directly to hardware implementations.
oharboe's avatar
oharboe committed
61
 */
oharboe's avatar
oharboe committed
62

63
64
typedef enum tap_state
{
oharboe's avatar
oharboe committed
65
66
67
68
69
70
71
72
73
74
75
#if BUILD_ECOSBOARD
/* These are the old numbers. Leave as-is for now... */
	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

oharboe's avatar
oharboe committed
99
100
typedef struct tap_transition_s
{
101
102
	tap_state_t high;
	tap_state_t low;
oharboe's avatar
oharboe committed
103
104
} tap_transition_t;

105
106
//extern tap_transition_t tap_transitions[16];    /* describe the TAP state diagram */

107

108
109
#ifdef INCLUDE_JTAG_INTERFACE_H

110
111
112
113
114
115
116
117
118
119
120
/*-----<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
121

122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
/**
 * 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
144

145
#endif
oharboe's avatar
oharboe committed
146

147
148
149
150
151
152
153
154
/**
 * 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
155

156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
/**
 * 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);

183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201

/**
 * Function int tap_get_tms_path_len
 * returns the total number of bits that represents a TMS path
 * transition as given by the function tap_get_tms_path().
 *
 * For at least one interface (JLink) it's not OK to simply "pad" TMS sequences
 * to fit a whole byte.  (I suspect this is a general TAP problem within OOCD.)
 * Padding TMS causes all manner of instability that's not easily
 * discovered.  Using this routine we can apply EXACTLY the state transitions
 * required to make something work - no more - no less.
 *
 * @param from is the starting state
 * @param to is the resultant or final state
 * @return int - the total number of bits in a transition.
 */
int tap_get_tms_path_len(tap_state_t from, tap_state_t to);


202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
/**
 * 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
219
 * returns true if the \a astate is stable.
220
 */
221
bool tap_is_state_stable(tap_state_t astate);
222
223
224
225
226
227
228
229

/**
 * 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.
 */
230
tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
231
232
233
234
235
236
237

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

oharboe's avatar
oharboe committed
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
#ifdef _DEBUG_JTAG_IO_
/**
 * @brief Prints verbose TAP state transitions for the given TMS/TDI buffers.
 * @param tms_buf must points to a buffer containing the TMS bitstream.
 * @param tdi_buf must points to a buffer containing the TDI bitstream.
 * @param tap_len must specify the length of the TMS/TDI bitstreams.
 * @param start_tap_state must specify the current TAP state.
 * @returns the final TAP state; pass as @a start_tap_state in following call.
 */
tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf,
		unsigned tap_len, tap_state_t start_tap_state);
#else
static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
		const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
{
	return start_tap_state;
}
#endif // _DEBUG_JTAG_IO_

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

259
260
#endif // INCLUDE_JTAG_INTERFACE_H

261

262
263
264
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 */

oharboe's avatar
oharboe committed
265
266
typedef struct scan_field_s
{
267
268
269
270
	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*         in_value;           /* pointer to a 32-bit memory location to take data scanned out */
271
272
273
274
275
276
277
278

	u8*         check_value;        /* Used together with jtag_add_dr_scan_check() to check data clocked
	                                   in */
	u8*         check_mask;         /* mask to go with check_value */

	/* internal work space */
	int			allocated;			/* in_value has been allocated for the queue */
	int			modified;			/* did we modify the in_value? */
279
	u8			intmp[4];			/* temporary storage for checking synchronously */
oharboe's avatar
oharboe committed
280
281
} scan_field_t;

282
283
#ifdef INCLUDE_JTAG_INTERFACE_H

284
enum scan_type {
oharboe's avatar
oharboe committed
285
286
287
288
289
290
	/* IN: from device to host, OUT: from host to device */
	SCAN_IN = 1, SCAN_OUT = 2, SCAN_IO = 3
};

typedef struct scan_command_s
{
291
	bool          ir_scan;      /* instruction/not data scan */
292
293
294
	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
295
296
297
298
} scan_command_t;

typedef struct statemove_command_s
{
299
	tap_state_t end_state;   /* TAP state in which JTAG commands should finish */
oharboe's avatar
oharboe committed
300
301
302
303
} statemove_command_t;

typedef struct pathmove_command_s
{
304
305
	int          num_states;    /* number of states in *path */
	tap_state_t* path;          /* states that have to be passed */
oharboe's avatar
oharboe committed
306
307
308
309
} pathmove_command_t;

typedef struct runtest_command_s
{
310
311
	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
312
313
} runtest_command_t;

314
315
316

typedef struct stableclocks_command_s
{
317
	int num_cycles;             /* number of clock cycles that should be sent */
318
319
320
} stableclocks_command_t;


oharboe's avatar
oharboe committed
321
322
typedef struct reset_command_s
{
323
	int trst;           /* trst/srst 0: deassert, 1: assert, -1: don't change */
oharboe's avatar
oharboe committed
324
325
326
327
328
	int srst;
} reset_command_t;

typedef struct end_state_command_s
{
329
	tap_state_t end_state;   /* TAP state in which JTAG commands should finish */
oharboe's avatar
oharboe committed
330
331
332
333
} end_state_command_t;

typedef struct sleep_command_s
{
334
	u32 us;     /* number of microseconds to sleep */
oharboe's avatar
oharboe committed
335
336
337
338
} sleep_command_t;

typedef union jtag_command_container_u
{
339
340
341
342
343
344
345
346
	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
347
348
} jtag_command_container_t;

349
350
351
352
353
354
355
enum jtag_command_type {
	JTAG_SCAN         = 1,
	JTAG_STATEMOVE    = 2,
	JTAG_RUNTEST      = 3,
	JTAG_RESET        = 4,
	JTAG_PATHMOVE     = 6,
	JTAG_SLEEP        = 7,
356
	JTAG_STABLECLOCKS = 8
oharboe's avatar
oharboe committed
357
358
359
360
361
};

typedef struct jtag_command_s
{
	jtag_command_container_t cmd;
362
363
	enum jtag_command_type   type;
	struct jtag_command_s*   next;
oharboe's avatar
oharboe committed
364
365
} jtag_command_t;

366
extern jtag_command_t* jtag_command_queue;
oharboe's avatar
oharboe committed
367

368
369
370
371
372
373
extern void* cmd_queue_alloc(size_t size);
extern void cmd_queue_free(void);

extern void jtag_queue_command(jtag_command_t *cmd);
extern void jtag_command_queue_reset(void);

374
375
#endif // INCLUDE_JTAG_INTERFACE_H

376
/* forward declaration */
377
378
typedef struct jtag_tap_event_action_s jtag_tap_event_action_t;

379
380
381
/* this is really: typedef jtag_tap_t */
/* But - the typedef is done in "types.h" */
/* due to "forward decloration reasons" */
382
struct jtag_tap_s
oharboe's avatar
oharboe committed
383
{
384
385
386
	const char* chip;
	const char* tapname;
	const char* dotted_name;
387
	int         abs_chain_position;
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
	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;
403
};
404
405
406
407
408
409
410
411
412
extern jtag_tap_t* jtag_AllTaps(void);
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
413
{
414
415
	if (p == NULL)
	{
416
		/* start at the head of list */
oharboe's avatar
oharboe committed
417
		p = jtag_AllTaps();
418
419
420
	}
	else
	{
421
		/* start *after* this one */
oharboe's avatar
oharboe committed
422
423
		p = p->next_tap;
	}
424
425
426
427
	while (p)
	{
		if (p->enabled)
		{
oharboe's avatar
oharboe committed
428
			break;
429
430
431
		}
		else
		{
oharboe's avatar
oharboe committed
432
433
434
			p = p->next_tap;
		}
	}
435

oharboe's avatar
oharboe committed
436
437
438
	return p;
}

439
440

enum reset_line_mode {
oharboe's avatar
oharboe committed
441
	LINE_OPEN_DRAIN = 0x0,
442
	LINE_PUSH_PULL  = 0x1,
oharboe's avatar
oharboe committed
443
444
};

445
446
#ifdef INCLUDE_JTAG_INTERFACE_H

oharboe's avatar
oharboe committed
447
448
449
typedef struct jtag_interface_s
{
	char* name;
450

oharboe's avatar
oharboe committed
451
452
453
	/* queued command execution
	 */
	int (*execute_queue)(void);
454

oharboe's avatar
oharboe committed
455
456
457
	/* interface initalization
	 */
	int (*speed)(int speed);
458
	int (*register_commands)(struct command_context_s* cmd_ctx);
oharboe's avatar
oharboe committed
459
460
	int (*init)(void);
	int (*quit)(void);
461

oharboe's avatar
oharboe committed
462
	/* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
463
464
465
466
467
468
469
470
471
	 *  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);

472
	/* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
473
474
	 *  a failure if it can't support the KHz/RTCK. */
	int (*speed_div)(int speed, int* khz);
475
476

	/* Read and clear the power dropout flag. Note that a power dropout
477
478
479
480
481
482
483
484
485
	 *  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);
486
487
488
489
490
491
492

	/* 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.
	 */
493
	int (*srst_asserted)(int* srst_asserted);
oharboe's avatar
oharboe committed
494
495
} jtag_interface_t;

496
497
#endif // INCLUDE_JTAG_INTERFACE_H

498
enum jtag_event {
499
	JTAG_TRST_ASSERTED
oharboe's avatar
oharboe committed
500
501
};

502
extern char* jtag_event_strings[];
503

504
enum jtag_tap_event {
505
506
507
508
509
510
	JTAG_TAP_EVENT_ENABLE,
	JTAG_TAP_EVENT_DISABLE
};

extern const Jim_Nvp nvp_jtag_tap_event[];

511
512
513
514
515
struct jtag_tap_event_action_s
{
	enum jtag_tap_event      event;
	Jim_Obj*                 body;
	jtag_tap_event_action_t* next;
516
};
oharboe's avatar
oharboe committed
517
518
519
520
521
522

extern int jtag_trst;
extern int jtag_srst;

typedef struct jtag_event_callback_s
{
523
524
525
	int (*callback)(enum jtag_event event, void* priv);
	void*                         priv;
	struct jtag_event_callback_s* next;
oharboe's avatar
oharboe committed
526
527
} jtag_event_callback_t;

528
extern jtag_event_callback_t* jtag_event_callbacks;
oharboe's avatar
oharboe committed
529
530

extern int jtag_speed;
531
extern int jtag_speed_post_reset;
oharboe's avatar
oharboe committed
532

533
534
535
536
537
enum reset_types {
	RESET_NONE            = 0x0,
	RESET_HAS_TRST        = 0x1,
	RESET_HAS_SRST        = 0x2,
	RESET_TRST_AND_SRST   = 0x3,
oharboe's avatar
oharboe committed
538
539
540
	RESET_SRST_PULLS_TRST = 0x4,
	RESET_TRST_PULLS_SRST = 0x8,
	RESET_TRST_OPEN_DRAIN = 0x10,
541
	RESET_SRST_PUSH_PULL  = 0x20,
oharboe's avatar
oharboe committed
542
543
544
545
};

extern enum reset_types jtag_reset_config;

546
/* initialize interface upon startup. A successful no-op
547
548
 * upon subsequent invocations
 */
549
550
extern int  jtag_interface_init(struct command_context_s* cmd_ctx);

551
552
553
/// Shutdown the JTAG interface upon program exit.
extern int  jtag_interface_quit(void);

554
/* initialize JTAG chain using only a RESET reset. If init fails,
555
556
 * try reset + init.
 */
557
558
extern int  jtag_init(struct command_context_s* cmd_ctx);

559
/* reset, then initialize JTAG chain */
560
561
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
562

563
/* JTAG interface, can be implemented with a software or hardware fifo
564
 *
565
 * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states. TAP_DRSHIFT/IRSHIFT as end states
566
567
568
 * can be emulated by using a larger scan.
 *
 * Code that is relatively insensitive to the path(as long
569
570
571
572
 * 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.
573
 *
574
 */
575
extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
576
/* same as jtag_add_ir_scan except no verify is performed */
577
578
extern void jtag_add_ir_scan_noverify(int num_fields, const scan_field_t *fields, tap_state_t state);
extern void jtag_add_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
579

580
581
582
583
584
585
586
587
588
589
/* 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
 * JTAG queues.
 *
 * In the event of an asynchronous queue execution the queue buffer
 * allocation method is used, for the synchronous case the temporary 32 bits come
 * from the input field itself.
 */
extern void jtag_alloc_in_value32(scan_field_t *field);

590
591
/* This version of jtag_add_dr_scan() uses the check_value/mask fields */
extern void jtag_add_dr_scan_check(int num_fields, scan_field_t* fields, tap_state_t endstate);
592
593
extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
extern void jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
594

595
596
597
598
599
600
601
602

/* Simplest/typical callback - do some conversion on the data clocked in.
 * This callback is for such conversion that can not fail.
 * For conversion types or checks that can
 * fail, use the jtag_callback_t variant */
typedef void (*jtag_callback1_t)(u8 *in);

#ifndef HAVE_JTAG_MINIDRIVER_H
603
/* A simpler version of jtag_add_callback4 */
604
605
606
607
608
extern void jtag_add_callback(jtag_callback1_t, u8 *in);
#else
/* implemented by minidriver */
#endif

oharboe's avatar
oharboe committed
609

610
611
/* This type can store an integer safely by a normal cast on 64 and
 * 32 bit systems. */
oharboe's avatar
oharboe committed
612
typedef intptr_t jtag_callback_data_t;
613
614
615
616
617
618

/* The generic callback mechanism.
 *
 * The callback is invoked with three arguments. The first argument is
 * the pointer to the data clocked in.
 */
619
typedef int (*jtag_callback_t)(u8 *in, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3);
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653


/* This callback can be executed immediately the queue has been flushed. Note that
 * the JTAG queue can either be executed synchronously or asynchronously. Typically
 * for USB the queue is executed asynchronously. For low latency interfaces, the
 * queue may be executed synchronously.
 *
 * These callbacks are typically executed *after* the *entire* JTAG queue has been
 * executed for e.g. USB interfaces.
 *
 * The callbacks are guaranteeed to be invoked in the order that they were queued.
 *
 * The strange name is due to C's lack of overloading using function arguments
 *
 * The callback mechansim is very general and does not really make any assumptions
 * about what the callback does and what the arguments are.
 *
 * in - typically used to point to the data to operate on. More often than not
 * this will be the data clocked in during a shift operation
 *
 * data1 - an integer that is big enough to be used either as an 'int' or
 * cast to/from a pointer
 *
 * data2 - an integer that is big enough to be used either as an 'int' or
 * cast to/from a pointer
 *
 * Why stop at 'data2' for arguments? Somewhat historical reasons. This is
 * sufficient to implement the jtag_check_value_mask(), besides the
 * line is best drawn somewhere...
 *
 * If the execution of the queue fails before the callbacks, then the
 * callbacks may or may not be invoked depending on driver implementation.
 */
#ifndef HAVE_JTAG_MINIDRIVER_H
654
extern void jtag_add_callback4(jtag_callback_t, u8 *in, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3);
655
656
657
658
659
#else
/* implemented by minidriver */
#endif


660
/* run a TAP_RESET reset. End state is TAP_RESET, regardless
661
662
 * of start state.
 */
oharboe's avatar
oharboe committed
663
extern void jtag_add_tlr(void);
664

oharboe's avatar
oharboe committed
665
666
667
668
669
670
671
/* Application code *must* assume that interfaces will
 * 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.
672
 *
oharboe's avatar
oharboe committed
673
674
 * Use jtag_add_pathmove() when specific transition sequences
 * are required.
675
 *
oharboe's avatar
oharboe committed
676
 * Do not use jtag_add_pathmove() unless you need to, but do use it
677
 * if you have to.
oharboe's avatar
oharboe committed
678
 *
679
 * DANGER! If the target is dependent upon a particular sequence
680
681
682
683
684
 * 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"
685
686
 * path when transitioning to/from end
 * state.
oharboe's avatar
oharboe committed
687
 *
688
 * A list of unambigious single clock state transitions, not
oharboe's avatar
oharboe committed
689
690
 * all drivers can support this, but it is required for e.g.
 * XScale and Xilinx support
691
 *
692
 * Note! TAP_RESET must not be used in the path!
693
694
695
 *
 * Note that the first on the list must be reachable
 * via a single transition from the current state.
696
697
698
699
700
701
702
703
704
 *
 * 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
705
 */
706
extern void jtag_add_pathmove(int num_states, const tap_state_t* path);
707

708
709
710
/* 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
711
 *
oharboe's avatar
oharboe committed
712
 * nb! num_cycles can be 0, in which case the fn will navigate
713
 * to endstate via TAP_IDLE
oharboe's avatar
oharboe committed
714
 */
715
716
extern void jtag_add_runtest(int num_cycles, tap_state_t endstate);

717
/* A reset of the TAP state machine can be requested.
718
719
 *
 * Whether tms or trst reset is used depends on the capabilities of
720
 * the target and jtag interface(reset_config  command configures this).
721
 *
722
723
 * srst can driver a reset of the TAP state machine and vice
 * versa
724
 *
725
726
 * Application code may need to examine value of jtag_reset_config
 * to determine the proper codepath
727
 *
728
729
 * 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.
730
 *
731
 * This is why combinations such as "reset_config srst_only srst_pulls_trst"
732
 * are supported.
733
 *
734
 * only req_tlr_or_trst and srst can have a transition for a
735
 * call as the effects of transitioning both at the "same time"
736
737
 * are undefined, but when srst_pulls_trst or vice versa,
 * then trst & srst *must* be asserted together.
738
 */
739
extern void jtag_add_reset(int req_tlr_or_trst, int srst);
740
741

extern void jtag_add_end_state(tap_state_t endstate);
742
extern void jtag_add_sleep(u32 us);
743

744
745
746
747
748
749

/**
 * 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.
 */
750
void jtag_add_clocks(int num_cycles);
751
752


oharboe's avatar
oharboe committed
753
/*
754
 * For software FIFO implementations, the queued commands can be executed
oharboe's avatar
oharboe committed
755
756
 * 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".
757
758
 *
 * This fn will return an error code if any of the prior jtag_add_xxx()
oharboe's avatar
oharboe committed
759
760
 * calls caused a failure, e.g. check failure. Note that it does not
 * matter if the operation was executed *before* jtag_execute_queue(),
761
762
 * jtag_execute_queue() will still return an error code.
 *
oharboe's avatar
oharboe committed
763
 * All jtag_add_xxx() calls that have in_handler!=NULL will have been
764
765
766
767
768
769
770
771
 * 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
772
 */
773
774
extern int            jtag_execute_queue(void);

oharboe's avatar
oharboe committed
775
776
777
/* same as jtag_execute_queue() but does not clear the error flag */
extern void jtag_execute_queue_noclear(void);

778
779
780
781
782
783
784
785
/* this flag is set when an error occurs while executing the queue. cleared
 * by jtag_execute_queue()
 *
 * this flag can also be set from application code if some error happens
 * during processing that should be reported during jtag_execute_queue().
 */
extern int jtag_error;

oharboe's avatar
oharboe committed
786
787
788
789
790
791
792
793
794
795
static __inline__ void jtag_set_error(int error)
{
	if ((error==ERROR_OK)||(jtag_error!=ERROR_OK))
	{
		/* keep first error */
		return;
	}
	jtag_error=error;
}

796
797


oharboe's avatar
oharboe committed
798
/* can be implemented by hw+sw */
799
800
extern int            jtag_power_dropout(int* dropout);
extern int            jtag_srst_asserted(int* srst_asserted);
801

oharboe's avatar
oharboe committed
802
/* JTAG support functions */
oharboe's avatar
oharboe committed
803

804
805
806
/* execute jtag queue and check value and use mask if mask is != NULL. invokes
 * jtag_set_error() with any error. */
extern void jtag_check_value_mask(scan_field_t *field, u8 *value, u8 *mask);
807
808

#ifdef INCLUDE_JTAG_INTERFACE_H
809
810
811
812
extern enum scan_type jtag_scan_type(const scan_command_t* cmd);
extern int            jtag_scan_size(const scan_command_t* cmd);
extern int            jtag_read_buffer(u8* buffer, const scan_command_t* cmd);
extern int            jtag_build_buffer(const scan_command_t* cmd, u8** buffer);
813
#endif  // INCLUDE_JTAG_INTERFACE_H
814

815
816
817
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
818
819
820

extern int jtag_verify_capture_ir;

821
void jtag_tap_handle_event(jtag_tap_t* tap, enum jtag_tap_event e);
822

oharboe's avatar
oharboe committed
823
824
825
/* error codes
 * JTAG subsystem uses codes between -100 and -199 */

826
827
828
829
830
831
832
#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
833

834
835
836
837
/* jtag_add_dr_out() is a version of jtag_add_dr_scan() which
 * 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.
838
 *
mifi's avatar
mifi committed
839
 * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
840
 *
841
 * num_bits[i] is the number of bits to clock out from value[i] LSB first.
842
 *
843
844
845
 * 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
846
847
 * be passed to it.
 *
848
849
850
 * 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.
851
 *
852
853
854
855
856
857
 * 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!
858
 */
zwelch's avatar
zwelch committed
859
860
861
extern void jtag_add_dr_out(jtag_tap_t* tap,
		int num_fields, const int* num_bits, const u32* value,
		tap_state_t end_state);
862
863
864
865
866
867
868
869
870
871


/**
 * Function jtag_add_statemove
 * moves from the current state to the goal \a state. This needs
 * to be handled according to the xsvf spec, see the XSTATE command
 * description.
 */
extern int jtag_add_statemove(tap_state_t goal_state);

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