1 // SPDX-License-Identifier: GPL-2.0-or-later
3 /***************************************************************************
4 * Copyright (C) 2011-2013 by Martin Schmoelzer *
5 * <martin.schmoelzer@student.tuwien.ac.at> *
6 ***************************************************************************/
13 #include "helper/system.h"
14 #include <jtag/interface.h>
15 #include <jtag/commands.h>
16 #include <target/image.h>
18 #include "libusb_helper.h"
19 #include "OpenULINK/include/msgtypes.h"
21 /** USB Vendor ID of ULINK device in unconfigured state (no firmware loaded
22 * yet) or with OpenULINK firmware. */
23 #define ULINK_VID 0xC251
25 /** USB Product ID of ULINK device in unconfigured state (no firmware loaded
26 * yet) or with OpenULINK firmware. */
27 #define ULINK_PID 0x2710
29 /** Address of EZ-USB CPU Control & Status register. This register can be
30 * written by issuing a Control EP0 vendor request. */
31 #define CPUCS_REG 0x7F92
33 /** USB Control EP0 bRequest: "Firmware Load". */
34 #define REQUEST_FIRMWARE_LOAD 0xA0
36 /** Value to write into CPUCS to put EZ-USB into reset. */
37 #define CPU_RESET 0x01
39 /** Value to write into CPUCS to put EZ-USB out of reset. */
40 #define CPU_START 0x00
42 /** Base address of firmware in EZ-USB code space. */
43 #define FIRMWARE_ADDR 0x0000
45 /** USB interface number */
46 #define USB_INTERFACE 0
48 /** Delay (in microseconds) to wait while EZ-USB performs ReNumeration. */
49 #define ULINK_RENUMERATION_DELAY 1500000
51 /** Default location of OpenULINK firmware image. */
52 #define ULINK_FIRMWARE_FILE PKGDATADIR "/OpenULINK/ulink_firmware.hex"
54 /** Maximum size of a single firmware section. Entire EZ-USB code space = 8kB */
55 #define SECTION_BUFFERSIZE 8192
57 /** Tuning of OpenOCD SCAN commands split into multiple OpenULINK commands. */
58 #define SPLIT_SCAN_THRESHOLD 10
60 /** ULINK hardware type */
62 /** Original ULINK adapter, based on Cypress EZ-USB (AN2131):
63 * Full JTAG support, no SWD support. */
66 /** Newer ULINK adapter, based on NXP LPC2148. Currently unsupported. */
69 /** Newer ULINK adapter, based on EZ-USB FX2 + FPGA. Currently unsupported. */
72 /** Newer ULINK adapter, possibly based on ULINK 2. Currently unsupported. */
76 enum ulink_payload_direction
{
77 PAYLOAD_DIRECTION_OUT
,
81 enum ulink_delay_type
{
90 * OpenULINK command (OpenULINK command queue element).
92 * For the OUT direction payload, things are quite easy: Payload is stored
93 * in a rather small array (up to 63 bytes), the payload is always allocated
94 * by the function generating the command and freed by ulink_clear_queue().
96 * For the IN direction payload, things get a little bit more complicated:
97 * The maximum IN payload size for a single command is 64 bytes. Assume that
98 * a single OpenOCD command needs to scan 256 bytes. This results in the
99 * generation of four OpenULINK commands. The function generating these
100 * commands shall allocate an uint8_t[256] array. Each command's #payload_in
101 * pointer shall point to the corresponding offset where IN data shall be
102 * placed, while #payload_in_start shall point to the first element of the 256
104 * - first command: #payload_in_start + 0
105 * - second command: #payload_in_start + 64
106 * - third command: #payload_in_start + 128
107 * - fourth command: #payload_in_start + 192
109 * The last command sets #needs_postprocessing to true.
112 uint8_t id
; /**< ULINK command ID */
114 uint8_t *payload_out
; /**< OUT direction payload data */
115 uint8_t payload_out_size
; /**< OUT direction payload size for this command */
117 uint8_t *payload_in_start
; /**< Pointer to first element of IN payload array */
118 uint8_t *payload_in
; /**< Pointer where IN payload shall be stored */
119 uint8_t payload_in_size
; /**< IN direction payload size for this command */
121 /** Indicates if this command needs post-processing */
122 bool needs_postprocessing
;
124 /** Indicates if ulink_clear_queue() should free payload_in_start */
125 bool free_payload_in_start
;
127 /** Pointer to corresponding OpenOCD command for post-processing */
128 struct jtag_command
*cmd_origin
;
130 struct ulink_cmd
*next
; /**< Pointer to next command (linked list) */
133 /** Describes one driver instance */
135 struct libusb_context
*libusb_ctx
;
136 struct libusb_device_handle
*usb_device_handle
;
137 enum ulink_type type
;
139 unsigned int ep_in
; /**< IN endpoint number */
140 unsigned int ep_out
; /**< OUT endpoint number */
142 int delay_scan_in
; /**< Delay value for SCAN_IN commands */
143 int delay_scan_out
; /**< Delay value for SCAN_OUT commands */
144 int delay_scan_io
; /**< Delay value for SCAN_IO commands */
145 int delay_clock_tck
; /**< Delay value for CLOCK_TMS commands */
146 int delay_clock_tms
; /**< Delay value for CLOCK_TCK commands */
148 int commands_in_queue
; /**< Number of commands in queue */
149 struct ulink_cmd
*queue_start
; /**< Pointer to first command in queue */
150 struct ulink_cmd
*queue_end
; /**< Pointer to last command in queue */
153 /**************************** Function Prototypes *****************************/
155 /* USB helper functions */
156 static int ulink_usb_open(struct ulink
**device
);
157 static int ulink_usb_close(struct ulink
**device
);
159 /* ULINK MCU (Cypress EZ-USB) specific functions */
160 static int ulink_cpu_reset(struct ulink
*device
, unsigned char reset_bit
);
161 static int ulink_load_firmware_and_renumerate(struct ulink
**device
, const char *filename
,
163 static int ulink_load_firmware(struct ulink
*device
, const char *filename
);
164 static int ulink_write_firmware_section(struct ulink
*device
,
165 struct image
*firmware_image
, int section_index
);
167 /* Generic helper functions */
168 static void ulink_print_signal_states(uint8_t input_signals
, uint8_t output_signals
);
170 /* OpenULINK command generation helper functions */
171 static int ulink_allocate_payload(struct ulink_cmd
*ulink_cmd
, int size
,
172 enum ulink_payload_direction direction
);
174 /* OpenULINK command queue helper functions */
175 static int ulink_get_queue_size(struct ulink
*device
,
176 enum ulink_payload_direction direction
);
177 static void ulink_clear_queue(struct ulink
*device
);
178 static int ulink_append_queue(struct ulink
*device
, struct ulink_cmd
*ulink_cmd
);
179 static int ulink_execute_queued_commands(struct ulink
*device
, int timeout
);
181 static void ulink_print_queue(struct ulink
*device
);
183 static int ulink_append_scan_cmd(struct ulink
*device
,
184 enum scan_type scan_type
,
189 uint8_t tms_count_start
,
190 uint8_t tms_sequence_start
,
191 uint8_t tms_count_end
,
192 uint8_t tms_sequence_end
,
193 struct jtag_command
*origin
,
195 static int ulink_append_clock_tms_cmd(struct ulink
*device
, uint8_t count
,
197 static int ulink_append_clock_tck_cmd(struct ulink
*device
, uint16_t count
);
198 static int ulink_append_get_signals_cmd(struct ulink
*device
);
199 static int ulink_append_set_signals_cmd(struct ulink
*device
, uint8_t low
,
201 static int ulink_append_sleep_cmd(struct ulink
*device
, uint32_t us
);
202 static int ulink_append_configure_tck_cmd(struct ulink
*device
,
208 static int __attribute__((unused
)) ulink_append_led_cmd(struct ulink
*device
, uint8_t led_state
);
209 static int ulink_append_test_cmd(struct ulink
*device
);
211 /* OpenULINK TCK frequency helper functions */
212 static int ulink_calculate_delay(enum ulink_delay_type type
, long f
, int *delay
);
214 /* Interface between OpenULINK and OpenOCD */
215 static void ulink_set_end_state(tap_state_t endstate
);
216 static int ulink_queue_statemove(struct ulink
*device
);
218 static int ulink_queue_scan(struct ulink
*device
, struct jtag_command
*cmd
);
219 static int ulink_queue_tlr_reset(struct ulink
*device
, struct jtag_command
*cmd
);
220 static int ulink_queue_runtest(struct ulink
*device
, struct jtag_command
*cmd
);
221 static int ulink_queue_reset(struct ulink
*device
, struct jtag_command
*cmd
);
222 static int ulink_queue_pathmove(struct ulink
*device
, struct jtag_command
*cmd
);
223 static int ulink_queue_sleep(struct ulink
*device
, struct jtag_command
*cmd
);
224 static int ulink_queue_stableclocks(struct ulink
*device
, struct jtag_command
*cmd
);
226 static int ulink_post_process_scan(struct ulink_cmd
*ulink_cmd
);
227 static int ulink_post_process_queue(struct ulink
*device
);
229 /* adapter driver functions */
230 static int ulink_execute_queue(void);
231 static int ulink_khz(int khz
, int *jtag_speed
);
232 static int ulink_speed(int speed
);
233 static int ulink_speed_div(int speed
, int *khz
);
234 static int ulink_init(void);
235 static int ulink_quit(void);
237 /****************************** Global Variables ******************************/
239 static struct ulink
*ulink_handle
;
241 /**************************** USB helper functions ****************************/
244 * Opens the ULINK device
246 * Currently, only the original ULINK is supported
248 * @param device pointer to struct ulink identifying ULINK driver instance.
249 * @return on success: ERROR_OK
250 * @return on failure: ERROR_FAIL
252 static int ulink_usb_open(struct ulink
**device
)
254 ssize_t num_devices
, i
;
256 struct libusb_device
**usb_devices
;
257 struct libusb_device_descriptor usb_desc
;
258 struct libusb_device_handle
*usb_device_handle
;
260 num_devices
= libusb_get_device_list((*device
)->libusb_ctx
, &usb_devices
);
262 if (num_devices
<= 0)
266 for (i
= 0; i
< num_devices
; i
++) {
267 if (libusb_get_device_descriptor(usb_devices
[i
], &usb_desc
) != 0)
269 else if (usb_desc
.idVendor
== ULINK_VID
&& usb_desc
.idProduct
== ULINK_PID
) {
278 if (libusb_open(usb_devices
[i
], &usb_device_handle
) != 0)
280 libusb_free_device_list(usb_devices
, 1);
282 (*device
)->usb_device_handle
= usb_device_handle
;
283 (*device
)->type
= ULINK_1
;
289 * Releases the ULINK interface and closes the USB device handle.
291 * @param device pointer to struct ulink identifying ULINK driver instance.
292 * @return on success: ERROR_OK
293 * @return on failure: ERROR_FAIL
295 static int ulink_usb_close(struct ulink
**device
)
297 if (libusb_release_interface((*device
)->usb_device_handle
, 0) != 0)
300 libusb_close((*device
)->usb_device_handle
);
302 (*device
)->usb_device_handle
= NULL
;
307 /******************* ULINK CPU (EZ-USB) specific functions ********************/
310 * Writes '0' or '1' to the CPUCS register, putting the EZ-USB CPU into reset
313 * @param device pointer to struct ulink identifying ULINK driver instance.
314 * @param reset_bit 0 to put CPU into reset, 1 to put CPU out of reset.
315 * @return on success: ERROR_OK
316 * @return on failure: ERROR_FAIL
318 static int ulink_cpu_reset(struct ulink
*device
, unsigned char reset_bit
)
322 ret
= libusb_control_transfer(device
->usb_device_handle
,
323 (LIBUSB_ENDPOINT_OUT
| LIBUSB_REQUEST_TYPE_VENDOR
| LIBUSB_RECIPIENT_DEVICE
),
324 REQUEST_FIRMWARE_LOAD
, CPUCS_REG
, 0, &reset_bit
, 1, LIBUSB_TIMEOUT_MS
);
326 /* usb_control_msg() returns the number of bytes transferred during the
327 * DATA stage of the control transfer - must be exactly 1 in this case! */
334 * Puts the ULINK's EZ-USB microcontroller into reset state, downloads
335 * the firmware image, resumes the microcontroller and re-enumerates
338 * @param device pointer to struct ulink identifying ULINK driver instance.
339 * The usb_handle member will be modified during re-enumeration.
340 * @param filename path to the Intel HEX file containing the firmware image.
341 * @param delay the delay to wait for the device to re-enumerate.
342 * @return on success: ERROR_OK
343 * @return on failure: ERROR_FAIL
345 static int ulink_load_firmware_and_renumerate(struct ulink
**device
,
346 const char *filename
, uint32_t delay
)
350 /* Basic process: After downloading the firmware, the ULINK will disconnect
351 * itself and re-connect after a short amount of time so we have to close
352 * the handle and re-enumerate USB devices */
354 ret
= ulink_load_firmware(*device
, filename
);
358 ret
= ulink_usb_close(device
);
364 ret
= ulink_usb_open(device
);
372 * Downloads a firmware image to the ULINK's EZ-USB microcontroller
375 * @param device pointer to struct ulink identifying ULINK driver instance.
376 * @param filename an absolute or relative path to the Intel HEX file
377 * containing the firmware image.
378 * @return on success: ERROR_OK
379 * @return on failure: ERROR_FAIL
381 static int ulink_load_firmware(struct ulink
*device
, const char *filename
)
383 struct image ulink_firmware_image
;
386 ret
= ulink_cpu_reset(device
, CPU_RESET
);
387 if (ret
!= ERROR_OK
) {
388 LOG_ERROR("Could not halt ULINK CPU");
392 ulink_firmware_image
.base_address
= 0;
393 ulink_firmware_image
.base_address_set
= false;
395 ret
= image_open(&ulink_firmware_image
, filename
, "ihex");
396 if (ret
!= ERROR_OK
) {
397 LOG_ERROR("Could not load firmware image");
401 /* Download all sections in the image to ULINK */
402 for (unsigned int i
= 0; i
< ulink_firmware_image
.num_sections
; i
++) {
403 ret
= ulink_write_firmware_section(device
, &ulink_firmware_image
, i
);
408 image_close(&ulink_firmware_image
);
410 ret
= ulink_cpu_reset(device
, CPU_START
);
411 if (ret
!= ERROR_OK
) {
412 LOG_ERROR("Could not restart ULINK CPU");
420 * Send one contiguous firmware section to the ULINK's EZ-USB microcontroller
423 * @param device pointer to struct ulink identifying ULINK driver instance.
424 * @param firmware_image pointer to the firmware image that contains the section
425 * which should be sent to the ULINK's EZ-USB microcontroller.
426 * @param section_index index of the section within the firmware image.
427 * @return on success: ERROR_OK
428 * @return on failure: ERROR_FAIL
430 static int ulink_write_firmware_section(struct ulink
*device
,
431 struct image
*firmware_image
, int section_index
)
433 uint16_t addr
, size
, bytes_remaining
, chunk_size
;
434 uint8_t data
[SECTION_BUFFERSIZE
];
435 uint8_t *data_ptr
= data
;
439 size
= (uint16_t)firmware_image
->sections
[section_index
].size
;
440 addr
= (uint16_t)firmware_image
->sections
[section_index
].base_address
;
442 LOG_DEBUG("section %02i at addr 0x%04x (size 0x%04x)", section_index
, addr
,
445 /* Copy section contents to local buffer */
446 ret
= image_read_section(firmware_image
, section_index
, 0, size
, data
,
449 if ((ret
!= ERROR_OK
) || (size_read
!= size
)) {
450 /* Propagating the return code would return '0' (misleadingly indicating
451 * successful execution of the function) if only the size check fails. */
455 bytes_remaining
= size
;
457 /* Send section data in chunks of up to 64 bytes to ULINK */
458 while (bytes_remaining
> 0) {
459 if (bytes_remaining
> 64)
462 chunk_size
= bytes_remaining
;
464 ret
= libusb_control_transfer(device
->usb_device_handle
,
465 (LIBUSB_ENDPOINT_OUT
| LIBUSB_REQUEST_TYPE_VENDOR
| LIBUSB_RECIPIENT_DEVICE
),
466 REQUEST_FIRMWARE_LOAD
, addr
, FIRMWARE_ADDR
, (unsigned char *)data_ptr
,
467 chunk_size
, LIBUSB_TIMEOUT_MS
);
469 if (ret
!= (int)chunk_size
) {
470 /* Abort if libusb sent less data than requested */
474 bytes_remaining
-= chunk_size
;
476 data_ptr
+= chunk_size
;
482 /************************** Generic helper functions **************************/
485 * Print state of interesting signals via LOG_INFO().
487 * @param input_signals input signal states as returned by CMD_GET_SIGNALS
488 * @param output_signals output signal states as returned by CMD_GET_SIGNALS
490 static void ulink_print_signal_states(uint8_t input_signals
, uint8_t output_signals
)
492 LOG_INFO("ULINK signal states: TDI: %i, TDO: %i, TMS: %i, TCK: %i, TRST: %i,"
494 (output_signals
& SIGNAL_TDI
? 1 : 0),
495 (input_signals
& SIGNAL_TDO
? 1 : 0),
496 (output_signals
& SIGNAL_TMS
? 1 : 0),
497 (output_signals
& SIGNAL_TCK
? 1 : 0),
498 (output_signals
& SIGNAL_TRST
? 0 : 1), /* Inverted by hardware */
499 (output_signals
& SIGNAL_RESET
? 0 : 1)); /* Inverted by hardware */
502 /**************** OpenULINK command generation helper functions ***************/
505 * Allocate and initialize space in memory for OpenULINK command payload.
507 * @param ulink_cmd pointer to command whose payload should be allocated.
508 * @param size the amount of memory to allocate (bytes).
509 * @param direction which payload to allocate.
510 * @return on success: ERROR_OK
511 * @return on failure: ERROR_FAIL
513 static int ulink_allocate_payload(struct ulink_cmd
*ulink_cmd
, int size
,
514 enum ulink_payload_direction direction
)
518 payload
= calloc(size
, sizeof(uint8_t));
521 LOG_ERROR("Could not allocate OpenULINK command payload: out of memory");
526 case PAYLOAD_DIRECTION_OUT
:
527 if (ulink_cmd
->payload_out
) {
528 LOG_ERROR("BUG: Duplicate payload allocation for OpenULINK command");
532 ulink_cmd
->payload_out
= payload
;
533 ulink_cmd
->payload_out_size
= size
;
536 case PAYLOAD_DIRECTION_IN
:
537 if (ulink_cmd
->payload_in_start
) {
538 LOG_ERROR("BUG: Duplicate payload allocation for OpenULINK command");
542 ulink_cmd
->payload_in_start
= payload
;
543 ulink_cmd
->payload_in
= payload
;
544 ulink_cmd
->payload_in_size
= size
;
546 /* By default, free payload_in_start in ulink_clear_queue(). Commands
547 * that do not want this behavior (e. g. split scans) must turn it off
549 ulink_cmd
->free_payload_in_start
= true;
557 /****************** OpenULINK command queue helper functions ******************/
560 * Get the current number of bytes in the queue, including command IDs.
562 * @param device pointer to struct ulink identifying ULINK driver instance.
563 * @param direction the transfer direction for which to get byte count.
564 * @return the number of bytes currently stored in the queue for the specified
567 static int ulink_get_queue_size(struct ulink
*device
,
568 enum ulink_payload_direction direction
)
570 struct ulink_cmd
*current
= device
->queue_start
;
575 case PAYLOAD_DIRECTION_OUT
:
576 sum
+= current
->payload_out_size
+ 1; /* + 1 byte for Command ID */
578 case PAYLOAD_DIRECTION_IN
:
579 sum
+= current
->payload_in_size
;
583 current
= current
->next
;
590 * Clear the OpenULINK command queue.
592 * @param device pointer to struct ulink identifying ULINK driver instance.
594 static void ulink_clear_queue(struct ulink
*device
)
596 struct ulink_cmd
*current
= device
->queue_start
;
597 struct ulink_cmd
*next
= NULL
;
600 /* Save pointer to next element */
601 next
= current
->next
;
603 /* Free payloads: OUT payload can be freed immediately */
604 free(current
->payload_out
);
605 current
->payload_out
= NULL
;
607 /* IN payload MUST be freed ONLY if no other commands use the
608 * payload_in_start buffer */
609 if (current
->free_payload_in_start
== true) {
610 free(current
->payload_in_start
);
611 current
->payload_in_start
= NULL
;
612 current
->payload_in
= NULL
;
615 /* Free queue element */
618 /* Proceed with next element */
622 device
->commands_in_queue
= 0;
623 device
->queue_start
= NULL
;
624 device
->queue_end
= NULL
;
628 * Add a command to the OpenULINK command queue.
630 * @param device pointer to struct ulink identifying ULINK driver instance.
631 * @param ulink_cmd pointer to command that shall be appended to the OpenULINK
633 * @return on success: ERROR_OK
634 * @return on failure: ERROR_FAIL
636 static int ulink_append_queue(struct ulink
*device
, struct ulink_cmd
*ulink_cmd
)
638 int newsize_out
, newsize_in
;
641 newsize_out
= ulink_get_queue_size(device
, PAYLOAD_DIRECTION_OUT
) + 1
642 + ulink_cmd
->payload_out_size
;
644 newsize_in
= ulink_get_queue_size(device
, PAYLOAD_DIRECTION_IN
)
645 + ulink_cmd
->payload_in_size
;
647 /* Check if the current command can be appended to the queue */
648 if ((newsize_out
> 64) || (newsize_in
> 64)) {
649 /* New command does not fit. Execute all commands in queue before starting
650 * new queue with the current command as first entry. */
651 ret
= ulink_execute_queued_commands(device
, LIBUSB_TIMEOUT_MS
);
654 ret
= ulink_post_process_queue(device
);
657 ulink_clear_queue(device
);
660 if (!device
->queue_start
) {
661 /* Queue was empty */
662 device
->commands_in_queue
= 1;
664 device
->queue_start
= ulink_cmd
;
665 device
->queue_end
= ulink_cmd
;
667 /* There are already commands in the queue */
668 device
->commands_in_queue
++;
670 device
->queue_end
->next
= ulink_cmd
;
671 device
->queue_end
= ulink_cmd
;
675 ulink_clear_queue(device
);
681 * Sends all queued OpenULINK commands to the ULINK for execution.
683 * @param device pointer to struct ulink identifying ULINK driver instance.
685 * @return on success: ERROR_OK
686 * @return on failure: ERROR_FAIL
688 static int ulink_execute_queued_commands(struct ulink
*device
, int timeout
)
690 struct ulink_cmd
*current
;
691 int ret
, i
, index_out
, index_in
, count_out
, count_in
, transferred
;
694 if (LOG_LEVEL_IS(LOG_LVL_DEBUG_IO
))
695 ulink_print_queue(device
);
701 for (current
= device
->queue_start
; current
; current
= current
->next
) {
702 /* Add command to packet */
703 buffer
[index_out
] = current
->id
;
707 for (i
= 0; i
< current
->payload_out_size
; i
++)
708 buffer
[index_out
+ i
] = current
->payload_out
[i
];
709 index_out
+= current
->payload_out_size
;
710 count_in
+= current
->payload_in_size
;
711 count_out
+= current
->payload_out_size
;
714 /* Send packet to ULINK */
715 ret
= libusb_bulk_transfer(device
->usb_device_handle
, device
->ep_out
,
716 (unsigned char *)buffer
, count_out
, &transferred
, timeout
);
719 if (transferred
!= count_out
)
722 /* Wait for response if commands contain IN payload data */
724 ret
= libusb_bulk_transfer(device
->usb_device_handle
, device
->ep_in
,
725 (unsigned char *)buffer
, 64, &transferred
, timeout
);
728 if (transferred
!= count_in
)
731 /* Write back IN payload data */
733 for (current
= device
->queue_start
; current
; current
= current
->next
) {
734 for (i
= 0; i
< current
->payload_in_size
; i
++) {
735 current
->payload_in
[i
] = buffer
[index_in
];
745 * Convert an OpenULINK command ID (\a id) to a human-readable string.
747 * @param id the OpenULINK command ID.
748 * @return the corresponding human-readable string.
750 static const char *ulink_cmd_id_string(uint8_t id
)
754 return "CMD_SCAN_IN";
755 case CMD_SLOW_SCAN_IN
:
756 return "CMD_SLOW_SCAN_IN";
758 return "CMD_SCAN_OUT";
759 case CMD_SLOW_SCAN_OUT
:
760 return "CMD_SLOW_SCAN_OUT";
762 return "CMD_SCAN_IO";
763 case CMD_SLOW_SCAN_IO
:
764 return "CMD_SLOW_SCAN_IO";
766 return "CMD_CLOCK_TMS";
767 case CMD_SLOW_CLOCK_TMS
:
768 return "CMD_SLOW_CLOCK_TMS";
770 return "CMD_CLOCK_TCK";
771 case CMD_SLOW_CLOCK_TCK
:
772 return "CMD_SLOW_CLOCK_TCK";
774 return "CMD_SLEEP_US";
776 return "CMD_SLEEP_MS";
777 case CMD_GET_SIGNALS
:
778 return "CMD_GET_SIGNALS";
779 case CMD_SET_SIGNALS
:
780 return "CMD_SET_SIGNALS";
781 case CMD_CONFIGURE_TCK_FREQ
:
782 return "CMD_CONFIGURE_TCK_FREQ";
784 return "CMD_SET_LEDS";
788 return "CMD_UNKNOWN";
793 * Print one OpenULINK command to stdout.
795 * @param ulink_cmd pointer to OpenULINK command.
797 static void ulink_print_command(struct ulink_cmd
*ulink_cmd
)
801 printf(" %-22s | OUT size = %i, bytes = 0x",
802 ulink_cmd_id_string(ulink_cmd
->id
), ulink_cmd
->payload_out_size
);
804 for (i
= 0; i
< ulink_cmd
->payload_out_size
; i
++)
805 printf("%02X ", ulink_cmd
->payload_out
[i
]);
806 printf("\n | IN size = %i\n",
807 ulink_cmd
->payload_in_size
);
811 * Print the OpenULINK command queue to stdout.
813 * @param device pointer to struct ulink identifying ULINK driver instance.
815 static void ulink_print_queue(struct ulink
*device
)
817 struct ulink_cmd
*current
;
819 printf("OpenULINK command queue:\n");
821 for (current
= device
->queue_start
; current
; current
= current
->next
)
822 ulink_print_command(current
);
828 * Creates and appends a JTAG scan command to the OpenULINK command queue.
829 * A JTAG scan consists of three steps:
830 * - Move to the desired SHIFT state, depending on scan type (IR/DR scan).
831 * - Shift TDI data into the JTAG chain, optionally reading the TDO pin.
832 * - Move to the desired end state.
834 * @param device pointer to struct ulink identifying ULINK driver instance.
835 * @param scan_type the type of the scan (IN, OUT, IO (bidirectional)).
836 * @param scan_size_bits number of bits to shift into the JTAG chain.
837 * @param tdi pointer to array containing TDI data.
838 * @param tdo_start pointer to first element of array where TDO data shall be
839 * stored. See #ulink_cmd for details.
840 * @param tdo pointer to array where TDO data shall be stored
841 * @param tms_count_start number of TMS state transitions to perform BEFORE
842 * shifting data into the JTAG chain.
843 * @param tms_sequence_start sequence of TMS state transitions that will be
844 * performed BEFORE shifting data into the JTAG chain.
845 * @param tms_count_end number of TMS state transitions to perform AFTER
846 * shifting data into the JTAG chain.
847 * @param tms_sequence_end sequence of TMS state transitions that will be
848 * performed AFTER shifting data into the JTAG chain.
849 * @param origin pointer to OpenOCD command that generated this scan command.
850 * @param postprocess whether this command needs to be post-processed after
852 * @return on success: ERROR_OK
853 * @return on failure: ERROR_FAIL
855 static int ulink_append_scan_cmd(struct ulink
*device
, enum scan_type scan_type
,
856 int scan_size_bits
, uint8_t *tdi
, uint8_t *tdo_start
, uint8_t *tdo
,
857 uint8_t tms_count_start
, uint8_t tms_sequence_start
, uint8_t tms_count_end
,
858 uint8_t tms_sequence_end
, struct jtag_command
*origin
, bool postprocess
)
860 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
861 int ret
, i
, scan_size_bytes
;
862 uint8_t bits_last_byte
;
867 /* Check size of command. USB buffer can hold 64 bytes, 1 byte is command ID,
868 * 5 bytes are setup data -> 58 remaining payload bytes for TDI data */
869 if (scan_size_bits
> (58 * 8)) {
870 LOG_ERROR("BUG: Tried to create CMD_SCAN_IO OpenULINK command with too"
876 scan_size_bytes
= DIV_ROUND_UP(scan_size_bits
, 8);
878 bits_last_byte
= scan_size_bits
% 8;
879 if (bits_last_byte
== 0)
882 /* Allocate out_payload depending on scan type */
885 if (device
->delay_scan_in
< 0)
886 cmd
->id
= CMD_SCAN_IN
;
888 cmd
->id
= CMD_SLOW_SCAN_IN
;
889 ret
= ulink_allocate_payload(cmd
, 5, PAYLOAD_DIRECTION_OUT
);
892 if (device
->delay_scan_out
< 0)
893 cmd
->id
= CMD_SCAN_OUT
;
895 cmd
->id
= CMD_SLOW_SCAN_OUT
;
896 ret
= ulink_allocate_payload(cmd
, scan_size_bytes
+ 5, PAYLOAD_DIRECTION_OUT
);
899 if (device
->delay_scan_io
< 0)
900 cmd
->id
= CMD_SCAN_IO
;
902 cmd
->id
= CMD_SLOW_SCAN_IO
;
903 ret
= ulink_allocate_payload(cmd
, scan_size_bytes
+ 5, PAYLOAD_DIRECTION_OUT
);
906 LOG_ERROR("BUG: ulink_append_scan_cmd() encountered an unknown scan type");
911 if (ret
!= ERROR_OK
) {
916 /* Build payload_out that is common to all scan types */
917 cmd
->payload_out
[0] = scan_size_bytes
& 0xFF;
918 cmd
->payload_out
[1] = bits_last_byte
& 0xFF;
919 cmd
->payload_out
[2] = ((tms_count_start
& 0x0F) << 4) | (tms_count_end
& 0x0F);
920 cmd
->payload_out
[3] = tms_sequence_start
;
921 cmd
->payload_out
[4] = tms_sequence_end
;
923 /* Setup payload_out for types with OUT transfer */
924 if ((scan_type
== SCAN_OUT
) || (scan_type
== SCAN_IO
)) {
925 for (i
= 0; i
< scan_size_bytes
; i
++)
926 cmd
->payload_out
[i
+ 5] = tdi
[i
];
929 /* Setup payload_in pointers for types with IN transfer */
930 if ((scan_type
== SCAN_IN
) || (scan_type
== SCAN_IO
)) {
931 cmd
->payload_in_start
= tdo_start
;
932 cmd
->payload_in
= tdo
;
933 cmd
->payload_in_size
= scan_size_bytes
;
936 cmd
->needs_postprocessing
= postprocess
;
937 cmd
->cmd_origin
= origin
;
939 /* For scan commands, we free payload_in_start only when the command is
940 * the last in a series of split commands or a stand-alone command */
941 cmd
->free_payload_in_start
= postprocess
;
943 return ulink_append_queue(device
, cmd
);
947 * Perform TAP state transitions
949 * @param device pointer to struct ulink identifying ULINK driver instance.
950 * @param count defines the number of TCK clock cycles generated (up to 8).
951 * @param sequence defines the TMS pin levels for each state transition. The
952 * Least-Significant Bit is read first.
953 * @return on success: ERROR_OK
954 * @return on failure: ERROR_FAIL
956 static int ulink_append_clock_tms_cmd(struct ulink
*device
, uint8_t count
,
959 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
965 if (device
->delay_clock_tms
< 0)
966 cmd
->id
= CMD_CLOCK_TMS
;
968 cmd
->id
= CMD_SLOW_CLOCK_TMS
;
970 /* CMD_CLOCK_TMS has two OUT payload bytes and zero IN payload bytes */
971 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
972 if (ret
!= ERROR_OK
) {
977 cmd
->payload_out
[0] = count
;
978 cmd
->payload_out
[1] = sequence
;
980 return ulink_append_queue(device
, cmd
);
984 * Generate a defined amount of TCK clock cycles
986 * All other JTAG signals are left unchanged.
988 * @param device pointer to struct ulink identifying ULINK driver instance.
989 * @param count the number of TCK clock cycles to generate.
990 * @return on success: ERROR_OK
991 * @return on failure: ERROR_FAIL
993 static int ulink_append_clock_tck_cmd(struct ulink
*device
, uint16_t count
)
995 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1001 if (device
->delay_clock_tck
< 0)
1002 cmd
->id
= CMD_CLOCK_TCK
;
1004 cmd
->id
= CMD_SLOW_CLOCK_TCK
;
1006 /* CMD_CLOCK_TCK has two OUT payload bytes and zero IN payload bytes */
1007 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1008 if (ret
!= ERROR_OK
) {
1013 cmd
->payload_out
[0] = count
& 0xff;
1014 cmd
->payload_out
[1] = (count
>> 8) & 0xff;
1016 return ulink_append_queue(device
, cmd
);
1020 * Read JTAG signals.
1022 * @param device pointer to struct ulink identifying ULINK driver instance.
1023 * @return on success: ERROR_OK
1024 * @return on failure: ERROR_FAIL
1026 static int ulink_append_get_signals_cmd(struct ulink
*device
)
1028 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1034 cmd
->id
= CMD_GET_SIGNALS
;
1035 cmd
->needs_postprocessing
= true;
1037 /* CMD_GET_SIGNALS has two IN payload bytes */
1038 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_IN
);
1040 if (ret
!= ERROR_OK
) {
1045 return ulink_append_queue(device
, cmd
);
1049 * Arbitrarily set JTAG output signals.
1051 * @param device pointer to struct ulink identifying ULINK driver instance.
1052 * @param low defines which signals will be de-asserted. Each bit corresponds
1061 * @param high defines which signals will be asserted.
1062 * @return on success: ERROR_OK
1063 * @return on failure: ERROR_FAIL
1065 static int ulink_append_set_signals_cmd(struct ulink
*device
, uint8_t low
,
1068 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1074 cmd
->id
= CMD_SET_SIGNALS
;
1076 /* CMD_SET_SIGNALS has two OUT payload bytes and zero IN payload bytes */
1077 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1079 if (ret
!= ERROR_OK
) {
1084 cmd
->payload_out
[0] = low
;
1085 cmd
->payload_out
[1] = high
;
1087 return ulink_append_queue(device
, cmd
);
1091 * Sleep for a pre-defined number of microseconds
1093 * @param device pointer to struct ulink identifying ULINK driver instance.
1094 * @param us the number microseconds to sleep.
1095 * @return on success: ERROR_OK
1096 * @return on failure: ERROR_FAIL
1098 static int ulink_append_sleep_cmd(struct ulink
*device
, uint32_t us
)
1100 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1106 cmd
->id
= CMD_SLEEP_US
;
1108 /* CMD_SLEEP_US has two OUT payload bytes and zero IN payload bytes */
1109 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1111 if (ret
!= ERROR_OK
) {
1116 cmd
->payload_out
[0] = us
& 0x00ff;
1117 cmd
->payload_out
[1] = (us
>> 8) & 0x00ff;
1119 return ulink_append_queue(device
, cmd
);
1123 * Set TCK delay counters
1125 * @param device pointer to struct ulink identifying ULINK driver instance.
1126 * @param delay_scan_in delay count top value in jtag_slow_scan_in() function.
1127 * @param delay_scan_out delay count top value in jtag_slow_scan_out() function.
1128 * @param delay_scan_io delay count top value in jtag_slow_scan_io() function.
1129 * @param delay_tck delay count top value in jtag_clock_tck() function.
1130 * @param delay_tms delay count top value in jtag_slow_clock_tms() function.
1131 * @return on success: ERROR_OK
1132 * @return on failure: ERROR_FAIL
1134 static int ulink_append_configure_tck_cmd(struct ulink
*device
, int delay_scan_in
,
1135 int delay_scan_out
, int delay_scan_io
, int delay_tck
, int delay_tms
)
1137 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1143 cmd
->id
= CMD_CONFIGURE_TCK_FREQ
;
1145 /* CMD_CONFIGURE_TCK_FREQ has five OUT payload bytes and zero
1146 * IN payload bytes */
1147 ret
= ulink_allocate_payload(cmd
, 5, PAYLOAD_DIRECTION_OUT
);
1148 if (ret
!= ERROR_OK
) {
1153 if (delay_scan_in
< 0)
1154 cmd
->payload_out
[0] = 0;
1156 cmd
->payload_out
[0] = (uint8_t)delay_scan_in
;
1158 if (delay_scan_out
< 0)
1159 cmd
->payload_out
[1] = 0;
1161 cmd
->payload_out
[1] = (uint8_t)delay_scan_out
;
1163 if (delay_scan_io
< 0)
1164 cmd
->payload_out
[2] = 0;
1166 cmd
->payload_out
[2] = (uint8_t)delay_scan_io
;
1169 cmd
->payload_out
[3] = 0;
1171 cmd
->payload_out
[3] = (uint8_t)delay_tck
;
1174 cmd
->payload_out
[4] = 0;
1176 cmd
->payload_out
[4] = (uint8_t)delay_tms
;
1178 return ulink_append_queue(device
, cmd
);
1182 * Turn on/off ULINK LEDs.
1184 * @param device pointer to struct ulink identifying ULINK driver instance.
1185 * @param led_state which LED(s) to turn on or off. The following bits
1186 * influence the LEDS:
1187 * - Bit 0: Turn COM LED on
1188 * - Bit 1: Turn RUN LED on
1189 * - Bit 2: Turn COM LED off
1190 * - Bit 3: Turn RUN LED off
1191 * If both the on-bit and the off-bit for the same LED is set, the LED is
1193 * @return on success: ERROR_OK
1194 * @return on failure: ERROR_FAIL
1196 static int ulink_append_led_cmd(struct ulink
*device
, uint8_t led_state
)
1198 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1204 cmd
->id
= CMD_SET_LEDS
;
1206 /* CMD_SET_LEDS has one OUT payload byte and zero IN payload bytes */
1207 ret
= ulink_allocate_payload(cmd
, 1, PAYLOAD_DIRECTION_OUT
);
1208 if (ret
!= ERROR_OK
) {
1213 cmd
->payload_out
[0] = led_state
;
1215 return ulink_append_queue(device
, cmd
);
1219 * Test command. Used to check if the ULINK device is ready to accept new
1222 * @param device pointer to struct ulink identifying ULINK driver instance.
1223 * @return on success: ERROR_OK
1224 * @return on failure: ERROR_FAIL
1226 static int ulink_append_test_cmd(struct ulink
*device
)
1228 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1236 /* CMD_TEST has one OUT payload byte and zero IN payload bytes */
1237 ret
= ulink_allocate_payload(cmd
, 1, PAYLOAD_DIRECTION_OUT
);
1238 if (ret
!= ERROR_OK
) {
1243 cmd
->payload_out
[0] = 0xAA;
1245 return ulink_append_queue(device
, cmd
);
1248 /****************** OpenULINK TCK frequency helper functions ******************/
1251 * Calculate delay values for a given TCK frequency.
1253 * The OpenULINK firmware uses five different speed values for different
1254 * commands. These speed values are calculated in these functions.
1256 * The five different commands which support variable TCK frequency are
1257 * implemented twice in the firmware:
1258 * 1. Maximum possible frequency without any artificial delay
1259 * 2. Variable frequency with artificial linear delay loop
1261 * To set the ULINK to maximum frequency, it is only necessary to use the
1262 * corresponding command IDs. To set the ULINK to a lower frequency, the
1263 * delay loop top values have to be calculated first. Then, a
1264 * CMD_CONFIGURE_TCK_FREQ command needs to be sent to the ULINK device.
1266 * The delay values are described by linear equations:
1268 * (t = period, k = constant, x = delay value, d = constant)
1270 * Thus, the delay can be calculated as in the following equation:
1273 * The constants in these equations have been determined and validated by
1274 * measuring the frequency resulting from different delay values.
1276 * @param type for which command to calculate the delay value.
1277 * @param f TCK frequency for which to calculate the delay value in Hz.
1278 * @param delay where to store resulting delay value.
1279 * @return on success: ERROR_OK
1280 * @return on failure: ERROR_FAIL
1282 static int ulink_calculate_delay(enum ulink_delay_type type
, long f
, int *delay
)
1286 /* Calculate period of requested TCK frequency */
1287 t
= 1.0 / (float)(f
);
1290 case DELAY_CLOCK_TCK
:
1291 x
= (t
- (float)(6E-6)) / (float)(4E-6);
1293 case DELAY_CLOCK_TMS
:
1294 x
= (t
- (float)(8.5E-6)) / (float)(4E-6);
1297 x
= (t
- (float)(8.8308E-6)) / (float)(4E-6);
1299 case DELAY_SCAN_OUT
:
1300 x
= (t
- (float)(1.0527E-5)) / (float)(4E-6);
1303 x
= (t
- (float)(1.3132E-5)) / (float)(4E-6);
1310 /* Check if the delay value is negative. This happens when a frequency is
1311 * requested that is too high for the delay loop implementation. In this
1312 * case, set delay value to zero. */
1316 /* We need to convert the exact delay value to an integer. Therefore, we
1317 * round the exact value UP to ensure that the resulting frequency is NOT
1318 * higher than the requested frequency. */
1321 /* Check if the value is within limits */
1325 *delay
= (int)x_ceil
;
1331 * Calculate frequency for a given delay value.
1333 * Similar to the #ulink_calculate_delay function, this function calculates the
1334 * TCK frequency for a given delay value by using linear equations of the form:
1336 * (t = period, k = constant, x = delay value, d = constant)
1338 * @param type for which command to calculate the delay value.
1339 * @param delay delay value for which to calculate the resulting TCK frequency.
1340 * @return the resulting TCK frequency
1342 static long ulink_calculate_frequency(enum ulink_delay_type type
, int delay
)
1350 case DELAY_CLOCK_TCK
:
1352 t
= (float)(2.666E-6);
1354 t
= (float)(4E-6) * (float)(delay
) + (float)(6E-6);
1356 case DELAY_CLOCK_TMS
:
1358 t
= (float)(5.666E-6);
1360 t
= (float)(4E-6) * (float)(delay
) + (float)(8.5E-6);
1364 t
= (float)(5.5E-6);
1366 t
= (float)(4E-6) * (float)(delay
) + (float)(8.8308E-6);
1368 case DELAY_SCAN_OUT
:
1370 t
= (float)(7.0E-6);
1372 t
= (float)(4E-6) * (float)(delay
) + (float)(1.0527E-5);
1376 t
= (float)(9.926E-6);
1378 t
= (float)(4E-6) * (float)(delay
) + (float)(1.3132E-5);
1385 return roundf(f_float
);
1388 /******************* Interface between OpenULINK and OpenOCD ******************/
1391 * Sets the end state follower (see interface.h) if \a endstate is a stable
1394 * @param endstate the state the end state follower should be set to.
1396 static void ulink_set_end_state(tap_state_t endstate
)
1398 if (tap_is_state_stable(endstate
))
1399 tap_set_end_state(endstate
);
1401 LOG_ERROR("BUG: %s is not a valid end state", tap_state_name(endstate
));
1407 * Move from the current TAP state to the current TAP end state.
1409 * @param device pointer to struct ulink identifying ULINK driver instance.
1410 * @return on success: ERROR_OK
1411 * @return on failure: ERROR_FAIL
1413 static int ulink_queue_statemove(struct ulink
*device
)
1415 uint8_t tms_sequence
, tms_count
;
1418 if (tap_get_state() == tap_get_end_state()) {
1419 /* Do nothing if we are already there */
1423 tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1424 tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1426 ret
= ulink_append_clock_tms_cmd(device
, tms_count
, tms_sequence
);
1428 if (ret
== ERROR_OK
)
1429 tap_set_state(tap_get_end_state());
1435 * Perform a scan operation on a JTAG register.
1437 * @param device pointer to struct ulink identifying ULINK driver instance.
1438 * @param cmd pointer to the command that shall be executed.
1439 * @return on success: ERROR_OK
1440 * @return on failure: ERROR_FAIL
1442 static int ulink_queue_scan(struct ulink
*device
, struct jtag_command
*cmd
)
1444 uint32_t scan_size_bits
, scan_size_bytes
, bits_last_scan
;
1445 uint32_t scans_max_payload
, bytecount
;
1446 uint8_t *tdi_buffer_start
= NULL
, *tdi_buffer
= NULL
;
1447 uint8_t *tdo_buffer_start
= NULL
, *tdo_buffer
= NULL
;
1449 uint8_t first_tms_count
, first_tms_sequence
;
1450 uint8_t last_tms_count
, last_tms_sequence
;
1452 uint8_t tms_count_pause
, tms_sequence_pause
;
1453 uint8_t tms_count_resume
, tms_sequence_resume
;
1455 uint8_t tms_count_start
, tms_sequence_start
;
1456 uint8_t tms_count_end
, tms_sequence_end
;
1458 enum scan_type type
;
1461 /* Determine scan size */
1462 scan_size_bits
= jtag_scan_size(cmd
->cmd
.scan
);
1463 scan_size_bytes
= DIV_ROUND_UP(scan_size_bits
, 8);
1465 /* Determine scan type (IN/OUT/IO) */
1466 type
= jtag_scan_type(cmd
->cmd
.scan
);
1468 /* Determine number of scan commands with maximum payload */
1469 scans_max_payload
= scan_size_bytes
/ 58;
1471 /* Determine size of last shift command */
1472 bits_last_scan
= scan_size_bits
- (scans_max_payload
* 58 * 8);
1474 /* Allocate TDO buffer if required */
1475 if ((type
== SCAN_IN
) || (type
== SCAN_IO
)) {
1476 tdo_buffer_start
= calloc(sizeof(uint8_t), scan_size_bytes
);
1478 if (!tdo_buffer_start
)
1481 tdo_buffer
= tdo_buffer_start
;
1484 /* Fill TDI buffer if required */
1485 if ((type
== SCAN_OUT
) || (type
== SCAN_IO
)) {
1486 jtag_build_buffer(cmd
->cmd
.scan
, &tdi_buffer_start
);
1487 tdi_buffer
= tdi_buffer_start
;
1490 /* Get TAP state transitions */
1491 if (cmd
->cmd
.scan
->ir_scan
) {
1492 ulink_set_end_state(TAP_IRSHIFT
);
1493 first_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1494 first_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1496 tap_set_state(TAP_IRSHIFT
);
1497 tap_set_end_state(cmd
->cmd
.scan
->end_state
);
1498 last_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1499 last_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1501 /* TAP state transitions for split scans */
1502 tms_count_pause
= tap_get_tms_path_len(TAP_IRSHIFT
, TAP_IRPAUSE
);
1503 tms_sequence_pause
= tap_get_tms_path(TAP_IRSHIFT
, TAP_IRPAUSE
);
1504 tms_count_resume
= tap_get_tms_path_len(TAP_IRPAUSE
, TAP_IRSHIFT
);
1505 tms_sequence_resume
= tap_get_tms_path(TAP_IRPAUSE
, TAP_IRSHIFT
);
1507 ulink_set_end_state(TAP_DRSHIFT
);
1508 first_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1509 first_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1511 tap_set_state(TAP_DRSHIFT
);
1512 tap_set_end_state(cmd
->cmd
.scan
->end_state
);
1513 last_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1514 last_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1516 /* TAP state transitions for split scans */
1517 tms_count_pause
= tap_get_tms_path_len(TAP_DRSHIFT
, TAP_DRPAUSE
);
1518 tms_sequence_pause
= tap_get_tms_path(TAP_DRSHIFT
, TAP_DRPAUSE
);
1519 tms_count_resume
= tap_get_tms_path_len(TAP_DRPAUSE
, TAP_DRSHIFT
);
1520 tms_sequence_resume
= tap_get_tms_path(TAP_DRPAUSE
, TAP_DRSHIFT
);
1523 /* Generate scan commands */
1524 bytecount
= scan_size_bytes
;
1525 while (bytecount
> 0) {
1526 if (bytecount
== scan_size_bytes
) {
1527 /* This is the first scan */
1528 tms_count_start
= first_tms_count
;
1529 tms_sequence_start
= first_tms_sequence
;
1531 /* Resume from previous scan */
1532 tms_count_start
= tms_count_resume
;
1533 tms_sequence_start
= tms_sequence_resume
;
1536 if (bytecount
> 58) { /* Full scan, at least one scan will follow */
1537 tms_count_end
= tms_count_pause
;
1538 tms_sequence_end
= tms_sequence_pause
;
1540 ret
= ulink_append_scan_cmd(device
,
1555 /* Update TDI and TDO buffer pointers */
1556 if (tdi_buffer_start
)
1558 if (tdo_buffer_start
)
1560 } else if (bytecount
== 58) { /* Full scan, no further scans */
1561 tms_count_end
= last_tms_count
;
1562 tms_sequence_end
= last_tms_sequence
;
1564 ret
= ulink_append_scan_cmd(device
,
1578 } else {/* Scan with less than maximum payload, no further scans */
1579 tms_count_end
= last_tms_count
;
1580 tms_sequence_end
= last_tms_sequence
;
1582 ret
= ulink_append_scan_cmd(device
,
1598 if (ret
!= ERROR_OK
) {
1599 free(tdi_buffer_start
);
1600 free(tdo_buffer_start
);
1605 free(tdi_buffer_start
);
1607 /* Set current state to the end state requested by the command */
1608 tap_set_state(cmd
->cmd
.scan
->end_state
);
1614 * Move the TAP into the Test Logic Reset state.
1616 * @param device pointer to struct ulink identifying ULINK driver instance.
1617 * @param cmd pointer to the command that shall be executed.
1618 * @return on success: ERROR_OK
1619 * @return on failure: ERROR_FAIL
1621 static int ulink_queue_tlr_reset(struct ulink
*device
, struct jtag_command
*cmd
)
1625 ret
= ulink_append_clock_tms_cmd(device
, 5, 0xff);
1627 if (ret
== ERROR_OK
)
1628 tap_set_state(TAP_RESET
);
1636 * Generate TCK clock cycles while remaining
1637 * in the Run-Test/Idle state.
1639 * @param device pointer to struct ulink identifying ULINK driver instance.
1640 * @param cmd pointer to the command that shall be executed.
1641 * @return on success: ERROR_OK
1642 * @return on failure: ERROR_FAIL
1644 static int ulink_queue_runtest(struct ulink
*device
, struct jtag_command
*cmd
)
1648 /* Only perform statemove if the TAP currently isn't in the TAP_IDLE state */
1649 if (tap_get_state() != TAP_IDLE
) {
1650 ulink_set_end_state(TAP_IDLE
);
1651 ulink_queue_statemove(device
);
1654 /* Generate the clock cycles */
1655 ret
= ulink_append_clock_tck_cmd(device
, cmd
->cmd
.runtest
->num_cycles
);
1656 if (ret
!= ERROR_OK
)
1659 /* Move to end state specified in command */
1660 if (cmd
->cmd
.runtest
->end_state
!= tap_get_state()) {
1661 tap_set_end_state(cmd
->cmd
.runtest
->end_state
);
1662 ulink_queue_statemove(device
);
1669 * Execute a JTAG_RESET command
1672 * @param cmd pointer to the command that shall be executed.
1673 * @return on success: ERROR_OK
1674 * @return on failure: ERROR_FAIL
1676 static int ulink_queue_reset(struct ulink
*device
, struct jtag_command
*cmd
)
1678 uint8_t low
= 0, high
= 0;
1680 if (cmd
->cmd
.reset
->trst
) {
1681 tap_set_state(TAP_RESET
);
1682 high
|= SIGNAL_TRST
;
1686 if (cmd
->cmd
.reset
->srst
)
1687 high
|= SIGNAL_RESET
;
1689 low
|= SIGNAL_RESET
;
1691 return ulink_append_set_signals_cmd(device
, low
, high
);
1695 * Move to one TAP state or several states in succession.
1697 * @param device pointer to struct ulink identifying ULINK driver instance.
1698 * @param cmd pointer to the command that shall be executed.
1699 * @return on success: ERROR_OK
1700 * @return on failure: ERROR_FAIL
1702 static int ulink_queue_pathmove(struct ulink
*device
, struct jtag_command
*cmd
)
1704 int ret
, i
, num_states
, batch_size
, state_count
;
1706 uint8_t tms_sequence
;
1708 num_states
= cmd
->cmd
.pathmove
->num_states
;
1709 path
= cmd
->cmd
.pathmove
->path
;
1712 while (num_states
> 0) {
1715 /* Determine batch size */
1716 if (num_states
>= 8)
1719 batch_size
= num_states
;
1721 for (i
= 0; i
< batch_size
; i
++) {
1722 if (tap_state_transition(tap_get_state(), false) == path
[state_count
]) {
1723 /* Append '0' transition: clear bit 'i' in tms_sequence */
1724 buf_set_u32(&tms_sequence
, i
, 1, 0x0);
1725 } else if (tap_state_transition(tap_get_state(), true)
1726 == path
[state_count
]) {
1727 /* Append '1' transition: set bit 'i' in tms_sequence */
1728 buf_set_u32(&tms_sequence
, i
, 1, 0x1);
1730 /* Invalid state transition */
1731 LOG_ERROR("BUG: %s -> %s isn't a valid TAP state transition",
1732 tap_state_name(tap_get_state()),
1733 tap_state_name(path
[state_count
]));
1737 tap_set_state(path
[state_count
]);
1742 /* Append CLOCK_TMS command to OpenULINK command queue */
1744 "pathmove batch: count = %i, sequence = 0x%x", batch_size
, tms_sequence
);
1745 ret
= ulink_append_clock_tms_cmd(ulink_handle
, batch_size
, tms_sequence
);
1746 if (ret
!= ERROR_OK
)
1754 * Sleep for a specific amount of time.
1756 * @param device pointer to struct ulink identifying ULINK driver instance.
1757 * @param cmd pointer to the command that shall be executed.
1758 * @return on success: ERROR_OK
1759 * @return on failure: ERROR_FAIL
1761 static int ulink_queue_sleep(struct ulink
*device
, struct jtag_command
*cmd
)
1763 /* IMPORTANT! Due to the time offset in command execution introduced by
1764 * command queueing, this needs to be implemented in the ULINK device */
1765 return ulink_append_sleep_cmd(device
, cmd
->cmd
.sleep
->us
);
1769 * Generate TCK cycles while remaining in a stable state.
1771 * @param device pointer to struct ulink identifying ULINK driver instance.
1772 * @param cmd pointer to the command that shall be executed.
1774 static int ulink_queue_stableclocks(struct ulink
*device
, struct jtag_command
*cmd
)
1777 unsigned num_cycles
;
1779 if (!tap_is_state_stable(tap_get_state())) {
1780 LOG_ERROR("JTAG_STABLECLOCKS: state not stable");
1784 num_cycles
= cmd
->cmd
.stableclocks
->num_cycles
;
1786 /* TMS stays either high (Test Logic Reset state) or low (all other states) */
1787 if (tap_get_state() == TAP_RESET
)
1788 ret
= ulink_append_set_signals_cmd(device
, 0, SIGNAL_TMS
);
1790 ret
= ulink_append_set_signals_cmd(device
, SIGNAL_TMS
, 0);
1792 if (ret
!= ERROR_OK
)
1795 while (num_cycles
> 0) {
1796 if (num_cycles
> 0xFFFF) {
1797 /* OpenULINK CMD_CLOCK_TCK can generate up to 0xFFFF (uint16_t) cycles */
1798 ret
= ulink_append_clock_tck_cmd(device
, 0xFFFF);
1799 num_cycles
-= 0xFFFF;
1801 ret
= ulink_append_clock_tck_cmd(device
, num_cycles
);
1805 if (ret
!= ERROR_OK
)
1813 * Post-process JTAG_SCAN command
1815 * @param ulink_cmd pointer to OpenULINK command that shall be processed.
1816 * @return on success: ERROR_OK
1817 * @return on failure: ERROR_FAIL
1819 static int ulink_post_process_scan(struct ulink_cmd
*ulink_cmd
)
1821 struct jtag_command
*cmd
= ulink_cmd
->cmd_origin
;
1824 switch (jtag_scan_type(cmd
->cmd
.scan
)) {
1827 ret
= jtag_read_buffer(ulink_cmd
->payload_in_start
, cmd
->cmd
.scan
);
1830 /* Nothing to do for OUT scans */
1834 LOG_ERROR("BUG: ulink_post_process_scan() encountered an unknown"
1844 * Perform post-processing of commands after OpenULINK queue has been executed.
1846 * @param device pointer to struct ulink identifying ULINK driver instance.
1847 * @return on success: ERROR_OK
1848 * @return on failure: ERROR_FAIL
1850 static int ulink_post_process_queue(struct ulink
*device
)
1852 struct ulink_cmd
*current
;
1853 struct jtag_command
*openocd_cmd
;
1856 current
= device
->queue_start
;
1859 openocd_cmd
= current
->cmd_origin
;
1861 /* Check if a corresponding OpenOCD command is stored for this
1862 * OpenULINK command */
1863 if ((current
->needs_postprocessing
== true) && (openocd_cmd
)) {
1864 switch (openocd_cmd
->type
) {
1866 ret
= ulink_post_process_scan(current
);
1868 case JTAG_TLR_RESET
:
1873 case JTAG_STABLECLOCKS
:
1874 /* Nothing to do for these commands */
1879 LOG_ERROR("BUG: ulink_post_process_queue() encountered unknown JTAG "
1884 if (ret
!= ERROR_OK
)
1888 current
= current
->next
;
1894 /**************************** JTAG driver functions ***************************/
1897 * Executes the JTAG Command Queue.
1899 * This is done in three stages: First, all OpenOCD commands are processed into
1900 * queued OpenULINK commands. Next, the OpenULINK command queue is sent to the
1901 * ULINK device and data received from the ULINK device is cached. Finally,
1902 * the post-processing function writes back data to the corresponding OpenOCD
1905 * @return on success: ERROR_OK
1906 * @return on failure: ERROR_FAIL
1908 static int ulink_execute_queue(void)
1910 struct jtag_command
*cmd
= jtag_command_queue
;
1914 switch (cmd
->type
) {
1916 ret
= ulink_queue_scan(ulink_handle
, cmd
);
1918 case JTAG_TLR_RESET
:
1919 ret
= ulink_queue_tlr_reset(ulink_handle
, cmd
);
1922 ret
= ulink_queue_runtest(ulink_handle
, cmd
);
1925 ret
= ulink_queue_reset(ulink_handle
, cmd
);
1928 ret
= ulink_queue_pathmove(ulink_handle
, cmd
);
1931 ret
= ulink_queue_sleep(ulink_handle
, cmd
);
1933 case JTAG_STABLECLOCKS
:
1934 ret
= ulink_queue_stableclocks(ulink_handle
, cmd
);
1938 LOG_ERROR("BUG: encountered unknown JTAG command type");
1942 if (ret
!= ERROR_OK
)
1948 if (ulink_handle
->commands_in_queue
> 0) {
1949 ret
= ulink_execute_queued_commands(ulink_handle
, LIBUSB_TIMEOUT_MS
);
1950 if (ret
!= ERROR_OK
)
1953 ret
= ulink_post_process_queue(ulink_handle
);
1954 if (ret
!= ERROR_OK
)
1957 ulink_clear_queue(ulink_handle
);
1964 * Set the TCK frequency of the ULINK adapter.
1966 * @param khz desired JTAG TCK frequency.
1967 * @param jtag_speed where to store corresponding adapter-specific speed value.
1968 * @return on success: ERROR_OK
1969 * @return on failure: ERROR_FAIL
1971 static int ulink_khz(int khz
, int *jtag_speed
)
1976 LOG_ERROR("RCLK not supported");
1980 /* CLOCK_TCK commands are decoupled from others. Therefore, the frequency
1981 * setting can be done independently from all other commands. */
1983 ulink_handle
->delay_clock_tck
= -1;
1985 ret
= ulink_calculate_delay(DELAY_CLOCK_TCK
, khz
* 1000,
1986 &ulink_handle
->delay_clock_tck
);
1987 if (ret
!= ERROR_OK
)
1991 /* SCAN_{IN,OUT,IO} commands invoke CLOCK_TMS commands. Therefore, if the
1992 * requested frequency goes below the maximum frequency for SLOW_CLOCK_TMS
1993 * commands, all SCAN commands MUST also use the variable frequency
1994 * implementation! */
1996 ulink_handle
->delay_clock_tms
= -1;
1997 ulink_handle
->delay_scan_in
= -1;
1998 ulink_handle
->delay_scan_out
= -1;
1999 ulink_handle
->delay_scan_io
= -1;
2001 ret
= ulink_calculate_delay(DELAY_CLOCK_TMS
, khz
* 1000,
2002 &ulink_handle
->delay_clock_tms
);
2003 if (ret
!= ERROR_OK
)
2006 ret
= ulink_calculate_delay(DELAY_SCAN_IN
, khz
* 1000,
2007 &ulink_handle
->delay_scan_in
);
2008 if (ret
!= ERROR_OK
)
2011 ret
= ulink_calculate_delay(DELAY_SCAN_OUT
, khz
* 1000,
2012 &ulink_handle
->delay_scan_out
);
2013 if (ret
!= ERROR_OK
)
2016 ret
= ulink_calculate_delay(DELAY_SCAN_IO
, khz
* 1000,
2017 &ulink_handle
->delay_scan_io
);
2018 if (ret
!= ERROR_OK
)
2022 LOG_DEBUG_IO("ULINK TCK setup: delay_tck = %i (%li Hz),",
2023 ulink_handle
->delay_clock_tck
,
2024 ulink_calculate_frequency(DELAY_CLOCK_TCK
, ulink_handle
->delay_clock_tck
));
2025 LOG_DEBUG_IO(" delay_tms = %i (%li Hz),",
2026 ulink_handle
->delay_clock_tms
,
2027 ulink_calculate_frequency(DELAY_CLOCK_TMS
, ulink_handle
->delay_clock_tms
));
2028 LOG_DEBUG_IO(" delay_scan_in = %i (%li Hz),",
2029 ulink_handle
->delay_scan_in
,
2030 ulink_calculate_frequency(DELAY_SCAN_IN
, ulink_handle
->delay_scan_in
));
2031 LOG_DEBUG_IO(" delay_scan_out = %i (%li Hz),",
2032 ulink_handle
->delay_scan_out
,
2033 ulink_calculate_frequency(DELAY_SCAN_OUT
, ulink_handle
->delay_scan_out
));
2034 LOG_DEBUG_IO(" delay_scan_io = %i (%li Hz),",
2035 ulink_handle
->delay_scan_io
,
2036 ulink_calculate_frequency(DELAY_SCAN_IO
, ulink_handle
->delay_scan_io
));
2038 /* Configure the ULINK device with the new delay values */
2039 ret
= ulink_append_configure_tck_cmd(ulink_handle
,
2040 ulink_handle
->delay_scan_in
,
2041 ulink_handle
->delay_scan_out
,
2042 ulink_handle
->delay_scan_io
,
2043 ulink_handle
->delay_clock_tck
,
2044 ulink_handle
->delay_clock_tms
);
2046 if (ret
!= ERROR_OK
)
2055 * Set the TCK frequency of the ULINK adapter.
2057 * Because of the way the TCK frequency is set up in the OpenULINK firmware,
2058 * there are five different speed settings. To simplify things, the
2059 * adapter-specific speed setting value is identical to the TCK frequency in
2062 * @param speed desired adapter-specific speed value.
2063 * @return on success: ERROR_OK
2064 * @return on failure: ERROR_FAIL
2066 static int ulink_speed(int speed
)
2070 return ulink_khz(speed
, &dummy
);
2074 * Convert adapter-specific speed value to corresponding TCK frequency in kHz.
2076 * Because of the way the TCK frequency is set up in the OpenULINK firmware,
2077 * there are five different speed settings. To simplify things, the
2078 * adapter-specific speed setting value is identical to the TCK frequency in
2081 * @param speed adapter-specific speed value.
2082 * @param khz where to store corresponding TCK frequency in kHz.
2083 * @return on success: ERROR_OK
2084 * @return on failure: ERROR_FAIL
2086 static int ulink_speed_div(int speed
, int *khz
)
2094 * Initiates the firmware download to the ULINK adapter and prepares
2097 * @return on success: ERROR_OK
2098 * @return on failure: ERROR_FAIL
2100 static int ulink_init(void)
2102 int ret
, transferred
;
2103 char str_manufacturer
[20];
2104 bool download_firmware
= false;
2105 unsigned char *dummy
;
2106 uint8_t input_signals
, output_signals
;
2108 ulink_handle
= calloc(1, sizeof(struct ulink
));
2112 libusb_init(&ulink_handle
->libusb_ctx
);
2114 ret
= ulink_usb_open(&ulink_handle
);
2115 if (ret
!= ERROR_OK
) {
2116 LOG_ERROR("Could not open ULINK device");
2118 ulink_handle
= NULL
;
2122 /* Get String Descriptor to determine if firmware needs to be loaded */
2123 ret
= libusb_get_string_descriptor_ascii(ulink_handle
->usb_device_handle
, 1, (unsigned char *)str_manufacturer
, 20);
2125 /* Could not get descriptor -> Unconfigured or original Keil firmware */
2126 download_firmware
= true;
2128 /* We got a String Descriptor, check if it is the correct one */
2129 if (strncmp(str_manufacturer
, "OpenULINK", 9) != 0)
2130 download_firmware
= true;
2133 if (download_firmware
== true) {
2134 LOG_INFO("Loading OpenULINK firmware. This is reversible by power-cycling"
2136 ret
= ulink_load_firmware_and_renumerate(&ulink_handle
,
2137 ULINK_FIRMWARE_FILE
, ULINK_RENUMERATION_DELAY
);
2138 if (ret
!= ERROR_OK
) {
2139 LOG_ERROR("Could not download firmware and re-numerate ULINK");
2141 ulink_handle
= NULL
;
2145 LOG_INFO("ULINK device is already running OpenULINK firmware");
2147 /* Get OpenULINK USB IN/OUT endpoints and claim the interface */
2148 ret
= jtag_libusb_choose_interface(ulink_handle
->usb_device_handle
,
2149 &ulink_handle
->ep_in
, &ulink_handle
->ep_out
, -1, -1, -1, -1);
2150 if (ret
!= ERROR_OK
)
2153 /* Initialize OpenULINK command queue */
2154 ulink_clear_queue(ulink_handle
);
2156 /* Issue one test command with short timeout */
2157 ret
= ulink_append_test_cmd(ulink_handle
);
2158 if (ret
!= ERROR_OK
)
2161 ret
= ulink_execute_queued_commands(ulink_handle
, 200);
2162 if (ret
!= ERROR_OK
) {
2163 /* Sending test command failed. The ULINK device may be forever waiting for
2164 * the host to fetch an USB Bulk IN packet (e. g. OpenOCD crashed or was
2165 * shut down by the user via Ctrl-C. Try to retrieve this Bulk IN packet. */
2166 dummy
= calloc(64, sizeof(uint8_t));
2168 ret
= libusb_bulk_transfer(ulink_handle
->usb_device_handle
, ulink_handle
->ep_in
,
2169 dummy
, 64, &transferred
, 200);
2173 if (ret
!= 0 || transferred
== 0) {
2174 /* Bulk IN transfer failed -> unrecoverable error condition */
2175 LOG_ERROR("Cannot communicate with ULINK device. Disconnect ULINK from "
2176 "the USB port and re-connect, then re-run OpenOCD");
2178 ulink_handle
= NULL
;
2181 #ifdef _DEBUG_USB_COMMS_
2183 /* Successfully received Bulk IN packet -> continue */
2184 LOG_INFO("Recovered from lost Bulk IN packet");
2188 ulink_clear_queue(ulink_handle
);
2190 ret
= ulink_append_get_signals_cmd(ulink_handle
);
2191 if (ret
== ERROR_OK
)
2192 ret
= ulink_execute_queued_commands(ulink_handle
, 200);
2194 if (ret
== ERROR_OK
) {
2195 /* Post-process the single CMD_GET_SIGNALS command */
2196 input_signals
= ulink_handle
->queue_start
->payload_in
[0];
2197 output_signals
= ulink_handle
->queue_start
->payload_in
[1];
2199 ulink_print_signal_states(input_signals
, output_signals
);
2202 ulink_clear_queue(ulink_handle
);
2208 * Closes the USB handle for the ULINK device.
2210 * @return on success: ERROR_OK
2211 * @return on failure: ERROR_FAIL
2213 static int ulink_quit(void)
2217 ret
= ulink_usb_close(&ulink_handle
);
2224 * Set a custom path to ULINK firmware image and force downloading to ULINK.
2226 COMMAND_HANDLER(ulink_download_firmware_handler
)
2231 return ERROR_COMMAND_SYNTAX_ERROR
;
2234 LOG_INFO("Downloading ULINK firmware image %s", CMD_ARGV
[0]);
2236 /* Download firmware image in CMD_ARGV[0] */
2237 ret
= ulink_load_firmware_and_renumerate(&ulink_handle
, CMD_ARGV
[0],
2238 ULINK_RENUMERATION_DELAY
);
2243 /*************************** Command Registration **************************/
2245 static const struct command_registration ulink_subcommand_handlers
[] = {
2247 .name
= "download_firmware",
2248 .handler
= &ulink_download_firmware_handler
,
2249 .mode
= COMMAND_EXEC
,
2250 .help
= "download firmware image to ULINK device",
2251 .usage
= "path/to/ulink_firmware.hex",
2253 COMMAND_REGISTRATION_DONE
,
2256 static const struct command_registration ulink_command_handlers
[] = {
2259 .mode
= COMMAND_ANY
,
2260 .help
= "perform ulink management",
2261 .chain
= ulink_subcommand_handlers
,
2264 COMMAND_REGISTRATION_DONE
2267 static struct jtag_interface ulink_interface
= {
2268 .execute_queue
= ulink_execute_queue
,
2271 struct adapter_driver ulink_adapter_driver
= {
2273 .transports
= jtag_only
,
2274 .commands
= ulink_command_handlers
,
2278 .speed
= ulink_speed
,
2280 .speed_div
= ulink_speed_div
,
2282 .jtag_ops
= &ulink_interface
,
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)