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 *
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>
61 /* XSVF commands, from appendix B of xapp503.pdf */
62 #define XCOMPLETE 0x00
70 #define XSETSDRMASKS 0x0A
85 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
86 * generates this. Arguably it is needed because the XSVF XRUNTEST command
87 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
88 * This XWAITSTATE does map directly from the SVF RUNTEST command.
90 #define XWAITSTATE 0x18
92 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
93 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
94 * Here is an example of usage of the 3 lattice opcode extensions:
96 ! Set the maximum loop count to 25.
98 ! Step to DRPAUSE give 5 clocks and wait for 1.00e+000 SEC.
99 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
100 ! Test for the completed status. Match means pass.
101 ! Loop back to LDELAY line if not match and loop count less than 25.
112 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
113 #define XSV_RESET 0x00
114 #define XSV_IDLE 0x01
115 #define XSV_DRSELECT 0x02
116 #define XSV_DRCAPTURE 0x03
117 #define XSV_DRSHIFT 0x04
118 #define XSV_DREXIT1 0x05
119 #define XSV_DRPAUSE 0x06
120 #define XSV_DREXIT2 0x07
121 #define XSV_DRUPDATE 0x08
122 #define XSV_IRSELECT 0x09
123 #define XSV_IRCAPTURE 0x0A
124 #define XSV_IRSHIFT 0x0B
125 #define XSV_IREXIT1 0x0C
126 #define XSV_IRPAUSE 0x0D
127 #define XSV_IREXIT2 0x0E
128 #define XSV_IRUPDATE 0x0F
131 #define XSTATE_MAX_PATH 12
133 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc);
135 static int xsvf_fd = 0;
138 /* map xsvf tap state to an openocd "enum tap_state" */
139 static tap_state_t xsvf_to_tap( int xsvf_state )
145 case XSV_RESET: ret = TAP_RESET; break;
146 case XSV_IDLE: ret = TAP_IDLE; break;
147 case XSV_DRSELECT: ret = TAP_DRSELECT; break;
148 case XSV_DRCAPTURE: ret = TAP_DRCAPTURE; break;
149 case XSV_DRSHIFT: ret = TAP_DRSHIFT; break;
150 case XSV_DREXIT1: ret = TAP_DREXIT1; break;
151 case XSV_DRPAUSE: ret = TAP_DRPAUSE; break;
152 case XSV_DREXIT2: ret = TAP_DREXIT2; break;
153 case XSV_DRUPDATE: ret = TAP_DRUPDATE; break;
154 case XSV_IRSELECT: ret = TAP_IRSELECT; break;
155 case XSV_IRCAPTURE: ret = TAP_IRCAPTURE; break;
156 case XSV_IRSHIFT: ret = TAP_IRSHIFT; break;
157 case XSV_IREXIT1: ret = TAP_IREXIT1; break;
158 case XSV_IRPAUSE: ret = TAP_IRPAUSE; break;
159 case XSV_IREXIT2: ret = TAP_IREXIT2; break;
160 case XSV_IRUPDATE: ret = TAP_IRUPDATE; break;
162 LOG_ERROR( "UNKNOWN XSVF STATE 0x%02X", xsvf_state );
170 /* xsvf has it's own definition of a statemove. This needs
171 * to be handled according to the xsvf spec, which has nothing
172 * to do with the JTAG spec or OpenOCD as such.
174 * Implemented via jtag_add_pathmove().
176 static void xsvf_add_statemove(tap_state_t state)
178 tap_state_t moves[7]; /* max # of transitions */
179 tap_state_t curstate = cmd_queue_cur_state;
182 u8 move = TAP_MOVE(cmd_queue_cur_state, state);
184 if (state != TAP_RESET && state==cmd_queue_cur_state)
195 int j = (move >> i) & 1;
198 curstate = tap_transitions[curstate].high;
202 curstate = tap_transitions[curstate].low;
207 jtag_add_pathmove(7, moves);
210 int xsvf_register_commands(struct command_context_s *cmd_ctx)
212 register_command(cmd_ctx, NULL, "xsvf", handle_xsvf_command,
213 COMMAND_EXEC, "run xsvf <file> [virt2]");
218 static int xsvf_read_buffer(int num_bits, int fd, u8* buf)
222 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--)
224 /* reverse the order of bytes as they are read sequentially from file */
225 if (read(fd, buf + num_bytes - 1, 1) < 0)
226 return ERROR_XSVF_EOF;
233 static int xsvf_read_xstates(int fd, tap_state_t *path, int max_path, int *path_len)
238 while ((read(fd, &c, 1) > 0) && (c == XSTATE))
242 if (*path_len > max_path)
244 LOG_WARNING("XSTATE path longer than max_path");
247 if (read(fd, &uc, 1) < 0)
249 return ERROR_XSVF_EOF;
252 mystate = xsvf_to_tap(uc);
254 LOG_DEBUG("XSTATE %02X %s", uc, jtag_state_name(mystate) );
256 path[(*path_len)++] = mystate;
259 lseek(fd, -1, SEEK_CUR);
265 static int handle_xsvf_command(struct command_context_s *cmd_ctx, char *cmd, char **args, int argc)
267 u8 *dr_out_buf = NULL; /* from host to device (TDI) */
268 u8 *dr_in_buf = NULL; /* from device to host (TDO) */
269 u8 *dr_in_mask = NULL;
272 int xruntest = 0; /* number of TCK cycles OR microseconds */
273 int xrepeat = 0; /* number of retries */
275 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial xendir to be TAP_IDLE */
276 tap_state_t xenddr = TAP_IDLE;
280 long file_offset = 0;
283 tap_state_t loop_state = TAP_IDLE;
289 int tdo_mismatch = 0;
292 int runtest_requires_tck = 0; /* a flag telling whether to clock TCK during waits, or simply sleep, controled by virt2 */
295 /* use NULL to indicate a "plain" xsvf file which accounts for
296 additional devices in the scan chain, otherwise the device
297 that should be affected
299 jtag_tap_t *tap = NULL;
303 command_print(cmd_ctx, "usage: xsvf <device#|plain> <file> <variant>");
307 if (strcmp(args[0], "plain") != 0)
309 tap = jtag_TapByString( args[0] );
312 command_print( cmd_ctx, "Tap: %s unknown", args[0] );
317 if ((xsvf_fd = open(args[1], O_RDONLY)) < 0)
319 command_print(cmd_ctx, "file \"%s\" not found", args[1]);
323 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as usecs */
324 if ((argc > 2) && (strcmp(args[2], "virt2") == 0))
326 runtest_requires_tck = 1;
329 LOG_USER("xsvf processing file: \"%s\"", args[1]);
331 while( read(xsvf_fd, &opcode, 1) > 0 )
333 /* record the position of the just read opcode within the file */
334 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
339 LOG_DEBUG("XCOMPLETE");
341 result = jtag_execute_queue();
342 if (result != ERROR_OK)
350 LOG_DEBUG("XTDOMASK");
351 if (dr_in_mask && (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
359 if (read(xsvf_fd, xruntest_buf, 4) < 0)
365 xruntest = be_to_h_u32(xruntest_buf);
366 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
374 if (read(xsvf_fd, &myrepeat, 1) < 0)
379 LOG_DEBUG("XREPEAT %d", xrepeat );
388 if (read(xsvf_fd, xsdrsize_buf, 4) < 0)
394 xsdrsize = be_to_h_u32(xsdrsize_buf);
395 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
397 if( dr_out_buf ) free(dr_out_buf);
398 if( dr_in_buf) free(dr_in_buf);
399 if( dr_in_mask) free(dr_in_mask);
401 dr_out_buf = malloc((xsdrsize + 7) / 8);
402 dr_in_buf = malloc((xsdrsize + 7) / 8);
403 dr_in_mask = malloc((xsdrsize + 7) / 8);
407 case XSDR: /* these two are identical except for the dr_in_buf */
414 const char* op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
416 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK)
422 if (opcode == XSDRTDO)
424 if(xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
434 LOG_DEBUG("%s %d", op_name, xsdrsize);
436 for( attempt=0; attempt<limit; ++attempt )
442 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
443 illustrated in psuedo code at end of this file. We start from state
451 This sequence should be harmless for other devices, and it
452 will be skipped entirely if xrepeat is set to zero.
455 static tap_state_t exception_path[] = {
463 jtag_add_pathmove( sizeof(exception_path)/sizeof(exception_path[0]), exception_path);
465 LOG_USER("%s %d retry %d", op_name, xsdrsize, attempt);
469 field.num_bits = xsdrsize;
470 field.out_value = dr_out_buf;
471 field.out_mask = NULL;
472 field.in_value = NULL;
474 jtag_set_check_value(&field, dr_in_buf, dr_in_mask, NULL);
477 jtag_add_plain_dr_scan(1, &field, TAP_DRPAUSE);
479 jtag_add_dr_scan(1, &field, TAP_DRPAUSE);
481 /* LOG_DEBUG("FLUSHING QUEUE"); */
482 result = jtag_execute_queue();
483 if (result == ERROR_OK)
492 LOG_USER( "%s mismatch", op_name);
497 /* See page 19 of XSVF spec regarding opcode "XSDR" */
500 xsvf_add_statemove(TAP_IDLE);
502 if (runtest_requires_tck)
503 jtag_add_clocks(xruntest);
505 jtag_add_sleep(xruntest);
507 else if (xendir != TAP_DRPAUSE) /* we are already in TAP_DRPAUSE */
508 xsvf_add_statemove(xenddr);
513 LOG_ERROR("unsupported XSETSDRMASKS\n");
518 LOG_ERROR("unsupported XSDRINC\n");
523 LOG_ERROR("unsupported XSDRB\n");
528 LOG_ERROR("unsupported XSDRC\n");
533 LOG_ERROR("unsupported XSDRE\n");
538 LOG_ERROR("unsupported XSDRTDOB\n");
543 LOG_ERROR("unsupported XSDRTDOC\n");
548 LOG_ERROR("unsupported XSDRTDOE\n");
558 if (read(xsvf_fd, &uc, 1) < 0)
564 mystate = xsvf_to_tap(uc);
566 LOG_DEBUG("XSTATE 0x%02X %s", uc, jtag_state_name(mystate) );
568 path = calloc(XSTATE_MAX_PATH, 4);
572 if (xsvf_read_xstates(xsvf_fd, path, XSTATE_MAX_PATH, &path_len) != ERROR_OK)
578 /* here the trick is that jtag_add_pathmove() must end in a stable
579 * state, so we must only invoke jtag_add_tlr() when we absolutely
582 for(i=0,lasti=0; i<path_len; i++)
584 if(path[i]==TAP_RESET)
588 jtag_add_pathmove(i-lasti,path+lasti);
596 jtag_add_pathmove(i-lasti, path+lasti);
607 if (read(xsvf_fd, &uc, 1) < 0)
613 /* see page 22 of XSVF spec */
614 mystate = uc == 1 ? TAP_IRPAUSE : TAP_IDLE;
616 LOG_DEBUG("XENDIR 0x%02X %s", uc, jtag_state_name(mystate));
618 /* assuming that the XRUNTEST comes from SVF RUNTEST, then only these states
619 * should come here because the SVF spec only allows these with a RUNTEST
621 if (mystate != TAP_IRPAUSE && mystate != TAP_DRPAUSE && mystate != TAP_RESET && mystate != TAP_IDLE )
623 LOG_ERROR("illegal XENDIR endstate: \"%s\"", jtag_state_name(mystate));
635 if (read(xsvf_fd, &uc, 1) < 0)
641 /* see page 22 of XSVF spec */
642 mystate = uc == 1 ? TAP_DRPAUSE : TAP_IDLE;
644 LOG_DEBUG("XENDDR %02X %s", uc, jtag_state_name(mystate));
646 if (mystate != TAP_IRPAUSE && mystate != TAP_DRPAUSE && mystate != TAP_RESET && mystate != TAP_IDLE )
648 LOG_ERROR("illegal XENDDR endstate: \"%s\"", jtag_state_name( mystate ));
662 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
666 /* one byte bitcount */
667 if (read(xsvf_fd, short_buf, 1) < 0)
672 bitcount = short_buf[0];
673 LOG_DEBUG("XSIR %d", bitcount);
677 if (read(xsvf_fd, short_buf, 2) < 0)
682 bitcount = be_to_h_u16(short_buf);
683 LOG_DEBUG("XSIR2 %d", bitcount);
686 ir_buf = malloc((bitcount+7) / 8);
688 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
695 field.num_bits = bitcount;
696 field.out_value = ir_buf;
697 field.out_mask = NULL;
698 field.in_value = NULL;
699 field.in_check_value = NULL;
700 field.in_check_mask = NULL;
701 field.in_handler = NULL;
702 field.in_handler_priv = NULL;
705 jtag_add_plain_ir_scan(1, &field, my_end_state);
707 jtag_add_ir_scan(1, &field, my_end_state);
711 if (runtest_requires_tck)
712 jtag_add_clocks(xruntest);
714 jtag_add_sleep(xruntest);
717 /* Note that an -irmask of non-zero in your config file
718 * can cause this to fail. Setting -irmask to zero cand work
719 * around the problem.
722 /* LOG_DEBUG("FLUSHING QUEUE"); */
723 result = jtag_execute_queue();
724 if(result != ERROR_OK)
740 if (read(xsvf_fd, &uc, 1) < 0)
746 if ( ndx < sizeof(comment)-1 )
751 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
758 /* expected in stream:
759 XWAIT <u8 wait_state> <u8 end_state> <u32 usecs>
766 tap_state_t wait_state;
767 tap_state_t end_state;
770 if ( read(xsvf_fd, &wait, 1) < 0
771 || read(xsvf_fd, &end, 1) < 0
772 || read(xsvf_fd, delay_buf, 4) < 0)
778 wait_state = xsvf_to_tap(wait);
779 end_state = xsvf_to_tap(end);
780 delay = be_to_h_u32(delay_buf);
782 LOG_DEBUG("XWAIT %s %s usecs:%d", jtag_state_name(wait_state), jtag_state_name(end_state), delay);
784 if (runtest_requires_tck && wait_state == TAP_IDLE )
786 jtag_add_runtest(delay, end_state);
790 xsvf_add_statemove( wait_state );
791 jtag_add_sleep(delay);
792 xsvf_add_statemove( end_state );
799 /* expected in stream:
800 XWAITSTATE <u8 wait_state> <u8 end_state> <u32 clock_count> <u32 usecs>
807 tap_state_t wait_state;
808 tap_state_t end_state;
812 if ( read(xsvf_fd, &wait, 1) < 0
813 || read(xsvf_fd, &end, 1) < 0
814 || read(xsvf_fd, clock_buf, 4) < 0
815 || read(xsvf_fd, usecs_buf, 4) < 0 )
821 wait_state = xsvf_to_tap( wait );
822 end_state = xsvf_to_tap( end );
824 clock_count = be_to_h_u32(clock_buf);
825 usecs = be_to_h_u32(usecs_buf);
827 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
828 jtag_state_name(wait_state),
829 jtag_state_name(end_state),
832 /* the following states are 'stable', meaning that they have a transition
833 * in the state diagram back to themselves. This is necessary because we will
834 * be issuing a number of clocks in this state. This set of allowed states is also
835 * determined by the SVF RUNTEST command's allowed states.
837 if (wait_state != TAP_IRPAUSE && wait_state != TAP_DRPAUSE && wait_state != TAP_RESET && wait_state != TAP_IDLE)
839 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"", jtag_state_name( wait_state ));
843 xsvf_add_statemove( wait_state );
845 jtag_add_clocks( clock_count );
847 jtag_add_sleep( usecs );
849 xsvf_add_statemove( end_state );
855 /* expected in stream:
856 LCOUNT <u32 loop_count>
860 if ( read(xsvf_fd, count_buf, 4) < 0 )
866 loop_count = be_to_h_u32(count_buf);
867 LOG_DEBUG("LCOUNT %d", loop_count);
873 /* expected in stream:
874 LDELAY <u8 wait_state> <u32 clock_count> <u32 usecs_to_sleep>
880 if ( read(xsvf_fd, &state, 1) < 0
881 || read(xsvf_fd, clock_buf, 4) < 0
882 || read(xsvf_fd, usecs_buf, 4) < 0 )
888 loop_state = xsvf_to_tap(state);
889 loop_clocks = be_to_h_u32(clock_buf);
890 loop_usecs = be_to_h_u32(usecs_buf);
892 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", jtag_state_name(loop_state), loop_clocks, loop_usecs);
896 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
897 * comes with clocks !AND! sleep requirements.
901 int limit = loop_count;
907 if ( xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
908 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK )
917 for( attempt=0; attempt<limit; ++attempt )
922 field.num_bits = xsdrsize;
923 field.out_value = dr_out_buf;
924 field.out_mask = NULL;
925 field.in_value = NULL;
928 LOG_USER("LSDR retry %d", attempt);
930 jtag_set_check_value(&field, dr_in_buf, dr_in_mask, NULL);
932 jtag_add_plain_dr_scan(1, &field, loop_state);
934 jtag_add_dr_scan(1, &field, loop_state);
936 /* LOG_DEBUG("FLUSHING QUEUE"); */
937 result = jtag_execute_queue();
938 if(result == ERROR_OK)
944 jtag_add_clocks(loop_clocks);
945 jtag_add_sleep(loop_usecs);
950 LOG_USER( "LSDR mismatch" );
958 LOG_ERROR("unknown xsvf command (0x%02X)\n", uc);
962 if (do_abort || unsupported || tdo_mismatch)
964 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
966 /* upon error, return the TAPs to a reasonable state */
967 xsvf_add_statemove( TAP_IDLE );
968 jtag_execute_queue();
975 command_print(cmd_ctx, "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
984 command_print(cmd_ctx,
985 "unsupported xsvf command: 0x%02X in xsvf file at offset %ld, aborting",
986 uc, lseek(xsvf_fd, 0, SEEK_CUR)-1 );
992 command_print(cmd_ctx, "premature end of xsvf file detected, aborting");
1007 command_print(cmd_ctx, "XSVF file programmed successfully");
1013 /* PSUEDO-Code from Xilinx Appnote XAPP067.pdf:
1015 the following pseudo code clarifies the intent of the xrepeat support. The
1016 flow given is for the entire processing of an SVF file, not an XSVF file.
1017 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1019 "Pseudo-Code Algorithm for SVF-Based ISP"
1021 1. Go to Test-Logic-Reset state
1022 2. Go to Run-Test Idle state
1025 4. if SIR record then
1026 go to Shift-IR state
1029 5. else if SDR record then
1030 set <repeat count> to 0
1031 store <TDI value> as <current TDI value>
1032 store <TDO value> as <current TDO value>
1033 6. go to Shift-DR state
1034 scan in <current TDI value>
1035 if <current TDO value> is specified then
1036 if <current TDO value> does not equal <actual TDO value> then
1037 if <repeat count> > 32 then
1039 go to Run-Test Idle state
1048 increment <repeat count> by 1
1049 pause <current pause time> microseconds
1053 go to Run-Test Idle state
1056 else if RUNTEST record then
1057 pause tester for <TCK value> microseconds
1058 store <TCK value> as <current pause time>