1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3 /***************************************************************************
4 * Copyright (C) 2005 by Dominic Rath *
5 * Dominic.Rath@gmx.de *
7 * Copyright (C) 2007,2008 Øyvind Harboe *
8 * oyvind.harboe@zylin.com *
10 * Copyright (C) 2008 Peter Hettkamp *
11 * peter.hettkamp@htp-tel.de *
13 * Copyright (C) 2009 SoftPLC Corporation. http://softplc.com *
14 * Dick Hollenbeck <dick@softplc.com> *
15 ***************************************************************************/
17 /* The specification for SVF is available here:
18 * http://www.asset-intertech.com/support/svf.pdf
19 * Below, this document is referred to as the "SVF spec".
21 * The specification for XSVF is available here:
22 * http://www.xilinx.com/support/documentation/application_notes/xapp503.pdf
23 * Below, this document is referred to as the "XSVF spec".
31 #include "helper/system.h"
32 #include <jtag/jtag.h>
35 /* XSVF commands, from appendix B of xapp503.pdf */
36 #define XCOMPLETE 0x00
44 #define XSETSDRMASKS 0x0A
59 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
60 * generates this. Arguably it is needed because the XSVF XRUNTEST command
61 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
62 * This XWAITSTATE does map directly from the SVF RUNTEST command.
64 #define XWAITSTATE 0x18
66 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
67 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
68 * Here is an example of usage of the 3 lattice opcode extensions:
70 ! Set the maximum loop count to 25.
72 ! Step to DRPAUSE give 5 clocks and wait for 1.00e + 000 SEC.
73 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
74 ! Test for the completed status. Match means pass.
75 ! Loop back to LDELAY line if not match and loop count less than 25.
86 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
87 #define XSV_RESET 0x00
89 #define XSV_DRSELECT 0x02
90 #define XSV_DRCAPTURE 0x03
91 #define XSV_DRSHIFT 0x04
92 #define XSV_DREXIT1 0x05
93 #define XSV_DRPAUSE 0x06
94 #define XSV_DREXIT2 0x07
95 #define XSV_DRUPDATE 0x08
96 #define XSV_IRSELECT 0x09
97 #define XSV_IRCAPTURE 0x0A
98 #define XSV_IRSHIFT 0x0B
99 #define XSV_IREXIT1 0x0C
100 #define XSV_IRPAUSE 0x0D
101 #define XSV_IREXIT2 0x0E
102 #define XSV_IRUPDATE 0x0F
104 /* arguments to XTRST */
108 #define XTRST_ABSENT 3
110 #define XSTATE_MAX_PATH 12
114 /* map xsvf tap state to an openocd "tap_state_t" */
115 static tap_state_t xsvf_to_tap(int xsvf_state)
119 switch (xsvf_state) {
169 LOG_ERROR("UNKNOWN XSVF STATE 0x%02X", xsvf_state);
176 static int xsvf_read_buffer(int num_bits, int fd, uint8_t *buf)
180 for (num_bytes = (num_bits + 7) / 8; num_bytes > 0; num_bytes--) {
181 /* reverse the order of bytes as they are read sequentially from file */
182 if (read(fd, buf + num_bytes - 1, 1) < 0)
183 return ERROR_XSVF_EOF;
189 COMMAND_HANDLER(handle_xsvf_command)
191 uint8_t *dr_out_buf = NULL; /* from host to device (TDI) */
192 uint8_t *dr_in_buf = NULL; /* from device to host (TDO) */
193 uint8_t *dr_in_mask = NULL;
196 int xruntest = 0; /* number of TCK cycles OR *microseconds */
197 int xrepeat = 0; /* number of retries */
199 tap_state_t xendir = TAP_IDLE; /* see page 8 of the SVF spec, initial
200 *xendir to be TAP_IDLE */
201 tap_state_t xenddr = TAP_IDLE;
205 long file_offset = 0;
208 tap_state_t loop_state = TAP_IDLE;
214 int tdo_mismatch = 0;
218 bool collecting_path = false;
219 tap_state_t path[XSTATE_MAX_PATH];
220 unsigned pathlen = 0;
222 /* a flag telling whether to clock TCK during waits,
223 * or simply sleep, controlled by virt2
225 int runtest_requires_tck = 0;
227 /* use NULL to indicate a "plain" xsvf file which accounts for
228 * additional devices in the scan chain, otherwise the device
229 * that should be affected
231 struct jtag_tap *tap = NULL;
234 return ERROR_COMMAND_SYNTAX_ERROR;
236 /* we mess with CMD_ARGV starting point below, snapshot filename here */
237 const char *filename = CMD_ARGV[1];
239 if (strcmp(CMD_ARGV[0], "plain") != 0) {
240 tap = jtag_tap_by_string(CMD_ARGV[0]);
242 command_print(CMD, "Tap: %s unknown", CMD_ARGV[0]);
247 xsvf_fd = open(filename, O_RDONLY);
249 command_print(CMD, "file \"%s\" not found", filename);
253 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as
255 if ((CMD_ARGC > 2) && (strcmp(CMD_ARGV[2], "virt2") == 0)) {
256 runtest_requires_tck = 1;
261 if ((CMD_ARGC > 2) && (strcmp(CMD_ARGV[2], "quiet") == 0))
264 LOG_WARNING("XSVF support in OpenOCD is limited. Consider using SVF instead");
265 LOG_USER("xsvf processing file: \"%s\"", filename);
267 while (read(xsvf_fd, &opcode, 1) > 0) {
268 /* record the position of this opcode within the file */
269 file_offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
271 /* maybe collect another state for a pathmove();
272 * or terminate a path.
274 if (collecting_path) {
279 /* ignore/show comments between XSTATE ops */
282 /* try to collect another transition */
283 if (pathlen == XSTATE_MAX_PATH) {
284 LOG_ERROR("XSVF: path too long");
289 if (read(xsvf_fd, &uc, 1) < 0) {
294 mystate = xsvf_to_tap(uc);
295 path[pathlen++] = mystate;
297 LOG_DEBUG("XSTATE 0x%02X %s", uc,
298 tap_state_name(mystate));
300 /* If path is incomplete, collect more */
301 if (!svf_tap_state_is_stable(mystate))
304 /* Else execute the path transitions we've
307 * NOTE: Punting on the saved path is not
308 * strictly correct, but we must to do this
309 * unless jtag_add_pathmove() stops rejecting
310 * paths containing RESET. This is probably
311 * harmless, since there aren't many options
312 * for going from a stable state to reset;
313 * at the worst, we may issue extra clocks
314 * once we get to RESET.
316 if (mystate == TAP_RESET) {
317 LOG_WARNING("XSVF: dodgey RESET");
323 /* Execute the path we collected
325 * NOTE: OpenOCD requires something that XSVF
326 * doesn't: the last TAP state in the path
327 * must be stable. In practice, tools that
328 * create XSVF seem to follow that rule too.
330 collecting_path = false;
332 if (path[0] == TAP_RESET)
335 jtag_add_pathmove(pathlen, path);
337 result = jtag_execute_queue();
338 if (result != ERROR_OK) {
339 LOG_ERROR("XSVF: pathmove error %d", result);
349 LOG_DEBUG("XCOMPLETE");
351 result = jtag_execute_queue();
352 if (result != ERROR_OK) {
359 LOG_DEBUG("XTDOMASK");
361 (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_mask) != ERROR_OK))
367 uint8_t xruntest_buf[4];
369 if (read(xsvf_fd, xruntest_buf, 4) < 0) {
374 xruntest = be_to_h_u32(xruntest_buf);
375 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest, xruntest);
383 if (read(xsvf_fd, &myrepeat, 1) < 0)
387 LOG_DEBUG("XREPEAT %d", xrepeat);
394 uint8_t xsdrsize_buf[4];
396 if (read(xsvf_fd, xsdrsize_buf, 4) < 0) {
401 xsdrsize = be_to_h_u32(xsdrsize_buf);
402 LOG_DEBUG("XSDRSIZE %d", xsdrsize);
408 dr_out_buf = malloc((xsdrsize + 7) / 8);
409 dr_in_buf = malloc((xsdrsize + 7) / 8);
410 dr_in_mask = malloc((xsdrsize + 7) / 8);
414 case XSDR: /* these two are identical except for the dr_in_buf */
421 const char *op_name = (opcode == XSDR ? "XSDR" : "XSDRTDO");
423 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK) {
428 if (opcode == XSDRTDO) {
429 if (xsvf_read_buffer(xsdrsize, xsvf_fd,
430 dr_in_buf) != ERROR_OK) {
439 LOG_DEBUG("%s %d", op_name, xsdrsize);
441 for (attempt = 0; attempt < limit; ++attempt) {
442 struct scan_field field;
445 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
446 * illustrated in pseudo code at end of this file. We start from state
452 * go to Run-Test/Idle
454 * This sequence should be harmless for other devices, and it
455 * will be skipped entirely if xrepeat is set to zero.
458 static tap_state_t exception_path[] = {
466 jtag_add_pathmove(ARRAY_SIZE(exception_path), exception_path);
469 LOG_USER("%s mismatch, xsdrsize=%d retry=%d",
475 field.num_bits = xsdrsize;
476 field.out_value = dr_out_buf;
477 field.in_value = calloc(DIV_ROUND_UP(field.num_bits, 8), 1);
480 jtag_add_plain_dr_scan(field.num_bits,
485 jtag_add_dr_scan(tap, 1, &field, TAP_DRPAUSE);
487 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
489 free(field.in_value);
491 /* LOG_DEBUG("FLUSHING QUEUE"); */
492 result = jtag_execute_queue();
493 if (result == ERROR_OK) {
500 LOG_USER("%s mismatch", op_name);
505 /* See page 19 of XSVF spec regarding opcode "XSDR" */
507 result = svf_add_statemove(TAP_IDLE);
508 if (result != ERROR_OK)
511 if (runtest_requires_tck)
512 jtag_add_clocks(xruntest);
514 jtag_add_sleep(xruntest);
515 } else if (xendir != TAP_DRPAUSE) {
516 /* we are already in TAP_DRPAUSE */
517 result = svf_add_statemove(xenddr);
518 if (result != ERROR_OK)
525 LOG_ERROR("unsupported XSETSDRMASKS");
530 LOG_ERROR("unsupported XSDRINC");
535 LOG_ERROR("unsupported XSDRB");
540 LOG_ERROR("unsupported XSDRC");
545 LOG_ERROR("unsupported XSDRE");
550 LOG_ERROR("unsupported XSDRTDOB");
555 LOG_ERROR("unsupported XSDRTDOC");
560 LOG_ERROR("unsupported XSDRTDOE");
568 if (read(xsvf_fd, &uc, 1) < 0) {
573 mystate = xsvf_to_tap(uc);
575 LOG_DEBUG("XSTATE 0x%02X %s", uc, tap_state_name(mystate));
577 if (mystate == TAP_INVALID) {
578 LOG_ERROR("XSVF: bad XSTATE %02x", uc);
583 /* NOTE: the current state is SVF-stable! */
585 /* no change == NOP */
586 if (mystate == cmd_queue_cur_state
587 && mystate != TAP_RESET)
590 /* Hand off to SVF? */
591 if (svf_tap_state_is_stable(mystate)) {
592 result = svf_add_statemove(mystate);
593 if (result != ERROR_OK)
599 * A sequence of XSTATE transitions, each TAP
600 * state adjacent to the previous one. Start
603 collecting_path = true;
611 if (read(xsvf_fd, &uc, 1) < 0) {
616 /* see page 22 of XSVF spec */
620 xendir = TAP_IRPAUSE;
622 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc);
627 LOG_DEBUG("XENDIR 0x%02X %s", uc, tap_state_name(xendir));
632 if (read(xsvf_fd, &uc, 1) < 0) {
637 /* see page 22 of XSVF spec */
641 xenddr = TAP_DRPAUSE;
643 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc);
648 LOG_DEBUG("XENDDR %02X %s", uc, tap_state_name(xenddr));
654 uint8_t short_buf[2];
657 tap_state_t my_end_state = xruntest ? TAP_IDLE : xendir;
659 if (opcode == XSIR) {
660 /* one byte bitcount */
661 if (read(xsvf_fd, short_buf, 1) < 0) {
665 bitcount = short_buf[0];
666 LOG_DEBUG("XSIR %d", bitcount);
668 if (read(xsvf_fd, short_buf, 2) < 0) {
672 bitcount = be_to_h_u16(short_buf);
673 LOG_DEBUG("XSIR2 %d", bitcount);
676 ir_buf = malloc((bitcount + 7) / 8);
678 if (xsvf_read_buffer(bitcount, xsvf_fd, ir_buf) != ERROR_OK)
681 struct scan_field field;
683 field.num_bits = bitcount;
684 field.out_value = ir_buf;
686 field.in_value = NULL;
689 jtag_add_plain_ir_scan(field.num_bits,
690 field.out_value, field.in_value, my_end_state);
692 jtag_add_ir_scan(tap, &field, my_end_state);
695 if (runtest_requires_tck)
696 jtag_add_clocks(xruntest);
698 jtag_add_sleep(xruntest);
701 /* Note that an -irmask of non-zero in your config file
702 * can cause this to fail. Setting -irmask to zero cand work
703 * around the problem.
706 /* LOG_DEBUG("FLUSHING QUEUE"); */
707 result = jtag_execute_queue();
708 if (result != ERROR_OK)
717 unsigned int ndx = 0;
721 if (read(xsvf_fd, &uc, 1) < 0) {
726 if (ndx < sizeof(comment)-1)
731 comment[sizeof(comment)-1] = 0; /* regardless, terminate */
733 LOG_USER("# %s", comment);
739 /* expected in stream:
740 XWAIT <uint8_t wait_state> <uint8_t end_state> <uint32_t usecs>
745 uint8_t delay_buf[4];
747 tap_state_t wait_state;
748 tap_state_t end_state;
751 if (read(xsvf_fd, &wait_local, 1) < 0
752 || read(xsvf_fd, &end, 1) < 0
753 || read(xsvf_fd, delay_buf, 4) < 0) {
758 wait_state = xsvf_to_tap(wait_local);
759 end_state = xsvf_to_tap(end);
760 delay = be_to_h_u32(delay_buf);
762 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(
763 wait_state), tap_state_name(end_state), delay);
765 if (runtest_requires_tck && wait_state == TAP_IDLE)
766 jtag_add_runtest(delay, end_state);
768 /* FIXME handle statemove errors ... */
769 result = svf_add_statemove(wait_state);
770 if (result != ERROR_OK)
772 jtag_add_sleep(delay);
773 result = svf_add_statemove(end_state);
774 if (result != ERROR_OK)
782 /* expected in stream:
783 * XWAITSTATE <uint8_t wait_state> <uint8_t end_state> <uint32_t clock_count>
787 uint8_t clock_buf[4];
788 uint8_t usecs_buf[4];
791 tap_state_t wait_state;
792 tap_state_t end_state;
796 if (read(xsvf_fd, &wait_local, 1) < 0
797 || read(xsvf_fd, &end, 1) < 0
798 || read(xsvf_fd, clock_buf, 4) < 0
799 || read(xsvf_fd, usecs_buf, 4) < 0) {
804 wait_state = xsvf_to_tap(wait_local);
805 end_state = xsvf_to_tap(end);
807 clock_count = be_to_h_u32(clock_buf);
808 usecs = be_to_h_u32(usecs_buf);
810 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
811 tap_state_name(wait_state),
812 tap_state_name(end_state),
815 /* the following states are 'stable', meaning that they have a transition
816 * in the state diagram back to themselves. This is necessary because we will
817 * be issuing a number of clocks in this state. This set of allowed states is also
818 * determined by the SVF RUNTEST command's allowed states.
820 if (!svf_tap_state_is_stable(wait_state)) {
821 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"",
822 tap_state_name(wait_state));
824 /* REVISIT "break" so we won't run? */
827 /* FIXME handle statemove errors ... */
828 result = svf_add_statemove(wait_state);
829 if (result != ERROR_OK)
832 jtag_add_clocks(clock_count);
833 jtag_add_sleep(usecs);
835 result = svf_add_statemove(end_state);
836 if (result != ERROR_OK)
843 /* expected in stream:
844 * LCOUNT <uint32_t loop_count>
846 uint8_t count_buf[4];
848 if (read(xsvf_fd, count_buf, 4) < 0) {
853 loop_count = be_to_h_u32(count_buf);
854 LOG_DEBUG("LCOUNT %d", loop_count);
860 /* expected in stream:
861 * LDELAY <uint8_t wait_state> <uint32_t clock_count> <uint32_t usecs_to_sleep>
864 uint8_t clock_buf[4];
865 uint8_t usecs_buf[4];
867 if (read(xsvf_fd, &state, 1) < 0
868 || read(xsvf_fd, clock_buf, 4) < 0
869 || read(xsvf_fd, usecs_buf, 4) < 0) {
874 /* NOTE: loop_state must be stable! */
875 loop_state = xsvf_to_tap(state);
876 loop_clocks = be_to_h_u32(clock_buf);
877 loop_usecs = be_to_h_u32(usecs_buf);
879 LOG_DEBUG("LDELAY %s clocks:%d usecs:%d", tap_state_name(
880 loop_state), loop_clocks, loop_usecs);
884 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
885 * comes with clocks !AND! sleep requirements.
889 int limit = loop_count;
895 if (xsvf_read_buffer(xsdrsize, xsvf_fd, dr_out_buf) != ERROR_OK
896 || xsvf_read_buffer(xsdrsize, xsvf_fd, dr_in_buf) != ERROR_OK) {
904 for (attempt = 0; attempt < limit; ++attempt) {
905 struct scan_field field;
907 result = svf_add_statemove(loop_state);
908 if (result != ERROR_OK) {
912 jtag_add_clocks(loop_clocks);
913 jtag_add_sleep(loop_usecs);
915 field.num_bits = xsdrsize;
916 field.out_value = dr_out_buf;
917 field.in_value = calloc(DIV_ROUND_UP(field.num_bits, 8), 1);
919 if (attempt > 0 && verbose)
920 LOG_USER("LSDR retry %d", attempt);
923 jtag_add_plain_dr_scan(field.num_bits,
928 jtag_add_dr_scan(tap, 1, &field, TAP_DRPAUSE);
930 jtag_check_value_mask(&field, dr_in_buf, dr_in_mask);
932 free(field.in_value);
935 /* LOG_DEBUG("FLUSHING QUEUE"); */
936 result = jtag_execute_queue();
937 if (result == ERROR_OK) {
944 LOG_USER("LSDR mismatch");
955 if (read(xsvf_fd, &trst_mode, 1) < 0) {
962 jtag_add_reset(1, 0);
966 jtag_add_reset(0, 0);
971 LOG_ERROR("XTRST mode argument (0x%02X) out of range", trst_mode);
978 LOG_ERROR("unknown xsvf command (0x%02X)", uc);
982 if (do_abort || unsupported || tdo_mismatch) {
983 LOG_DEBUG("xsvf failed, setting taps to reasonable state");
985 /* upon error, return the TAPs to a reasonable state */
986 result = svf_add_statemove(TAP_IDLE);
987 if (result != ERROR_OK)
989 result = jtag_execute_queue();
990 if (result != ERROR_OK)
998 "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
1005 off_t offset = lseek(xsvf_fd, 0, SEEK_CUR) - 1;
1007 "unsupported xsvf command (0x%02X) at offset %jd, aborting",
1008 uc, (intmax_t)offset);
1013 command_print(CMD, "premature end of xsvf file detected, aborting");
1023 command_print(CMD, "XSVF file programmed successfully");
1028 static const struct command_registration xsvf_command_handlers[] = {
1031 .handler = handle_xsvf_command,
1032 .mode = COMMAND_EXEC,
1033 .help = "Runs a XSVF file. If 'virt2' is given, xruntest "
1034 "counts are interpreted as TCK cycles rather than "
1035 "as microseconds. Without the 'quiet' option, all "
1036 "comments, retries, and mismatches will be reported.",
1037 .usage = "(tapname|'plain') filename ['virt2'] ['quiet']",
1039 COMMAND_REGISTRATION_DONE
1042 int xsvf_register_commands(struct command_context *cmd_ctx)
1044 return register_commands(cmd_ctx, NULL, xsvf_command_handlers);
1049 PSEUDO-Code from Xilinx Appnote XAPP067.pdf :
1051 the following pseudo code clarifies the intent of the xrepeat support.The
1052 flow given is for the entire processing of an SVF file, not an XSVF file.
1053 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1055 "Pseudo-Code Algorithm for SVF-Based ISP"
1057 1. Go to Test-Logic-Reset state
1058 2. Go to Run-Test Idle state
1061 4. if SIR record then
1062 go to Shift-IR state
1065 5. else if SDR record then
1066 set <repeat count> to 0
1067 store <TDI value> as <current TDI value>
1068 store <TDO value> as <current TDO value>
1069 6. go to Shift-DR state
1070 scan in <current TDI value>
1071 if < current TDO value > is specified then
1072 if < current TDO value > does not equal <actual TDO value> then
1073 if < repeat count > > 32 then
1075 go to Run-Test Idle state
1084 increment <repeat count> by 1
1085 pause <current pause time> microseconds
1089 go to Run-Test Idle state
1092 else if RUNTEST record then
1093 pause tester for < TCK value > microseconds
1094 store <TCK value> as <current pause time>