- Replace 'while(' with 'while ('.
[openocd.git] / src / jtag / core.c
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 * Copyright (C) 2009 SoftPLC Corporation *
9 * http://softplc.com *
10 * dick@softplc.com *
11 * *
12 * Copyright (C) 2009 Zachary T Welch *
13 * zw@superlucidity.net *
14 * *
15 * This program is free software; you can redistribute it and/or modify *
16 * it under the terms of the GNU General Public License as published by *
17 * the Free Software Foundation; either version 2 of the License, or *
18 * (at your option) any later version. *
19 * *
20 * This program is distributed in the hope that it will be useful, *
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
23 * GNU General Public License for more details. *
24 * *
25 * You should have received a copy of the GNU General Public License *
26 * along with this program; if not, write to the *
27 * Free Software Foundation, Inc., *
28 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
29 ***************************************************************************/
30 #ifdef HAVE_CONFIG_H
31 #include "config.h"
32 #endif
33
34 #include "jtag.h"
35 #include "minidriver.h"
36 #include "interface.h"
37
38 #ifdef HAVE_STRINGS_H
39 #include <strings.h>
40 #endif
41
42
43 /// The number of JTAG queue flushes (for profiling and debugging purposes).
44 static int jtag_flush_queue_count;
45
46 static void jtag_add_scan_check(void (*jtag_add_scan)(int in_num_fields, const scan_field_t *in_fields, tap_state_t state),
47 int in_num_fields, scan_field_t *in_fields, tap_state_t state);
48
49 /**
50 * The jtag_error variable is set when an error occurs while executing
51 * the queue. Application code may set this using jtag_set_error(),
52 * when an error occurs during processing that should be reported during
53 * jtag_execute_queue().
54 *
55 * Tts value may be checked with jtag_get_error() and cleared with
56 * jtag_error_clear(). This value is returned (and cleared) by
57 * jtag_execute_queue().
58 */
59 static int jtag_error = ERROR_OK;
60
61 static const char *jtag_event_strings[] =
62 {
63 [JTAG_TRST_ASSERTED] = "JTAG controller reset (RESET or TRST)",
64 [JTAG_TAP_EVENT_ENABLE] = "TAP enabled",
65 [JTAG_TAP_EVENT_DISABLE] = "TAP disabled",
66 };
67
68 static int jtag_trst = 0;
69 static int jtag_srst = 0;
70
71 /**
72 * List all TAPs that have been created.
73 */
74 static jtag_tap_t *__jtag_all_taps = NULL;
75 /**
76 * The number of TAPs in the __jtag_all_taps list, used to track the
77 * assigned chain position to new TAPs
78 */
79 static unsigned jtag_num_taps = 0;
80
81 static enum reset_types jtag_reset_config = RESET_NONE;
82 static tap_state_t cmd_queue_end_state = TAP_RESET;
83 tap_state_t cmd_queue_cur_state = TAP_RESET;
84
85 static bool jtag_verify_capture_ir = true;
86 static int jtag_verify = 1;
87
88 /* how long the OpenOCD should wait before attempting JTAG communication after reset lines deasserted (in ms) */
89 static int jtag_nsrst_delay = 0; /* default to no nSRST delay */
90 static int jtag_ntrst_delay = 0; /* default to no nTRST delay */
91
92 typedef struct jtag_event_callback_s
93 {
94 jtag_event_handler_t callback;
95 void* priv;
96 struct jtag_event_callback_s* next;
97 } jtag_event_callback_t;
98
99 /* callbacks to inform high-level handlers about JTAG state changes */
100 static jtag_event_callback_t *jtag_event_callbacks;
101
102 /* speed in kHz*/
103 static int speed_khz = 0;
104 /* flag if the kHz speed was defined */
105 static bool hasKHz = false;
106 static int jtag_speed = 0;
107
108 static struct jtag_interface_s *jtag = NULL;
109
110 /* configuration */
111 jtag_interface_t *jtag_interface = NULL;
112
113 void jtag_set_error(int error)
114 {
115 if ((error == ERROR_OK) || (jtag_error != ERROR_OK))
116 return;
117 jtag_error = error;
118 }
119 int jtag_get_error(void)
120 {
121 return jtag_error;
122 }
123 int jtag_error_clear(void)
124 {
125 int temp = jtag_error;
126 jtag_error = ERROR_OK;
127 return temp;
128 }
129
130
131 jtag_tap_t *jtag_all_taps(void)
132 {
133 return __jtag_all_taps;
134 };
135
136 unsigned jtag_tap_count(void)
137 {
138 return jtag_num_taps;
139 }
140
141 unsigned jtag_tap_count_enabled(void)
142 {
143 jtag_tap_t *t = jtag_all_taps();
144 unsigned n = 0;
145 while (t)
146 {
147 if (t->enabled)
148 n++;
149 t = t->next_tap;
150 }
151 return n;
152 }
153
154 /// Append a new TAP to the chain of all taps.
155 void jtag_tap_add(struct jtag_tap_s *t)
156 {
157 t->abs_chain_position = jtag_num_taps++;
158
159 jtag_tap_t **tap = &__jtag_all_taps;
160 while (*tap != NULL)
161 tap = &(*tap)->next_tap;
162 *tap = t;
163 }
164
165 jtag_tap_t *jtag_tap_by_string(const char *s)
166 {
167 /* try by name first */
168 jtag_tap_t *t = jtag_all_taps();
169 while (t)
170 {
171 if (0 == strcmp(t->dotted_name, s))
172 return t;
173 t = t->next_tap;
174 }
175
176 /* no tap found by name, so try to parse the name as a number */
177 unsigned n;
178 if (parse_uint(s, &n) != ERROR_OK)
179 return NULL;
180
181 return jtag_tap_by_position(n);
182 }
183
184 jtag_tap_t *jtag_tap_by_jim_obj(Jim_Interp *interp, Jim_Obj *o)
185 {
186 const char *cp = Jim_GetString(o, NULL);
187 jtag_tap_t *t = cp ? jtag_tap_by_string(cp) : NULL;
188 if (NULL == cp)
189 cp = "(unknown)";
190 if (NULL == t)
191 Jim_SetResult_sprintf(interp, "Tap '%s' could not be found", cp);
192 return t;
193 }
194
195 /* returns a pointer to the n-th device in the scan chain */
196 jtag_tap_t *jtag_tap_by_position(unsigned n)
197 {
198 jtag_tap_t *t = jtag_all_taps();
199
200 while (t && n-- > 0)
201 t = t->next_tap;
202
203 return t;
204 }
205
206 jtag_tap_t* jtag_tap_next_enabled(jtag_tap_t* p)
207 {
208 p = p ? p->next_tap : jtag_all_taps();
209 while (p)
210 {
211 if (p->enabled)
212 return p;
213 p = p->next_tap;
214 }
215 return NULL;
216 }
217
218 const char *jtag_tap_name(const jtag_tap_t *tap)
219 {
220 return (tap == NULL) ? "(unknown)" : tap->dotted_name;
221 }
222
223
224 int jtag_register_event_callback(jtag_event_handler_t callback, void *priv)
225 {
226 jtag_event_callback_t **callbacks_p = &jtag_event_callbacks;
227
228 if (callback == NULL)
229 {
230 return ERROR_INVALID_ARGUMENTS;
231 }
232
233 if (*callbacks_p)
234 {
235 while ((*callbacks_p)->next)
236 callbacks_p = &((*callbacks_p)->next);
237 callbacks_p = &((*callbacks_p)->next);
238 }
239
240 (*callbacks_p) = malloc(sizeof(jtag_event_callback_t));
241 (*callbacks_p)->callback = callback;
242 (*callbacks_p)->priv = priv;
243 (*callbacks_p)->next = NULL;
244
245 return ERROR_OK;
246 }
247
248 int jtag_unregister_event_callback(jtag_event_handler_t callback, void *priv)
249 {
250 jtag_event_callback_t **callbacks_p;
251 jtag_event_callback_t **next;
252
253 if (callback == NULL)
254 {
255 return ERROR_INVALID_ARGUMENTS;
256 }
257
258 for (callbacks_p = &jtag_event_callbacks;
259 *callbacks_p != NULL;
260 callbacks_p = next)
261 {
262 next = &((*callbacks_p)->next);
263
264 if ((*callbacks_p)->priv != priv)
265 continue;
266
267 if ((*callbacks_p)->callback == callback)
268 {
269 free(*callbacks_p);
270 *callbacks_p = *next;
271 }
272 }
273
274 return ERROR_OK;
275 }
276
277 int jtag_call_event_callbacks(enum jtag_event event)
278 {
279 jtag_event_callback_t *callback = jtag_event_callbacks;
280
281 LOG_DEBUG("jtag event: %s", jtag_event_strings[event]);
282
283 while (callback)
284 {
285 jtag_event_callback_t *next;
286
287 /* callback may remove itself */
288 next = callback->next;
289 callback->callback(event, callback->priv);
290 callback = next;
291 }
292
293 return ERROR_OK;
294 }
295
296 static void jtag_checks(void)
297 {
298 assert(jtag_trst == 0);
299 }
300
301 static void jtag_prelude(tap_state_t state)
302 {
303 jtag_checks();
304
305 assert(state!=TAP_INVALID);
306
307 cmd_queue_cur_state = state;
308 }
309
310 void jtag_alloc_in_value32(scan_field_t *field)
311 {
312 interface_jtag_alloc_in_value32(field);
313 }
314
315 void jtag_add_ir_scan_noverify(int in_count, const scan_field_t *in_fields,
316 tap_state_t state)
317 {
318 jtag_prelude(state);
319
320 int retval = interface_jtag_add_ir_scan(in_count, in_fields, state);
321 jtag_set_error(retval);
322 }
323
324
325 void jtag_add_ir_scan(int in_num_fields, scan_field_t *in_fields, tap_state_t state)
326 {
327 if (jtag_verify&&jtag_verify_capture_ir)
328 {
329 /* 8 x 32 bit id's is enough for all invocations */
330
331 for (int j = 0; j < in_num_fields; j++)
332 {
333 /* if we are to run a verification of the ir scan, we need to get the input back.
334 * We may have to allocate space if the caller didn't ask for the input back.
335 */
336 in_fields[j].check_value=in_fields[j].tap->expected;
337 in_fields[j].check_mask=in_fields[j].tap->expected_mask;
338 }
339 jtag_add_scan_check(jtag_add_ir_scan_noverify, in_num_fields, in_fields, state);
340 } else
341 {
342 jtag_add_ir_scan_noverify(in_num_fields, in_fields, state);
343 }
344 }
345
346 void jtag_add_plain_ir_scan(int in_num_fields, const scan_field_t *in_fields,
347 tap_state_t state)
348 {
349 jtag_prelude(state);
350
351 int retval = interface_jtag_add_plain_ir_scan(
352 in_num_fields, in_fields, state);
353 jtag_set_error(retval);
354 }
355
356 void jtag_add_callback(jtag_callback1_t f, jtag_callback_data_t data0)
357 {
358 interface_jtag_add_callback(f, data0);
359 }
360
361 void jtag_add_callback4(jtag_callback_t f, jtag_callback_data_t data0,
362 jtag_callback_data_t data1, jtag_callback_data_t data2,
363 jtag_callback_data_t data3)
364 {
365 interface_jtag_add_callback4(f, data0, data1, data2, data3);
366 }
367
368 int jtag_check_value_inner(uint8_t *captured, uint8_t *in_check_value, uint8_t *in_check_mask, int num_bits);
369
370 static int jtag_check_value_mask_callback(jtag_callback_data_t data0, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3)
371 {
372 return jtag_check_value_inner((uint8_t *)data0, (uint8_t *)data1, (uint8_t *)data2, (int)data3);
373 }
374
375 static void jtag_add_scan_check(void (*jtag_add_scan)(int in_num_fields, const scan_field_t *in_fields, tap_state_t state),
376 int in_num_fields, scan_field_t *in_fields, tap_state_t state)
377 {
378 for (int i = 0; i < in_num_fields; i++)
379 {
380 struct scan_field_s *field = &in_fields[i];
381 field->allocated = 0;
382 field->modified = 0;
383 if (field->check_value || field->in_value)
384 continue;
385 interface_jtag_add_scan_check_alloc(field);
386 field->modified = 1;
387 }
388
389 jtag_add_scan(in_num_fields, in_fields, state);
390
391 for (int i = 0; i < in_num_fields; i++)
392 {
393 if ((in_fields[i].check_value != NULL) && (in_fields[i].in_value != NULL))
394 {
395 /* this is synchronous for a minidriver */
396 jtag_add_callback4(jtag_check_value_mask_callback, (jtag_callback_data_t)in_fields[i].in_value,
397 (jtag_callback_data_t)in_fields[i].check_value,
398 (jtag_callback_data_t)in_fields[i].check_mask,
399 (jtag_callback_data_t)in_fields[i].num_bits);
400 }
401 if (in_fields[i].allocated)
402 {
403 free(in_fields[i].in_value);
404 }
405 if (in_fields[i].modified)
406 {
407 in_fields[i].in_value = NULL;
408 }
409 }
410 }
411
412 void jtag_add_dr_scan_check(int in_num_fields, scan_field_t *in_fields, tap_state_t state)
413 {
414 if (jtag_verify)
415 {
416 jtag_add_scan_check(jtag_add_dr_scan, in_num_fields, in_fields, state);
417 } else
418 {
419 jtag_add_dr_scan(in_num_fields, in_fields, state);
420 }
421 }
422
423
424 void jtag_add_dr_scan(int in_num_fields, const scan_field_t *in_fields,
425 tap_state_t state)
426 {
427 jtag_prelude(state);
428
429 int retval;
430 retval = interface_jtag_add_dr_scan(in_num_fields, in_fields, state);
431 jtag_set_error(retval);
432 }
433
434 void jtag_add_plain_dr_scan(int in_num_fields, const scan_field_t *in_fields,
435 tap_state_t state)
436 {
437 jtag_prelude(state);
438
439 int retval;
440 retval = interface_jtag_add_plain_dr_scan(in_num_fields, in_fields, state);
441 jtag_set_error(retval);
442 }
443
444 void jtag_add_dr_out(jtag_tap_t* tap,
445 int num_fields, const int* num_bits, const uint32_t* value,
446 tap_state_t end_state)
447 {
448 assert(end_state != TAP_INVALID);
449
450 cmd_queue_cur_state = end_state;
451
452 interface_jtag_add_dr_out(tap,
453 num_fields, num_bits, value,
454 end_state);
455 }
456
457 void jtag_add_tlr(void)
458 {
459 jtag_prelude(TAP_RESET);
460 jtag_set_error(interface_jtag_add_tlr());
461 jtag_call_event_callbacks(JTAG_TRST_ASSERTED);
462 }
463
464 void jtag_add_pathmove(int num_states, const tap_state_t *path)
465 {
466 tap_state_t cur_state = cmd_queue_cur_state;
467
468 /* the last state has to be a stable state */
469 if (!tap_is_state_stable(path[num_states - 1]))
470 {
471 LOG_ERROR("BUG: TAP path doesn't finish in a stable state");
472 jtag_set_error(ERROR_JTAG_NOT_STABLE_STATE);
473 return;
474 }
475
476 for (int i = 0; i < num_states; i++)
477 {
478 if (path[i] == TAP_RESET)
479 {
480 LOG_ERROR("BUG: TAP_RESET is not a valid state for pathmove sequences");
481 jtag_set_error(ERROR_JTAG_STATE_INVALID);
482 return;
483 }
484
485 if ( tap_state_transition(cur_state, true) != path[i]
486 && tap_state_transition(cur_state, false) != path[i])
487 {
488 LOG_ERROR("BUG: %s -> %s isn't a valid TAP transition",
489 tap_state_name(cur_state), tap_state_name(path[i]));
490 jtag_set_error(ERROR_JTAG_TRANSITION_INVALID);
491 return;
492 }
493 cur_state = path[i];
494 }
495
496 jtag_checks();
497
498 jtag_set_error(interface_jtag_add_pathmove(num_states, path));
499 cmd_queue_cur_state = path[num_states - 1];
500 }
501
502 int jtag_add_statemove(tap_state_t goal_state)
503 {
504 tap_state_t cur_state = cmd_queue_cur_state;
505
506 LOG_DEBUG( "cur_state=%s goal_state=%s",
507 tap_state_name(cur_state),
508 tap_state_name(goal_state) );
509
510
511 if (goal_state==cur_state )
512 ; /* nothing to do */
513 else if ( goal_state==TAP_RESET )
514 {
515 jtag_add_tlr();
516 }
517 else if ( tap_is_state_stable(cur_state) && tap_is_state_stable(goal_state) )
518 {
519 unsigned tms_bits = tap_get_tms_path(cur_state, goal_state);
520 unsigned tms_count = tap_get_tms_path_len(cur_state, goal_state);
521 tap_state_t moves[8];
522 assert(tms_count < DIM(moves));
523
524 for (unsigned i = 0; i < tms_count; i++, tms_bits >>= 1)
525 {
526 bool bit = tms_bits & 1;
527
528 cur_state = tap_state_transition(cur_state, bit);
529 moves[i] = cur_state;
530 }
531
532 jtag_add_pathmove(tms_count, moves);
533 }
534 else if ( tap_state_transition(cur_state, true) == goal_state
535 || tap_state_transition(cur_state, false) == goal_state )
536 {
537 jtag_add_pathmove(1, &goal_state);
538 }
539
540 else
541 return ERROR_FAIL;
542
543 return ERROR_OK;
544 }
545
546 void jtag_add_runtest(int num_cycles, tap_state_t state)
547 {
548 jtag_prelude(state);
549 jtag_set_error(interface_jtag_add_runtest(num_cycles, state));
550 }
551
552
553 void jtag_add_clocks(int num_cycles)
554 {
555 if (!tap_is_state_stable(cmd_queue_cur_state))
556 {
557 LOG_ERROR("jtag_add_clocks() called with TAP in unstable state \"%s\"",
558 tap_state_name(cmd_queue_cur_state));
559 jtag_set_error(ERROR_JTAG_NOT_STABLE_STATE);
560 return;
561 }
562
563 if (num_cycles > 0)
564 {
565 jtag_checks();
566 jtag_set_error(interface_jtag_add_clocks(num_cycles));
567 }
568 }
569
570 void jtag_add_reset(int req_tlr_or_trst, int req_srst)
571 {
572 int trst_with_tlr = 0;
573
574 /* FIX!!! there are *many* different cases here. A better
575 * approach is needed for legal combinations of transitions...
576 */
577 if ((jtag_reset_config & RESET_HAS_SRST)&&
578 (jtag_reset_config & RESET_HAS_TRST)&&
579 ((jtag_reset_config & RESET_SRST_PULLS_TRST)==0))
580 {
581 if (((req_tlr_or_trst&&!jtag_trst)||
582 (!req_tlr_or_trst&&jtag_trst))&&
583 ((req_srst&&!jtag_srst)||
584 (!req_srst&&jtag_srst)))
585 {
586 /* FIX!!! srst_pulls_trst allows 1,1 => 0,0 transition.... */
587 //LOG_ERROR("BUG: transition of req_tlr_or_trst and req_srst in the same jtag_add_reset() call is undefined");
588 }
589 }
590
591 /* Make sure that jtag_reset_config allows the requested reset */
592 /* if SRST pulls TRST, we can't fulfill srst == 1 with trst == 0 */
593 if (((jtag_reset_config & RESET_SRST_PULLS_TRST) && (req_srst == 1)) && (!req_tlr_or_trst))
594 {
595 LOG_ERROR("BUG: requested reset would assert trst");
596 jtag_set_error(ERROR_FAIL);
597 return;
598 }
599
600 /* if TRST pulls SRST, we reset with TAP T-L-R */
601 if (((jtag_reset_config & RESET_TRST_PULLS_SRST) && (req_tlr_or_trst)) && (req_srst == 0))
602 {
603 trst_with_tlr = 1;
604 }
605
606 if (req_srst && !(jtag_reset_config & RESET_HAS_SRST))
607 {
608 LOG_ERROR("BUG: requested SRST assertion, but the current configuration doesn't support this");
609 jtag_set_error(ERROR_FAIL);
610 return;
611 }
612
613 if (req_tlr_or_trst)
614 {
615 if (!trst_with_tlr && (jtag_reset_config & RESET_HAS_TRST))
616 {
617 jtag_trst = 1;
618 } else
619 {
620 trst_with_tlr = 1;
621 }
622 } else
623 {
624 jtag_trst = 0;
625 }
626
627 jtag_srst = req_srst;
628
629 int retval = interface_jtag_add_reset(jtag_trst, jtag_srst);
630 if (retval != ERROR_OK)
631 {
632 jtag_set_error(retval);
633 return;
634 }
635 jtag_execute_queue();
636
637 if (jtag_srst)
638 {
639 LOG_DEBUG("SRST line asserted");
640 }
641 else
642 {
643 LOG_DEBUG("SRST line released");
644 if (jtag_nsrst_delay)
645 jtag_add_sleep(jtag_nsrst_delay * 1000);
646 }
647
648 if (trst_with_tlr)
649 {
650 LOG_DEBUG("JTAG reset with RESET instead of TRST");
651 jtag_set_end_state(TAP_RESET);
652 jtag_add_tlr();
653 return;
654 }
655
656 if (jtag_trst)
657 {
658 /* we just asserted nTRST, so we're now in Test-Logic-Reset,
659 * and inform possible listeners about this
660 */
661 LOG_DEBUG("TRST line asserted");
662 tap_set_state(TAP_RESET);
663 jtag_call_event_callbacks(JTAG_TRST_ASSERTED);
664 }
665 else
666 {
667 if (jtag_ntrst_delay)
668 jtag_add_sleep(jtag_ntrst_delay * 1000);
669 }
670 }
671
672 tap_state_t jtag_set_end_state(tap_state_t state)
673 {
674 if ((state == TAP_DRSHIFT)||(state == TAP_IRSHIFT))
675 {
676 LOG_ERROR("BUG: TAP_DRSHIFT/IRSHIFT can't be end state. Calling code should use a larger scan field");
677 }
678
679 if (state!=TAP_INVALID)
680 cmd_queue_end_state = state;
681 return cmd_queue_end_state;
682 }
683
684 tap_state_t jtag_get_end_state(void)
685 {
686 return cmd_queue_end_state;
687 }
688
689 void jtag_add_sleep(uint32_t us)
690 {
691 /// @todo Here, keep_alive() appears to be a layering violation!!!
692 keep_alive();
693 jtag_set_error(interface_jtag_add_sleep(us));
694 }
695
696 int jtag_check_value_inner(uint8_t *captured, uint8_t *in_check_value, uint8_t *in_check_mask, int num_bits)
697 {
698 int retval = ERROR_OK;
699
700 int compare_failed = 0;
701
702 if (in_check_mask)
703 compare_failed = buf_cmp_mask(captured, in_check_value, in_check_mask, num_bits);
704 else
705 compare_failed = buf_cmp(captured, in_check_value, num_bits);
706
707 if (compare_failed){
708 /* An error handler could have caught the failing check
709 * only report a problem when there wasn't a handler, or if the handler
710 * acknowledged the error
711 */
712 /*
713 LOG_WARNING("TAP %s:",
714 jtag_tap_name(field->tap));
715 */
716 if (compare_failed)
717 {
718 char *captured_char = buf_to_str(captured, (num_bits > DEBUG_JTAG_IOZ) ? DEBUG_JTAG_IOZ : num_bits, 16);
719 char *in_check_value_char = buf_to_str(in_check_value, (num_bits > DEBUG_JTAG_IOZ) ? DEBUG_JTAG_IOZ : num_bits, 16);
720
721 if (in_check_mask)
722 {
723 char *in_check_mask_char;
724 in_check_mask_char = buf_to_str(in_check_mask, (num_bits > DEBUG_JTAG_IOZ) ? DEBUG_JTAG_IOZ : num_bits, 16);
725 LOG_WARNING("value captured during scan didn't pass the requested check:");
726 LOG_WARNING("captured: 0x%s check_value: 0x%s check_mask: 0x%s",
727 captured_char, in_check_value_char, in_check_mask_char);
728 free(in_check_mask_char);
729 }
730 else
731 {
732 LOG_WARNING("value captured during scan didn't pass the requested check: captured: 0x%s check_value: 0x%s", captured_char, in_check_value_char);
733 }
734
735 free(captured_char);
736 free(in_check_value_char);
737
738 retval = ERROR_JTAG_QUEUE_FAILED;
739 }
740
741 }
742 return retval;
743 }
744
745 void jtag_check_value_mask(scan_field_t *field, uint8_t *value, uint8_t *mask)
746 {
747 assert(field->in_value != NULL);
748
749 if (value==NULL)
750 {
751 /* no checking to do */
752 return;
753 }
754
755 jtag_execute_queue_noclear();
756
757 int retval=jtag_check_value_inner(field->in_value, value, mask, field->num_bits);
758 jtag_set_error(retval);
759 }
760
761
762
763 int default_interface_jtag_execute_queue(void)
764 {
765 if (NULL == jtag)
766 {
767 LOG_ERROR("No JTAG interface configured yet. "
768 "Issue 'init' command in startup scripts "
769 "before communicating with targets.");
770 return ERROR_FAIL;
771 }
772
773 return jtag->execute_queue();
774 }
775
776 void jtag_execute_queue_noclear(void)
777 {
778 jtag_flush_queue_count++;
779 jtag_set_error(interface_jtag_execute_queue());
780 }
781
782 int jtag_get_flush_queue_count(void)
783 {
784 return jtag_flush_queue_count;
785 }
786
787 int jtag_execute_queue(void)
788 {
789 jtag_execute_queue_noclear();
790 return jtag_error_clear();
791 }
792
793 static int jtag_reset_callback(enum jtag_event event, void *priv)
794 {
795 jtag_tap_t *tap = priv;
796
797 LOG_DEBUG("-");
798
799 if (event == JTAG_TRST_ASSERTED)
800 {
801 tap->enabled = !tap->disabled_after_reset;
802
803 buf_set_ones(tap->cur_instr, tap->ir_length);
804 tap->bypass = 1;
805 }
806
807 return ERROR_OK;
808 }
809
810 void jtag_sleep(uint32_t us)
811 {
812 alive_sleep(us/1000);
813 }
814
815 /// maximum number of JTAG devices expected in the chain
816 #define JTAG_MAX_CHAIN_SIZE 20
817
818 #define EXTRACT_MFG(X) (((X) & 0xffe) >> 1)
819 #define EXTRACT_PART(X) (((X) & 0xffff000) >> 12)
820 #define EXTRACT_VER(X) (((X) & 0xf0000000) >> 28)
821
822 static int jtag_examine_chain_execute(uint8_t *idcode_buffer, unsigned num_idcode)
823 {
824 scan_field_t field = {
825 .tap = NULL,
826 .num_bits = num_idcode * 32,
827 .out_value = idcode_buffer,
828 .in_value = idcode_buffer,
829 };
830
831 // initialize to the end of chain ID value
832 for (unsigned i = 0; i < JTAG_MAX_CHAIN_SIZE; i++)
833 buf_set_u32(idcode_buffer, i * 32, 32, 0x000000FF);
834
835 jtag_add_plain_dr_scan(1, &field, TAP_RESET);
836 return jtag_execute_queue();
837 }
838
839 static bool jtag_examine_chain_check(uint8_t *idcodes, unsigned count)
840 {
841 uint8_t zero_check = 0x0;
842 uint8_t one_check = 0xff;
843
844 for (unsigned i = 0; i < count * 4; i++)
845 {
846 zero_check |= idcodes[i];
847 one_check &= idcodes[i];
848 }
849
850 /* if there wasn't a single non-zero bit or if all bits were one,
851 * the scan is not valid */
852 if (zero_check == 0x00 || one_check == 0xff)
853 {
854 LOG_ERROR("JTAG communication failure: check connection, "
855 "JTAG interface, target power etc.");
856 return false;
857 }
858 return true;
859 }
860
861 static void jtag_examine_chain_display(enum log_levels level, const char *msg,
862 const char *name, uint32_t idcode)
863 {
864 log_printf_lf(level, __FILE__, __LINE__, __FUNCTION__,
865 "JTAG tap: %s %16.16s: 0x%08x "
866 "(mfg: 0x%3.3x, part: 0x%4.4x, ver: 0x%1.1x)",
867 name, msg,
868 (unsigned int)idcode,
869 (unsigned int)EXTRACT_MFG(idcode),
870 (unsigned int)EXTRACT_PART(idcode),
871 (unsigned int)EXTRACT_VER(idcode) );
872 }
873
874 static bool jtag_idcode_is_final(uint32_t idcode)
875 {
876 return idcode == 0x000000FF || idcode == 0xFFFFFFFF;
877 }
878
879 /**
880 * This helper checks that remaining bits in the examined chain data are
881 * all as expected, but a single JTAG device requires only 64 bits to be
882 * read back correctly. This can help identify and diagnose problems
883 * with the JTAG chain earlier, gives more helpful/explicit error messages.
884 */
885 static void jtag_examine_chain_end(uint8_t *idcodes, unsigned count, unsigned max)
886 {
887 bool triggered = false;
888 for ( ; count < max - 31; count += 32)
889 {
890 uint32_t idcode = buf_get_u32(idcodes, count, 32);
891 // do not trigger the warning if the data looks good
892 if (!triggered && jtag_idcode_is_final(idcode))
893 continue;
894 LOG_WARNING("Unexpected idcode after end of chain: %d 0x%08x",
895 count, (unsigned int)idcode);
896 triggered = true;
897 }
898 }
899
900 static bool jtag_examine_chain_match_tap(const struct jtag_tap_s *tap)
901 {
902 if (0 == tap->expected_ids_cnt)
903 {
904 /// @todo Enable LOG_INFO to ask for reports about unknown TAP IDs.
905 #if 0
906 LOG_INFO("Uknown JTAG TAP ID: 0x%08x", tap->idcode)
907 LOG_INFO("Please report the chip name and reported ID code to the openocd project");
908 #endif
909 return true;
910 }
911
912 /* Loop over the expected identification codes and test for a match */
913 uint8_t ii;
914 for (ii = 0; ii < tap->expected_ids_cnt; ii++)
915 {
916 if (tap->idcode == tap->expected_ids[ii])
917 break;
918 }
919
920 /* If none of the expected ids matched, log an error */
921 if (ii != tap->expected_ids_cnt)
922 {
923 LOG_INFO("JTAG Tap/device matched");
924 return true;
925 }
926 jtag_examine_chain_display(LOG_LVL_ERROR, "got",
927 tap->dotted_name, tap->idcode);
928 for (ii = 0; ii < tap->expected_ids_cnt; ii++)
929 {
930 char msg[32];
931 snprintf(msg, sizeof(msg), "expected %hhu of %hhu",
932 ii + 1, tap->expected_ids_cnt);
933 jtag_examine_chain_display(LOG_LVL_ERROR, msg,
934 tap->dotted_name, tap->expected_ids[ii]);
935 }
936 return false;
937 }
938
939 /* Try to examine chain layout according to IEEE 1149.1 §12
940 */
941 int jtag_examine_chain(void)
942 {
943 uint8_t idcode_buffer[JTAG_MAX_CHAIN_SIZE * 4];
944 unsigned device_count = 0;
945
946 jtag_examine_chain_execute(idcode_buffer, JTAG_MAX_CHAIN_SIZE);
947
948 if (!jtag_examine_chain_check(idcode_buffer, JTAG_MAX_CHAIN_SIZE))
949 return ERROR_JTAG_INIT_FAILED;
950
951 /* point at the 1st tap */
952 jtag_tap_t *tap = jtag_tap_next_enabled(NULL);
953 if (tap == NULL)
954 {
955 LOG_ERROR("JTAG: No taps enabled?");
956 return ERROR_JTAG_INIT_FAILED;
957 }
958
959 for (unsigned bit_count = 0; bit_count < (JTAG_MAX_CHAIN_SIZE * 32) - 31;)
960 {
961 uint32_t idcode = buf_get_u32(idcode_buffer, bit_count, 32);
962 if ((idcode & 1) == 0)
963 {
964 /* LSB must not be 0, this indicates a device in bypass */
965 LOG_WARNING("Tap/Device does not have IDCODE");
966 idcode = 0;
967
968 bit_count += 1;
969 }
970 else
971 {
972 /*
973 * End of chain (invalid manufacturer ID) some devices, such
974 * as AVR will output all 1's instead of TDI input value at
975 * end of chain.
976 */
977 if (jtag_idcode_is_final(idcode))
978 {
979 jtag_examine_chain_end(idcode_buffer,
980 bit_count + 32, JTAG_MAX_CHAIN_SIZE * 32);
981 break;
982 }
983
984 jtag_examine_chain_display(LOG_LVL_INFO, "tap/device found",
985 tap ? tap->dotted_name : "(not-named)",
986 idcode);
987
988 bit_count += 32;
989 }
990 device_count++;
991 if (!tap)
992 continue;
993
994 tap->idcode = idcode;
995
996 // ensure the TAP ID does matches what was expected
997 if (!jtag_examine_chain_match_tap(tap))
998 return ERROR_JTAG_INIT_FAILED;
999
1000 tap = jtag_tap_next_enabled(tap);
1001 }
1002
1003 /* see if number of discovered devices matches configuration */
1004 if (device_count != jtag_tap_count_enabled())
1005 {
1006 LOG_ERROR("number of discovered devices in JTAG chain (%i) "
1007 "does not match (enabled) configuration (%i), total taps: %d",
1008 device_count, jtag_tap_count_enabled(), jtag_tap_count());
1009 LOG_ERROR("check the config file and ensure proper JTAG communication"
1010 " (connections, speed, ...)");
1011 return ERROR_JTAG_INIT_FAILED;
1012 }
1013
1014 return ERROR_OK;
1015 }
1016
1017 int jtag_validate_chain(void)
1018 {
1019 jtag_tap_t *tap;
1020 int total_ir_length = 0;
1021 uint8_t *ir_test = NULL;
1022 scan_field_t field;
1023 int chain_pos = 0;
1024
1025 tap = NULL;
1026 total_ir_length = 0;
1027 for(;;){
1028 tap = jtag_tap_next_enabled(tap);
1029 if ( tap == NULL ){
1030 break;
1031 }
1032 total_ir_length += tap->ir_length;
1033 }
1034
1035 total_ir_length += 2;
1036 ir_test = malloc(CEIL(total_ir_length, 8));
1037 buf_set_ones(ir_test, total_ir_length);
1038
1039 field.tap = NULL;
1040 field.num_bits = total_ir_length;
1041 field.out_value = ir_test;
1042 field.in_value = ir_test;
1043
1044
1045 jtag_add_plain_ir_scan(1, &field, TAP_RESET);
1046 jtag_execute_queue();
1047
1048 tap = NULL;
1049 chain_pos = 0;
1050 int val;
1051 for(;;){
1052 tap = jtag_tap_next_enabled(tap);
1053 if ( tap == NULL ){
1054 break;
1055 }
1056
1057 val = buf_get_u32(ir_test, chain_pos, 2);
1058 if (val != 0x1)
1059 {
1060 char *cbuf = buf_to_str(ir_test, total_ir_length, 16);
1061 LOG_ERROR("Could not validate JTAG scan chain, IR mismatch, scan returned 0x%s. tap=%s pos=%d expected 0x1 got %0x", cbuf, jtag_tap_name(tap), chain_pos, val);
1062 free(cbuf);
1063 free(ir_test);
1064 return ERROR_JTAG_INIT_FAILED;
1065 }
1066 chain_pos += tap->ir_length;
1067 }
1068
1069 val = buf_get_u32(ir_test, chain_pos, 2);
1070 if (val != 0x3)
1071 {
1072 char *cbuf = buf_to_str(ir_test, total_ir_length, 16);
1073 LOG_ERROR("Could not validate end of JTAG scan chain, IR mismatch, scan returned 0x%s. pos=%d expected 0x3 got %0x", cbuf, chain_pos, val);
1074 free(cbuf);
1075 free(ir_test);
1076 return ERROR_JTAG_INIT_FAILED;
1077 }
1078
1079 free(ir_test);
1080
1081 return ERROR_OK;
1082 }
1083
1084
1085 void jtag_tap_init(jtag_tap_t *tap)
1086 {
1087 assert(0 != tap->ir_length);
1088
1089 tap->expected = malloc(tap->ir_length);
1090 tap->expected_mask = malloc(tap->ir_length);
1091 tap->cur_instr = malloc(tap->ir_length);
1092
1093 /// @todo cope sanely with ir_length bigger than 32 bits
1094 buf_set_u32(tap->expected, 0, tap->ir_length, tap->ir_capture_value);
1095 buf_set_u32(tap->expected_mask, 0, tap->ir_length, tap->ir_capture_mask);
1096 buf_set_ones(tap->cur_instr, tap->ir_length);
1097
1098 // place TAP in bypass mode
1099 tap->bypass = 1;
1100 // register the reset callback for the TAP
1101 jtag_register_event_callback(&jtag_reset_callback, tap);
1102
1103 LOG_DEBUG("Created Tap: %s @ abs position %d, "
1104 "irlen %d, capture: 0x%x mask: 0x%x", tap->dotted_name,
1105 tap->abs_chain_position, tap->ir_length,
1106 (unsigned int)(tap->ir_capture_value), (unsigned int)(tap->ir_capture_mask));
1107 jtag_tap_add(tap);
1108 }
1109
1110 void jtag_tap_free(jtag_tap_t *tap)
1111 {
1112 jtag_unregister_event_callback(&jtag_reset_callback, tap);
1113
1114 /// @todo is anything missing? no memory leaks please
1115 free((void *)tap->expected_ids);
1116 free((void *)tap->chip);
1117 free((void *)tap->tapname);
1118 free((void *)tap->dotted_name);
1119 free(tap);
1120 }
1121
1122 int jtag_interface_init(struct command_context_s *cmd_ctx)
1123 {
1124 if (jtag)
1125 return ERROR_OK;
1126
1127 if (!jtag_interface)
1128 {
1129 /* nothing was previously specified by "interface" command */
1130 LOG_ERROR("JTAG interface has to be specified, see \"interface\" command");
1131 return ERROR_JTAG_INVALID_INTERFACE;
1132 }
1133 if (hasKHz)
1134 {
1135 jtag_interface->khz(jtag_get_speed_khz(), &jtag_speed);
1136 hasKHz = false;
1137 }
1138
1139 if (jtag_interface->init() != ERROR_OK)
1140 return ERROR_JTAG_INIT_FAILED;
1141
1142 jtag = jtag_interface;
1143 return ERROR_OK;
1144 }
1145
1146 static int jtag_init_inner(struct command_context_s *cmd_ctx)
1147 {
1148 jtag_tap_t *tap;
1149 int retval;
1150
1151 LOG_DEBUG("Init JTAG chain");
1152
1153 tap = jtag_tap_next_enabled(NULL);
1154 if ( tap == NULL ){
1155 LOG_ERROR("There are no enabled taps?");
1156 return ERROR_JTAG_INIT_FAILED;
1157 }
1158
1159 jtag_add_tlr();
1160 if ((retval=jtag_execute_queue())!=ERROR_OK)
1161 return retval;
1162
1163 /* examine chain first, as this could discover the real chain layout */
1164 if (jtag_examine_chain() != ERROR_OK)
1165 {
1166 LOG_ERROR("trying to validate configured JTAG chain anyway...");
1167 }
1168
1169 if (jtag_validate_chain() != ERROR_OK)
1170 {
1171 LOG_WARNING("Could not validate JTAG chain, continuing anyway...");
1172 }
1173
1174 return ERROR_OK;
1175 }
1176
1177 int jtag_interface_quit(void)
1178 {
1179 if (!jtag || !jtag->quit)
1180 return ERROR_OK;
1181
1182 // close the JTAG interface
1183 int result = jtag->quit();
1184 if (ERROR_OK != result)
1185 LOG_ERROR("failed: %d", result);
1186
1187 return ERROR_OK;
1188 }
1189
1190
1191 int jtag_init_reset(struct command_context_s *cmd_ctx)
1192 {
1193 int retval;
1194
1195 if ((retval=jtag_interface_init(cmd_ctx)) != ERROR_OK)
1196 return retval;
1197
1198 LOG_DEBUG("Trying to bring the JTAG controller to life by asserting TRST / RESET");
1199
1200 /* Reset can happen after a power cycle.
1201 *
1202 * Ideally we would only assert TRST or run RESET before the target reset.
1203 *
1204 * However w/srst_pulls_trst, trst is asserted together with the target
1205 * reset whether we want it or not.
1206 *
1207 * NB! Some targets have JTAG circuitry disabled until a
1208 * trst & srst has been asserted.
1209 *
1210 * NB! here we assume nsrst/ntrst delay are sufficient!
1211 *
1212 * NB! order matters!!!! srst *can* disconnect JTAG circuitry
1213 *
1214 */
1215 jtag_add_reset(1, 0); /* RESET or TRST */
1216 if (jtag_reset_config & RESET_HAS_SRST)
1217 {
1218 jtag_add_reset(1, 1);
1219 if ((jtag_reset_config & RESET_SRST_PULLS_TRST)==0)
1220 jtag_add_reset(0, 1);
1221 }
1222 jtag_add_reset(0, 0);
1223 if ((retval = jtag_execute_queue()) != ERROR_OK)
1224 return retval;
1225
1226 /* Check that we can communication on the JTAG chain + eventually we want to
1227 * be able to perform enumeration only after OpenOCD has started
1228 * telnet and GDB server
1229 *
1230 * That would allow users to more easily perform any magic they need to before
1231 * reset happens.
1232 */
1233 return jtag_init_inner(cmd_ctx);
1234 }
1235
1236 int jtag_init(struct command_context_s *cmd_ctx)
1237 {
1238 int retval;
1239 if ((retval=jtag_interface_init(cmd_ctx)) != ERROR_OK)
1240 return retval;
1241 if (jtag_init_inner(cmd_ctx)==ERROR_OK)
1242 {
1243 return ERROR_OK;
1244 }
1245 return jtag_init_reset(cmd_ctx);
1246 }
1247
1248 void jtag_set_speed_khz(unsigned khz)
1249 {
1250 speed_khz = khz;
1251 }
1252 unsigned jtag_get_speed_khz(void)
1253 {
1254 return speed_khz;
1255 }
1256 int jtag_config_khz(unsigned khz)
1257 {
1258 LOG_DEBUG("handle jtag khz");
1259 jtag_set_speed_khz(khz);
1260
1261 int cur_speed = 0;
1262 if (jtag != NULL)
1263 {
1264 LOG_DEBUG("have interface set up");
1265 int speed_div1;
1266 int retval = jtag->khz(jtag_get_speed_khz(), &speed_div1);
1267 if (ERROR_OK != retval)
1268 {
1269 jtag_set_speed_khz(0);
1270 return retval;
1271 }
1272 cur_speed = speed_div1;
1273 }
1274 return jtag_set_speed(cur_speed);
1275 }
1276
1277 int jtag_get_speed(void)
1278 {
1279 return jtag_speed;
1280 }
1281
1282 int jtag_set_speed(int speed)
1283 {
1284 jtag_speed = speed;
1285 /* this command can be called during CONFIG,
1286 * in which case jtag isn't initialized */
1287 hasKHz = !jtag;
1288 return jtag ? jtag->speed(speed) : ERROR_OK;
1289 }
1290
1291 int jtag_get_speed_readable(int *speed)
1292 {
1293 return jtag ? jtag->speed_div(jtag_get_speed(), speed) : ERROR_OK;
1294 }
1295
1296
1297 void jtag_set_verify(bool enable)
1298 {
1299 jtag_verify = enable;
1300 }
1301
1302 bool jtag_will_verify()
1303 {
1304 return jtag_verify;
1305 }
1306
1307 void jtag_set_verify_capture_ir(bool enable)
1308 {
1309 jtag_verify_capture_ir = enable;
1310 }
1311
1312 bool jtag_will_verify_capture_ir()
1313 {
1314 return jtag_verify_capture_ir;
1315 }
1316
1317 int jtag_power_dropout(int *dropout)
1318 {
1319 return jtag->power_dropout(dropout);
1320 }
1321
1322 int jtag_srst_asserted(int *srst_asserted)
1323 {
1324 return jtag->srst_asserted(srst_asserted);
1325 }
1326
1327 enum reset_types jtag_get_reset_config(void)
1328 {
1329 return jtag_reset_config;
1330 }
1331 void jtag_set_reset_config(enum reset_types type)
1332 {
1333 jtag_reset_config = type;
1334 }
1335
1336 int jtag_get_trst(void)
1337 {
1338 return jtag_trst;
1339 }
1340 int jtag_get_srst(void)
1341 {
1342 return jtag_srst;
1343 }
1344
1345 void jtag_set_nsrst_delay(unsigned delay)
1346 {
1347 jtag_nsrst_delay = delay;
1348 }
1349 unsigned jtag_get_nsrst_delay(void)
1350 {
1351 return jtag_nsrst_delay;
1352 }
1353 void jtag_set_ntrst_delay(unsigned delay)
1354 {
1355 jtag_ntrst_delay = delay;
1356 }
1357 unsigned jtag_get_ntrst_delay(void)
1358 {
1359 return jtag_ntrst_delay;
1360 }