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".
48 /* XSVF commands, from appendix B of xapp503.pdf */
49 #define XCOMPLETE 0x00
57 #define XSETSDRMASKS 0x0A
72 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
73 * generates this. Arguably it is needed because the XSVF XRUNTEST command
74 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
75 * This XWAITSTATE does map directly from the SVF RUNTEST command.
77 #define XWAITSTATE 0x18
79 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
80 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
81 * Here is an example of usage of the 3 lattice opcode extensions:
83 ! Set the maximum loop count to 25.
85 ! Step to DRPAUSE give 5 clocks and wait for 1.00e + 000 SEC.
86 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
87 ! Test for the completed status. Match means pass.
88 ! Loop back to LDELAY line if not match and loop count less than 25.
100 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
101 #define XSV_RESET 0x00
102 #define XSV_IDLE 0x01
103 #define XSV_DRSELECT 0x02
104 #define XSV_DRCAPTURE 0x03
105 #define XSV_DRSHIFT 0x04
106 #define XSV_DREXIT1 0x05
107 #define XSV_DRPAUSE 0x06
108 #define XSV_DREXIT2 0x07
109 #define XSV_DRUPDATE 0x08
110 #define XSV_IRSELECT 0x09
111 #define XSV_IRCAPTURE 0x0A
112 #define XSV_IRSHIFT 0x0B
113 #define XSV_IREXIT1 0x0C
114 #define XSV_IRPAUSE 0x0D
115 #define XSV_IREXIT2 0x0E
116 #define XSV_IRUPDATE 0x0F
118 /* arguments to XTRST */
122 #define XTRST_ABSENT 3
124 #define XSTATE_MAX_PATH 12
126 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc);
128 static int xsvf_fd = 0;
131 /* map xsvf tap state to an openocd "tap_state_t" */
132 static tap_state_t xsvf_to_tap(int xsvf_state)
138 case XSV_RESET: ret = TAP_RESET; break;
139 case XSV_IDLE: ret = TAP_IDLE; break;
140 case XSV_DRSELECT: ret = TAP_DRSELECT; break;
141 case XSV_DRCAPTURE: ret = TAP_DRCAPTURE; break;
142 case XSV_DRSHIFT: ret = TAP_DRSHIFT; break;
143 case XSV_DREXIT1: ret = TAP_DREXIT1; break;
144 case XSV_DRPAUSE: ret = TAP_DRPAUSE; break;
145 case XSV_DREXIT2: ret = TAP_DREXIT2; break;
146 case XSV_DRUPDATE: ret = TAP_DRUPDATE; break;
147 case XSV_IRSELECT: ret = TAP_IRSELECT; break;
148 case XSV_IRCAPTURE: ret = TAP_IRCAPTURE; break;
149 case XSV_IRSHIFT: ret = TAP_IRSHIFT; break;
150 case XSV_IREXIT1: ret = TAP_IREXIT1; break;
151 case XSV_IRPAUSE: ret = TAP_IRPAUSE; break;
152 case XSV_IREXIT2: ret = TAP_IREXIT2; break;
153 case XSV_IRUPDATE: ret = TAP_IRUPDATE; break;
155 LOG_ERROR("UNKNOWN XSVF STATE 0x%02X", xsvf_state);
164 int xsvf_register_commands(struct command_context_s *cmd_ctx)
166 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
167 COMMAND_EXEC, "run xsvf <file> [virt2] [quiet]");
172 static int xsvf_read_buffer(int num_bits, int fd, uint8_t* buf)
176 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
178 /* reverse the order of bytes as they are read sequentially from file */
179 if (read(fd, buf + num_bytes - 1, 1) < 0)
180 return ERROR_XSVF_EOF;
187 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
189 uint8_t *dr_out_buf = NULL; /* from host to device (TDI) */
190 uint8_t *dr_in_buf = NULL; /* from device to host (TDO) */
191 uint8_t *dr_in_mask = NULL;
194 int xruntest = 0; /* number of TCK cycles OR microseconds */
195 int xrepeat = 0; /* number of retries */
197 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
198 tap_state_t xenddr = TAP_IDLE;
202 long file_offset = 0;
205 tap_state_t loop_state = TAP_IDLE;
211 int tdo_mismatch = 0;
216 bool collecting_path = false;
217 tap_state_t path[XSTATE_MAX_PATH];
218 unsigned pathlen = 0;
220 /* a flag telling whether to clock TCK during waits,
221 * or simply sleep, controled by virt2
223 int runtest_requires_tck = 0;
226 /* use NULL to indicate a "plain" xsvf file which accounts for
227 additional devices in the scan chain, otherwise the device
228 that should be affected
230 jtag_tap_t *tap = NULL;
234 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> [<variant>] [quiet]");
238 filename = args[1]; /* we mess with args starting point below, snapshot filename here */
240 if (strcmp(args[0], "plain") != 0)
242 tap = jtag_tap_by_string(args[0]);
245 command_print(cmd_ctx, "Tap: %s unknown", args[0]);
250 if ((xsvf_fd = open(filename, O_RDONLY)) < 0)
252 command_print(cmd_ctx, "file \"%s\" not found", filename);
256 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
257 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
259 runtest_requires_tck = 1;
264 if ((argc > 2) && (strcmp(args[2], "quiet") == 0))
269 LOG_USER("xsvf processing file: \"%s\"", filename);
271 while (read(xsvf_fd, &opcode, 1) > 0)
273 /* record the position of this opcode within the file */
274 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
276 /* maybe collect another state for a pathmove();
277 * or terminate a path.
279 if (collecting_path) {
285 /* ignore/show comments between XSTATE ops */
288 /* try to collect another transition */
289 if (pathlen == XSTATE_MAX_PATH) {
290 LOG_ERROR("XSVF: path too long");
295 if (read(xsvf_fd, &uc, 1) < 0)
301 mystate = xsvf_to_tap(uc);
302 path[pathlen++] = mystate;
304 LOG_DEBUG("XSTATE 0x%02X %s", uc,
305 tap_state_name(mystate));
307 /* If path is incomplete, collect more */
308 if (!svf_tap_state_is_stable(mystate))
311 /* Else execute the path transitions we've
314 * NOTE: Punting on the saved path is not
315 * strictly correct, but we must to do this
316 * unless jtag_add_pathmove() stops rejecting
317 * paths containing RESET. This is probably
318 * harmless, since there aren't many options
319 * for going from a stable state to reset;
320 * at the worst, we may issue extra clocks
321 * once we get to RESET.
323 if (mystate == TAP_RESET) {
324 LOG_WARNING("XSVF: dodgey RESET");
330 /* Execute the path we collected
332 * NOTE: OpenOCD requires something that XSVF
333 * doesn't: the last TAP state in the path
334 * must be stable. In practice, tools that
335 * create XSVF seem to follow that rule too.
337 collecting_path = false;
339 if (path[0] == TAP_RESET)
342 jtag_add_pathmove(pathlen, path);
344 result = jtag_get_error();
345 if (result != ERROR_OK) {
346 LOG_ERROR("XSVF: pathmove error %d",
358 LOG_DEBUG("XCOMPLETE");
360 result = jtag_execute_queue();
361 if (result != ERROR_OK)
369 LOG_DEBUG("XTDOMASK");
370 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
376 uint8_t xruntest_buf[4];
378 if (read(xsvf_fd, xruntest_buf, 4) < 0)
384 xruntest = be_to_h_u32(xruntest_buf);
385 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
393 if (read(xsvf_fd, &myrepeat, 1) < 0)
398 LOG_DEBUG("XREPEAT %d", xrepeat);
405 uint8_t xsdrsize_buf[4];
407 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
413 xsdrsize = be_to_h_u32(xsdrsize_buf);
414 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
416 if (dr_out_buf) free(dr_out_buf);
417 if (dr_in_buf) free(dr_in_buf);
418 if (dr_in_mask) free(dr_in_mask);
420 dr_out_buf = malloc((xsdrsize + 7) / 8);
421 dr_in_buf = malloc((xsdrsize + 7) / 8);
422 dr_in_mask = malloc((xsdrsize + 7) / 8);
426 case XSDR: /* these two are identical except for the dr_in_buf */
433 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
435 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
441 if (opcode == XSDRTDO)
443 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK)
453 LOG_DEBUG("%s %d", op_name, xsdrsize);
455 for (attempt = 0; attempt < limit; ++attempt)
461 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
462 illustrated in psuedo code at end of this file. We start from state
470 This sequence should be harmless for other devices, and it
471 will be skipped entirely if xrepeat is set to zero.
474 static tap_state_t exception_path[] = {
482 jtag_add_pathmove(DIM(exception_path), exception_path);
485 LOG_USER("%s mismatch, xsdrsize=%d retry=%d", op_name, xsdrsize, attempt);
489 field.num_bits = xsdrsize;
490 field.out_value = dr_out_buf;
491 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
494 jtag_add_plain_dr_scan(1, &field, jtag_set_end_state(TAP_DRPAUSE));
496 jtag_add_dr_scan(1, &field, jtag_set_end_state(TAP_DRPAUSE));
498 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
500 free(field.in_value);
503 /* LOG_DEBUG("FLUSHING QUEUE"); */
504 result = jtag_execute_queue();
505 if (result == ERROR_OK)
514 LOG_USER("%s mismatch", op_name);
519 /* See page 19 of XSVF spec regarding opcode "XSDR" */
522 result = svf_add_statemove(TAP_IDLE);
524 if (runtest_requires_tck)
525 jtag_add_clocks(xruntest);
527 jtag_add_sleep(xruntest);
529 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
530 result = svf_add_statemove(xenddr);
535 LOG_ERROR("unsupported XSETSDRMASKS\n");
540 LOG_ERROR("unsupported XSDRINC\n");
545 LOG_ERROR("unsupported XSDRB\n");
550 LOG_ERROR("unsupported XSDRC\n");
555 LOG_ERROR("unsupported XSDRE\n");
560 LOG_ERROR("unsupported XSDRTDOB\n");
565 LOG_ERROR("unsupported XSDRTDOC\n");
570 LOG_ERROR("unsupported XSDRTDOE\n");
579 if (read(xsvf_fd, &uc, 1) < 0)
585 mystate = xsvf_to_tap(uc);
587 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate));
589 if (mystate == TAP_INVALID) {
590 LOG_ERROR("XSVF: bad XSTATE %02x", uc);
595 /* NOTE: the current state is SVF-stable! */
597 /* no change == NOP */
598 if (mystate == cmd_queue_cur_state
599 && mystate != TAP_RESET)
602 /* Hand off to SVF? */
603 if (svf_tap_state_is_stable(mystate))
605 result = svf_add_statemove(mystate);
606 if (result != ERROR_OK)
612 * A sequence of XSTATE transitions, each TAP
613 * state adjacent to the previous one. Start
616 collecting_path = true;
624 if (read(xsvf_fd, &uc, 1) < 0)
630 /* see page 22 of XSVF spec */
634 xendir = TAP_IRPAUSE;
637 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
642 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
647 if (read(xsvf_fd, &uc, 1) < 0)
653 /* see page 22 of XSVF spec */
657 xenddr = TAP_DRPAUSE;
660 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
665 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
671 uint8_t short_buf[2];
674 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
678 /* one byte bitcount */
679 if (read(xsvf_fd, short_buf, 1) < 0)
684 bitcount = short_buf[0];
685 LOG_DEBUG("XSIR %d", bitcount);
689 if (read(xsvf_fd, short_buf, 2) < 0)
694 bitcount = be_to_h_u16(short_buf);
695 LOG_DEBUG("XSIR2 %d", bitcount);
698 ir_buf = malloc((bitcount + 7) / 8);
700 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
707 field.num_bits = bitcount;
708 field.out_value = ir_buf;
710 field.in_value = NULL;
716 jtag_add_plain_ir_scan(1, &field, my_end_state);
718 jtag_add_ir_scan(1, &field, my_end_state);
722 if (runtest_requires_tck)
723 jtag_add_clocks(xruntest);
725 jtag_add_sleep(xruntest);
728 /* Note that an -irmask of non-zero in your config file
729 * can cause this to fail. Setting -irmask to zero cand work
730 * around the problem.
733 /* LOG_DEBUG("FLUSHING QUEUE"); */
734 result = jtag_execute_queue();
735 if (result != ERROR_OK)
746 unsigned int ndx = 0;
751 if (read(xsvf_fd, &uc, 1) < 0)
757 if (ndx < sizeof(comment)-1)
762 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
764 LOG_USER("# %s", comment);
770 /* expected in stream:
771 XWAIT <uint8_t wait_state> <uint8_t end_state> <uint32_t usecs>
776 uint8_t delay_buf[4];
778 tap_state_t wait_state;
779 tap_state_t end_state;
782 if (read(xsvf_fd, &wait, 1) < 0
783 || read(xsvf_fd, &end, 1) < 0
784 || read(xsvf_fd, delay_buf, 4) < 0)
790 wait_state = xsvf_to_tap(wait);
791 end_state = xsvf_to_tap(end);
792 delay = be_to_h_u32(delay_buf);
794 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(wait_state), tap_state_name(end_state), delay);
796 if (runtest_requires_tck && wait_state == TAP_IDLE)
798 jtag_add_runtest(delay, end_state);
802 /* FIXME handle statemove errors ... */
803 result = svf_add_statemove(wait_state);
804 jtag_add_sleep(delay);
805 result = svf_add_statemove(end_state);
812 /* expected in stream:
813 XWAITSTATE <uint8_t wait_state> <uint8_t end_state> <uint32_t clock_count> <uint32_t usecs>
816 uint8_t clock_buf[4];
817 uint8_t usecs_buf[4];
820 tap_state_t wait_state;
821 tap_state_t end_state;
825 if (read(xsvf_fd, &wait, 1) < 0
826 || read(xsvf_fd, &end, 1) < 0
827 || read(xsvf_fd, clock_buf, 4) < 0
828 || read(xsvf_fd, usecs_buf, 4) < 0)
834 wait_state = xsvf_to_tap(wait);
835 end_state = xsvf_to_tap(end);
837 clock_count = be_to_h_u32(clock_buf);
838 usecs = be_to_h_u32(usecs_buf);
840 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
841 tap_state_name(wait_state),
842 tap_state_name(end_state),
845 /* the following states are 'stable', meaning that they have a transition
846 * in the state diagram back to themselves. This is necessary because we will
847 * be issuing a number of clocks in this state. This set of allowed states is also
848 * determined by the SVF RUNTEST command's allowed states.
850 if (!svf_tap_state_is_stable(wait_state))
852 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"",
853 tap_state_name(wait_state));
855 /* REVISIT "break" so we won't run? */
858 /* FIXME handle statemove errors ... */
859 result = svf_add_statemove(wait_state);
861 jtag_add_clocks(clock_count);
863 jtag_add_sleep(usecs);
865 result = svf_add_statemove(end_state);
871 /* expected in stream:
872 LCOUNT <uint32_t loop_count>
874 uint8_t count_buf[4];
876 if (read(xsvf_fd, count_buf, 4) < 0)
882 loop_count = be_to_h_u32(count_buf);
883 LOG_DEBUG("LCOUNT %d", loop_count);
889 /* expected in stream:
890 LDELAY <uint8_t wait_state> <uint32_t clock_count> <uint32_t usecs_to_sleep>
893 uint8_t clock_buf[4];
894 uint8_t usecs_buf[4];
896 if (read(xsvf_fd, &state, 1) < 0
897 || read(xsvf_fd, clock_buf, 4) < 0
898 || read(xsvf_fd, usecs_buf, 4) < 0)
904 /* NOTE: loop_state must be stable! */
905 loop_state = xsvf_to_tap(state);
906 loop_clocks = be_to_h_u32(clock_buf);
907 loop_usecs = be_to_h_u32(usecs_buf);
909 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
913 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
914 * comes with clocks !AND! sleep requirements.
918 int limit = loop_count;
924 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
925 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK)
934 for (attempt = 0; attempt < limit; ++attempt)
938 result = svf_add_statemove(loop_state);
939 jtag_add_clocks(loop_clocks);
940 jtag_add_sleep(loop_usecs);
943 field.num_bits = xsdrsize;
944 field.out_value = dr_out_buf;
945 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
947 if (attempt > 0 && verbose)
948 LOG_USER("LSDR retry %d", attempt);
951 jtag_add_plain_dr_scan(1, &field, jtag_set_end_state(TAP_DRPAUSE));
953 jtag_add_dr_scan(1, &field, jtag_set_end_state(TAP_DRPAUSE));
955 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
957 free(field.in_value);
960 /* LOG_DEBUG("FLUSHING QUEUE"); */
961 result = jtag_execute_queue();
962 if (result == ERROR_OK)
971 LOG_USER("LSDR mismatch");
982 if (read(xsvf_fd, &trst_mode, 1) < 0)
991 jtag_add_reset(1, 0);
995 jtag_add_reset(0, 0);
1000 LOG_ERROR("XTRST mode argument (0x%02X) out of range", trst_mode);
1007 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
1011 if (do_abort || unsupported || tdo_mismatch)
1013 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
1015 /* upon error, return the TAPs to a reasonable state */
1016 result = svf_add_statemove(TAP_IDLE);
1017 result = jtag_execute_queue();
1024 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
1033 off_t offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
1034 command_print(cmd_ctx,
1035 "unsupported xsvf command (0x%02X) at offset %jd, aborting",
1036 uc, (intmax_t)offset);
1042 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
1057 command_print(cmd_ctx, "XSVF file programmed successfully");
1063 #if 0 /* this comment style used to try and keep uncrustify from adding * at begin of line */
1065 PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
1067 the following pseudo code clarifies the intent of the xrepeat support. The
1068 flow given is for the entire processing of an SVF file, not an XSVF file.
1069 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1071 "Pseudo-Code Algorithm for SVF-Based ISP"
1073 1. Go to Test-Logic-Reset state
1074 2. Go to Run-Test Idle state
1077 4. if SIR record then
1078 go to Shift-IR state
1081 5. else if SDR record then
1082 set <repeat count> to 0
1083 store <TDI value> as <current TDI value>
1084 store <TDO value> as <current TDO value>
1085 6. go to Shift-DR state
1086 scan in <current TDI value>
1087 if <current TDO value> is specified then
1088 if <current TDO value> does not equal <actual TDO value> then
1089 if <repeat count> > 32 then
1091 go to Run-Test Idle state
1100 increment <repeat count> by 1
1101 pause <current pause time> microseconds
1105 go to Run-Test Idle state
1108 else if RUNTEST record then
1109 pause tester for <TCK value> microseconds
1110 store <TCK value> as <current pause time>