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 refered 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 refered to as the "XSVF spec".
42 #include <jtag/jtag.h>
45 /* XSVF commands, from appendix B of xapp503.pdf */
46 #define XCOMPLETE 0x00
54 #define XSETSDRMASKS 0x0A
69 /* XWAITSTATE is not in the xilinx XSVF spec, but the svf2xsvf.py translator
70 * generates this. Arguably it is needed because the XSVF XRUNTEST command
71 * was ill conceived and does not directly flow out of the SVF RUNTEST command.
72 * This XWAITSTATE does map directly from the SVF RUNTEST command.
74 #define XWAITSTATE 0x18
76 /* Lattice has extended the SVF file format, and Dick Hollenbeck's python based
77 * SVF2XSVF converter supports these 3 additional XSVF opcodes, LCOUNT, LDELAY, LSDR.
78 * Here is an example of usage of the 3 lattice opcode extensions:
80 ! Set the maximum loop count to 25.
82 ! Step to DRPAUSE give 5 clocks and wait for 1.00e + 000 SEC.
83 LDELAY DRPAUSE 5 TCK 1.00E-003 SEC;
84 ! Test for the completed status. Match means pass.
85 ! Loop back to LDELAY line if not match and loop count less than 25.
96 /* XSVF valid state values for the XSTATE command, from appendix B of xapp503.pdf */
97 #define XSV_RESET 0x00
99 #define XSV_DRSELECT 0x02
100 #define XSV_DRCAPTURE 0x03
101 #define XSV_DRSHIFT 0x04
102 #define XSV_DREXIT1 0x05
103 #define XSV_DRPAUSE 0x06
104 #define XSV_DREXIT2 0x07
105 #define XSV_DRUPDATE 0x08
106 #define XSV_IRSELECT 0x09
107 #define XSV_IRCAPTURE 0x0A
108 #define XSV_IRSHIFT 0x0B
109 #define XSV_IREXIT1 0x0C
110 #define XSV_IRPAUSE 0x0D
111 #define XSV_IREXIT2 0x0E
112 #define XSV_IRUPDATE 0x0F
114 /* arguments to XTRST */
118 #define XTRST_ABSENT 3
120 #define XSTATE_MAX_PATH 12
124 /* map xsvf tap state to an openocd "tap_state_t" */
125 static tap_state_t
xsvf_to_tap(int xsvf_state
)
129 switch (xsvf_state
) {
179 LOG_ERROR("UNKNOWN XSVF STATE 0x%02X", xsvf_state
);
186 static int xsvf_read_buffer(int num_bits
, int fd
, uint8_t *buf
)
190 for (num_bytes
= (num_bits
+ 7) / 8; num_bytes
> 0; num_bytes
--) {
191 /* reverse the order of bytes as they are read sequentially from file */
192 if (read(fd
, buf
+ num_bytes
- 1, 1) < 0)
193 return ERROR_XSVF_EOF
;
199 COMMAND_HANDLER(handle_xsvf_command
)
201 uint8_t *dr_out_buf
= NULL
; /* from host to device (TDI) */
202 uint8_t *dr_in_buf
= NULL
; /* from device to host (TDO) */
203 uint8_t *dr_in_mask
= NULL
;
206 int xruntest
= 0; /* number of TCK cycles OR *microseconds */
207 int xrepeat
= 0; /* number of retries */
209 tap_state_t xendir
= TAP_IDLE
; /* see page 8 of the SVF spec, initial
210 *xendir to be TAP_IDLE */
211 tap_state_t xenddr
= TAP_IDLE
;
215 long file_offset
= 0;
218 tap_state_t loop_state
= TAP_IDLE
;
224 int tdo_mismatch
= 0;
228 bool collecting_path
= false;
229 tap_state_t path
[XSTATE_MAX_PATH
];
230 unsigned pathlen
= 0;
232 /* a flag telling whether to clock TCK during waits,
233 * or simply sleep, controled by virt2
235 int runtest_requires_tck
= 0;
237 /* use NULL to indicate a "plain" xsvf file which accounts for
238 * additional devices in the scan chain, otherwise the device
239 * that should be affected
241 struct jtag_tap
*tap
= NULL
;
244 return ERROR_COMMAND_SYNTAX_ERROR
;
246 /* we mess with CMD_ARGV starting point below, snapshot filename here */
247 const char *filename
= CMD_ARGV
[1];
249 if (strcmp(CMD_ARGV
[0], "plain") != 0) {
250 tap
= jtag_tap_by_string(CMD_ARGV
[0]);
252 command_print(CMD_CTX
, "Tap: %s unknown", CMD_ARGV
[0]);
257 xsvf_fd
= open(filename
, O_RDONLY
);
259 command_print(CMD_CTX
, "file \"%s\" not found", filename
);
263 /* if this argument is present, then interpret xruntest counts as TCK cycles rather than as
265 if ((CMD_ARGC
> 2) && (strcmp(CMD_ARGV
[2], "virt2") == 0)) {
266 runtest_requires_tck
= 1;
271 if ((CMD_ARGC
> 2) && (strcmp(CMD_ARGV
[2], "quiet") == 0))
274 LOG_WARNING("XSVF support in OpenOCD is limited. Consider using SVF instead");
275 LOG_USER("xsvf processing file: \"%s\"", filename
);
277 while (read(xsvf_fd
, &opcode
, 1) > 0) {
278 /* record the position of this opcode within the file */
279 file_offset
= lseek(xsvf_fd
, 0, SEEK_CUR
) - 1;
281 /* maybe collect another state for a pathmove();
282 * or terminate a path.
284 if (collecting_path
) {
289 /* ignore/show comments between XSTATE ops */
292 /* try to collect another transition */
293 if (pathlen
== XSTATE_MAX_PATH
) {
294 LOG_ERROR("XSVF: path too long");
299 if (read(xsvf_fd
, &uc
, 1) < 0) {
304 mystate
= xsvf_to_tap(uc
);
305 path
[pathlen
++] = mystate
;
307 LOG_DEBUG("XSTATE 0x%02X %s", uc
,
308 tap_state_name(mystate
));
310 /* If path is incomplete, collect more */
311 if (!svf_tap_state_is_stable(mystate
))
314 /* Else execute the path transitions we've
317 * NOTE: Punting on the saved path is not
318 * strictly correct, but we must to do this
319 * unless jtag_add_pathmove() stops rejecting
320 * paths containing RESET. This is probably
321 * harmless, since there aren't many options
322 * for going from a stable state to reset;
323 * at the worst, we may issue extra clocks
324 * once we get to RESET.
326 if (mystate
== TAP_RESET
) {
327 LOG_WARNING("XSVF: dodgey RESET");
333 /* Execute the path we collected
335 * NOTE: OpenOCD requires something that XSVF
336 * doesn't: the last TAP state in the path
337 * must be stable. In practice, tools that
338 * create XSVF seem to follow that rule too.
340 collecting_path
= false;
342 if (path
[0] == TAP_RESET
)
345 jtag_add_pathmove(pathlen
, path
);
347 result
= jtag_execute_queue();
348 if (result
!= ERROR_OK
) {
349 LOG_ERROR("XSVF: pathmove error %d", result
);
359 LOG_DEBUG("XCOMPLETE");
361 result
= jtag_execute_queue();
362 if (result
!= ERROR_OK
) {
369 LOG_DEBUG("XTDOMASK");
371 (xsvf_read_buffer(xsdrsize
, xsvf_fd
, dr_in_mask
) != ERROR_OK
))
377 uint8_t xruntest_buf
[4];
379 if (read(xsvf_fd
, xruntest_buf
, 4) < 0) {
384 xruntest
= be_to_h_u32(xruntest_buf
);
385 LOG_DEBUG("XRUNTEST %d 0x%08X", xruntest
, xruntest
);
393 if (read(xsvf_fd
, &myrepeat
, 1) < 0)
397 LOG_DEBUG("XREPEAT %d", xrepeat
);
404 uint8_t xsdrsize_buf
[4];
406 if (read(xsvf_fd
, xsdrsize_buf
, 4) < 0) {
411 xsdrsize
= be_to_h_u32(xsdrsize_buf
);
412 LOG_DEBUG("XSDRSIZE %d", xsdrsize
);
421 dr_out_buf
= malloc((xsdrsize
+ 7) / 8);
422 dr_in_buf
= malloc((xsdrsize
+ 7) / 8);
423 dr_in_mask
= malloc((xsdrsize
+ 7) / 8);
427 case XSDR
: /* these two are identical except for the dr_in_buf */
434 const char *op_name
= (opcode
== XSDR
? "XSDR" : "XSDRTDO");
436 if (xsvf_read_buffer(xsdrsize
, xsvf_fd
, dr_out_buf
) != ERROR_OK
) {
441 if (opcode
== XSDRTDO
) {
442 if (xsvf_read_buffer(xsdrsize
, xsvf_fd
,
443 dr_in_buf
) != ERROR_OK
) {
452 LOG_DEBUG("%s %d", op_name
, xsdrsize
);
454 for (attempt
= 0; attempt
< limit
; ++attempt
) {
455 struct scan_field field
;
458 /* perform the XC9500 exception handling sequence shown in xapp067.pdf and
459 * illustrated in psuedo code at end of this file. We start from state
465 * go to Run-Test/Idle
467 * This sequence should be harmless for other devices, and it
468 * will be skipped entirely if xrepeat is set to zero.
471 static tap_state_t exception_path
[] = {
479 jtag_add_pathmove(ARRAY_SIZE(exception_path
), exception_path
);
482 LOG_USER("%s mismatch, xsdrsize=%d retry=%d",
488 field
.num_bits
= xsdrsize
;
489 field
.out_value
= dr_out_buf
;
490 field
.in_value
= calloc(DIV_ROUND_UP(field
.num_bits
, 8), 1);
493 jtag_add_plain_dr_scan(field
.num_bits
,
498 jtag_add_dr_scan(tap
, 1, &field
, TAP_DRPAUSE
);
500 jtag_check_value_mask(&field
, dr_in_buf
, dr_in_mask
);
502 free(field
.in_value
);
504 /* LOG_DEBUG("FLUSHING QUEUE"); */
505 result
= jtag_execute_queue();
506 if (result
== ERROR_OK
) {
513 LOG_USER("%s mismatch", op_name
);
518 /* See page 19 of XSVF spec regarding opcode "XSDR" */
520 result
= svf_add_statemove(TAP_IDLE
);
521 if (result
!= ERROR_OK
)
524 if (runtest_requires_tck
)
525 jtag_add_clocks(xruntest
);
527 jtag_add_sleep(xruntest
);
528 } else if (xendir
!= TAP_DRPAUSE
) {
529 /* we are already in TAP_DRPAUSE */
530 result
= svf_add_statemove(xenddr
);
531 if (result
!= ERROR_OK
)
538 LOG_ERROR("unsupported XSETSDRMASKS");
543 LOG_ERROR("unsupported XSDRINC");
548 LOG_ERROR("unsupported XSDRB");
553 LOG_ERROR("unsupported XSDRC");
558 LOG_ERROR("unsupported XSDRE");
563 LOG_ERROR("unsupported XSDRTDOB");
568 LOG_ERROR("unsupported XSDRTDOC");
573 LOG_ERROR("unsupported XSDRTDOE");
581 if (read(xsvf_fd
, &uc
, 1) < 0) {
586 mystate
= xsvf_to_tap(uc
);
588 LOG_DEBUG("XSTATE 0x%02X %s", uc
, tap_state_name(mystate
));
590 if (mystate
== TAP_INVALID
) {
591 LOG_ERROR("XSVF: bad XSTATE %02x", uc
);
596 /* NOTE: the current state is SVF-stable! */
598 /* no change == NOP */
599 if (mystate
== cmd_queue_cur_state
600 && mystate
!= TAP_RESET
)
603 /* Hand off to SVF? */
604 if (svf_tap_state_is_stable(mystate
)) {
605 result
= svf_add_statemove(mystate
);
606 if (result
!= ERROR_OK
)
612 * A sequence of XSTATE transitions, each TAP
613 * state adjacent to the previous one. Start
616 collecting_path
= true;
624 if (read(xsvf_fd
, &uc
, 1) < 0) {
629 /* see page 22 of XSVF spec */
633 xendir
= TAP_IRPAUSE
;
635 LOG_ERROR("illegial XENDIR argument: 0x%02X", uc
);
640 LOG_DEBUG("XENDIR 0x%02X %s", uc
, tap_state_name(xendir
));
645 if (read(xsvf_fd
, &uc
, 1) < 0) {
650 /* see page 22 of XSVF spec */
654 xenddr
= TAP_DRPAUSE
;
656 LOG_ERROR("illegial XENDDR argument: 0x%02X", uc
);
661 LOG_DEBUG("XENDDR %02X %s", uc
, tap_state_name(xenddr
));
667 uint8_t short_buf
[2];
670 tap_state_t my_end_state
= xruntest
? TAP_IDLE
: xendir
;
672 if (opcode
== XSIR
) {
673 /* one byte bitcount */
674 if (read(xsvf_fd
, short_buf
, 1) < 0) {
678 bitcount
= short_buf
[0];
679 LOG_DEBUG("XSIR %d", bitcount
);
681 if (read(xsvf_fd
, short_buf
, 2) < 0) {
685 bitcount
= be_to_h_u16(short_buf
);
686 LOG_DEBUG("XSIR2 %d", bitcount
);
689 ir_buf
= malloc((bitcount
+ 7) / 8);
691 if (xsvf_read_buffer(bitcount
, xsvf_fd
, ir_buf
) != ERROR_OK
)
694 struct scan_field field
;
696 field
.num_bits
= bitcount
;
697 field
.out_value
= ir_buf
;
699 field
.in_value
= NULL
;
702 jtag_add_plain_ir_scan(field
.num_bits
,
703 field
.out_value
, field
.in_value
, my_end_state
);
705 jtag_add_ir_scan(tap
, &field
, my_end_state
);
708 if (runtest_requires_tck
)
709 jtag_add_clocks(xruntest
);
711 jtag_add_sleep(xruntest
);
714 /* Note that an -irmask of non-zero in your config file
715 * can cause this to fail. Setting -irmask to zero cand work
716 * around the problem.
719 /* LOG_DEBUG("FLUSHING QUEUE"); */
720 result
= jtag_execute_queue();
721 if (result
!= ERROR_OK
)
730 unsigned int ndx
= 0;
734 if (read(xsvf_fd
, &uc
, 1) < 0) {
739 if (ndx
< sizeof(comment
)-1)
744 comment
[sizeof(comment
)-1] = 0; /* regardless, terminate */
746 LOG_USER("# %s", comment
);
752 /* expected in stream:
753 XWAIT <uint8_t wait_state> <uint8_t end_state> <uint32_t usecs>
758 uint8_t delay_buf
[4];
760 tap_state_t wait_state
;
761 tap_state_t end_state
;
764 if (read(xsvf_fd
, &wait_local
, 1) < 0
765 || read(xsvf_fd
, &end
, 1) < 0
766 || read(xsvf_fd
, delay_buf
, 4) < 0) {
771 wait_state
= xsvf_to_tap(wait_local
);
772 end_state
= xsvf_to_tap(end
);
773 delay
= be_to_h_u32(delay_buf
);
775 LOG_DEBUG("XWAIT %s %s usecs:%d", tap_state_name(
776 wait_state
), tap_state_name(end_state
), delay
);
778 if (runtest_requires_tck
&& wait_state
== TAP_IDLE
)
779 jtag_add_runtest(delay
, end_state
);
781 /* FIXME handle statemove errors ... */
782 result
= svf_add_statemove(wait_state
);
783 if (result
!= ERROR_OK
)
785 jtag_add_sleep(delay
);
786 result
= svf_add_statemove(end_state
);
787 if (result
!= ERROR_OK
)
795 /* expected in stream:
796 * XWAITSTATE <uint8_t wait_state> <uint8_t end_state> <uint32_t clock_count>
800 uint8_t clock_buf
[4];
801 uint8_t usecs_buf
[4];
804 tap_state_t wait_state
;
805 tap_state_t end_state
;
809 if (read(xsvf_fd
, &wait_local
, 1) < 0
810 || read(xsvf_fd
, &end
, 1) < 0
811 || read(xsvf_fd
, clock_buf
, 4) < 0
812 || read(xsvf_fd
, usecs_buf
, 4) < 0) {
817 wait_state
= xsvf_to_tap(wait_local
);
818 end_state
= xsvf_to_tap(end
);
820 clock_count
= be_to_h_u32(clock_buf
);
821 usecs
= be_to_h_u32(usecs_buf
);
823 LOG_DEBUG("XWAITSTATE %s %s clocks:%i usecs:%i",
824 tap_state_name(wait_state
),
825 tap_state_name(end_state
),
828 /* the following states are 'stable', meaning that they have a transition
829 * in the state diagram back to themselves. This is necessary because we will
830 * be issuing a number of clocks in this state. This set of allowed states is also
831 * determined by the SVF RUNTEST command's allowed states.
833 if (!svf_tap_state_is_stable(wait_state
)) {
834 LOG_ERROR("illegal XWAITSTATE wait_state: \"%s\"",
835 tap_state_name(wait_state
));
837 /* REVISIT "break" so we won't run? */
840 /* FIXME handle statemove errors ... */
841 result
= svf_add_statemove(wait_state
);
842 if (result
!= ERROR_OK
)
845 jtag_add_clocks(clock_count
);
846 jtag_add_sleep(usecs
);
848 result
= svf_add_statemove(end_state
);
849 if (result
!= ERROR_OK
)
856 /* expected in stream:
857 * LCOUNT <uint32_t loop_count>
859 uint8_t count_buf
[4];
861 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 <uint8_t wait_state> <uint32_t clock_count> <uint32_t usecs_to_sleep>
877 uint8_t clock_buf
[4];
878 uint8_t usecs_buf
[4];
880 if (read(xsvf_fd
, &state
, 1) < 0
881 || read(xsvf_fd
, clock_buf
, 4) < 0
882 || read(xsvf_fd
, usecs_buf
, 4) < 0) {
887 /* NOTE: loop_state must be stable! */
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", tap_state_name(
893 loop_state
), loop_clocks
, loop_usecs
);
897 /* LSDR is more like XSDRTDO than it is like XSDR. It uses LDELAY which
898 * comes with clocks !AND! sleep requirements.
902 int limit
= loop_count
;
908 if (xsvf_read_buffer(xsdrsize
, xsvf_fd
, dr_out_buf
) != ERROR_OK
909 || xsvf_read_buffer(xsdrsize
, xsvf_fd
, dr_in_buf
) != ERROR_OK
) {
917 for (attempt
= 0; attempt
< limit
; ++attempt
) {
918 struct scan_field field
;
920 result
= svf_add_statemove(loop_state
);
921 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
)
1008 command_print(CMD_CTX
,
1009 "TDO mismatch, somewhere near offset %lu in xsvf file, aborting",
1016 off_t offset
= lseek(xsvf_fd
, 0, SEEK_CUR
) - 1;
1017 command_print(CMD_CTX
,
1018 "unsupported xsvf command (0x%02X) at offset %jd, aborting",
1019 uc
, (intmax_t)offset
);
1024 command_print(CMD_CTX
, "premature end of xsvf file detected, aborting");
1039 command_print(CMD_CTX
, "XSVF file programmed successfully");
1044 static const struct command_registration xsvf_command_handlers
[] = {
1047 .handler
= handle_xsvf_command
,
1048 .mode
= COMMAND_EXEC
,
1049 .help
= "Runs a XSVF file. If 'virt2' is given, xruntest "
1050 "counts are interpreted as TCK cycles rather than "
1051 "as microseconds. Without the 'quiet' option, all "
1052 "comments, retries, and mismatches will be reported.",
1053 .usage
= "(tapname|'plain') filename ['virt2'] ['quiet']",
1055 COMMAND_REGISTRATION_DONE
1058 int xsvf_register_commands(struct command_context
*cmd_ctx
)
1060 return register_commands(cmd_ctx
, NULL
, xsvf_command_handlers
);
1065 PSUEDO-Code from Xilinx Appnote XAPP067.pdf :
1067 the following pseudo code clarifies the intent of the xrepeat support.The
1068 flow given is for the entire processing of an SVF file, not an XSVF file.
1069 No idea if this is just for the XC9500/XL/XV devices or all Xilinx parts.
1071 "Pseudo-Code Algorithm for SVF-Based ISP"
1073 1. Go to Test-Logic-Reset state
1074 2. Go to Run-Test Idle state
1077 4. if SIR record then
1078 go to Shift-IR state
1081 5. else if SDR record then
1082 set <repeat count> to 0
1083 store <TDI value> as <current TDI value>
1084 store <TDO value> as <current TDO value>
1085 6. go to Shift-DR state
1086 scan in <current TDI value>
1087 if < current TDO value > is specified then
1088 if < current TDO value > does not equal <actual TDO value> then
1089 if < repeat count > > 32 then
1091 go to Run-Test Idle state
1100 increment <repeat count> by 1
1101 pause <current pause time> microseconds
1105 go to Run-Test Idle state
1108 else if RUNTEST record then
1109 pause tester for < TCK value > microseconds
1110 store <TCK value> as <current pause time>