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 "enum tap_state" */
115 static enum tap_state xsvf_to_tap(int xsvf_state)
116 {
117  enum tap_state 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  enum tap_state xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial
200  *xendir to be TAP_IDLE */
201  enum tap_state 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  enum tap_state 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;
219  enum tap_state path[XSTATE_MAX_PATH];
220  unsigned int 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  enum tap_state 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  result = jtag_execute_queue();
351  if (result != ERROR_OK)
352  tdo_mismatch = 1;
353  break;
354 
355  case XTDOMASK:
356  LOG_DEBUG("XTDOMASK");
357  if (dr_in_mask &&
358  (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
359  do_abort = 1;
360  break;
361 
362  case XRUNTEST:
363  {
364  uint8_t xruntest_buf[4];
365 
366  if (read(xsvf_fd, xruntest_buf, 4) < 0) {
367  do_abort = 1;
368  break;
369  }
370 
371  xruntest = be_to_h_u32(xruntest_buf);
372  LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
373  }
374  break;
375 
376  case XREPEAT:
377  {
378  uint8_t myrepeat;
379 
380  if (read(xsvf_fd, &myrepeat, 1) < 0) {
381  do_abort = 1;
382  } else {
383  xrepeat = myrepeat;
384  LOG_DEBUG("XREPEAT %d", xrepeat);
385  }
386  }
387  break;
388 
389  case XSDRSIZE:
390  {
391  uint8_t xsdrsize_buf[4];
392 
393  if (read(xsvf_fd, xsdrsize_buf, 4) < 0) {
394  do_abort = 1;
395  break;
396  }
397 
398  xsdrsize = be_to_h_u32(xsdrsize_buf);
399  LOG_DEBUG("XSDRSIZE %d", xsdrsize);
400 
401  free(dr_out_buf);
402  free(dr_in_buf);
403  free(dr_in_mask);
404 
405  dr_out_buf = malloc((xsdrsize + 7) / 8);
406  dr_in_buf = malloc((xsdrsize + 7) / 8);
407  dr_in_mask = malloc((xsdrsize + 7) / 8);
408  }
409  break;
410 
411  case XSDR: /* these two are identical except for the dr_in_buf */
412  case XSDRTDO:
413  {
414  int limit = xrepeat;
415  int matched = 0;
416  int attempt;
417 
418  const char *op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
419 
420  if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK) {
421  do_abort = 1;
422  break;
423  }
424 
425  if (opcode == XSDRTDO) {
426  if (xsvf_read_buffer(xsdrsize, xsvf_fd,
427  dr_in_buf) != ERROR_OK) {
428  do_abort = 1;
429  break;
430  }
431  }
432 
433  if (limit < 1)
434  limit = 1;
435 
436  LOG_DEBUG("%s %d", op_name, xsdrsize);
437 
438  for (attempt = 0; attempt < limit; ++attempt) {
439  struct scan_field field;
440 
441  if (attempt > 0) {
442  /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
443  * illustrated in pseudo code at end of this file. We start from state
444  * DRPAUSE:
445  * go to Exit2-DR
446  * go to Shift-DR
447  * go to Exit1-DR
448  * go to Update-DR
449  * go to Run-Test/Idle
450  *
451  * This sequence should be harmless for other devices, and it
452  * will be skipped entirely if xrepeat is set to zero.
453  */
454 
455  static enum tap_state exception_path[] = {
456  TAP_DREXIT2,
457  TAP_DRSHIFT,
458  TAP_DREXIT1,
459  TAP_DRUPDATE,
460  TAP_IDLE,
461  };
462 
463  jtag_add_pathmove(ARRAY_SIZE(exception_path), exception_path);
464 
465  if (verbose)
466  LOG_USER("%s mismatch, xsdrsize=%d retry=%d",
467  op_name,
468  xsdrsize,
469  attempt);
470  }
471 
472  field.num_bits = xsdrsize;
473  field.out_value = dr_out_buf;
474  field.in_value = calloc(DIV_ROUND_UP(field.num_bits, 8), 1);
475 
476  if (!tap)
478  field.out_value,
479  field.in_value,
480  TAP_DRPAUSE);
481  else
482  jtag_add_dr_scan(tap, 1, &field, TAP_DRPAUSE);
483 
484  jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
485 
486  free(field.in_value);
487 
488  /* LOG_DEBUG("FLUSHING QUEUE"); */
489  result = jtag_execute_queue();
490  if (result == ERROR_OK) {
491  matched = 1;
492  break;
493  }
494  }
495 
496  if (!matched) {
497  LOG_USER("%s mismatch", op_name);
498  tdo_mismatch = 1;
499  break;
500  }
501 
502  /* See page 19 of XSVF spec regarding opcode "XSDR" */
503  if (xruntest) {
504  result = svf_add_statemove(TAP_IDLE);
505  if (result != ERROR_OK)
506  return result;
507 
508  if (runtest_requires_tck)
509  jtag_add_clocks(xruntest);
510  else
511  jtag_add_sleep(xruntest);
512  } else if (xendir != TAP_DRPAUSE) {
513  /* we are already in TAP_DRPAUSE */
514  result = svf_add_statemove(xenddr);
515  if (result != ERROR_OK)
516  return result;
517  }
518  }
519  break;
520 
521  case XSETSDRMASKS:
522  LOG_ERROR("unsupported XSETSDRMASKS");
523  unsupported = 1;
524  break;
525 
526  case XSDRINC:
527  LOG_ERROR("unsupported XSDRINC");
528  unsupported = 1;
529  break;
530 
531  case XSDRB:
532  LOG_ERROR("unsupported XSDRB");
533  unsupported = 1;
534  break;
535 
536  case XSDRC:
537  LOG_ERROR("unsupported XSDRC");
538  unsupported = 1;
539  break;
540 
541  case XSDRE:
542  LOG_ERROR("unsupported XSDRE");
543  unsupported = 1;
544  break;
545 
546  case XSDRTDOB:
547  LOG_ERROR("unsupported XSDRTDOB");
548  unsupported = 1;
549  break;
550 
551  case XSDRTDOC:
552  LOG_ERROR("unsupported XSDRTDOC");
553  unsupported = 1;
554  break;
555 
556  case XSDRTDOE:
557  LOG_ERROR("unsupported XSDRTDOE");
558  unsupported = 1;
559  break;
560 
561  case XSTATE:
562  {
563  enum tap_state mystate;
564 
565  if (read(xsvf_fd, &uc, 1) < 0) {
566  do_abort = 1;
567  break;
568  }
569 
570  mystate = xsvf_to_tap(uc);
571 
572  LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate));
573 
574  if (mystate == TAP_INVALID) {
575  LOG_ERROR("XSVF: bad XSTATE %02x", uc);
576  do_abort = 1;
577  break;
578  }
579 
580  /* NOTE: the current state is SVF-stable! */
581 
582  /* no change == NOP */
583  if (mystate == cmd_queue_cur_state
584  && mystate != TAP_RESET)
585  break;
586 
587  /* Hand off to SVF? */
588  if (svf_tap_state_is_stable(mystate)) {
589  result = svf_add_statemove(mystate);
590  if (result != ERROR_OK)
591  unsupported = 1;
592  break;
593  }
594 
595  /*
596  * A sequence of XSTATE transitions, each TAP
597  * state adjacent to the previous one. Start
598  * collecting them.
599  */
600  collecting_path = true;
601  pathlen = 1;
602  path[0] = mystate;
603  }
604  break;
605 
606  case XENDIR:
607  if (read(xsvf_fd, &uc, 1) < 0) {
608  do_abort = 1;
609  break;
610  }
611 
612  /* see page 22 of XSVF spec */
613  if (uc == 0) {
614  xendir = TAP_IDLE;
615  } else if (uc == 1) {
616  xendir = TAP_IRPAUSE;
617  } else {
618  LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
619  unsupported = 1;
620  break;
621  }
622 
623  LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
624  break;
625 
626  case XENDDR:
627  if (read(xsvf_fd, &uc, 1) < 0) {
628  do_abort = 1;
629  break;
630  }
631 
632  /* see page 22 of XSVF spec */
633  if (uc == 0) {
634  xenddr = TAP_IDLE;
635  } else if (uc == 1) {
636  xenddr = TAP_DRPAUSE;
637  } else {
638  LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
639  unsupported = 1;
640  break;
641  }
642 
643  LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
644  break;
645 
646  case XSIR:
647  case XSIR2:
648  {
649  uint8_t short_buf[2];
650  uint8_t *ir_buf;
651  int bitcount;
652  enum tap_state my_end_state = xruntest ? TAP_IDLE : xendir;
653 
654  if (opcode == XSIR) {
655  /* one byte bitcount */
656  if (read(xsvf_fd, short_buf, 1) < 0) {
657  do_abort = 1;
658  break;
659  }
660  bitcount = short_buf[0];
661  LOG_DEBUG("XSIR %d", bitcount);
662  } else {
663  if (read(xsvf_fd, short_buf, 2) < 0) {
664  do_abort = 1;
665  break;
666  }
667  bitcount = be_to_h_u16(short_buf);
668  LOG_DEBUG("XSIR2 %d", bitcount);
669  }
670 
671  ir_buf = malloc((bitcount + 7) / 8);
672 
673  if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK) {
674  do_abort = 1;
675  } else {
676  struct scan_field field;
677 
678  field.num_bits = bitcount;
679  field.out_value = ir_buf;
680 
681  field.in_value = NULL;
682 
683  if (!tap)
685  field.out_value, field.in_value, my_end_state);
686  else
687  jtag_add_ir_scan(tap, &field, my_end_state);
688 
689  if (xruntest) {
690  if (runtest_requires_tck)
691  jtag_add_clocks(xruntest);
692  else
693  jtag_add_sleep(xruntest);
694  }
695 
696  /* Note that an -irmask of non-zero in your config file
697  * can cause this to fail. Setting -irmask to zero cand work
698  * around the problem.
699  */
700 
701  /* LOG_DEBUG("FLUSHING QUEUE"); */
702  result = jtag_execute_queue();
703  if (result != ERROR_OK)
704  tdo_mismatch = 1;
705  }
706  free(ir_buf);
707  }
708  break;
709 
710  case XCOMMENT:
711  {
712  unsigned int ndx = 0;
713  char comment[128];
714 
715  do {
716  if (read(xsvf_fd, &uc, 1) < 0) {
717  do_abort = 1;
718  break;
719  }
720 
721  if (ndx < sizeof(comment)-1)
722  comment[ndx++] = uc;
723 
724  } while (uc != 0);
725 
726  comment[sizeof(comment)-1] = 0; /* regardless, terminate */
727  if (verbose)
728  LOG_USER("# %s", comment);
729  }
730  break;
731 
732  case XWAIT:
733  {
734  /* expected in stream:
735  XWAIT <uint8_t wait_state> <uint8_t end_state> <uint32_t usecs>
736  */
737 
738  uint8_t wait_local;
739  uint8_t end;
740  uint8_t delay_buf[4];
741 
742  enum tap_state wait_state;
743  enum tap_state end_state;
744  int delay;
745 
746  if (read(xsvf_fd, &wait_local, 1) < 0
747  || read(xsvf_fd, &end, 1) < 0
748  || read(xsvf_fd, delay_buf, 4) < 0) {
749  do_abort = 1;
750  break;
751  }
752 
753  wait_state = xsvf_to_tap(wait_local);
754  end_state = xsvf_to_tap(end);
755  delay = be_to_h_u32(delay_buf);
756 
757  LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(
758  wait_state), tap_state_name(end_state), delay);
759 
760  if (runtest_requires_tck && wait_state == TAP_IDLE) {
761  jtag_add_runtest(delay, end_state);
762  } else {
763  /* FIXME handle statemove errors ... */
764  result = svf_add_statemove(wait_state);
765  if (result != ERROR_OK)
766  return result;
767  jtag_add_sleep(delay);
768  result = svf_add_statemove(end_state);
769  if (result != ERROR_OK)
770  return result;
771  }
772  }
773  break;
774 
775  case XWAITSTATE:
776  {
777  /* expected in stream:
778  * XWAITSTATE <uint8_t wait_state> <uint8_t end_state> <uint32_t clock_count>
779  * <uint32_t usecs>
780  */
781 
782  uint8_t clock_buf[4];
783  uint8_t usecs_buf[4];
784  uint8_t wait_local;
785  uint8_t end;
786  enum tap_state wait_state;
787  enum tap_state end_state;
788  int clock_count;
789  int usecs;
790 
791  if (read(xsvf_fd, &wait_local, 1) < 0
792  || read(xsvf_fd, &end, 1) < 0
793  || read(xsvf_fd, clock_buf, 4) < 0
794  || read(xsvf_fd, usecs_buf, 4) < 0) {
795  do_abort = 1;
796  break;
797  }
798 
799  wait_state = xsvf_to_tap(wait_local);
800  end_state = xsvf_to_tap(end);
801 
802  clock_count = be_to_h_u32(clock_buf);
803  usecs = be_to_h_u32(usecs_buf);
804 
805  LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
806  tap_state_name(wait_state),
807  tap_state_name(end_state),
808  clock_count, usecs);
809 
810  /* the following states are 'stable', meaning that they have a transition
811  * in the state diagram back to themselves. This is necessary because we will
812  * be issuing a number of clocks in this state. This set of allowed states is also
813  * determined by the SVF RUNTEST command's allowed states.
814  */
815  if (!svf_tap_state_is_stable(wait_state)) {
816  LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"",
817  tap_state_name(wait_state));
818  unsupported = 1;
819  /* REVISIT "break" so we won't run? */
820  }
821 
822  /* FIXME handle statemove errors ... */
823  result = svf_add_statemove(wait_state);
824  if (result != ERROR_OK)
825  return result;
826 
828  jtag_add_sleep(usecs);
829 
830  result = svf_add_statemove(end_state);
831  if (result != ERROR_OK)
832  return result;
833  }
834  break;
835 
836  case LCOUNT:
837  {
838  /* expected in stream:
839  * LCOUNT <uint32_t loop_count>
840  */
841  uint8_t count_buf[4];
842 
843  if (read(xsvf_fd, count_buf, 4) < 0) {
844  do_abort = 1;
845  break;
846  }
847 
848  loop_count = be_to_h_u32(count_buf);
849  LOG_DEBUG("LCOUNT %d", loop_count);
850  }
851  break;
852 
853  case LDELAY:
854  {
855  /* expected in stream:
856  * LDELAY <uint8_t wait_state> <uint32_t clock_count> <uint32_t usecs_to_sleep>
857  */
858  uint8_t state;
859  uint8_t clock_buf[4];
860  uint8_t usecs_buf[4];
861 
862  if (read(xsvf_fd, &state, 1) < 0
863  || read(xsvf_fd, clock_buf, 4) < 0
864  || read(xsvf_fd, usecs_buf, 4) < 0) {
865  do_abort = 1;
866  break;
867  }
868 
869  /* NOTE: loop_state must be stable! */
870  loop_state = xsvf_to_tap(state);
871  loop_clocks = be_to_h_u32(clock_buf);
872  loop_usecs = be_to_h_u32(usecs_buf);
873 
874  LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(
875  loop_state), loop_clocks, loop_usecs);
876  }
877  break;
878 
879  /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
880  * comes with clocks !AND! sleep requirements.
881  */
882  case LSDR:
883  {
884  int limit = loop_count;
885  int matched = 0;
886  int attempt;
887 
888  LOG_DEBUG("LSDR");
889 
890  if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
891  || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK) {
892  do_abort = 1;
893  break;
894  }
895 
896  if (limit < 1)
897  limit = 1;
898 
899  for (attempt = 0; attempt < limit; ++attempt) {
900  struct scan_field field;
901 
902  result = svf_add_statemove(loop_state);
903  if (result != ERROR_OK) {
904  free(dr_in_mask);
905  return result;
906  }
907  jtag_add_clocks(loop_clocks);
908  jtag_add_sleep(loop_usecs);
909 
910  field.num_bits = xsdrsize;
911  field.out_value = dr_out_buf;
912  field.in_value = calloc(DIV_ROUND_UP(field.num_bits, 8), 1);
913 
914  if (attempt > 0 && verbose)
915  LOG_USER("LSDR retry %d", attempt);
916 
917  if (!tap)
919  field.out_value,
920  field.in_value,
921  TAP_DRPAUSE);
922  else
923  jtag_add_dr_scan(tap, 1, &field, TAP_DRPAUSE);
924 
925  jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
926 
927  free(field.in_value);
928 
929 
930  /* LOG_DEBUG("FLUSHING QUEUE"); */
931  result = jtag_execute_queue();
932  if (result == ERROR_OK) {
933  matched = 1;
934  break;
935  }
936  }
937 
938  if (!matched) {
939  LOG_USER("LSDR mismatch");
940  tdo_mismatch = 1;
941  break;
942  }
943  }
944  break;
945 
946  case XTRST:
947  {
948  uint8_t trst_mode;
949 
950  if (read(xsvf_fd, &trst_mode, 1) < 0) {
951  do_abort = 1;
952  break;
953  }
954 
955  switch (trst_mode) {
956  case XTRST_ON:
957  jtag_add_reset(1, 0);
958  break;
959  case XTRST_OFF:
960  case XTRST_Z:
961  jtag_add_reset(0, 0);
962  break;
963  case XTRST_ABSENT:
964  break;
965  default:
966  LOG_ERROR("XTRST mode argument (0x%02X) out of range", trst_mode);
967  do_abort = 1;
968  }
969  }
970  break;
971 
972  default:
973  LOG_ERROR("unknown xsvf command (0x%02X)", uc);
974  unsupported = 1;
975  }
976 
977  if (do_abort || unsupported || tdo_mismatch) {
978  LOG_DEBUG("xsvf failed, setting taps to reasonable state");
979 
980  /* upon error, return the TAPs to a reasonable state */
981  result = svf_add_statemove(TAP_IDLE);
982  if (result != ERROR_OK)
983  return result;
984  result = jtag_execute_queue();
985  if (result != ERROR_OK)
986  return result;
987  break;
988  }
989  }
990 
991  if (tdo_mismatch) {
993  "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
994  file_offset);
995 
996  return ERROR_FAIL;
997  }
998 
999  if (unsupported) {
1000  off_t offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
1002  "unsupported xsvf command (0x%02X) at offset %jd, aborting",
1003  uc, (intmax_t)offset);
1004  return ERROR_FAIL;
1005  }
1006 
1007  if (do_abort) {
1008  command_print(CMD, "premature end of xsvf file detected, aborting");
1009  return ERROR_FAIL;
1010  }
1011 
1012  free(dr_out_buf);
1013  free(dr_in_buf);
1014  free(dr_in_mask);
1015 
1016  close(xsvf_fd);
1017 
1018  command_print(CMD, "XSVF file programmed successfully");
1019 
1020  return ERROR_OK;
1021 }
1022 
1023 static const struct command_registration xsvf_command_handlers[] = {
1024  {
1025  .name = "xsvf",
1026  .handler = handle_xsvf_command,
1027  .mode = COMMAND_EXEC,
1028  .help = "Runs a XSVF file. If 'virt2' is given, xruntest "
1029  "counts are interpreted as TCK cycles rather than "
1030  "as microseconds. Without the 'quiet' option, all "
1031  "comments, retries, and mismatches will be reported.",
1032  .usage = "(tapname|'plain') filename ['virt2'] ['quiet']",
1033  },
1035 };
1036 
1038 {
1039  return register_commands(cmd_ctx, NULL, xsvf_command_handlers);
1040 }
1041 
1042 /*
1043 
1044 PSEUDO-Code from Xilinx Appnote XAPP067.pdf :
1045 
1046 the following pseudo code clarifies the intent of the xrepeat support.The
1047 flow given is for the entire processing of an SVF file, not an XSVF file.
1048 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1049 
1050 "Pseudo-Code Algorithm for SVF-Based ISP"
1051 
1052 1. Go to Test-Logic-Reset state
1053 2. Go to Run-Test Idle state
1054 3. Read SVF record
1055 
1056 4. if SIR record then
1057 go to Shift-IR state
1058 Scan in <TDI value>
1059 
1060 5. else if SDR record then
1061 set <repeat count> to 0
1062 store <TDI value> as <current TDI value>
1063 store <TDO value> as <current TDO value>
1064 6. go to Shift-DR state
1065 scan in <current TDI value>
1066 if < current TDO value > is specified then
1067 if < current TDO value > does not equal <actual TDO value> then
1068 if < repeat count > > 32 then
1069 LOG ERROR
1070 go to Run-Test Idle state
1071 go to Step 3
1072 end if
1073 go to Pause-DR
1074 go to Exit2-DR
1075 go to Shift-DR
1076 go to Exit1-DR
1077 go to Update-DR
1078 go to Run-Test/Idle
1079 increment <repeat count> by 1
1080 pause <current pause time> microseconds
1081 go to Step 6)
1082 end if
1083 else
1084  go to Run-Test Idle state
1085  go to Step 3
1086  endif
1087  else if RUNTEST record then
1088  pause tester for < TCK value > microseconds
1089  store <TCK value> as <current pause time>
1090  end if
1091 
1092 */
void command_print(struct command_invocation *cmd, const char *format,...)
Definition: command.c:371
#define CMD
Use this macro to access the command being handled, rather than accessing the variable directly.
Definition: command.h:141
#define CMD_ARGV
Use this macro to access the arguments for the command being handled, rather than accessing the varia...
Definition: command.h:156
#define ERROR_COMMAND_SYNTAX_ERROR
Definition: command.h:400
#define CMD_ARGC
Use this macro to access the number of arguments for the command being handled, rather than accessing...
Definition: command.h:151
#define COMMAND_REGISTRATION_DONE
Use this as the last entry in an array of command_registration records.
Definition: command.h:251
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:272
@ COMMAND_EXEC
Definition: command.h:40
static int clock_count
Definition: dummy.c:21
const char * tap_state_name(enum tap_state state)
Function tap_state_name Returns a string suitable for display representing the JTAG tap_state.
Definition: interface.c:344
void jtag_add_plain_dr_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits, enum tap_state state)
Scan out the bits in ir scan mode.
Definition: jtag/core.c:471
struct jtag_tap * jtag_tap_by_string(const char *s)
Definition: jtag/core.c:243
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:771
void jtag_add_runtest(unsigned int num_cycles, enum tap_state state)
Goes to TAP_IDLE (if we're not already there), cycle precisely num_cycles in the TAP_IDLE state,...
Definition: jtag/core.c:598
int jtag_execute_queue(void)
For software FIFO implementations, the queued commands can be executed during this call or earlier.
Definition: jtag/core.c:1050
void jtag_add_pathmove(unsigned int num_states, const enum tap_state *path)
Application code must assume that interfaces will implement transitions between states with different...
Definition: jtag/core.c:523
void jtag_add_clocks(unsigned 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:605
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:484
void jtag_add_dr_scan(struct jtag_tap *active, int in_num_fields, const struct scan_field *in_fields, enum tap_state state)
Generate a DR SCAN using the fields passed to the function.
Definition: jtag/core.c:457
void jtag_add_sleep(uint32_t us)
Definition: jtag/core.c:883
enum tap_state cmd_queue_cur_state
The current TAP state of the pending JTAG command queue.
Definition: jtag/core.c:90
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:930
void jtag_add_plain_ir_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits, enum tap_state state)
Scan out the bits in ir scan mode.
Definition: jtag/core.c:398
void jtag_add_ir_scan(struct jtag_tap *active, struct scan_field *in_fields, enum tap_state state)
Generate an IR SCAN with a list of scan fields with one entry for each enabled TAP.
Definition: jtag/core.c:380
The JTAG interface can be implemented with a software or hardware fifo.
tap_state
Defines JTAG Test Access Port states.
Definition: jtag.h:37
@ TAP_IRCAPTURE
Definition: jtag.h:55
@ TAP_RESET
Definition: jtag.h:56
@ TAP_DRCAPTURE
Definition: jtag.h:47
@ TAP_DRSELECT
Definition: jtag.h:48
@ TAP_DREXIT1
Definition: jtag.h:42
@ TAP_IREXIT1
Definition: jtag.h:50
@ TAP_DRPAUSE
Definition: jtag.h:44
@ TAP_IRSELECT
Definition: jtag.h:45
@ TAP_IRUPDATE
Definition: jtag.h:54
@ TAP_IREXIT2
Definition: jtag.h:49
@ TAP_IRSHIFT
Definition: jtag.h:51
@ TAP_DREXIT2
Definition: jtag.h:41
@ TAP_IDLE
Definition: jtag.h:53
@ TAP_DRSHIFT
Definition: jtag.h:43
@ TAP_IRPAUSE
Definition: jtag.h:52
@ TAP_DRUPDATE
Definition: jtag.h:46
@ TAP_INVALID
Definition: jtag.h:38
#define LOG_USER(expr ...)
Definition: log.h:136
#define LOG_WARNING(expr ...)
Definition: log.h:130
#define ERROR_FAIL
Definition: log.h:174
#define LOG_ERROR(expr ...)
Definition: log.h:133
#define LOG_DEBUG(expr ...)
Definition: log.h:110
#define ERROR_OK
Definition: log.h:168
const char * name
Definition: command.h:234
Definition: jtag.h:101
This structure defines a single scan field in the scan.
Definition: jtag.h:87
uint8_t * in_value
A pointer to a 32-bit memory location for data scanned out.
Definition: jtag.h:93
const uint8_t * out_value
A pointer to value to be scanned into the device.
Definition: jtag.h:91
unsigned int num_bits
The number of bits this field specifies.
Definition: jtag.h:89
trst_mode
Definition: svf.c:63
int svf_add_statemove(enum tap_state state_to)
svf_add_statemove() moves from the current state to goal_state.
Definition: svf.c:316
bool svf_tap_state_is_stable(enum tap_state state)
svf_tap_state_is_stable() returns true for stable non-SHIFT states
Definition: svf.c:821
#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:1037
#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
static enum tap_state xsvf_to_tap(int xsvf_state)
Definition: xsvf.c:115
#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 const struct command_registration xsvf_command_handlers[]
Definition: xsvf.c:1023
#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