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 ***************************************************************************/
26 #include <jtag/interface.h>
27 #include <jtag/commands.h>
28 #include <target/image.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 */
76 /** Original ULINK adapter, based on Cypress EZ-USB (AN2131):
77 * Full JTAG support, no SWD support. */
80 /** Newer ULINK adapter, based on NXP LPC2148. Currently unsupported. */
83 /** Newer ULINK adapter, based on EZ-USB FX2 + FPGA. Currently unsupported. */
86 /** Newer ULINK adapter, possibly based on ULINK 2. Currently unsupported. */
90 enum ulink_payload_direction
{
91 PAYLOAD_DIRECTION_OUT
,
95 enum ulink_delay_type
{
104 * OpenULINK command (OpenULINK command queue element).
106 * For the OUT direction payload, things are quite easy: Payload is stored
107 * in a rather small array (up to 63 bytes), the payload is always allocated
108 * by the function generating the command and freed by ulink_clear_queue().
110 * For the IN direction payload, things get a little bit more complicated:
111 * The maximum IN payload size for a single command is 64 bytes. Assume that
112 * a single OpenOCD command needs to scan 256 bytes. This results in the
113 * generation of four OpenULINK commands. The function generating these
114 * commands shall allocate an uint8_t[256] array. Each command's #payload_in
115 * pointer shall point to the corresponding offset where IN data shall be
116 * placed, while #payload_in_start shall point to the first element of the 256
118 * - first command: #payload_in_start + 0
119 * - second command: #payload_in_start + 64
120 * - third command: #payload_in_start + 128
121 * - fourth command: #payload_in_start + 192
123 * The last command sets #needs_postprocessing to true.
126 uint8_t id
; /* /< ULINK command ID */
128 uint8_t *payload_out
; /* /< OUT direction payload data */
129 uint8_t payload_out_size
; /* /< OUT direction payload size for this command */
131 uint8_t *payload_in_start
; /* /< Pointer to first element of IN payload array */
132 uint8_t *payload_in
; /* /< Pointer where IN payload shall be stored */
133 uint8_t payload_in_size
;/* /< IN direction payload size for this command */
135 /** Indicates if this command needs post-processing */
136 bool needs_postprocessing
;
138 /** Indicates if ulink_clear_queue() should free payload_in_start */
139 bool free_payload_in_start
;
141 /** Pointer to corresponding OpenOCD command for post-processing */
142 struct jtag_command
*cmd_origin
;
144 struct ulink_cmd
*next
; /* /< Pointer to next command (linked list) */
147 /** Describes one driver instance */
149 struct usb_dev_handle
*usb_handle
;
150 enum ulink_type type
;
152 int delay_scan_in
; /* /< Delay value for SCAN_IN commands */
153 int delay_scan_out
; /* /< Delay value for SCAN_OUT commands */
154 int delay_scan_io
; /* /< Delay value for SCAN_IO commands */
155 int delay_clock_tck
; /* /< Delay value for CLOCK_TMS commands */
156 int delay_clock_tms
; /* /< Delay value for CLOCK_TCK commands */
158 int commands_in_queue
; /* /< Number of commands in queue */
159 struct ulink_cmd
*queue_start
; /* /< Pointer to first command in queue */
160 struct ulink_cmd
*queue_end
; /* /< Pointer to last command in queue */
163 /**************************** Function Prototypes *****************************/
165 /* USB helper functions */
166 int ulink_usb_open(struct ulink
**device
);
167 int ulink_usb_close(struct ulink
**device
);
169 /* ULINK MCU (Cypress EZ-USB) specific functions */
170 int ulink_cpu_reset(struct ulink
*device
, char reset_bit
);
171 int ulink_load_firmware_and_renumerate(struct ulink
**device
, char *filename
,
173 int ulink_load_firmware(struct ulink
*device
, char *filename
);
174 int ulink_write_firmware_section(struct ulink
*device
,
175 struct image
*firmware_image
, int section_index
);
177 /* Generic helper functions */
178 void ulink_print_signal_states(uint8_t input_signals
, uint8_t output_signals
);
180 /* OpenULINK command generation helper functions */
181 int ulink_allocate_payload(struct ulink_cmd
*ulink_cmd
, int size
,
182 enum ulink_payload_direction direction
);
184 /* OpenULINK command queue helper functions */
185 int ulink_get_queue_size(struct ulink
*device
,
186 enum ulink_payload_direction direction
);
187 void ulink_clear_queue(struct ulink
*device
);
188 int ulink_append_queue(struct ulink
*device
, struct ulink_cmd
*ulink_cmd
);
189 int ulink_execute_queued_commands(struct ulink
*device
, int timeout
);
191 #ifdef _DEBUG_JTAG_IO_
192 const char *ulink_cmd_id_string(uint8_t id
);
193 void ulink_print_command(struct ulink_cmd
*ulink_cmd
);
194 void ulink_print_queue(struct ulink
*device
);
197 int ulink_append_scan_cmd(struct ulink
*device
,
198 enum scan_type scan_type
,
203 uint8_t tms_count_start
,
204 uint8_t tms_sequence_start
,
205 uint8_t tms_count_end
,
206 uint8_t tms_sequence_end
,
207 struct jtag_command
*origin
,
209 int ulink_append_clock_tms_cmd(struct ulink
*device
, uint8_t count
,
211 int ulink_append_clock_tck_cmd(struct ulink
*device
, uint16_t count
);
212 int ulink_append_get_signals_cmd(struct ulink
*device
);
213 int ulink_append_set_signals_cmd(struct ulink
*device
, uint8_t low
,
215 int ulink_append_sleep_cmd(struct ulink
*device
, uint32_t us
);
216 int ulink_append_configure_tck_cmd(struct ulink
*device
,
222 int ulink_append_led_cmd(struct ulink
*device
, uint8_t led_state
);
223 int ulink_append_test_cmd(struct ulink
*device
);
225 /* OpenULINK TCK frequency helper functions */
226 int ulink_calculate_delay(enum ulink_delay_type type
, long f
, int *delay
);
227 int ulink_calculate_frequency(enum ulink_delay_type type
, int delay
, long *f
);
229 /* Interface between OpenULINK and OpenOCD */
230 static void ulink_set_end_state(tap_state_t endstate
);
231 int ulink_queue_statemove(struct ulink
*device
);
233 int ulink_queue_scan(struct ulink
*device
, struct jtag_command
*cmd
);
234 int ulink_queue_tlr_reset(struct ulink
*device
, struct jtag_command
*cmd
);
235 int ulink_queue_runtest(struct ulink
*device
, struct jtag_command
*cmd
);
236 int ulink_queue_reset(struct ulink
*device
, struct jtag_command
*cmd
);
237 int ulink_queue_pathmove(struct ulink
*device
, struct jtag_command
*cmd
);
238 int ulink_queue_sleep(struct ulink
*device
, struct jtag_command
*cmd
);
239 int ulink_queue_stableclocks(struct ulink
*device
, struct jtag_command
*cmd
);
241 int ulink_post_process_scan(struct ulink_cmd
*ulink_cmd
);
242 int ulink_post_process_queue(struct ulink
*device
);
244 /* JTAG driver functions (registered in struct jtag_interface) */
245 static int ulink_execute_queue(void);
246 static int ulink_khz(int khz
, int *jtag_speed
);
247 static int ulink_speed(int speed
);
248 static int ulink_speed_div(int speed
, int *khz
);
249 static int ulink_init(void);
250 static int ulink_quit(void);
252 /****************************** Global Variables ******************************/
254 struct ulink
*ulink_handle
;
256 /**************************** USB helper functions ****************************/
259 * Opens the ULINK device and claims its USB interface.
261 * @param device pointer to struct ulink identifying ULINK driver instance.
262 * @return on success: ERROR_OK
263 * @return on failure: ERROR_FAIL
265 int ulink_usb_open(struct ulink
**device
)
268 struct usb_dev_handle
*usb_handle
;
270 /* Currently, only original ULINK is supported */
271 uint16_t vids
[] = { ULINK_VID
, 0 };
272 uint16_t pids
[] = { ULINK_PID
, 0 };
274 ret
= jtag_usb_open(vids
, pids
, &usb_handle
);
279 ret
= usb_claim_interface(usb_handle
, 0);
284 (*device
)->usb_handle
= usb_handle
;
285 (*device
)->type
= ULINK_1
;
291 * Releases the ULINK interface and closes the USB device handle.
293 * @param device pointer to struct ulink identifying ULINK driver instance.
294 * @return on success: ERROR_OK
295 * @return on failure: ERROR_FAIL
297 int ulink_usb_close(struct ulink
**device
)
299 if (usb_release_interface((*device
)->usb_handle
, 0) != 0)
302 if (usb_close((*device
)->usb_handle
) != 0)
305 (*device
)->usb_handle
= NULL
;
310 /******************* ULINK CPU (EZ-USB) specific functions ********************/
313 * Writes '0' or '1' to the CPUCS register, putting the EZ-USB CPU into reset
316 * @param device pointer to struct ulink identifying ULINK driver instance.
317 * @param reset_bit 0 to put CPU into reset, 1 to put CPU out of reset.
318 * @return on success: ERROR_OK
319 * @return on failure: ERROR_FAIL
321 int ulink_cpu_reset(struct ulink
*device
, char reset_bit
)
325 ret
= usb_control_msg(device
->usb_handle
,
326 (USB_ENDPOINT_OUT
| USB_TYPE_VENDOR
| USB_RECIP_DEVICE
),
327 REQUEST_FIRMWARE_LOAD
, CPUCS_REG
, 0, &reset_bit
, 1, USB_TIMEOUT
);
329 /* usb_control_msg() returns the number of bytes transferred during the
330 * DATA stage of the control transfer - must be exactly 1 in this case! */
337 * Puts the ULINK's EZ-USB microcontroller into reset state, downloads
338 * the firmware image, resumes the microcontroller and re-enumerates
341 * @param device pointer to struct ulink identifying ULINK driver instance.
342 * The usb_handle member will be modified during re-enumeration.
343 * @param filename path to the Intel HEX file containing the firmware image.
344 * @param delay the delay to wait for the device to re-enumerate.
345 * @return on success: ERROR_OK
346 * @return on failure: ERROR_FAIL
348 int ulink_load_firmware_and_renumerate(struct ulink
**device
,
349 char *filename
, uint32_t delay
)
353 /* Basic process: After downloading the firmware, the ULINK will disconnect
354 * itself and re-connect after a short amount of time so we have to close
355 * the handle and re-enumerate USB devices */
357 ret
= ulink_load_firmware(*device
, filename
);
361 ret
= ulink_usb_close(device
);
367 ret
= ulink_usb_open(device
);
375 * Downloads a firmware image to the ULINK's EZ-USB microcontroller
378 * @param device pointer to struct ulink identifying ULINK driver instance.
379 * @param filename an absolute or relative path to the Intel HEX file
380 * containing the firmware image.
381 * @return on success: ERROR_OK
382 * @return on failure: ERROR_FAIL
384 int ulink_load_firmware(struct ulink
*device
, char *filename
)
386 struct image ulink_firmware_image
;
389 ret
= ulink_cpu_reset(device
, CPU_RESET
);
390 if (ret
!= ERROR_OK
) {
391 LOG_ERROR("Could not halt ULINK CPU");
395 ulink_firmware_image
.base_address
= 0;
396 ulink_firmware_image
.base_address_set
= 0;
398 ret
= image_open(&ulink_firmware_image
, filename
, "ihex");
399 if (ret
!= ERROR_OK
) {
400 LOG_ERROR("Could not load firmware image");
404 /* Download all sections in the image to ULINK */
405 for (i
= 0; i
< ulink_firmware_image
.num_sections
; i
++) {
406 ret
= ulink_write_firmware_section(device
, &ulink_firmware_image
, i
);
411 image_close(&ulink_firmware_image
);
413 ret
= ulink_cpu_reset(device
, CPU_START
);
414 if (ret
!= ERROR_OK
) {
415 LOG_ERROR("Could not restart ULINK CPU");
423 * Send one contiguous firmware section to the ULINK's EZ-USB microcontroller
426 * @param device pointer to struct ulink identifying ULINK driver instance.
427 * @param firmware_image pointer to the firmware image that contains the section
428 * which should be sent to the ULINK's EZ-USB microcontroller.
429 * @param section_index index of the section within the firmware image.
430 * @return on success: ERROR_OK
431 * @return on failure: ERROR_FAIL
433 int ulink_write_firmware_section(struct ulink
*device
,
434 struct image
*firmware_image
, int section_index
)
436 uint16_t addr
, size
, bytes_remaining
, chunk_size
;
437 uint8_t data
[SECTION_BUFFERSIZE
];
438 uint8_t *data_ptr
= data
;
442 size
= (uint16_t)firmware_image
->sections
[section_index
].size
;
443 addr
= (uint16_t)firmware_image
->sections
[section_index
].base_address
;
445 LOG_DEBUG("section %02i at addr 0x%04x (size 0x%04x)", section_index
, addr
,
451 /* Copy section contents to local buffer */
452 ret
= image_read_section(firmware_image
, section_index
, 0, size
, data
,
455 if ((ret
!= ERROR_OK
) || (size_read
!= size
)) {
456 /* Propagating the return code would return '0' (misleadingly indicating
457 * successful execution of the function) if only the size check fails. */
461 bytes_remaining
= size
;
463 /* Send section data in chunks of up to 64 bytes to ULINK */
464 while (bytes_remaining
> 0) {
465 if (bytes_remaining
> 64)
468 chunk_size
= bytes_remaining
;
470 ret
= usb_control_msg(device
->usb_handle
,
471 (USB_ENDPOINT_OUT
| USB_TYPE_VENDOR
| USB_RECIP_DEVICE
),
472 REQUEST_FIRMWARE_LOAD
, addr
, FIRMWARE_ADDR
, (char *)data_ptr
,
473 chunk_size
, USB_TIMEOUT
);
475 if (ret
!= (int)chunk_size
) {
476 /* Abort if libusb sent less data than requested */
480 bytes_remaining
-= chunk_size
;
482 data_ptr
+= chunk_size
;
488 /************************** Generic helper functions **************************/
491 * Print state of interesting signals via LOG_INFO().
493 * @param input_signals input signal states as returned by CMD_GET_SIGNALS
494 * @param output_signals output signal states as returned by CMD_GET_SIGNALS
496 void ulink_print_signal_states(uint8_t input_signals
, uint8_t output_signals
)
498 LOG_INFO("ULINK signal states: TDI: %i, TDO: %i, TMS: %i, TCK: %i, TRST: %i,"
500 (output_signals
& SIGNAL_TDI
? 1 : 0),
501 (input_signals
& SIGNAL_TDO
? 1 : 0),
502 (output_signals
& SIGNAL_TMS
? 1 : 0),
503 (output_signals
& SIGNAL_TCK
? 1 : 0),
504 (output_signals
& SIGNAL_TRST
? 0 : 1),/* TRST and RESET are inverted */
505 (output_signals
& SIGNAL_RESET
? 0 : 1)); /* by hardware */
508 /**************** OpenULINK command generation helper functions ***************/
511 * Allocate and initialize space in memory for OpenULINK command payload.
513 * @param ulink_cmd pointer to command whose payload should be allocated.
514 * @param size the amount of memory to allocate (bytes).
515 * @param direction which payload to allocate.
516 * @return on success: ERROR_OK
517 * @return on failure: ERROR_FAIL
519 int ulink_allocate_payload(struct ulink_cmd
*ulink_cmd
, int size
,
520 enum ulink_payload_direction direction
)
524 payload
= calloc(size
, sizeof(uint8_t));
526 if (payload
== NULL
) {
527 LOG_ERROR("Could not allocate OpenULINK command payload: out of memory");
532 case PAYLOAD_DIRECTION_OUT
:
533 if (ulink_cmd
->payload_out
!= NULL
) {
534 LOG_ERROR("BUG: Duplicate payload allocation for OpenULINK command");
538 ulink_cmd
->payload_out
= payload
;
539 ulink_cmd
->payload_out_size
= size
;
542 case PAYLOAD_DIRECTION_IN
:
543 if (ulink_cmd
->payload_in_start
!= NULL
) {
544 LOG_ERROR("BUG: Duplicate payload allocation for OpenULINK command");
548 ulink_cmd
->payload_in_start
= payload
;
549 ulink_cmd
->payload_in
= payload
;
550 ulink_cmd
->payload_in_size
= size
;
552 /* By default, free payload_in_start in ulink_clear_queue(). Commands
553 * that do not want this behavior (e. g. split scans) must turn it off
555 ulink_cmd
->free_payload_in_start
= true;
563 /****************** OpenULINK command queue helper functions ******************/
566 * Get the current number of bytes in the queue, including command IDs.
568 * @param device pointer to struct ulink identifying ULINK driver instance.
569 * @param direction the transfer direction for which to get byte count.
570 * @return the number of bytes currently stored in the queue for the specified
573 int ulink_get_queue_size(struct ulink
*device
,
574 enum ulink_payload_direction direction
)
576 struct ulink_cmd
*current
= device
->queue_start
;
579 while (current
!= NULL
) {
581 case PAYLOAD_DIRECTION_OUT
:
582 sum
+= current
->payload_out_size
+ 1; /* + 1 byte for Command ID */
584 case PAYLOAD_DIRECTION_IN
:
585 sum
+= current
->payload_in_size
;
589 current
= current
->next
;
596 * Clear the OpenULINK command queue.
598 * @param device pointer to struct ulink identifying ULINK driver instance.
599 * @return on success: ERROR_OK
600 * @return on failure: ERROR_FAIL
602 void ulink_clear_queue(struct ulink
*device
)
604 struct ulink_cmd
*current
= device
->queue_start
;
605 struct ulink_cmd
*next
= NULL
;
607 while (current
!= NULL
) {
608 /* Save pointer to next element */
609 next
= current
->next
;
611 /* Free payloads: OUT payload can be freed immediately */
612 free(current
->payload_out
);
613 current
->payload_out
= NULL
;
615 /* IN payload MUST be freed ONLY if no other commands use the
616 * payload_in_start buffer */
617 if (current
->free_payload_in_start
== true) {
618 free(current
->payload_in_start
);
619 current
->payload_in_start
= NULL
;
620 current
->payload_in
= NULL
;
623 /* Free queue element */
626 /* Proceed with next element */
630 device
->commands_in_queue
= 0;
631 device
->queue_start
= NULL
;
632 device
->queue_end
= NULL
;
636 * Add a command to the OpenULINK command queue.
638 * @param device pointer to struct ulink identifying ULINK driver instance.
639 * @param ulink_cmd pointer to command that shall be appended to the OpenULINK
641 * @return on success: ERROR_OK
642 * @return on failure: ERROR_FAIL
644 int ulink_append_queue(struct ulink
*device
, struct ulink_cmd
*ulink_cmd
)
646 int newsize_out
, newsize_in
;
649 newsize_out
= ulink_get_queue_size(device
, PAYLOAD_DIRECTION_OUT
) + 1
650 + ulink_cmd
->payload_out_size
;
652 newsize_in
= ulink_get_queue_size(device
, PAYLOAD_DIRECTION_IN
)
653 + ulink_cmd
->payload_in_size
;
655 /* Check if the current command can be appended to the queue */
656 if ((newsize_out
> 64) || (newsize_in
> 64)) {
657 /* New command does not fit. Execute all commands in queue before starting
658 * new queue with the current command as first entry. */
659 ret
= ulink_execute_queued_commands(device
, USB_TIMEOUT
);
663 ret
= ulink_post_process_queue(device
);
667 ulink_clear_queue(device
);
670 if (device
->queue_start
== NULL
) {
671 /* Queue was empty */
672 device
->commands_in_queue
= 1;
674 device
->queue_start
= ulink_cmd
;
675 device
->queue_end
= ulink_cmd
;
677 /* There are already commands in the queue */
678 device
->commands_in_queue
++;
680 device
->queue_end
->next
= ulink_cmd
;
681 device
->queue_end
= ulink_cmd
;
688 * Sends all queued OpenULINK commands to the ULINK for execution.
690 * @param device pointer to struct ulink identifying ULINK driver instance.
691 * @return on success: ERROR_OK
692 * @return on failure: ERROR_FAIL
694 int ulink_execute_queued_commands(struct ulink
*device
, int timeout
)
696 struct ulink_cmd
*current
;
697 int ret
, i
, index_out
, index_in
, count_out
, count_in
;
700 #ifdef _DEBUG_JTAG_IO_
701 ulink_print_queue(device
);
708 for (current
= device
->queue_start
; current
; current
= current
->next
) {
709 /* Add command to packet */
710 buffer
[index_out
] = current
->id
;
714 for (i
= 0; i
< current
->payload_out_size
; i
++)
715 buffer
[index_out
+ i
] = current
->payload_out
[i
];
716 index_out
+= current
->payload_out_size
;
717 count_in
+= current
->payload_in_size
;
718 count_out
+= current
->payload_out_size
;
721 /* Send packet to ULINK */
722 ret
= usb_bulk_write(device
->usb_handle
, (2 | USB_ENDPOINT_OUT
),
723 (char *)buffer
, count_out
, timeout
);
726 if (ret
!= count_out
)
729 /* Wait for response if commands contain IN payload data */
731 ret
= usb_bulk_read(device
->usb_handle
, (2 | USB_ENDPOINT_IN
),
732 (char *)buffer
, 64, timeout
);
738 /* Write back IN payload data */
740 for (current
= device
->queue_start
; current
; current
= current
->next
) {
741 for (i
= 0; i
< current
->payload_in_size
; i
++) {
742 current
->payload_in
[i
] = buffer
[index_in
];
751 #ifdef _DEBUG_JTAG_IO_
754 * Convert an OpenULINK command ID (\a id) to a human-readable string.
756 * @param id the OpenULINK command ID.
757 * @return the corresponding human-readable string.
759 const char *ulink_cmd_id_string(uint8_t id
)
763 return "CMD_SCAN_IN";
765 case CMD_SLOW_SCAN_IN
:
766 return "CMD_SLOW_SCAN_IN";
769 return "CMD_SCAN_OUT";
771 case CMD_SLOW_SCAN_OUT
:
772 return "CMD_SLOW_SCAN_OUT";
775 return "CMD_SCAN_IO";
777 case CMD_SLOW_SCAN_IO
:
778 return "CMD_SLOW_SCAN_IO";
781 return "CMD_CLOCK_TMS";
783 case CMD_SLOW_CLOCK_TMS
:
784 return "CMD_SLOW_CLOCK_TMS";
787 return "CMD_CLOCK_TCK";
789 case CMD_SLOW_CLOCK_TCK
:
790 return "CMD_SLOW_CLOCK_TCK";
793 return "CMD_SLEEP_US";
796 return "CMD_SLEEP_MS";
798 case CMD_GET_SIGNALS
:
799 return "CMD_GET_SIGNALS";
801 case CMD_SET_SIGNALS
:
802 return "CMD_SET_SIGNALS";
804 case CMD_CONFIGURE_TCK_FREQ
:
805 return "CMD_CONFIGURE_TCK_FREQ";
808 return "CMD_SET_LEDS";
814 return "CMD_UNKNOWN";
820 * Print one OpenULINK command to stdout.
822 * @param ulink_cmd pointer to OpenULINK command.
824 void ulink_print_command(struct ulink_cmd
*ulink_cmd
)
828 printf(" %-22s | OUT size = %i, bytes = 0x",
829 ulink_cmd_id_string(ulink_cmd
->id
), ulink_cmd
->payload_out_size
);
831 for (i
= 0; i
< ulink_cmd
->payload_out_size
; i
++)
832 printf("%02X ", ulink_cmd
->payload_out
[i
]);
833 printf("\n | IN size = %i\n",
834 ulink_cmd
->payload_in_size
);
838 * Print the OpenULINK command queue to stdout.
840 * @param device pointer to struct ulink identifying ULINK driver instance.
842 void ulink_print_queue(struct ulink
*device
)
844 struct ulink_cmd
*current
;
846 printf("OpenULINK command queue:\n");
848 for (current
= device
->queue_start
; current
; current
= current
->next
)
849 ulink_print_command(current
);
852 #endif /* _DEBUG_JTAG_IO_ */
857 * Creates and appends a JTAG scan command to the OpenULINK command queue.
858 * A JTAG scan consists of three steps:
859 * - Move to the desired SHIFT state, depending on scan type (IR/DR scan).
860 * - Shift TDI data into the JTAG chain, optionally reading the TDO pin.
861 * - Move to the desired end state.
863 * @param device pointer to struct ulink identifying ULINK driver instance.
864 * @param scan_type the type of the scan (IN, OUT, IO (bidirectional)).
865 * @param scan_size_bits number of bits to shift into the JTAG chain.
866 * @param tdi pointer to array containing TDI data.
867 * @param tdo_start pointer to first element of array where TDO data shall be
868 * stored. See #ulink_cmd for details.
869 * @param tdo pointer to array where TDO data shall be stored
870 * @param tms_count_start number of TMS state transitions to perform BEFORE
871 * shifting data into the JTAG chain.
872 * @param tms_sequence_start sequence of TMS state transitions that will be
873 * performed BEFORE shifting data into the JTAG chain.
874 * @param tms_count_end number of TMS state transitions to perform AFTER
875 * shifting data into the JTAG chain.
876 * @param tms_sequence_end sequence of TMS state transitions that will be
877 * performed AFTER shifting data into the JTAG chain.
878 * @param origin pointer to OpenOCD command that generated this scan command.
879 * @param postprocess whether this command needs to be post-processed after
881 * @return on success: ERROR_OK
882 * @return on failure: ERROR_FAIL
884 int ulink_append_scan_cmd(struct ulink
*device
, enum scan_type scan_type
,
885 int scan_size_bits
, uint8_t *tdi
, uint8_t *tdo_start
, uint8_t *tdo
,
886 uint8_t tms_count_start
, uint8_t tms_sequence_start
, uint8_t tms_count_end
,
887 uint8_t tms_sequence_end
, struct jtag_command
*origin
, bool postprocess
)
889 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
890 int ret
, i
, scan_size_bytes
;
891 uint8_t bits_last_byte
;
896 /* Check size of command. USB buffer can hold 64 bytes, 1 byte is command ID,
897 * 5 bytes are setup data -> 58 remaining payload bytes for TDI data */
898 if (scan_size_bits
> (58 * 8)) {
899 LOG_ERROR("BUG: Tried to create CMD_SCAN_IO OpenULINK command with too"
905 scan_size_bytes
= DIV_ROUND_UP(scan_size_bits
, 8);
907 bits_last_byte
= scan_size_bits
% 8;
908 if (bits_last_byte
== 0)
911 /* Allocate out_payload depending on scan type */
914 if (device
->delay_scan_in
< 0)
915 cmd
->id
= CMD_SCAN_IN
;
917 cmd
->id
= CMD_SLOW_SCAN_IN
;
918 ret
= ulink_allocate_payload(cmd
, 5, PAYLOAD_DIRECTION_OUT
);
921 if (device
->delay_scan_out
< 0)
922 cmd
->id
= CMD_SCAN_OUT
;
924 cmd
->id
= CMD_SLOW_SCAN_OUT
;
925 ret
= ulink_allocate_payload(cmd
, scan_size_bytes
+ 5, PAYLOAD_DIRECTION_OUT
);
928 if (device
->delay_scan_io
< 0)
929 cmd
->id
= CMD_SCAN_IO
;
931 cmd
->id
= CMD_SLOW_SCAN_IO
;
932 ret
= ulink_allocate_payload(cmd
, scan_size_bytes
+ 5, PAYLOAD_DIRECTION_OUT
);
935 LOG_ERROR("BUG: ulink_append_scan_cmd() encountered an unknown scan type");
940 if (ret
!= ERROR_OK
) {
945 /* Build payload_out that is common to all scan types */
946 cmd
->payload_out
[0] = scan_size_bytes
& 0xFF;
947 cmd
->payload_out
[1] = bits_last_byte
& 0xFF;
948 cmd
->payload_out
[2] = ((tms_count_start
& 0x0F) << 4) | (tms_count_end
& 0x0F);
949 cmd
->payload_out
[3] = tms_sequence_start
;
950 cmd
->payload_out
[4] = tms_sequence_end
;
952 /* Setup payload_out for types with OUT transfer */
953 if ((scan_type
== SCAN_OUT
) || (scan_type
== SCAN_IO
)) {
954 for (i
= 0; i
< scan_size_bytes
; i
++)
955 cmd
->payload_out
[i
+ 5] = tdi
[i
];
958 /* Setup payload_in pointers for types with IN transfer */
959 if ((scan_type
== SCAN_IN
) || (scan_type
== SCAN_IO
)) {
960 cmd
->payload_in_start
= tdo_start
;
961 cmd
->payload_in
= tdo
;
962 cmd
->payload_in_size
= scan_size_bytes
;
965 cmd
->needs_postprocessing
= postprocess
;
966 cmd
->cmd_origin
= origin
;
968 /* For scan commands, we free payload_in_start only when the command is
969 * the last in a series of split commands or a stand-alone command */
970 cmd
->free_payload_in_start
= postprocess
;
972 return ulink_append_queue(device
, cmd
);
976 * Perform TAP state transitions
978 * @param device pointer to struct ulink identifying ULINK driver instance.
979 * @param count defines the number of TCK clock cycles generated (up to 8).
980 * @param sequence defines the TMS pin levels for each state transition. The
981 * Least-Significant Bit is read first.
982 * @return on success: ERROR_OK
983 * @return on failure: ERROR_FAIL
985 int ulink_append_clock_tms_cmd(struct ulink
*device
, uint8_t count
,
988 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
994 if (device
->delay_clock_tms
< 0)
995 cmd
->id
= CMD_CLOCK_TMS
;
997 cmd
->id
= CMD_SLOW_CLOCK_TMS
;
999 /* CMD_CLOCK_TMS has two OUT payload bytes and zero IN payload bytes */
1000 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1001 if (ret
!= ERROR_OK
) {
1006 cmd
->payload_out
[0] = count
;
1007 cmd
->payload_out
[1] = sequence
;
1009 return ulink_append_queue(device
, cmd
);
1013 * Generate a defined amount of TCK clock cycles
1015 * All other JTAG signals are left unchanged.
1017 * @param device pointer to struct ulink identifying ULINK driver instance.
1018 * @param count the number of TCK clock cycles to generate.
1019 * @return on success: ERROR_OK
1020 * @return on failure: ERROR_FAIL
1022 int ulink_append_clock_tck_cmd(struct ulink
*device
, uint16_t count
)
1024 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1030 if (device
->delay_clock_tck
< 0)
1031 cmd
->id
= CMD_CLOCK_TCK
;
1033 cmd
->id
= CMD_SLOW_CLOCK_TCK
;
1035 /* CMD_CLOCK_TCK has two OUT payload bytes and zero IN payload bytes */
1036 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1037 if (ret
!= ERROR_OK
) {
1042 cmd
->payload_out
[0] = count
& 0xff;
1043 cmd
->payload_out
[1] = (count
>> 8) & 0xff;
1045 return ulink_append_queue(device
, cmd
);
1049 * Read JTAG signals.
1051 * @param device pointer to struct ulink identifying ULINK driver instance.
1052 * @return on success: ERROR_OK
1053 * @return on failure: ERROR_FAIL
1055 int ulink_append_get_signals_cmd(struct ulink
*device
)
1057 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1063 cmd
->id
= CMD_GET_SIGNALS
;
1064 cmd
->needs_postprocessing
= true;
1066 /* CMD_GET_SIGNALS has two IN payload bytes */
1067 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_IN
);
1069 if (ret
!= ERROR_OK
) {
1074 return ulink_append_queue(device
, cmd
);
1078 * Arbitrarily set JTAG output signals.
1080 * @param device pointer to struct ulink identifying ULINK driver instance.
1081 * @param low defines which signals will be de-asserted. Each bit corresponds
1090 * @param high defines which signals will be asserted.
1091 * @return on success: ERROR_OK
1092 * @return on failure: ERROR_FAIL
1094 int ulink_append_set_signals_cmd(struct ulink
*device
, uint8_t low
,
1097 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1103 cmd
->id
= CMD_SET_SIGNALS
;
1105 /* CMD_SET_SIGNALS has two OUT payload bytes and zero IN payload bytes */
1106 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1108 if (ret
!= ERROR_OK
) {
1113 cmd
->payload_out
[0] = low
;
1114 cmd
->payload_out
[1] = high
;
1116 return ulink_append_queue(device
, cmd
);
1120 * Sleep for a pre-defined number of microseconds
1122 * @param device pointer to struct ulink identifying ULINK driver instance.
1123 * @param us the number microseconds to sleep.
1124 * @return on success: ERROR_OK
1125 * @return on failure: ERROR_FAIL
1127 int ulink_append_sleep_cmd(struct ulink
*device
, uint32_t us
)
1129 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1135 cmd
->id
= CMD_SLEEP_US
;
1137 /* CMD_SLEEP_US has two OUT payload bytes and zero IN payload bytes */
1138 ret
= ulink_allocate_payload(cmd
, 2, PAYLOAD_DIRECTION_OUT
);
1140 if (ret
!= ERROR_OK
) {
1145 cmd
->payload_out
[0] = us
& 0x00ff;
1146 cmd
->payload_out
[1] = (us
>> 8) & 0x00ff;
1148 return ulink_append_queue(device
, cmd
);
1152 * Set TCK delay counters
1154 * @param device pointer to struct ulink identifying ULINK driver instance.
1155 * @param delay_scan_in delay count top value in jtag_slow_scan_in() function.
1156 * @param delay_scan_out delay count top value in jtag_slow_scan_out() function.
1157 * @param delay_scan_io delay count top value in jtag_slow_scan_io() function.
1158 * @param delay_tck delay count top value in jtag_clock_tck() function.
1159 * @param delay_tms delay count top value in jtag_slow_clock_tms() function.
1160 * @return on success: ERROR_OK
1161 * @return on failure: ERROR_FAIL
1163 int ulink_append_configure_tck_cmd(struct ulink
*device
, int delay_scan_in
,
1164 int delay_scan_out
, int delay_scan_io
, int delay_tck
, int delay_tms
)
1166 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1172 cmd
->id
= CMD_CONFIGURE_TCK_FREQ
;
1174 /* CMD_CONFIGURE_TCK_FREQ has five OUT payload bytes and zero
1175 * IN payload bytes */
1176 ret
= ulink_allocate_payload(cmd
, 5, PAYLOAD_DIRECTION_OUT
);
1177 if (ret
!= ERROR_OK
) {
1182 if (delay_scan_in
< 0)
1183 cmd
->payload_out
[0] = 0;
1185 cmd
->payload_out
[0] = (uint8_t)delay_scan_in
;
1187 if (delay_scan_out
< 0)
1188 cmd
->payload_out
[1] = 0;
1190 cmd
->payload_out
[1] = (uint8_t)delay_scan_out
;
1192 if (delay_scan_io
< 0)
1193 cmd
->payload_out
[2] = 0;
1195 cmd
->payload_out
[2] = (uint8_t)delay_scan_io
;
1198 cmd
->payload_out
[3] = 0;
1200 cmd
->payload_out
[3] = (uint8_t)delay_tck
;
1203 cmd
->payload_out
[4] = 0;
1205 cmd
->payload_out
[4] = (uint8_t)delay_tms
;
1207 return ulink_append_queue(device
, cmd
);
1211 * Turn on/off ULINK LEDs.
1213 * @param device pointer to struct ulink identifying ULINK driver instance.
1214 * @param led_state which LED(s) to turn on or off. The following bits
1215 * influence the LEDS:
1216 * - Bit 0: Turn COM LED on
1217 * - Bit 1: Turn RUN LED on
1218 * - Bit 2: Turn COM LED off
1219 * - Bit 3: Turn RUN LED off
1220 * If both the on-bit and the off-bit for the same LED is set, the LED is
1222 * @return on success: ERROR_OK
1223 * @return on failure: ERROR_FAIL
1225 int ulink_append_led_cmd(struct ulink
*device
, uint8_t led_state
)
1227 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1233 cmd
->id
= CMD_SET_LEDS
;
1235 /* CMD_SET_LEDS has one OUT payload byte and zero IN payload bytes */
1236 ret
= ulink_allocate_payload(cmd
, 1, PAYLOAD_DIRECTION_OUT
);
1237 if (ret
!= ERROR_OK
) {
1242 cmd
->payload_out
[0] = led_state
;
1244 return ulink_append_queue(device
, cmd
);
1248 * Test command. Used to check if the ULINK device is ready to accept new
1251 * @param device pointer to struct ulink identifying ULINK driver instance.
1252 * @return on success: ERROR_OK
1253 * @return on failure: ERROR_FAIL
1255 int ulink_append_test_cmd(struct ulink
*device
)
1257 struct ulink_cmd
*cmd
= calloc(1, sizeof(struct ulink_cmd
));
1265 /* CMD_TEST has one OUT payload byte and zero IN payload bytes */
1266 ret
= ulink_allocate_payload(cmd
, 1, PAYLOAD_DIRECTION_OUT
);
1267 if (ret
!= ERROR_OK
) {
1272 cmd
->payload_out
[0] = 0xAA;
1274 return ulink_append_queue(device
, cmd
);
1277 /****************** OpenULINK TCK frequency helper functions ******************/
1280 * Calculate delay values for a given TCK frequency.
1282 * The OpenULINK firmware uses five different speed values for different
1283 * commands. These speed values are calculated in these functions.
1285 * The five different commands which support variable TCK frequency are
1286 * implemented twice in the firmware:
1287 * 1. Maximum possible frequency without any artificial delay
1288 * 2. Variable frequency with artificial linear delay loop
1290 * To set the ULINK to maximum frequency, it is only neccessary to use the
1291 * corresponding command IDs. To set the ULINK to a lower frequency, the
1292 * delay loop top values have to be calculated first. Then, a
1293 * CMD_CONFIGURE_TCK_FREQ command needs to be sent to the ULINK device.
1295 * The delay values are described by linear equations:
1297 * (t = period, k = constant, x = delay value, d = constant)
1299 * Thus, the delay can be calculated as in the following equation:
1302 * The constants in these equations have been determined and validated by
1303 * measuring the frequency resulting from different delay values.
1305 * @param type for which command to calculate the delay value.
1306 * @param f TCK frequency for which to calculate the delay value in Hz.
1307 * @param delay where to store resulting delay value.
1308 * @return on success: ERROR_OK
1309 * @return on failure: ERROR_FAIL
1311 int ulink_calculate_delay(enum ulink_delay_type type
, long f
, int *delay
)
1315 /* Calculate period of requested TCK frequency */
1316 t
= 1.0 / (float)(f
);
1319 case DELAY_CLOCK_TCK
:
1320 x
= (t
- (float)(6E-6)) / (float)(4E-6);
1322 case DELAY_CLOCK_TMS
:
1323 x
= (t
- (float)(8.5E-6)) / (float)(4E-6);
1326 x
= (t
- (float)(8.8308E-6)) / (float)(4E-6);
1328 case DELAY_SCAN_OUT
:
1329 x
= (t
- (float)(1.0527E-5)) / (float)(4E-6);
1332 x
= (t
- (float)(1.3132E-5)) / (float)(4E-6);
1339 /* Check if the delay value is negative. This happens when a frequency is
1340 * requested that is too high for the delay loop implementation. In this
1341 * case, set delay value to zero. */
1345 /* We need to convert the exact delay value to an integer. Therefore, we
1346 * round the exact value UP to ensure that the resulting frequency is NOT
1347 * higher than the requested frequency. */
1350 /* Check if the value is within limits */
1354 *delay
= (int)x_ceil
;
1360 * Calculate frequency for a given delay value.
1362 * Similar to the #ulink_calculate_delay function, this function calculates the
1363 * TCK frequency for a given delay value by using linear equations of the form:
1365 * (t = period, k = constant, x = delay value, d = constant)
1367 * @param type for which command to calculate the delay value.
1368 * @param delay delay value for which to calculate the resulting TCK frequency.
1369 * @param f where to store the resulting TCK frequency.
1370 * @return on success: ERROR_OK
1371 * @return on failure: ERROR_FAIL
1373 int ulink_calculate_frequency(enum ulink_delay_type type
, int delay
, long *f
)
1375 float t
, f_float
, f_rounded
;
1381 case DELAY_CLOCK_TCK
:
1383 t
= (float)(2.666E-6);
1385 t
= (float)(4E-6) * (float)(delay
) + (float)(6E-6);
1387 case DELAY_CLOCK_TMS
:
1389 t
= (float)(5.666E-6);
1391 t
= (float)(4E-6) * (float)(delay
) + (float)(8.5E-6);
1395 t
= (float)(5.5E-6);
1397 t
= (float)(4E-6) * (float)(delay
) + (float)(8.8308E-6);
1399 case DELAY_SCAN_OUT
:
1401 t
= (float)(7.0E-6);
1403 t
= (float)(4E-6) * (float)(delay
) + (float)(1.0527E-5);
1407 t
= (float)(9.926E-6);
1409 t
= (float)(4E-6) * (float)(delay
) + (float)(1.3132E-5);
1417 f_rounded
= roundf(f_float
);
1418 *f
= (long)f_rounded
;
1423 /******************* Interface between OpenULINK and OpenOCD ******************/
1426 * Sets the end state follower (see interface.h) if \a endstate is a stable
1429 * @param endstate the state the end state follower should be set to.
1431 static void ulink_set_end_state(tap_state_t endstate
)
1433 if (tap_is_state_stable(endstate
))
1434 tap_set_end_state(endstate
);
1436 LOG_ERROR("BUG: %s is not a valid end state", tap_state_name(endstate
));
1442 * Move from the current TAP state to the current TAP end state.
1444 * @param device pointer to struct ulink identifying ULINK driver instance.
1445 * @return on success: ERROR_OK
1446 * @return on failure: ERROR_FAIL
1448 int ulink_queue_statemove(struct ulink
*device
)
1450 uint8_t tms_sequence
, tms_count
;
1453 if (tap_get_state() == tap_get_end_state()) {
1454 /* Do nothing if we are already there */
1458 tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1459 tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1461 ret
= ulink_append_clock_tms_cmd(device
, tms_count
, tms_sequence
);
1463 if (ret
== ERROR_OK
)
1464 tap_set_state(tap_get_end_state());
1470 * Perform a scan operation on a JTAG register.
1472 * @param device pointer to struct ulink identifying ULINK driver instance.
1473 * @param cmd pointer to the command that shall be executed.
1474 * @return on success: ERROR_OK
1475 * @return on failure: ERROR_FAIL
1477 int ulink_queue_scan(struct ulink
*device
, struct jtag_command
*cmd
)
1479 uint32_t scan_size_bits
, scan_size_bytes
, bits_last_scan
;
1480 uint32_t scans_max_payload
, bytecount
;
1481 uint8_t *tdi_buffer_start
= NULL
, *tdi_buffer
= NULL
;
1482 uint8_t *tdo_buffer_start
= NULL
, *tdo_buffer
= NULL
;
1484 uint8_t first_tms_count
, first_tms_sequence
;
1485 uint8_t last_tms_count
, last_tms_sequence
;
1487 uint8_t tms_count_pause
, tms_sequence_pause
;
1488 uint8_t tms_count_resume
, tms_sequence_resume
;
1490 uint8_t tms_count_start
, tms_sequence_start
;
1491 uint8_t tms_count_end
, tms_sequence_end
;
1493 enum scan_type type
;
1496 /* Determine scan size */
1497 scan_size_bits
= jtag_scan_size(cmd
->cmd
.scan
);
1498 scan_size_bytes
= DIV_ROUND_UP(scan_size_bits
, 8);
1500 /* Determine scan type (IN/OUT/IO) */
1501 type
= jtag_scan_type(cmd
->cmd
.scan
);
1503 /* Determine number of scan commands with maximum payload */
1504 scans_max_payload
= scan_size_bytes
/ 58;
1506 /* Determine size of last shift command */
1507 bits_last_scan
= scan_size_bits
- (scans_max_payload
* 58 * 8);
1509 /* Allocate TDO buffer if required */
1510 if ((type
== SCAN_IN
) || (type
== SCAN_IO
)) {
1511 tdo_buffer_start
= calloc(sizeof(uint8_t), scan_size_bytes
);
1513 if (tdo_buffer_start
== NULL
)
1516 tdo_buffer
= tdo_buffer_start
;
1519 /* Fill TDI buffer if required */
1520 if ((type
== SCAN_OUT
) || (type
== SCAN_IO
)) {
1521 jtag_build_buffer(cmd
->cmd
.scan
, &tdi_buffer_start
);
1522 tdi_buffer
= tdi_buffer_start
;
1525 /* Get TAP state transitions */
1526 if (cmd
->cmd
.scan
->ir_scan
) {
1527 ulink_set_end_state(TAP_IRSHIFT
);
1528 first_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1529 first_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1531 tap_set_state(TAP_IRSHIFT
);
1532 tap_set_end_state(cmd
->cmd
.scan
->end_state
);
1533 last_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1534 last_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1536 /* TAP state transitions for split scans */
1537 tms_count_pause
= tap_get_tms_path_len(TAP_IRSHIFT
, TAP_IRPAUSE
);
1538 tms_sequence_pause
= tap_get_tms_path(TAP_IRSHIFT
, TAP_IRPAUSE
);
1539 tms_count_resume
= tap_get_tms_path_len(TAP_IRPAUSE
, TAP_IRSHIFT
);
1540 tms_sequence_resume
= tap_get_tms_path(TAP_IRPAUSE
, TAP_IRSHIFT
);
1542 ulink_set_end_state(TAP_DRSHIFT
);
1543 first_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1544 first_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1546 tap_set_state(TAP_DRSHIFT
);
1547 tap_set_end_state(cmd
->cmd
.scan
->end_state
);
1548 last_tms_count
= tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1549 last_tms_sequence
= tap_get_tms_path(tap_get_state(), tap_get_end_state());
1551 /* TAP state transitions for split scans */
1552 tms_count_pause
= tap_get_tms_path_len(TAP_DRSHIFT
, TAP_DRPAUSE
);
1553 tms_sequence_pause
= tap_get_tms_path(TAP_DRSHIFT
, TAP_DRPAUSE
);
1554 tms_count_resume
= tap_get_tms_path_len(TAP_DRPAUSE
, TAP_DRSHIFT
);
1555 tms_sequence_resume
= tap_get_tms_path(TAP_DRPAUSE
, TAP_DRSHIFT
);
1558 /* Generate scan commands */
1559 bytecount
= scan_size_bytes
;
1560 while (bytecount
> 0) {
1561 if (bytecount
== scan_size_bytes
) {
1562 /* This is the first scan */
1563 tms_count_start
= first_tms_count
;
1564 tms_sequence_start
= first_tms_sequence
;
1566 /* Resume from previous scan */
1567 tms_count_start
= tms_count_resume
;
1568 tms_sequence_start
= tms_sequence_resume
;
1571 if (bytecount
> 58) { /* Full scan, at least one scan will follow */
1572 tms_count_end
= tms_count_pause
;
1573 tms_sequence_end
= tms_sequence_pause
;
1575 ret
= ulink_append_scan_cmd(device
,
1590 /* Update TDI and TDO buffer pointers */
1591 if (tdi_buffer_start
!= NULL
)
1593 if (tdo_buffer_start
!= NULL
)
1595 } else if (bytecount
== 58) { /* Full scan, no further scans */
1596 tms_count_end
= last_tms_count
;
1597 tms_sequence_end
= last_tms_sequence
;
1599 ret
= ulink_append_scan_cmd(device
,
1613 } else {/* Scan with less than maximum payload, no further scans */
1614 tms_count_end
= last_tms_count
;
1615 tms_sequence_end
= last_tms_sequence
;
1617 ret
= ulink_append_scan_cmd(device
,
1633 if (ret
!= ERROR_OK
) {
1634 free(tdi_buffer_start
);
1639 free(tdi_buffer_start
);
1641 /* Set current state to the end state requested by the command */
1642 tap_set_state(cmd
->cmd
.scan
->end_state
);
1648 * Move the TAP into the Test Logic Reset state.
1650 * @param device pointer to struct ulink identifying ULINK driver instance.
1651 * @param cmd pointer to the command that shall be executed.
1652 * @return on success: ERROR_OK
1653 * @return on failure: ERROR_FAIL
1655 int ulink_queue_tlr_reset(struct ulink
*device
, struct jtag_command
*cmd
)
1659 ret
= ulink_append_clock_tms_cmd(device
, 5, 0xff);
1661 if (ret
== ERROR_OK
)
1662 tap_set_state(TAP_RESET
);
1670 * Generate TCK clock cycles while remaining
1671 * in the Run-Test/Idle state.
1673 * @param device pointer to struct ulink identifying ULINK driver instance.
1674 * @param cmd pointer to the command that shall be executed.
1675 * @return on success: ERROR_OK
1676 * @return on failure: ERROR_FAIL
1678 int ulink_queue_runtest(struct ulink
*device
, struct jtag_command
*cmd
)
1682 /* Only perform statemove if the TAP currently isn't in the TAP_IDLE state */
1683 if (tap_get_state() != TAP_IDLE
) {
1684 ulink_set_end_state(TAP_IDLE
);
1685 ulink_queue_statemove(device
);
1688 /* Generate the clock cycles */
1689 ret
= ulink_append_clock_tck_cmd(device
, cmd
->cmd
.runtest
->num_cycles
);
1690 if (ret
!= ERROR_OK
)
1693 /* Move to end state specified in command */
1694 if (cmd
->cmd
.runtest
->end_state
!= tap_get_state()) {
1695 tap_set_end_state(cmd
->cmd
.runtest
->end_state
);
1696 ulink_queue_statemove(device
);
1703 * Execute a JTAG_RESET command
1705 * @param cmd pointer to the command that shall be executed.
1706 * @return on success: ERROR_OK
1707 * @return on failure: ERROR_FAIL
1709 int ulink_queue_reset(struct ulink
*device
, struct jtag_command
*cmd
)
1711 uint8_t low
= 0, high
= 0;
1713 if (cmd
->cmd
.reset
->trst
) {
1714 tap_set_state(TAP_RESET
);
1715 high
|= SIGNAL_TRST
;
1719 if (cmd
->cmd
.reset
->srst
)
1720 high
|= SIGNAL_RESET
;
1722 low
|= SIGNAL_RESET
;
1724 return ulink_append_set_signals_cmd(device
, low
, high
);
1728 * Move to one TAP state or several states in succession.
1730 * @param device pointer to struct ulink identifying ULINK driver instance.
1731 * @param cmd pointer to the command that shall be executed.
1732 * @return on success: ERROR_OK
1733 * @return on failure: ERROR_FAIL
1735 int ulink_queue_pathmove(struct ulink
*device
, struct jtag_command
*cmd
)
1737 int ret
, i
, num_states
, batch_size
, state_count
;
1739 uint8_t tms_sequence
;
1741 num_states
= cmd
->cmd
.pathmove
->num_states
;
1742 path
= cmd
->cmd
.pathmove
->path
;
1745 while (num_states
> 0) {
1748 /* Determine batch size */
1749 if (num_states
>= 8)
1752 batch_size
= num_states
;
1754 for (i
= 0; i
< batch_size
; i
++) {
1755 if (tap_state_transition(tap_get_state(), false) == path
[state_count
]) {
1756 /* Append '0' transition: clear bit 'i' in tms_sequence */
1757 buf_set_u32(&tms_sequence
, i
, 1, 0x0);
1758 } else if (tap_state_transition(tap_get_state(), true)
1759 == path
[state_count
]) {
1760 /* Append '1' transition: set bit 'i' in tms_sequence */
1761 buf_set_u32(&tms_sequence
, i
, 1, 0x1);
1763 /* Invalid state transition */
1764 LOG_ERROR("BUG: %s -> %s isn't a valid TAP state transition",
1765 tap_state_name(tap_get_state()),
1766 tap_state_name(path
[state_count
]));
1770 tap_set_state(path
[state_count
]);
1775 /* Append CLOCK_TMS command to OpenULINK command queue */
1777 "pathmove batch: count = %i, sequence = 0x%x", batch_size
, tms_sequence
);
1778 ret
= ulink_append_clock_tms_cmd(ulink_handle
, batch_size
, tms_sequence
);
1779 if (ret
!= ERROR_OK
)
1787 * Sleep for a specific amount of time.
1789 * @param device pointer to struct ulink identifying ULINK driver instance.
1790 * @param cmd pointer to the command that shall be executed.
1791 * @return on success: ERROR_OK
1792 * @return on failure: ERROR_FAIL
1794 int ulink_queue_sleep(struct ulink
*device
, struct jtag_command
*cmd
)
1796 /* IMPORTANT! Due to the time offset in command execution introduced by
1797 * command queueing, this needs to be implemented in the ULINK device */
1798 return ulink_append_sleep_cmd(device
, cmd
->cmd
.sleep
->us
);
1802 * Generate TCK cycles while remaining in a stable state.
1804 * @param device pointer to struct ulink identifying ULINK driver instance.
1805 * @param cmd pointer to the command that shall be executed.
1807 int ulink_queue_stableclocks(struct ulink
*device
, struct jtag_command
*cmd
)
1810 unsigned num_cycles
;
1812 if (!tap_is_state_stable(tap_get_state())) {
1813 LOG_ERROR("JTAG_STABLECLOCKS: state not stable");
1817 num_cycles
= cmd
->cmd
.stableclocks
->num_cycles
;
1819 /* TMS stays either high (Test Logic Reset state) or low (all other states) */
1820 if (tap_get_state() == TAP_RESET
)
1821 ret
= ulink_append_set_signals_cmd(device
, 0, SIGNAL_TMS
);
1823 ret
= ulink_append_set_signals_cmd(device
, SIGNAL_TMS
, 0);
1825 if (ret
!= ERROR_OK
)
1828 while (num_cycles
> 0) {
1829 if (num_cycles
> 0xFFFF) {
1830 /* OpenULINK CMD_CLOCK_TCK can generate up to 0xFFFF (uint16_t) cycles */
1831 ret
= ulink_append_clock_tck_cmd(device
, 0xFFFF);
1832 num_cycles
-= 0xFFFF;
1834 ret
= ulink_append_clock_tck_cmd(device
, num_cycles
);
1838 if (ret
!= ERROR_OK
)
1846 * Post-process JTAG_SCAN command
1848 * @param ulink_cmd pointer to OpenULINK command that shall be processed.
1849 * @return on success: ERROR_OK
1850 * @return on failure: ERROR_FAIL
1852 int ulink_post_process_scan(struct ulink_cmd
*ulink_cmd
)
1854 struct jtag_command
*cmd
= ulink_cmd
->cmd_origin
;
1857 switch (jtag_scan_type(cmd
->cmd
.scan
)) {
1860 ret
= jtag_read_buffer(ulink_cmd
->payload_in_start
, cmd
->cmd
.scan
);
1863 /* Nothing to do for OUT scans */
1867 LOG_ERROR("BUG: ulink_post_process_scan() encountered an unknown"
1877 * Perform post-processing of commands after OpenULINK queue has been executed.
1879 * @param device pointer to struct ulink identifying ULINK driver instance.
1880 * @return on success: ERROR_OK
1881 * @return on failure: ERROR_FAIL
1883 int ulink_post_process_queue(struct ulink
*device
)
1885 struct ulink_cmd
*current
;
1886 struct jtag_command
*openocd_cmd
;
1889 current
= device
->queue_start
;
1891 while (current
!= NULL
) {
1892 openocd_cmd
= current
->cmd_origin
;
1894 /* Check if a corresponding OpenOCD command is stored for this
1895 * OpenULINK command */
1896 if ((current
->needs_postprocessing
== true) && (openocd_cmd
!= NULL
)) {
1897 switch (openocd_cmd
->type
) {
1899 ret
= ulink_post_process_scan(current
);
1901 case JTAG_TLR_RESET
:
1906 case JTAG_STABLECLOCKS
:
1907 /* Nothing to do for these commands */
1912 LOG_ERROR("BUG: ulink_post_process_queue() encountered unknown JTAG "
1917 if (ret
!= ERROR_OK
)
1921 current
= current
->next
;
1927 /**************************** JTAG driver functions ***************************/
1930 * Executes the JTAG Command Queue.
1932 * This is done in three stages: First, all OpenOCD commands are processed into
1933 * queued OpenULINK commands. Next, the OpenULINK command queue is sent to the
1934 * ULINK device and data received from the ULINK device is cached. Finally,
1935 * the post-processing function writes back data to the corresponding OpenOCD
1938 * @return on success: ERROR_OK
1939 * @return on failure: ERROR_FAIL
1941 static int ulink_execute_queue(void)
1943 struct jtag_command
*cmd
= jtag_command_queue
;
1947 switch (cmd
->type
) {
1949 ret
= ulink_queue_scan(ulink_handle
, cmd
);
1951 case JTAG_TLR_RESET
:
1952 ret
= ulink_queue_tlr_reset(ulink_handle
, cmd
);
1955 ret
= ulink_queue_runtest(ulink_handle
, cmd
);
1958 ret
= ulink_queue_reset(ulink_handle
, cmd
);
1961 ret
= ulink_queue_pathmove(ulink_handle
, cmd
);
1964 ret
= ulink_queue_sleep(ulink_handle
, cmd
);
1966 case JTAG_STABLECLOCKS
:
1967 ret
= ulink_queue_stableclocks(ulink_handle
, cmd
);
1971 LOG_ERROR("BUG: encountered unknown JTAG command type");
1975 if (ret
!= ERROR_OK
)
1981 if (ulink_handle
->commands_in_queue
> 0) {
1982 ret
= ulink_execute_queued_commands(ulink_handle
, USB_TIMEOUT
);
1983 if (ret
!= ERROR_OK
)
1986 ret
= ulink_post_process_queue(ulink_handle
);
1987 if (ret
!= ERROR_OK
)
1990 ulink_clear_queue(ulink_handle
);
1997 * Set the TCK frequency of the ULINK adapter.
1999 * @param khz desired JTAG TCK frequency.
2000 * @param jtag_speed where to store corresponding adapter-specific speed value.
2001 * @return on success: ERROR_OK
2002 * @return on failure: ERROR_FAIL
2004 static int ulink_khz(int khz
, int *jtag_speed
)
2009 LOG_ERROR("RCLK not supported");
2013 /* CLOCK_TCK commands are decoupled from others. Therefore, the frequency
2014 * setting can be done independently from all other commands. */
2016 ulink_handle
->delay_clock_tck
= -1;
2018 ret
= ulink_calculate_delay(DELAY_CLOCK_TCK
, khz
* 1000,
2019 &ulink_handle
->delay_clock_tck
);
2020 if (ret
!= ERROR_OK
)
2024 /* SCAN_{IN,OUT,IO} commands invoke CLOCK_TMS commands. Therefore, if the
2025 * requested frequency goes below the maximum frequency for SLOW_CLOCK_TMS
2026 * commands, all SCAN commands MUST also use the variable frequency
2027 * implementation! */
2029 ulink_handle
->delay_clock_tms
= -1;
2030 ulink_handle
->delay_scan_in
= -1;
2031 ulink_handle
->delay_scan_out
= -1;
2032 ulink_handle
->delay_scan_io
= -1;
2034 ret
= ulink_calculate_delay(DELAY_CLOCK_TMS
, khz
* 1000,
2035 &ulink_handle
->delay_clock_tms
);
2036 if (ret
!= ERROR_OK
)
2039 ret
= ulink_calculate_delay(DELAY_SCAN_IN
, khz
* 1000,
2040 &ulink_handle
->delay_scan_in
);
2041 if (ret
!= ERROR_OK
)
2044 ret
= ulink_calculate_delay(DELAY_SCAN_OUT
, khz
* 1000,
2045 &ulink_handle
->delay_scan_out
);
2046 if (ret
!= ERROR_OK
)
2049 ret
= ulink_calculate_delay(DELAY_SCAN_IO
, khz
* 1000,
2050 &ulink_handle
->delay_scan_io
);
2051 if (ret
!= ERROR_OK
)
2055 #ifdef _DEBUG_JTAG_IO_
2056 long f_tck
, f_tms
, f_scan_in
, f_scan_out
, f_scan_io
;
2058 ulink_calculate_frequency(DELAY_CLOCK_TCK
, ulink_handle
->delay_clock_tck
,
2060 ulink_calculate_frequency(DELAY_CLOCK_TMS
, ulink_handle
->delay_clock_tms
,
2062 ulink_calculate_frequency(DELAY_SCAN_IN
, ulink_handle
->delay_scan_in
,
2064 ulink_calculate_frequency(DELAY_SCAN_OUT
, ulink_handle
->delay_scan_out
,
2066 ulink_calculate_frequency(DELAY_SCAN_IO
, ulink_handle
->delay_scan_io
,
2069 DEBUG_JTAG_IO("ULINK TCK setup: delay_tck = %i (%li Hz),",
2070 ulink_handle
->delay_clock_tck
, f_tck
);
2071 DEBUG_JTAG_IO(" delay_tms = %i (%li Hz),",
2072 ulink_handle
->delay_clock_tms
, f_tms
);
2073 DEBUG_JTAG_IO(" delay_scan_in = %i (%li Hz),",
2074 ulink_handle
->delay_scan_in
, f_scan_in
);
2075 DEBUG_JTAG_IO(" delay_scan_out = %i (%li Hz),",
2076 ulink_handle
->delay_scan_out
, f_scan_out
);
2077 DEBUG_JTAG_IO(" delay_scan_io = %i (%li Hz),",
2078 ulink_handle
->delay_scan_io
, f_scan_io
);
2081 /* Configure the ULINK device with the new delay values */
2082 ret
= ulink_append_configure_tck_cmd(ulink_handle
,
2083 ulink_handle
->delay_scan_in
,
2084 ulink_handle
->delay_scan_out
,
2085 ulink_handle
->delay_scan_io
,
2086 ulink_handle
->delay_clock_tck
,
2087 ulink_handle
->delay_clock_tms
);
2089 if (ret
!= ERROR_OK
)
2098 * Set the TCK frequency of the ULINK adapter.
2100 * Because of the way the TCK frequency is set up in the OpenULINK firmware,
2101 * there are five different speed settings. To simplify things, the
2102 * adapter-specific speed setting value is identical to the TCK frequency in
2105 * @param speed desired adapter-specific speed value.
2106 * @return on success: ERROR_OK
2107 * @return on failure: ERROR_FAIL
2109 static int ulink_speed(int speed
)
2113 return ulink_khz(speed
, &dummy
);
2117 * Convert adapter-specific speed value to corresponding TCK frequency in kHz.
2119 * Because of the way the TCK frequency is set up in the OpenULINK firmware,
2120 * there are five different speed settings. To simplify things, the
2121 * adapter-specific speed setting value is identical to the TCK frequency in
2124 * @param speed adapter-specific speed value.
2125 * @param khz where to store corresponding TCK frequency in kHz.
2126 * @return on success: ERROR_OK
2127 * @return on failure: ERROR_FAIL
2129 static int ulink_speed_div(int speed
, int *khz
)
2137 * Initiates the firmware download to the ULINK adapter and prepares
2140 * @return on success: ERROR_OK
2141 * @return on failure: ERROR_FAIL
2143 static int ulink_init(void)
2146 char str_manufacturer
[20];
2147 bool download_firmware
= false;
2149 uint8_t input_signals
, output_signals
;
2151 ulink_handle
= calloc(1, sizeof(struct ulink
));
2152 if (ulink_handle
== NULL
)
2157 ret
= ulink_usb_open(&ulink_handle
);
2158 if (ret
!= ERROR_OK
) {
2159 LOG_ERROR("Could not open ULINK device");
2161 ulink_handle
= NULL
;
2165 /* Get String Descriptor to determine if firmware needs to be loaded */
2166 ret
= usb_get_string_simple(ulink_handle
->usb_handle
, 1, str_manufacturer
, 20);
2168 /* Could not get descriptor -> Unconfigured or original Keil firmware */
2169 download_firmware
= true;
2171 /* We got a String Descriptor, check if it is the correct one */
2172 if (strncmp(str_manufacturer
, "OpenULINK", 9) != 0)
2173 download_firmware
= true;
2176 if (download_firmware
== true) {
2177 LOG_INFO("Loading OpenULINK firmware. This is reversible by power-cycling"
2179 ret
= ulink_load_firmware_and_renumerate(&ulink_handle
,
2180 ULINK_FIRMWARE_FILE
, ULINK_RENUMERATION_DELAY
);
2181 if (ret
!= ERROR_OK
) {
2182 LOG_ERROR("Could not download firmware and re-numerate ULINK");
2184 ulink_handle
= NULL
;
2188 LOG_INFO("ULINK device is already running OpenULINK firmware");
2190 /* Initialize OpenULINK command queue */
2191 ulink_clear_queue(ulink_handle
);
2193 /* Issue one test command with short timeout */
2194 ret
= ulink_append_test_cmd(ulink_handle
);
2195 if (ret
!= ERROR_OK
)
2198 ret
= ulink_execute_queued_commands(ulink_handle
, 200);
2199 if (ret
!= ERROR_OK
) {
2200 /* Sending test command failed. The ULINK device may be forever waiting for
2201 * the host to fetch an USB Bulk IN packet (e. g. OpenOCD crashed or was
2202 * shut down by the user via Ctrl-C. Try to retrieve this Bulk IN packet. */
2203 dummy
= calloc(64, sizeof(uint8_t));
2205 ret
= usb_bulk_read(ulink_handle
->usb_handle
, (2 | USB_ENDPOINT_IN
),
2206 (char *)dummy
, 64, 200);
2211 /* Bulk IN transfer failed -> unrecoverable error condition */
2212 LOG_ERROR("Cannot communicate with ULINK device. Disconnect ULINK from "
2213 "the USB port and re-connect, then re-run OpenOCD");
2215 ulink_handle
= NULL
;
2218 #ifdef _DEBUG_USB_COMMS_
2220 /* Successfully received Bulk IN packet -> continue */
2221 LOG_INFO("Recovered from lost Bulk IN packet");
2225 ulink_clear_queue(ulink_handle
);
2227 ulink_append_get_signals_cmd(ulink_handle
);
2228 ulink_execute_queued_commands(ulink_handle
, 200);
2230 /* Post-process the single CMD_GET_SIGNALS command */
2231 input_signals
= ulink_handle
->queue_start
->payload_in
[0];
2232 output_signals
= ulink_handle
->queue_start
->payload_in
[1];
2234 ulink_print_signal_states(input_signals
, output_signals
);
2236 ulink_clear_queue(ulink_handle
);
2242 * Closes the USB handle for the ULINK device.
2244 * @return on success: ERROR_OK
2245 * @return on failure: ERROR_FAIL
2247 static int ulink_quit(void)
2251 ret
= ulink_usb_close(&ulink_handle
);
2258 * Set a custom path to ULINK firmware image and force downloading to ULINK.
2260 COMMAND_HANDLER(ulink_download_firmware_handler
)
2265 return ERROR_COMMAND_SYNTAX_ERROR
;
2268 LOG_INFO("Downloading ULINK firmware image %s", CMD_ARGV
[0]);
2270 /* Download firmware image in CMD_ARGV[0] */
2271 ret
= ulink_load_firmware_and_renumerate(&ulink_handle
, (char *)CMD_ARGV
[0],
2272 ULINK_RENUMERATION_DELAY
);
2277 /*************************** Command Registration **************************/
2279 static const struct command_registration ulink_command_handlers
[] = {
2281 .name
= "ulink_download_firmware",
2282 .handler
= &ulink_download_firmware_handler
,
2283 .mode
= COMMAND_EXEC
,
2284 .help
= "download firmware image to ULINK device",
2285 .usage
= "path/to/ulink_firmware.hex",
2287 COMMAND_REGISTRATION_DONE
,
2290 struct jtag_interface ulink_interface
= {
2293 .commands
= ulink_command_handlers
,
2294 .transports
= jtag_only
,
2296 .execute_queue
= ulink_execute_queue
,
2298 .speed
= ulink_speed
,
2299 .speed_div
= ulink_speed_div
,
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)