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".
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 * Function xsvf_add_statemove
165 * moves from the current state to the goal \a state. This needs
166 * to be handled according to the xsvf spec, see the XSTATE command
169 static int xsvf_add_statemove(tap_state_t goal_state)
171 int retval = ERROR_OK;
173 tap_state_t moves[8];
174 tap_state_t cur_state = cmd_queue_cur_state;
179 LOG_DEBUG( "cur_state=%s goal_state=%s",
180 tap_state_name(cur_state),
181 tap_state_name(goal_state) );
184 /* From the XSVF spec, pertaining to XSTATE:
186 For special states known as stable states (Test-Logic-Reset,
187 Run-Test/Idle, Pause-DR, Pause- IR), an XSVF interpreter follows
188 predefined TAP state paths when the starting state is a stable state and
189 when the XSTATE specifies a new stable state (see the STATE command in
190 the [Ref 5] for the TAP state paths between stable states). For
191 non-stable states, XSTATE should specify a state that is only one TAP
192 state transition distance from the current TAP state to avoid undefined
193 TAP state paths. A sequence of multiple XSTATE commands can be issued to
194 transition the TAP through a specific state path.
197 if (goal_state==cur_state )
198 ; /* nothing to do */
200 else if( goal_state==TAP_RESET )
205 else if( tap_is_state_stable(cur_state) && tap_is_state_stable(goal_state) )
207 /* note: unless tms_bits holds a path that agrees with [Ref 5] in above
208 spec, then this code is not fully conformant to the xsvf spec. This
209 puts a burden on tap_get_tms_path() function from the xsvf spec.
210 If in doubt, you should confirm that that burden is being met.
213 tms_bits = tap_get_tms_path(cur_state, goal_state);
214 tms_count = tap_get_tms_path_len(cur_state, goal_state);
216 assert( (unsigned) tms_count < DIM(moves) );
218 for (i=0; i<tms_count; i++, tms_bits>>=1)
220 bool bit = tms_bits & 1;
222 cur_state = tap_state_transition(cur_state, bit);
223 moves[i] = cur_state;
226 jtag_add_pathmove(tms_count, moves);
229 /* else state must be immediately reachable in one clock cycle, and does not
230 need to be a stable state.
232 else if( tap_state_transition(cur_state, true) == goal_state
233 || tap_state_transition(cur_state, false) == goal_state )
235 /* move a single state */
236 moves[0] = goal_state;
237 jtag_add_pathmove( 1, moves );
249 int xsvf_register_commands(struct command_context_s *cmd_ctx)
251 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
252 COMMAND_EXEC, "run xsvf <file> [virt2] [quiet]");
257 static int xsvf_read_buffer(int num_bits, int fd, u8* buf)
261 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
263 /* reverse the order of bytes as they are read sequentially from file */
264 if (read(fd, buf + num_bytes - 1, 1) < 0)
265 return ERROR_XSVF_EOF;
272 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
274 u8 *dr_out_buf = NULL; /* from host to device (TDI) */
275 u8 *dr_in_buf = NULL; /* from device to host (TDO) */
276 u8 *dr_in_mask = NULL;
279 int xruntest = 0; /* number of TCK cycles OR microseconds */
280 int xrepeat = 0; /* number of retries */
282 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
283 tap_state_t xenddr = TAP_IDLE;
287 long file_offset = 0;
290 tap_state_t loop_state = TAP_IDLE;
296 int tdo_mismatch = 0;
301 int runtest_requires_tck = 0; /* a flag telling whether to clock TCK during waits, or simply sleep, controled by virt2 */
304 /* use NULL to indicate a "plain" xsvf file which accounts for
305 additional devices in the scan chain, otherwise the device
306 that should be affected
308 jtag_tap_t *tap = NULL;
312 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> [<variant>] [quiet]");
316 filename = args[1]; /* we mess with args starting point below, snapshot filename here */
318 if (strcmp(args[0], "plain") != 0)
320 tap = jtag_TapByString( args[0] );
323 command_print( cmd_ctx, "Tap: %s unknown", args[0] );
328 if ((xsvf_fd = open(filename, O_RDONLY)) < 0)
330 command_print(cmd_ctx, "file \"%s\" not found", filename);
334 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
335 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
337 runtest_requires_tck = 1;
342 if ((argc > 2) && (strcmp(args[2], "quiet") == 0))
347 LOG_USER("xsvf processing file: \"%s\"", filename);
349 while( read(xsvf_fd, &opcode, 1) > 0 )
351 /* record the position of the just read opcode within the file */
352 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
357 LOG_DEBUG("XCOMPLETE");
359 result = jtag_execute_queue();
360 if (result != ERROR_OK)
368 LOG_DEBUG("XTDOMASK");
369 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
377 if (read(xsvf_fd, xruntest_buf, 4) < 0)
383 xruntest = be_to_h_u32(xruntest_buf);
384 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
392 if (read(xsvf_fd, &myrepeat, 1) < 0)
397 LOG_DEBUG("XREPEAT %d", xrepeat );
406 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
412 xsdrsize = be_to_h_u32(xsdrsize_buf);
413 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
415 if( dr_out_buf ) free(dr_out_buf);
416 if( dr_in_buf) free(dr_in_buf);
417 if( dr_in_mask) free(dr_in_mask);
419 dr_out_buf = malloc((xsdrsize + 7) / 8);
420 dr_in_buf = malloc((xsdrsize + 7) / 8);
421 dr_in_mask = malloc((xsdrsize + 7) / 8);
425 case XSDR: /* these two are identical except for the dr_in_buf */
432 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
434 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
440 if (opcode == XSDRTDO)
442 if(xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
452 LOG_DEBUG("%s %d", op_name, xsdrsize);
454 for( attempt=0; attempt<limit; ++attempt )
460 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
461 illustrated in psuedo code at end of this file. We start from state
469 This sequence should be harmless for other devices, and it
470 will be skipped entirely if xrepeat is set to zero.
473 static tap_state_t exception_path[] = {
481 jtag_add_pathmove( DIM(exception_path), exception_path );
484 LOG_USER("%s mismatch, xsdrsize=%d retry=%d", op_name, xsdrsize, attempt);
488 field.num_bits = xsdrsize;
489 field.out_value = dr_out_buf;
490 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
493 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
495 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
497 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
499 free(field.in_value);
502 /* LOG_DEBUG("FLUSHING QUEUE"); */
503 result = jtag_execute_queue();
504 if (result == ERROR_OK)
513 LOG_USER( "%s mismatch", op_name);
518 /* See page 19 of XSVF spec regarding opcode "XSDR" */
521 xsvf_add_statemove(TAP_IDLE);
523 if (runtest_requires_tck)
524 jtag_add_clocks(xruntest);
526 jtag_add_sleep(xruntest);
528 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
529 xsvf_add_statemove(xenddr);
534 LOG_ERROR("unsupported XSETSDRMASKS\n");
539 LOG_ERROR("unsupported XSDRINC\n");
544 LOG_ERROR("unsupported XSDRB\n");
549 LOG_ERROR("unsupported XSDRC\n");
554 LOG_ERROR("unsupported XSDRE\n");
559 LOG_ERROR("unsupported XSDRTDOB\n");
564 LOG_ERROR("unsupported XSDRTDOC\n");
569 LOG_ERROR("unsupported XSDRTDOE\n");
578 if (read(xsvf_fd, &uc, 1) < 0)
584 mystate = xsvf_to_tap(uc);
586 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate) );
588 /* there is no need for the lookahead code that was here since we
589 queue up the jtag commands anyway. This is a simple way to handle
593 if( xsvf_add_statemove( mystate ) != ERROR_OK )
595 /* For special states known as stable states
596 (Test-Logic-Reset, Run-Test/Idle, Pause-DR, Pause- IR),
597 an XSVF interpreter follows predefined TAP state paths
598 when the starting state is a stable state and when the
599 XSTATE specifies a new stable state (see the STATE
600 command in the [Ref 5] for the TAP state paths between
601 stable states). For non-stable states, XSTATE should
602 specify a state that is only one TAP state transition
603 distance from the current TAP state to avoid undefined
604 TAP state paths. A sequence of multiple XSTATE commands
605 can be issued to transition the TAP through a specific
609 LOG_ERROR("XSTATE %s is not reachable from current state %s in one clock cycle",
610 tap_state_name(mystate),
611 tap_state_name(cmd_queue_cur_state)
619 if (read(xsvf_fd, &uc, 1) < 0)
625 /* see page 22 of XSVF spec */
629 xendir = TAP_IRPAUSE;
632 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
637 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
642 if (read(xsvf_fd, &uc, 1) < 0)
648 /* see page 22 of XSVF spec */
652 xenddr = TAP_DRPAUSE;
655 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
660 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
669 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
673 /* one byte bitcount */
674 if (read(xsvf_fd, short_buf, 1) < 0)
679 bitcount = short_buf[0];
680 LOG_DEBUG("XSIR %d", bitcount);
684 if (read(xsvf_fd, short_buf, 2) < 0)
689 bitcount = be_to_h_u16(short_buf);
690 LOG_DEBUG("XSIR2 %d", bitcount);
693 ir_buf = malloc((bitcount+7) / 8);
695 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
702 field.num_bits = bitcount;
703 field.out_value = ir_buf;
705 field.in_value = NULL;
711 jtag_add_plain_ir_scan(1, &field, my_end_state);
713 jtag_add_ir_scan(1, &field, my_end_state);
717 if (runtest_requires_tck)
718 jtag_add_clocks(xruntest);
720 jtag_add_sleep(xruntest);
723 /* Note that an -irmask of non-zero in your config file
724 * can cause this to fail. Setting -irmask to zero cand work
725 * around the problem.
728 /* LOG_DEBUG("FLUSHING QUEUE"); */
729 result = jtag_execute_queue();
730 if(result != ERROR_OK)
741 unsigned int ndx = 0;
746 if (read(xsvf_fd, &uc, 1) < 0)
752 if ( ndx < sizeof(comment)-1 )
757 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
759 LOG_USER("# %s", comment);
765 /* expected in stream:
766 XWAIT <u8 wait_state> <u8 end_state> <u32 usecs>
773 tap_state_t wait_state;
774 tap_state_t end_state;
777 if ( read(xsvf_fd, &wait, 1) < 0
778 || read(xsvf_fd, &end, 1) < 0
779 || read(xsvf_fd, delay_buf, 4) < 0)
785 wait_state = xsvf_to_tap(wait);
786 end_state = xsvf_to_tap(end);
787 delay = be_to_h_u32(delay_buf);
789 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(wait_state), tap_state_name(end_state), delay);
791 if (runtest_requires_tck && wait_state == TAP_IDLE )
793 jtag_add_runtest(delay, end_state);
797 xsvf_add_statemove( wait_state );
798 jtag_add_sleep(delay);
799 xsvf_add_statemove( end_state );
806 /* expected in stream:
807 XWAITSTATE <u8 wait_state> <u8 end_state> <u32 clock_count> <u32 usecs>
814 tap_state_t wait_state;
815 tap_state_t end_state;
819 if ( read(xsvf_fd, &wait, 1) < 0
820 || read(xsvf_fd, &end, 1) < 0
821 || read(xsvf_fd, clock_buf, 4) < 0
822 || read(xsvf_fd, usecs_buf, 4) < 0 )
828 wait_state = xsvf_to_tap( wait );
829 end_state = xsvf_to_tap( end );
831 clock_count = be_to_h_u32(clock_buf);
832 usecs = be_to_h_u32(usecs_buf);
834 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
835 tap_state_name(wait_state),
836 tap_state_name(end_state),
839 /* the following states are 'stable', meaning that they have a transition
840 * in the state diagram back to themselves. This is necessary because we will
841 * be issuing a number of clocks in this state. This set of allowed states is also
842 * determined by the SVF RUNTEST command's allowed states.
844 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
846 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", tap_state_name( wait_state ));
850 xsvf_add_statemove( wait_state );
852 jtag_add_clocks( clock_count );
854 jtag_add_sleep( usecs );
856 xsvf_add_statemove( end_state );
862 /* expected in stream:
863 LCOUNT <u32 loop_count>
867 if ( read(xsvf_fd, count_buf, 4) < 0 )
873 loop_count = be_to_h_u32(count_buf);
874 LOG_DEBUG("LCOUNT %d", loop_count);
880 /* expected in stream:
881 LDELAY <u8 wait_state> <u32 clock_count> <u32 usecs_to_sleep>
887 if ( read(xsvf_fd, &state, 1) < 0
888 || read(xsvf_fd, clock_buf, 4) < 0
889 || read(xsvf_fd, usecs_buf, 4) < 0 )
895 loop_state = xsvf_to_tap(state);
896 loop_clocks = be_to_h_u32(clock_buf);
897 loop_usecs = be_to_h_u32(usecs_buf);
899 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
903 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
904 * comes with clocks !AND! sleep requirements.
908 int limit = loop_count;
914 if ( xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
915 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
924 for( attempt=0; attempt<limit; ++attempt )
928 xsvf_add_statemove( loop_state );
929 jtag_add_clocks(loop_clocks);
930 jtag_add_sleep(loop_usecs);
933 field.num_bits = xsdrsize;
934 field.out_value = dr_out_buf;
935 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
937 if (attempt > 0 && verbose)
938 LOG_USER("LSDR retry %d", attempt);
941 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
943 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
945 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
947 free(field.in_value);
950 /* LOG_DEBUG("FLUSHING QUEUE"); */
951 result = jtag_execute_queue();
952 if(result == ERROR_OK)
961 LOG_USER( "LSDR mismatch" );
972 if (read(xsvf_fd, &trst_mode, 1) < 0)
981 jtag_add_reset(1, 0);
985 jtag_add_reset(0, 0);
990 LOG_ERROR( "XTRST mode argument (0x%02X) out of range", trst_mode );
997 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
1001 if (do_abort || unsupported || tdo_mismatch)
1003 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
1005 /* upon error, return the TAPs to a reasonable state */
1006 xsvf_add_statemove( TAP_IDLE );
1007 jtag_execute_queue();
1014 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
1023 command_print(cmd_ctx,
1024 "unsupported xsvf command: 0x%02X in xsvf file at offset %ld, aborting",
1025 uc, lseek(xsvf_fd, 0, SEEK_CUR)-1 );
1031 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
1046 command_print(cmd_ctx, "XSVF file programmed successfully");
1052 #if 0 /* this comment style used to try and keep uncrustify from adding * at begin of line */
1054 PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
1056 the following pseudo code clarifies the intent of the xrepeat support. The
1057 flow given is for the entire processing of an SVF file, not an XSVF file.
1058 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1060 "Pseudo-Code Algorithm for SVF-Based ISP"
1062 1. Go to Test-Logic-Reset state
1063 2. Go to Run-Test Idle state
1066 4. if SIR record then
1067 go to Shift-IR state
1070 5. else if SDR record then
1071 set <repeat count> to 0
1072 store <TDI value> as <current TDI value>
1073 store <TDO value> as <current TDO value>
1074 6. go to Shift-DR state
1075 scan in <current TDI value>
1076 if <current TDO value> is specified then
1077 if <current TDO value> does not equal <actual TDO value> then
1078 if <repeat count> > 32 then
1080 go to Run-Test Idle state
1089 increment <repeat count> by 1
1090 pause <current pause time> microseconds
1094 go to Run-Test Idle state
1097 else if RUNTEST record then
1098 pause tester for <TCK value> microseconds
1099 store <TCK value> as <current pause time>