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, see <http://www.gnu.org/licenses/>. *
26 ***************************************************************************/
28 /* The specification for SVF is available here:
29 * http://www.asset-intertech.com/support/svf.pdf
30 * Below, this document is referred to as the "SVF spec".
32 * The specification for XSVF is available here:
33 * http://www.xilinx.com/support/documentation/application_notes/xapp503.pdf
34 * Below, this document is referred to as the "XSVF spec".
42 #include "helper/system.h"
43 #include <jtag/jtag.h>
46 /* XSVF commands, from appendix B of xapp503.pdf */
47 #define XCOMPLETE 0x00
55 #define XSETSDRMASKS 0x0A
70 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
71 * generates this. Arguably it is needed because the XSVF XRUNTEST command
72 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
73 * This XWAITSTATE does map directly from the SVF RUNTEST command.
75 #define XWAITSTATE 0x18
77 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
78 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
79 * Here is an example of usage of the 3 lattice opcode extensions:
81 ! Set the maximum loop count to 25.
83 ! Step to DRPAUSE give 5 clocks and wait for 1.00e + 000 SEC.
84 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
85 ! Test for the completed status. Match means pass.
86 ! Loop back to LDELAY line if not match and loop count less than 25.
97 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
98 #define XSV_RESET 0x00
100 #define XSV_DRSELECT 0x02
101 #define XSV_DRCAPTURE 0x03
102 #define XSV_DRSHIFT 0x04
103 #define XSV_DREXIT1 0x05
104 #define XSV_DRPAUSE 0x06
105 #define XSV_DREXIT2 0x07
106 #define XSV_DRUPDATE 0x08
107 #define XSV_IRSELECT 0x09
108 #define XSV_IRCAPTURE 0x0A
109 #define XSV_IRSHIFT 0x0B
110 #define XSV_IREXIT1 0x0C
111 #define XSV_IRPAUSE 0x0D
112 #define XSV_IREXIT2 0x0E
113 #define XSV_IRUPDATE 0x0F
115 /* arguments to XTRST */
119 #define XTRST_ABSENT 3
121 #define XSTATE_MAX_PATH 12
125 /* map xsvf tap state to an openocd "tap_state_t" */
126 static tap_state_t xsvf_to_tap(int xsvf_state)
130 switch (xsvf_state) {
180 LOG_ERROR("UNKNOWN XSVF STATE 0x%02X", xsvf_state);
187 static int xsvf_read_buffer(int num_bits, int fd, uint8_t *buf)
191 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--) {
192 /* reverse the order of bytes as they are read sequentially from file */
193 if (read(fd, buf + num_bytes - 1, 1) < 0)
194 return ERROR_XSVF_EOF;
200 COMMAND_HANDLER(handle_xsvf_command)
202 uint8_t *dr_out_buf = NULL; /* from host to device (TDI) */
203 uint8_t *dr_in_buf = NULL; /* from device to host (TDO) */
204 uint8_t *dr_in_mask = NULL;
207 int xruntest = 0; /* number of TCK cycles OR *microseconds */
208 int xrepeat = 0; /* number of retries */
210 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial
211 *xendir to be TAP_IDLE */
212 tap_state_t xenddr = TAP_IDLE;
216 long file_offset = 0;
219 tap_state_t loop_state = TAP_IDLE;
225 int tdo_mismatch = 0;
229 bool collecting_path = false;
230 tap_state_t path[XSTATE_MAX_PATH];
231 unsigned pathlen = 0;
233 /* a flag telling whether to clock TCK during waits,
234 * or simply sleep, controlled by virt2
236 int runtest_requires_tck = 0;
238 /* use NULL to indicate a "plain" xsvf file which accounts for
239 * additional devices in the scan chain, otherwise the device
240 * that should be affected
242 struct jtag_tap *tap = NULL;
245 return ERROR_COMMAND_SYNTAX_ERROR;
247 /* we mess with CMD_ARGV starting point below, snapshot filename here */
248 const char *filename = CMD_ARGV[1];
250 if (strcmp(CMD_ARGV[0], "plain") != 0) {
251 tap = jtag_tap_by_string(CMD_ARGV[0]);
253 command_print(CMD, "Tap: %s unknown", CMD_ARGV[0]);
258 xsvf_fd = open(filename, O_RDONLY);
260 command_print(CMD, "file \"%s\" not found", filename);
264 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as
266 if ((CMD_ARGC > 2) && (strcmp(CMD_ARGV[2], "virt2") == 0)) {
267 runtest_requires_tck = 1;
272 if ((CMD_ARGC > 2) && (strcmp(CMD_ARGV[2], "quiet") == 0))
275 LOG_WARNING("XSVF support in OpenOCD is limited. Consider using SVF instead");
276 LOG_USER("xsvf processing file: \"%s\"", filename);
278 while (read(xsvf_fd, &opcode, 1) > 0) {
279 /* record the position of this opcode within the file */
280 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
282 /* maybe collect another state for a pathmove();
283 * or terminate a path.
285 if (collecting_path) {
290 /* ignore/show comments between XSTATE ops */
293 /* try to collect another transition */
294 if (pathlen == XSTATE_MAX_PATH) {
295 LOG_ERROR("XSVF: path too long");
300 if (read(xsvf_fd, &uc, 1) < 0) {
305 mystate = xsvf_to_tap(uc);
306 path[pathlen++] = mystate;
308 LOG_DEBUG("XSTATE 0x%02X %s", uc,
309 tap_state_name(mystate));
311 /* If path is incomplete, collect more */
312 if (!svf_tap_state_is_stable(mystate))
315 /* Else execute the path transitions we've
318 * NOTE: Punting on the saved path is not
319 * strictly correct, but we must to do this
320 * unless jtag_add_pathmove() stops rejecting
321 * paths containing RESET. This is probably
322 * harmless, since there aren't many options
323 * for going from a stable state to reset;
324 * at the worst, we may issue extra clocks
325 * once we get to RESET.
327 if (mystate == TAP_RESET) {
328 LOG_WARNING("XSVF: dodgey RESET");
334 /* Execute the path we collected
336 * NOTE: OpenOCD requires something that XSVF
337 * doesn't: the last TAP state in the path
338 * must be stable. In practice, tools that
339 * create XSVF seem to follow that rule too.
341 collecting_path = false;
343 if (path[0] == TAP_RESET)
346 jtag_add_pathmove(pathlen, path);
348 result = jtag_execute_queue();
349 if (result != ERROR_OK) {
350 LOG_ERROR("XSVF: pathmove error %d", result);
360 LOG_DEBUG("XCOMPLETE");
362 result = jtag_execute_queue();
363 if (result != ERROR_OK) {
370 LOG_DEBUG("XTDOMASK");
372 (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
378 uint8_t xruntest_buf[4];
380 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)
398 LOG_DEBUG("XREPEAT %d", xrepeat);
405 uint8_t xsdrsize_buf[4];
407 if (read(xsvf_fd, xsdrsize_buf, 4) < 0) {
412 xsdrsize = be_to_h_u32(xsdrsize_buf);
413 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
419 dr_out_buf = malloc((xsdrsize + 7) / 8);
420 dr_in_buf = malloc((xsdrsize + 7) / 8);
421 dr_in_mask = malloc((xsdrsize + 7) / 8);
425 case XSDR: /* these two are identical except for the dr_in_buf */
432 const char *op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
434 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK) {
439 if (opcode == XSDRTDO) {
440 if (xsvf_read_buffer(xsdrsize, xsvf_fd,
441 dr_in_buf) != ERROR_OK) {
450 LOG_DEBUG("%s %d", op_name, xsdrsize);
452 for (attempt = 0; attempt < limit; ++attempt) {
453 struct scan_field field;
456 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
457 * illustrated in pseudo code at end of this file. We start from state
463 * go to Run-Test/Idle
465 * This sequence should be harmless for other devices, and it
466 * will be skipped entirely if xrepeat is set to zero.
469 static tap_state_t exception_path[] = {
477 jtag_add_pathmove(ARRAY_SIZE(exception_path), exception_path);
480 LOG_USER("%s mismatch, xsdrsize=%d retry=%d",
486 field.num_bits = xsdrsize;
487 field.out_value = dr_out_buf;
488 field.in_value = calloc(DIV_ROUND_UP(field.num_bits, 8), 1);
491 jtag_add_plain_dr_scan(field.num_bits,
496 jtag_add_dr_scan(tap, 1, &field, TAP_DRPAUSE);
498 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
500 free(field.in_value);
502 /* LOG_DEBUG("FLUSHING QUEUE"); */
503 result = jtag_execute_queue();
504 if (result == ERROR_OK) {
511 LOG_USER("%s mismatch", op_name);
516 /* See page 19 of XSVF spec regarding opcode "XSDR" */
518 result = svf_add_statemove(TAP_IDLE);
519 if (result != ERROR_OK)
522 if (runtest_requires_tck)
523 jtag_add_clocks(xruntest);
525 jtag_add_sleep(xruntest);
526 } else if (xendir != TAP_DRPAUSE) {
527 /* we are already in TAP_DRPAUSE */
528 result = svf_add_statemove(xenddr);
529 if (result != ERROR_OK)
536 LOG_ERROR("unsupported XSETSDRMASKS");
541 LOG_ERROR("unsupported XSDRINC");
546 LOG_ERROR("unsupported XSDRB");
551 LOG_ERROR("unsupported XSDRC");
556 LOG_ERROR("unsupported XSDRE");
561 LOG_ERROR("unsupported XSDRTDOB");
566 LOG_ERROR("unsupported XSDRTDOC");
571 LOG_ERROR("unsupported XSDRTDOE");
579 if (read(xsvf_fd, &uc, 1) < 0) {
584 mystate = xsvf_to_tap(uc);
586 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate));
588 if (mystate == TAP_INVALID) {
589 LOG_ERROR("XSVF: bad XSTATE %02x", uc);
594 /* NOTE: the current state is SVF-stable! */
596 /* no change == NOP */
597 if (mystate == cmd_queue_cur_state
598 && mystate != TAP_RESET)
601 /* Hand off to SVF? */
602 if (svf_tap_state_is_stable(mystate)) {
603 result = svf_add_statemove(mystate);
604 if (result != ERROR_OK)
610 * A sequence of XSTATE transitions, each TAP
611 * state adjacent to the previous one. Start
614 collecting_path = true;
622 if (read(xsvf_fd, &uc, 1) < 0) {
627 /* see page 22 of XSVF spec */
631 xendir = TAP_IRPAUSE;
633 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
638 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
643 if (read(xsvf_fd, &uc, 1) < 0) {
648 /* see page 22 of XSVF spec */
652 xenddr = TAP_DRPAUSE;
654 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
659 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
665 uint8_t short_buf[2];
668 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
670 if (opcode == XSIR) {
671 /* one byte bitcount */
672 if (read(xsvf_fd, short_buf, 1) < 0) {
676 bitcount = short_buf[0];
677 LOG_DEBUG("XSIR %d", bitcount);
679 if (read(xsvf_fd, short_buf, 2) < 0) {
683 bitcount = be_to_h_u16(short_buf);
684 LOG_DEBUG("XSIR2 %d", bitcount);
687 ir_buf = malloc((bitcount + 7) / 8);
689 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
692 struct scan_field field;
694 field.num_bits = bitcount;
695 field.out_value = ir_buf;
697 field.in_value = NULL;
700 jtag_add_plain_ir_scan(field.num_bits,
701 field.out_value, field.in_value, my_end_state);
703 jtag_add_ir_scan(tap, &field, my_end_state);
706 if (runtest_requires_tck)
707 jtag_add_clocks(xruntest);
709 jtag_add_sleep(xruntest);
712 /* Note that an -irmask of non-zero in your config file
713 * can cause this to fail. Setting -irmask to zero cand work
714 * around the problem.
717 /* LOG_DEBUG("FLUSHING QUEUE"); */
718 result = jtag_execute_queue();
719 if (result != ERROR_OK)
728 unsigned int ndx = 0;
732 if (read(xsvf_fd, &uc, 1) < 0) {
737 if (ndx < sizeof(comment)-1)
742 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
744 LOG_USER("# %s", comment);
750 /* expected in stream:
751 XWAIT <uint8_t wait_state> <uint8_t end_state> <uint32_t usecs>
756 uint8_t delay_buf[4];
758 tap_state_t wait_state;
759 tap_state_t end_state;
762 if (read(xsvf_fd, &wait_local, 1) < 0
763 || read(xsvf_fd, &end, 1) < 0
764 || read(xsvf_fd, delay_buf, 4) < 0) {
769 wait_state = xsvf_to_tap(wait_local);
770 end_state = xsvf_to_tap(end);
771 delay = be_to_h_u32(delay_buf);
773 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(
774 wait_state), tap_state_name(end_state), delay);
776 if (runtest_requires_tck && wait_state == TAP_IDLE)
777 jtag_add_runtest(delay, end_state);
779 /* FIXME handle statemove errors ... */
780 result = svf_add_statemove(wait_state);
781 if (result != ERROR_OK)
783 jtag_add_sleep(delay);
784 result = svf_add_statemove(end_state);
785 if (result != ERROR_OK)
793 /* expected in stream:
794 * XWAITSTATE <uint8_t wait_state> <uint8_t end_state> <uint32_t clock_count>
798 uint8_t clock_buf[4];
799 uint8_t usecs_buf[4];
802 tap_state_t wait_state;
803 tap_state_t end_state;
807 if (read(xsvf_fd, &wait_local, 1) < 0
808 || read(xsvf_fd, &end, 1) < 0
809 || read(xsvf_fd, clock_buf, 4) < 0
810 || read(xsvf_fd, usecs_buf, 4) < 0) {
815 wait_state = xsvf_to_tap(wait_local);
816 end_state = xsvf_to_tap(end);
818 clock_count = be_to_h_u32(clock_buf);
819 usecs = be_to_h_u32(usecs_buf);
821 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
822 tap_state_name(wait_state),
823 tap_state_name(end_state),
826 /* the following states are 'stable', meaning that they have a transition
827 * in the state diagram back to themselves. This is necessary because we will
828 * be issuing a number of clocks in this state. This set of allowed states is also
829 * determined by the SVF RUNTEST command's allowed states.
831 if (!svf_tap_state_is_stable(wait_state)) {
832 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"",
833 tap_state_name(wait_state));
835 /* REVISIT "break" so we won't run? */
838 /* FIXME handle statemove errors ... */
839 result = svf_add_statemove(wait_state);
840 if (result != ERROR_OK)
843 jtag_add_clocks(clock_count);
844 jtag_add_sleep(usecs);
846 result = svf_add_statemove(end_state);
847 if (result != ERROR_OK)
854 /* expected in stream:
855 * LCOUNT <uint32_t loop_count>
857 uint8_t count_buf[4];
859 if (read(xsvf_fd, count_buf, 4) < 0) {
864 loop_count = be_to_h_u32(count_buf);
865 LOG_DEBUG("LCOUNT %d", loop_count);
871 /* expected in stream:
872 * LDELAY <uint8_t wait_state> <uint32_t clock_count> <uint32_t usecs_to_sleep>
875 uint8_t clock_buf[4];
876 uint8_t usecs_buf[4];
878 if (read(xsvf_fd, &state, 1) < 0
879 || read(xsvf_fd, clock_buf, 4) < 0
880 || read(xsvf_fd, usecs_buf, 4) < 0) {
885 /* NOTE: loop_state must be stable! */
886 loop_state = xsvf_to_tap(state);
887 loop_clocks = be_to_h_u32(clock_buf);
888 loop_usecs = be_to_h_u32(usecs_buf);
890 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(
891 loop_state), loop_clocks, loop_usecs);
895 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
896 * comes with clocks !AND! sleep requirements.
900 int limit = loop_count;
906 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
907 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK) {
915 for (attempt = 0; attempt < limit; ++attempt) {
916 struct scan_field field;
918 result = svf_add_statemove(loop_state);
919 if (result != ERROR_OK) {
923 jtag_add_clocks(loop_clocks);
924 jtag_add_sleep(loop_usecs);
926 field.num_bits = xsdrsize;
927 field.out_value = dr_out_buf;
928 field.in_value = calloc(DIV_ROUND_UP(field.num_bits, 8), 1);
930 if (attempt > 0 && verbose)
931 LOG_USER("LSDR retry %d", attempt);
934 jtag_add_plain_dr_scan(field.num_bits,
939 jtag_add_dr_scan(tap, 1, &field, TAP_DRPAUSE);
941 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
943 free(field.in_value);
946 /* LOG_DEBUG("FLUSHING QUEUE"); */
947 result = jtag_execute_queue();
948 if (result == ERROR_OK) {
955 LOG_USER("LSDR mismatch");
966 if (read(xsvf_fd, &trst_mode, 1) < 0) {
973 jtag_add_reset(1, 0);
977 jtag_add_reset(0, 0);
982 LOG_ERROR("XTRST mode argument (0x%02X) out of range", trst_mode);
989 LOG_ERROR("unknown xsvf command (0x%02X)", uc);
993 if (do_abort || unsupported || tdo_mismatch) {
994 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
996 /* upon error, return the TAPs to a reasonable state */
997 result = svf_add_statemove(TAP_IDLE);
998 if (result != ERROR_OK)
1000 result = jtag_execute_queue();
1001 if (result != ERROR_OK)
1009 "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
1016 off_t offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
1018 "unsupported xsvf command (0x%02X) at offset %jd, aborting",
1019 uc, (intmax_t)offset);
1024 command_print(CMD, "premature end of xsvf file detected, aborting");
1034 command_print(CMD, "XSVF file programmed successfully");
1039 static const struct command_registration xsvf_command_handlers[] = {
1042 .handler = handle_xsvf_command,
1043 .mode = COMMAND_EXEC,
1044 .help = "Runs a XSVF file. If 'virt2' is given, xruntest "
1045 "counts are interpreted as TCK cycles rather than "
1046 "as microseconds. Without the 'quiet' option, all "
1047 "comments, retries, and mismatches will be reported.",
1048 .usage = "(tapname|'plain') filename ['virt2'] ['quiet']",
1050 COMMAND_REGISTRATION_DONE
1053 int xsvf_register_commands(struct command_context *cmd_ctx)
1055 return register_commands(cmd_ctx, NULL, xsvf_command_handlers);
1060 PSEUDO-Code from Xilinx Appnote XAPP067.pdf :
1062 the following pseudo code clarifies the intent of the xrepeat support.The
1063 flow given is for the entire processing of an SVF file, not an XSVF file.
1064 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1066 "Pseudo-Code Algorithm for SVF-Based ISP"
1068 1. Go to Test-Logic-Reset state
1069 2. Go to Run-Test Idle state
1072 4. if SIR record then
1073 go to Shift-IR state
1076 5. else if SDR record then
1077 set <repeat count> to 0
1078 store <TDI value> as <current TDI value>
1079 store <TDO value> as <current TDO value>
1080 6. go to Shift-DR state
1081 scan in <current TDI value>
1082 if < current TDO value > is specified then
1083 if < current TDO value > does not equal <actual TDO value> then
1084 if < repeat count > > 32 then
1086 go to Run-Test Idle state
1095 increment <repeat count> by 1
1096 pause <current pause time> microseconds
1100 go to Run-Test Idle state
1103 else if RUNTEST record then
1104 pause tester for < TCK value > microseconds
1105 store <TCK value> as <current pause time>