1 /***************************************************************************
2 * Copyright (C) 2004, 2006 by Dominic Rath *
3 * Dominic.Rath@gmx.de *
5 * Copyright (C) 2008 by Spencer Oliver *
6 * spen@spen-soft.co.uk *
8 * Copyright (C) 2009 by SoftPLC Corporation. http://softplc.com *
9 * Dick Hollenbeck <dick@softplc.com> *
11 * This program is free software; you can redistribute it and/or modify *
12 * it under the terms of the GNU General Public License as published by *
13 * the Free Software Foundation; either version 2 of the License, or *
14 * (at your option) any later version. *
16 * This program is distributed in the hope that it will be useful, *
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
19 * GNU General Public License for more details. *
21 * You should have received a copy of the GNU General Public License *
22 * along with this program; if not, write to the *
23 * Free Software Foundation, Inc., *
24 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
25 ***************************************************************************/
27 /* This code uses information contained in the MPSSE specification which was
29 * http://www.ftdichip.com/Documents/AppNotes/AN2232C-01_MPSSE_Cmnd.pdf
30 * Hereafter this is called the "MPSSE Spec".
32 * The datasheet for the ftdichip.com's FT2232D part is here:
33 * http://www.ftdichip.com/Documents/DataSheets/DS_FT2232D.pdf
40 /* project specific includes */
41 #include "interface.h"
43 #include "time_support.h"
51 #if (BUILD_FT2232_FTD2XX == 1 && BUILD_FT2232_LIBFTDI == 1)
52 #error "BUILD_FT2232_FTD2XX && BUILD_FT2232_LIBFTDI are mutually exclusive"
53 #elif (BUILD_FT2232_FTD2XX != 1 && BUILD_FT2232_LIBFTDI != 1)
54 #error "BUILD_FT2232_FTD2XX || BUILD_FT2232_LIBFTDI must be chosen"
57 /* FT2232 access library includes */
58 #if BUILD_FT2232_FTD2XX == 1
60 #elif BUILD_FT2232_LIBFTDI == 1
64 /* max TCK for the high speed devices 30000 kHz */
65 #define FTDI_2232H_4232H_MAX_TCK 30000
66 /* max TCK for the full speed devices 6000 kHz */
67 #define FTDI_2232C_MAX_TCK 6000
68 /* this speed value tells that RTCK is requested */
71 #ifndef BUILD_FT2232_HIGHSPEED
72 #if BUILD_FT2232_FTD2XX == 1
73 enum { FT_DEVICE_2232H
= 6, FT_DEVICE_4232H
};
74 #elif BUILD_FT2232_LIBFTDI == 1
75 enum { TYPE_2232H
= 4, TYPE_4232H
= 5 };
79 static int ft2232_execute_queue(void);
80 static int ft2232_speed(int speed
);
81 static int ft2232_speed_div(int speed
, int* khz
);
82 static int ft2232_khz(int khz
, int* jtag_speed
);
83 static int ft2232_register_commands(struct command_context_s
* cmd_ctx
);
84 static int ft2232_init(void);
85 static int ft2232_quit(void);
87 static int ft2232_handle_device_desc_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
);
88 static int ft2232_handle_serial_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
);
89 static int ft2232_handle_layout_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
);
90 static int ft2232_handle_vid_pid_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
);
91 static int ft2232_handle_latency_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
);
94 * Send out \a num_cycles on the TCK line while the TAP(s) are in a
95 * stable state. Calling code must ensure that current state is stable,
96 * that verification is not done in here.
98 * @param num_cycles The number of clocks cycles to send.
99 * @param cmd The command to send.
101 * @returns ERROR_OK on success, or ERROR_JTAG_QUEUE_FAILED on failure.
103 static int ft2232_stableclocks(int num_cycles
, jtag_command_t
* cmd
);
105 static char * ft2232_device_desc_A
= NULL
;
106 static char* ft2232_device_desc
= NULL
;
107 static char* ft2232_serial
= NULL
;
108 static char* ft2232_layout
= NULL
;
109 static uint8_t ft2232_latency
= 2;
110 static unsigned ft2232_max_tck
= FTDI_2232C_MAX_TCK
;
112 #define MAX_USB_IDS 8
113 /* vid = pid = 0 marks the end of the list */
114 static uint16_t ft2232_vid
[MAX_USB_IDS
+ 1] = { 0x0403, 0 };
115 static uint16_t ft2232_pid
[MAX_USB_IDS
+ 1] = { 0x6010, 0 };
117 typedef struct ft2232_layout_s
121 void (*reset
)(int trst
, int srst
);
125 /* init procedures for supported layouts */
126 static int usbjtag_init(void);
127 static int jtagkey_init(void);
128 static int olimex_jtag_init(void);
129 static int flyswatter_init(void);
130 static int turtle_init(void);
131 static int comstick_init(void);
132 static int stm32stick_init(void);
133 static int axm0432_jtag_init(void);
134 static int sheevaplug_init(void);
135 static int icebear_jtag_init(void);
136 static int cortino_jtag_init(void);
138 /* reset procedures for supported layouts */
139 static void usbjtag_reset(int trst
, int srst
);
140 static void jtagkey_reset(int trst
, int srst
);
141 static void olimex_jtag_reset(int trst
, int srst
);
142 static void flyswatter_reset(int trst
, int srst
);
143 static void turtle_reset(int trst
, int srst
);
144 static void comstick_reset(int trst
, int srst
);
145 static void stm32stick_reset(int trst
, int srst
);
146 static void axm0432_jtag_reset(int trst
, int srst
);
147 static void sheevaplug_reset(int trst
, int srst
);
148 static void icebear_jtag_reset(int trst
, int srst
);
150 /* blink procedures for layouts that support a blinking led */
151 static void olimex_jtag_blink(void);
152 static void flyswatter_jtag_blink(void);
153 static void turtle_jtag_blink(void);
155 static const ft2232_layout_t ft2232_layouts
[] =
157 { "usbjtag", usbjtag_init
, usbjtag_reset
, NULL
},
158 { "jtagkey", jtagkey_init
, jtagkey_reset
, NULL
},
159 { "jtagkey_prototype_v1", jtagkey_init
, jtagkey_reset
, NULL
},
160 { "oocdlink", jtagkey_init
, jtagkey_reset
, NULL
},
161 { "signalyzer", usbjtag_init
, usbjtag_reset
, NULL
},
162 { "evb_lm3s811", usbjtag_init
, usbjtag_reset
, NULL
},
163 { "luminary_icdi", usbjtag_init
, usbjtag_reset
, NULL
},
164 { "olimex-jtag", olimex_jtag_init
, olimex_jtag_reset
, olimex_jtag_blink
},
165 { "flyswatter", flyswatter_init
, flyswatter_reset
, flyswatter_jtag_blink
},
166 { "turtelizer2", turtle_init
, turtle_reset
, turtle_jtag_blink
},
167 { "comstick", comstick_init
, comstick_reset
, NULL
},
168 { "stm32stick", stm32stick_init
, stm32stick_reset
, NULL
},
169 { "axm0432_jtag", axm0432_jtag_init
, axm0432_jtag_reset
, NULL
},
170 { "sheevaplug", sheevaplug_init
, sheevaplug_reset
, NULL
},
171 { "icebear", icebear_jtag_init
, icebear_jtag_reset
, NULL
},
172 { "cortino", cortino_jtag_init
, comstick_reset
, NULL
},
173 { NULL
, NULL
, NULL
, NULL
},
176 static uint8_t nTRST
, nTRSTnOE
, nSRST
, nSRSTnOE
;
178 static const ft2232_layout_t
*layout
;
179 static uint8_t low_output
= 0x0;
180 static uint8_t low_direction
= 0x0;
181 static uint8_t high_output
= 0x0;
182 static uint8_t high_direction
= 0x0;
184 #if BUILD_FT2232_FTD2XX == 1
185 static FT_HANDLE ftdih
= NULL
;
186 static FT_DEVICE ftdi_device
= 0;
187 #elif BUILD_FT2232_LIBFTDI == 1
188 static struct ftdi_context ftdic
;
189 static enum ftdi_chip_type ftdi_device
;
192 static jtag_command_t
* first_unsent
; /* next command that has to be sent */
193 static int require_send
;
195 /* http://urjtag.wiki.sourceforge.net/Cable + FT2232 says:
197 "There is a significant difference between libftdi and libftd2xx. The latter
198 one allows to schedule up to 64*64 bytes of result data while libftdi fails
199 with more than 4*64. As a consequence, the FT2232 driver is forced to
200 perform around 16x more USB transactions for long command streams with TDO
201 capture when running with libftdi."
204 #define FT2232_BUFFER_SIZE 131072
205 a comment would have been nice.
208 #define FT2232_BUFFER_SIZE 131072
210 static uint8_t* ft2232_buffer
= NULL
;
211 static int ft2232_buffer_size
= 0;
212 static int ft2232_read_pointer
= 0;
213 static int ft2232_expect_read
= 0;
216 * Function buffer_write
217 * writes a byte into the byte buffer, "ft2232_buffer", which must be sent later.
218 * @param val is the byte to send.
220 static inline void buffer_write(uint8_t val
)
222 assert(ft2232_buffer
);
223 assert((unsigned) ft2232_buffer_size
< (unsigned) FT2232_BUFFER_SIZE
);
224 ft2232_buffer
[ft2232_buffer_size
++] = val
;
228 * Function buffer_read
229 * returns a byte from the byte buffer.
231 static inline uint8_t buffer_read(void)
233 assert(ft2232_buffer
);
234 assert(ft2232_read_pointer
< ft2232_buffer_size
);
235 return ft2232_buffer
[ft2232_read_pointer
++];
239 * Clocks out \a bit_count bits on the TMS line, starting with the least
240 * significant bit of tms_bits and progressing to more significant bits.
241 * Rigorous state transition logging is done here via tap_set_state().
243 * @param mpsse_cmd One of the MPSSE TMS oriented commands such as
244 * 0x4b or 0x6b. See the MPSSE spec referenced above for their
245 * functionality. The MPSSE command "Clock Data to TMS/CS Pin (no Read)"
246 * is often used for this, 0x4b.
248 * @param tms_bits Holds the sequence of bits to send.
249 * @param tms_count Tells how many bits in the sequence.
250 * @param tdi_bit A single bit to pass on to TDI before the first TCK
251 * cycle and held static for the duration of TMS clocking.
253 * See the MPSSE spec referenced above.
255 static void clock_tms(uint8_t mpsse_cmd
, int tms_bits
, int tms_count
, bool tdi_bit
)
259 int tms_ndx
; /* bit index into tms_byte */
261 assert(tms_count
> 0);
264 LOG_DEBUG("mpsse cmd=%02x, tms_bits = 0x%08x, bit_count=%d", mpsse_cmd
, tms_bits
, tms_count
);
267 for (tms_byte
= tms_ndx
= i
= 0; i
< tms_count
; ++i
, tms_bits
>>=1)
269 bool bit
= tms_bits
& 1;
272 tms_byte
|= (1 << tms_ndx
);
274 /* always do state transitions in public view */
275 tap_set_state(tap_state_transition(tap_get_state(), bit
));
277 /* we wrote a bit to tms_byte just above, increment bit index. if bit was zero
282 if (tms_ndx
== 7 || i
== tms_count
-1)
284 buffer_write(mpsse_cmd
);
285 buffer_write(tms_ndx
- 1);
287 /* Bit 7 of the byte is passed on to TDI/DO before the first TCK/SK of
288 TMS/CS and is held static for the duration of TMS/CS clocking.
290 buffer_write(tms_byte
| (tdi_bit
<< 7));
296 * Function get_tms_buffer_requirements
297 * returns what clock_tms() will consume if called with
300 static inline int get_tms_buffer_requirements(int bit_count
)
302 return ((bit_count
+ 6)/7) * 3;
306 * Function move_to_state
307 * moves the TAP controller from the current state to a
308 * \a goal_state through a path given by tap_get_tms_path(). State transition
309 * logging is performed by delegation to clock_tms().
311 * @param goal_state is the destination state for the move.
313 static void move_to_state(tap_state_t goal_state
)
315 tap_state_t start_state
= tap_get_state();
317 /* goal_state is 1/2 of a tuple/pair of states which allow convenient
318 lookup of the required TMS pattern to move to this state from the
322 /* do the 2 lookups */
323 int tms_bits
= tap_get_tms_path(start_state
, goal_state
);
324 int tms_count
= tap_get_tms_path_len(start_state
, goal_state
);
326 DEBUG_JTAG_IO("start=%s goal=%s", tap_state_name(start_state
), tap_state_name(goal_state
));
328 clock_tms(0x4b, tms_bits
, tms_count
, 0);
331 jtag_interface_t ft2232_interface
=
334 .execute_queue
= ft2232_execute_queue
,
335 .speed
= ft2232_speed
,
336 .speed_div
= ft2232_speed_div
,
338 .register_commands
= ft2232_register_commands
,
343 static int ft2232_write(uint8_t* buf
, int size
, uint32_t* bytes_written
)
345 #if BUILD_FT2232_FTD2XX == 1
347 DWORD dw_bytes_written
;
348 if ((status
= FT_Write(ftdih
, buf
, size
, &dw_bytes_written
)) != FT_OK
)
350 *bytes_written
= dw_bytes_written
;
351 LOG_ERROR("FT_Write returned: %lu", status
);
352 return ERROR_JTAG_DEVICE_ERROR
;
356 *bytes_written
= dw_bytes_written
;
359 #elif BUILD_FT2232_LIBFTDI == 1
361 if ((retval
= ftdi_write_data(&ftdic
, buf
, size
)) < 0)
364 LOG_ERROR("ftdi_write_data: %s", ftdi_get_error_string(&ftdic
));
365 return ERROR_JTAG_DEVICE_ERROR
;
369 *bytes_written
= retval
;
375 static int ft2232_read(uint8_t* buf
, uint32_t size
, uint32_t* bytes_read
)
377 #if BUILD_FT2232_FTD2XX == 1
383 while ((*bytes_read
< size
) && timeout
--)
385 if ((status
= FT_Read(ftdih
, buf
+ *bytes_read
, size
-
386 *bytes_read
, &dw_bytes_read
)) != FT_OK
)
389 LOG_ERROR("FT_Read returned: %lu", status
);
390 return ERROR_JTAG_DEVICE_ERROR
;
392 *bytes_read
+= dw_bytes_read
;
395 #elif BUILD_FT2232_LIBFTDI == 1
400 while ((*bytes_read
< size
) && timeout
--)
402 if ((retval
= ftdi_read_data(&ftdic
, buf
+ *bytes_read
, size
- *bytes_read
)) < 0)
405 LOG_ERROR("ftdi_read_data: %s", ftdi_get_error_string(&ftdic
));
406 return ERROR_JTAG_DEVICE_ERROR
;
408 *bytes_read
+= retval
;
413 if (*bytes_read
< size
)
415 LOG_ERROR("couldn't read the requested number of bytes from FT2232 device (%i < %i)",
416 (unsigned int)(*bytes_read
),
418 return ERROR_JTAG_DEVICE_ERROR
;
424 static bool ft2232_device_is_highspeed(void)
426 #if BUILD_FT2232_FTD2XX == 1
427 return (ftdi_device
== FT_DEVICE_2232H
) || (ftdi_device
== FT_DEVICE_4232H
);
428 #elif BUILD_FT2232_LIBFTDI == 1
429 return (ftdi_device
== TYPE_2232H
|| ftdi_device
== TYPE_4232H
);
434 * Commands that only apply to the FT2232H and FT4232H devices.
435 * See chapter 6 in http://www.ftdichip.com/Documents/AppNotes/
436 * AN_108_Command_Processor_for_MPSSE_and_MCU_Host_Bus_Emulation_Modes.pdf
439 static int ft2232h_ft4232h_adaptive_clocking(bool enable
)
441 uint8_t buf
= enable
? 0x96 : 0x97;
442 LOG_DEBUG("%2.2x", buf
);
444 uint32_t bytes_written
;
445 int retval
= ft2232_write(&buf
, 1, &bytes_written
);
446 if ((ERROR_OK
!= retval
) || (bytes_written
!= 1))
448 LOG_ERROR("couldn't write command to %s adaptive clocking"
449 , enable
? "enable" : "disable");
457 * Enable/disable the clk divide by 5 of the 60MHz master clock.
458 * This result in a JTAG clock speed range of 91.553Hz-6MHz
459 * respective 457.763Hz-30MHz.
461 static int ft2232h_ft4232h_clk_divide_by_5(bool enable
)
463 uint32_t bytes_written
;
464 uint8_t buf
= enable
? 0x8b : 0x8a;
465 int retval
= ft2232_write(&buf
, 1, &bytes_written
);
466 if ((ERROR_OK
!= retval
) || (bytes_written
!= 1))
468 LOG_ERROR("couldn't write command to %s clk divide by 5"
469 , enable
? "enable" : "disable");
470 return ERROR_JTAG_INIT_FAILED
;
472 ft2232_max_tck
= enable
? FTDI_2232C_MAX_TCK
: FTDI_2232H_4232H_MAX_TCK
;
473 LOG_INFO("max TCK change to: %u kHz", ft2232_max_tck
);
478 static int ft2232_speed(int speed
)
482 uint32_t bytes_written
;
485 bool enable_adaptive_clocking
= (RTCK_SPEED
== speed
);
486 if (ft2232_device_is_highspeed())
487 retval
= ft2232h_ft4232h_adaptive_clocking(enable_adaptive_clocking
);
488 else if (enable_adaptive_clocking
)
490 LOG_ERROR("ft2232 device %lu does not support RTCK"
491 , (long unsigned int)ftdi_device
);
495 if ((enable_adaptive_clocking
) || (ERROR_OK
!= retval
))
498 buf
[0] = 0x86; /* command "set divisor" */
499 buf
[1] = speed
& 0xff; /* valueL (0 = 6MHz, 1 = 3MHz, 2 = 2.0MHz, ...*/
500 buf
[2] = (speed
>> 8) & 0xff; /* valueH */
502 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
503 if (((retval
= ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
505 LOG_ERROR("couldn't set FT2232 TCK speed");
512 static int ft2232_speed_div(int speed
, int* khz
)
514 /* Take a look in the FT2232 manual,
515 * AN2232C-01 Command Processor for
516 * MPSSE and MCU Host Bus. Chapter 3.8 */
518 *khz
= (RTCK_SPEED
== speed
) ? 0 : ft2232_max_tck
/ (1 + speed
);
523 static int ft2232_khz(int khz
, int* jtag_speed
)
527 if (ft2232_device_is_highspeed())
529 *jtag_speed
= RTCK_SPEED
;
534 LOG_DEBUG("RCLK not supported");
539 /* Take a look in the FT2232 manual,
540 * AN2232C-01 Command Processor for
541 * MPSSE and MCU Host Bus. Chapter 3.8
543 * We will calc here with a multiplier
544 * of 10 for better rounding later. */
546 /* Calc speed, (ft2232_max_tck / khz) - 1 */
547 /* Use 65000 for better rounding */
548 *jtag_speed
= ((ft2232_max_tck
*10) / khz
) - 10;
550 /* Add 0.9 for rounding */
553 /* Calc real speed */
554 *jtag_speed
= *jtag_speed
/ 10;
556 /* Check if speed is greater than 0 */
562 /* Check max value */
563 if (*jtag_speed
> 0xFFFF)
565 *jtag_speed
= 0xFFFF;
571 static int ft2232_register_commands(struct command_context_s
* cmd_ctx
)
573 register_command(cmd_ctx
, NULL
, "ft2232_device_desc", ft2232_handle_device_desc_command
,
574 COMMAND_CONFIG
, "the USB device description of the FTDI FT2232 device");
575 register_command(cmd_ctx
, NULL
, "ft2232_serial", ft2232_handle_serial_command
,
576 COMMAND_CONFIG
, "the serial number of the FTDI FT2232 device");
577 register_command(cmd_ctx
, NULL
, "ft2232_layout", ft2232_handle_layout_command
,
578 COMMAND_CONFIG
, "the layout of the FT2232 GPIO signals used to control output-enables and reset signals");
579 register_command(cmd_ctx
, NULL
, "ft2232_vid_pid", ft2232_handle_vid_pid_command
,
580 COMMAND_CONFIG
, "the vendor ID and product ID of the FTDI FT2232 device");
581 register_command(cmd_ctx
, NULL
, "ft2232_latency", ft2232_handle_latency_command
,
582 COMMAND_CONFIG
, "set the FT2232 latency timer to a new value");
586 static void ft2232_end_state(tap_state_t state
)
588 if (tap_is_state_stable(state
))
589 tap_set_end_state(state
);
592 LOG_ERROR("BUG: %s is not a stable end state", tap_state_name(state
));
597 static void ft2232_read_scan(enum scan_type type
, uint8_t* buffer
, int scan_size
)
599 int num_bytes
= (scan_size
+ 7) / 8;
600 int bits_left
= scan_size
;
603 while (num_bytes
-- > 1)
605 buffer
[cur_byte
++] = buffer_read();
609 buffer
[cur_byte
] = 0x0;
611 /* There is one more partial byte left from the clock data in/out instructions */
614 buffer
[cur_byte
] = buffer_read() >> 1;
616 /* This shift depends on the length of the clock data to tms instruction, insterted at end of the scan, now fixed to a two step transition in ft2232_add_scan */
617 buffer
[cur_byte
] = (buffer
[cur_byte
] | (((buffer_read()) << 1) & 0x80)) >> (8 - bits_left
);
620 static void ft2232_debug_dump_buffer(void)
626 for (i
= 0; i
< ft2232_buffer_size
; i
++)
628 line_p
+= snprintf(line_p
, 256 - (line_p
- line
), "%2.2x ", ft2232_buffer
[i
]);
631 LOG_DEBUG("%s", line
);
637 LOG_DEBUG("%s", line
);
640 static int ft2232_send_and_recv(jtag_command_t
* first
, jtag_command_t
* last
)
647 uint32_t bytes_written
= 0;
648 uint32_t bytes_read
= 0;
650 #ifdef _DEBUG_USB_IO_
651 struct timeval start
, inter
, inter2
, end
;
652 struct timeval d_inter
, d_inter2
, d_end
;
655 #ifdef _DEBUG_USB_COMMS_
656 LOG_DEBUG("write buffer (size %i):", ft2232_buffer_size
);
657 ft2232_debug_dump_buffer();
660 #ifdef _DEBUG_USB_IO_
661 gettimeofday(&start
, NULL
);
664 if ((retval
= ft2232_write(ft2232_buffer
, ft2232_buffer_size
, &bytes_written
)) != ERROR_OK
)
666 LOG_ERROR("couldn't write MPSSE commands to FT2232");
670 #ifdef _DEBUG_USB_IO_
671 gettimeofday(&inter
, NULL
);
674 if (ft2232_expect_read
)
677 ft2232_buffer_size
= 0;
679 #ifdef _DEBUG_USB_IO_
680 gettimeofday(&inter2
, NULL
);
683 if ((retval
= ft2232_read(ft2232_buffer
, ft2232_expect_read
, &bytes_read
)) != ERROR_OK
)
685 LOG_ERROR("couldn't read from FT2232");
689 #ifdef _DEBUG_USB_IO_
690 gettimeofday(&end
, NULL
);
692 timeval_subtract(&d_inter
, &inter
, &start
);
693 timeval_subtract(&d_inter2
, &inter2
, &start
);
694 timeval_subtract(&d_end
, &end
, &start
);
696 LOG_INFO("inter: %u.%06u, inter2: %u.%06u end: %u.%06u",
697 (unsigned)d_inter
.tv_sec
, (unsigned)d_inter
.tv_usec
,
698 (unsigned)d_inter2
.tv_sec
, (unsigned)d_inter2
.tv_usec
,
699 (unsigned)d_end
.tv_sec
, (unsigned)d_end
.tv_usec
);
702 ft2232_buffer_size
= bytes_read
;
704 if (ft2232_expect_read
!= ft2232_buffer_size
)
706 LOG_ERROR("ft2232_expect_read (%i) != ft2232_buffer_size (%i) (%i retries)", ft2232_expect_read
,
709 ft2232_debug_dump_buffer();
714 #ifdef _DEBUG_USB_COMMS_
715 LOG_DEBUG("read buffer (%i retries): %i bytes", 100 - timeout
, ft2232_buffer_size
);
716 ft2232_debug_dump_buffer();
720 ft2232_expect_read
= 0;
721 ft2232_read_pointer
= 0;
723 /* return ERROR_OK, unless a jtag_read_buffer returns a failed check
724 * that wasn't handled by a caller-provided error handler
734 type
= jtag_scan_type(cmd
->cmd
.scan
);
735 if (type
!= SCAN_OUT
)
737 scan_size
= jtag_scan_size(cmd
->cmd
.scan
);
738 buffer
= calloc(CEIL(scan_size
, 8), 1);
739 ft2232_read_scan(type
, buffer
, scan_size
);
740 if (jtag_read_buffer(buffer
, cmd
->cmd
.scan
) != ERROR_OK
)
741 retval
= ERROR_JTAG_QUEUE_FAILED
;
753 ft2232_buffer_size
= 0;
759 * Function ft2232_add_pathmove
760 * moves the TAP controller from the current state to a new state through the
761 * given path, where path is an array of tap_state_t's.
763 * @param path is an array of tap_stat_t which gives the states to traverse through
764 * ending with the last state at path[num_states-1]
765 * @param num_states is the count of state steps to move through
767 static void ft2232_add_pathmove(tap_state_t
* path
, int num_states
)
771 assert((unsigned) num_states
<= 32u); /* tms_bits only holds 32 bits */
773 /* this loop verifies that the path is legal and logs each state in the path */
776 unsigned char tms_byte
= 0; /* zero this on each MPSSE batch */
778 int num_states_batch
= num_states
> 7 ? 7 : num_states
;
780 /* command "Clock Data to TMS/CS Pin (no Read)" */
783 /* number of states remaining */
784 buffer_write(num_states_batch
- 1);
786 while (num_states_batch
--) {
787 /* either TMS=0 or TMS=1 must work ... */
788 if (tap_state_transition(tap_get_state(), false)
789 == path
[state_count
])
790 buf_set_u32(&tms_byte
, bit_count
++, 1, 0x0);
791 else if (tap_state_transition(tap_get_state(), true)
792 == path
[state_count
])
793 buf_set_u32(&tms_byte
, bit_count
++, 1, 0x1);
795 /* ... or else the caller goofed BADLY */
797 LOG_ERROR("BUG: %s -> %s isn't a valid "
798 "TAP state transition",
799 tap_state_name(tap_get_state()),
800 tap_state_name(path
[state_count
]));
804 tap_set_state(path
[state_count
]);
809 buffer_write(tms_byte
);
811 tap_set_end_state(tap_get_state());
814 static void ft2232_add_scan(bool ir_scan
, enum scan_type type
, uint8_t* buffer
, int scan_size
)
816 int num_bytes
= (scan_size
+ 7) / 8;
817 int bits_left
= scan_size
;
823 if (tap_get_state() != TAP_DRSHIFT
)
825 move_to_state(TAP_DRSHIFT
);
830 if (tap_get_state() != TAP_IRSHIFT
)
832 move_to_state(TAP_IRSHIFT
);
836 /* add command for complete bytes */
837 while (num_bytes
> 1)
842 /* Clock Data Bytes In and Out LSB First */
844 /* LOG_DEBUG("added TDI bytes (io %i)", num_bytes); */
846 else if (type
== SCAN_OUT
)
848 /* Clock Data Bytes Out on -ve Clock Edge LSB First (no Read) */
850 /* LOG_DEBUG("added TDI bytes (o)"); */
852 else if (type
== SCAN_IN
)
854 /* Clock Data Bytes In on +ve Clock Edge LSB First (no Write) */
856 /* LOG_DEBUG("added TDI bytes (i %i)", num_bytes); */
859 thisrun_bytes
= (num_bytes
> 65537) ? 65536 : (num_bytes
- 1);
860 num_bytes
-= thisrun_bytes
;
862 buffer_write((uint8_t) (thisrun_bytes
- 1));
863 buffer_write((uint8_t) ((thisrun_bytes
- 1) >> 8));
867 /* add complete bytes */
868 while (thisrun_bytes
-- > 0)
870 buffer_write(buffer
[cur_byte
++]);
874 else /* (type == SCAN_IN) */
876 bits_left
-= 8 * (thisrun_bytes
);
880 /* the most signifcant bit is scanned during TAP movement */
882 last_bit
= (buffer
[cur_byte
] >> (bits_left
- 1)) & 0x1;
886 /* process remaining bits but the last one */
891 /* Clock Data Bits In and Out LSB First */
893 /* LOG_DEBUG("added TDI bits (io) %i", bits_left - 1); */
895 else if (type
== SCAN_OUT
)
897 /* Clock Data Bits Out on -ve Clock Edge LSB First (no Read) */
899 /* LOG_DEBUG("added TDI bits (o)"); */
901 else if (type
== SCAN_IN
)
903 /* Clock Data Bits In on +ve Clock Edge LSB First (no Write) */
905 /* LOG_DEBUG("added TDI bits (i %i)", bits_left - 1); */
908 buffer_write(bits_left
- 2);
910 buffer_write(buffer
[cur_byte
]);
913 if ((ir_scan
&& (tap_get_end_state() == TAP_IRSHIFT
))
914 || (!ir_scan
&& (tap_get_end_state() == TAP_DRSHIFT
)))
918 /* Clock Data Bits In and Out LSB First */
920 /* LOG_DEBUG("added TDI bits (io) %i", bits_left - 1); */
922 else if (type
== SCAN_OUT
)
924 /* Clock Data Bits Out on -ve Clock Edge LSB First (no Read) */
926 /* LOG_DEBUG("added TDI bits (o)"); */
928 else if (type
== SCAN_IN
)
930 /* Clock Data Bits In on +ve Clock Edge LSB First (no Write) */
932 /* LOG_DEBUG("added TDI bits (i %i)", bits_left - 1); */
935 buffer_write(last_bit
);
943 /* move from Shift-IR/DR to end state */
944 if (type
!= SCAN_OUT
)
946 /* We always go to the PAUSE state in two step at the end of an IN or IO scan */
947 /* This must be coordinated with the bit shifts in ft2232_read_scan */
950 /* Clock Data to TMS/CS Pin with Read */
952 /* LOG_DEBUG("added TMS scan (read)"); */
956 tms_bits
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
957 tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
958 /* Clock Data to TMS/CS Pin (no Read) */
960 /* LOG_DEBUG("added TMS scan (no read)"); */
963 clock_tms(mpsse_cmd
, tms_bits
, tms_count
, last_bit
);
966 if (tap_get_state() != tap_get_end_state())
968 move_to_state(tap_get_end_state());
972 static int ft2232_large_scan(scan_command_t
* cmd
, enum scan_type type
, uint8_t* buffer
, int scan_size
)
974 int num_bytes
= (scan_size
+ 7) / 8;
975 int bits_left
= scan_size
;
978 uint8_t* receive_buffer
= malloc(CEIL(scan_size
, 8));
979 uint8_t* receive_pointer
= receive_buffer
;
980 uint32_t bytes_written
;
983 int thisrun_read
= 0;
987 LOG_ERROR("BUG: large IR scans are not supported");
991 if (tap_get_state() != TAP_DRSHIFT
)
993 move_to_state(TAP_DRSHIFT
);
996 if ((retval
= ft2232_write(ft2232_buffer
, ft2232_buffer_size
, &bytes_written
)) != ERROR_OK
)
998 LOG_ERROR("couldn't write MPSSE commands to FT2232");
1001 LOG_DEBUG("ft2232_buffer_size: %i, bytes_written: %i",
1002 ft2232_buffer_size
, (int)bytes_written
);
1003 ft2232_buffer_size
= 0;
1005 /* add command for complete bytes */
1006 while (num_bytes
> 1)
1010 if (type
== SCAN_IO
)
1012 /* Clock Data Bytes In and Out LSB First */
1014 /* LOG_DEBUG("added TDI bytes (io %i)", num_bytes); */
1016 else if (type
== SCAN_OUT
)
1018 /* Clock Data Bytes Out on -ve Clock Edge LSB First (no Read) */
1020 /* LOG_DEBUG("added TDI bytes (o)"); */
1022 else if (type
== SCAN_IN
)
1024 /* Clock Data Bytes In on +ve Clock Edge LSB First (no Write) */
1026 /* LOG_DEBUG("added TDI bytes (i %i)", num_bytes); */
1029 thisrun_bytes
= (num_bytes
> 65537) ? 65536 : (num_bytes
- 1);
1030 thisrun_read
= thisrun_bytes
;
1031 num_bytes
-= thisrun_bytes
;
1032 buffer_write((uint8_t) (thisrun_bytes
- 1));
1033 buffer_write((uint8_t) ((thisrun_bytes
- 1) >> 8));
1035 if (type
!= SCAN_IN
)
1037 /* add complete bytes */
1038 while (thisrun_bytes
-- > 0)
1040 buffer_write(buffer
[cur_byte
]);
1045 else /* (type == SCAN_IN) */
1047 bits_left
-= 8 * (thisrun_bytes
);
1050 if ((retval
= ft2232_write(ft2232_buffer
, ft2232_buffer_size
, &bytes_written
)) != ERROR_OK
)
1052 LOG_ERROR("couldn't write MPSSE commands to FT2232");
1055 LOG_DEBUG("ft2232_buffer_size: %i, bytes_written: %i",
1057 (int)bytes_written
);
1058 ft2232_buffer_size
= 0;
1060 if (type
!= SCAN_OUT
)
1062 if ((retval
= ft2232_read(receive_pointer
, thisrun_read
, &bytes_read
)) != ERROR_OK
)
1064 LOG_ERROR("couldn't read from FT2232");
1067 LOG_DEBUG("thisrun_read: %i, bytes_read: %i",
1070 receive_pointer
+= bytes_read
;
1076 /* the most signifcant bit is scanned during TAP movement */
1077 if (type
!= SCAN_IN
)
1078 last_bit
= (buffer
[cur_byte
] >> (bits_left
- 1)) & 0x1;
1082 /* process remaining bits but the last one */
1085 if (type
== SCAN_IO
)
1087 /* Clock Data Bits In and Out LSB First */
1089 /* LOG_DEBUG("added TDI bits (io) %i", bits_left - 1); */
1091 else if (type
== SCAN_OUT
)
1093 /* Clock Data Bits Out on -ve Clock Edge LSB First (no Read) */
1095 /* LOG_DEBUG("added TDI bits (o)"); */
1097 else if (type
== SCAN_IN
)
1099 /* Clock Data Bits In on +ve Clock Edge LSB First (no Write) */
1101 /* LOG_DEBUG("added TDI bits (i %i)", bits_left - 1); */
1103 buffer_write(bits_left
- 2);
1104 if (type
!= SCAN_IN
)
1105 buffer_write(buffer
[cur_byte
]);
1107 if (type
!= SCAN_OUT
)
1111 if (tap_get_end_state() == TAP_DRSHIFT
)
1113 if (type
== SCAN_IO
)
1115 /* Clock Data Bits In and Out LSB First */
1117 /* LOG_DEBUG("added TDI bits (io) %i", bits_left - 1); */
1119 else if (type
== SCAN_OUT
)
1121 /* Clock Data Bits Out on -ve Clock Edge LSB First (no Read) */
1123 /* LOG_DEBUG("added TDI bits (o)"); */
1125 else if (type
== SCAN_IN
)
1127 /* Clock Data Bits In on +ve Clock Edge LSB First (no Write) */
1129 /* LOG_DEBUG("added TDI bits (i %i)", bits_left - 1); */
1132 buffer_write(last_bit
);
1136 int tms_bits
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1137 int tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1140 /* move from Shift-IR/DR to end state */
1141 if (type
!= SCAN_OUT
)
1143 /* Clock Data to TMS/CS Pin with Read */
1145 /* LOG_DEBUG("added TMS scan (read)"); */
1149 /* Clock Data to TMS/CS Pin (no Read) */
1151 /* LOG_DEBUG("added TMS scan (no read)"); */
1154 clock_tms(mpsse_cmd
, tms_bits
, tms_count
, last_bit
);
1157 if (type
!= SCAN_OUT
)
1160 if ((retval
= ft2232_write(ft2232_buffer
, ft2232_buffer_size
, &bytes_written
)) != ERROR_OK
)
1162 LOG_ERROR("couldn't write MPSSE commands to FT2232");
1165 LOG_DEBUG("ft2232_buffer_size: %i, bytes_written: %i",
1167 (int)bytes_written
);
1168 ft2232_buffer_size
= 0;
1170 if (type
!= SCAN_OUT
)
1172 if ((retval
= ft2232_read(receive_pointer
, thisrun_read
, &bytes_read
)) != ERROR_OK
)
1174 LOG_ERROR("couldn't read from FT2232");
1177 LOG_DEBUG("thisrun_read: %i, bytes_read: %i",
1180 receive_pointer
+= bytes_read
;
1186 static int ft2232_predict_scan_out(int scan_size
, enum scan_type type
)
1188 int predicted_size
= 3;
1189 int num_bytes
= (scan_size
- 1) / 8;
1191 if (tap_get_state() != TAP_DRSHIFT
)
1192 predicted_size
+= get_tms_buffer_requirements(tap_get_tms_path_len(tap_get_state(), TAP_DRSHIFT
));
1194 if (type
== SCAN_IN
) /* only from device to host */
1196 /* complete bytes */
1197 predicted_size
+= CEIL(num_bytes
, 65536) * 3;
1199 /* remaining bits - 1 (up to 7) */
1200 predicted_size
+= ((scan_size
- 1) % 8) ? 2 : 0;
1202 else /* host to device, or bidirectional */
1204 /* complete bytes */
1205 predicted_size
+= num_bytes
+ CEIL(num_bytes
, 65536) * 3;
1207 /* remaining bits -1 (up to 7) */
1208 predicted_size
+= ((scan_size
- 1) % 8) ? 3 : 0;
1211 return predicted_size
;
1214 static int ft2232_predict_scan_in(int scan_size
, enum scan_type type
)
1216 int predicted_size
= 0;
1218 if (type
!= SCAN_OUT
)
1220 /* complete bytes */
1221 predicted_size
+= (CEIL(scan_size
, 8) > 1) ? (CEIL(scan_size
, 8) - 1) : 0;
1223 /* remaining bits - 1 */
1224 predicted_size
+= ((scan_size
- 1) % 8) ? 1 : 0;
1226 /* last bit (from TMS scan) */
1227 predicted_size
+= 1;
1230 /* LOG_DEBUG("scan_size: %i, predicted_size: %i", scan_size, predicted_size); */
1232 return predicted_size
;
1235 static void usbjtag_reset(int trst
, int srst
)
1237 enum reset_types jtag_reset_config
= jtag_get_reset_config();
1240 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
1241 low_direction
|= nTRSTnOE
; /* switch to output pin (output is low) */
1243 low_output
&= ~nTRST
; /* switch output low */
1247 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
1248 low_direction
&= ~nTRSTnOE
; /* switch to input pin (high-Z + internal and external pullup) */
1250 low_output
|= nTRST
; /* switch output high */
1255 if (jtag_reset_config
& RESET_SRST_PUSH_PULL
)
1256 low_output
&= ~nSRST
; /* switch output low */
1258 low_direction
|= nSRSTnOE
; /* switch to output pin (output is low) */
1262 if (jtag_reset_config
& RESET_SRST_PUSH_PULL
)
1263 low_output
|= nSRST
; /* switch output high */
1265 low_direction
&= ~nSRSTnOE
; /* switch to input pin (high-Z) */
1268 /* command "set data bits low byte" */
1270 buffer_write(low_output
);
1271 buffer_write(low_direction
);
1274 static void jtagkey_reset(int trst
, int srst
)
1276 enum reset_types jtag_reset_config
= jtag_get_reset_config();
1279 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
1280 high_output
&= ~nTRSTnOE
;
1282 high_output
&= ~nTRST
;
1286 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
1287 high_output
|= nTRSTnOE
;
1289 high_output
|= nTRST
;
1294 if (jtag_reset_config
& RESET_SRST_PUSH_PULL
)
1295 high_output
&= ~nSRST
;
1297 high_output
&= ~nSRSTnOE
;
1301 if (jtag_reset_config
& RESET_SRST_PUSH_PULL
)
1302 high_output
|= nSRST
;
1304 high_output
|= nSRSTnOE
;
1307 /* command "set data bits high byte" */
1309 buffer_write(high_output
);
1310 buffer_write(high_direction
);
1311 LOG_DEBUG("trst: %i, srst: %i, high_output: 0x%2.2x, high_direction: 0x%2.2x", trst
, srst
, high_output
,
1315 static void olimex_jtag_reset(int trst
, int srst
)
1317 enum reset_types jtag_reset_config
= jtag_get_reset_config();
1320 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
1321 high_output
&= ~nTRSTnOE
;
1323 high_output
&= ~nTRST
;
1327 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
1328 high_output
|= nTRSTnOE
;
1330 high_output
|= nTRST
;
1335 high_output
|= nSRST
;
1339 high_output
&= ~nSRST
;
1342 /* command "set data bits high byte" */
1344 buffer_write(high_output
);
1345 buffer_write(high_direction
);
1346 LOG_DEBUG("trst: %i, srst: %i, high_output: 0x%2.2x, high_direction: 0x%2.2x", trst
, srst
, high_output
,
1350 static void axm0432_jtag_reset(int trst
, int srst
)
1354 tap_set_state(TAP_RESET
);
1355 high_output
&= ~nTRST
;
1359 high_output
|= nTRST
;
1364 high_output
&= ~nSRST
;
1368 high_output
|= nSRST
;
1371 /* command "set data bits low byte" */
1373 buffer_write(high_output
);
1374 buffer_write(high_direction
);
1375 LOG_DEBUG("trst: %i, srst: %i, high_output: 0x%2.2x, high_direction: 0x%2.2x", trst
, srst
, high_output
,
1379 static void flyswatter_reset(int trst
, int srst
)
1383 low_output
&= ~nTRST
;
1387 low_output
|= nTRST
;
1392 low_output
|= nSRST
;
1396 low_output
&= ~nSRST
;
1399 /* command "set data bits low byte" */
1401 buffer_write(low_output
);
1402 buffer_write(low_direction
);
1403 LOG_DEBUG("trst: %i, srst: %i, low_output: 0x%2.2x, low_direction: 0x%2.2x", trst
, srst
, low_output
, low_direction
);
1406 static void turtle_reset(int trst
, int srst
)
1412 low_output
|= nSRST
;
1416 low_output
&= ~nSRST
;
1419 /* command "set data bits low byte" */
1421 buffer_write(low_output
);
1422 buffer_write(low_direction
);
1423 LOG_DEBUG("srst: %i, low_output: 0x%2.2x, low_direction: 0x%2.2x", srst
, low_output
, low_direction
);
1426 static void comstick_reset(int trst
, int srst
)
1430 high_output
&= ~nTRST
;
1434 high_output
|= nTRST
;
1439 high_output
&= ~nSRST
;
1443 high_output
|= nSRST
;
1446 /* command "set data bits high byte" */
1448 buffer_write(high_output
);
1449 buffer_write(high_direction
);
1450 LOG_DEBUG("trst: %i, srst: %i, high_output: 0x%2.2x, high_direction: 0x%2.2x", trst
, srst
, high_output
,
1454 static void stm32stick_reset(int trst
, int srst
)
1458 high_output
&= ~nTRST
;
1462 high_output
|= nTRST
;
1467 low_output
&= ~nSRST
;
1471 low_output
|= nSRST
;
1474 /* command "set data bits low byte" */
1476 buffer_write(low_output
);
1477 buffer_write(low_direction
);
1479 /* command "set data bits high byte" */
1481 buffer_write(high_output
);
1482 buffer_write(high_direction
);
1483 LOG_DEBUG("trst: %i, srst: %i, high_output: 0x%2.2x, high_direction: 0x%2.2x", trst
, srst
, high_output
,
1487 static void sheevaplug_reset(int trst
, int srst
)
1490 high_output
&= ~nTRST
;
1492 high_output
|= nTRST
;
1495 high_output
&= ~nSRSTnOE
;
1497 high_output
|= nSRSTnOE
;
1499 /* command "set data bits high byte" */
1501 buffer_write(high_output
);
1502 buffer_write(high_direction
);
1503 LOG_DEBUG("trst: %i, srst: %i, high_output: 0x%2.2x, high_direction: 0x%2.2x", trst
, srst
, high_output
, high_direction
);
1506 static int ft2232_execute_runtest(jtag_command_t
*cmd
)
1510 int predicted_size
= 0;
1513 DEBUG_JTAG_IO("runtest %i cycles, end in %s",
1514 cmd
->cmd
.runtest
->num_cycles
,
1515 tap_state_name(cmd
->cmd
.runtest
->end_state
));
1517 /* only send the maximum buffer size that FT2232C can handle */
1519 if (tap_get_state() != TAP_IDLE
)
1520 predicted_size
+= 3;
1521 predicted_size
+= 3 * CEIL(cmd
->cmd
.runtest
->num_cycles
, 7);
1522 if (cmd
->cmd
.runtest
->end_state
!= TAP_IDLE
)
1523 predicted_size
+= 3;
1524 if (tap_get_end_state() != TAP_IDLE
)
1525 predicted_size
+= 3;
1526 if (ft2232_buffer_size
+ predicted_size
+ 1 > FT2232_BUFFER_SIZE
)
1528 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1529 retval
= ERROR_JTAG_QUEUE_FAILED
;
1533 if (tap_get_state() != TAP_IDLE
)
1535 move_to_state(TAP_IDLE
);
1538 i
= cmd
->cmd
.runtest
->num_cycles
;
1541 /* there are no state transitions in this code, so omit state tracking */
1543 /* command "Clock Data to TMS/CS Pin (no Read)" */
1547 buffer_write((i
> 7) ? 6 : (i
- 1));
1551 tap_set_state(TAP_IDLE
);
1553 i
-= (i
> 7) ? 7 : i
;
1554 /* LOG_DEBUG("added TMS scan (no read)"); */
1557 ft2232_end_state(cmd
->cmd
.runtest
->end_state
);
1559 if (tap_get_state() != tap_get_end_state())
1561 move_to_state(tap_get_end_state());
1565 #ifdef _DEBUG_JTAG_IO_
1566 LOG_DEBUG("runtest: %i, end in %s", cmd
->cmd
.runtest
->num_cycles
, tap_state_name(tap_get_end_state()));
1572 static int ft2232_execute_statemove(jtag_command_t
*cmd
)
1574 int predicted_size
= 0;
1575 int retval
= ERROR_OK
;
1577 DEBUG_JTAG_IO("statemove end in %i", cmd
->cmd
.statemove
->end_state
);
1579 /* only send the maximum buffer size that FT2232C can handle */
1581 if (ft2232_buffer_size
+ predicted_size
+ 1 > FT2232_BUFFER_SIZE
)
1583 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1584 retval
= ERROR_JTAG_QUEUE_FAILED
;
1588 ft2232_end_state(cmd
->cmd
.statemove
->end_state
);
1590 /* For TAP_RESET, ignore the current recorded state. It's often
1591 * wrong at server startup, and this transation is critical whenever
1594 if (tap_get_end_state() == TAP_RESET
) {
1595 clock_tms(0x4b, 0xff, 5, 0);
1598 /* shortest-path move to desired end state */
1599 } else if (tap_get_state() != tap_get_end_state())
1601 move_to_state(tap_get_end_state());
1608 static int ft2232_execute_pathmove(jtag_command_t
*cmd
)
1610 int predicted_size
= 0;
1611 int retval
= ERROR_OK
;
1613 tap_state_t
* path
= cmd
->cmd
.pathmove
->path
;
1614 int num_states
= cmd
->cmd
.pathmove
->num_states
;
1616 DEBUG_JTAG_IO("pathmove: %i states, current: %s end: %s", num_states
,
1617 tap_state_name(tap_get_state()),
1618 tap_state_name(path
[num_states
-1]));
1620 /* only send the maximum buffer size that FT2232C can handle */
1621 predicted_size
= 3 * CEIL(num_states
, 7);
1622 if (ft2232_buffer_size
+ predicted_size
+ 1 > FT2232_BUFFER_SIZE
)
1624 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1625 retval
= ERROR_JTAG_QUEUE_FAILED
;
1631 ft2232_add_pathmove(path
, num_states
);
1637 static int ft2232_execute_scan(jtag_command_t
*cmd
)
1640 int scan_size
; /* size of IR or DR scan */
1641 int predicted_size
= 0;
1642 int retval
= ERROR_OK
;
1644 enum scan_type type
= jtag_scan_type(cmd
->cmd
.scan
);
1646 DEBUG_JTAG_IO("%s type:%d", cmd
->cmd
.scan
->ir_scan
? "IRSCAN" : "DRSCAN", type
);
1648 scan_size
= jtag_build_buffer(cmd
->cmd
.scan
, &buffer
);
1650 predicted_size
= ft2232_predict_scan_out(scan_size
, type
);
1651 if ((predicted_size
+ 1) > FT2232_BUFFER_SIZE
)
1653 LOG_DEBUG("oversized ft2232 scan (predicted_size > FT2232_BUFFER_SIZE)");
1654 /* unsent commands before this */
1655 if (first_unsent
!= cmd
)
1656 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1657 retval
= ERROR_JTAG_QUEUE_FAILED
;
1659 /* current command */
1660 ft2232_end_state(cmd
->cmd
.scan
->end_state
);
1661 ft2232_large_scan(cmd
->cmd
.scan
, type
, buffer
, scan_size
);
1663 first_unsent
= cmd
->next
;
1668 else if (ft2232_buffer_size
+ predicted_size
+ 1 > FT2232_BUFFER_SIZE
)
1670 LOG_DEBUG("ft2232 buffer size reached, sending queued commands (first_unsent: %p, cmd: %p)",
1673 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1674 retval
= ERROR_JTAG_QUEUE_FAILED
;
1678 ft2232_expect_read
+= ft2232_predict_scan_in(scan_size
, type
);
1679 /* LOG_DEBUG("new read size: %i", ft2232_expect_read); */
1680 ft2232_end_state(cmd
->cmd
.scan
->end_state
);
1681 ft2232_add_scan(cmd
->cmd
.scan
->ir_scan
, type
, buffer
, scan_size
);
1685 #ifdef _DEBUG_JTAG_IO_
1686 LOG_DEBUG("%s scan, %i bits, end in %s", (cmd
->cmd
.scan
->ir_scan
) ? "IR" : "DR", scan_size
,
1687 tap_state_name(tap_get_end_state()));
1693 static int ft2232_execute_reset(jtag_command_t
*cmd
)
1696 int predicted_size
= 0;
1699 DEBUG_JTAG_IO("reset trst: %i srst %i",
1700 cmd
->cmd
.reset
->trst
, cmd
->cmd
.reset
->srst
);
1702 /* only send the maximum buffer size that FT2232C can handle */
1704 if (ft2232_buffer_size
+ predicted_size
+ 1 > FT2232_BUFFER_SIZE
)
1706 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1707 retval
= ERROR_JTAG_QUEUE_FAILED
;
1712 layout
->reset(cmd
->cmd
.reset
->trst
, cmd
->cmd
.reset
->srst
);
1715 #ifdef _DEBUG_JTAG_IO_
1716 LOG_DEBUG("trst: %i, srst: %i", cmd
->cmd
.reset
->trst
, cmd
->cmd
.reset
->srst
);
1721 static int ft2232_execute_sleep(jtag_command_t
*cmd
)
1726 DEBUG_JTAG_IO("sleep %i", cmd
->cmd
.sleep
->us
);
1728 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1729 retval
= ERROR_JTAG_QUEUE_FAILED
;
1730 first_unsent
= cmd
->next
;
1731 jtag_sleep(cmd
->cmd
.sleep
->us
);
1732 #ifdef _DEBUG_JTAG_IO_
1733 LOG_DEBUG("sleep %i usec while in %s", cmd
->cmd
.sleep
->us
, tap_state_name(tap_get_state()));
1739 static int ft2232_execute_stableclocks(jtag_command_t
*cmd
)
1744 /* this is only allowed while in a stable state. A check for a stable
1745 * state was done in jtag_add_clocks()
1747 if (ft2232_stableclocks(cmd
->cmd
.stableclocks
->num_cycles
, cmd
) != ERROR_OK
)
1748 retval
= ERROR_JTAG_QUEUE_FAILED
;
1749 #ifdef _DEBUG_JTAG_IO_
1750 LOG_DEBUG("clocks %i while in %s", cmd
->cmd
.stableclocks
->num_cycles
, tap_state_name(tap_get_state()));
1756 static int ft2232_execute_command(jtag_command_t
*cmd
)
1763 case JTAG_RESET
: retval
= ft2232_execute_reset(cmd
); break;
1764 case JTAG_RUNTEST
: retval
= ft2232_execute_runtest(cmd
); break;
1765 case JTAG_STATEMOVE
: retval
= ft2232_execute_statemove(cmd
); break;
1766 case JTAG_PATHMOVE
: retval
= ft2232_execute_pathmove(cmd
); break;
1767 case JTAG_SCAN
: retval
= ft2232_execute_scan(cmd
); break;
1768 case JTAG_SLEEP
: retval
= ft2232_execute_sleep(cmd
); break;
1769 case JTAG_STABLECLOCKS
: retval
= ft2232_execute_stableclocks(cmd
); break;
1771 LOG_ERROR("BUG: unknown JTAG command type encountered");
1777 static int ft2232_execute_queue()
1779 jtag_command_t
* cmd
= jtag_command_queue
; /* currently processed command */
1782 first_unsent
= cmd
; /* next command that has to be sent */
1785 /* return ERROR_OK, unless ft2232_send_and_recv reports a failed check
1786 * that wasn't handled by a caller-provided error handler
1790 ft2232_buffer_size
= 0;
1791 ft2232_expect_read
= 0;
1793 /* blink, if the current layout has that feature */
1799 if (ft2232_execute_command(cmd
) != ERROR_OK
)
1800 retval
= ERROR_JTAG_QUEUE_FAILED
;
1801 /* Start reading input before FT2232 TX buffer fills up */
1803 if (ft2232_expect_read
> 256)
1805 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1806 retval
= ERROR_JTAG_QUEUE_FAILED
;
1811 if (require_send
> 0)
1812 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
1813 retval
= ERROR_JTAG_QUEUE_FAILED
;
1818 #if BUILD_FT2232_FTD2XX == 1
1819 static int ft2232_init_ftd2xx(uint16_t vid
, uint16_t pid
, int more
, int* try_more
)
1823 char SerialNumber
[16];
1824 char Description
[64];
1825 DWORD openex_flags
= 0;
1826 char* openex_string
= NULL
;
1827 uint8_t latency_timer
;
1829 LOG_DEBUG("'ft2232' interface using FTD2XX with '%s' layout (%4.4x:%4.4x)", ft2232_layout
, vid
, pid
);
1832 /* Add non-standard Vid/Pid to the linux driver */
1833 if ((status
= FT_SetVIDPID(vid
, pid
)) != FT_OK
)
1835 LOG_WARNING("couldn't add %4.4x:%4.4x", vid
, pid
);
1839 if (ft2232_device_desc
&& ft2232_serial
)
1841 LOG_WARNING("can't open by device description and serial number, giving precedence to serial");
1842 ft2232_device_desc
= NULL
;
1845 if (ft2232_device_desc
)
1847 openex_string
= ft2232_device_desc
;
1848 openex_flags
= FT_OPEN_BY_DESCRIPTION
;
1850 else if (ft2232_serial
)
1852 openex_string
= ft2232_serial
;
1853 openex_flags
= FT_OPEN_BY_SERIAL_NUMBER
;
1857 LOG_ERROR("neither device description nor serial number specified");
1858 LOG_ERROR("please add \"ft2232_device_desc <string>\" or \"ft2232_serial <string>\" to your .cfg file");
1860 return ERROR_JTAG_INIT_FAILED
;
1863 status
= FT_OpenEx(openex_string
, openex_flags
, &ftdih
);
1864 if (status
!= FT_OK
) {
1865 /* under Win32, the FTD2XX driver appends an "A" to the end
1866 * of the description, if we tried by the desc, then
1867 * try by the alternate "A" description. */
1868 if (openex_string
== ft2232_device_desc
) {
1869 /* Try the alternate method. */
1870 openex_string
= ft2232_device_desc_A
;
1871 status
= FT_OpenEx(openex_string
, openex_flags
, &ftdih
);
1872 if (status
== FT_OK
) {
1873 /* yea, the "alternate" method worked! */
1875 /* drat, give the user a meaningfull message.
1876 * telling the use we tried *BOTH* methods. */
1877 LOG_WARNING("Unable to open FTDI Device tried: '%s' and '%s'\n",
1879 ft2232_device_desc_A
);
1884 if (status
!= FT_OK
)
1890 LOG_WARNING("unable to open ftdi device (trying more): %lu", status
);
1892 return ERROR_JTAG_INIT_FAILED
;
1894 LOG_ERROR("unable to open ftdi device: %lu", status
);
1895 status
= FT_ListDevices(&num_devices
, NULL
, FT_LIST_NUMBER_ONLY
);
1896 if (status
== FT_OK
)
1898 char** desc_array
= malloc(sizeof(char*) * (num_devices
+ 1));
1901 for (i
= 0; i
< num_devices
; i
++)
1902 desc_array
[i
] = malloc(64);
1904 desc_array
[num_devices
] = NULL
;
1906 status
= FT_ListDevices(desc_array
, &num_devices
, FT_LIST_ALL
| openex_flags
);
1908 if (status
== FT_OK
)
1910 LOG_ERROR("ListDevices: %lu\n", num_devices
);
1911 for (i
= 0; i
< num_devices
; i
++)
1912 LOG_ERROR("%" PRIu32
": \"%s\"", i
, desc_array
[i
]);
1915 for (i
= 0; i
< num_devices
; i
++)
1916 free(desc_array
[i
]);
1922 LOG_ERROR("ListDevices: NONE\n");
1924 return ERROR_JTAG_INIT_FAILED
;
1927 if ((status
= FT_SetLatencyTimer(ftdih
, ft2232_latency
)) != FT_OK
)
1929 LOG_ERROR("unable to set latency timer: %lu", status
);
1930 return ERROR_JTAG_INIT_FAILED
;
1933 if ((status
= FT_GetLatencyTimer(ftdih
, &latency_timer
)) != FT_OK
)
1935 LOG_ERROR("unable to get latency timer: %lu", status
);
1936 return ERROR_JTAG_INIT_FAILED
;
1940 LOG_DEBUG("current latency timer: %i", latency_timer
);
1943 if ((status
= FT_SetTimeouts(ftdih
, 5000, 5000)) != FT_OK
)
1945 LOG_ERROR("unable to set timeouts: %lu", status
);
1946 return ERROR_JTAG_INIT_FAILED
;
1949 if ((status
= FT_SetBitMode(ftdih
, 0x0b, 2)) != FT_OK
)
1951 LOG_ERROR("unable to enable bit i/o mode: %lu", status
);
1952 return ERROR_JTAG_INIT_FAILED
;
1955 if ((status
= FT_GetDeviceInfo(ftdih
, &ftdi_device
, &deviceID
, SerialNumber
, Description
, NULL
)) != FT_OK
)
1957 LOG_ERROR("unable to get FT_GetDeviceInfo: %lu", status
);
1958 return ERROR_JTAG_INIT_FAILED
;
1962 static const char* type_str
[] =
1963 {"BM", "AM", "100AX", "UNKNOWN", "2232C", "232R", "2232H", "4232H"};
1964 unsigned no_of_known_types
= sizeof(type_str
) / sizeof(type_str
[0]) - 1;
1965 unsigned type_index
= ((unsigned)ftdi_device
<= no_of_known_types
)
1966 ? ftdi_device
: FT_DEVICE_UNKNOWN
;
1967 LOG_INFO("device: %lu \"%s\"", ftdi_device
, type_str
[type_index
]);
1968 LOG_INFO("deviceID: %lu", deviceID
);
1969 LOG_INFO("SerialNumber: %s", SerialNumber
);
1970 LOG_INFO("Description: %s", Description
);
1976 static int ft2232_purge_ftd2xx(void)
1980 if ((status
= FT_Purge(ftdih
, FT_PURGE_RX
| FT_PURGE_TX
)) != FT_OK
)
1982 LOG_ERROR("error purging ftd2xx device: %lu", status
);
1983 return ERROR_JTAG_INIT_FAILED
;
1989 #endif /* BUILD_FT2232_FTD2XX == 1 */
1991 #if BUILD_FT2232_LIBFTDI == 1
1992 static int ft2232_init_libftdi(uint16_t vid
, uint16_t pid
, int more
, int* try_more
)
1994 uint8_t latency_timer
;
1996 LOG_DEBUG("'ft2232' interface using libftdi with '%s' layout (%4.4x:%4.4x)",
1997 ft2232_layout
, vid
, pid
);
1999 if (ftdi_init(&ftdic
) < 0)
2000 return ERROR_JTAG_INIT_FAILED
;
2002 if (ftdi_set_interface(&ftdic
, INTERFACE_A
) < 0)
2004 LOG_ERROR("unable to select FT2232 channel A: %s", ftdic
.error_str
);
2005 return ERROR_JTAG_INIT_FAILED
;
2008 /* context, vendor id, product id */
2009 if (ftdi_usb_open_desc(&ftdic
, vid
, pid
, ft2232_device_desc
,
2013 LOG_WARNING("unable to open ftdi device (trying more): %s",
2016 LOG_ERROR("unable to open ftdi device: %s", ftdic
.error_str
);
2018 return ERROR_JTAG_INIT_FAILED
;
2021 /* There is already a reset in ftdi_usb_open_desc, this should be redundant */
2022 if (ftdi_usb_reset(&ftdic
) < 0)
2024 LOG_ERROR("unable to reset ftdi device");
2025 return ERROR_JTAG_INIT_FAILED
;
2028 if (ftdi_set_latency_timer(&ftdic
, ft2232_latency
) < 0)
2030 LOG_ERROR("unable to set latency timer");
2031 return ERROR_JTAG_INIT_FAILED
;
2034 if (ftdi_get_latency_timer(&ftdic
, &latency_timer
) < 0)
2036 LOG_ERROR("unable to get latency timer");
2037 return ERROR_JTAG_INIT_FAILED
;
2041 LOG_DEBUG("current latency timer: %i", latency_timer
);
2044 ftdi_set_bitmode(&ftdic
, 0x0b, 2); /* ctx, JTAG I/O mask */
2046 ftdi_device
= ftdic
.type
;
2047 static const char* type_str
[] =
2048 {"AM", "BM", "2232C", "R", "2232H", "4232H", "Unknown"};
2049 unsigned no_of_known_types
= sizeof(type_str
) / sizeof(type_str
[0]) - 1;
2050 unsigned type_index
= ((unsigned)ftdi_device
< no_of_known_types
)
2051 ? ftdi_device
: no_of_known_types
;
2052 LOG_DEBUG("FTDI chip type: %i \"%s\"", (int)ftdi_device
, type_str
[type_index
]);
2056 static int ft2232_purge_libftdi(void)
2058 if (ftdi_usb_purge_buffers(&ftdic
) < 0)
2060 LOG_ERROR("ftdi_purge_buffers: %s", ftdic
.error_str
);
2061 return ERROR_JTAG_INIT_FAILED
;
2067 #endif /* BUILD_FT2232_LIBFTDI == 1 */
2069 static int ft2232_init(void)
2073 uint32_t bytes_written
;
2074 const ft2232_layout_t
* cur_layout
= ft2232_layouts
;
2077 if (tap_get_tms_path_len(TAP_IRPAUSE
,TAP_IRPAUSE
) == 7)
2079 LOG_DEBUG("ft2232 interface using 7 step jtag state transitions");
2083 LOG_DEBUG("ft2232 interface using shortest path jtag state transitions");
2086 if ((ft2232_layout
== NULL
) || (ft2232_layout
[0] == 0))
2088 ft2232_layout
= "usbjtag";
2089 LOG_WARNING("No ft2232 layout specified, using default 'usbjtag'");
2092 while (cur_layout
->name
)
2094 if (strcmp(cur_layout
->name
, ft2232_layout
) == 0)
2096 layout
= cur_layout
;
2104 LOG_ERROR("No matching layout found for %s", ft2232_layout
);
2105 return ERROR_JTAG_INIT_FAILED
;
2111 * "more indicates that there are more IDs to try, so we should
2112 * not print an error for an ID mismatch (but for anything
2115 * try_more indicates that the error code returned indicates an
2116 * ID mismatch (and nothing else) and that we should proceeed
2117 * with the next ID pair.
2119 int more
= ft2232_vid
[i
+ 1] || ft2232_pid
[i
+ 1];
2122 #if BUILD_FT2232_FTD2XX == 1
2123 retval
= ft2232_init_ftd2xx(ft2232_vid
[i
], ft2232_pid
[i
],
2125 #elif BUILD_FT2232_LIBFTDI == 1
2126 retval
= ft2232_init_libftdi(ft2232_vid
[i
], ft2232_pid
[i
],
2131 if (!more
|| !try_more
)
2135 ft2232_buffer_size
= 0;
2136 ft2232_buffer
= malloc(FT2232_BUFFER_SIZE
);
2138 if (layout
->init() != ERROR_OK
)
2139 return ERROR_JTAG_INIT_FAILED
;
2141 if (ft2232_device_is_highspeed())
2143 #ifndef BUILD_FT2232_HIGHSPEED
2144 #if BUILD_FT2232_FTD2XX == 1
2145 LOG_WARNING("High Speed device found - You need a newer FTD2XX driver (version 2.04.16 or later)");
2146 #elif BUILD_FT2232_LIBFTDI == 1
2147 LOG_WARNING("High Speed device found - You need a newer libftdi version (0.16 or later)");
2150 /* make sure the legacy mode is disabled */
2151 if (ft2232h_ft4232h_clk_divide_by_5(false) != ERROR_OK
)
2152 return ERROR_JTAG_INIT_FAILED
;
2155 ft2232_speed(jtag_get_speed());
2157 buf
[0] = 0x85; /* Disconnect TDI/DO to TDO/DI for Loopback */
2158 if (((retval
= ft2232_write(buf
, 1, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 1))
2160 LOG_ERROR("couldn't write to FT2232 to disable loopback");
2161 return ERROR_JTAG_INIT_FAILED
;
2164 #if BUILD_FT2232_FTD2XX == 1
2165 return ft2232_purge_ftd2xx();
2166 #elif BUILD_FT2232_LIBFTDI == 1
2167 return ft2232_purge_libftdi();
2173 static int usbjtag_init(void)
2176 uint32_t bytes_written
;
2179 low_direction
= 0x0b;
2181 if (strcmp(ft2232_layout
, "usbjtag") == 0)
2188 else if (strcmp(ft2232_layout
, "signalyzer") == 0)
2195 else if (strcmp(ft2232_layout
, "evb_lm3s811") == 0)
2202 low_direction
= 0x8b;
2204 else if (strcmp(ft2232_layout
, "luminary_icdi") == 0)
2211 low_direction
= 0xcb;
2215 LOG_ERROR("BUG: usbjtag_init called for unknown layout '%s'", ft2232_layout
);
2216 return ERROR_JTAG_INIT_FAILED
;
2219 enum reset_types jtag_reset_config
= jtag_get_reset_config();
2220 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
2222 low_direction
&= ~nTRSTnOE
; /* nTRST input */
2223 low_output
&= ~nTRST
; /* nTRST = 0 */
2227 low_direction
|= nTRSTnOE
; /* nTRST output */
2228 low_output
|= nTRST
; /* nTRST = 1 */
2231 if (jtag_reset_config
& RESET_SRST_PUSH_PULL
)
2233 low_direction
|= nSRSTnOE
; /* nSRST output */
2234 low_output
|= nSRST
; /* nSRST = 1 */
2238 low_direction
&= ~nSRSTnOE
; /* nSRST input */
2239 low_output
&= ~nSRST
; /* nSRST = 0 */
2242 /* initialize low byte for jtag */
2243 buf
[0] = 0x80; /* command "set data bits low byte" */
2244 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, xRST high) */
2245 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in */
2246 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2248 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2250 LOG_ERROR("couldn't initialize FT2232 with 'USBJTAG' layout");
2251 return ERROR_JTAG_INIT_FAILED
;
2257 static int axm0432_jtag_init(void)
2260 uint32_t bytes_written
;
2263 low_direction
= 0x2b;
2265 /* initialize low byte for jtag */
2266 buf
[0] = 0x80; /* command "set data bits low byte" */
2267 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2268 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in, nOE = out */
2269 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2271 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2273 LOG_ERROR("couldn't initialize FT2232 with 'JTAGkey' layout");
2274 return ERROR_JTAG_INIT_FAILED
;
2277 if (strcmp(layout
->name
, "axm0432_jtag") == 0)
2280 nTRSTnOE
= 0x0; /* No output enable for TRST*/
2282 nSRSTnOE
= 0x0; /* No output enable for SRST*/
2286 LOG_ERROR("BUG: axm0432_jtag_init called for non axm0432 layout");
2291 high_direction
= 0x0c;
2293 enum reset_types jtag_reset_config
= jtag_get_reset_config();
2294 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
2296 LOG_ERROR("can't set nTRSTOE to push-pull on the Dicarlo jtag");
2300 high_output
|= nTRST
;
2303 if (jtag_reset_config
& RESET_SRST_PUSH_PULL
)
2305 LOG_ERROR("can't set nSRST to push-pull on the Dicarlo jtag");
2309 high_output
|= nSRST
;
2312 /* initialize high port */
2313 buf
[0] = 0x82; /* command "set data bits high byte" */
2314 buf
[1] = high_output
; /* value */
2315 buf
[2] = high_direction
; /* all outputs (xRST and xRSTnOE) */
2316 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2318 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2320 LOG_ERROR("couldn't initialize FT2232 with 'Dicarlo' layout");
2321 return ERROR_JTAG_INIT_FAILED
;
2327 static int jtagkey_init(void)
2330 uint32_t bytes_written
;
2333 low_direction
= 0x1b;
2335 /* initialize low byte for jtag */
2336 buf
[0] = 0x80; /* command "set data bits low byte" */
2337 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2338 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in, nOE = out */
2339 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2341 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2343 LOG_ERROR("couldn't initialize FT2232 with 'JTAGkey' layout");
2344 return ERROR_JTAG_INIT_FAILED
;
2347 if (strcmp(layout
->name
, "jtagkey") == 0)
2354 else if ((strcmp(layout
->name
, "jtagkey_prototype_v1") == 0)
2355 || (strcmp(layout
->name
, "oocdlink") == 0))
2364 LOG_ERROR("BUG: jtagkey_init called for non jtagkey layout");
2369 high_direction
= 0x0f;
2371 enum reset_types jtag_reset_config
= jtag_get_reset_config();
2372 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
2374 high_output
|= nTRSTnOE
;
2375 high_output
&= ~nTRST
;
2379 high_output
&= ~nTRSTnOE
;
2380 high_output
|= nTRST
;
2383 if (jtag_reset_config
& RESET_SRST_PUSH_PULL
)
2385 high_output
&= ~nSRSTnOE
;
2386 high_output
|= nSRST
;
2390 high_output
|= nSRSTnOE
;
2391 high_output
&= ~nSRST
;
2394 /* initialize high port */
2395 buf
[0] = 0x82; /* command "set data bits high byte" */
2396 buf
[1] = high_output
; /* value */
2397 buf
[2] = high_direction
; /* all outputs (xRST and xRSTnOE) */
2398 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2400 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2402 LOG_ERROR("couldn't initialize FT2232 with 'JTAGkey' layout");
2403 return ERROR_JTAG_INIT_FAILED
;
2409 static int olimex_jtag_init(void)
2412 uint32_t bytes_written
;
2415 low_direction
= 0x1b;
2417 /* initialize low byte for jtag */
2418 buf
[0] = 0x80; /* command "set data bits low byte" */
2419 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2420 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in, nOE = out */
2421 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2423 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2425 LOG_ERROR("couldn't initialize FT2232 with 'Olimex' layout");
2426 return ERROR_JTAG_INIT_FAILED
;
2432 nSRSTnOE
= 0x00; /* no output enable for nSRST */
2435 high_direction
= 0x0f;
2437 enum reset_types jtag_reset_config
= jtag_get_reset_config();
2438 if (jtag_reset_config
& RESET_TRST_OPEN_DRAIN
)
2440 high_output
|= nTRSTnOE
;
2441 high_output
&= ~nTRST
;
2445 high_output
&= ~nTRSTnOE
;
2446 high_output
|= nTRST
;
2449 if (jtag_reset_config
& RESET_SRST_PUSH_PULL
)
2451 LOG_ERROR("can't set nSRST to push-pull on the Olimex ARM-USB-OCD");
2455 high_output
&= ~nSRST
;
2458 /* turn red LED on */
2459 high_output
|= 0x08;
2461 /* initialize high port */
2462 buf
[0] = 0x82; /* command "set data bits high byte" */
2463 buf
[1] = high_output
; /* value */
2464 buf
[2] = high_direction
; /* all outputs (xRST and xRSTnOE) */
2465 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2467 if ((ft2232_write(buf
, 3, &bytes_written
) != ERROR_OK
) || (bytes_written
!= 3))
2469 LOG_ERROR("couldn't initialize FT2232 with 'Olimex' layout");
2470 return ERROR_JTAG_INIT_FAILED
;
2476 static int flyswatter_init(void)
2479 uint32_t bytes_written
;
2482 low_direction
= 0xfb;
2484 /* initialize low byte for jtag */
2485 buf
[0] = 0x80; /* command "set data bits low byte" */
2486 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2487 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in, nOE[12]=out, n[ST]srst = out */
2488 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2490 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2492 LOG_ERROR("couldn't initialize FT2232 with 'flyswatter' layout");
2493 return ERROR_JTAG_INIT_FAILED
;
2497 nTRSTnOE
= 0x0; /* not output enable for nTRST */
2499 nSRSTnOE
= 0x00; /* no output enable for nSRST */
2502 high_direction
= 0x0c;
2504 /* turn red LED3 on, LED2 off */
2505 high_output
|= 0x08;
2507 /* initialize high port */
2508 buf
[0] = 0x82; /* command "set data bits high byte" */
2509 buf
[1] = high_output
; /* value */
2510 buf
[2] = high_direction
; /* all outputs (xRST and xRSTnOE) */
2511 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2513 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2515 LOG_ERROR("couldn't initialize FT2232 with 'flyswatter' layout");
2516 return ERROR_JTAG_INIT_FAILED
;
2522 static int turtle_init(void)
2525 uint32_t bytes_written
;
2528 low_direction
= 0x5b;
2530 /* initialize low byte for jtag */
2531 buf
[0] = 0x80; /* command "set data bits low byte" */
2532 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2533 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in, nOE = out */
2534 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2536 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2538 LOG_ERROR("couldn't initialize FT2232 with 'turtelizer2' layout");
2539 return ERROR_JTAG_INIT_FAILED
;
2545 high_direction
= 0x0C;
2547 /* initialize high port */
2548 buf
[0] = 0x82; /* command "set data bits high byte" */
2549 buf
[1] = high_output
;
2550 buf
[2] = high_direction
;
2551 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2553 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2555 LOG_ERROR("couldn't initialize FT2232 with 'turtelizer2' layout");
2556 return ERROR_JTAG_INIT_FAILED
;
2562 static int comstick_init(void)
2565 uint32_t bytes_written
;
2568 low_direction
= 0x0b;
2570 /* initialize low byte for jtag */
2571 buf
[0] = 0x80; /* command "set data bits low byte" */
2572 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2573 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in, nOE = out */
2574 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2576 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2578 LOG_ERROR("couldn't initialize FT2232 with 'comstick' layout");
2579 return ERROR_JTAG_INIT_FAILED
;
2583 nTRSTnOE
= 0x00; /* no output enable for nTRST */
2585 nSRSTnOE
= 0x00; /* no output enable for nSRST */
2588 high_direction
= 0x03;
2590 /* initialize high port */
2591 buf
[0] = 0x82; /* command "set data bits high byte" */
2592 buf
[1] = high_output
;
2593 buf
[2] = high_direction
;
2594 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2596 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2598 LOG_ERROR("couldn't initialize FT2232 with 'comstick' layout");
2599 return ERROR_JTAG_INIT_FAILED
;
2605 static int stm32stick_init(void)
2608 uint32_t bytes_written
;
2611 low_direction
= 0x8b;
2613 /* initialize low byte for jtag */
2614 buf
[0] = 0x80; /* command "set data bits low byte" */
2615 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2616 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in, nOE = out */
2617 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2619 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2621 LOG_ERROR("couldn't initialize FT2232 with 'stm32stick' layout");
2622 return ERROR_JTAG_INIT_FAILED
;
2626 nTRSTnOE
= 0x00; /* no output enable for nTRST */
2628 nSRSTnOE
= 0x00; /* no output enable for nSRST */
2631 high_direction
= 0x03;
2633 /* initialize high port */
2634 buf
[0] = 0x82; /* command "set data bits high byte" */
2635 buf
[1] = high_output
;
2636 buf
[2] = high_direction
;
2637 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2639 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2641 LOG_ERROR("couldn't initialize FT2232 with 'stm32stick' layout");
2642 return ERROR_JTAG_INIT_FAILED
;
2648 static int sheevaplug_init(void)
2651 uint32_t bytes_written
;
2654 low_direction
= 0x1b;
2656 /* initialize low byte for jtag */
2657 buf
[0] = 0x80; /* command "set data bits low byte" */
2658 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2659 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in */
2660 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2662 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2664 LOG_ERROR("couldn't initialize FT2232 with 'sheevaplug' layout");
2665 return ERROR_JTAG_INIT_FAILED
;
2674 high_direction
= 0x0f;
2676 /* nTRST is always push-pull */
2677 high_output
&= ~nTRSTnOE
;
2678 high_output
|= nTRST
;
2680 /* nSRST is always open-drain */
2681 high_output
|= nSRSTnOE
;
2682 high_output
&= ~nSRST
;
2684 /* initialize high port */
2685 buf
[0] = 0x82; /* command "set data bits high byte" */
2686 buf
[1] = high_output
; /* value */
2687 buf
[2] = high_direction
; /* all outputs - xRST */
2688 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2690 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2692 LOG_ERROR("couldn't initialize FT2232 with 'sheevaplug' layout");
2693 return ERROR_JTAG_INIT_FAILED
;
2699 static int cortino_jtag_init(void)
2702 uint32_t bytes_written
;
2705 low_direction
= 0x1b;
2707 /* initialize low byte for jtag */
2708 buf
[0] = 0x80; /* command "set data bits low byte" */
2709 buf
[1] = low_output
; /* value (TMS = 1,TCK = 0, TDI = 0, nOE = 0) */
2710 buf
[2] = low_direction
; /* dir (output = 1), TCK/TDI/TMS = out, TDO = in, nOE = out */
2711 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2713 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2715 LOG_ERROR("couldn't initialize FT2232 with 'cortino' layout");
2716 return ERROR_JTAG_INIT_FAILED
;
2720 nTRSTnOE
= 0x00; /* no output enable for nTRST */
2722 nSRSTnOE
= 0x00; /* no output enable for nSRST */
2725 high_direction
= 0x03;
2727 /* initialize high port */
2728 buf
[0] = 0x82; /* command "set data bits high byte" */
2729 buf
[1] = high_output
;
2730 buf
[2] = high_direction
;
2731 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
2733 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3))
2735 LOG_ERROR("couldn't initialize FT2232 with 'stm32stick' layout");
2736 return ERROR_JTAG_INIT_FAILED
;
2742 static void olimex_jtag_blink(void)
2744 /* Olimex ARM-USB-OCD has a LED connected to ACBUS3
2745 * ACBUS3 is bit 3 of the GPIOH port
2747 if (high_output
& 0x08)
2749 /* set port pin high */
2750 high_output
&= 0x07;
2754 /* set port pin low */
2755 high_output
|= 0x08;
2759 buffer_write(high_output
);
2760 buffer_write(high_direction
);
2763 static void flyswatter_jtag_blink(void)
2766 * Flyswatter has two LEDs connected to ACBUS2 and ACBUS3
2768 high_output
^= 0x0c;
2771 buffer_write(high_output
);
2772 buffer_write(high_direction
);
2775 static void turtle_jtag_blink(void)
2778 * Turtelizer2 has two LEDs connected to ACBUS2 and ACBUS3
2780 if (high_output
& 0x08)
2790 buffer_write(high_output
);
2791 buffer_write(high_direction
);
2794 static int ft2232_quit(void)
2796 #if BUILD_FT2232_FTD2XX == 1
2799 status
= FT_Close(ftdih
);
2800 #elif BUILD_FT2232_LIBFTDI == 1
2801 ftdi_usb_close(&ftdic
);
2803 ftdi_deinit(&ftdic
);
2806 free(ft2232_buffer
);
2807 ft2232_buffer
= NULL
;
2812 static int ft2232_handle_device_desc_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
)
2818 ft2232_device_desc
= strdup(args
[0]);
2819 cp
= strchr(ft2232_device_desc
, 0);
2820 /* under Win32, the FTD2XX driver appends an "A" to the end
2821 * of the description, this examines the given desc
2822 * and creates the 'missing' _A or non_A variable. */
2823 if ((cp
[-1] == 'A') && (cp
[-2]==' ')) {
2824 /* it was, so make this the "A" version. */
2825 ft2232_device_desc_A
= ft2232_device_desc
;
2826 /* and *CREATE* the non-A version. */
2827 strcpy(buf
, ft2232_device_desc
);
2828 cp
= strchr(buf
, 0);
2830 ft2232_device_desc
= strdup(buf
);
2832 /* <space > A not defined
2834 sprintf(buf
, "%s A", ft2232_device_desc
);
2835 ft2232_device_desc_A
= strdup(buf
);
2840 LOG_ERROR("expected exactly one argument to ft2232_device_desc <description>");
2846 static int ft2232_handle_serial_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
)
2850 ft2232_serial
= strdup(args
[0]);
2854 LOG_ERROR("expected exactly one argument to ft2232_serial <serial-number>");
2860 static int ft2232_handle_layout_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
)
2865 ft2232_layout
= malloc(strlen(args
[0]) + 1);
2866 strcpy(ft2232_layout
, args
[0]);
2871 static int ft2232_handle_vid_pid_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
)
2873 if (argc
> MAX_USB_IDS
* 2)
2875 LOG_WARNING("ignoring extra IDs in ft2232_vid_pid "
2876 "(maximum is %d pairs)", MAX_USB_IDS
);
2877 argc
= MAX_USB_IDS
* 2;
2879 if (argc
< 2 || (argc
& 1))
2881 LOG_WARNING("incomplete ft2232_vid_pid configuration directive");
2883 return ERROR_COMMAND_SYNTAX_ERROR
;
2884 /* remove the incomplete trailing id */
2889 int retval
= ERROR_OK
;
2890 for (i
= 0; i
< argc
; i
+= 2)
2892 retval
= parse_u16(args
[i
], &ft2232_vid
[i
>> 1]);
2893 if (ERROR_OK
!= retval
)
2895 retval
= parse_u16(args
[i
+ 1], &ft2232_pid
[i
>> 1]);
2896 if (ERROR_OK
!= retval
)
2901 * Explicitly terminate, in case there are multiples instances of
2904 ft2232_vid
[i
>> 1] = ft2232_pid
[i
>> 1] = 0;
2909 static int ft2232_handle_latency_command(struct command_context_s
* cmd_ctx
, char* cmd
, char** args
, int argc
)
2913 ft2232_latency
= atoi(args
[0]);
2917 LOG_ERROR("expected exactly one argument to ft2232_latency <ms>");
2923 static int ft2232_stableclocks(int num_cycles
, jtag_command_t
* cmd
)
2927 /* 7 bits of either ones or zeros. */
2928 uint8_t tms
= (tap_get_state() == TAP_RESET
? 0x7F : 0x00);
2930 while (num_cycles
> 0)
2932 /* the command 0x4b, "Clock Data to TMS/CS Pin (no Read)" handles
2933 * at most 7 bits per invocation. Here we invoke it potentially
2936 int bitcount_per_command
= (num_cycles
> 7) ? 7 : num_cycles
;
2938 if (ft2232_buffer_size
+ 3 >= FT2232_BUFFER_SIZE
)
2940 if (ft2232_send_and_recv(first_unsent
, cmd
) != ERROR_OK
)
2941 retval
= ERROR_JTAG_QUEUE_FAILED
;
2946 /* there are no state transitions in this code, so omit state tracking */
2948 /* command "Clock Data to TMS/CS Pin (no Read)" */
2952 buffer_write(bitcount_per_command
- 1);
2954 /* TMS data bits are either all zeros or ones to stay in the current stable state */
2959 num_cycles
-= bitcount_per_command
;
2965 /* ---------------------------------------------------------------------
2966 * Support for IceBear JTAG adapter from Section5:
2967 * http://section5.ch/icebear
2969 * Author: Sten, debian@sansys-electronic.com
2972 /* Icebear pin layout
2974 * ADBUS5 (nEMU) nSRST | 2 1| GND (10k->VCC)
2975 * GND GND | 4 3| n.c.
2976 * ADBUS3 TMS | 6 5| ADBUS6 VCC
2977 * ADBUS0 TCK | 8 7| ADBUS7 (GND)
2978 * ADBUS4 nTRST |10 9| ACBUS0 (GND)
2979 * ADBUS1 TDI |12 11| ACBUS1 (GND)
2980 * ADBUS2 TDO |14 13| GND GND
2982 * ADBUS0 O L TCK ACBUS0 GND
2983 * ADBUS1 O L TDI ACBUS1 GND
2984 * ADBUS2 I TDO ACBUS2 n.c.
2985 * ADBUS3 O H TMS ACBUS3 n.c.
2991 static int icebear_jtag_init(void) {
2993 uint32_t bytes_written
;
2995 low_direction
= 0x0b; /* output: TCK TDI TMS; input: TDO */
2996 low_output
= 0x08; /* high: TMS; low: TCK TDI */
3000 enum reset_types jtag_reset_config
= jtag_get_reset_config();
3001 if ((jtag_reset_config
& RESET_TRST_OPEN_DRAIN
) != 0) {
3002 low_direction
&= ~nTRST
; /* nTRST high impedance */
3005 low_direction
|= nTRST
;
3006 low_output
|= nTRST
;
3009 low_direction
|= nSRST
;
3010 low_output
|= nSRST
;
3012 /* initialize low byte for jtag */
3013 buf
[0] = 0x80; /* command "set data bits low byte" */
3014 buf
[1] = low_output
;
3015 buf
[2] = low_direction
;
3016 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
3018 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3)) {
3019 LOG_ERROR("couldn't initialize FT2232 with 'IceBear' layout (low)");
3020 return ERROR_JTAG_INIT_FAILED
;
3024 high_direction
= 0x00;
3027 /* initialize high port */
3028 buf
[0] = 0x82; /* command "set data bits high byte" */
3029 buf
[1] = high_output
; /* value */
3030 buf
[2] = high_direction
; /* all outputs (xRST and xRSTnOE) */
3031 LOG_DEBUG("%2.2x %2.2x %2.2x", buf
[0], buf
[1], buf
[2]);
3033 if (((ft2232_write(buf
, 3, &bytes_written
)) != ERROR_OK
) || (bytes_written
!= 3)) {
3034 LOG_ERROR("couldn't initialize FT2232 with 'IceBear' layout (high)");
3035 return ERROR_JTAG_INIT_FAILED
;
3041 static void icebear_jtag_reset(int trst
, int srst
) {
3044 low_direction
|= nTRST
;
3045 low_output
&= ~nTRST
;
3047 else if (trst
== 0) {
3048 enum reset_types jtag_reset_config
= jtag_get_reset_config();
3049 if ((jtag_reset_config
& RESET_TRST_OPEN_DRAIN
) != 0)
3050 low_direction
&= ~nTRST
;
3052 low_output
|= nTRST
;
3056 low_output
&= ~nSRST
;
3058 else if (srst
== 0) {
3059 low_output
|= nSRST
;
3062 /* command "set data bits low byte" */
3064 buffer_write(low_output
);
3065 buffer_write(low_direction
);
3067 LOG_DEBUG("trst: %i, srst: %i, low_output: 0x%2.2x, low_direction: 0x%2.2x", trst
, srst
, low_output
, low_direction
);
Linking to existing account procedure
If you already have an account and want to add another login method
you
MUST first sign in with your existing account and
then change URL to read
https://review.openocd.org/login/?link
to get to this page again but this time it'll work for linking. Thank you.
SSH host keys fingerprints
1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=.. |
|+o.. . |
|*.o . . |
|+B . . . |
|Bo. = o S |
|Oo.+ + = |
|oB=.* = . o |
| =+=.+ + E |
|. .=o . o |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)