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>
62 /* XSVF commands, from appendix B of xapp503.pdf */
63 #define XCOMPLETE 0x00
71 #define XSETSDRMASKS 0x0A
86 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
87 * generates this. Arguably it is needed because the XSVF XRUNTEST command
88 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
89 * This XWAITSTATE does map directly from the SVF RUNTEST command.
91 #define XWAITSTATE 0x18
93 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
94 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
95 * Here is an example of usage of the 3 lattice opcode extensions:
97 ! Set the maximum loop count to 25.
99 ! Step to DRPAUSE give 5 clocks and wait for 1.00e+000 SEC.
100 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
101 ! Test for the completed status. Match means pass.
102 ! Loop back to LDELAY line if not match and loop count less than 25.
114 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
115 #define XSV_RESET 0x00
116 #define XSV_IDLE 0x01
117 #define XSV_DRSELECT 0x02
118 #define XSV_DRCAPTURE 0x03
119 #define XSV_DRSHIFT 0x04
120 #define XSV_DREXIT1 0x05
121 #define XSV_DRPAUSE 0x06
122 #define XSV_DREXIT2 0x07
123 #define XSV_DRUPDATE 0x08
124 #define XSV_IRSELECT 0x09
125 #define XSV_IRCAPTURE 0x0A
126 #define XSV_IRSHIFT 0x0B
127 #define XSV_IREXIT1 0x0C
128 #define XSV_IRPAUSE 0x0D
129 #define XSV_IREXIT2 0x0E
130 #define XSV_IRUPDATE 0x0F
132 /* arguments to XTRST */
136 #define XTRST_ABSENT 3
138 #define XSTATE_MAX_PATH 12
140 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc);
142 static int xsvf_fd = 0;
145 /* map xsvf tap state to an openocd "tap_state_t" */
146 static tap_state_t xsvf_to_tap( int xsvf_state )
152 case XSV_RESET: ret = TAP_RESET; break;
153 case XSV_IDLE: ret = TAP_IDLE; break;
154 case XSV_DRSELECT: ret = TAP_DRSELECT; break;
155 case XSV_DRCAPTURE: ret = TAP_DRCAPTURE; break;
156 case XSV_DRSHIFT: ret = TAP_DRSHIFT; break;
157 case XSV_DREXIT1: ret = TAP_DREXIT1; break;
158 case XSV_DRPAUSE: ret = TAP_DRPAUSE; break;
159 case XSV_DREXIT2: ret = TAP_DREXIT2; break;
160 case XSV_DRUPDATE: ret = TAP_DRUPDATE; break;
161 case XSV_IRSELECT: ret = TAP_IRSELECT; break;
162 case XSV_IRCAPTURE: ret = TAP_IRCAPTURE; break;
163 case XSV_IRSHIFT: ret = TAP_IRSHIFT; break;
164 case XSV_IREXIT1: ret = TAP_IREXIT1; break;
165 case XSV_IRPAUSE: ret = TAP_IRPAUSE; break;
166 case XSV_IREXIT2: ret = TAP_IREXIT2; break;
167 case XSV_IRUPDATE: ret = TAP_IRUPDATE; break;
169 LOG_ERROR( "UNKNOWN XSVF STATE 0x%02X", xsvf_state );
178 * Function xsvf_add_statemove
179 * moves from the current state to the goal \a state. This needs
180 * to be handled according to the xsvf spec, see the XSTATE command
183 static int xsvf_add_statemove(tap_state_t goal_state)
185 int retval = ERROR_OK;
187 tap_state_t moves[8];
188 tap_state_t cur_state = cmd_queue_cur_state;
193 LOG_DEBUG( "cur_state=%s goal_state=%s",
194 tap_state_name(cur_state),
195 tap_state_name(goal_state) );
198 /* From the XSVF spec, pertaining to XSTATE:
200 For special states known as stable states (Test-Logic-Reset,
201 Run-Test/Idle, Pause-DR, Pause- IR), an XSVF interpreter follows
202 predefined TAP state paths when the starting state is a stable state and
203 when the XSTATE specifies a new stable state (see the STATE command in
204 the [Ref 5] for the TAP state paths between stable states). For
205 non-stable states, XSTATE should specify a state that is only one TAP
206 state transition distance from the current TAP state to avoid undefined
207 TAP state paths. A sequence of multiple XSTATE commands can be issued to
208 transition the TAP through a specific state path.
211 if (goal_state==cur_state )
212 ; /* nothing to do */
214 else if( goal_state==TAP_RESET )
219 else if( tap_is_state_stable(cur_state) && tap_is_state_stable(goal_state) )
221 /* note: unless tms_bits holds a path that agrees with [Ref 5] in above
222 spec, then this code is not fully conformant to the xsvf spec. This
223 puts a burden on tap_get_tms_path() function from the xsvf spec.
224 If in doubt, you should confirm that that burden is being met.
227 tms_bits = tap_get_tms_path(cur_state, goal_state);
228 tms_count = tap_get_tms_path_len(cur_state, goal_state);
230 assert( (unsigned) tms_count < DIM(moves) );
232 for (i=0; i<tms_count; i++, tms_bits>>=1)
234 bool bit = tms_bits & 1;
236 cur_state = tap_state_transition(cur_state, bit);
237 moves[i] = cur_state;
240 jtag_add_pathmove(tms_count, moves);
243 /* else state must be immediately reachable in one clock cycle, and does not
244 need to be a stable state.
246 else if( tap_state_transition(cur_state, true) == goal_state
247 || tap_state_transition(cur_state, false) == goal_state )
249 /* move a single state */
250 moves[0] = goal_state;
251 jtag_add_pathmove( 1, moves );
263 int xsvf_register_commands(struct command_context_s *cmd_ctx)
265 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
266 COMMAND_EXEC, "run xsvf <file> [virt2] [quiet]");
271 static int xsvf_read_buffer(int num_bits, int fd, u8* buf)
275 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
277 /* reverse the order of bytes as they are read sequentially from file */
278 if (read(fd, buf + num_bytes - 1, 1) < 0)
279 return ERROR_XSVF_EOF;
286 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
288 u8 *dr_out_buf = NULL; /* from host to device (TDI) */
289 u8 *dr_in_buf = NULL; /* from device to host (TDO) */
290 u8 *dr_in_mask = NULL;
293 int xruntest = 0; /* number of TCK cycles OR microseconds */
294 int xrepeat = 0; /* number of retries */
296 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
297 tap_state_t xenddr = TAP_IDLE;
301 long file_offset = 0;
304 tap_state_t loop_state = TAP_IDLE;
310 int tdo_mismatch = 0;
315 int runtest_requires_tck = 0; /* a flag telling whether to clock TCK during waits, or simply sleep, controled by virt2 */
318 /* use NULL to indicate a "plain" xsvf file which accounts for
319 additional devices in the scan chain, otherwise the device
320 that should be affected
322 jtag_tap_t *tap = NULL;
326 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> [<variant>] [quiet]");
330 filename = args[1]; /* we mess with args starting point below, snapshot filename here */
332 if (strcmp(args[0], "plain") != 0)
334 tap = jtag_TapByString( args[0] );
337 command_print( cmd_ctx, "Tap: %s unknown", args[0] );
342 if ((xsvf_fd = open(filename, O_RDONLY)) < 0)
344 command_print(cmd_ctx, "file \"%s\" not found", filename);
348 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
349 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
351 runtest_requires_tck = 1;
356 if ((argc > 2) && (strcmp(args[2], "quiet") == 0))
361 LOG_USER("xsvf processing file: \"%s\"", filename);
363 while( read(xsvf_fd, &opcode, 1) > 0 )
365 /* record the position of the just read opcode within the file */
366 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
371 LOG_DEBUG("XCOMPLETE");
373 result = jtag_execute_queue();
374 if (result != ERROR_OK)
382 LOG_DEBUG("XTDOMASK");
383 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
391 if (read(xsvf_fd, xruntest_buf, 4) < 0)
397 xruntest = be_to_h_u32(xruntest_buf);
398 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
406 if (read(xsvf_fd, &myrepeat, 1) < 0)
411 LOG_DEBUG("XREPEAT %d", xrepeat );
420 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
426 xsdrsize = be_to_h_u32(xsdrsize_buf);
427 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
429 if( dr_out_buf ) free(dr_out_buf);
430 if( dr_in_buf) free(dr_in_buf);
431 if( dr_in_mask) free(dr_in_mask);
433 dr_out_buf = malloc((xsdrsize + 7) / 8);
434 dr_in_buf = malloc((xsdrsize + 7) / 8);
435 dr_in_mask = malloc((xsdrsize + 7) / 8);
439 case XSDR: /* these two are identical except for the dr_in_buf */
446 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
448 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
454 if (opcode == XSDRTDO)
456 if(xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
466 LOG_DEBUG("%s %d", op_name, xsdrsize);
468 for( attempt=0; attempt<limit; ++attempt )
474 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
475 illustrated in psuedo code at end of this file. We start from state
483 This sequence should be harmless for other devices, and it
484 will be skipped entirely if xrepeat is set to zero.
487 static tap_state_t exception_path[] = {
495 jtag_add_pathmove( DIM(exception_path), exception_path );
498 LOG_USER("%s mismatch, xsdrsize=%d retry=%d", op_name, xsdrsize, attempt);
502 field.num_bits = xsdrsize;
503 field.out_value = dr_out_buf;
504 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
507 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
509 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
511 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
513 free(field.in_value);
516 /* LOG_DEBUG("FLUSHING QUEUE"); */
517 result = jtag_execute_queue();
518 if (result == ERROR_OK)
527 LOG_USER( "%s mismatch", op_name);
532 /* See page 19 of XSVF spec regarding opcode "XSDR" */
535 xsvf_add_statemove(TAP_IDLE);
537 if (runtest_requires_tck)
538 jtag_add_clocks(xruntest);
540 jtag_add_sleep(xruntest);
542 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
543 xsvf_add_statemove(xenddr);
548 LOG_ERROR("unsupported XSETSDRMASKS\n");
553 LOG_ERROR("unsupported XSDRINC\n");
558 LOG_ERROR("unsupported XSDRB\n");
563 LOG_ERROR("unsupported XSDRC\n");
568 LOG_ERROR("unsupported XSDRE\n");
573 LOG_ERROR("unsupported XSDRTDOB\n");
578 LOG_ERROR("unsupported XSDRTDOC\n");
583 LOG_ERROR("unsupported XSDRTDOE\n");
592 if (read(xsvf_fd, &uc, 1) < 0)
598 mystate = xsvf_to_tap(uc);
600 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate) );
602 /* there is no need for the lookahead code that was here since we
603 queue up the jtag commands anyway. This is a simple way to handle
607 if( xsvf_add_statemove( mystate ) != ERROR_OK )
609 /* For special states known as stable states
610 (Test-Logic-Reset, Run-Test/Idle, Pause-DR, Pause- IR),
611 an XSVF interpreter follows predefined TAP state paths
612 when the starting state is a stable state and when the
613 XSTATE specifies a new stable state (see the STATE
614 command in the [Ref 5] for the TAP state paths between
615 stable states). For non-stable states, XSTATE should
616 specify a state that is only one TAP state transition
617 distance from the current TAP state to avoid undefined
618 TAP state paths. A sequence of multiple XSTATE commands
619 can be issued to transition the TAP through a specific
623 LOG_ERROR("XSTATE %s is not reachable from current state %s in one clock cycle",
624 tap_state_name(mystate),
625 tap_state_name(cmd_queue_cur_state)
633 if (read(xsvf_fd, &uc, 1) < 0)
639 /* see page 22 of XSVF spec */
643 xendir = TAP_IRPAUSE;
646 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
651 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
656 if (read(xsvf_fd, &uc, 1) < 0)
662 /* see page 22 of XSVF spec */
666 xenddr = TAP_DRPAUSE;
669 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
674 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
683 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
687 /* one byte bitcount */
688 if (read(xsvf_fd, short_buf, 1) < 0)
693 bitcount = short_buf[0];
694 LOG_DEBUG("XSIR %d", bitcount);
698 if (read(xsvf_fd, short_buf, 2) < 0)
703 bitcount = be_to_h_u16(short_buf);
704 LOG_DEBUG("XSIR2 %d", bitcount);
707 ir_buf = malloc((bitcount+7) / 8);
709 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
716 field.num_bits = bitcount;
717 field.out_value = ir_buf;
719 field.in_value = NULL;
725 jtag_add_plain_ir_scan(1, &field, my_end_state);
727 jtag_add_ir_scan(1, &field, my_end_state);
731 if (runtest_requires_tck)
732 jtag_add_clocks(xruntest);
734 jtag_add_sleep(xruntest);
737 /* Note that an -irmask of non-zero in your config file
738 * can cause this to fail. Setting -irmask to zero cand work
739 * around the problem.
742 /* LOG_DEBUG("FLUSHING QUEUE"); */
743 result = jtag_execute_queue();
744 if(result != ERROR_OK)
755 unsigned int ndx = 0;
760 if (read(xsvf_fd, &uc, 1) < 0)
766 if ( ndx < sizeof(comment)-1 )
771 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
773 LOG_USER("# %s", comment);
779 /* expected in stream:
780 XWAIT <u8 wait_state> <u8 end_state> <u32 usecs>
787 tap_state_t wait_state;
788 tap_state_t end_state;
791 if ( read(xsvf_fd, &wait, 1) < 0
792 || read(xsvf_fd, &end, 1) < 0
793 || read(xsvf_fd, delay_buf, 4) < 0)
799 wait_state = xsvf_to_tap(wait);
800 end_state = xsvf_to_tap(end);
801 delay = be_to_h_u32(delay_buf);
803 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(wait_state), tap_state_name(end_state), delay);
805 if (runtest_requires_tck && wait_state == TAP_IDLE )
807 jtag_add_runtest(delay, end_state);
811 xsvf_add_statemove( wait_state );
812 jtag_add_sleep(delay);
813 xsvf_add_statemove( end_state );
820 /* expected in stream:
821 XWAITSTATE <u8 wait_state> <u8 end_state> <u32 clock_count> <u32 usecs>
828 tap_state_t wait_state;
829 tap_state_t end_state;
833 if ( read(xsvf_fd, &wait, 1) < 0
834 || read(xsvf_fd, &end, 1) < 0
835 || read(xsvf_fd, clock_buf, 4) < 0
836 || read(xsvf_fd, usecs_buf, 4) < 0 )
842 wait_state = xsvf_to_tap( wait );
843 end_state = xsvf_to_tap( end );
845 clock_count = be_to_h_u32(clock_buf);
846 usecs = be_to_h_u32(usecs_buf);
848 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
849 tap_state_name(wait_state),
850 tap_state_name(end_state),
853 /* the following states are 'stable', meaning that they have a transition
854 * in the state diagram back to themselves. This is necessary because we will
855 * be issuing a number of clocks in this state. This set of allowed states is also
856 * determined by the SVF RUNTEST command's allowed states.
858 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
860 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", tap_state_name( wait_state ));
864 xsvf_add_statemove( wait_state );
866 jtag_add_clocks( clock_count );
868 jtag_add_sleep( usecs );
870 xsvf_add_statemove( end_state );
876 /* expected in stream:
877 LCOUNT <u32 loop_count>
881 if ( read(xsvf_fd, count_buf, 4) < 0 )
887 loop_count = be_to_h_u32(count_buf);
888 LOG_DEBUG("LCOUNT %d", loop_count);
894 /* expected in stream:
895 LDELAY <u8 wait_state> <u32 clock_count> <u32 usecs_to_sleep>
901 if ( read(xsvf_fd, &state, 1) < 0
902 || read(xsvf_fd, clock_buf, 4) < 0
903 || read(xsvf_fd, usecs_buf, 4) < 0 )
909 loop_state = xsvf_to_tap(state);
910 loop_clocks = be_to_h_u32(clock_buf);
911 loop_usecs = be_to_h_u32(usecs_buf);
913 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
917 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
918 * comes with clocks !AND! sleep requirements.
922 int limit = loop_count;
928 if ( xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
929 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
938 for( attempt=0; attempt<limit; ++attempt )
942 xsvf_add_statemove( loop_state );
943 jtag_add_clocks(loop_clocks);
944 jtag_add_sleep(loop_usecs);
947 field.num_bits = xsdrsize;
948 field.out_value = dr_out_buf;
949 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
951 if (attempt > 0 && verbose)
952 LOG_USER("LSDR retry %d", attempt);
955 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
957 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
959 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
961 free(field.in_value);
964 /* LOG_DEBUG("FLUSHING QUEUE"); */
965 result = jtag_execute_queue();
966 if(result == ERROR_OK)
975 LOG_USER( "LSDR mismatch" );
986 if (read(xsvf_fd, &trst_mode, 1) < 0)
995 jtag_add_reset(1, 0);
999 jtag_add_reset(0, 0);
1004 LOG_ERROR( "XTRST mode argument (0x%02X) out of range", trst_mode );
1011 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
1015 if (do_abort || unsupported || tdo_mismatch)
1017 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
1019 /* upon error, return the TAPs to a reasonable state */
1020 xsvf_add_statemove( TAP_IDLE );
1021 jtag_execute_queue();
1028 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
1037 command_print(cmd_ctx,
1038 "unsupported xsvf command: 0x%02X in xsvf file at offset %ld, aborting",
1039 uc, lseek(xsvf_fd, 0, SEEK_CUR)-1 );
1045 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
1060 command_print(cmd_ctx, "XSVF file programmed successfully");
1066 #if 0 /* this comment style used to try and keep uncrustify from adding * at begin of line */
1068 PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
1070 the following pseudo code clarifies the intent of the xrepeat support. The
1071 flow given is for the entire processing of an SVF file, not an XSVF file.
1072 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1074 "Pseudo-Code Algorithm for SVF-Based ISP"
1076 1. Go to Test-Logic-Reset state
1077 2. Go to Run-Test Idle state
1080 4. if SIR record then
1081 go to Shift-IR state
1084 5. else if SDR record then
1085 set <repeat count> to 0
1086 store <TDI value> as <current TDI value>
1087 store <TDO value> as <current TDO value>
1088 6. go to Shift-DR state
1089 scan in <current TDI value>
1090 if <current TDO value> is specified then
1091 if <current TDO value> does not equal <actual TDO value> then
1092 if <repeat count> > 32 then
1094 go to Run-Test Idle state
1103 increment <repeat count> by 1
1104 pause <current pause time> microseconds
1108 go to Run-Test Idle state
1111 else if RUNTEST record then
1112 pause tester for <TCK value> microseconds
1113 store <TCK value> as <current pause time>