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 int xsvf_register_commands(struct command_context_s *cmd_ctx)
166 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
167 COMMAND_EXEC, "run xsvf <file> [virt2] [quiet]");
172 static int xsvf_read_buffer(int num_bits, int fd, u8* buf)
176 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
178 /* reverse the order of bytes as they are read sequentially from file */
179 if (read(fd, buf + num_bytes - 1, 1) < 0)
180 return ERROR_XSVF_EOF;
187 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
189 u8 *dr_out_buf = NULL; /* from host to device (TDI) */
190 u8 *dr_in_buf = NULL; /* from device to host (TDO) */
191 u8 *dr_in_mask = NULL;
194 int xruntest = 0; /* number of TCK cycles OR microseconds */
195 int xrepeat = 0; /* number of retries */
197 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
198 tap_state_t xenddr = TAP_IDLE;
202 long file_offset = 0;
205 tap_state_t loop_state = TAP_IDLE;
211 int tdo_mismatch = 0;
216 int runtest_requires_tck = 0; /* a flag telling whether to clock TCK during waits, or simply sleep, controled by virt2 */
219 /* use NULL to indicate a "plain" xsvf file which accounts for
220 additional devices in the scan chain, otherwise the device
221 that should be affected
223 jtag_tap_t *tap = NULL;
227 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> [<variant>] [quiet]");
231 filename = args[1]; /* we mess with args starting point below, snapshot filename here */
233 if (strcmp(args[0], "plain") != 0)
235 tap = jtag_TapByString( args[0] );
238 command_print( cmd_ctx, "Tap: %s unknown", args[0] );
243 if ((xsvf_fd = open(filename, O_RDONLY)) < 0)
245 command_print(cmd_ctx, "file \"%s\" not found", filename);
249 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
250 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
252 runtest_requires_tck = 1;
257 if ((argc > 2) && (strcmp(args[2], "quiet") == 0))
262 LOG_USER("xsvf processing file: \"%s\"", filename);
264 while( read(xsvf_fd, &opcode, 1) > 0 )
266 /* record the position of the just read opcode within the file */
267 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
272 LOG_DEBUG("XCOMPLETE");
274 result = jtag_execute_queue();
275 if (result != ERROR_OK)
283 LOG_DEBUG("XTDOMASK");
284 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
292 if (read(xsvf_fd, xruntest_buf, 4) < 0)
298 xruntest = be_to_h_u32(xruntest_buf);
299 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
307 if (read(xsvf_fd, &myrepeat, 1) < 0)
312 LOG_DEBUG("XREPEAT %d", xrepeat );
321 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
327 xsdrsize = be_to_h_u32(xsdrsize_buf);
328 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
330 if( dr_out_buf ) free(dr_out_buf);
331 if( dr_in_buf) free(dr_in_buf);
332 if( dr_in_mask) free(dr_in_mask);
334 dr_out_buf = malloc((xsdrsize + 7) / 8);
335 dr_in_buf = malloc((xsdrsize + 7) / 8);
336 dr_in_mask = malloc((xsdrsize + 7) / 8);
340 case XSDR: /* these two are identical except for the dr_in_buf */
347 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
349 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
355 if (opcode == XSDRTDO)
357 if(xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
367 LOG_DEBUG("%s %d", op_name, xsdrsize);
369 for( attempt=0; attempt<limit; ++attempt )
375 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
376 illustrated in psuedo code at end of this file. We start from state
384 This sequence should be harmless for other devices, and it
385 will be skipped entirely if xrepeat is set to zero.
388 static tap_state_t exception_path[] = {
396 jtag_add_pathmove( DIM(exception_path), exception_path );
399 LOG_USER("%s mismatch, xsdrsize=%d retry=%d", op_name, xsdrsize, attempt);
403 field.num_bits = xsdrsize;
404 field.out_value = dr_out_buf;
405 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
408 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
410 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
412 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
414 free(field.in_value);
417 /* LOG_DEBUG("FLUSHING QUEUE"); */
418 result = jtag_execute_queue();
419 if (result == ERROR_OK)
428 LOG_USER( "%s mismatch", op_name);
433 /* See page 19 of XSVF spec regarding opcode "XSDR" */
436 jtag_add_statemove(TAP_IDLE);
438 if (runtest_requires_tck)
439 jtag_add_clocks(xruntest);
441 jtag_add_sleep(xruntest);
443 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
444 jtag_add_statemove(xenddr);
449 LOG_ERROR("unsupported XSETSDRMASKS\n");
454 LOG_ERROR("unsupported XSDRINC\n");
459 LOG_ERROR("unsupported XSDRB\n");
464 LOG_ERROR("unsupported XSDRC\n");
469 LOG_ERROR("unsupported XSDRE\n");
474 LOG_ERROR("unsupported XSDRTDOB\n");
479 LOG_ERROR("unsupported XSDRTDOC\n");
484 LOG_ERROR("unsupported XSDRTDOE\n");
493 if (read(xsvf_fd, &uc, 1) < 0)
499 mystate = xsvf_to_tap(uc);
501 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate) );
503 /* there is no need for the lookahead code that was here since we
504 queue up the jtag commands anyway. This is a simple way to handle
508 if( jtag_add_statemove( mystate ) != ERROR_OK )
510 /* For special states known as stable states
511 (Test-Logic-Reset, Run-Test/Idle, Pause-DR, Pause- IR),
512 an XSVF interpreter follows predefined TAP state paths
513 when the starting state is a stable state and when the
514 XSTATE specifies a new stable state (see the STATE
515 command in the [Ref 5] for the TAP state paths between
516 stable states). For non-stable states, XSTATE should
517 specify a state that is only one TAP state transition
518 distance from the current TAP state to avoid undefined
519 TAP state paths. A sequence of multiple XSTATE commands
520 can be issued to transition the TAP through a specific
524 LOG_ERROR("XSTATE %s is not reachable from current state %s in one clock cycle",
525 tap_state_name(mystate),
526 tap_state_name(cmd_queue_cur_state)
534 if (read(xsvf_fd, &uc, 1) < 0)
540 /* see page 22 of XSVF spec */
544 xendir = TAP_IRPAUSE;
547 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
552 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
557 if (read(xsvf_fd, &uc, 1) < 0)
563 /* see page 22 of XSVF spec */
567 xenddr = TAP_DRPAUSE;
570 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
575 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
584 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
588 /* one byte bitcount */
589 if (read(xsvf_fd, short_buf, 1) < 0)
594 bitcount = short_buf[0];
595 LOG_DEBUG("XSIR %d", bitcount);
599 if (read(xsvf_fd, short_buf, 2) < 0)
604 bitcount = be_to_h_u16(short_buf);
605 LOG_DEBUG("XSIR2 %d", bitcount);
608 ir_buf = malloc((bitcount+7) / 8);
610 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
617 field.num_bits = bitcount;
618 field.out_value = ir_buf;
620 field.in_value = NULL;
626 jtag_add_plain_ir_scan(1, &field, my_end_state);
628 jtag_add_ir_scan(1, &field, my_end_state);
632 if (runtest_requires_tck)
633 jtag_add_clocks(xruntest);
635 jtag_add_sleep(xruntest);
638 /* Note that an -irmask of non-zero in your config file
639 * can cause this to fail. Setting -irmask to zero cand work
640 * around the problem.
643 /* LOG_DEBUG("FLUSHING QUEUE"); */
644 result = jtag_execute_queue();
645 if(result != ERROR_OK)
656 unsigned int ndx = 0;
661 if (read(xsvf_fd, &uc, 1) < 0)
667 if ( ndx < sizeof(comment)-1 )
672 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
674 LOG_USER("# %s", comment);
680 /* expected in stream:
681 XWAIT <u8 wait_state> <u8 end_state> <u32 usecs>
688 tap_state_t wait_state;
689 tap_state_t end_state;
692 if ( read(xsvf_fd, &wait, 1) < 0
693 || read(xsvf_fd, &end, 1) < 0
694 || read(xsvf_fd, delay_buf, 4) < 0)
700 wait_state = xsvf_to_tap(wait);
701 end_state = xsvf_to_tap(end);
702 delay = be_to_h_u32(delay_buf);
704 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(wait_state), tap_state_name(end_state), delay);
706 if (runtest_requires_tck && wait_state == TAP_IDLE )
708 jtag_add_runtest(delay, end_state);
712 jtag_add_statemove( wait_state );
713 jtag_add_sleep(delay);
714 jtag_add_statemove( end_state );
721 /* expected in stream:
722 XWAITSTATE <u8 wait_state> <u8 end_state> <u32 clock_count> <u32 usecs>
729 tap_state_t wait_state;
730 tap_state_t end_state;
734 if ( read(xsvf_fd, &wait, 1) < 0
735 || read(xsvf_fd, &end, 1) < 0
736 || read(xsvf_fd, clock_buf, 4) < 0
737 || read(xsvf_fd, usecs_buf, 4) < 0 )
743 wait_state = xsvf_to_tap( wait );
744 end_state = xsvf_to_tap( end );
746 clock_count = be_to_h_u32(clock_buf);
747 usecs = be_to_h_u32(usecs_buf);
749 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
750 tap_state_name(wait_state),
751 tap_state_name(end_state),
754 /* the following states are 'stable', meaning that they have a transition
755 * in the state diagram back to themselves. This is necessary because we will
756 * be issuing a number of clocks in this state. This set of allowed states is also
757 * determined by the SVF RUNTEST command's allowed states.
759 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
761 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", tap_state_name( wait_state ));
765 jtag_add_statemove( wait_state );
767 jtag_add_clocks( clock_count );
769 jtag_add_sleep( usecs );
771 jtag_add_statemove( end_state );
777 /* expected in stream:
778 LCOUNT <u32 loop_count>
782 if ( read(xsvf_fd, count_buf, 4) < 0 )
788 loop_count = be_to_h_u32(count_buf);
789 LOG_DEBUG("LCOUNT %d", loop_count);
795 /* expected in stream:
796 LDELAY <u8 wait_state> <u32 clock_count> <u32 usecs_to_sleep>
802 if ( read(xsvf_fd, &state, 1) < 0
803 || read(xsvf_fd, clock_buf, 4) < 0
804 || read(xsvf_fd, usecs_buf, 4) < 0 )
810 loop_state = xsvf_to_tap(state);
811 loop_clocks = be_to_h_u32(clock_buf);
812 loop_usecs = be_to_h_u32(usecs_buf);
814 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(loop_state), loop_clocks, loop_usecs);
818 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
819 * comes with clocks !AND! sleep requirements.
823 int limit = loop_count;
829 if ( xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
830 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
839 for( attempt=0; attempt<limit; ++attempt )
843 jtag_add_statemove( loop_state );
844 jtag_add_clocks(loop_clocks);
845 jtag_add_sleep(loop_usecs);
848 field.num_bits = xsdrsize;
849 field.out_value = dr_out_buf;
850 field.in_value = calloc(CEIL(field.num_bits, 8), 1);
852 if (attempt > 0 && verbose)
853 LOG_USER("LSDR retry %d", attempt);
856 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
858 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
860 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
862 free(field.in_value);
865 /* LOG_DEBUG("FLUSHING QUEUE"); */
866 result = jtag_execute_queue();
867 if(result == ERROR_OK)
876 LOG_USER( "LSDR mismatch" );
887 if (read(xsvf_fd, &trst_mode, 1) < 0)
896 jtag_add_reset(1, 0);
900 jtag_add_reset(0, 0);
905 LOG_ERROR( "XTRST mode argument (0x%02X) out of range", trst_mode );
912 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
916 if (do_abort || unsupported || tdo_mismatch)
918 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
920 /* upon error, return the TAPs to a reasonable state */
921 jtag_add_statemove( TAP_IDLE );
922 jtag_execute_queue();
929 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
938 off_t offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
939 command_print(cmd_ctx,
940 "unsupported xsvf command (0x%02X) at offset %jd, aborting",
941 uc, (intmax_t)offset);
947 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
962 command_print(cmd_ctx, "XSVF file programmed successfully");
968 #if 0 /* this comment style used to try and keep uncrustify from adding * at begin of line */
970 PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
972 the following pseudo code clarifies the intent of the xrepeat support. The
973 flow given is for the entire processing of an SVF file, not an XSVF file.
974 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
976 "Pseudo-Code Algorithm for SVF-Based ISP"
978 1. Go to Test-Logic-Reset state
979 2. Go to Run-Test Idle state
982 4. if SIR record then
986 5. else if SDR record then
987 set <repeat count> to 0
988 store <TDI value> as <current TDI value>
989 store <TDO value> as <current TDO value>
990 6. go to Shift-DR state
991 scan in <current TDI value>
992 if <current TDO value> is specified then
993 if <current TDO value> does not equal <actual TDO value> then
994 if <repeat count> > 32 then
996 go to Run-Test Idle state
1005 increment <repeat count> by 1
1006 pause <current pause time> microseconds
1010 go to Run-Test Idle state
1013 else if RUNTEST record then
1014 pause tester for <TCK value> microseconds
1015 store <TCK value> as <current pause time>