]> git.sur5r.net Git - openocd/blob - src/jtag/jtag.h
552e217c7877db4425090807dde37d9c6fe071ba
[openocd] / src / jtag / jtag.h
1 /***************************************************************************
2 *   Copyright (C) 2005 by Dominic Rath                                    *
3 *   Dominic.Rath@gmx.de                                                   *
4 *                                                                         *
5 *   Copyright (C) 2007,2008 Ã˜yvind Harboe                                 *
6 *   oyvind.harboe@zylin.com                                               *
7 *                                                                         *
8 *   This program is free software; you can redistribute it and/or modify  *
9 *   it under the terms of the GNU General Public License as published by  *
10 *   the Free Software Foundation; either version 2 of the License, or     *
11 *   (at your option) any later version.                                   *
12 *                                                                         *
13 *   This program is distributed in the hope that it will be useful,       *
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
16 *   GNU General Public License for more details.                          *
17 *                                                                         *
18 *   You should have received a copy of the GNU General Public License     *
19 *   along with this program; if not, write to the                         *
20 *   Free Software Foundation, Inc.,                                       *
21 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
22 ***************************************************************************/
23 #ifndef JTAG_H
24 #define JTAG_H
25
26 #include "binarybuffer.h"
27 #include "log.h"
28
29
30 #ifdef _DEBUG_JTAG_IO_
31 #define DEBUG_JTAG_IO(expr ...)         LOG_DEBUG(expr)
32 #else
33 #define DEBUG_JTAG_IO(expr ...)
34 #endif
35
36 #ifndef DEBUG_JTAG_IOZ
37 #define DEBUG_JTAG_IOZ 64
38 #endif
39
40 /*-----<Macros>--------------------------------------------------*/
41
42 /**
43  * When given an array, compute its DIMension; in other words, the
44  * number of elements in the array
45  */
46 #define DIM(x)                                  (sizeof(x)/sizeof((x)[0]))
47
48 /** Calculate the number of bytes required to hold @a n TAP scan bits */
49 #define TAP_SCAN_BYTES(n)               CEIL(n, 8)
50
51 /*-----</Macros>-------------------------------------------------*/
52
53 /**
54  * Defines JTAG Test Access Port states.
55  *
56  * These definitions were gleaned from the ARM7TDMI-S Technical
57  * Reference Manual and validated against several other ARM core
58  * technical manuals.  tap_get_tms_path() is sensitive to this numbering
59  * and ordering of the TAP states; furthermore, some interfaces require
60  * specific numbers be used, as they are handed-off directly to their
61  * hardware implementations.
62  */
63 typedef enum tap_state
64 {
65 #if BUILD_ECOSBOARD
66         /* These are the old numbers. Leave as-is for now... */
67         TAP_RESET    = 0, TAP_IDLE = 8,
68         TAP_DRSELECT = 1, TAP_DRCAPTURE = 2, TAP_DRSHIFT = 3, TAP_DREXIT1 = 4,
69         TAP_DRPAUSE  = 5, TAP_DREXIT2 = 6, TAP_DRUPDATE = 7,
70         TAP_IRSELECT = 9, TAP_IRCAPTURE = 10, TAP_IRSHIFT = 11, TAP_IREXIT1 = 12,
71         TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,
72
73         TAP_NUM_STATES = 16, TAP_INVALID = -1,
74 #else
75         /* Proper ARM recommended numbers */
76         TAP_DREXIT2 = 0x0,
77         TAP_DREXIT1 = 0x1,
78         TAP_DRSHIFT = 0x2,
79         TAP_DRPAUSE = 0x3,
80         TAP_IRSELECT = 0x4,
81         TAP_DRUPDATE = 0x5,
82         TAP_DRCAPTURE = 0x6,
83         TAP_DRSELECT = 0x7,
84         TAP_IREXIT2 = 0x8,
85         TAP_IREXIT1 = 0x9,
86         TAP_IRSHIFT = 0xa,
87         TAP_IRPAUSE = 0xb,
88         TAP_IDLE = 0xc,
89         TAP_IRUPDATE = 0xd,
90         TAP_IRCAPTURE = 0xe,
91         TAP_RESET = 0x0f,
92
93         TAP_NUM_STATES = 0x10,
94
95         TAP_INVALID = -1,
96 #endif
97 } tap_state_t;
98
99 /**
100  * Function tap_state_name
101  * Returns a string suitable for display representing the JTAG tap_state
102  */
103 const char* tap_state_name(tap_state_t state);
104
105 /// The current TAP state of the pending JTAG command queue.
106 extern tap_state_t cmd_queue_cur_state;
107
108 /**
109  * This structure defines a single scan field in the scan. It provides
110  * fields for the field's width and pointers to scan input and output
111  * values.
112  *
113  * In addition, this structure includes a value and mask that is used by
114  * jtag_add_dr_scan_check() to validate the value that was scanned out.
115  *
116  * The allocated, modified, and intmp fields are internal work space.
117  */
118 typedef struct scan_field_s
119 {
120         /// A pointer to the tap structure to which this field refers.
121         jtag_tap_t* tap;
122
123         /// The number of bits this field specifies (up to 32)
124         int num_bits;
125         /// A pointer to value to be scanned into the device
126         u8* out_value;
127         /// A pointer to a 32-bit memory location for data scanned out
128         u8* in_value;
129
130         /// The value used to check the data scanned out.
131         u8* check_value;
132         /// The mask to go with check_value
133         u8* check_mask;
134
135         /// in_value has been allocated for the queue
136         int allocated;
137         /// Indicates we modified the in_value.
138         int modified;
139         /// temporary storage for performing value checks synchronously
140         u8 intmp[4];
141 } scan_field_t;
142
143 typedef struct jtag_tap_event_action_s jtag_tap_event_action_t;
144
145 /* this is really: typedef jtag_tap_t */
146 /* But - the typedef is done in "types.h" */
147 /* due to "forward decloration reasons" */
148 struct jtag_tap_s
149 {
150         const char* chip;
151         const char* tapname;
152         const char* dotted_name;
153         int abs_chain_position;
154         /// Is this TAP enabled?
155         int enabled;
156         int ir_length; /**< size of instruction register */
157         u32 ir_capture_value;
158         u8* expected; /**< Capture-IR expected value */
159         u32 ir_capture_mask;
160         u8* expected_mask; /**< Capture-IR expected mask */
161         u32 idcode;
162         /**< device identification code */
163
164         /// Array of expected identification codes */
165         u32* expected_ids;
166         /// Number of expected identification codes
167         u8 expected_ids_cnt;
168
169         /// current instruction
170         u8* cur_instr;
171         /// Bypass register selected
172         int bypass;
173
174         jtag_tap_event_action_t *event_action;
175
176         jtag_tap_t* next_tap;
177 };
178 extern jtag_tap_t* jtag_AllTaps(void);
179 extern jtag_tap_t* jtag_TapByPosition(int n);
180 extern jtag_tap_t* jtag_TapByString(const char* dotted_name);
181 extern jtag_tap_t* jtag_TapByJimObj(Jim_Interp* interp, Jim_Obj* obj);
182 extern jtag_tap_t* jtag_TapByAbsPosition(int abs_position);
183 extern int jtag_NumEnabledTaps(void);
184 extern int jtag_NumTotalTaps(void);
185
186 static __inline__ jtag_tap_t* jtag_NextEnabledTap(jtag_tap_t* p)
187 {
188         if (p == NULL)
189         {
190                 /* start at the head of list */
191                 p = jtag_AllTaps();
192         }
193         else
194         {
195                 /* start *after* this one */
196                 p = p->next_tap;
197         }
198         while (p)
199         {
200                 if (p->enabled)
201                 {
202                         break;
203                 }
204                 else
205                 {
206                         p = p->next_tap;
207                 }
208         }
209
210         return p;
211 }
212
213
214 enum reset_line_mode {
215         LINE_OPEN_DRAIN = 0x0,
216         LINE_PUSH_PULL  = 0x1,
217 };
218
219 /* 
220  * There are three cases when JTAG_TRST_ASSERTED callback is invoked. The
221  * event is invoked *after* TRST is asserted(or queued rather). It is illegal 
222  * to communicate with the JTAG interface during the callback(as there is 
223  * currently a queue being built).
224  * 
225  * - TMS reset
226  * - SRST pulls TRST
227  * - TRST asserted
228  * 
229  **/
230 enum jtag_event {
231         JTAG_TRST_ASSERTED
232 };
233
234 extern char* jtag_event_strings[];
235
236 enum jtag_tap_event {
237         JTAG_TAP_EVENT_ENABLE,
238         JTAG_TAP_EVENT_DISABLE
239 };
240
241 extern const Jim_Nvp nvp_jtag_tap_event[];
242
243 struct jtag_tap_event_action_s
244 {
245         enum jtag_tap_event      event;
246         Jim_Obj*                 body;
247         jtag_tap_event_action_t* next;
248 };
249
250 extern int jtag_trst;
251 extern int jtag_srst;
252
253 typedef struct jtag_event_callback_s
254 {
255         int (*callback)(enum jtag_event event, void* priv);
256         void*                         priv;
257         struct jtag_event_callback_s* next;
258 } jtag_event_callback_t;
259
260 extern jtag_event_callback_t* jtag_event_callbacks;
261
262 extern int jtag_speed;
263 extern int jtag_speed_post_reset;
264
265 enum reset_types {
266         RESET_NONE            = 0x0,
267         RESET_HAS_TRST        = 0x1,
268         RESET_HAS_SRST        = 0x2,
269         RESET_TRST_AND_SRST   = 0x3,
270         RESET_SRST_PULLS_TRST = 0x4,
271         RESET_TRST_PULLS_SRST = 0x8,
272         RESET_TRST_OPEN_DRAIN = 0x10,
273         RESET_SRST_PUSH_PULL  = 0x20,
274 };
275
276 extern enum reset_types jtag_reset_config;
277
278 /**
279  * Initialize interface upon startup.  Return a successful no-op upon
280  * subsequent invocations.
281  */
282 extern int  jtag_interface_init(struct command_context_s* cmd_ctx);
283
284 /// Shutdown the JTAG interface upon program exit.
285 extern int  jtag_interface_quit(void);
286
287 /**
288  * Initialize JTAG chain using only a RESET reset. If init fails,
289  * try reset + init.
290  */
291 extern int  jtag_init(struct command_context_s* cmd_ctx);
292
293 /// reset, then initialize JTAG chain
294 extern int  jtag_init_reset(struct command_context_s* cmd_ctx);
295 extern int  jtag_register_commands(struct command_context_s* cmd_ctx);
296
297 /**
298  * @file
299  * The JTAG interface can be implemented with a software or hardware fifo.
300  *
301  * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states; however,
302  * TAP_DRSHIFT/IRSHIFT can be emulated as end states, by using longer
303  * scans.
304  *
305  * Code that is relatively insensitive to the path taken through state
306  * machine (as long as it is JTAG compliant) can use @a endstate for
307  * jtag_add_xxx_scan(). Otherwise, the pause state must be specified as
308  * end state and a subsequent jtag_add_pathmove() must be issued.
309  */
310
311 extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
312 /**
313  * The same as jtag_add_ir_scan except no verification is performed out
314  * the output values.
315  */
316 extern void jtag_add_ir_scan_noverify(int num_fields, const scan_field_t *fields, tap_state_t state);
317
318
319 /**
320  * Set in_value to point to 32 bits of memory to scan into. This
321  * function is a way to handle the case of synchronous and asynchronous
322  * JTAG queues.
323  *
324  * In the event of an asynchronous queue execution the queue buffer
325  * allocation method is used, for the synchronous case the temporary 32
326  * bits come from the input field itself.
327  */
328 extern void jtag_alloc_in_value32(scan_field_t *field);
329
330 extern void jtag_add_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
331 /// A version of jtag_add_dr_scan() that uses the check_value/mask fields
332 extern void jtag_add_dr_scan_check(int num_fields, scan_field_t* fields, tap_state_t endstate);
333 extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
334 extern void jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
335
336
337 /**
338  * Defines a simple JTAG callback that can allow conversions on data
339  * scanned in from an interface.
340  *
341  * This callback should only be used for conversion that cannot fail.
342  * For conversion types or checks that can fail, use the more complete
343  * variant: jtag_callback_t.
344  */
345 typedef void (*jtag_callback1_t)(u8 *in);
346
347 /// A simpler version of jtag_add_callback4().
348 extern void jtag_add_callback(jtag_callback1_t, u8 *in);
349
350
351 /**
352  * Defines the type of data passed to the jtag_callback_t interface.
353  * The underlying type must allow storing an @c int or pointer type.
354  */
355 typedef intptr_t jtag_callback_data_t;
356
357 /**
358  * Defines the interface of the JTAG callback mechanism.
359  *
360  * @param in the pointer to the data clocked in
361  * @param data1 An integer big enough to use as an @c int or a pointer.
362  * @param data2 An integer big enough to use as an @c int or a pointer.
363  * @param data3 An integer big enough to use as an @c int or a pointer.
364  * @returns an error code
365  */
366 typedef int (*jtag_callback_t)(u8 *in, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3);
367
368
369 /**
370  * This callback can be executed immediately the queue has been flushed.
371  *
372  * The JTAG queue can be executed synchronously or asynchronously.
373  * Typically for USB, the queue is executed asynchronously.  For
374  * low-latency interfaces, the queue may be executed synchronously.
375  *
376  * The callback mechanism is very general and does not make many
377  * assumptions about what the callback does or what its arguments are.
378  * These callbacks are typically executed *after* the *entire* JTAG
379  * queue has been executed for e.g. USB interfaces, and they are
380  * guaranteeed to be invoked in the order that they were queued.
381  *
382  * If the execution of the queue fails before the callbacks, then --
383  * depending on driver implementation -- the callbacks may or may not be
384  * invoked.  @todo Can we make this behavior consistent?
385  *
386  * The strange name is due to C's lack of overloading using function
387  * arguments.
388  *
389  * @param f The callback function to add.
390  * @param in Typically used to point to the data to operate on.
391  * Frequently this will be the data clocked in during a shift operation.
392  * @param data1 An integer big enough to use as an @c int or a pointer.
393  * @param data2 An integer big enough to use as an @c int or a pointer.
394  * @param data3 An integer big enough to use as an @c int or a pointer.
395  *
396  */
397 extern void jtag_add_callback4(jtag_callback_t f, u8 *in,
398                 jtag_callback_data_t data1, jtag_callback_data_t data2,
399                 jtag_callback_data_t data3);
400
401
402 /**
403  * Run a TAP_RESET reset where the end state is TAP_RESET,
404  * regardless of the start state.
405  */
406 extern void jtag_add_tlr(void);
407
408 /**
409  * Application code *must* assume that interfaces will
410  * implement transitions between states with different
411  * paths and path lengths through the state diagram. The
412  * path will vary across interface and also across versions
413  * of the same interface over time. Even if the OpenOCD code
414  * is unchanged, the actual path taken may vary over time
415  * and versions of interface firmware or PCB revisions.
416  *
417  * Use jtag_add_pathmove() when specific transition sequences
418  * are required.
419  *
420  * Do not use jtag_add_pathmove() unless you need to, but do use it
421  * if you have to.
422  *
423  * DANGER! If the target is dependent upon a particular sequence
424  * of transitions for things to work correctly(e.g. as a workaround
425  * for an errata that contradicts the JTAG standard), then pathmove
426  * must be used, even if some jtag interfaces happen to use the
427  * desired path. Worse, the jtag interface used for testing a
428  * particular implementation, could happen to use the "desired"
429  * path when transitioning to/from end
430  * state.
431  *
432  * A list of unambigious single clock state transitions, not
433  * all drivers can support this, but it is required for e.g.
434  * XScale and Xilinx support
435  *
436  * Note! TAP_RESET must not be used in the path!
437  *
438  * Note that the first on the list must be reachable
439  * via a single transition from the current state.
440  *
441  * All drivers are required to implement jtag_add_pathmove().
442  * However, if the pathmove sequence can not be precisely
443  * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
444  * must return an error. It is legal, but not recommended, that
445  * a driver returns an error in all cases for a pathmove if it
446  * can only implement a few transitions and therefore
447  * a partial implementation of pathmove would have little practical
448  * application.
449  */
450 extern void jtag_add_pathmove(int num_states, const tap_state_t* path);
451
452 /**
453  * Goes to TAP_IDLE (if we're not already there), cycle
454  * precisely num_cycles in the TAP_IDLE state, after which move
455  * to @a endstate (unless it is also TAP_IDLE).
456  *
457  * @param num_cycles Number of cycles in TAP_IDLE state.  This argument
458  *      may be 0, in which case this routine will navigate to @a endstate
459  *      via TAP_IDLE.
460  * @param endstate The final state.
461  */
462 extern void jtag_add_runtest(int num_cycles, tap_state_t endstate);
463
464 /**
465  * A reset of the TAP state machine can be requested.
466  *
467  * Whether tms or trst reset is used depends on the capabilities of
468  * the target and jtag interface(reset_config  command configures this).
469  *
470  * srst can driver a reset of the TAP state machine and vice
471  * versa
472  *
473  * Application code may need to examine value of jtag_reset_config
474  * to determine the proper codepath
475  *
476  * DANGER! Even though srst drives trst, trst might not be connected to
477  * the interface, and it might actually be *harmful* to assert trst in this case.
478  *
479  * This is why combinations such as "reset_config srst_only srst_pulls_trst"
480  * are supported.
481  *
482  * only req_tlr_or_trst and srst can have a transition for a
483  * call as the effects of transitioning both at the "same time"
484  * are undefined, but when srst_pulls_trst or vice versa,
485  * then trst & srst *must* be asserted together.
486  */
487 extern void jtag_add_reset(int req_tlr_or_trst, int srst);
488
489
490 /**
491  * Function jtag_add_end_state
492  *
493  * Set a global variable to \a state if \a state != TAP_INVALID.
494  *
495  * Return the value of the global variable.
496  *
497  **/
498 extern tap_state_t jtag_add_end_state(tap_state_t state);
499 /**
500  * Function jtag_get_end_state
501  *
502  * Return the value of the global variable for end state
503  *
504  **/
505 extern tap_state_t jtag_get_end_state(void);
506 extern void jtag_add_sleep(u32 us);
507
508
509 /**
510  * Function jtag_add_stable_clocks
511  * first checks that the state in which the clocks are to be issued is
512  * stable, then queues up clock_count clocks for transmission.
513  */
514 void jtag_add_clocks(int num_cycles);
515
516
517 /**
518  * For software FIFO implementations, the queued commands can be executed
519  * during this call or earlier. A sw queue might decide to push out
520  * some of the jtag_add_xxx() operations once the queue is "big enough".
521  *
522  * This fn will return an error code if any of the prior jtag_add_xxx()
523  * calls caused a failure, e.g. check failure. Note that it does not
524  * matter if the operation was executed *before* jtag_execute_queue(),
525  * jtag_execute_queue() will still return an error code.
526  *
527  * All jtag_add_xxx() calls that have in_handler!=NULL will have been
528  * executed when this fn returns, but if what has been queued only
529  * clocks data out, without reading anything back, then JTAG could
530  * be running *after* jtag_execute_queue() returns. The API does
531  * not define a way to flush a hw FIFO that runs *after*
532  * jtag_execute_queue() returns.
533  *
534  * jtag_add_xxx() commands can either be executed immediately or
535  * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
536  */
537 extern int jtag_execute_queue(void);
538
539 /* same as jtag_execute_queue() but does not clear the error flag */
540 extern void jtag_execute_queue_noclear(void);
541
542 /**
543  * The jtag_error variable is set when an error occurs while executing
544  * the queue.
545  *
546  * This flag can also be set from application code, if an error happens
547  * during processing that should be reported during jtag_execute_queue().
548  *
549  * It is cleared by jtag_execute_queue().
550  */
551 extern int jtag_error;
552
553 static __inline__ void jtag_set_error(int error)
554 {
555         if ((error==ERROR_OK)||(jtag_error!=ERROR_OK))
556         {
557                 /* keep first error */
558                 return;
559         }
560         jtag_error=error;
561 }
562
563
564
565 /* can be implemented by hw+sw */
566 extern int jtag_power_dropout(int* dropout);
567 extern int jtag_srst_asserted(int* srst_asserted);
568
569 /* JTAG support functions */
570
571 /**
572  * Execute jtag queue and check value with an optional mask.
573  * @param field Pointer to scan field.
574  * @param value Pointer to scan value.
575  * @param mask Pointer to scan mask; may be NULL.
576  * @returns Nothing, but calls jtag_set_error() on any error.
577  */
578 extern void jtag_check_value_mask(scan_field_t *field, u8 *value, u8 *mask);
579
580 extern void jtag_sleep(u32 us);
581 extern int jtag_call_event_callbacks(enum jtag_event event);
582 extern int jtag_register_event_callback(int (* callback)(enum jtag_event event, void* priv), void* priv);
583
584 extern int jtag_verify_capture_ir;
585
586 void jtag_tap_handle_event(jtag_tap_t* tap, enum jtag_tap_event e);
587
588 /*
589  * The JTAG subsystem defines a number of error codes,
590  * using codes between -100 and -199.
591  */
592 #define ERROR_JTAG_INIT_FAILED       (-100)
593 #define ERROR_JTAG_INVALID_INTERFACE (-101)
594 #define ERROR_JTAG_NOT_IMPLEMENTED   (-102)
595 #define ERROR_JTAG_TRST_ASSERTED     (-103)
596 #define ERROR_JTAG_QUEUE_FAILED      (-104)
597 #define ERROR_JTAG_NOT_STABLE_STATE  (-105)
598 #define ERROR_JTAG_DEVICE_ERROR      (-107)
599
600 /**
601  * jtag_add_dr_out() is a version of jtag_add_dr_scan() which
602  * only scans data out. It operates on 32 bit integers instead
603  * of 8 bit, which makes it a better impedance match with
604  * the calling code which often operate on 32 bit integers.
605  *
606  * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
607  *
608  * num_bits[i] is the number of bits to clock out from value[i] LSB first.
609  *
610  * If the device is in bypass, then that is an error condition in
611  * the caller code that is not detected by this fn, whereas
612  * jtag_add_dr_scan() does detect it. Similarly if the device is not in
613  * bypass, data must be passed to it.
614  *
615  * If anything fails, then jtag_error will be set and jtag_execute() will
616  * return an error. There is no way to determine if there was a failure
617  * during this function call.
618  *
619  * This is an inline fn to speed up embedded hosts. Also note that
620  * interface_jtag_add_dr_out() can be a *small* inline function for
621  * embedded hosts.
622  *
623  * There is no jtag_add_dr_outin() version of this fn that also allows
624  * clocking data back in. Patches gladly accepted!
625  */
626 extern void jtag_add_dr_out(jtag_tap_t* tap,
627                 int num_fields, const int* num_bits, const u32* value,
628                 tap_state_t end_state);
629
630
631 /**
632  * jtag_add_statemove() moves from the current state to @a goal_state.
633  *
634  * This function was originally designed to handle the XSTATE command
635  * from the XSVF specification.
636  *
637  * @param goal_state The final TAP state.
638  * @return ERROR_OK on success, or an error code on failure.
639  */
640 extern int jtag_add_statemove(tap_state_t goal_state);
641
642 #endif /* JTAG_H */