1 /***************************************************************************
2 * Copyright (C) 2005 by Dominic Rath *
3 * Dominic.Rath@gmx.de *
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 *
26 * Free Software Foundation, Inc., *
27 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
28 ***************************************************************************/
31 /* The specification for SVF is available here:
32 * http://www.asset-intertech.com/support/svf.pdf
33 * Below, this document is refered to as the "SVF spec".
35 * The specification for XSVF is available here:
36 * http://www.xilinx.com/support/documentation/application_notes/xapp503.pdf
37 * Below, this document is refered to as the "XSVF spec".
52 #include <sys/types.h>
61 /* XSVF commands, from appendix B of xapp503.pdf */
62 #define XCOMPLETE 0x00
70 #define XSETSDRMASKS 0x0A
85 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
86 * generates this. Arguably it is needed because the XSVF XRUNTEST command
87 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
88 * This XWAITSTATE does map directly from the SVF RUNTEST command.
90 #define XWAITSTATE 0x18
92 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
93 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
94 * Here is an example of usage of the 3 lattice opcode extensions:
96 ! Set the maximum loop count to 25.
98 ! Step to DRPAUSE give 5 clocks and wait for 1.00e+000 SEC.
99 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
100 ! Test for the completed status. Match means pass.
101 ! Loop back to LDELAY line if not match and loop count less than 25.
113 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
114 #define XSV_RESET 0x00
115 #define XSV_IDLE 0x01
116 #define XSV_DRSELECT 0x02
117 #define XSV_DRCAPTURE 0x03
118 #define XSV_DRSHIFT 0x04
119 #define XSV_DREXIT1 0x05
120 #define XSV_DRPAUSE 0x06
121 #define XSV_DREXIT2 0x07
122 #define XSV_DRUPDATE 0x08
123 #define XSV_IRSELECT 0x09
124 #define XSV_IRCAPTURE 0x0A
125 #define XSV_IRSHIFT 0x0B
126 #define XSV_IREXIT1 0x0C
127 #define XSV_IRPAUSE 0x0D
128 #define XSV_IREXIT2 0x0E
129 #define XSV_IRUPDATE 0x0F
131 /* arguments to XTRST */
135 #define XTRST_ABSENT 3
137 #define XSTATE_MAX_PATH 12
139 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc);
141 static int xsvf_fd = 0;
144 /* map xsvf tap state to an openocd "tap_state_t" */
145 static tap_state_t xsvf_to_tap( int xsvf_state )
151 case XSV_RESET: ret = TAP_RESET; break;
152 case XSV_IDLE: ret = TAP_IDLE; break;
153 case XSV_DRSELECT: ret = TAP_DRSELECT; break;
154 case XSV_DRCAPTURE: ret = TAP_DRCAPTURE; break;
155 case XSV_DRSHIFT: ret = TAP_DRSHIFT; break;
156 case XSV_DREXIT1: ret = TAP_DREXIT1; break;
157 case XSV_DRPAUSE: ret = TAP_DRPAUSE; break;
158 case XSV_DREXIT2: ret = TAP_DREXIT2; break;
159 case XSV_DRUPDATE: ret = TAP_DRUPDATE; break;
160 case XSV_IRSELECT: ret = TAP_IRSELECT; break;
161 case XSV_IRCAPTURE: ret = TAP_IRCAPTURE; break;
162 case XSV_IRSHIFT: ret = TAP_IRSHIFT; break;
163 case XSV_IREXIT1: ret = TAP_IREXIT1; break;
164 case XSV_IRPAUSE: ret = TAP_IRPAUSE; break;
165 case XSV_IREXIT2: ret = TAP_IREXIT2; break;
166 case XSV_IRUPDATE: ret = TAP_IRUPDATE; break;
168 LOG_ERROR( "UNKNOWN XSVF STATE 0x%02X", xsvf_state );
176 /* xsvf has it's own definition of a statemove. This needs
177 * to be handled according to the xsvf spec, which has nothing
178 * to do with the JTAG spec or OpenOCD as such.
180 * Implemented via jtag_add_pathmove().
182 static void xsvf_add_statemove(tap_state_t state)
184 tap_state_t moves[7]; /* max # of transitions */
185 tap_state_t curstate = cmd_queue_cur_state;
188 u8 move = tap_get_tms_path(cmd_queue_cur_state, state);
190 if (state != TAP_RESET && state==cmd_queue_cur_state)
201 int j = (move >> i) & 1;
204 curstate = tap_state_transition(curstate, true);
208 curstate = tap_state_transition(curstate, false);
213 jtag_add_pathmove(7, moves);
216 int xsvf_register_commands(struct command_context_s *cmd_ctx)
218 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
219 COMMAND_EXEC, "run xsvf <file> [virt2] [quiet]");
224 static int xsvf_read_buffer(int num_bits, int fd, u8* buf)
228 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
230 /* reverse the order of bytes as they are read sequentially from file */
231 if (read(fd, buf + num_bytes - 1, 1) < 0)
232 return ERROR_XSVF_EOF;
239 static int xsvf_read_xstates(int fd, tap_state_t *path, int max_path, int *path_len)
244 while ((read(fd, &c, 1) > 0) && (c == XSTATE))
248 if (*path_len > max_path)
250 LOG_WARNING("XSTATE path longer than max_path");
253 if (read(fd, &uc, 1) < 0)
255 return ERROR_XSVF_EOF;
258 mystate = xsvf_to_tap(uc);
260 LOG_DEBUG("XSTATE %02X %s", uc, tap_state_name(mystate) );
262 path[(*path_len)++] = mystate;
265 lseek(fd, -1, SEEK_CUR);
271 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
273 u8 *dr_out_buf = NULL; /* from host to device (TDI) */
274 u8 *dr_in_buf = NULL; /* from device to host (TDO) */
275 u8 *dr_in_mask = NULL;
278 int xruntest = 0; /* number of TCK cycles OR microseconds */
279 int xrepeat = 0; /* number of retries */
281 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
282 tap_state_t xenddr = TAP_IDLE;
286 long file_offset = 0;
289 tap_state_t loop_state = TAP_IDLE;
295 int tdo_mismatch = 0;
300 int runtest_requires_tck = 0; /* a flag telling whether to clock TCK during waits, or simply sleep, controled by virt2 */
303 /* use NULL to indicate a "plain" xsvf file which accounts for
304 additional devices in the scan chain, otherwise the device
305 that should be affected
307 jtag_tap_t *tap = NULL;
311 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> [<variant>] [quiet]");
315 filename = args[1]; /* we mess with args starting point below, snapshot filename here */
317 if (strcmp(args[0], "plain") != 0)
319 tap = jtag_TapByString( args[0] );
322 command_print( cmd_ctx, "Tap: %s unknown", args[0] );
327 if ((xsvf_fd = open(filename, O_RDONLY)) < 0)
329 command_print(cmd_ctx, "file \"%s\" not found", filename);
333 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
334 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
336 runtest_requires_tck = 1;
341 if ((argc > 2) && (strcmp(args[2], "quiet") == 0))
346 LOG_USER("xsvf processing file: \"%s\"", filename);
348 while( read(xsvf_fd, &opcode, 1) > 0 )
350 /* record the position of the just read opcode within the file */
351 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
356 LOG_DEBUG("XCOMPLETE");
358 result = jtag_execute_queue();
359 if (result != ERROR_OK)
367 LOG_DEBUG("XTDOMASK");
368 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
376 if (read(xsvf_fd, xruntest_buf, 4) < 0)
382 xruntest = be_to_h_u32(xruntest_buf);
383 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
391 if (read(xsvf_fd, &myrepeat, 1) < 0)
396 LOG_DEBUG("XREPEAT %d", xrepeat );
405 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
411 xsdrsize = be_to_h_u32(xsdrsize_buf);
412 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
414 if( dr_out_buf ) free(dr_out_buf);
415 if( dr_in_buf) free(dr_in_buf);
416 if( dr_in_mask) free(dr_in_mask);
418 dr_out_buf = malloc((xsdrsize + 7) / 8);
419 dr_in_buf = malloc((xsdrsize + 7) / 8);
420 dr_in_mask = malloc((xsdrsize + 7) / 8);
424 case XSDR: /* these two are identical except for the dr_in_buf */
431 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
433 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
439 if (opcode == XSDRTDO)
441 if(xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
451 LOG_DEBUG("%s %d", op_name, xsdrsize);
453 for( attempt=0; attempt<limit; ++attempt )
459 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
460 illustrated in psuedo code at end of this file. We start from state
468 This sequence should be harmless for other devices, and it
469 will be skipped entirely if xrepeat is set to zero.
472 static tap_state_t exception_path[] = {
480 jtag_add_pathmove( sizeof(exception_path)/sizeof(exception_path[0]), exception_path);
483 LOG_USER("%s mismatch, xsdrsize=%d retry=%d", op_name, xsdrsize, attempt);
487 field.num_bits = xsdrsize;
488 field.out_value = dr_out_buf;
489 field.out_mask = NULL;
490 field.in_value = NULL;
492 jtag_set_check_value(&field, dr_in_buf, dr_in_mask, NULL);
495 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
497 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
499 /* LOG_DEBUG("FLUSHING QUEUE"); */
500 result = jtag_execute_queue();
501 if (result == ERROR_OK)
510 LOG_USER( "%s mismatch", op_name);
515 /* See page 19 of XSVF spec regarding opcode "XSDR" */
518 xsvf_add_statemove(TAP_IDLE);
520 if (runtest_requires_tck)
521 jtag_add_clocks(xruntest);
523 jtag_add_sleep(xruntest);
525 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
526 xsvf_add_statemove(xenddr);
531 LOG_ERROR("unsupported XSETSDRMASKS\n");
536 LOG_ERROR("unsupported XSDRINC\n");
541 LOG_ERROR("unsupported XSDRB\n");
546 LOG_ERROR("unsupported XSDRC\n");
551 LOG_ERROR("unsupported XSDRE\n");
556 LOG_ERROR("unsupported XSDRTDOB\n");
561 LOG_ERROR("unsupported XSDRTDOC\n");
566 LOG_ERROR("unsupported XSDRTDOE\n");
576 if (read(xsvf_fd, &uc, 1) < 0)
582 mystate = xsvf_to_tap(uc);
584 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate) );
586 path = calloc(XSTATE_MAX_PATH, 4);
590 if (xsvf_read_xstates(xsvf_fd, path, XSTATE_MAX_PATH, &path_len) != ERROR_OK)
596 /* here the trick is that jtag_add_pathmove() must end in a stable
597 * state, so we must only invoke jtag_add_tlr() when we absolutely
600 for(i=0,lasti=0; i<path_len; i++)
602 if(path[i]==TAP_RESET)
606 jtag_add_pathmove(i-lasti,path+lasti);
614 jtag_add_pathmove(i-lasti, path+lasti);
623 if (read(xsvf_fd, &uc, 1) < 0)
629 /* see page 22 of XSVF spec */
633 xendir = TAP_IRPAUSE;
636 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
641 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
646 if (read(xsvf_fd, &uc, 1) < 0)
652 /* see page 22 of XSVF spec */
656 xenddr = TAP_DRPAUSE;
659 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
664 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
673 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
677 /* one byte bitcount */
678 if (read(xsvf_fd, short_buf, 1) < 0)
683 bitcount = short_buf[0];
684 LOG_DEBUG("XSIR %d", bitcount);
688 if (read(xsvf_fd, short_buf, 2) < 0)
693 bitcount = be_to_h_u16(short_buf);
694 LOG_DEBUG("XSIR2 %d", bitcount);
697 ir_buf = malloc((bitcount+7) / 8);
699 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
706 field.num_bits = bitcount;
707 field.out_value = ir_buf;
708 field.out_mask = NULL;
709 field.in_value = NULL;
710 field.in_check_value = NULL;
711 field.in_check_mask = NULL;
712 field.in_handler = NULL;
713 field.in_handler_priv = 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 <u8 wait_state> <u8 end_state> <u32 usecs>
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 xsvf_add_statemove( wait_state );
803 jtag_add_sleep(delay);
804 xsvf_add_statemove( end_state );
811 /* expected in stream:
812 XWAITSTATE <u8 wait_state> <u8 end_state> <u32 clock_count> <u32 usecs>
819 tap_state_t wait_state;
820 tap_state_t end_state;
824 if ( read(xsvf_fd, &wait, 1) < 0
825 || read(xsvf_fd, &end, 1) < 0
826 || read(xsvf_fd, clock_buf, 4) < 0
827 || read(xsvf_fd, usecs_buf, 4) < 0 )
833 wait_state = xsvf_to_tap( wait );
834 end_state = xsvf_to_tap( end );
836 clock_count = be_to_h_u32(clock_buf);
837 usecs = be_to_h_u32(usecs_buf);
839 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
840 tap_state_name(wait_state),
841 tap_state_name(end_state),
844 /* the following states are 'stable', meaning that they have a transition
845 * in the state diagram back to themselves. This is necessary because we will
846 * be issuing a number of clocks in this state. This set of allowed states is also
847 * determined by the SVF RUNTEST command's allowed states.
849 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
851 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", tap_state_name( wait_state ));
855 xsvf_add_statemove( wait_state );
857 jtag_add_clocks( clock_count );
859 jtag_add_sleep( usecs );
861 xsvf_add_statemove( end_state );
867 /* expected in stream:
868 LCOUNT <u32 loop_count>
872 if ( read(xsvf_fd, count_buf, 4) < 0 )
878 loop_count = be_to_h_u32(count_buf);
879 LOG_DEBUG("LCOUNT %d", loop_count);
885 /* expected in stream:
886 LDELAY <u8 wait_state> <u32 clock_count> <u32 usecs_to_sleep>
892 if ( read(xsvf_fd, &state, 1) < 0
893 || read(xsvf_fd, clock_buf, 4) < 0
894 || read(xsvf_fd, usecs_buf, 4) < 0 )
900 loop_state = xsvf_to_tap(state);
901 loop_clocks = be_to_h_u32(clock_buf);
902 loop_usecs = be_to_h_u32(usecs_buf);
904 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
908 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
909 * comes with clocks !AND! sleep requirements.
913 int limit = loop_count;
919 if ( xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
920 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
929 for( attempt=0; attempt<limit; ++attempt )
933 xsvf_add_statemove( loop_state );
934 jtag_add_clocks(loop_clocks);
935 jtag_add_sleep(loop_usecs);
938 field.num_bits = xsdrsize;
939 field.out_value = dr_out_buf;
940 field.out_mask = NULL;
941 field.in_value = NULL;
943 if (attempt > 0 && verbose)
944 LOG_USER("LSDR retry %d", attempt);
946 jtag_set_check_value(&field, dr_in_buf, dr_in_mask, NULL);
948 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
950 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
952 /* LOG_DEBUG("FLUSHING QUEUE"); */
953 result = jtag_execute_queue();
954 if(result == ERROR_OK)
963 LOG_USER( "LSDR mismatch" );
974 if (read(xsvf_fd, &trst_mode, 1) < 0)
983 jtag_add_reset(1, 0);
987 jtag_add_reset(0, 0);
992 LOG_ERROR( "XTRST mode argument (0x%02X) out of range", trst_mode );
999 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
1003 if (do_abort || unsupported || tdo_mismatch)
1005 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
1007 /* upon error, return the TAPs to a reasonable state */
1008 xsvf_add_statemove( TAP_IDLE );
1009 jtag_execute_queue();
1016 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
1025 command_print(cmd_ctx,
1026 "unsupported xsvf command: 0x%02X in xsvf file at offset %ld, aborting",
1027 uc, lseek(xsvf_fd, 0, SEEK_CUR)-1 );
1033 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
1048 command_print(cmd_ctx, "XSVF file programmed successfully");
1054 #if 0 /* this comment style used to try and keep uncrustify from adding * at begin of line */
1056 PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
1058 the following pseudo code clarifies the intent of the xrepeat support. The
1059 flow given is for the entire processing of an SVF file, not an XSVF file.
1060 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1062 "Pseudo-Code Algorithm for SVF-Based ISP"
1064 1. Go to Test-Logic-Reset state
1065 2. Go to Run-Test Idle state
1068 4. if SIR record then
1069 go to Shift-IR state
1072 5. else if SDR record then
1073 set <repeat count> to 0
1074 store <TDI value> as <current TDI value>
1075 store <TDO value> as <current TDO value>
1076 6. go to Shift-DR state
1077 scan in <current TDI value>
1078 if <current TDO value> is specified then
1079 if <current TDO value> does not equal <actual TDO value> then
1080 if <repeat count> > 32 then
1082 go to Run-Test Idle state
1091 increment <repeat count> by 1
1092 pause <current pause time> microseconds
1096 go to Run-Test Idle state
1099 else if RUNTEST record then
1100 pause tester for <TCK value> microseconds
1101 store <TCK value> as <current pause time>