OpenOCD
xsvf.c
Go to the documentation of this file.
1 // SPDX-License-Identifier: GPL-2.0-or-later
2 
3 /***************************************************************************
4  * Copyright (C) 2005 by Dominic Rath *
5  * Dominic.Rath@gmx.de *
6  * *
7  * Copyright (C) 2007,2008 Øyvind Harboe *
8  * oyvind.harboe@zylin.com *
9  * *
10  * Copyright (C) 2008 Peter Hettkamp *
11  * peter.hettkamp@htp-tel.de *
12  * *
13  * Copyright (C) 2009 SoftPLC Corporation. http://softplc.com *
14  * Dick Hollenbeck <dick@softplc.com> *
15  ***************************************************************************/
16 
17 /* The specification for SVF is available here:
18  * http://www.asset-intertech.com/support/svf.pdf
19  * Below, this document is referred to as the "SVF spec".
20  *
21  * The specification for XSVF is available here:
22  * http://www.xilinx.com/support/documentation/application_notes/xapp503.pdf
23  * Below, this document is referred to as the "XSVF spec".
24  */
25 
26 #ifdef HAVE_CONFIG_H
27 #include "config.h"
28 #endif
29 
30 #include "xsvf.h"
31 #include "helper/system.h"
32 #include <jtag/jtag.h>
33 #include <svf/svf.h>
34 
35 /* XSVF commands, from appendix B of xapp503.pdf */
36 #define XCOMPLETE 0x00
37 #define XTDOMASK 0x01
38 #define XSIR 0x02
39 #define XSDR 0x03
40 #define XRUNTEST 0x04
41 #define XREPEAT 0x07
42 #define XSDRSIZE 0x08
43 #define XSDRTDO 0x09
44 #define XSETSDRMASKS 0x0A
45 #define XSDRINC 0x0B
46 #define XSDRB 0x0C
47 #define XSDRC 0x0D
48 #define XSDRE 0x0E
49 #define XSDRTDOB 0x0F
50 #define XSDRTDOC 0x10
51 #define XSDRTDOE 0x11
52 #define XSTATE 0x12
53 #define XENDIR 0x13
54 #define XENDDR 0x14
55 #define XSIR2 0x15
56 #define XCOMMENT 0x16
57 #define XWAIT 0x17
58 
59 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
60  * generates this. Arguably it is needed because the XSVF XRUNTEST command
61  * was ill conceived and does not directly flow out of the SVF RUNTEST command.
62  * This XWAITSTATE does map directly from the SVF RUNTEST command.
63  */
64 #define XWAITSTATE 0x18
65 
66 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
67  * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
68  * Here is an example of usage of the 3 lattice opcode extensions:
69 
70 ! Set the maximum loop count to 25.
71 LCOUNT 25;
72 ! Step to DRPAUSE give 5 clocks and wait for 1.00e + 000 SEC.
73 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
74 ! Test for the completed status. Match means pass.
75 ! Loop back to LDELAY line if not match and loop count less than 25.
76 
77 LSDR 1 TDI (0)
78 TDO (1);
79 */
80 
81 #define LCOUNT 0x19
82 #define LDELAY 0x1A
83 #define LSDR 0x1B
84 #define XTRST 0x1C
85 
86 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
87 #define XSV_RESET 0x00
88 #define XSV_IDLE 0x01
89 #define XSV_DRSELECT 0x02
90 #define XSV_DRCAPTURE 0x03
91 #define XSV_DRSHIFT 0x04
92 #define XSV_DREXIT1 0x05
93 #define XSV_DRPAUSE 0x06
94 #define XSV_DREXIT2 0x07
95 #define XSV_DRUPDATE 0x08
96 #define XSV_IRSELECT 0x09
97 #define XSV_IRCAPTURE 0x0A
98 #define XSV_IRSHIFT 0x0B
99 #define XSV_IREXIT1 0x0C
100 #define XSV_IRPAUSE 0x0D
101 #define XSV_IREXIT2 0x0E
102 #define XSV_IRUPDATE 0x0F
103 
104 /* arguments to XTRST */
105 #define XTRST_ON 0
106 #define XTRST_OFF 1
107 #define XTRST_Z 2
108 #define XTRST_ABSENT 3
109 
110 #define XSTATE_MAX_PATH 12
111 
112 static int xsvf_fd;
113 
114 /* map xsvf tap state to an openocd "tap_state_t" */
115 static tap_state_t xsvf_to_tap(int xsvf_state)
116 {
117  tap_state_t ret;
118 
119  switch (xsvf_state) {
120  case XSV_RESET:
121  ret = TAP_RESET;
122  break;
123  case XSV_IDLE:
124  ret = TAP_IDLE;
125  break;
126  case XSV_DRSELECT:
127  ret = TAP_DRSELECT;
128  break;
129  case XSV_DRCAPTURE:
130  ret = TAP_DRCAPTURE;
131  break;
132  case XSV_DRSHIFT:
133  ret = TAP_DRSHIFT;
134  break;
135  case XSV_DREXIT1:
136  ret = TAP_DREXIT1;
137  break;
138  case XSV_DRPAUSE:
139  ret = TAP_DRPAUSE;
140  break;
141  case XSV_DREXIT2:
142  ret = TAP_DREXIT2;
143  break;
144  case XSV_DRUPDATE:
145  ret = TAP_DRUPDATE;
146  break;
147  case XSV_IRSELECT:
148  ret = TAP_IRSELECT;
149  break;
150  case XSV_IRCAPTURE:
151  ret = TAP_IRCAPTURE;
152  break;
153  case XSV_IRSHIFT:
154  ret = TAP_IRSHIFT;
155  break;
156  case XSV_IREXIT1:
157  ret = TAP_IREXIT1;
158  break;
159  case XSV_IRPAUSE:
160  ret = TAP_IRPAUSE;
161  break;
162  case XSV_IREXIT2:
163  ret = TAP_IREXIT2;
164  break;
165  case XSV_IRUPDATE:
166  ret = TAP_IRUPDATE;
167  break;
168  default:
169  LOG_ERROR("UNKNOWN XSVF STATE 0x%02X", xsvf_state);
170  exit(1);
171  }
172 
173  return ret;
174 }
175 
176 static int xsvf_read_buffer(int num_bits, int fd, uint8_t *buf)
177 {
178  int num_bytes;
179 
180  for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--) {
181  /* reverse the order of bytes as they are read sequentially from file */
182  if (read(fd, buf + num_bytes - 1, 1) < 0)
183  return ERROR_XSVF_EOF;
184  }
185 
186  return ERROR_OK;
187 }
188 
189 COMMAND_HANDLER(handle_xsvf_command)
190 {
191  uint8_t *dr_out_buf = NULL; /* from host to device (TDI) */
192  uint8_t *dr_in_buf = NULL; /* from device to host (TDO) */
193  uint8_t *dr_in_mask = NULL;
194 
195  int xsdrsize = 0;
196  int xruntest = 0; /* number of TCK cycles OR *microseconds */
197  int xrepeat = 0; /* number of retries */
198 
199  tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial
200  *xendir to be TAP_IDLE */
201  tap_state_t xenddr = TAP_IDLE;
202 
203  uint8_t opcode;
204  uint8_t uc = 0;
205  long file_offset = 0;
206 
207  int loop_count = 0;
208  tap_state_t loop_state = TAP_IDLE;
209  int loop_clocks = 0;
210  int loop_usecs = 0;
211 
212  int do_abort = 0;
213  int unsupported = 0;
214  int tdo_mismatch = 0;
215  int result;
216  int verbose = 1;
217 
218  bool collecting_path = false;
220  unsigned pathlen = 0;
221 
222  /* a flag telling whether to clock TCK during waits,
223  * or simply sleep, controlled by virt2
224  */
225  int runtest_requires_tck = 0;
226 
227  /* use NULL to indicate a "plain" xsvf file which accounts for
228  * additional devices in the scan chain, otherwise the device
229  * that should be affected
230  */
231  struct jtag_tap *tap = NULL;
232 
233  if (CMD_ARGC < 2)
235 
236  /* we mess with CMD_ARGV starting point below, snapshot filename here */
237  const char *filename = CMD_ARGV[1];
238 
239  if (strcmp(CMD_ARGV[0], "plain") != 0) {
240  tap = jtag_tap_by_string(CMD_ARGV[0]);
241  if (!tap) {
242  command_print(CMD, "Tap: %s unknown", CMD_ARGV[0]);
243  return ERROR_FAIL;
244  }
245  }
246 
247  xsvf_fd = open(filename, O_RDONLY);
248  if (xsvf_fd < 0) {
249  command_print(CMD, "file \"%s\" not found", filename);
250  return ERROR_FAIL;
251  }
252 
253  /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as
254  *usecs */
255  if ((CMD_ARGC > 2) && (strcmp(CMD_ARGV[2], "virt2") == 0)) {
256  runtest_requires_tck = 1;
257  --CMD_ARGC;
258  ++CMD_ARGV;
259  }
260 
261  if ((CMD_ARGC > 2) && (strcmp(CMD_ARGV[2], "quiet") == 0))
262  verbose = 0;
263 
264  LOG_WARNING("XSVF support in OpenOCD is limited. Consider using SVF instead");
265  LOG_USER("xsvf processing file: \"%s\"", filename);
266 
267  while (read(xsvf_fd, &opcode, 1) > 0) {
268  /* record the position of this opcode within the file */
269  file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
270 
271  /* maybe collect another state for a pathmove();
272  * or terminate a path.
273  */
274  if (collecting_path) {
275  tap_state_t mystate;
276 
277  switch (opcode) {
278  case XCOMMENT:
279  /* ignore/show comments between XSTATE ops */
280  break;
281  case XSTATE:
282  /* try to collect another transition */
283  if (pathlen == XSTATE_MAX_PATH) {
284  LOG_ERROR("XSVF: path too long");
285  do_abort = 1;
286  break;
287  }
288 
289  if (read(xsvf_fd, &uc, 1) < 0) {
290  do_abort = 1;
291  break;
292  }
293 
294  mystate = xsvf_to_tap(uc);
295  path[pathlen++] = mystate;
296 
297  LOG_DEBUG("XSTATE 0x%02X %s", uc,
298  tap_state_name(mystate));
299 
300  /* If path is incomplete, collect more */
301  if (!svf_tap_state_is_stable(mystate))
302  continue;
303 
304  /* Else execute the path transitions we've
305  * collected so far.
306  *
307  * NOTE: Punting on the saved path is not
308  * strictly correct, but we must to do this
309  * unless jtag_add_pathmove() stops rejecting
310  * paths containing RESET. This is probably
311  * harmless, since there aren't many options
312  * for going from a stable state to reset;
313  * at the worst, we may issue extra clocks
314  * once we get to RESET.
315  */
316  if (mystate == TAP_RESET) {
317  LOG_WARNING("XSVF: dodgey RESET");
318  path[0] = mystate;
319  }
320 
321  /* FALL THROUGH */
322  default:
323  /* Execute the path we collected
324  *
325  * NOTE: OpenOCD requires something that XSVF
326  * doesn't: the last TAP state in the path
327  * must be stable. In practice, tools that
328  * create XSVF seem to follow that rule too.
329  */
330  collecting_path = false;
331 
332  if (path[0] == TAP_RESET)
333  jtag_add_tlr();
334  else
335  jtag_add_pathmove(pathlen, path);
336 
337  result = jtag_execute_queue();
338  if (result != ERROR_OK) {
339  LOG_ERROR("XSVF: pathmove error %d", result);
340  do_abort = 1;
341  break;
342  }
343  continue;
344  }
345  }
346 
347  switch (opcode) {
348  case XCOMPLETE:
349  LOG_DEBUG("XCOMPLETE");
350 
351  result = jtag_execute_queue();
352  if (result != ERROR_OK) {
353  tdo_mismatch = 1;
354  break;
355  }
356  break;
357 
358  case XTDOMASK:
359  LOG_DEBUG("XTDOMASK");
360  if (dr_in_mask &&
361  (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
362  do_abort = 1;
363  break;
364 
365  case XRUNTEST:
366  {
367  uint8_t xruntest_buf[4];
368 
369  if (read(xsvf_fd, xruntest_buf, 4) < 0) {
370  do_abort = 1;
371  break;
372  }
373 
374  xruntest = be_to_h_u32(xruntest_buf);
375  LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
376  }
377  break;
378 
379  case XREPEAT:
380  {
381  uint8_t myrepeat;
382 
383  if (read(xsvf_fd, &myrepeat, 1) < 0)
384  do_abort = 1;
385  else {
386  xrepeat = myrepeat;
387  LOG_DEBUG("XREPEAT %d", xrepeat);
388  }
389  }
390  break;
391 
392  case XSDRSIZE:
393  {
394  uint8_t xsdrsize_buf[4];
395 
396  if (read(xsvf_fd, xsdrsize_buf, 4) < 0) {
397  do_abort = 1;
398  break;
399  }
400 
401  xsdrsize = be_to_h_u32(xsdrsize_buf);
402  LOG_DEBUG("XSDRSIZE %d", xsdrsize);
403 
404  free(dr_out_buf);
405  free(dr_in_buf);
406  free(dr_in_mask);
407 
408  dr_out_buf = malloc((xsdrsize + 7) / 8);
409  dr_in_buf = malloc((xsdrsize + 7) / 8);
410  dr_in_mask = malloc((xsdrsize + 7) / 8);
411  }
412  break;
413 
414  case XSDR: /* these two are identical except for the dr_in_buf */
415  case XSDRTDO:
416  {
417  int limit = xrepeat;
418  int matched = 0;
419  int attempt;
420 
421  const char *op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
422 
423  if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK) {
424  do_abort = 1;
425  break;
426  }
427 
428  if (opcode == XSDRTDO) {
429  if (xsvf_read_buffer(xsdrsize, xsvf_fd,
430  dr_in_buf) != ERROR_OK) {
431  do_abort = 1;
432  break;
433  }
434  }
435 
436  if (limit < 1)
437  limit = 1;
438 
439  LOG_DEBUG("%s %d", op_name, xsdrsize);
440 
441  for (attempt = 0; attempt < limit; ++attempt) {
442  struct scan_field field;
443 
444  if (attempt > 0) {
445  /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
446  * illustrated in pseudo code at end of this file. We start from state
447  * DRPAUSE:
448  * go to Exit2-DR
449  * go to Shift-DR
450  * go to Exit1-DR
451  * go to Update-DR
452  * go to Run-Test/Idle
453  *
454  * This sequence should be harmless for other devices, and it
455  * will be skipped entirely if xrepeat is set to zero.
456  */
457 
458  static tap_state_t exception_path[] = {
459  TAP_DREXIT2,
460  TAP_DRSHIFT,
461  TAP_DREXIT1,
462  TAP_DRUPDATE,
463  TAP_IDLE,
464  };
465 
466  jtag_add_pathmove(ARRAY_SIZE(exception_path), exception_path);
467 
468  if (verbose)
469  LOG_USER("%s mismatch, xsdrsize=%d retry=%d",
470  op_name,
471  xsdrsize,
472  attempt);
473  }
474 
475  field.num_bits = xsdrsize;
476  field.out_value = dr_out_buf;
477  field.in_value = calloc(DIV_ROUND_UP(field.num_bits, 8), 1);
478 
479  if (!tap)
481  field.out_value,
482  field.in_value,
483  TAP_DRPAUSE);
484  else
485  jtag_add_dr_scan(tap, 1, &field, TAP_DRPAUSE);
486 
487  jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
488 
489  free(field.in_value);
490 
491  /* LOG_DEBUG("FLUSHING QUEUE"); */
492  result = jtag_execute_queue();
493  if (result == ERROR_OK) {
494  matched = 1;
495  break;
496  }
497  }
498 
499  if (!matched) {
500  LOG_USER("%s mismatch", op_name);
501  tdo_mismatch = 1;
502  break;
503  }
504 
505  /* See page 19 of XSVF spec regarding opcode "XSDR" */
506  if (xruntest) {
507  result = svf_add_statemove(TAP_IDLE);
508  if (result != ERROR_OK)
509  return result;
510 
511  if (runtest_requires_tck)
512  jtag_add_clocks(xruntest);
513  else
514  jtag_add_sleep(xruntest);
515  } else if (xendir != TAP_DRPAUSE) {
516  /* we are already in TAP_DRPAUSE */
517  result = svf_add_statemove(xenddr);
518  if (result != ERROR_OK)
519  return result;
520  }
521  }
522  break;
523 
524  case XSETSDRMASKS:
525  LOG_ERROR("unsupported XSETSDRMASKS");
526  unsupported = 1;
527  break;
528 
529  case XSDRINC:
530  LOG_ERROR("unsupported XSDRINC");
531  unsupported = 1;
532  break;
533 
534  case XSDRB:
535  LOG_ERROR("unsupported XSDRB");
536  unsupported = 1;
537  break;
538 
539  case XSDRC:
540  LOG_ERROR("unsupported XSDRC");
541  unsupported = 1;
542  break;
543 
544  case XSDRE:
545  LOG_ERROR("unsupported XSDRE");
546  unsupported = 1;
547  break;
548 
549  case XSDRTDOB:
550  LOG_ERROR("unsupported XSDRTDOB");
551  unsupported = 1;
552  break;
553 
554  case XSDRTDOC:
555  LOG_ERROR("unsupported XSDRTDOC");
556  unsupported = 1;
557  break;
558 
559  case XSDRTDOE:
560  LOG_ERROR("unsupported XSDRTDOE");
561  unsupported = 1;
562  break;
563 
564  case XSTATE:
565  {
566  tap_state_t mystate;
567 
568  if (read(xsvf_fd, &uc, 1) < 0) {
569  do_abort = 1;
570  break;
571  }
572 
573  mystate = xsvf_to_tap(uc);
574 
575  LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate));
576 
577  if (mystate == TAP_INVALID) {
578  LOG_ERROR("XSVF: bad XSTATE %02x", uc);
579  do_abort = 1;
580  break;
581  }
582 
583  /* NOTE: the current state is SVF-stable! */
584 
585  /* no change == NOP */
586  if (mystate == cmd_queue_cur_state
587  && mystate != TAP_RESET)
588  break;
589 
590  /* Hand off to SVF? */
591  if (svf_tap_state_is_stable(mystate)) {
592  result = svf_add_statemove(mystate);
593  if (result != ERROR_OK)
594  unsupported = 1;
595  break;
596  }
597 
598  /*
599  * A sequence of XSTATE transitions, each TAP
600  * state adjacent to the previous one. Start
601  * collecting them.
602  */
603  collecting_path = true;
604  pathlen = 1;
605  path[0] = mystate;
606  }
607  break;
608 
609  case XENDIR:
610 
611  if (read(xsvf_fd, &uc, 1) < 0) {
612  do_abort = 1;
613  break;
614  }
615 
616  /* see page 22 of XSVF spec */
617  if (uc == 0)
618  xendir = TAP_IDLE;
619  else if (uc == 1)
620  xendir = TAP_IRPAUSE;
621  else {
622  LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
623  unsupported = 1;
624  break;
625  }
626 
627  LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
628  break;
629 
630  case XENDDR:
631 
632  if (read(xsvf_fd, &uc, 1) < 0) {
633  do_abort = 1;
634  break;
635  }
636 
637  /* see page 22 of XSVF spec */
638  if (uc == 0)
639  xenddr = TAP_IDLE;
640  else if (uc == 1)
641  xenddr = TAP_DRPAUSE;
642  else {
643  LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
644  unsupported = 1;
645  break;
646  }
647 
648  LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
649  break;
650 
651  case XSIR:
652  case XSIR2:
653  {
654  uint8_t short_buf[2];
655  uint8_t *ir_buf;
656  int bitcount;
657  tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
658 
659  if (opcode == XSIR) {
660  /* one byte bitcount */
661  if (read(xsvf_fd, short_buf, 1) < 0) {
662  do_abort = 1;
663  break;
664  }
665  bitcount = short_buf[0];
666  LOG_DEBUG("XSIR %d", bitcount);
667  } else {
668  if (read(xsvf_fd, short_buf, 2) < 0) {
669  do_abort = 1;
670  break;
671  }
672  bitcount = be_to_h_u16(short_buf);
673  LOG_DEBUG("XSIR2 %d", bitcount);
674  }
675 
676  ir_buf = malloc((bitcount + 7) / 8);
677 
678  if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
679  do_abort = 1;
680  else {
681  struct scan_field field;
682 
683  field.num_bits = bitcount;
684  field.out_value = ir_buf;
685 
686  field.in_value = NULL;
687 
688  if (!tap)
690  field.out_value, field.in_value, my_end_state);
691  else
692  jtag_add_ir_scan(tap, &field, my_end_state);
693 
694  if (xruntest) {
695  if (runtest_requires_tck)
696  jtag_add_clocks(xruntest);
697  else
698  jtag_add_sleep(xruntest);
699  }
700 
701  /* Note that an -irmask of non-zero in your config file
702  * can cause this to fail. Setting -irmask to zero cand work
703  * around the problem.
704  */
705 
706  /* LOG_DEBUG("FLUSHING QUEUE"); */
707  result = jtag_execute_queue();
708  if (result != ERROR_OK)
709  tdo_mismatch = 1;
710  }
711  free(ir_buf);
712  }
713  break;
714 
715  case XCOMMENT:
716  {
717  unsigned int ndx = 0;
718  char comment[128];
719 
720  do {
721  if (read(xsvf_fd, &uc, 1) < 0) {
722  do_abort = 1;
723  break;
724  }
725 
726  if (ndx < sizeof(comment)-1)
727  comment[ndx++] = uc;
728 
729  } while (uc != 0);
730 
731  comment[sizeof(comment)-1] = 0; /* regardless, terminate */
732  if (verbose)
733  LOG_USER("# %s", comment);
734  }
735  break;
736 
737  case XWAIT:
738  {
739  /* expected in stream:
740  XWAIT <uint8_t wait_state> <uint8_t end_state> <uint32_t usecs>
741  */
742 
743  uint8_t wait_local;
744  uint8_t end;
745  uint8_t delay_buf[4];
746 
747  tap_state_t wait_state;
748  tap_state_t end_state;
749  int delay;
750 
751  if (read(xsvf_fd, &wait_local, 1) < 0
752  || read(xsvf_fd, &end, 1) < 0
753  || read(xsvf_fd, delay_buf, 4) < 0) {
754  do_abort = 1;
755  break;
756  }
757 
758  wait_state = xsvf_to_tap(wait_local);
759  end_state = xsvf_to_tap(end);
760  delay = be_to_h_u32(delay_buf);
761 
762  LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(
763  wait_state), tap_state_name(end_state), delay);
764 
765  if (runtest_requires_tck && wait_state == TAP_IDLE)
766  jtag_add_runtest(delay, end_state);
767  else {
768  /* FIXME handle statemove errors ... */
769  result = svf_add_statemove(wait_state);
770  if (result != ERROR_OK)
771  return result;
772  jtag_add_sleep(delay);
773  result = svf_add_statemove(end_state);
774  if (result != ERROR_OK)
775  return result;
776  }
777  }
778  break;
779 
780  case XWAITSTATE:
781  {
782  /* expected in stream:
783  * XWAITSTATE <uint8_t wait_state> <uint8_t end_state> <uint32_t clock_count>
784  * <uint32_t usecs>
785  */
786 
787  uint8_t clock_buf[4];
788  uint8_t usecs_buf[4];
789  uint8_t wait_local;
790  uint8_t end;
791  tap_state_t wait_state;
792  tap_state_t end_state;
793  int clock_count;
794  int usecs;
795 
796  if (read(xsvf_fd, &wait_local, 1) < 0
797  || read(xsvf_fd, &end, 1) < 0
798  || read(xsvf_fd, clock_buf, 4) < 0
799  || read(xsvf_fd, usecs_buf, 4) < 0) {
800  do_abort = 1;
801  break;
802  }
803 
804  wait_state = xsvf_to_tap(wait_local);
805  end_state = xsvf_to_tap(end);
806 
807  clock_count = be_to_h_u32(clock_buf);
808  usecs = be_to_h_u32(usecs_buf);
809 
810  LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
811  tap_state_name(wait_state),
812  tap_state_name(end_state),
813  clock_count, usecs);
814 
815  /* the following states are 'stable', meaning that they have a transition
816  * in the state diagram back to themselves. This is necessary because we will
817  * be issuing a number of clocks in this state. This set of allowed states is also
818  * determined by the SVF RUNTEST command's allowed states.
819  */
820  if (!svf_tap_state_is_stable(wait_state)) {
821  LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"",
822  tap_state_name(wait_state));
823  unsupported = 1;
824  /* REVISIT "break" so we won't run? */
825  }
826 
827  /* FIXME handle statemove errors ... */
828  result = svf_add_statemove(wait_state);
829  if (result != ERROR_OK)
830  return result;
831 
833  jtag_add_sleep(usecs);
834 
835  result = svf_add_statemove(end_state);
836  if (result != ERROR_OK)
837  return result;
838  }
839  break;
840 
841  case LCOUNT:
842  {
843  /* expected in stream:
844  * LCOUNT <uint32_t loop_count>
845  */
846  uint8_t count_buf[4];
847 
848  if (read(xsvf_fd, count_buf, 4) < 0) {
849  do_abort = 1;
850  break;
851  }
852 
853  loop_count = be_to_h_u32(count_buf);
854  LOG_DEBUG("LCOUNT %d", loop_count);
855  }
856  break;
857 
858  case LDELAY:
859  {
860  /* expected in stream:
861  * LDELAY <uint8_t wait_state> <uint32_t clock_count> <uint32_t usecs_to_sleep>
862  */
863  uint8_t state;
864  uint8_t clock_buf[4];
865  uint8_t usecs_buf[4];
866 
867  if (read(xsvf_fd, &state, 1) < 0
868  || read(xsvf_fd, clock_buf, 4) < 0
869  || read(xsvf_fd, usecs_buf, 4) < 0) {
870  do_abort = 1;
871  break;
872  }
873 
874  /* NOTE: loop_state must be stable! */
875  loop_state = xsvf_to_tap(state);
876  loop_clocks = be_to_h_u32(clock_buf);
877  loop_usecs = be_to_h_u32(usecs_buf);
878 
879  LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(
880  loop_state), loop_clocks, loop_usecs);
881  }
882  break;
883 
884  /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
885  * comes with clocks !AND! sleep requirements.
886  */
887  case LSDR:
888  {
889  int limit = loop_count;
890  int matched = 0;
891  int attempt;
892 
893  LOG_DEBUG("LSDR");
894 
895  if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
896  || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK) {
897  do_abort = 1;
898  break;
899  }
900 
901  if (limit < 1)
902  limit = 1;
903 
904  for (attempt = 0; attempt < limit; ++attempt) {
905  struct scan_field field;
906 
907  result = svf_add_statemove(loop_state);
908  if (result != ERROR_OK) {
909  free(dr_in_mask);
910  return result;
911  }
912  jtag_add_clocks(loop_clocks);
913  jtag_add_sleep(loop_usecs);
914 
915  field.num_bits = xsdrsize;
916  field.out_value = dr_out_buf;
917  field.in_value = calloc(DIV_ROUND_UP(field.num_bits, 8), 1);
918 
919  if (attempt > 0 && verbose)
920  LOG_USER("LSDR retry %d", attempt);
921 
922  if (!tap)
924  field.out_value,
925  field.in_value,
926  TAP_DRPAUSE);
927  else
928  jtag_add_dr_scan(tap, 1, &field, TAP_DRPAUSE);
929 
930  jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
931 
932  free(field.in_value);
933 
934 
935  /* LOG_DEBUG("FLUSHING QUEUE"); */
936  result = jtag_execute_queue();
937  if (result == ERROR_OK) {
938  matched = 1;
939  break;
940  }
941  }
942 
943  if (!matched) {
944  LOG_USER("LSDR mismatch");
945  tdo_mismatch = 1;
946  break;
947  }
948  }
949  break;
950 
951  case XTRST:
952  {
953  uint8_t trst_mode;
954 
955  if (read(xsvf_fd, &trst_mode, 1) < 0) {
956  do_abort = 1;
957  break;
958  }
959 
960  switch (trst_mode) {
961  case XTRST_ON:
962  jtag_add_reset(1, 0);
963  break;
964  case XTRST_OFF:
965  case XTRST_Z:
966  jtag_add_reset(0, 0);
967  break;
968  case XTRST_ABSENT:
969  break;
970  default:
971  LOG_ERROR("XTRST mode argument (0x%02X) out of range", trst_mode);
972  do_abort = 1;
973  }
974  }
975  break;
976 
977  default:
978  LOG_ERROR("unknown xsvf command (0x%02X)", uc);
979  unsupported = 1;
980  }
981 
982  if (do_abort || unsupported || tdo_mismatch) {
983  LOG_DEBUG("xsvf failed, setting taps to reasonable state");
984 
985  /* upon error, return the TAPs to a reasonable state */
986  result = svf_add_statemove(TAP_IDLE);
987  if (result != ERROR_OK)
988  return result;
989  result = jtag_execute_queue();
990  if (result != ERROR_OK)
991  return result;
992  break;
993  }
994  }
995 
996  if (tdo_mismatch) {
998  "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
999  file_offset);
1000 
1001  return ERROR_FAIL;
1002  }
1003 
1004  if (unsupported) {
1005  off_t offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
1007  "unsupported xsvf command (0x%02X) at offset %jd, aborting",
1008  uc, (intmax_t)offset);
1009  return ERROR_FAIL;
1010  }
1011 
1012  if (do_abort) {
1013  command_print(CMD, "premature end of xsvf file detected, aborting");
1014  return ERROR_FAIL;
1015  }
1016 
1017  free(dr_out_buf);
1018  free(dr_in_buf);
1019  free(dr_in_mask);
1020 
1021  close(xsvf_fd);
1022 
1023  command_print(CMD, "XSVF file programmed successfully");
1024 
1025  return ERROR_OK;
1026 }
1027 
1028 static const struct command_registration xsvf_command_handlers[] = {
1029  {
1030  .name = "xsvf",
1031  .handler = handle_xsvf_command,
1032  .mode = COMMAND_EXEC,
1033  .help = "Runs a XSVF file. If 'virt2' is given, xruntest "
1034  "counts are interpreted as TCK cycles rather than "
1035  "as microseconds. Without the 'quiet' option, all "
1036  "comments, retries, and mismatches will be reported.",
1037  .usage = "(tapname|'plain') filename ['virt2'] ['quiet']",
1038  },
1040 };
1041 
1043 {
1044  return register_commands(cmd_ctx, NULL, xsvf_command_handlers);
1045 }
1046 
1047 /*
1048 
1049 PSEUDO-Code from Xilinx Appnote XAPP067.pdf :
1050 
1051 the following pseudo code clarifies the intent of the xrepeat support.The
1052 flow given is for the entire processing of an SVF file, not an XSVF file.
1053 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1054 
1055 "Pseudo-Code Algorithm for SVF-Based ISP"
1056 
1057 1. Go to Test-Logic-Reset state
1058 2. Go to Run-Test Idle state
1059 3. Read SVF record
1060 
1061 4. if SIR record then
1062 go to Shift-IR state
1063 Scan in <TDI value>
1064 
1065 5. else if SDR record then
1066 set <repeat count> to 0
1067 store <TDI value> as <current TDI value>
1068 store <TDO value> as <current TDO value>
1069 6. go to Shift-DR state
1070 scan in <current TDI value>
1071 if < current TDO value > is specified then
1072 if < current TDO value > does not equal <actual TDO value> then
1073 if < repeat count > > 32 then
1074 LOG ERROR
1075 go to Run-Test Idle state
1076 go to Step 3
1077 end if
1078 go to Pause-DR
1079 go to Exit2-DR
1080 go to Shift-DR
1081 go to Exit1-DR
1082 go to Update-DR
1083 go to Run-Test/Idle
1084 increment <repeat count> by 1
1085 pause <current pause time> microseconds
1086 go to Step 6)
1087 end if
1088 else
1089  go to Run-Test Idle state
1090  go to Step 3
1091  endif
1092  else if RUNTEST record then
1093  pause tester for < TCK value > microseconds
1094  store <TCK value> as <current pause time>
1095  end if
1096 
1097 */
void command_print(struct command_invocation *cmd, const char *format,...)
Definition: command.c:473
#define CMD
Use this macro to access the command being handled, rather than accessing the variable directly.
Definition: command.h:140
#define CMD_ARGV
Use this macro to access the arguments for the command being handled, rather than accessing the varia...
Definition: command.h:155
#define ERROR_COMMAND_SYNTAX_ERROR
Definition: command.h:385
#define CMD_ARGC
Use this macro to access the number of arguments for the command being handled, rather than accessing...
Definition: command.h:150
#define COMMAND_REGISTRATION_DONE
Use this as the last entry in an array of command_registration records.
Definition: command.h:247
static int register_commands(struct command_context *cmd_ctx, const char *cmd_prefix, const struct command_registration *cmds)
Register one or more commands in the specified context, as children of parent (or top-level commends,...
Definition: command.h:268
@ COMMAND_EXEC
Definition: command.h:40
static int clock_count
Definition: dummy.c:21
const char * tap_state_name(tap_state_t state)
Function tap_state_name Returns a string suitable for display representing the JTAG tap_state.
Definition: interface.c:344
struct jtag_tap * jtag_tap_by_string(const char *s)
Definition: jtag/core.c:237
void jtag_add_plain_dr_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits, tap_state_t state)
Scan out the bits in ir scan mode.
Definition: jtag/core.c:465
void jtag_add_pathmove(int num_states, const tap_state_t *path)
Application code must assume that interfaces will implement transitions between states with different...
Definition: jtag/core.c:517
void jtag_add_reset(int req_tlr_or_trst, int req_srst)
A reset of the TAP state machine can be requested.
Definition: jtag/core.c:758
void jtag_add_plain_ir_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits, tap_state_t state)
Scan out the bits in ir scan mode.
Definition: jtag/core.c:392
void jtag_add_clocks(int num_cycles)
Function jtag_add_clocks first checks that the state in which the clocks are to be issued is stable,...
Definition: jtag/core.c:599
int jtag_execute_queue(void)
For software FIFO implementations, the queued commands can be executed during this call or earlier.
Definition: jtag/core.c:1037
tap_state_t cmd_queue_cur_state
The current TAP state of the pending JTAG command queue.
Definition: jtag/core.c:88
void jtag_add_tlr(void)
Run a TAP_RESET reset where the end state is TAP_RESET, regardless of the start state.
Definition: jtag/core.c:478
void jtag_add_sleep(uint32_t us)
Definition: jtag/core.c:870
void jtag_check_value_mask(struct scan_field *field, uint8_t *value, uint8_t *mask)
Execute jtag queue and check value with an optional mask.
Definition: jtag/core.c:917
void jtag_add_ir_scan(struct jtag_tap *active, struct scan_field *in_fields, tap_state_t state)
Generate an IR SCAN with a list of scan fields with one entry for each enabled TAP.
Definition: jtag/core.c:374
void jtag_add_runtest(int num_cycles, tap_state_t state)
Goes to TAP_IDLE (if we're not already there), cycle precisely num_cycles in the TAP_IDLE state,...
Definition: jtag/core.c:592
void jtag_add_dr_scan(struct jtag_tap *active, int in_num_fields, const struct scan_field *in_fields, tap_state_t state)
Generate a DR SCAN using the fields passed to the function.
Definition: jtag/core.c:451
The JTAG interface can be implemented with a software or hardware fifo.
@ TAP_IRCAPTURE
Definition: jtag.h:54
@ TAP_RESET
Definition: jtag.h:55
@ TAP_DRCAPTURE
Definition: jtag.h:46
@ TAP_DRSELECT
Definition: jtag.h:47
@ TAP_DREXIT1
Definition: jtag.h:41
@ TAP_IREXIT1
Definition: jtag.h:49
@ TAP_DRPAUSE
Definition: jtag.h:43
@ TAP_IRSELECT
Definition: jtag.h:44
@ TAP_IRUPDATE
Definition: jtag.h:53
@ TAP_IREXIT2
Definition: jtag.h:48
@ TAP_IRSHIFT
Definition: jtag.h:50
@ TAP_DREXIT2
Definition: jtag.h:40
@ TAP_IDLE
Definition: jtag.h:52
@ TAP_DRSHIFT
Definition: jtag.h:42
@ TAP_IRPAUSE
Definition: jtag.h:51
@ TAP_DRUPDATE
Definition: jtag.h:45
@ TAP_INVALID
Definition: jtag.h:37
enum tap_state tap_state_t
Defines JTAG Test Access Port states.
#define LOG_USER(expr ...)
Definition: log.h:126
#define LOG_WARNING(expr ...)
Definition: log.h:120
#define ERROR_FAIL
Definition: log.h:161
#define LOG_ERROR(expr ...)
Definition: log.h:123
#define LOG_DEBUG(expr ...)
Definition: log.h:109
#define ERROR_OK
Definition: log.h:155
const char * name
Definition: command.h:229
Definition: jtag.h:100
This structure defines a single scan field in the scan.
Definition: jtag.h:86
int num_bits
The number of bits this field specifies.
Definition: jtag.h:88
uint8_t * in_value
A pointer to a 32-bit memory location for data scanned out.
Definition: jtag.h:92
const uint8_t * out_value
A pointer to value to be scanned into the device.
Definition: jtag.h:90
bool svf_tap_state_is_stable(tap_state_t state)
svf_tap_state_is_stable() returns true for stable non-SHIFT states
Definition: svf.c:732
trst_mode
Definition: svf.c:61
int svf_add_statemove(tap_state_t state_to)
svf_add_statemove() moves from the current state to goal_state.
Definition: svf.c:309
#define ARRAY_SIZE(x)
Compute the number of elements of a variable length array.
Definition: types.h:57
#define DIV_ROUND_UP(m, n)
Rounds m up to the nearest multiple of n using division.
Definition: types.h:79
static uint32_t be_to_h_u32(const uint8_t *buf)
Definition: types.h:139
static uint16_t be_to_h_u16(const uint8_t *buf)
Definition: types.h:149
#define NULL
Definition: usb.h:16
uint8_t offset[4]
Definition: vdebug.c:9
uint8_t state[4]
Definition: vdebug.c:21
#define XSV_DREXIT1
Definition: xsvf.c:92
#define XTRST
Definition: xsvf.c:84
#define XSDRC
Definition: xsvf.c:47
#define XSV_DRPAUSE
Definition: xsvf.c:93
#define XSDRE
Definition: xsvf.c:48
static int xsvf_read_buffer(int num_bits, int fd, uint8_t *buf)
Definition: xsvf.c:176
int xsvf_register_commands(struct command_context *cmd_ctx)
Definition: xsvf.c:1042
#define XTRST_Z
Definition: xsvf.c:107
#define XREPEAT
Definition: xsvf.c:41
#define XSV_IDLE
Definition: xsvf.c:88
#define XWAITSTATE
Definition: xsvf.c:64
COMMAND_HANDLER(handle_xsvf_command)
Definition: xsvf.c:189
#define XSV_IREXIT2
Definition: xsvf.c:101
#define XSV_IRUPDATE
Definition: xsvf.c:102
#define XSIR
Definition: xsvf.c:38
#define XSDRINC
Definition: xsvf.c:45
#define XSV_DREXIT2
Definition: xsvf.c:94
#define XSETSDRMASKS
Definition: xsvf.c:44
#define XSDRTDO
Definition: xsvf.c:43
#define XSV_IREXIT1
Definition: xsvf.c:99
#define XSV_IRCAPTURE
Definition: xsvf.c:97
#define XTRST_ABSENT
Definition: xsvf.c:108
#define XSDRTDOE
Definition: xsvf.c:51
#define XSDRSIZE
Definition: xsvf.c:42
#define XWAIT
Definition: xsvf.c:57
#define XTRST_OFF
Definition: xsvf.c:106
#define LSDR
Definition: xsvf.c:83
#define XSDR
Definition: xsvf.c:39
static int xsvf_fd
Definition: xsvf.c:112
#define XSTATE_MAX_PATH
Definition: xsvf.c:110
#define XSV_IRPAUSE
Definition: xsvf.c:100
#define XSV_DRCAPTURE
Definition: xsvf.c:90
#define XENDIR
Definition: xsvf.c:53
#define XSV_IRSELECT
Definition: xsvf.c:96
#define LCOUNT
Definition: xsvf.c:81
#define XSV_DRSELECT
Definition: xsvf.c:89
#define XSIR2
Definition: xsvf.c:55
#define XENDDR
Definition: xsvf.c:54
#define XSDRB
Definition: xsvf.c:46
#define XRUNTEST
Definition: xsvf.c:40
#define XSDRTDOC
Definition: xsvf.c:50
#define XCOMPLETE
Definition: xsvf.c:36
#define XSV_RESET
Definition: xsvf.c:87
#define XSV_DRUPDATE
Definition: xsvf.c:95
#define XTDOMASK
Definition: xsvf.c:37
#define XSV_DRSHIFT
Definition: xsvf.c:91
static tap_state_t xsvf_to_tap(int xsvf_state)
Definition: xsvf.c:115
static const struct command_registration xsvf_command_handlers[]
Definition: xsvf.c:1028
#define XTRST_ON
Definition: xsvf.c:105
#define XSTATE
Definition: xsvf.c:52
#define XCOMMENT
Definition: xsvf.c:56
#define LDELAY
Definition: xsvf.c:82
#define XSV_IRSHIFT
Definition: xsvf.c:98
#define XSDRTDOB
Definition: xsvf.c:49
#define ERROR_XSVF_EOF
Definition: xsvf.h:15