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, which has nothing
181 * to do with the JTAG spec or OpenOCD as such.
183 * Implemented via jtag_add_pathmove().
185 static void xsvf_add_statemove(tap_state_t goal_state)
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) );
197 if (goal_state==cur_state )
200 if( goal_state==TAP_RESET )
206 tms_bits = tap_get_tms_path(cur_state, goal_state);
207 tms_count = tap_get_tms_path_len(cur_state, goal_state);
209 assert( (unsigned) tms_count < DIM(moves) );
211 for (i=0; i<tms_count; i++, tms_bits>>=1)
213 bool bit = tms_bits & 1;
215 cur_state = tap_state_transition(cur_state, bit);
216 moves[i] = cur_state;
219 jtag_add_pathmove(tms_count, moves);
223 int xsvf_register_commands(struct command_context_s *cmd_ctx)
225 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
226 COMMAND_EXEC, "run xsvf <file> [virt2] [quiet]");
231 static int xsvf_read_buffer(int num_bits, int fd, u8* buf)
235 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
237 /* reverse the order of bytes as they are read sequentially from file */
238 if (read(fd, buf + num_bytes - 1, 1) < 0)
239 return ERROR_XSVF_EOF;
246 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
248 u8 *dr_out_buf = NULL; /* from host to device (TDI) */
249 u8 *dr_in_buf = NULL; /* from device to host (TDO) */
250 u8 *dr_in_mask = NULL;
253 int xruntest = 0; /* number of TCK cycles OR microseconds */
254 int xrepeat = 0; /* number of retries */
256 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
257 tap_state_t xenddr = TAP_IDLE;
261 long file_offset = 0;
264 tap_state_t loop_state = TAP_IDLE;
270 int tdo_mismatch = 0;
275 int runtest_requires_tck = 0; /* a flag telling whether to clock TCK during waits, or simply sleep, controled by virt2 */
278 /* use NULL to indicate a "plain" xsvf file which accounts for
279 additional devices in the scan chain, otherwise the device
280 that should be affected
282 jtag_tap_t *tap = NULL;
286 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> [<variant>] [quiet]");
290 filename = args[1]; /* we mess with args starting point below, snapshot filename here */
292 if (strcmp(args[0], "plain") != 0)
294 tap = jtag_TapByString( args[0] );
297 command_print( cmd_ctx, "Tap: %s unknown", args[0] );
302 if ((xsvf_fd = open(filename, O_RDONLY)) < 0)
304 command_print(cmd_ctx, "file \"%s\" not found", filename);
308 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
309 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
311 runtest_requires_tck = 1;
316 if ((argc > 2) && (strcmp(args[2], "quiet") == 0))
321 LOG_USER("xsvf processing file: \"%s\"", filename);
323 while( read(xsvf_fd, &opcode, 1) > 0 )
325 /* record the position of the just read opcode within the file */
326 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
331 LOG_DEBUG("XCOMPLETE");
333 result = jtag_execute_queue();
334 if (result != ERROR_OK)
342 LOG_DEBUG("XTDOMASK");
343 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
351 if (read(xsvf_fd, xruntest_buf, 4) < 0)
357 xruntest = be_to_h_u32(xruntest_buf);
358 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
366 if (read(xsvf_fd, &myrepeat, 1) < 0)
371 LOG_DEBUG("XREPEAT %d", xrepeat );
380 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
386 xsdrsize = be_to_h_u32(xsdrsize_buf);
387 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
389 if( dr_out_buf ) free(dr_out_buf);
390 if( dr_in_buf) free(dr_in_buf);
391 if( dr_in_mask) free(dr_in_mask);
393 dr_out_buf = malloc((xsdrsize + 7) / 8);
394 dr_in_buf = malloc((xsdrsize + 7) / 8);
395 dr_in_mask = malloc((xsdrsize + 7) / 8);
399 case XSDR: /* these two are identical except for the dr_in_buf */
406 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
408 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
414 if (opcode == XSDRTDO)
416 if(xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
426 LOG_DEBUG("%s %d", op_name, xsdrsize);
428 for( attempt=0; attempt<limit; ++attempt )
434 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
435 illustrated in psuedo code at end of this file. We start from state
443 This sequence should be harmless for other devices, and it
444 will be skipped entirely if xrepeat is set to zero.
447 static tap_state_t exception_path[] = {
455 jtag_add_pathmove( DIM(exception_path), exception_path );
458 LOG_USER("%s mismatch, xsdrsize=%d retry=%d", op_name, xsdrsize, attempt);
462 field.num_bits = xsdrsize;
463 field.out_value = dr_out_buf;
465 field.in_value = NULL;
467 jtag_set_check_value(&field, dr_in_buf, dr_in_mask, NULL);
470 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
472 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
474 /* LOG_DEBUG("FLUSHING QUEUE"); */
475 result = jtag_execute_queue();
476 if (result == ERROR_OK)
485 LOG_USER( "%s mismatch", op_name);
490 /* See page 19 of XSVF spec regarding opcode "XSDR" */
493 xsvf_add_statemove(TAP_IDLE);
495 if (runtest_requires_tck)
496 jtag_add_clocks(xruntest);
498 jtag_add_sleep(xruntest);
500 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
501 xsvf_add_statemove(xenddr);
506 LOG_ERROR("unsupported XSETSDRMASKS\n");
511 LOG_ERROR("unsupported XSDRINC\n");
516 LOG_ERROR("unsupported XSDRB\n");
521 LOG_ERROR("unsupported XSDRC\n");
526 LOG_ERROR("unsupported XSDRE\n");
531 LOG_ERROR("unsupported XSDRTDOB\n");
536 LOG_ERROR("unsupported XSDRTDOC\n");
541 LOG_ERROR("unsupported XSDRTDOE\n");
550 if (read(xsvf_fd, &uc, 1) < 0)
556 mystate = xsvf_to_tap(uc);
558 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate) );
560 xsvf_add_statemove( mystate );
566 if (read(xsvf_fd, &uc, 1) < 0)
572 /* see page 22 of XSVF spec */
576 xendir = TAP_IRPAUSE;
579 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
584 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
589 if (read(xsvf_fd, &uc, 1) < 0)
595 /* see page 22 of XSVF spec */
599 xenddr = TAP_DRPAUSE;
602 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
607 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
616 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
620 /* one byte bitcount */
621 if (read(xsvf_fd, short_buf, 1) < 0)
626 bitcount = short_buf[0];
627 LOG_DEBUG("XSIR %d", bitcount);
631 if (read(xsvf_fd, short_buf, 2) < 0)
636 bitcount = be_to_h_u16(short_buf);
637 LOG_DEBUG("XSIR2 %d", bitcount);
640 ir_buf = malloc((bitcount+7) / 8);
642 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
649 field.num_bits = bitcount;
650 field.out_value = ir_buf;
652 field.in_value = NULL;
655 field.in_handler = NULL;
658 jtag_add_plain_ir_scan(1, &field, my_end_state);
660 jtag_add_ir_scan(1, &field, my_end_state);
664 if (runtest_requires_tck)
665 jtag_add_clocks(xruntest);
667 jtag_add_sleep(xruntest);
670 /* Note that an -irmask of non-zero in your config file
671 * can cause this to fail. Setting -irmask to zero cand work
672 * around the problem.
675 /* LOG_DEBUG("FLUSHING QUEUE"); */
676 result = jtag_execute_queue();
677 if(result != ERROR_OK)
688 unsigned int ndx = 0;
693 if (read(xsvf_fd, &uc, 1) < 0)
699 if ( ndx < sizeof(comment)-1 )
704 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
706 LOG_USER("\"# %s\"", comment);
712 /* expected in stream:
713 XWAIT <u8 wait_state> <u8 end_state> <u32 usecs>
720 tap_state_t wait_state;
721 tap_state_t end_state;
724 if ( read(xsvf_fd, &wait, 1) < 0
725 || read(xsvf_fd, &end, 1) < 0
726 || read(xsvf_fd, delay_buf, 4) < 0)
732 wait_state = xsvf_to_tap(wait);
733 end_state = xsvf_to_tap(end);
734 delay = be_to_h_u32(delay_buf);
736 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(wait_state), tap_state_name(end_state), delay);
738 if (runtest_requires_tck && wait_state == TAP_IDLE )
740 jtag_add_runtest(delay, end_state);
744 xsvf_add_statemove( wait_state );
745 jtag_add_sleep(delay);
746 xsvf_add_statemove( end_state );
753 /* expected in stream:
754 XWAITSTATE <u8 wait_state> <u8 end_state> <u32 clock_count> <u32 usecs>
761 tap_state_t wait_state;
762 tap_state_t end_state;
766 if ( read(xsvf_fd, &wait, 1) < 0
767 || read(xsvf_fd, &end, 1) < 0
768 || read(xsvf_fd, clock_buf, 4) < 0
769 || read(xsvf_fd, usecs_buf, 4) < 0 )
775 wait_state = xsvf_to_tap( wait );
776 end_state = xsvf_to_tap( end );
778 clock_count = be_to_h_u32(clock_buf);
779 usecs = be_to_h_u32(usecs_buf);
781 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
782 tap_state_name(wait_state),
783 tap_state_name(end_state),
786 /* the following states are 'stable', meaning that they have a transition
787 * in the state diagram back to themselves. This is necessary because we will
788 * be issuing a number of clocks in this state. This set of allowed states is also
789 * determined by the SVF RUNTEST command's allowed states.
791 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
793 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", tap_state_name( wait_state ));
797 xsvf_add_statemove( wait_state );
799 jtag_add_clocks( clock_count );
801 jtag_add_sleep( usecs );
803 xsvf_add_statemove( end_state );
809 /* expected in stream:
810 LCOUNT <u32 loop_count>
814 if ( read(xsvf_fd, count_buf, 4) < 0 )
820 loop_count = be_to_h_u32(count_buf);
821 LOG_DEBUG("LCOUNT %d", loop_count);
827 /* expected in stream:
828 LDELAY <u8 wait_state> <u32 clock_count> <u32 usecs_to_sleep>
834 if ( read(xsvf_fd, &state, 1) < 0
835 || read(xsvf_fd, clock_buf, 4) < 0
836 || read(xsvf_fd, usecs_buf, 4) < 0 )
842 loop_state = xsvf_to_tap(state);
843 loop_clocks = be_to_h_u32(clock_buf);
844 loop_usecs = be_to_h_u32(usecs_buf);
846 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
850 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
851 * comes with clocks !AND! sleep requirements.
855 int limit = loop_count;
861 if ( xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
862 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
871 for( attempt=0; attempt<limit; ++attempt )
875 xsvf_add_statemove( loop_state );
876 jtag_add_clocks(loop_clocks);
877 jtag_add_sleep(loop_usecs);
880 field.num_bits = xsdrsize;
881 field.out_value = dr_out_buf;
883 field.in_value = NULL;
885 if (attempt > 0 && verbose)
886 LOG_USER("LSDR retry %d", attempt);
888 jtag_set_check_value(&field, dr_in_buf, dr_in_mask, NULL);
890 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
892 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
894 /* LOG_DEBUG("FLUSHING QUEUE"); */
895 result = jtag_execute_queue();
896 if(result == ERROR_OK)
905 LOG_USER( "LSDR mismatch" );
916 if (read(xsvf_fd, &trst_mode, 1) < 0)
925 jtag_add_reset(1, 0);
929 jtag_add_reset(0, 0);
934 LOG_ERROR( "XTRST mode argument (0x%02X) out of range", trst_mode );
941 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
945 if (do_abort || unsupported || tdo_mismatch)
947 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
949 /* upon error, return the TAPs to a reasonable state */
950 xsvf_add_statemove( TAP_IDLE );
951 jtag_execute_queue();
958 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
967 command_print(cmd_ctx,
968 "unsupported xsvf command: 0x%02X in xsvf file at offset %ld, aborting",
969 uc, lseek(xsvf_fd, 0, SEEK_CUR)-1 );
975 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
990 command_print(cmd_ctx, "XSVF file programmed successfully");
996 #if 0 /* this comment style used to try and keep uncrustify from adding * at begin of line */
998 PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
1000 the following pseudo code clarifies the intent of the xrepeat support. The
1001 flow given is for the entire processing of an SVF file, not an XSVF file.
1002 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1004 "Pseudo-Code Algorithm for SVF-Based ISP"
1006 1. Go to Test-Logic-Reset state
1007 2. Go to Run-Test Idle state
1010 4. if SIR record then
1011 go to Shift-IR state
1014 5. else if SDR record then
1015 set <repeat count> to 0
1016 store <TDI value> as <current TDI value>
1017 store <TDO value> as <current TDO value>
1018 6. go to Shift-DR state
1019 scan in <current TDI value>
1020 if <current TDO value> is specified then
1021 if <current TDO value> does not equal <actual TDO value> then
1022 if <repeat count> > 32 then
1024 go to Run-Test Idle state
1033 increment <repeat count> by 1
1034 pause <current pause time> microseconds
1038 go to Run-Test Idle state
1041 else if RUNTEST record then
1042 pause tester for <TCK value> microseconds
1043 store <TCK value> as <current pause time>