2 * Copyright (C) 2005 by Dominic Rath
5 * Copyright (C) 2007,2008 Øyvind Harboe
6 * oyvind.harboe@zylin.com
8 * Copyright (C) 2008 Peter Hettkamp
9 * peter.hettkamp@htp-tel.de
11 * Copyright (C) 2009 SoftPLC Corporation. http://softplc.com
12 * Dick Hollenbeck <dick@softplc.com>
14 * This program is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU General Public License as published by
16 * the Free Software Foundation; either version 2 of the License, or
17 * (at your option) any later version.
19 * This program is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU General Public License for more details.
24 * You should have received a copy of the GNU General Public License
25 * along with this program; if not, write to the Free Software
26 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
30 /* The specification for SVF is available here:
31 * http://www.asset-intertech.com/support/svf.pdf
32 * Below, this document is refered to as the "SVF spec".
34 * The specification for XSVF is available here:
35 * http://www.xilinx.com/support/documentation/application_notes/xapp503.pdf
36 * Below, this document is refered to as the "XSVF spec".
47 /* XSVF commands, from appendix B of xapp503.pdf */
48 #define XCOMPLETE 0x00
56 #define XSETSDRMASKS 0x0A
71 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
72 * generates this. Arguably it is needed because the XSVF XRUNTEST command
73 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
74 * This XWAITSTATE does map directly from the SVF RUNTEST command.
76 #define XWAITSTATE 0x18
78 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
79 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
80 * Here is an example of usage of the 3 lattice opcode extensions:
82 ! Set the maximum loop count to 25.
84 ! Step to DRPAUSE give 5 clocks and wait for 1.00e + 000 SEC.
85 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
86 ! Test for the completed status. Match means pass.
87 ! Loop back to LDELAY line if not match and loop count less than 25.
99 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
100 #define XSV_RESET 0x00
101 #define XSV_IDLE 0x01
102 #define XSV_DRSELECT 0x02
103 #define XSV_DRCAPTURE 0x03
104 #define XSV_DRSHIFT 0x04
105 #define XSV_DREXIT1 0x05
106 #define XSV_DRPAUSE 0x06
107 #define XSV_DREXIT2 0x07
108 #define XSV_DRUPDATE 0x08
109 #define XSV_IRSELECT 0x09
110 #define XSV_IRCAPTURE 0x0A
111 #define XSV_IRSHIFT 0x0B
112 #define XSV_IREXIT1 0x0C
113 #define XSV_IRPAUSE 0x0D
114 #define XSV_IREXIT2 0x0E
115 #define XSV_IRUPDATE 0x0F
117 /* arguments to XTRST */
121 #define XTRST_ABSENT 3
123 #define XSTATE_MAX_PATH 12
125 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc);
127 static int xsvf_fd = 0;
130 /* map xsvf tap state to an openocd "tap_state_t" */
131 static tap_state_t xsvf_to_tap(int xsvf_state)
137 case XSV_RESET: ret = TAP_RESET; break;
138 case XSV_IDLE: ret = TAP_IDLE; break;
139 case XSV_DRSELECT: ret = TAP_DRSELECT; break;
140 case XSV_DRCAPTURE: ret = TAP_DRCAPTURE; break;
141 case XSV_DRSHIFT: ret = TAP_DRSHIFT; break;
142 case XSV_DREXIT1: ret = TAP_DREXIT1; break;
143 case XSV_DRPAUSE: ret = TAP_DRPAUSE; break;
144 case XSV_DREXIT2: ret = TAP_DREXIT2; break;
145 case XSV_DRUPDATE: ret = TAP_DRUPDATE; break;
146 case XSV_IRSELECT: ret = TAP_IRSELECT; break;
147 case XSV_IRCAPTURE: ret = TAP_IRCAPTURE; break;
148 case XSV_IRSHIFT: ret = TAP_IRSHIFT; break;
149 case XSV_IREXIT1: ret = TAP_IREXIT1; break;
150 case XSV_IRPAUSE: ret = TAP_IRPAUSE; break;
151 case XSV_IREXIT2: ret = TAP_IREXIT2; break;
152 case XSV_IRUPDATE: ret = TAP_IRUPDATE; break;
154 LOG_ERROR("UNKNOWN XSVF STATE 0x%02X", xsvf_state);
163 int xsvf_register_commands(struct command_context_s *cmd_ctx)
165 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
166 COMMAND_EXEC, "run xsvf <file> [virt2] [quiet]");
171 static int xsvf_read_buffer(int num_bits, int fd, uint8_t* buf)
175 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
177 /* reverse the order of bytes as they are read sequentially from file */
178 if (read(fd, buf + num_bytes - 1, 1) < 0)
179 return ERROR_XSVF_EOF;
186 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
188 uint8_t *dr_out_buf = NULL; /* from host to device (TDI) */
189 uint8_t *dr_in_buf = NULL; /* from device to host (TDO) */
190 uint8_t *dr_in_mask = NULL;
193 int xruntest = 0; /* number of TCK cycles OR microseconds */
194 int xrepeat = 0; /* number of retries */
196 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
197 tap_state_t xenddr = TAP_IDLE;
201 long file_offset = 0;
204 tap_state_t loop_state = TAP_IDLE;
210 int tdo_mismatch = 0;
215 int runtest_requires_tck = 0; /* a flag telling whether to clock TCK during waits, or simply sleep, controled by virt2 */
218 /* use NULL to indicate a "plain" xsvf file which accounts for
219 additional devices in the scan chain, otherwise the device
220 that should be affected
222 jtag_tap_t *tap = NULL;
226 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> [<variant>] [quiet]");
230 filename = args[1]; /* we mess with args starting point below, snapshot filename here */
232 if (strcmp(args[0], "plain") != 0)
234 tap = jtag_tap_by_string(args[0]);
237 command_print(cmd_ctx, "Tap: %s unknown", args[0]);
242 if ((xsvf_fd = open(filename, O_RDONLY)) < 0)
244 command_print(cmd_ctx, "file \"%s\" not found", filename);
248 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
249 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
251 runtest_requires_tck = 1;
256 if ((argc > 2) && (strcmp(args[2], "quiet") == 0))
261 LOG_USER("xsvf processing file: \"%s\"", filename);
263 while (read(xsvf_fd, &opcode, 1) > 0)
265 /* record the position of the just read opcode within the file */
266 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
271 LOG_DEBUG("XCOMPLETE");
273 result = jtag_execute_queue();
274 if (result != ERROR_OK)
282 LOG_DEBUG("XTDOMASK");
283 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
289 uint8_t xruntest_buf[4];
291 if (read(xsvf_fd, xruntest_buf, 4) < 0)
297 xruntest = be_to_h_u32(xruntest_buf);
298 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
306 if (read(xsvf_fd, &myrepeat, 1) < 0)
311 LOG_DEBUG("XREPEAT %d", xrepeat);
318 uint8_t xsdrsize_buf[4];
320 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
326 xsdrsize = be_to_h_u32(xsdrsize_buf);
327 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
329 if (dr_out_buf) free(dr_out_buf);
330 if (dr_in_buf) free(dr_in_buf);
331 if (dr_in_mask) free(dr_in_mask);
333 dr_out_buf = malloc((xsdrsize + 7) / 8);
334 dr_in_buf = malloc((xsdrsize + 7) / 8);
335 dr_in_mask = malloc((xsdrsize + 7) / 8);
339 case XSDR: /* these two are identical except for the dr_in_buf */
346 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
348 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
354 if (opcode == XSDRTDO)
356 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK)
366 LOG_DEBUG("%s %d", op_name, xsdrsize);
368 for (attempt = 0; attempt < limit; ++attempt)
374 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
375 illustrated in psuedo code at end of this file. We start from state
383 This sequence should be harmless for other devices, and it
384 will be skipped entirely if xrepeat is set to zero.
387 static tap_state_t exception_path[] = {
395 jtag_add_pathmove(DIM(exception_path), exception_path);
398 LOG_USER("%s mismatch, xsdrsize=%d retry=%d", op_name, xsdrsize, attempt);
402 field.num_bits = xsdrsize;
403 field.out_value = dr_out_buf;
404 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
407 jtag_add_plain_dr_scan(1, &field, jtag_set_end_state(TAP_DRPAUSE));
409 jtag_add_dr_scan(1, &field, jtag_set_end_state(TAP_DRPAUSE));
411 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
413 free(field.in_value);
416 /* LOG_DEBUG("FLUSHING QUEUE"); */
417 result = jtag_execute_queue();
418 if (result == ERROR_OK)
427 LOG_USER("%s mismatch", op_name);
432 /* See page 19 of XSVF spec regarding opcode "XSDR" */
435 jtag_add_statemove(TAP_IDLE);
437 if (runtest_requires_tck)
438 jtag_add_clocks(xruntest);
440 jtag_add_sleep(xruntest);
442 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
443 jtag_add_statemove(xenddr);
448 LOG_ERROR("unsupported XSETSDRMASKS\n");
453 LOG_ERROR("unsupported XSDRINC\n");
458 LOG_ERROR("unsupported XSDRB\n");
463 LOG_ERROR("unsupported XSDRC\n");
468 LOG_ERROR("unsupported XSDRE\n");
473 LOG_ERROR("unsupported XSDRTDOB\n");
478 LOG_ERROR("unsupported XSDRTDOC\n");
483 LOG_ERROR("unsupported XSDRTDOE\n");
492 if (read(xsvf_fd, &uc, 1) < 0)
498 mystate = xsvf_to_tap(uc);
500 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate));
502 /* there is no need for the lookahead code that was here since we
503 queue up the jtag commands anyway. This is a simple way to handle
507 if (jtag_add_statemove(mystate) != ERROR_OK)
509 /* For special states known as stable states
510 (Test-Logic-Reset, Run-Test/Idle, Pause-DR, Pause- IR),
511 an XSVF interpreter follows predefined TAP state paths
512 when the starting state is a stable state and when the
513 XSTATE specifies a new stable state (see the STATE
514 command in the [Ref 5] for the TAP state paths between
515 stable states). For non-stable states, XSTATE should
516 specify a state that is only one TAP state transition
517 distance from the current TAP state to avoid undefined
518 TAP state paths. A sequence of multiple XSTATE commands
519 can be issued to transition the TAP through a specific
523 LOG_ERROR("XSTATE %s is not reachable from current state %s in one clock cycle",
524 tap_state_name(mystate),
525 tap_state_name(cmd_queue_cur_state)
533 if (read(xsvf_fd, &uc, 1) < 0)
539 /* see page 22 of XSVF spec */
543 xendir = TAP_IRPAUSE;
546 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
551 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
556 if (read(xsvf_fd, &uc, 1) < 0)
562 /* see page 22 of XSVF spec */
566 xenddr = TAP_DRPAUSE;
569 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
574 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
580 uint8_t short_buf[2];
583 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
587 /* one byte bitcount */
588 if (read(xsvf_fd, short_buf, 1) < 0)
593 bitcount = short_buf[0];
594 LOG_DEBUG("XSIR %d", bitcount);
598 if (read(xsvf_fd, short_buf, 2) < 0)
603 bitcount = be_to_h_u16(short_buf);
604 LOG_DEBUG("XSIR2 %d", bitcount);
607 ir_buf = malloc((bitcount + 7) / 8);
609 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
616 field.num_bits = bitcount;
617 field.out_value = ir_buf;
619 field.in_value = NULL;
625 jtag_add_plain_ir_scan(1, &field, my_end_state);
627 jtag_add_ir_scan(1, &field, my_end_state);
631 if (runtest_requires_tck)
632 jtag_add_clocks(xruntest);
634 jtag_add_sleep(xruntest);
637 /* Note that an -irmask of non-zero in your config file
638 * can cause this to fail. Setting -irmask to zero cand work
639 * around the problem.
642 /* LOG_DEBUG("FLUSHING QUEUE"); */
643 result = jtag_execute_queue();
644 if (result != ERROR_OK)
655 unsigned int ndx = 0;
660 if (read(xsvf_fd, &uc, 1) < 0)
666 if (ndx < sizeof(comment)-1)
671 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
673 LOG_USER("# %s", comment);
679 /* expected in stream:
680 XWAIT <uint8_t wait_state> <uint8_t end_state> <uint32_t usecs>
685 uint8_t delay_buf[4];
687 tap_state_t wait_state;
688 tap_state_t end_state;
691 if (read(xsvf_fd, &wait, 1) < 0
692 || read(xsvf_fd, &end, 1) < 0
693 || read(xsvf_fd, delay_buf, 4) < 0)
699 wait_state = xsvf_to_tap(wait);
700 end_state = xsvf_to_tap(end);
701 delay = be_to_h_u32(delay_buf);
703 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(wait_state), tap_state_name(end_state), delay);
705 if (runtest_requires_tck && wait_state == TAP_IDLE)
707 jtag_add_runtest(delay, end_state);
711 jtag_add_statemove(wait_state);
712 jtag_add_sleep(delay);
713 jtag_add_statemove(end_state);
720 /* expected in stream:
721 XWAITSTATE <uint8_t wait_state> <uint8_t end_state> <uint32_t clock_count> <uint32_t usecs>
724 uint8_t clock_buf[4];
725 uint8_t usecs_buf[4];
728 tap_state_t wait_state;
729 tap_state_t end_state;
733 if (read(xsvf_fd, &wait, 1) < 0
734 || read(xsvf_fd, &end, 1) < 0
735 || read(xsvf_fd, clock_buf, 4) < 0
736 || read(xsvf_fd, usecs_buf, 4) < 0)
742 wait_state = xsvf_to_tap(wait);
743 end_state = xsvf_to_tap(end);
745 clock_count = be_to_h_u32(clock_buf);
746 usecs = be_to_h_u32(usecs_buf);
748 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
749 tap_state_name(wait_state),
750 tap_state_name(end_state),
753 /* the following states are 'stable', meaning that they have a transition
754 * in the state diagram back to themselves. This is necessary because we will
755 * be issuing a number of clocks in this state. This set of allowed states is also
756 * determined by the SVF RUNTEST command's allowed states.
758 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
760 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", tap_state_name(wait_state));
764 jtag_add_statemove(wait_state);
766 jtag_add_clocks(clock_count);
768 jtag_add_sleep(usecs);
770 jtag_add_statemove(end_state);
776 /* expected in stream:
777 LCOUNT <uint32_t loop_count>
779 uint8_t count_buf[4];
781 if (read(xsvf_fd, count_buf, 4) < 0)
787 loop_count = be_to_h_u32(count_buf);
788 LOG_DEBUG("LCOUNT %d", loop_count);
794 /* expected in stream:
795 LDELAY <uint8_t wait_state> <uint32_t clock_count> <uint32_t usecs_to_sleep>
798 uint8_t clock_buf[4];
799 uint8_t usecs_buf[4];
801 if (read(xsvf_fd, &state, 1) < 0
802 || read(xsvf_fd, clock_buf, 4) < 0
803 || read(xsvf_fd, usecs_buf, 4) < 0)
809 loop_state = xsvf_to_tap(state);
810 loop_clocks = be_to_h_u32(clock_buf);
811 loop_usecs = be_to_h_u32(usecs_buf);
813 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
817 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
818 * comes with clocks !AND! sleep requirements.
822 int limit = loop_count;
828 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
829 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK)
838 for (attempt = 0; attempt < limit; ++attempt)
842 jtag_add_statemove(loop_state);
843 jtag_add_clocks(loop_clocks);
844 jtag_add_sleep(loop_usecs);
847 field.num_bits = xsdrsize;
848 field.out_value = dr_out_buf;
849 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
851 if (attempt > 0 && verbose)
852 LOG_USER("LSDR retry %d", attempt);
855 jtag_add_plain_dr_scan(1, &field, jtag_set_end_state(TAP_DRPAUSE));
857 jtag_add_dr_scan(1, &field, jtag_set_end_state(TAP_DRPAUSE));
859 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
861 free(field.in_value);
864 /* LOG_DEBUG("FLUSHING QUEUE"); */
865 result = jtag_execute_queue();
866 if (result == ERROR_OK)
875 LOG_USER("LSDR mismatch");
886 if (read(xsvf_fd, &trst_mode, 1) < 0)
895 jtag_add_reset(1, 0);
899 jtag_add_reset(0, 0);
904 LOG_ERROR("XTRST mode argument (0x%02X) out of range", trst_mode);
911 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
915 if (do_abort || unsupported || tdo_mismatch)
917 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
919 /* upon error, return the TAPs to a reasonable state */
920 jtag_add_statemove(TAP_IDLE);
921 jtag_execute_queue();
928 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
937 off_t offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
938 command_print(cmd_ctx,
939 "unsupported xsvf command (0x%02X) at offset %jd, aborting",
940 uc, (intmax_t)offset);
946 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
961 command_print(cmd_ctx, "XSVF file programmed successfully");
967 #if 0 /* this comment style used to try and keep uncrustify from adding * at begin of line */
969 PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
971 the following pseudo code clarifies the intent of the xrepeat support. The
972 flow given is for the entire processing of an SVF file, not an XSVF file.
973 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
975 "Pseudo-Code Algorithm for SVF-Based ISP"
977 1. Go to Test-Logic-Reset state
978 2. Go to Run-Test Idle state
981 4. if SIR record then
985 5. else if SDR record then
986 set <repeat count> to 0
987 store <TDI value> as <current TDI value>
988 store <TDO value> as <current TDO value>
989 6. go to Shift-DR state
990 scan in <current TDI value>
991 if <current TDO value> is specified then
992 if <current TDO value> does not equal <actual TDO value> then
993 if <repeat count> > 32 then
995 go to Run-Test Idle state
1004 increment <repeat count> by 1
1005 pause <current pause time> microseconds
1009 go to Run-Test Idle state
1012 else if RUNTEST record then
1013 pause tester for <TCK value> microseconds
1014 store <TCK value> as <current pause time>