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 *
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 %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);
625 if (read(xsvf_fd, &uc, 1) < 0)
631 /* see page 22 of XSVF spec */
632 mystate = uc == 1 ? TAP_IRPAUSE : TAP_IDLE;
634 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(mystate));
636 /* assuming that the XRUNTEST comes from SVF RUNTEST, then only these states
637 * should come here because the SVF spec only allows these with a RUNTEST
639 if (mystate != TAP_IRPAUSE && mystate != TAP_DRPAUSE && mystate != TAP_RESET && mystate != TAP_IDLE )
641 LOG_ERROR("illegal XENDIR endstate: \"%s\"", tap_state_name(mystate));
653 if (read(xsvf_fd, &uc, 1) < 0)
659 /* see page 22 of XSVF spec */
660 mystate = uc == 1 ? TAP_DRPAUSE : TAP_IDLE;
662 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(mystate));
664 if (mystate != TAP_IRPAUSE && mystate != TAP_DRPAUSE && mystate != TAP_RESET && mystate != TAP_IDLE )
666 LOG_ERROR("illegal XENDDR endstate: \"%s\"", tap_state_name( mystate ));
680 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
684 /* one byte bitcount */
685 if (read(xsvf_fd, short_buf, 1) < 0)
690 bitcount = short_buf[0];
691 LOG_DEBUG("XSIR %d", bitcount);
695 if (read(xsvf_fd, short_buf, 2) < 0)
700 bitcount = be_to_h_u16(short_buf);
701 LOG_DEBUG("XSIR2 %d", bitcount);
704 ir_buf = malloc((bitcount+7) / 8);
706 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
713 field.num_bits = bitcount;
714 field.out_value = ir_buf;
715 field.out_mask = NULL;
716 field.in_value = NULL;
717 field.in_check_value = NULL;
718 field.in_check_mask = NULL;
719 field.in_handler = NULL;
720 field.in_handler_priv = NULL;
723 jtag_add_plain_ir_scan(1, &field, my_end_state);
725 jtag_add_ir_scan(1, &field, my_end_state);
729 if (runtest_requires_tck)
730 jtag_add_clocks(xruntest);
732 jtag_add_sleep(xruntest);
735 /* Note that an -irmask of non-zero in your config file
736 * can cause this to fail. Setting -irmask to zero cand work
737 * around the problem.
740 /* LOG_DEBUG("FLUSHING QUEUE"); */
741 result = jtag_execute_queue();
742 if(result != ERROR_OK)
758 if (read(xsvf_fd, &uc, 1) < 0)
764 if ( ndx < sizeof(comment)-1 )
769 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
777 /* expected in stream:
778 XWAIT <u8 wait_state> <u8 end_state> <u32 usecs>
785 tap_state_t wait_state;
786 tap_state_t end_state;
789 if ( read(xsvf_fd, &wait, 1) < 0
790 || read(xsvf_fd, &end, 1) < 0
791 || read(xsvf_fd, delay_buf, 4) < 0)
797 wait_state = xsvf_to_tap(wait);
798 end_state = xsvf_to_tap(end);
799 delay = be_to_h_u32(delay_buf);
801 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(wait_state), tap_state_name(end_state), delay);
803 if (runtest_requires_tck && wait_state == TAP_IDLE )
805 jtag_add_runtest(delay, end_state);
809 xsvf_add_statemove( wait_state );
810 jtag_add_sleep(delay);
811 xsvf_add_statemove( end_state );
818 /* expected in stream:
819 XWAITSTATE <u8 wait_state> <u8 end_state> <u32 clock_count> <u32 usecs>
826 tap_state_t wait_state;
827 tap_state_t end_state;
831 if ( read(xsvf_fd, &wait, 1) < 0
832 || read(xsvf_fd, &end, 1) < 0
833 || read(xsvf_fd, clock_buf, 4) < 0
834 || read(xsvf_fd, usecs_buf, 4) < 0 )
840 wait_state = xsvf_to_tap( wait );
841 end_state = xsvf_to_tap( end );
843 clock_count = be_to_h_u32(clock_buf);
844 usecs = be_to_h_u32(usecs_buf);
846 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
847 tap_state_name(wait_state),
848 tap_state_name(end_state),
851 /* the following states are 'stable', meaning that they have a transition
852 * in the state diagram back to themselves. This is necessary because we will
853 * be issuing a number of clocks in this state. This set of allowed states is also
854 * determined by the SVF RUNTEST command's allowed states.
856 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
858 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", tap_state_name( wait_state ));
862 xsvf_add_statemove( wait_state );
864 jtag_add_clocks( clock_count );
866 jtag_add_sleep( usecs );
868 xsvf_add_statemove( end_state );
874 /* expected in stream:
875 LCOUNT <u32 loop_count>
879 if ( read(xsvf_fd, count_buf, 4) < 0 )
885 loop_count = be_to_h_u32(count_buf);
886 LOG_DEBUG("LCOUNT %d", loop_count);
892 /* expected in stream:
893 LDELAY <u8 wait_state> <u32 clock_count> <u32 usecs_to_sleep>
899 if ( read(xsvf_fd, &state, 1) < 0
900 || read(xsvf_fd, clock_buf, 4) < 0
901 || read(xsvf_fd, usecs_buf, 4) < 0 )
907 loop_state = xsvf_to_tap(state);
908 loop_clocks = be_to_h_u32(clock_buf);
909 loop_usecs = be_to_h_u32(usecs_buf);
911 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
915 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
916 * comes with clocks !AND! sleep requirements.
920 int limit = loop_count;
926 if ( xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
927 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
936 for( attempt=0; attempt<limit; ++attempt )
940 xsvf_add_statemove( loop_state );
941 jtag_add_clocks(loop_clocks);
942 jtag_add_sleep(loop_usecs);
945 field.num_bits = xsdrsize;
946 field.out_value = dr_out_buf;
947 field.out_mask = NULL;
948 field.in_value = NULL;
950 if (attempt > 0 && verbose)
951 LOG_USER("LSDR retry %d", attempt);
953 jtag_set_check_value(&field, dr_in_buf, dr_in_mask, NULL);
955 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
957 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
959 /* LOG_DEBUG("FLUSHING QUEUE"); */
960 result = jtag_execute_queue();
961 if(result == ERROR_OK)
970 LOG_USER( "LSDR mismatch" );
981 if (read(xsvf_fd, &trst_mode, 1) < 0)
990 jtag_add_reset(1, 0);
994 jtag_add_reset(0, 0);
999 LOG_ERROR( "XTRST mode argument (0x%02X) out of range", trst_mode );
1006 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
1010 if (do_abort || unsupported || tdo_mismatch)
1012 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
1014 /* upon error, return the TAPs to a reasonable state */
1015 xsvf_add_statemove( TAP_IDLE );
1016 jtag_execute_queue();
1023 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
1032 command_print(cmd_ctx,
1033 "unsupported xsvf command: 0x%02X in xsvf file at offset %ld, aborting",
1034 uc, lseek(xsvf_fd, 0, SEEK_CUR)-1 );
1040 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
1055 command_print(cmd_ctx, "XSVF file programmed successfully");
1061 /* PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
1063 the following pseudo code clarifies the intent of the xrepeat support. The
1064 flow given is for the entire processing of an SVF file, not an XSVF file.
1065 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1067 "Pseudo-Code Algorithm for SVF-Based ISP"
1069 1. Go to Test-Logic-Reset state
1070 2. Go to Run-Test Idle state
1073 4. if SIR record then
1074 go to Shift-IR state
1077 5. else if SDR record then
1078 set <repeat count> to 0
1079 store <TDI value> as <current TDI value>
1080 store <TDO value> as <current TDO value>
1081 6. go to Shift-DR state
1082 scan in <current TDI value>
1083 if <current TDO value> is specified then
1084 if <current TDO value> does not equal <actual TDO value> then
1085 if <repeat count> > 32 then
1087 go to Run-Test Idle state
1096 increment <repeat count> by 1
1097 pause <current pause time> microseconds
1101 go to Run-Test Idle state
1104 else if RUNTEST record then
1105 pause tester for <TCK value> microseconds
1106 store <TCK value> as <current pause time>