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".
50 /* XSVF commands, from appendix B of xapp503.pdf */
51 #define XCOMPLETE 0x00
59 #define XSETSDRMASKS 0x0A
74 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
75 * generates this. Arguably it is needed because the XSVF XRUNTEST command
76 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
77 * This XWAITSTATE does map directly from the SVF RUNTEST command.
79 #define XWAITSTATE 0x18
81 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
82 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
83 * Here is an example of usage of the 3 lattice opcode extensions:
85 ! Set the maximum loop count to 25.
87 ! Step to DRPAUSE give 5 clocks and wait for 1.00e+000 SEC.
88 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
89 ! Test for the completed status. Match means pass.
90 ! Loop back to LDELAY line if not match and loop count less than 25.
102 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
103 #define XSV_RESET 0x00
104 #define XSV_IDLE 0x01
105 #define XSV_DRSELECT 0x02
106 #define XSV_DRCAPTURE 0x03
107 #define XSV_DRSHIFT 0x04
108 #define XSV_DREXIT1 0x05
109 #define XSV_DRPAUSE 0x06
110 #define XSV_DREXIT2 0x07
111 #define XSV_DRUPDATE 0x08
112 #define XSV_IRSELECT 0x09
113 #define XSV_IRCAPTURE 0x0A
114 #define XSV_IRSHIFT 0x0B
115 #define XSV_IREXIT1 0x0C
116 #define XSV_IRPAUSE 0x0D
117 #define XSV_IREXIT2 0x0E
118 #define XSV_IRUPDATE 0x0F
120 /* arguments to XTRST */
124 #define XTRST_ABSENT 3
126 #define XSTATE_MAX_PATH 12
128 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc);
130 static int xsvf_fd = 0;
133 /* map xsvf tap state to an openocd "tap_state_t" */
134 static tap_state_t xsvf_to_tap( int xsvf_state )
140 case XSV_RESET: ret = TAP_RESET; break;
141 case XSV_IDLE: ret = TAP_IDLE; break;
142 case XSV_DRSELECT: ret = TAP_DRSELECT; break;
143 case XSV_DRCAPTURE: ret = TAP_DRCAPTURE; break;
144 case XSV_DRSHIFT: ret = TAP_DRSHIFT; break;
145 case XSV_DREXIT1: ret = TAP_DREXIT1; break;
146 case XSV_DRPAUSE: ret = TAP_DRPAUSE; break;
147 case XSV_DREXIT2: ret = TAP_DREXIT2; break;
148 case XSV_DRUPDATE: ret = TAP_DRUPDATE; break;
149 case XSV_IRSELECT: ret = TAP_IRSELECT; break;
150 case XSV_IRCAPTURE: ret = TAP_IRCAPTURE; break;
151 case XSV_IRSHIFT: ret = TAP_IRSHIFT; break;
152 case XSV_IREXIT1: ret = TAP_IREXIT1; break;
153 case XSV_IRPAUSE: ret = TAP_IRPAUSE; break;
154 case XSV_IREXIT2: ret = TAP_IREXIT2; break;
155 case XSV_IRUPDATE: ret = TAP_IRUPDATE; break;
157 LOG_ERROR( "UNKNOWN XSVF STATE 0x%02X", xsvf_state );
166 * Function xsvf_add_statemove
167 * moves from the current state to the goal \a state. This needs
168 * to be handled according to the xsvf spec, see the XSTATE command
171 static int xsvf_add_statemove(tap_state_t goal_state)
173 int retval = ERROR_OK;
175 tap_state_t moves[8];
176 tap_state_t cur_state = cmd_queue_cur_state;
181 LOG_DEBUG( "cur_state=%s goal_state=%s",
182 tap_state_name(cur_state),
183 tap_state_name(goal_state) );
186 /* From the XSVF spec, pertaining to XSTATE:
188 For special states known as stable states (Test-Logic-Reset,
189 Run-Test/Idle, Pause-DR, Pause- IR), an XSVF interpreter follows
190 predefined TAP state paths when the starting state is a stable state and
191 when the XSTATE specifies a new stable state (see the STATE command in
192 the [Ref 5] for the TAP state paths between stable states). For
193 non-stable states, XSTATE should specify a state that is only one TAP
194 state transition distance from the current TAP state to avoid undefined
195 TAP state paths. A sequence of multiple XSTATE commands can be issued to
196 transition the TAP through a specific state path.
199 if (goal_state==cur_state )
200 ; /* nothing to do */
202 else if( goal_state==TAP_RESET )
207 else if( tap_is_state_stable(cur_state) && tap_is_state_stable(goal_state) )
209 /* note: unless tms_bits holds a path that agrees with [Ref 5] in above
210 spec, then this code is not fully conformant to the xsvf spec. This
211 puts a burden on tap_get_tms_path() function from the xsvf spec.
212 If in doubt, you should confirm that that burden is being met.
215 tms_bits = tap_get_tms_path(cur_state, goal_state);
216 tms_count = tap_get_tms_path_len(cur_state, goal_state);
218 assert( (unsigned) tms_count < DIM(moves) );
220 for (i=0; i<tms_count; i++, tms_bits>>=1)
222 bool bit = tms_bits & 1;
224 cur_state = tap_state_transition(cur_state, bit);
225 moves[i] = cur_state;
228 jtag_add_pathmove(tms_count, moves);
231 /* else state must be immediately reachable in one clock cycle, and does not
232 need to be a stable state.
234 else if( tap_state_transition(cur_state, true) == goal_state
235 || tap_state_transition(cur_state, false) == goal_state )
237 /* move a single state */
238 moves[0] = goal_state;
239 jtag_add_pathmove( 1, moves );
251 int xsvf_register_commands(struct command_context_s *cmd_ctx)
253 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
254 COMMAND_EXEC, "run xsvf <file> [virt2] [quiet]");
259 static int xsvf_read_buffer(int num_bits, int fd, u8* buf)
263 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
265 /* reverse the order of bytes as they are read sequentially from file */
266 if (read(fd, buf + num_bytes - 1, 1) < 0)
267 return ERROR_XSVF_EOF;
274 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
276 u8 *dr_out_buf = NULL; /* from host to device (TDI) */
277 u8 *dr_in_buf = NULL; /* from device to host (TDO) */
278 u8 *dr_in_mask = NULL;
281 int xruntest = 0; /* number of TCK cycles OR microseconds */
282 int xrepeat = 0; /* number of retries */
284 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
285 tap_state_t xenddr = TAP_IDLE;
289 long file_offset = 0;
292 tap_state_t loop_state = TAP_IDLE;
298 int tdo_mismatch = 0;
303 int runtest_requires_tck = 0; /* a flag telling whether to clock TCK during waits, or simply sleep, controled by virt2 */
306 /* use NULL to indicate a "plain" xsvf file which accounts for
307 additional devices in the scan chain, otherwise the device
308 that should be affected
310 jtag_tap_t *tap = NULL;
314 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> [<variant>] [quiet]");
318 filename = args[1]; /* we mess with args starting point below, snapshot filename here */
320 if (strcmp(args[0], "plain") != 0)
322 tap = jtag_TapByString( args[0] );
325 command_print( cmd_ctx, "Tap: %s unknown", args[0] );
330 if ((xsvf_fd = open(filename, O_RDONLY)) < 0)
332 command_print(cmd_ctx, "file \"%s\" not found", filename);
336 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
337 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
339 runtest_requires_tck = 1;
344 if ((argc > 2) && (strcmp(args[2], "quiet") == 0))
349 LOG_USER("xsvf processing file: \"%s\"", filename);
351 while( read(xsvf_fd, &opcode, 1) > 0 )
353 /* record the position of the just read opcode within the file */
354 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
359 LOG_DEBUG("XCOMPLETE");
361 result = jtag_execute_queue();
362 if (result != ERROR_OK)
370 LOG_DEBUG("XTDOMASK");
371 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
379 if (read(xsvf_fd, xruntest_buf, 4) < 0)
385 xruntest = be_to_h_u32(xruntest_buf);
386 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
394 if (read(xsvf_fd, &myrepeat, 1) < 0)
399 LOG_DEBUG("XREPEAT %d", xrepeat );
408 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
414 xsdrsize = be_to_h_u32(xsdrsize_buf);
415 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
417 if( dr_out_buf ) free(dr_out_buf);
418 if( dr_in_buf) free(dr_in_buf);
419 if( dr_in_mask) free(dr_in_mask);
421 dr_out_buf = malloc((xsdrsize + 7) / 8);
422 dr_in_buf = malloc((xsdrsize + 7) / 8);
423 dr_in_mask = malloc((xsdrsize + 7) / 8);
427 case XSDR: /* these two are identical except for the dr_in_buf */
434 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
436 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
442 if (opcode == XSDRTDO)
444 if(xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
454 LOG_DEBUG("%s %d", op_name, xsdrsize);
456 for( attempt=0; attempt<limit; ++attempt )
462 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
463 illustrated in psuedo code at end of this file. We start from state
471 This sequence should be harmless for other devices, and it
472 will be skipped entirely if xrepeat is set to zero.
475 static tap_state_t exception_path[] = {
483 jtag_add_pathmove( DIM(exception_path), exception_path );
486 LOG_USER("%s mismatch, xsdrsize=%d retry=%d", op_name, xsdrsize, attempt);
490 field.num_bits = xsdrsize;
491 field.out_value = dr_out_buf;
492 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
495 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
497 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
499 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
501 free(field.in_value);
504 /* LOG_DEBUG("FLUSHING QUEUE"); */
505 result = jtag_execute_queue();
506 if (result == ERROR_OK)
515 LOG_USER( "%s mismatch", op_name);
520 /* See page 19 of XSVF spec regarding opcode "XSDR" */
523 xsvf_add_statemove(TAP_IDLE);
525 if (runtest_requires_tck)
526 jtag_add_clocks(xruntest);
528 jtag_add_sleep(xruntest);
530 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
531 xsvf_add_statemove(xenddr);
536 LOG_ERROR("unsupported XSETSDRMASKS\n");
541 LOG_ERROR("unsupported XSDRINC\n");
546 LOG_ERROR("unsupported XSDRB\n");
551 LOG_ERROR("unsupported XSDRC\n");
556 LOG_ERROR("unsupported XSDRE\n");
561 LOG_ERROR("unsupported XSDRTDOB\n");
566 LOG_ERROR("unsupported XSDRTDOC\n");
571 LOG_ERROR("unsupported XSDRTDOE\n");
580 if (read(xsvf_fd, &uc, 1) < 0)
586 mystate = xsvf_to_tap(uc);
588 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate) );
590 /* there is no need for the lookahead code that was here since we
591 queue up the jtag commands anyway. This is a simple way to handle
595 if( xsvf_add_statemove( mystate ) != ERROR_OK )
597 /* For special states known as stable states
598 (Test-Logic-Reset, Run-Test/Idle, Pause-DR, Pause- IR),
599 an XSVF interpreter follows predefined TAP state paths
600 when the starting state is a stable state and when the
601 XSTATE specifies a new stable state (see the STATE
602 command in the [Ref 5] for the TAP state paths between
603 stable states). For non-stable states, XSTATE should
604 specify a state that is only one TAP state transition
605 distance from the current TAP state to avoid undefined
606 TAP state paths. A sequence of multiple XSTATE commands
607 can be issued to transition the TAP through a specific
611 LOG_ERROR("XSTATE %s is not reachable from current state %s in one clock cycle",
612 tap_state_name(mystate),
613 tap_state_name(cmd_queue_cur_state)
621 if (read(xsvf_fd, &uc, 1) < 0)
627 /* see page 22 of XSVF spec */
631 xendir = TAP_IRPAUSE;
634 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
639 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
644 if (read(xsvf_fd, &uc, 1) < 0)
650 /* see page 22 of XSVF spec */
654 xenddr = TAP_DRPAUSE;
657 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
662 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
671 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
675 /* one byte bitcount */
676 if (read(xsvf_fd, short_buf, 1) < 0)
681 bitcount = short_buf[0];
682 LOG_DEBUG("XSIR %d", bitcount);
686 if (read(xsvf_fd, short_buf, 2) < 0)
691 bitcount = be_to_h_u16(short_buf);
692 LOG_DEBUG("XSIR2 %d", bitcount);
695 ir_buf = malloc((bitcount+7) / 8);
697 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
704 field.num_bits = bitcount;
705 field.out_value = ir_buf;
707 field.in_value = NULL;
713 jtag_add_plain_ir_scan(1, &field, my_end_state);
715 jtag_add_ir_scan(1, &field, my_end_state);
719 if (runtest_requires_tck)
720 jtag_add_clocks(xruntest);
722 jtag_add_sleep(xruntest);
725 /* Note that an -irmask of non-zero in your config file
726 * can cause this to fail. Setting -irmask to zero cand work
727 * around the problem.
730 /* LOG_DEBUG("FLUSHING QUEUE"); */
731 result = jtag_execute_queue();
732 if(result != ERROR_OK)
743 unsigned int ndx = 0;
748 if (read(xsvf_fd, &uc, 1) < 0)
754 if ( ndx < sizeof(comment)-1 )
759 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
761 LOG_USER("# %s", comment);
767 /* expected in stream:
768 XWAIT <u8 wait_state> <u8 end_state> <u32 usecs>
775 tap_state_t wait_state;
776 tap_state_t end_state;
779 if ( read(xsvf_fd, &wait, 1) < 0
780 || read(xsvf_fd, &end, 1) < 0
781 || read(xsvf_fd, delay_buf, 4) < 0)
787 wait_state = xsvf_to_tap(wait);
788 end_state = xsvf_to_tap(end);
789 delay = be_to_h_u32(delay_buf);
791 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(wait_state), tap_state_name(end_state), delay);
793 if (runtest_requires_tck && wait_state == TAP_IDLE )
795 jtag_add_runtest(delay, end_state);
799 xsvf_add_statemove( wait_state );
800 jtag_add_sleep(delay);
801 xsvf_add_statemove( end_state );
808 /* expected in stream:
809 XWAITSTATE <u8 wait_state> <u8 end_state> <u32 clock_count> <u32 usecs>
816 tap_state_t wait_state;
817 tap_state_t end_state;
821 if ( read(xsvf_fd, &wait, 1) < 0
822 || read(xsvf_fd, &end, 1) < 0
823 || read(xsvf_fd, clock_buf, 4) < 0
824 || read(xsvf_fd, usecs_buf, 4) < 0 )
830 wait_state = xsvf_to_tap( wait );
831 end_state = xsvf_to_tap( end );
833 clock_count = be_to_h_u32(clock_buf);
834 usecs = be_to_h_u32(usecs_buf);
836 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
837 tap_state_name(wait_state),
838 tap_state_name(end_state),
841 /* the following states are 'stable', meaning that they have a transition
842 * in the state diagram back to themselves. This is necessary because we will
843 * be issuing a number of clocks in this state. This set of allowed states is also
844 * determined by the SVF RUNTEST command's allowed states.
846 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
848 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", tap_state_name( wait_state ));
852 xsvf_add_statemove( wait_state );
854 jtag_add_clocks( clock_count );
856 jtag_add_sleep( usecs );
858 xsvf_add_statemove( end_state );
864 /* expected in stream:
865 LCOUNT <u32 loop_count>
869 if ( read(xsvf_fd, count_buf, 4) < 0 )
875 loop_count = be_to_h_u32(count_buf);
876 LOG_DEBUG("LCOUNT %d", loop_count);
882 /* expected in stream:
883 LDELAY <u8 wait_state> <u32 clock_count> <u32 usecs_to_sleep>
889 if ( read(xsvf_fd, &state, 1) < 0
890 || read(xsvf_fd, clock_buf, 4) < 0
891 || read(xsvf_fd, usecs_buf, 4) < 0 )
897 loop_state = xsvf_to_tap(state);
898 loop_clocks = be_to_h_u32(clock_buf);
899 loop_usecs = be_to_h_u32(usecs_buf);
901 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
905 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
906 * comes with clocks !AND! sleep requirements.
910 int limit = loop_count;
916 if ( xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
917 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
926 for( attempt=0; attempt<limit; ++attempt )
930 xsvf_add_statemove( loop_state );
931 jtag_add_clocks(loop_clocks);
932 jtag_add_sleep(loop_usecs);
935 field.num_bits = xsdrsize;
936 field.out_value = dr_out_buf;
937 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
939 if (attempt > 0 && verbose)
940 LOG_USER("LSDR retry %d", attempt);
943 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
945 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
947 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
949 free(field.in_value);
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>