1 /***************************************************************************
2 * Copyright (C) 2011 by Martin Schmoelzer *
3 * <martin.schmoelzer@student.tuwien.ac.at> *
5 * This program is free software; you can redistribute it and/or modify *
6 * it under the terms of the GNU General Public License as published by *
7 * the Free Software Foundation; either version 2 of the License, or *
8 * (at your option) any later version. *
10 * This program is distributed in the hope that it will be useful, *
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
13 * GNU General Public License for more details. *
15 * You should have received a copy of the GNU General Public License *
16 * along with this program; if not, write to the *
17 * Free Software Foundation, Inc., *
18 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
19 ***************************************************************************/
25 #include <jtag/interface.h>
26 #include <jtag/commands.h>
27 #include <target/image.h>
28 #include <helper/types.h>
29 #include "usb_common.h"
30 #include "OpenULINK/include/msgtypes.h"
32 /** USB Vendor ID of ULINK device in unconfigured state (no firmware loaded
33 * yet) or with OpenULINK firmware. */
34 #define ULINK_VID 0xC251
36 /** USB Product ID of ULINK device in unconfigured state (no firmware loaded
37 * yet) or with OpenULINK firmware. */
38 #define ULINK_PID 0x2710
40 /** Address of EZ-USB CPU Control & Status register. This register can be
41 * written by issuing a Control EP0 vendor request. */
42 #define CPUCS_REG 0x7F92
44 /** USB Control EP0 bRequest: "Firmware Load". */
45 #define REQUEST_FIRMWARE_LOAD 0xA0
47 /** Value to write into CPUCS to put EZ-USB into reset. */
48 #define CPU_RESET 0x01
50 /** Value to write into CPUCS to put EZ-USB out of reset. */
51 #define CPU_START 0x00
53 /** Base address of firmware in EZ-USB code space. */
54 #define FIRMWARE_ADDR 0x0000
56 /** USB interface number */
57 #define USB_INTERFACE 0
59 /** libusb timeout in ms */
60 #define USB_TIMEOUT 5000
62 /** Delay (in microseconds) to wait while EZ-USB performs ReNumeration. */
63 #define ULINK_RENUMERATION_DELAY 1500000
65 /** Default location of OpenULINK firmware image. */
66 #define ULINK_FIRMWARE_FILE PKGLIBDIR "/OpenULINK/ulink_firmware.hex"
68 /** Maximum size of a single firmware section. Entire EZ-USB code space = 8kB */
69 #define SECTION_BUFFERSIZE 8192
71 /** Tuning of OpenOCD SCAN commands split into multiple OpenULINK commands. */
72 #define SPLIT_SCAN_THRESHOLD 10
74 /** ULINK hardware type */
77 /** Original ULINK adapter, based on Cypress EZ-USB (AN2131):
78 * Full JTAG support, no SWD support. */
81 /** Newer ULINK adapter, based on NXP LPC2148. Currently unsupported. */
84 /** Newer ULINK adapter, based on EZ-USB FX2 + FPGA. Currently unsupported. */
87 /** Newer ULINK adapter, possibly based on ULINK 2. Currently unsupported. */
91 enum ulink_payload_direction
93 PAYLOAD_DIRECTION_OUT
,
98 * OpenULINK command (OpenULINK command queue element).
100 * For the OUT direction payload, things are quite easy: Payload is stored
101 * in a rather small array (up to 63 bytes), the payload is always allocated
102 * by the function generating the command and freed by ulink_clear_queue().
104 * For the IN direction payload, things get a little bit more complicated:
105 * The maximum IN payload size for a single command is 64 bytes. Assume that
106 * a single OpenOCD command needs to scan 256 bytes. This results in the
107 * generation of four OpenULINK commands. The function generating these
108 * commands shall allocate an uint8_t[256] array. Each command's #payload_in
109 * pointer shall point to the corresponding offset where IN data shall be
110 * placed, while #payload_in_start shall point to the first element of the 256
112 * - first command: #payload_in_start + 0
113 * - second command: #payload_in_start + 64
114 * - third command: #payload_in_start + 128
115 * - fourth command: #payload_in_start + 192
117 * The last command sets #needs_postprocessing to true.
120 uint8_t id
; ///< ULINK command ID
122 uint8_t *payload_out
; ///< OUT direction payload data
123 uint8_t payload_out_size
; ///< OUT direction payload size for this command
125 uint8_t *payload_in_start
; ///< Pointer to first element of IN payload array
126 uint8_t *payload_in
; ///< Pointer where IN payload shall be stored
127 uint8_t payload_in_size
; ///< IN direction payload size for this command
129 /** Indicates if this command needs post-processing */
130 bool needs_postprocessing
;
132 /** Indicates if ulink_clear_queue() should free payload_in_start */
133 bool free_payload_in_start
;
135 /** Pointer to corresponding OpenOCD command for post-processing */
136 struct jtag_command
*cmd_origin
;
138 struct ulink_cmd
*next
; ///< Pointer to next command (linked list)
141 typedef struct ulink_cmd ulink_cmd_t
;
143 /** Describes one driver instance */
146 struct usb_dev_handle
*usb_handle
;
147 enum ulink_type type
;
149 int commands_in_queue
; ///< Number of commands in queue
150 ulink_cmd_t
*queue_start
; ///< Pointer to first command in queue
151 ulink_cmd_t
*queue_end
; ///< Pointer to last command in queue
154 /**************************** Function Prototypes *****************************/
156 /* USB helper functions */
157 int ulink_usb_open(struct ulink
**device
);
158 int ulink_usb_close(struct ulink
**device
);
160 /* ULINK MCU (Cypress EZ-USB) specific functions */
161 int ulink_cpu_reset(struct ulink
*device
, char reset_bit
);
162 int ulink_load_firmware_and_renumerate(struct ulink
**device
, char *filename
,
164 int ulink_load_firmware(struct ulink
*device
, char *filename
);
165 int ulink_write_firmware_section(struct ulink
*device
,
166 struct image
*firmware_image
, int section_index
);
168 /* Generic helper functions */
169 void ulink_print_signal_states(uint8_t input_signals
, uint8_t output_signals
);
171 /* OpenULINK command generation helper functions */
172 int ulink_allocate_payload(ulink_cmd_t
*ulink_cmd
, int size
,
173 enum ulink_payload_direction direction
);
175 /* OpenULINK command queue helper functions */
176 int ulink_get_queue_size(struct ulink
*device
,
177 enum ulink_payload_direction direction
);
178 void ulink_clear_queue(struct ulink
*device
);
179 int ulink_append_queue(struct ulink
*device
, ulink_cmd_t
*ulink_cmd
);
180 int ulink_execute_queued_commands(struct ulink
*device
, int timeout
);
182 #ifdef _DEBUG_JTAG_IO_
183 const char * ulink_cmd_id_string(uint8_t id
);
184 void ulink_print_command(ulink_cmd_t
*ulink_cmd
);
185 void ulink_print_queue(struct ulink
*device
);
188 int ulink_append_scan_cmd(struct ulink
*device
, enum scan_type scan_type
,
189 int scan_size_bits
, uint8_t *tdi
, uint8_t *tdo_start
, uint8_t *tdo
,
190 uint8_t tms_count_start
, uint8_t tms_sequence_start
, uint8_t tms_count_end
,
191 uint8_t tms_sequence_end
, struct jtag_command
*origin
, bool postprocess
);
192 int ulink_append_clock_tms_cmd(struct ulink
*device
, uint8_t count
,
194 int ulink_append_clock_tck_cmd(struct ulink
*device
, uint16_t count
);
195 int ulink_append_get_signals_cmd(struct ulink
*device
);
196 int ulink_append_set_signals_cmd(struct ulink
*device
, uint8_t low
,
198 int ulink_append_sleep_cmd(struct ulink
*device
, uint32_t us
);
199 int ulink_append_configure_tck_cmd(struct ulink
*device
, uint8_t delay_scan
,
200 uint8_t delay_tck
, uint8_t delay_tms
);
201 int ulink_append_led_cmd(struct ulink
*device
, uint8_t led_state
);
202 int ulink_append_test_cmd(struct ulink
*device
);
204 /* Interface between OpenULINK and OpenOCD */
205 static void ulink_set_end_state(tap_state_t endstate
);
206 int ulink_queue_statemove(struct ulink
*device
);
208 int ulink_queue_scan(struct ulink
*device
, struct jtag_command
*cmd
);
209 int ulink_queue_tlr_reset(struct ulink
*device
, struct jtag_command
*cmd
);
210 int ulink_queue_runtest(struct ulink
*device
, struct jtag_command
*cmd
);
211 int ulink_queue_reset(struct ulink
*device
, struct jtag_command
*cmd
);
212 int ulink_queue_pathmove(struct ulink
*device
, struct jtag_command
*cmd
);
213 int ulink_queue_sleep(struct ulink
*device
, struct jtag_command
*cmd
);
215 int ulink_post_process_scan(ulink_cmd_t
*ulink_cmd
);
216 int ulink_post_process_queue(struct ulink
*device
);
218 /* JTAG driver functions (registered in struct jtag_interface) */
219 static int ulink_execute_queue(void);
220 static int ulink_khz(int khz
, int *jtag_speed
);
221 static int ulink_speed(int speed
);
222 static int ulink_speed_div(int speed
, int *khz
);
223 static int ulink_init(void);
224 static int ulink_quit(void);
226 /****************************** Global Variables ******************************/
228 struct ulink
*ulink_handle
;
230 /**************************** USB helper functions ****************************/
233 * Opens the ULINK device and claims its USB interface.
235 * @param device pointer to struct ulink identifying ULINK driver instance.
236 * @return on success: ERROR_OK
237 * @return on failure: ERROR_FAIL
239 int ulink_usb_open(struct ulink
**device
)
242 struct usb_dev_handle
*usb_handle
;
244 /* Currently, only original ULINK is supported */
245 uint16_t vids
[] = { ULINK_VID
, 0 };
246 uint16_t pids
[] = { ULINK_PID
, 0 };
248 ret
= jtag_usb_open(vids
, pids
, &usb_handle
);
250 if (ret
!= ERROR_OK
) {
254 ret
= usb_claim_interface(usb_handle
, 0);
260 (*device
)->usb_handle
= usb_handle
;
261 (*device
)->type
= ULINK_1
;
267 * Releases the ULINK interface and closes the USB device handle.
269 * @param device pointer to struct ulink identifying ULINK driver instance.
270 * @return on success: ERROR_OK
271 * @return on failure: ERROR_FAIL
273 int ulink_usb_close(struct ulink
**device
)
275 if (usb_release_interface((*device
)->usb_handle
, 0) != 0) {
279 if (usb_close((*device
)->usb_handle
) != 0) {
283 (*device
)->usb_handle
= NULL
;
288 /******************* ULINK CPU (EZ-USB) specific functions ********************/
291 * Writes '0' or '1' to the CPUCS register, putting the EZ-USB CPU into reset
294 * @param device pointer to struct ulink identifying ULINK driver instance.
295 * @param reset_bit 0 to put CPU into reset, 1 to put CPU out of reset.
296 * @return on success: ERROR_OK
297 * @return on failure: ERROR_FAIL
299 int ulink_cpu_reset(struct ulink
*device
, char reset_bit
)
303 ret
= usb_control_msg(device
->usb_handle
,
304 (USB_ENDPOINT_OUT
| USB_TYPE_VENDOR
| USB_RECIP_DEVICE
),
305 REQUEST_FIRMWARE_LOAD
, CPUCS_REG
, 0, &reset_bit
, 1, USB_TIMEOUT
);
307 /* usb_control_msg() returns the number of bytes transferred during the
308 * DATA stage of the control transfer - must be exactly 1 in this case! */
316 * Puts the ULINK's EZ-USB microcontroller into reset state, downloads
317 * the firmware image, resumes the microcontroller and re-enumerates
320 * @param device pointer to struct ulink identifying ULINK driver instance.
321 * The usb_handle member will be modified during re-enumeration.
322 * @param filename path to the Intel HEX file containing the firmware image.
323 * @param delay the delay to wait for the device to re-enumerate.
324 * @return on success: ERROR_OK
325 * @return on failure: ERROR_FAIL
327 int ulink_load_firmware_and_renumerate(struct ulink
**device
,
328 char *filename
, uint32_t delay
)
332 /* Basic process: After downloading the firmware, the ULINK will disconnect
333 * itself and re-connect after a short amount of time so we have to close
334 * the handle and re-enumerate USB devices */
336 ret
= ulink_load_firmware(*device
, filename
);
337 if (ret
!= ERROR_OK
) {
341 ret
= ulink_usb_close(device
);
342 if (ret
!= ERROR_OK
) {
348 ret
= ulink_usb_open(device
);
349 if (ret
!= ERROR_OK
) {
357 * Downloads a firmware image to the ULINK's EZ-USB microcontroller
360 * @param device pointer to struct ulink identifying ULINK driver instance.
361 * @param filename an absolute or relative path to the Intel HEX file
362 * containing the firmware image.
363 * @return on success: ERROR_OK
364 * @return on failure: ERROR_FAIL
366 int ulink_load_firmware(struct ulink
*device
, char *filename
)
368 struct image ulink_firmware_image
;
371 ret
= ulink_cpu_reset(device
, CPU_RESET
);
372 if (ret
!= ERROR_OK
) {
373 LOG_ERROR("Could not halt ULINK CPU");
377 ulink_firmware_image
.base_address
= 0;
378 ulink_firmware_image
.base_address_set
= 0;
380 ret
= image_open(&ulink_firmware_image
, filename
, "ihex");
381 if (ret
!= ERROR_OK
) {
382 LOG_ERROR("Could not load firmware image");
386 /* Download all sections in the image to ULINK */
387 for (i
= 0; i
< ulink_firmware_image
.num_sections
; i
++) {
388 ret
= ulink_write_firmware_section(device
, &ulink_firmware_image
, i
);
389 if (ret
!= ERROR_OK
) {
394 image_close(&ulink_firmware_image
);
396 ret
= ulink_cpu_reset(device
, CPU_START
);
397 if (ret
!= ERROR_OK
) {
398 LOG_ERROR("Could not restart ULINK CPU");
406 * Send one contiguous firmware section to the ULINK's EZ-USB microcontroller
409 * @param device pointer to struct ulink identifying ULINK driver instance.
410 * @param firmware_image pointer to the firmware image that contains the section
411 * which should be sent to the ULINK's EZ-USB microcontroller.
412 * @param section_index index of the section within the firmware image.
413 * @return on success: ERROR_OK
414 * @return on failure: ERROR_FAIL
416 int ulink_write_firmware_section(struct ulink
*device
,
417 struct image
*firmware_image
, int section_index
)
419 uint16_t addr
, size
, bytes_remaining
, chunk_size
;
420 uint8_t data
[SECTION_BUFFERSIZE
];
421 uint8_t *data_ptr
= data
;
425 size
= (uint16_t)firmware_image
->sections
[section_index
].size
;
426 addr
= (uint16_t)firmware_image
->sections
[section_index
].base_address
;
428 LOG_DEBUG("section %02i at addr 0x%04x (size 0x%04x)", section_index
, addr
,
435 /* Copy section contents to local buffer */
436 ret
= image_read_section(firmware_image
, section_index
, 0, size
, data
,
439 if ((ret
!= ERROR_OK
) || (size_read
!= size
)) {
440 /* Propagating the return code would return '0' (misleadingly indicating
441 * successful execution of the function) if only the size check fails. */
445 bytes_remaining
= size
;
447 /* Send section data in chunks of up to 64 bytes to ULINK */
448 while (bytes_remaining
> 0) {
449 if (bytes_remaining
> 64) {
453 chunk_size
= bytes_remaining
;
456 ret
= usb_control_msg(device
->usb_handle
,
457 (USB_ENDPOINT_OUT
| USB_TYPE_VENDOR
| USB_RECIP_DEVICE
),
458 REQUEST_FIRMWARE_LOAD
, addr
, FIRMWARE_ADDR
, (char *)data_ptr
,
459 chunk_size
, USB_TIMEOUT
);
461 if (ret
!= (int)chunk_size
) {
462 /* Abort if libusb sent less data than requested */
466 bytes_remaining
-= chunk_size
;
468 data_ptr
+= chunk_size
;
474 /************************** Generic helper functions **************************/
477 * Print state of interesting signals via LOG_INFO().
479 * @param input_signals input signal states as returned by CMD_GET_SIGNALS
480 * @param output_signals output signal states as returned by CMD_GET_SIGNALS
482 void ulink_print_signal_states(uint8_t input_signals
, uint8_t output_signals
)
484 LOG_INFO("ULINK signal states: TDI: %i, TDO: %i, TMS: %i, TCK: %i, TRST: %i,"
486 (output_signals
& SIGNAL_TDI
? 1 : 0),
487 (input_signals
& SIGNAL_TDO
? 1 : 0),
488 (output_signals
& SIGNAL_TMS
? 1 : 0),
489 (output_signals
& SIGNAL_TCK
? 1 : 0),
490 (output_signals
& SIGNAL_TRST
? 0 : 1), // TRST and RESET are inverted
491 (output_signals
& SIGNAL_RESET
? 0 : 1)); // by hardware
494 /**************** OpenULINK command generation helper functions ***************/
497 * Allocate and initialize space in memory for OpenULINK command payload.
499 * @param ulink_cmd pointer to command whose payload should be allocated.
500 * @param size the amount of memory to allocate (bytes).
501 * @param direction which payload to allocate.
502 * @return on success: ERROR_OK
503 * @return on failure: ERROR_FAIL
505 int ulink_allocate_payload(ulink_cmd_t
*ulink_cmd
, int size
,
506 enum ulink_payload_direction direction
)
510 payload
= calloc(size
, sizeof(uint8_t));
512 if (payload
== NULL
) {
513 LOG_ERROR("Could not allocate OpenULINK command payload: out of memory");
518 case PAYLOAD_DIRECTION_OUT
:
519 if (ulink_cmd
->payload_out
!= NULL
) {
520 LOG_ERROR("BUG: Duplicate payload allocation for OpenULINK command");
524 ulink_cmd
->payload_out
= payload
;
525 ulink_cmd
->payload_out_size
= size
;
528 case PAYLOAD_DIRECTION_IN
:
529 if (ulink_cmd
->payload_in_start
!= NULL
) {
530 LOG_ERROR("BUG: Duplicate payload allocation for OpenULINK command");
534 ulink_cmd
->payload_in_start
= payload
;
535 ulink_cmd
->payload_in
= payload
;
536 ulink_cmd
->payload_in_size
= size
;
538 /* By default, free payload_in_start in ulink_clear_queue(). Commands
539 * that do not want this behavior (e. g. split scans) must turn it off
541 ulink_cmd
->free_payload_in_start
= true;
549 /****************** OpenULINK command queue helper functions ******************/
552 * Get the current number of bytes in the queue, including command IDs.
554 * @param device pointer to struct ulink identifying ULINK driver instance.
555 * @param direction the transfer direction for which to get byte count.
556 * @return the number of bytes currently stored in the queue for the specified
559 int ulink_get_queue_size(struct ulink
*device
,
560 enum ulink_payload_direction direction
)
562 ulink_cmd_t
*current
= device
->queue_start
;
565 while (current
!= NULL
) {
567 case PAYLOAD_DIRECTION_OUT
:
568 sum
+= current
->payload_out_size
+ 1; // + 1 byte for Command ID
570 case PAYLOAD_DIRECTION_IN
:
571 sum
+= current
->payload_in_size
;
575 current
= current
->next
;
582 * Clear the OpenULINK command queue.
584 * @param device pointer to struct ulink identifying ULINK driver instance.
585 * @return on success: ERROR_OK
586 * @return on failure: ERROR_FAIL
588 void ulink_clear_queue(struct ulink
*device
)
590 ulink_cmd_t
*current
= device
->queue_start
;
591 ulink_cmd_t
*next
= NULL
;
593 while (current
!= NULL
) {
594 /* Save pointer to next element */
595 next
= current
->next
;
597 /* Free payloads: OUT payload can be freed immediately */
598 free(current
->payload_out
);
599 current
->payload_out
= NULL
;
601 /* IN payload MUST be freed ONLY if no other commands use the
602 * payload_in_start buffer */
603 if (current
->free_payload_in_start
== true) {
604 free(current
->payload_in_start
);
605 current
->payload_in_start
= NULL
;
606 current
->payload_in
= NULL
;
609 /* Free queue element */
612 /* Proceed with next element */
616 device
->commands_in_queue
= 0;
617 device
->queue_start
= NULL
;
618 device
->queue_end
= NULL
;
622 * Add a command to the OpenULINK command queue.
624 * @param device pointer to struct ulink identifying ULINK driver instance.
625 * @param ulink_cmd pointer to command that shall be appended to the OpenULINK
627 * @return on success: ERROR_OK
628 * @return on failure: ERROR_FAIL
630 int ulink_append_queue(struct ulink
*device
, ulink_cmd_t
*ulink_cmd
)
632 int newsize_out
, newsize_in
;
635 newsize_out
= ulink_get_queue_size(device
, PAYLOAD_DIRECTION_OUT
) + 1
636 + ulink_cmd
->payload_out_size
;
638 newsize_in
= ulink_get_queue_size(device
, PAYLOAD_DIRECTION_IN
)
639 + ulink_cmd
->payload_in_size
;
641 /* Check if the current command can be appended to the queue */
642 if ((newsize_out
> 64) || (newsize_in
> 64)) {
643 /* New command does not fit. Execute all commands in queue before starting
644 * new queue with the current command as first entry. */
645 ret
= ulink_execute_queued_commands(device
, USB_TIMEOUT
);
646 if (ret
!= ERROR_OK
) {
650 ret
= ulink_post_process_queue(device
);
651 if (ret
!= ERROR_OK
) {
655 ulink_clear_queue(device
);
658 if (device
->queue_start
== NULL
) {
659 /* Queue was empty */
660 device
->commands_in_queue
= 1;
662 device
->queue_start
= ulink_cmd
;
663 device
->queue_end
= ulink_cmd
;
666 /* There are already commands in the queue */
667 device
->commands_in_queue
++;
669 device
->queue_end
->next
= ulink_cmd
;
670 device
->queue_end
= ulink_cmd
;
677 * Sends all queued OpenULINK commands to the ULINK for execution.
679 * @param device pointer to struct ulink identifying ULINK driver instance.
680 * @return on success: ERROR_OK
681 * @return on failure: ERROR_FAIL
683 int ulink_execute_queued_commands(struct ulink
*device
, int timeout
)
685 ulink_cmd_t
*current
;
686 int ret
, i
, index_out
, index_in
, count_out
, count_in
;
689 #ifdef _DEBUG_JTAG_IO_
690 ulink_print_queue(device
);
697 for (current
= device
->queue_start
; current
; current
= current
->next
) {
698 /* Add command to packet */
699 buffer
[index_out
] = current
->id
;
703 for (i
= 0; i
< current
->payload_out_size
; i
++) {
704 buffer
[index_out
+ i
] = current
->payload_out
[i
];
706 index_out
+= current
->payload_out_size
;
707 count_in
+= current
->payload_in_size
;
708 count_out
+= current
->payload_out_size
;
711 /* Send packet to ULINK */
712 ret
= usb_bulk_write(device
->usb_handle
, (2 | USB_ENDPOINT_OUT
),
713 (char *)buffer
, count_out
, timeout
);
717 if (ret
!= count_out
) {
721 /* Wait for response if commands contain IN payload data */
723 ret
= usb_bulk_read(device
->usb_handle
, (2 | USB_ENDPOINT_IN
),
724 (char *)buffer
, 64, timeout
);
728 if (ret
!= count_in
) {
732 /* Write back IN payload data */
734 for (current
= device
->queue_start
; current
; current
= current
->next
) {
735 for (i
= 0; i
< current
->payload_in_size
; i
++) {
736 current
->payload_in
[i
] = buffer
[index_in
];
745 #ifdef _DEBUG_JTAG_IO_
748 * Convert an OpenULINK command ID (\a id) to a human-readable string.
750 * @param id the OpenULINK command ID.
751 * @return the corresponding human-readable string.
753 const char * ulink_cmd_id_string(uint8_t id
)
757 return "CMD_SCAN_IN";
759 case CMD_SLOW_SCAN_IN
:
760 return "CMD_SLOW_SCAN_IN";
763 return "CMD_SCAN_OUT";
765 case CMD_SLOW_SCAN_OUT
:
766 return "CMD_SLOW_SCAN_OUT";
769 return "CMD_SCAN_IO";
771 case CMD_SLOW_SCAN_IO
:
772 return "CMD_SLOW_SCAN_IO";
775 return "CMD_CLOCK_TMS";
777 case CMD_SLOW_CLOCK_TMS
:
778 return "CMD_SLOW_CLOCK_TMS";
781 return "CMD_CLOCK_TCK";
784 return "CMD_SLEEP_US";
787 return "CMD_SLEEP_MS";
789 case CMD_GET_SIGNALS
:
790 return "CMD_GET_SIGNALS";
792 case CMD_SET_SIGNALS
:
793 return "CMD_SET_SIGNALS";
795 case CMD_CONFIGURE_TCK_FREQ
:
796 return "CMD_CONFIGURE_TCK_FREQ";
799 return "CMD_SET_LEDS";
805 return "CMD_UNKNOWN";
811 * Print one OpenULINK command to stdout.
813 * @param ulink_cmd pointer to OpenULINK command.
815 void ulink_print_command(ulink_cmd_t
*ulink_cmd
)
819 printf(" %-22s | OUT size = %i, bytes = 0x", ulink_cmd_id_string(ulink_cmd
->id
),
820 ulink_cmd
->payload_out_size
);
822 for (i
= 0; i
< ulink_cmd
->payload_out_size
; i
++) {
823 printf("%02X ", ulink_cmd
->payload_out
[i
]);
825 printf("\n | IN size = %i\n", ulink_cmd
->payload_in_size
);
829 * Print the OpenULINK command queue to stdout.
831 * @param device pointer to struct ulink identifying ULINK driver instance.
833 void ulink_print_queue(struct ulink
*device
)
835 ulink_cmd_t
*current
;
837 printf("OpenULINK command queue:\n");
839 for (current
= device
->queue_start
; current
; current
= current
->next
) {
840 ulink_print_command(current
);
844 #endif /* _DEBUG_JTAG_IO_ */
849 * Creates and appends a JTAG scan command to the OpenULINK command queue.
850 * A JTAG scan consists of three steps:
851 * - Move to the desired SHIFT state, depending on scan type (IR/DR scan).
852 * - Shift TDI data into the JTAG chain, optionally reading the TDO pin.
853 * - Move to the desired end state.
855 * @param device pointer to struct ulink identifying ULINK driver instance.
856 * @param scan_type the type of the scan (IN, OUT, IO (bidirectional)).
857 * @param scan_size_bits number of bits to shift into the JTAG chain.
858 * @param tdi pointer to array containing TDI data.
859 * @param tdo_start pointer to first element of array where TDO data shall be
860 * stored. See #ulink_cmd for details.
861 * @param tdo pointer to array where TDO data shall be stored
862 * @param tms_count_start number of TMS state transitions to perform BEFORE
863 * shifting data into the JTAG chain.
864 * @param tms_sequence_start sequence of TMS state transitions that will be
865 * performed BEFORE shifting data into the JTAG chain.
866 * @param tms_count_end number of TMS state transitions to perform AFTER
867 * shifting data into the JTAG chain.
868 * @param tms_sequence_end sequence of TMS state transitions that will be
869 * performed AFTER shifting data into the JTAG chain.
870 * @param origin pointer to OpenOCD command that generated this scan command.
871 * @param postprocess whether this command needs to be post-processed after
873 * @return on success: ERROR_OK
874 * @return on failure: ERROR_FAIL
876 int ulink_append_scan_cmd(struct ulink
*device
, enum scan_type scan_type
,
877 int scan_size_bits
, uint8_t *tdi
, uint8_t *tdo_start
, uint8_t *tdo
,
878 uint8_t tms_count_start
, uint8_t tms_sequence_start
, uint8_t tms_count_end
,
879 uint8_t tms_sequence_end
, struct jtag_command
*origin
, bool postprocess
)
881 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
882 int ret
, i
, scan_size_bytes
;
883 uint8_t bits_last_byte
;
889 /* Check size of command. USB buffer can hold 64 bytes, 1 byte is command ID,
890 * 5 bytes are setup data -> 58 remaining payload bytes for TDI data */
891 if (scan_size_bits
> (58 * 8)) {
892 LOG_ERROR("BUG: Tried to create CMD_SCAN_IO OpenULINK command with too"
897 scan_size_bytes
= DIV_ROUND_UP(scan_size_bits
, 8);
899 bits_last_byte
= scan_size_bits
% 8;
900 if (bits_last_byte
== 0) {
904 /* Allocate out_payload depending on scan type */
905 // TODO: set command ID depending on interface speed settings (slow scan)
908 cmd
->id
= CMD_SCAN_IN
;
909 ret
= ulink_allocate_payload(cmd
, 5, PAYLOAD_DIRECTION_OUT
);
912 cmd
->id
= CMD_SCAN_OUT
;
913 ret
= ulink_allocate_payload(cmd
, scan_size_bytes
+ 5, PAYLOAD_DIRECTION_OUT
);
916 cmd
->id
= CMD_SCAN_IO
;
917 ret
= ulink_allocate_payload(cmd
, scan_size_bytes
+ 5, PAYLOAD_DIRECTION_OUT
);
920 LOG_ERROR("BUG: ulink_append_scan_cmd() encountered an unknown scan type");
925 if (ret
!= ERROR_OK
) {
929 /* Build payload_out that is common to all scan types */
930 cmd
->payload_out
[0] = scan_size_bytes
& 0xFF;
931 cmd
->payload_out
[1] = bits_last_byte
& 0xFF;
932 cmd
->payload_out
[2] = ((tms_count_start
& 0x0F) << 4) | (tms_count_end
& 0x0F);
933 cmd
->payload_out
[3] = tms_sequence_start
;
934 cmd
->payload_out
[4] = tms_sequence_end
;
936 /* Setup payload_out for types with OUT transfer */
937 if ((scan_type
== SCAN_OUT
) || (scan_type
== SCAN_IO
)) {
938 for (i
= 0; i
< scan_size_bytes
; i
++) {
939 cmd
->payload_out
[i
+ 5] = tdi
[i
];
943 /* Setup payload_in pointers for types with IN transfer */
944 if ((scan_type
== SCAN_IN
) || (scan_type
== SCAN_IO
)) {
945 cmd
->payload_in_start
= tdo_start
;
946 cmd
->payload_in
= tdo
;
947 cmd
->payload_in_size
= scan_size_bytes
;
950 cmd
->needs_postprocessing
= postprocess
;
951 cmd
->cmd_origin
= origin
;
953 /* For scan commands, we free payload_in_start only when the command is
954 * the last in a series of split commands or a stand-alone command */
955 cmd
->free_payload_in_start
= postprocess
;
957 return ulink_append_queue(device
, cmd
);
961 * Perform TAP state transitions
963 * @param device pointer to struct ulink identifying ULINK driver instance.
964 * @param count defines the number of TCK clock cycles generated (up to 8).
965 * @param sequence defines the TMS pin levels for each state transition. The
966 * Least-Significant Bit is read first.
967 * @return on success: ERROR_OK
968 * @return on failure: ERROR_FAIL
970 int ulink_append_clock_tms_cmd(struct ulink
*device
, uint8_t count
,
973 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
980 cmd
->id
= CMD_CLOCK_TMS
;
982 /* CMD_CLOCK_TMS has two OUT payload bytes and zero IN payload bytes */
983 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
984 if (ret
!= ERROR_OK
) {
988 cmd
->payload_out
[0] = count
;
989 cmd
->payload_out
[1] = sequence
;
991 return ulink_append_queue(device
, cmd
);
995 * Generate a defined amount of TCK clock cycles
997 * All other JTAG signals are left unchanged.
999 * @param device pointer to struct ulink identifying ULINK driver instance.
1000 * @param count the number of TCK clock cycles to generate.
1001 * @return on success: ERROR_OK
1002 * @return on failure: ERROR_FAIL
1004 int ulink_append_clock_tck_cmd(struct ulink
*device
, uint16_t count
)
1006 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
1013 cmd
->id
= CMD_CLOCK_TCK
;
1015 /* CMD_CLOCK_TCK has two OUT payload bytes and zero IN payload bytes */
1016 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1017 if (ret
!= ERROR_OK
) {
1021 cmd
->payload_out
[0] = count
& 0xff;
1022 cmd
->payload_out
[1] = (count
>> 8) & 0xff;
1024 return ulink_append_queue(device
, cmd
);
1028 * Read JTAG signals.
1030 * @param device pointer to struct ulink identifying ULINK driver instance.
1031 * @return on success: ERROR_OK
1032 * @return on failure: ERROR_FAIL
1034 int ulink_append_get_signals_cmd(struct ulink
*device
)
1036 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
1043 cmd
->id
= CMD_GET_SIGNALS
;
1044 cmd
->needs_postprocessing
= true;
1046 /* CMD_GET_SIGNALS has two IN payload bytes */
1047 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_IN
);
1049 if (ret
!= ERROR_OK
) {
1053 return ulink_append_queue(device
, cmd
);
1057 * Arbitrarily set JTAG output signals.
1059 * @param device pointer to struct ulink identifying ULINK driver instance.
1060 * @param low defines which signals will be de-asserted. Each bit corresponds
1069 * @param high defines which signals will be asserted.
1070 * @return on success: ERROR_OK
1071 * @return on failure: ERROR_FAIL
1073 int ulink_append_set_signals_cmd(struct ulink
*device
, uint8_t low
,
1076 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
1083 cmd
->id
= CMD_SET_SIGNALS
;
1085 /* CMD_SET_SIGNALS has two OUT payload bytes and zero IN payload bytes */
1086 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1088 if (ret
!= ERROR_OK
) {
1092 cmd
->payload_out
[0] = low
;
1093 cmd
->payload_out
[1] = high
;
1095 return ulink_append_queue(device
, cmd
);
1099 * Sleep for a pre-defined number of microseconds
1101 * @param device pointer to struct ulink identifying ULINK driver instance.
1102 * @param us the number microseconds to sleep.
1103 * @return on success: ERROR_OK
1104 * @return on failure: ERROR_FAIL
1106 int ulink_append_sleep_cmd(struct ulink
*device
, uint32_t us
)
1108 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
1115 cmd
->id
= CMD_SLEEP_US
;
1117 /* CMD_SLEEP_US has two OUT payload bytes and zero IN payload bytes */
1118 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1120 if (ret
!= ERROR_OK
) {
1124 cmd
->payload_out
[0] = us
& 0x00ff;
1125 cmd
->payload_out
[1] = (us
>> 8) & 0x00ff;
1127 return ulink_append_queue(device
, cmd
);
1131 * Set TCK delay counters
1133 * @param device pointer to struct ulink identifying ULINK driver instance.
1134 * @param delay_scan delay count top value in jtag_slow_scan() functions
1135 * @param delay_tck delay count top value in jtag_clock_tck() function
1136 * @param delay_tms delay count top value in jtag_slow_clock_tms() function
1137 * @return on success: ERROR_OK
1138 * @return on failure: ERROR_FAIL
1140 int ulink_append_configure_tck_cmd(struct ulink
*device
, uint8_t delay_scan
,
1141 uint8_t delay_tck
, uint8_t delay_tms
)
1143 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
1150 cmd
->id
= CMD_CONFIGURE_TCK_FREQ
;
1152 /* CMD_CONFIGURE_TCK_FREQ has three OUT payload bytes and zero
1153 * IN payload bytes */
1154 ret
= ulink_allocate_payload(cmd
, 3, PAYLOAD_DIRECTION_OUT
);
1155 if (ret
!= ERROR_OK
) {
1159 cmd
->payload_out
[0] = delay_scan
;
1160 cmd
->payload_out
[1] = delay_tck
;
1161 cmd
->payload_out
[2] = delay_tms
;
1163 return ulink_append_queue(device
, cmd
);
1167 * Turn on/off ULINK LEDs.
1169 * @param device pointer to struct ulink identifying ULINK driver instance.
1170 * @param led_state which LED(s) to turn on or off. The following bits
1171 * influence the LEDS:
1172 * - Bit 0: Turn COM LED on
1173 * - Bit 1: Turn RUN LED on
1174 * - Bit 2: Turn COM LED off
1175 * - Bit 3: Turn RUN LED off
1176 * If both the on-bit and the off-bit for the same LED is set, the LED is
1178 * @return on success: ERROR_OK
1179 * @return on failure: ERROR_FAIL
1181 int ulink_append_led_cmd(struct ulink
*device
, uint8_t led_state
)
1183 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
1190 cmd
->id
= CMD_SET_LEDS
;
1192 /* CMD_SET_LEDS has one OUT payload byte and zero IN payload bytes */
1193 ret
= ulink_allocate_payload(cmd
, 1, PAYLOAD_DIRECTION_OUT
);
1194 if (ret
!= ERROR_OK
) {
1198 cmd
->payload_out
[0] = led_state
;
1200 return ulink_append_queue(device
, cmd
);
1204 * Test command. Used to check if the ULINK device is ready to accept new
1207 * @param device pointer to struct ulink identifying ULINK driver instance.
1208 * @return on success: ERROR_OK
1209 * @return on failure: ERROR_FAIL
1211 int ulink_append_test_cmd(struct ulink
*device
)
1213 ulink_cmd_t
*cmd
= calloc(1, sizeof(ulink_cmd_t
));
1222 /* CMD_TEST has one OUT payload byte and zero IN payload bytes */
1223 ret
= ulink_allocate_payload(cmd
, 1, PAYLOAD_DIRECTION_OUT
);
1224 if (ret
!= ERROR_OK
) {
1228 cmd
->payload_out
[0] = 0xAA;
1230 return ulink_append_queue(device
, cmd
);
1233 /******************* Interface between OpenULINK and OpenOCD ******************/
1236 * Sets the end state follower (see interface.h) if \a endstate is a stable
1239 * @param endstate the state the end state follower should be set to.
1241 static void ulink_set_end_state(tap_state_t endstate
)
1243 if (tap_is_state_stable(endstate
)) {
1244 tap_set_end_state(endstate
);
1247 LOG_ERROR("BUG: %s is not a valid end state", tap_state_name(endstate
));
1248 exit( EXIT_FAILURE
);
1253 * Move from the current TAP state to the current TAP end state.
1255 * @param device pointer to struct ulink identifying ULINK driver instance.
1256 * @return on success: ERROR_OK
1257 * @return on failure: ERROR_FAIL
1259 int ulink_queue_statemove(struct ulink
*device
)
1261 uint8_t tms_sequence
, tms_count
;
1264 if (tap_get_state() == tap_get_end_state()) {
1265 /* Do nothing if we are already there */
1269 tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1270 tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1272 ret
= ulink_append_clock_tms_cmd(device
, tms_count
, tms_sequence
);
1274 if (ret
== ERROR_OK
) {
1275 tap_set_state(tap_get_end_state());
1282 * Perform a scan operation on a JTAG register.
1284 * @param device pointer to struct ulink identifying ULINK driver instance.
1285 * @param cmd pointer to the command that shall be executed.
1286 * @return on success: ERROR_OK
1287 * @return on failure: ERROR_FAIL
1289 int ulink_queue_scan(struct ulink
*device
, struct jtag_command
*cmd
)
1291 uint32_t scan_size_bits
, scan_size_bytes
, bits_last_scan
;
1292 uint32_t scans_max_payload
, bytecount
;
1293 uint8_t *tdi_buffer_start
= NULL
, *tdi_buffer
= NULL
;
1294 uint8_t *tdo_buffer_start
= NULL
, *tdo_buffer
= NULL
;
1296 uint8_t first_tms_count
, first_tms_sequence
;
1297 uint8_t last_tms_count
, last_tms_sequence
;
1299 uint8_t tms_count_pause
, tms_sequence_pause
;
1300 uint8_t tms_count_resume
, tms_sequence_resume
;
1302 uint8_t tms_count_start
, tms_sequence_start
;
1303 uint8_t tms_count_end
, tms_sequence_end
;
1305 enum scan_type type
;
1308 /* Determine scan size */
1309 scan_size_bits
= jtag_scan_size(cmd
->cmd
.scan
);
1310 scan_size_bytes
= DIV_ROUND_UP(scan_size_bits
, 8);
1312 /* Determine scan type (IN/OUT/IO) */
1313 type
= jtag_scan_type(cmd
->cmd
.scan
);
1315 /* Determine number of scan commands with maximum payload */
1316 scans_max_payload
= scan_size_bytes
/ 58;
1318 /* Determine size of last shift command */
1319 bits_last_scan
= scan_size_bits
- (scans_max_payload
* 58 * 8);
1321 /* Allocate TDO buffer if required */
1322 if ((type
== SCAN_IN
) || (type
== SCAN_IO
)) {
1323 tdo_buffer_start
= calloc(sizeof(uint8_t), scan_size_bytes
);
1325 if (tdo_buffer_start
== NULL
) {
1329 tdo_buffer
= tdo_buffer_start
;
1332 /* Fill TDI buffer if required */
1333 if ((type
== SCAN_OUT
) || (type
== SCAN_IO
)) {
1334 jtag_build_buffer(cmd
->cmd
.scan
, &tdi_buffer_start
);
1335 tdi_buffer
= tdi_buffer_start
;
1338 /* Get TAP state transitions */
1339 if (cmd
->cmd
.scan
->ir_scan
) {
1340 ulink_set_end_state(TAP_IRSHIFT
);
1341 first_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1342 first_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1344 tap_set_state(TAP_IRSHIFT
);
1345 tap_set_end_state(cmd
->cmd
.scan
->end_state
);
1346 last_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1347 last_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1349 /* TAP state transitions for split scans */
1350 tms_count_pause
= tap_get_tms_path_len(TAP_IRSHIFT
, TAP_IRPAUSE
);
1351 tms_sequence_pause
= tap_get_tms_path(TAP_IRSHIFT
, TAP_IRPAUSE
);
1352 tms_count_resume
= tap_get_tms_path_len(TAP_IRPAUSE
, TAP_IRSHIFT
);
1353 tms_sequence_resume
= tap_get_tms_path(TAP_IRPAUSE
, TAP_IRSHIFT
);
1356 ulink_set_end_state(TAP_DRSHIFT
);
1357 first_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1358 first_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1360 tap_set_state(TAP_DRSHIFT
);
1361 tap_set_end_state(cmd
->cmd
.scan
->end_state
);
1362 last_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1363 last_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1365 /* TAP state transitions for split scans */
1366 tms_count_pause
= tap_get_tms_path_len(TAP_DRSHIFT
, TAP_DRPAUSE
);
1367 tms_sequence_pause
= tap_get_tms_path(TAP_DRSHIFT
, TAP_DRPAUSE
);
1368 tms_count_resume
= tap_get_tms_path_len(TAP_DRPAUSE
, TAP_DRSHIFT
);
1369 tms_sequence_resume
= tap_get_tms_path(TAP_DRPAUSE
, TAP_DRSHIFT
);
1372 /* Generate scan commands */
1373 bytecount
= scan_size_bytes
;
1374 while (bytecount
> 0) {
1375 if (bytecount
== scan_size_bytes
) {
1376 /* This is the first scan */
1377 tms_count_start
= first_tms_count
;
1378 tms_sequence_start
= first_tms_sequence
;
1381 /* Resume from previous scan */
1382 tms_count_start
= tms_count_resume
;
1383 tms_sequence_start
= tms_sequence_resume
;
1386 if (bytecount
> 58) { /* Full scan, at least one scan will follow */
1387 tms_count_end
= tms_count_pause
;
1388 tms_sequence_end
= tms_sequence_pause
;
1390 ret
= ulink_append_scan_cmd(device
, type
, 58 * 8, tdi_buffer
,
1391 tdo_buffer_start
, tdo_buffer
, tms_count_start
, tms_sequence_start
,
1392 tms_count_end
, tms_sequence_end
, cmd
, false);
1396 /* Update TDI and TDO buffer pointers */
1397 if (tdi_buffer_start
!= NULL
) {
1400 if (tdo_buffer_start
!= NULL
) {
1404 else if (bytecount
== 58) { /* Full scan, no further scans */
1405 tms_count_end
= last_tms_count
;
1406 tms_sequence_end
= last_tms_sequence
;
1408 ret
= ulink_append_scan_cmd(device
, type
, 58 * 8, tdi_buffer
,
1409 tdo_buffer_start
, tdo_buffer
, tms_count_start
, tms_sequence_start
,
1410 tms_count_end
, tms_sequence_end
, cmd
, true);
1414 else { /* Scan with less than maximum payload, no further scans */
1415 tms_count_end
= last_tms_count
;
1416 tms_sequence_end
= last_tms_sequence
;
1418 ret
= ulink_append_scan_cmd(device
, type
, bits_last_scan
, tdi_buffer
,
1419 tdo_buffer_start
, tdo_buffer
, tms_count_start
, tms_sequence_start
,
1420 tms_count_end
, tms_sequence_end
, cmd
, true);
1425 if (ret
!= ERROR_OK
) {
1426 free(tdi_buffer_start
);
1431 free(tdi_buffer_start
);
1433 /* Set current state to the end state requested by the command */
1434 tap_set_state(cmd
->cmd
.scan
->end_state
);
1440 * Move the TAP into the Test Logic Reset state.
1442 * @param device pointer to struct ulink identifying ULINK driver instance.
1443 * @param cmd pointer to the command that shall be executed.
1444 * @return on success: ERROR_OK
1445 * @return on failure: ERROR_FAIL
1447 int ulink_queue_tlr_reset(struct ulink
*device
, struct jtag_command
*cmd
)
1451 ret
= ulink_append_clock_tms_cmd(device
, 5, 0xff);
1453 if (ret
== ERROR_OK
) {
1454 tap_set_state(TAP_RESET
);
1463 * Generate TCK clock cycles while remaining
1464 * in the Run-Test/Idle state.
1466 * @param device pointer to struct ulink identifying ULINK driver instance.
1467 * @param cmd pointer to the command that shall be executed.
1468 * @return on success: ERROR_OK
1469 * @return on failure: ERROR_FAIL
1471 int ulink_queue_runtest(struct ulink
*device
, struct jtag_command
*cmd
)
1475 /* Only perform statemove if the TAP currently isn't in the TAP_IDLE state */
1476 if (tap_get_state() != TAP_IDLE
) {
1477 ulink_set_end_state(TAP_IDLE
);
1478 ulink_queue_statemove(device
);
1481 /* Generate the clock cycles */
1482 ret
= ulink_append_clock_tck_cmd(device
, cmd
->cmd
.runtest
->num_cycles
);
1483 if (ret
!= ERROR_OK
) {
1487 /* Move to end state specified in command */
1488 if (cmd
->cmd
.runtest
->end_state
!= tap_get_state()) {
1489 tap_set_end_state(cmd
->cmd
.runtest
->end_state
);
1490 ulink_queue_statemove(device
);
1497 * Execute a JTAG_RESET command
1499 * @param cmd pointer to the command that shall be executed.
1500 * @return on success: ERROR_OK
1501 * @return on failure: ERROR_FAIL
1503 int ulink_queue_reset(struct ulink
*device
, struct jtag_command
*cmd
)
1505 uint8_t low
= 0, high
= 0;
1507 if (cmd
->cmd
.reset
->trst
) {
1508 tap_set_state(TAP_RESET
);
1509 high
|= SIGNAL_TRST
;
1515 if (cmd
->cmd
.reset
->srst
) {
1516 high
|= SIGNAL_RESET
;
1519 low
|= SIGNAL_RESET
;
1522 return ulink_append_set_signals_cmd(device
, low
, high
);
1526 * Move to one TAP state or several states in succession.
1528 * @param device pointer to struct ulink identifying ULINK driver instance.
1529 * @param cmd pointer to the command that shall be executed.
1530 * @return on success: ERROR_OK
1531 * @return on failure: ERROR_FAIL
1533 int ulink_queue_pathmove(struct ulink
*device
, struct jtag_command
*cmd
)
1535 // TODO: Implement this!
1540 * Sleep for a specific amount of time.
1542 * @param device pointer to struct ulink identifying ULINK driver instance.
1543 * @param cmd pointer to the command that shall be executed.
1544 * @return on success: ERROR_OK
1545 * @return on failure: ERROR_FAIL
1547 int ulink_queue_sleep(struct ulink
*device
, struct jtag_command
*cmd
)
1549 /* IMPORTANT! Due to the time offset in command execution introduced by
1550 * command queueing, this needs to be implemented in the ULINK device */
1551 return ulink_append_sleep_cmd(device
, cmd
->cmd
.sleep
->us
);
1555 * Post-process JTAG_SCAN command
1557 * @param ulink_cmd pointer to OpenULINK command that shall be processed.
1558 * @return on success: ERROR_OK
1559 * @return on failure: ERROR_FAIL
1561 int ulink_post_process_scan(ulink_cmd_t
*ulink_cmd
)
1563 struct jtag_command
*cmd
= ulink_cmd
->cmd_origin
;
1566 switch (jtag_scan_type(cmd
->cmd
.scan
)) {
1569 ret
= jtag_read_buffer(ulink_cmd
->payload_in_start
, cmd
->cmd
.scan
);
1572 /* Nothing to do for OUT scans */
1576 LOG_ERROR("BUG: ulink_post_process_scan() encountered an unknown"
1586 * Perform post-processing of commands after OpenULINK queue has been executed.
1588 * @param device pointer to struct ulink identifying ULINK driver instance.
1589 * @return on success: ERROR_OK
1590 * @return on failure: ERROR_FAIL
1592 int ulink_post_process_queue(struct ulink
*device
)
1594 ulink_cmd_t
*current
;
1595 struct jtag_command
*openocd_cmd
;
1598 current
= device
->queue_start
;
1600 while (current
!= NULL
) {
1601 openocd_cmd
= current
->cmd_origin
;
1603 /* Check if a corresponding OpenOCD command is stored for this
1604 * OpenULINK command */
1605 if ((current
->needs_postprocessing
== true) && (openocd_cmd
!= NULL
)) {
1606 switch (openocd_cmd
->type
) {
1608 ret
= ulink_post_process_scan(current
);
1610 case JTAG_TLR_RESET
:
1615 /* Nothing to do for these commands */
1620 LOG_ERROR("BUG: ulink_post_process_queue() encountered unknown JTAG "
1625 if (ret
!= ERROR_OK
) {
1630 current
= current
->next
;
1636 /**************************** JTAG driver functions ***************************/
1639 * Executes the JTAG Command Queue.
1641 * This is done in three stages: First, all OpenOCD commands are processed into
1642 * queued OpenULINK commands. Next, the OpenULINK command queue is sent to the
1643 * ULINK device and data received from the ULINK device is cached. Finally,
1644 * the post-processing function writes back data to the corresponding OpenOCD
1647 * @return on success: ERROR_OK
1648 * @return on failure: ERROR_FAIL
1650 static int ulink_execute_queue(void)
1652 struct jtag_command
*cmd
= jtag_command_queue
;
1656 switch (cmd
->type
) {
1658 ret
= ulink_queue_scan(ulink_handle
, cmd
);
1660 case JTAG_TLR_RESET
:
1661 ret
= ulink_queue_tlr_reset(ulink_handle
, cmd
);
1664 ret
= ulink_queue_runtest(ulink_handle
, cmd
);
1667 ret
= ulink_queue_reset(ulink_handle
, cmd
);
1670 ret
= ulink_queue_pathmove(ulink_handle
, cmd
);
1673 ret
= ulink_queue_sleep(ulink_handle
, cmd
);
1677 LOG_ERROR("BUG: encountered unknown JTAG command type");
1681 if (ret
!= ERROR_OK
) {
1688 if (ulink_handle
->commands_in_queue
> 0) {
1689 ret
= ulink_execute_queued_commands(ulink_handle
, USB_TIMEOUT
);
1690 if (ret
!= ERROR_OK
) {
1694 ret
= ulink_post_process_queue(ulink_handle
);
1695 if (ret
!= ERROR_OK
) {
1699 ulink_clear_queue(ulink_handle
);
1706 * Set the TCK frequency of the ULINK adapter.
1709 * @param jtag_speed ???
1710 * @return on success: ERROR_OK
1711 * @return on failure: ERROR_FAIL
1713 static int ulink_khz(int khz
, int *jtag_speed
)
1716 LOG_ERROR("RCLK not supported");
1720 LOG_INFO("ulink_khz: %i kHz", khz
);
1722 /* ULINK maximum TCK frequency is ~ 150 kHz */
1733 * Set the TCK frequency of the ULINK adapter.
1736 * @return on success: ERROR_OK
1737 * @return on failure: ERROR_FAIL
1739 static int ulink_speed(int speed
)
1747 static int ulink_speed_div(int speed
, int *khz
)
1749 LOG_INFO("ulink_speed_div: %i", speed
);
1764 * Initiates the firmware download to the ULINK adapter and prepares
1767 * @return on success: ERROR_OK
1768 * @return on failure: ERROR_FAIL
1770 static int ulink_init(void)
1773 char str_manufacturer
[20];
1774 bool download_firmware
= false;
1776 uint8_t input_signals
, output_signals
;
1778 ulink_handle
= calloc(1, sizeof(struct ulink
));
1779 if (ulink_handle
== NULL
) {
1785 ret
= ulink_usb_open(&ulink_handle
);
1786 if (ret
!= ERROR_OK
) {
1787 LOG_ERROR("Could not open ULINK device");
1791 /* Get String Descriptor to determine if firmware needs to be loaded */
1792 ret
= usb_get_string_simple(ulink_handle
->usb_handle
, 1, str_manufacturer
, 20);
1794 /* Could not get descriptor -> Unconfigured or original Keil firmware */
1795 download_firmware
= true;
1798 /* We got a String Descriptor, check if it is the correct one */
1799 if (strncmp(str_manufacturer
, "OpenULINK", 9) != 0) {
1800 download_firmware
= true;
1804 if (download_firmware
== true) {
1805 LOG_INFO("Loading OpenULINK firmware. This is reversible by power-cycling"
1807 ret
= ulink_load_firmware_and_renumerate(&ulink_handle
,
1808 ULINK_FIRMWARE_FILE
, ULINK_RENUMERATION_DELAY
);
1809 if (ret
!= ERROR_OK
) {
1810 LOG_ERROR("Could not download firmware and re-numerate ULINK");
1815 LOG_INFO("ULINK device is already running OpenULINK firmware");
1818 /* Initialize OpenULINK command queue */
1819 ulink_clear_queue(ulink_handle
);
1821 /* Issue one test command with short timeout */
1822 ret
= ulink_append_test_cmd(ulink_handle
);
1823 if (ret
!= ERROR_OK
) {
1827 ret
= ulink_execute_queued_commands(ulink_handle
, 200);
1828 if (ret
!= ERROR_OK
) {
1829 /* Sending test command failed. The ULINK device may be forever waiting for
1830 * the host to fetch an USB Bulk IN packet (e. g. OpenOCD crashed or was
1831 * shut down by the user via Ctrl-C. Try to retrieve this Bulk IN packet. */
1832 dummy
= calloc(64, sizeof(uint8_t));
1834 ret
= usb_bulk_read(ulink_handle
->usb_handle
, (2 | USB_ENDPOINT_IN
),
1835 (char *)dummy
, 64, 200);
1840 /* Bulk IN transfer failed -> unrecoverable error condition */
1841 LOG_ERROR("Cannot communicate with ULINK device. Disconnect ULINK from "
1842 "the USB port and re-connect, then re-run OpenOCD");
1845 #ifdef _DEBUG_USB_COMMS_
1847 /* Successfully received Bulk IN packet -> continue */
1848 LOG_INFO("Recovered from lost Bulk IN packet");
1852 ulink_clear_queue(ulink_handle
);
1854 ulink_append_get_signals_cmd(ulink_handle
);
1855 ulink_execute_queued_commands(ulink_handle
, 200);
1857 /* Post-process the single CMD_GET_SIGNALS command */
1858 input_signals
= ulink_handle
->queue_start
->payload_in
[0];
1859 output_signals
= ulink_handle
->queue_start
->payload_in
[1];
1861 ulink_print_signal_states(input_signals
, output_signals
);
1863 ulink_clear_queue(ulink_handle
);
1869 * Closes the USB handle for the ULINK device.
1871 * @return on success: ERROR_OK
1872 * @return on failure: ERROR_FAIL
1874 static int ulink_quit(void)
1878 ret
= ulink_usb_close(&ulink_handle
);
1885 * Set a custom path to ULINK firmware image and force downloading to ULINK.
1887 COMMAND_HANDLER(ulink_download_firmware_handler
)
1891 if (CMD_ARGC
!= 1) {
1892 LOG_ERROR("Need exactly one argument to ulink_download_firmware");
1896 LOG_INFO("Downloading ULINK firmware image %s", CMD_ARGV
[0]);
1898 /* Download firmware image in CMD_ARGV[0] */
1899 ret
= ulink_load_firmware_and_renumerate(&ulink_handle
, (char *)CMD_ARGV
[0],
1900 ULINK_RENUMERATION_DELAY
);
1905 /*************************** Command Registration **************************/
1907 static const struct command_registration ulink_command_handlers
[] = {
1909 .name
= "ulink_download_firmware",
1910 .handler
= &ulink_download_firmware_handler
,
1911 .mode
= COMMAND_EXEC
,
1912 .help
= "download firmware image to ULINK device",
1913 .usage
= "path/to/ulink_firmware.hex",
1915 COMMAND_REGISTRATION_DONE
,
1918 struct jtag_interface ulink_interface
= {
1921 .commands
= ulink_command_handlers
,
1922 .transports
= jtag_only
,
1924 .execute_queue
= ulink_execute_queue
,
1926 .speed
= ulink_speed
,
1927 .speed_div
= ulink_speed_div
,