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 <helper/types.h>
30 #include "usb_common.h"
31 #include "OpenULINK/include/msgtypes.h"
33 /** USB Vendor ID of ULINK device in unconfigured state (no firmware loaded
34 * yet) or with OpenULINK firmware. */
35 #define ULINK_VID 0xC251
37 /** USB Product ID of ULINK device in unconfigured state (no firmware loaded
38 * yet) or with OpenULINK firmware. */
39 #define ULINK_PID 0x2710
41 /** Address of EZ-USB CPU Control & Status register. This register can be
42 * written by issuing a Control EP0 vendor request. */
43 #define CPUCS_REG 0x7F92
45 /** USB Control EP0 bRequest: "Firmware Load". */
46 #define REQUEST_FIRMWARE_LOAD 0xA0
48 /** Value to write into CPUCS to put EZ-USB into reset. */
49 #define CPU_RESET 0x01
51 /** Value to write into CPUCS to put EZ-USB out of reset. */
52 #define CPU_START 0x00
54 /** Base address of firmware in EZ-USB code space. */
55 #define FIRMWARE_ADDR 0x0000
57 /** USB interface number */
58 #define USB_INTERFACE 0
60 /** libusb timeout in ms */
61 #define USB_TIMEOUT 5000
63 /** Delay (in microseconds) to wait while EZ-USB performs ReNumeration. */
64 #define ULINK_RENUMERATION_DELAY 1500000
66 /** Default location of OpenULINK firmware image. */
67 #define ULINK_FIRMWARE_FILE PKGLIBDIR "/OpenULINK/ulink_firmware.hex"
69 /** Maximum size of a single firmware section. Entire EZ-USB code space = 8kB */
70 #define SECTION_BUFFERSIZE 8192
72 /** Tuning of OpenOCD SCAN commands split into multiple OpenULINK commands. */
73 #define SPLIT_SCAN_THRESHOLD 10
75 /** ULINK hardware type */
78 /** Original ULINK adapter, based on Cypress EZ-USB (AN2131):
79 * Full JTAG support, no SWD support. */
82 /** Newer ULINK adapter, based on NXP LPC2148. Currently unsupported. */
85 /** Newer ULINK adapter, based on EZ-USB FX2 + FPGA. Currently unsupported. */
88 /** Newer ULINK adapter, possibly based on ULINK 2. Currently unsupported. */
92 enum ulink_payload_direction
94 PAYLOAD_DIRECTION_OUT,
108 * OpenULINK command (OpenULINK command queue element).
110 * For the OUT direction payload, things are quite easy: Payload is stored
111 * in a rather small array (up to 63 bytes), the payload is always allocated
112 * by the function generating the command and freed by ulink_clear_queue().
114 * For the IN direction payload, things get a little bit more complicated:
115 * The maximum IN payload size for a single command is 64 bytes. Assume that
116 * a single OpenOCD command needs to scan 256 bytes. This results in the
117 * generation of four OpenULINK commands. The function generating these
118 * commands shall allocate an uint8_t[256] array. Each command's #payload_in
119 * pointer shall point to the corresponding offset where IN data shall be
120 * placed, while #payload_in_start shall point to the first element of the 256
122 * - first command: #payload_in_start + 0
123 * - second command: #payload_in_start + 64
124 * - third command: #payload_in_start + 128
125 * - fourth command: #payload_in_start + 192
127 * The last command sets #needs_postprocessing to true.
130 uint8_t id; ///< ULINK command ID
132 uint8_t *payload_out; ///< OUT direction payload data
133 uint8_t payload_out_size; ///< OUT direction payload size for this command
135 uint8_t *payload_in_start; ///< Pointer to first element of IN payload array
136 uint8_t *payload_in; ///< Pointer where IN payload shall be stored
137 uint8_t payload_in_size; ///< IN direction payload size for this command
139 /** Indicates if this command needs post-processing */
140 bool needs_postprocessing;
142 /** Indicates if ulink_clear_queue() should free payload_in_start */
143 bool free_payload_in_start;
145 /** Pointer to corresponding OpenOCD command for post-processing */
146 struct jtag_command *cmd_origin;
148 struct ulink_cmd *next; ///< Pointer to next command (linked list)
151 typedef struct ulink_cmd ulink_cmd_t;
153 /** Describes one driver instance */
156 struct usb_dev_handle *usb_handle;
157 enum ulink_type type;
159 int delay_scan_in; ///< Delay value for SCAN_IN commands
160 int delay_scan_out; ///< Delay value for SCAN_OUT commands
161 int delay_scan_io; ///< Delay value for SCAN_IO commands
162 int delay_clock_tck; ///< Delay value for CLOCK_TMS commands
163 int delay_clock_tms; ///< Delay value for CLOCK_TCK commands
165 int commands_in_queue; ///< Number of commands in queue
166 ulink_cmd_t *queue_start; ///< Pointer to first command in queue
167 ulink_cmd_t *queue_end; ///< Pointer to last command in queue
170 /**************************** Function Prototypes *****************************/
172 /* USB helper functions */
173 int ulink_usb_open(struct ulink **device);
174 int ulink_usb_close(struct ulink **device);
176 /* ULINK MCU (Cypress EZ-USB) specific functions */
177 int ulink_cpu_reset(struct ulink *device, char reset_bit);
178 int ulink_load_firmware_and_renumerate(struct ulink **device, char *filename,
180 int ulink_load_firmware(struct ulink *device, char *filename);
181 int ulink_write_firmware_section(struct ulink *device,
182 struct image *firmware_image, int section_index);
184 /* Generic helper functions */
185 void ulink_print_signal_states(uint8_t input_signals, uint8_t output_signals);
187 /* OpenULINK command generation helper functions */
188 int ulink_allocate_payload(ulink_cmd_t *ulink_cmd, int size,
189 enum ulink_payload_direction direction);
191 /* OpenULINK command queue helper functions */
192 int ulink_get_queue_size(struct ulink *device,
193 enum ulink_payload_direction direction);
194 void ulink_clear_queue(struct ulink *device);
195 int ulink_append_queue(struct ulink *device, ulink_cmd_t *ulink_cmd);
196 int ulink_execute_queued_commands(struct ulink *device, int timeout);
198 #ifdef _DEBUG_JTAG_IO_
199 const char * ulink_cmd_id_string(uint8_t id);
200 void ulink_print_command(ulink_cmd_t *ulink_cmd);
201 void ulink_print_queue(struct ulink *device);
204 int ulink_append_scan_cmd(struct ulink *device, enum scan_type scan_type,
205 int scan_size_bits, uint8_t *tdi, uint8_t *tdo_start, uint8_t *tdo,
206 uint8_t tms_count_start, uint8_t tms_sequence_start, uint8_t tms_count_end,
207 uint8_t tms_sequence_end, struct jtag_command *origin, bool postprocess);
208 int ulink_append_clock_tms_cmd(struct ulink *device, uint8_t count,
210 int ulink_append_clock_tck_cmd(struct ulink *device, uint16_t count);
211 int ulink_append_get_signals_cmd(struct ulink *device);
212 int ulink_append_set_signals_cmd(struct ulink *device, uint8_t low,
214 int ulink_append_sleep_cmd(struct ulink *device, uint32_t us);
215 int ulink_append_configure_tck_cmd(struct ulink *device, int delay_scan_in,
216 int delay_scan_out, int delay_scan_io, int delay_tck, int delay_tms);
217 int ulink_append_led_cmd(struct ulink *device, uint8_t led_state);
218 int ulink_append_test_cmd(struct ulink *device);
220 /* OpenULINK TCK frequency helper functions */
221 int ulink_calculate_delay(enum ulink_delay_type type, long f, int *delay);
222 int ulink_calculate_frequency(enum ulink_delay_type type, int delay, long *f);
224 /* Interface between OpenULINK and OpenOCD */
225 static void ulink_set_end_state(tap_state_t endstate);
226 int ulink_queue_statemove(struct ulink *device);
228 int ulink_queue_scan(struct ulink *device, struct jtag_command *cmd);
229 int ulink_queue_tlr_reset(struct ulink *device, struct jtag_command *cmd);
230 int ulink_queue_runtest(struct ulink *device, struct jtag_command *cmd);
231 int ulink_queue_reset(struct ulink *device, struct jtag_command *cmd);
232 int ulink_queue_pathmove(struct ulink *device, struct jtag_command *cmd);
233 int ulink_queue_sleep(struct ulink *device, struct jtag_command *cmd);
234 int ulink_queue_stableclocks(struct ulink *device, struct jtag_command *cmd);
236 int ulink_post_process_scan(ulink_cmd_t *ulink_cmd);
237 int ulink_post_process_queue(struct ulink *device);
239 /* JTAG driver functions (registered in struct jtag_interface) */
240 static int ulink_execute_queue(void);
241 static int ulink_khz(int khz, int *jtag_speed);
242 static int ulink_speed(int speed);
243 static int ulink_speed_div(int speed, int *khz);
244 static int ulink_init(void);
245 static int ulink_quit(void);
247 /****************************** Global Variables ******************************/
249 struct ulink *ulink_handle;
251 /**************************** USB helper functions ****************************/
254 * Opens the ULINK device and claims its USB interface.
256 * @param device pointer to struct ulink identifying ULINK driver instance.
257 * @return on success: ERROR_OK
258 * @return on failure: ERROR_FAIL
260 int ulink_usb_open(struct ulink **device)
263 struct usb_dev_handle *usb_handle;
265 /* Currently, only original ULINK is supported */
266 uint16_t vids[] = { ULINK_VID, 0 };
267 uint16_t pids[] = { ULINK_PID, 0 };
269 ret = jtag_usb_open(vids, pids, &usb_handle);
271 if (ret != ERROR_OK) {
275 ret = usb_claim_interface(usb_handle, 0);
281 (*device)->usb_handle = usb_handle;
282 (*device)->type = ULINK_1;
288 * Releases the ULINK interface and closes the USB device handle.
290 * @param device pointer to struct ulink identifying ULINK driver instance.
291 * @return on success: ERROR_OK
292 * @return on failure: ERROR_FAIL
294 int ulink_usb_close(struct ulink **device)
296 if (usb_release_interface((*device)->usb_handle, 0) != 0) {
300 if (usb_close((*device)->usb_handle) != 0) {
304 (*device)->usb_handle = NULL;
309 /******************* ULINK CPU (EZ-USB) specific functions ********************/
312 * Writes '0' or '1' to the CPUCS register, putting the EZ-USB CPU into reset
315 * @param device pointer to struct ulink identifying ULINK driver instance.
316 * @param reset_bit 0 to put CPU into reset, 1 to put CPU out of reset.
317 * @return on success: ERROR_OK
318 * @return on failure: ERROR_FAIL
320 int ulink_cpu_reset(struct ulink *device, char reset_bit)
324 ret = usb_control_msg(device->usb_handle,
325 (USB_ENDPOINT_OUT | USB_TYPE_VENDOR | USB_RECIP_DEVICE),
326 REQUEST_FIRMWARE_LOAD, CPUCS_REG, 0, &reset_bit, 1, USB_TIMEOUT);
328 /* usb_control_msg() returns the number of bytes transferred during the
329 * 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);
358 if (ret != ERROR_OK) {
362 ret = ulink_usb_close(device);
363 if (ret != ERROR_OK) {
369 ret = ulink_usb_open(device);
370 if (ret != ERROR_OK) {
378 * Downloads a firmware image to the ULINK's EZ-USB microcontroller
381 * @param device pointer to struct ulink identifying ULINK driver instance.
382 * @param filename an absolute or relative path to the Intel HEX file
383 * containing the firmware image.
384 * @return on success: ERROR_OK
385 * @return on failure: ERROR_FAIL
387 int ulink_load_firmware(struct ulink *device, char *filename)
389 struct image ulink_firmware_image;
392 ret = ulink_cpu_reset(device, CPU_RESET);
393 if (ret != ERROR_OK) {
394 LOG_ERROR("Could not halt ULINK CPU");
398 ulink_firmware_image.base_address = 0;
399 ulink_firmware_image.base_address_set = 0;
401 ret = image_open(&ulink_firmware_image, filename, "ihex");
402 if (ret != ERROR_OK) {
403 LOG_ERROR("Could not load firmware image");
407 /* Download all sections in the image to ULINK */
408 for (i = 0; i < ulink_firmware_image.num_sections; i++) {
409 ret = ulink_write_firmware_section(device, &ulink_firmware_image, i);
410 if (ret != ERROR_OK) {
415 image_close(&ulink_firmware_image);
417 ret = ulink_cpu_reset(device, CPU_START);
418 if (ret != ERROR_OK) {
419 LOG_ERROR("Could not restart ULINK CPU");
427 * Send one contiguous firmware section to the ULINK's EZ-USB microcontroller
430 * @param device pointer to struct ulink identifying ULINK driver instance.
431 * @param firmware_image pointer to the firmware image that contains the section
432 * which should be sent to the ULINK's EZ-USB microcontroller.
433 * @param section_index index of the section within the firmware image.
434 * @return on success: ERROR_OK
435 * @return on failure: ERROR_FAIL
437 int ulink_write_firmware_section(struct ulink *device,
438 struct image *firmware_image, int section_index)
440 uint16_t addr, size, bytes_remaining, chunk_size;
441 uint8_t data[SECTION_BUFFERSIZE];
442 uint8_t *data_ptr = data;
446 size = (uint16_t)firmware_image->sections[section_index].size;
447 addr = (uint16_t)firmware_image->sections[section_index].base_address;
449 LOG_DEBUG("section %02i at addr 0x%04x (size 0x%04x)", section_index, addr,
456 /* Copy section contents to local buffer */
457 ret = image_read_section(firmware_image, section_index, 0, size, data,
460 if ((ret != ERROR_OK) || (size_read != size)) {
461 /* Propagating the return code would return '0' (misleadingly indicating
462 * successful execution of the function) if only the size check fails. */
466 bytes_remaining = size;
468 /* Send section data in chunks of up to 64 bytes to ULINK */
469 while (bytes_remaining > 0) {
470 if (bytes_remaining > 64) {
474 chunk_size = bytes_remaining;
477 ret = usb_control_msg(device->usb_handle,
478 (USB_ENDPOINT_OUT | USB_TYPE_VENDOR | USB_RECIP_DEVICE),
479 REQUEST_FIRMWARE_LOAD, addr, FIRMWARE_ADDR, (char *)data_ptr,
480 chunk_size, USB_TIMEOUT);
482 if (ret != (int)chunk_size) {
483 /* Abort if libusb sent less data than requested */
487 bytes_remaining -= chunk_size;
489 data_ptr += chunk_size;
495 /************************** Generic helper functions **************************/
498 * Print state of interesting signals via LOG_INFO().
500 * @param input_signals input signal states as returned by CMD_GET_SIGNALS
501 * @param output_signals output signal states as returned by CMD_GET_SIGNALS
503 void ulink_print_signal_states(uint8_t input_signals, uint8_t output_signals)
505 LOG_INFO("ULINK signal states: TDI: %i, TDO: %i, TMS: %i, TCK: %i, TRST: %i,"
507 (output_signals & SIGNAL_TDI ? 1 : 0),
508 (input_signals & SIGNAL_TDO ? 1 : 0),
509 (output_signals & SIGNAL_TMS ? 1 : 0),
510 (output_signals & SIGNAL_TCK ? 1 : 0),
511 (output_signals & SIGNAL_TRST ? 0 : 1), // TRST and RESET are inverted
512 (output_signals & SIGNAL_RESET ? 0 : 1)); // by hardware
515 /**************** OpenULINK command generation helper functions ***************/
518 * Allocate and initialize space in memory for OpenULINK command payload.
520 * @param ulink_cmd pointer to command whose payload should be allocated.
521 * @param size the amount of memory to allocate (bytes).
522 * @param direction which payload to allocate.
523 * @return on success: ERROR_OK
524 * @return on failure: ERROR_FAIL
526 int ulink_allocate_payload(ulink_cmd_t *ulink_cmd, int size,
527 enum ulink_payload_direction direction)
531 payload = calloc(size, sizeof(uint8_t));
533 if (payload == NULL) {
534 LOG_ERROR("Could not allocate OpenULINK command payload: out of memory");
539 case PAYLOAD_DIRECTION_OUT:
540 if (ulink_cmd->payload_out != NULL) {
541 LOG_ERROR("BUG: Duplicate payload allocation for OpenULINK command");
545 ulink_cmd->payload_out = payload;
546 ulink_cmd->payload_out_size = size;
549 case PAYLOAD_DIRECTION_IN:
550 if (ulink_cmd->payload_in_start != NULL) {
551 LOG_ERROR("BUG: Duplicate payload allocation for OpenULINK command");
555 ulink_cmd->payload_in_start = payload;
556 ulink_cmd->payload_in = payload;
557 ulink_cmd->payload_in_size = size;
559 /* By default, free payload_in_start in ulink_clear_queue(). Commands
560 * that do not want this behavior (e. g. split scans) must turn it off
562 ulink_cmd->free_payload_in_start = true;
570 /****************** OpenULINK command queue helper functions ******************/
573 * Get the current number of bytes in the queue, including command IDs.
575 * @param device pointer to struct ulink identifying ULINK driver instance.
576 * @param direction the transfer direction for which to get byte count.
577 * @return the number of bytes currently stored in the queue for the specified
580 int ulink_get_queue_size(struct ulink *device,
581 enum ulink_payload_direction direction)
583 ulink_cmd_t *current = device->queue_start;
586 while (current != NULL) {
588 case PAYLOAD_DIRECTION_OUT:
589 sum += current->payload_out_size + 1; // + 1 byte for Command ID
591 case PAYLOAD_DIRECTION_IN:
592 sum += current->payload_in_size;
596 current = current->next;
603 * Clear the OpenULINK command queue.
605 * @param device pointer to struct ulink identifying ULINK driver instance.
606 * @return on success: ERROR_OK
607 * @return on failure: ERROR_FAIL
609 void ulink_clear_queue(struct ulink *device)
611 ulink_cmd_t *current = device->queue_start;
612 ulink_cmd_t *next = NULL;
614 while (current != NULL) {
615 /* Save pointer to next element */
616 next = current->next;
618 /* Free payloads: OUT payload can be freed immediately */
619 free(current->payload_out);
620 current->payload_out = NULL;
622 /* IN payload MUST be freed ONLY if no other commands use the
623 * payload_in_start buffer */
624 if (current->free_payload_in_start == true) {
625 free(current->payload_in_start);
626 current->payload_in_start = NULL;
627 current->payload_in = NULL;
630 /* Free queue element */
633 /* Proceed with next element */
637 device->commands_in_queue = 0;
638 device->queue_start = NULL;
639 device->queue_end = NULL;
643 * Add a command to the OpenULINK command queue.
645 * @param device pointer to struct ulink identifying ULINK driver instance.
646 * @param ulink_cmd pointer to command that shall be appended to the OpenULINK
648 * @return on success: ERROR_OK
649 * @return on failure: ERROR_FAIL
651 int ulink_append_queue(struct ulink *device, ulink_cmd_t *ulink_cmd)
653 int newsize_out, newsize_in;
656 newsize_out = ulink_get_queue_size(device, PAYLOAD_DIRECTION_OUT) + 1
657 + ulink_cmd->payload_out_size;
659 newsize_in = ulink_get_queue_size(device, PAYLOAD_DIRECTION_IN)
660 + ulink_cmd->payload_in_size;
662 /* Check if the current command can be appended to the queue */
663 if ((newsize_out > 64) || (newsize_in > 64)) {
664 /* New command does not fit. Execute all commands in queue before starting
665 * new queue with the current command as first entry. */
666 ret = ulink_execute_queued_commands(device, USB_TIMEOUT);
667 if (ret != ERROR_OK) {
671 ret = ulink_post_process_queue(device);
672 if (ret != ERROR_OK) {
676 ulink_clear_queue(device);
679 if (device->queue_start == NULL) {
680 /* Queue was empty */
681 device->commands_in_queue = 1;
683 device->queue_start = ulink_cmd;
684 device->queue_end = ulink_cmd;
687 /* There are already commands in the queue */
688 device->commands_in_queue++;
690 device->queue_end->next = ulink_cmd;
691 device->queue_end = ulink_cmd;
698 * Sends all queued OpenULINK commands to the ULINK for execution.
700 * @param device pointer to struct ulink identifying ULINK driver instance.
701 * @return on success: ERROR_OK
702 * @return on failure: ERROR_FAIL
704 int ulink_execute_queued_commands(struct ulink *device, int timeout)
706 ulink_cmd_t *current;
707 int ret, i, index_out, index_in, count_out, count_in;
710 #ifdef _DEBUG_JTAG_IO_
711 ulink_print_queue(device);
718 for (current = device->queue_start; current; current = current->next) {
719 /* Add command to packet */
720 buffer[index_out] = current->id;
724 for (i = 0; i < current->payload_out_size; i++) {
725 buffer[index_out + i] = current->payload_out[i];
727 index_out += current->payload_out_size;
728 count_in += current->payload_in_size;
729 count_out += current->payload_out_size;
732 /* Send packet to ULINK */
733 ret = usb_bulk_write(device->usb_handle, (2 | USB_ENDPOINT_OUT),
734 (char *)buffer, count_out, timeout);
738 if (ret != count_out) {
742 /* Wait for response if commands contain IN payload data */
744 ret = usb_bulk_read(device->usb_handle, (2 | USB_ENDPOINT_IN),
745 (char *)buffer, 64, timeout);
749 if (ret != count_in) {
753 /* Write back IN payload data */
755 for (current = device->queue_start; current; current = current->next) {
756 for (i = 0; i < current->payload_in_size; i++) {
757 current->payload_in[i] = buffer[index_in];
766 #ifdef _DEBUG_JTAG_IO_
769 * Convert an OpenULINK command ID (\a id) to a human-readable string.
771 * @param id the OpenULINK command ID.
772 * @return the corresponding human-readable string.
774 const char * ulink_cmd_id_string(uint8_t id)
778 return "CMD_SCAN_IN";
780 case CMD_SLOW_SCAN_IN:
781 return "CMD_SLOW_SCAN_IN";
784 return "CMD_SCAN_OUT";
786 case CMD_SLOW_SCAN_OUT:
787 return "CMD_SLOW_SCAN_OUT";
790 return "CMD_SCAN_IO";
792 case CMD_SLOW_SCAN_IO:
793 return "CMD_SLOW_SCAN_IO";
796 return "CMD_CLOCK_TMS";
798 case CMD_SLOW_CLOCK_TMS:
799 return "CMD_SLOW_CLOCK_TMS";
802 return "CMD_CLOCK_TCK";
804 case CMD_SLOW_CLOCK_TCK:
805 return "CMD_SLOW_CLOCK_TCK";
808 return "CMD_SLEEP_US";
811 return "CMD_SLEEP_MS";
813 case CMD_GET_SIGNALS:
814 return "CMD_GET_SIGNALS";
816 case CMD_SET_SIGNALS:
817 return "CMD_SET_SIGNALS";
819 case CMD_CONFIGURE_TCK_FREQ:
820 return "CMD_CONFIGURE_TCK_FREQ";
823 return "CMD_SET_LEDS";
829 return "CMD_UNKNOWN";
835 * Print one OpenULINK command to stdout.
837 * @param ulink_cmd pointer to OpenULINK command.
839 void ulink_print_command(ulink_cmd_t *ulink_cmd)
843 printf(" %-22s | OUT size = %i, bytes = 0x", ulink_cmd_id_string(ulink_cmd->id),
844 ulink_cmd->payload_out_size);
846 for (i = 0; i < ulink_cmd->payload_out_size; i++) {
847 printf("%02X ", ulink_cmd->payload_out[i]);
849 printf("\n | IN size = %i\n", ulink_cmd->payload_in_size);
853 * Print the OpenULINK command queue to stdout.
855 * @param device pointer to struct ulink identifying ULINK driver instance.
857 void ulink_print_queue(struct ulink *device)
859 ulink_cmd_t *current;
861 printf("OpenULINK command queue:\n");
863 for (current = device->queue_start; current; current = current->next) {
864 ulink_print_command(current);
868 #endif /* _DEBUG_JTAG_IO_ */
873 * Creates and appends a JTAG scan command to the OpenULINK command queue.
874 * A JTAG scan consists of three steps:
875 * - Move to the desired SHIFT state, depending on scan type (IR/DR scan).
876 * - Shift TDI data into the JTAG chain, optionally reading the TDO pin.
877 * - Move to the desired end state.
879 * @param device pointer to struct ulink identifying ULINK driver instance.
880 * @param scan_type the type of the scan (IN, OUT, IO (bidirectional)).
881 * @param scan_size_bits number of bits to shift into the JTAG chain.
882 * @param tdi pointer to array containing TDI data.
883 * @param tdo_start pointer to first element of array where TDO data shall be
884 * stored. See #ulink_cmd for details.
885 * @param tdo pointer to array where TDO data shall be stored
886 * @param tms_count_start number of TMS state transitions to perform BEFORE
887 * shifting data into the JTAG chain.
888 * @param tms_sequence_start sequence of TMS state transitions that will be
889 * performed BEFORE shifting data into the JTAG chain.
890 * @param tms_count_end number of TMS state transitions to perform AFTER
891 * shifting data into the JTAG chain.
892 * @param tms_sequence_end sequence of TMS state transitions that will be
893 * performed AFTER shifting data into the JTAG chain.
894 * @param origin pointer to OpenOCD command that generated this scan command.
895 * @param postprocess whether this command needs to be post-processed after
897 * @return on success: ERROR_OK
898 * @return on failure: ERROR_FAIL
900 int ulink_append_scan_cmd(struct ulink *device, enum scan_type scan_type,
901 int scan_size_bits, uint8_t *tdi, uint8_t *tdo_start, uint8_t *tdo,
902 uint8_t tms_count_start, uint8_t tms_sequence_start, uint8_t tms_count_end,
903 uint8_t tms_sequence_end, struct jtag_command *origin, bool postprocess)
905 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
906 int ret, i, scan_size_bytes;
907 uint8_t bits_last_byte;
913 /* Check size of command. USB buffer can hold 64 bytes, 1 byte is command ID,
914 * 5 bytes are setup data -> 58 remaining payload bytes for TDI data */
915 if (scan_size_bits > (58 * 8)) {
916 LOG_ERROR("BUG: Tried to create CMD_SCAN_IO OpenULINK command with too"
921 scan_size_bytes = DIV_ROUND_UP(scan_size_bits, 8);
923 bits_last_byte = scan_size_bits % 8;
924 if (bits_last_byte == 0) {
928 /* Allocate out_payload depending on scan type */
931 if (device->delay_scan_in < 0) {
932 cmd->id = CMD_SCAN_IN;
935 cmd->id = CMD_SLOW_SCAN_IN;
937 ret = ulink_allocate_payload(cmd, 5, PAYLOAD_DIRECTION_OUT);
940 if (device->delay_scan_out < 0) {
941 cmd->id = CMD_SCAN_OUT;
944 cmd->id = CMD_SLOW_SCAN_OUT;
946 ret = ulink_allocate_payload(cmd, scan_size_bytes + 5, PAYLOAD_DIRECTION_OUT);
949 if (device->delay_scan_io < 0) {
950 cmd->id = CMD_SCAN_IO;
953 cmd->id = CMD_SLOW_SCAN_IO;
955 ret = ulink_allocate_payload(cmd, scan_size_bytes + 5, PAYLOAD_DIRECTION_OUT);
958 LOG_ERROR("BUG: ulink_append_scan_cmd() encountered an unknown scan type");
963 if (ret != ERROR_OK) {
967 /* Build payload_out that is common to all scan types */
968 cmd->payload_out[0] = scan_size_bytes & 0xFF;
969 cmd->payload_out[1] = bits_last_byte & 0xFF;
970 cmd->payload_out[2] = ((tms_count_start & 0x0F) << 4) | (tms_count_end & 0x0F);
971 cmd->payload_out[3] = tms_sequence_start;
972 cmd->payload_out[4] = tms_sequence_end;
974 /* Setup payload_out for types with OUT transfer */
975 if ((scan_type == SCAN_OUT) || (scan_type == SCAN_IO)) {
976 for (i = 0; i < scan_size_bytes; i++) {
977 cmd->payload_out[i + 5] = tdi[i];
981 /* Setup payload_in pointers for types with IN transfer */
982 if ((scan_type == SCAN_IN) || (scan_type == SCAN_IO)) {
983 cmd->payload_in_start = tdo_start;
984 cmd->payload_in = tdo;
985 cmd->payload_in_size = scan_size_bytes;
988 cmd->needs_postprocessing = postprocess;
989 cmd->cmd_origin = origin;
991 /* For scan commands, we free payload_in_start only when the command is
992 * the last in a series of split commands or a stand-alone command */
993 cmd->free_payload_in_start = postprocess;
995 return ulink_append_queue(device, cmd);
999 * Perform TAP state transitions
1001 * @param device pointer to struct ulink identifying ULINK driver instance.
1002 * @param count defines the number of TCK clock cycles generated (up to 8).
1003 * @param sequence defines the TMS pin levels for each state transition. The
1004 * Least-Significant Bit is read first.
1005 * @return on success: ERROR_OK
1006 * @return on failure: ERROR_FAIL
1008 int ulink_append_clock_tms_cmd(struct ulink *device, uint8_t count,
1011 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
1018 if (device->delay_clock_tms < 0) {
1019 cmd->id = CMD_CLOCK_TMS;
1022 cmd->id = CMD_SLOW_CLOCK_TMS;
1025 /* CMD_CLOCK_TMS has two OUT payload bytes and zero IN payload bytes */
1026 ret = ulink_allocate_payload(cmd, 2, PAYLOAD_DIRECTION_OUT);
1027 if (ret != ERROR_OK) {
1031 cmd->payload_out[0] = count;
1032 cmd->payload_out[1] = sequence;
1034 return ulink_append_queue(device, cmd);
1038 * Generate a defined amount of TCK clock cycles
1040 * All other JTAG signals are left unchanged.
1042 * @param device pointer to struct ulink identifying ULINK driver instance.
1043 * @param count the number of TCK clock cycles to generate.
1044 * @return on success: ERROR_OK
1045 * @return on failure: ERROR_FAIL
1047 int ulink_append_clock_tck_cmd(struct ulink *device, uint16_t count)
1049 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
1056 if (device->delay_clock_tck < 0) {
1057 cmd->id = CMD_CLOCK_TCK;
1060 cmd->id = CMD_SLOW_CLOCK_TCK;
1063 /* CMD_CLOCK_TCK has two OUT payload bytes and zero IN payload bytes */
1064 ret = ulink_allocate_payload(cmd, 2, PAYLOAD_DIRECTION_OUT);
1065 if (ret != ERROR_OK) {
1069 cmd->payload_out[0] = count & 0xff;
1070 cmd->payload_out[1] = (count >> 8) & 0xff;
1072 return ulink_append_queue(device, cmd);
1076 * Read JTAG signals.
1078 * @param device pointer to struct ulink identifying ULINK driver instance.
1079 * @return on success: ERROR_OK
1080 * @return on failure: ERROR_FAIL
1082 int ulink_append_get_signals_cmd(struct ulink *device)
1084 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
1091 cmd->id = CMD_GET_SIGNALS;
1092 cmd->needs_postprocessing = true;
1094 /* CMD_GET_SIGNALS has two IN payload bytes */
1095 ret = ulink_allocate_payload(cmd, 2, PAYLOAD_DIRECTION_IN);
1097 if (ret != ERROR_OK) {
1101 return ulink_append_queue(device, cmd);
1105 * Arbitrarily set JTAG output signals.
1107 * @param device pointer to struct ulink identifying ULINK driver instance.
1108 * @param low defines which signals will be de-asserted. Each bit corresponds
1117 * @param high defines which signals will be asserted.
1118 * @return on success: ERROR_OK
1119 * @return on failure: ERROR_FAIL
1121 int ulink_append_set_signals_cmd(struct ulink *device, uint8_t low,
1124 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
1131 cmd->id = CMD_SET_SIGNALS;
1133 /* CMD_SET_SIGNALS has two OUT payload bytes and zero IN payload bytes */
1134 ret = ulink_allocate_payload(cmd, 2, PAYLOAD_DIRECTION_OUT);
1136 if (ret != ERROR_OK) {
1140 cmd->payload_out[0] = low;
1141 cmd->payload_out[1] = high;
1143 return ulink_append_queue(device, cmd);
1147 * Sleep for a pre-defined number of microseconds
1149 * @param device pointer to struct ulink identifying ULINK driver instance.
1150 * @param us the number microseconds to sleep.
1151 * @return on success: ERROR_OK
1152 * @return on failure: ERROR_FAIL
1154 int ulink_append_sleep_cmd(struct ulink *device, uint32_t us)
1156 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
1163 cmd->id = CMD_SLEEP_US;
1165 /* CMD_SLEEP_US has two OUT payload bytes and zero IN payload bytes */
1166 ret = ulink_allocate_payload(cmd, 2, PAYLOAD_DIRECTION_OUT);
1168 if (ret != ERROR_OK) {
1172 cmd->payload_out[0] = us & 0x00ff;
1173 cmd->payload_out[1] = (us >> 8) & 0x00ff;
1175 return ulink_append_queue(device, cmd);
1179 * Set TCK delay counters
1181 * @param device pointer to struct ulink identifying ULINK driver instance.
1182 * @param delay_scan_in delay count top value in jtag_slow_scan_in() function.
1183 * @param delay_scan_out delay count top value in jtag_slow_scan_out() function.
1184 * @param delay_scan_io delay count top value in jtag_slow_scan_io() function.
1185 * @param delay_tck delay count top value in jtag_clock_tck() function.
1186 * @param delay_tms delay count top value in jtag_slow_clock_tms() function.
1187 * @return on success: ERROR_OK
1188 * @return on failure: ERROR_FAIL
1190 int ulink_append_configure_tck_cmd(struct ulink *device, int delay_scan_in,
1191 int delay_scan_out, int delay_scan_io, int delay_tck, int delay_tms)
1193 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
1200 cmd->id = CMD_CONFIGURE_TCK_FREQ;
1202 /* CMD_CONFIGURE_TCK_FREQ has five OUT payload bytes and zero
1203 * IN payload bytes */
1204 ret = ulink_allocate_payload(cmd, 5, PAYLOAD_DIRECTION_OUT);
1205 if (ret != ERROR_OK) {
1209 if (delay_scan_in < 0) {
1210 cmd->payload_out[0] = 0;
1213 cmd->payload_out[0] = (uint8_t)delay_scan_in;
1216 if (delay_scan_out < 0) {
1217 cmd->payload_out[1] = 0;
1220 cmd->payload_out[1] = (uint8_t)delay_scan_out;
1223 if (delay_scan_io < 0) {
1224 cmd->payload_out[2] = 0;
1227 cmd->payload_out[2] = (uint8_t)delay_scan_io;
1230 if (delay_tck < 0) {
1231 cmd->payload_out[3] = 0;
1234 cmd->payload_out[3] = (uint8_t)delay_tck;
1237 if (delay_tms < 0) {
1238 cmd->payload_out[4] = 0;
1241 cmd->payload_out[4] = (uint8_t)delay_tms;
1244 return ulink_append_queue(device, cmd);
1248 * Turn on/off ULINK LEDs.
1250 * @param device pointer to struct ulink identifying ULINK driver instance.
1251 * @param led_state which LED(s) to turn on or off. The following bits
1252 * influence the LEDS:
1253 * - Bit 0: Turn COM LED on
1254 * - Bit 1: Turn RUN LED on
1255 * - Bit 2: Turn COM LED off
1256 * - Bit 3: Turn RUN LED off
1257 * If both the on-bit and the off-bit for the same LED is set, the LED is
1259 * @return on success: ERROR_OK
1260 * @return on failure: ERROR_FAIL
1262 int ulink_append_led_cmd(struct ulink *device, uint8_t led_state)
1264 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
1271 cmd->id = CMD_SET_LEDS;
1273 /* CMD_SET_LEDS has one OUT payload byte and zero IN payload bytes */
1274 ret = ulink_allocate_payload(cmd, 1, PAYLOAD_DIRECTION_OUT);
1275 if (ret != ERROR_OK) {
1279 cmd->payload_out[0] = led_state;
1281 return ulink_append_queue(device, cmd);
1285 * Test command. Used to check if the ULINK device is ready to accept new
1288 * @param device pointer to struct ulink identifying ULINK driver instance.
1289 * @return on success: ERROR_OK
1290 * @return on failure: ERROR_FAIL
1292 int ulink_append_test_cmd(struct ulink *device)
1294 ulink_cmd_t *cmd = calloc(1, sizeof(ulink_cmd_t));
1303 /* CMD_TEST has one OUT payload byte and zero IN payload bytes */
1304 ret = ulink_allocate_payload(cmd, 1, PAYLOAD_DIRECTION_OUT);
1305 if (ret != ERROR_OK) {
1309 cmd->payload_out[0] = 0xAA;
1311 return ulink_append_queue(device, cmd);
1314 /****************** OpenULINK TCK frequency helper functions ******************/
1317 * Calculate delay values for a given TCK frequency.
1319 * The OpenULINK firmware uses five different speed values for different
1320 * commands. These speed values are calculated in these functions.
1322 * The five different commands which support variable TCK frequency are
1323 * implemented twice in the firmware:
1324 * 1. Maximum possible frequency without any artificial delay
1325 * 2. Variable frequency with artificial linear delay loop
1327 * To set the ULINK to maximum frequency, it is only neccessary to use the
1328 * corresponding command IDs. To set the ULINK to a lower frequency, the
1329 * delay loop top values have to be calculated first. Then, a
1330 * CMD_CONFIGURE_TCK_FREQ command needs to be sent to the ULINK device.
1332 * The delay values are described by linear equations:
1334 * (t = period, k = constant, x = delay value, d = constant)
1336 * Thus, the delay can be calculated as in the following equation:
1339 * The constants in these equations have been determined and validated by
1340 * measuring the frequency resulting from different delay values.
1342 * @param type for which command to calculate the delay value.
1343 * @param f TCK frequency for which to calculate the delay value in Hz.
1344 * @param delay where to store resulting delay value.
1345 * @return on success: ERROR_OK
1346 * @return on failure: ERROR_FAIL
1348 int ulink_calculate_delay(enum ulink_delay_type type, long f, int *delay)
1352 /* Calculate period of requested TCK frequency */
1353 t = 1.0 / (float)(f);
1356 case DELAY_CLOCK_TCK:
1357 x = (t - (float)(6E-6)) / (float)(4E-6);
1359 case DELAY_CLOCK_TMS:
1360 x = (t - (float)(8.5E-6)) / (float)(4E-6);
1363 x = (t - (float)(8.8308E-6)) / (float)(4E-6);
1365 case DELAY_SCAN_OUT:
1366 x = (t - (float)(1.0527E-5)) / (float)(4E-6);
1369 x = (t - (float)(1.3132E-5)) / (float)(4E-6);
1376 /* Check if the delay value is negative. This happens when a frequency is
1377 * requested that is too high for the delay loop implementation. In this
1378 * case, set delay value to zero. */
1383 /* We need to convert the exact delay value to an integer. Therefore, we
1384 * round the exact value UP to ensure that the resulting frequency is NOT
1385 * higher than the requested frequency. */
1388 /* Check if the value is within limits */
1393 *delay = (int)x_ceil;
1399 * Calculate frequency for a given delay value.
1401 * Similar to the #ulink_calculate_delay function, this function calculates the
1402 * TCK frequency for a given delay value by using linear equations of the form:
1404 * (t = period, k = constant, x = delay value, d = constant)
1406 * @param type for which command to calculate the delay value.
1407 * @param delay delay value for which to calculate the resulting TCK frequency.
1408 * @param f where to store the resulting TCK frequency.
1409 * @return on success: ERROR_OK
1410 * @return on failure: ERROR_FAIL
1412 int ulink_calculate_frequency(enum ulink_delay_type type, int delay, long *f)
1414 float t, f_float, f_rounded;
1421 case DELAY_CLOCK_TCK:
1423 t = (float)(2.666E-6);
1426 t = (float)(4E-6) * (float)(delay) + (float)(6E-6);
1429 case DELAY_CLOCK_TMS:
1431 t = (float)(5.666E-6);
1434 t = (float)(4E-6) * (float)(delay) + (float)(8.5E-6);
1439 t = (float)(5.5E-6);
1442 t = (float)(4E-6) * (float)(delay) + (float)(8.8308E-6);
1445 case DELAY_SCAN_OUT:
1447 t = (float)(7.0E-6);
1450 t = (float)(4E-6) * (float)(delay) + (float)(1.0527E-5);
1455 t = (float)(9.926E-6);
1458 t = (float)(4E-6) * (float)(delay) + (float)(1.3132E-5);
1467 f_rounded = roundf(f_float);
1468 *f = (long)f_rounded;
1473 /******************* Interface between OpenULINK and OpenOCD ******************/
1476 * Sets the end state follower (see interface.h) if \a endstate is a stable
1479 * @param endstate the state the end state follower should be set to.
1481 static void ulink_set_end_state(tap_state_t endstate)
1483 if (tap_is_state_stable(endstate)) {
1484 tap_set_end_state(endstate);
1487 LOG_ERROR("BUG: %s is not a valid end state", tap_state_name(endstate));
1488 exit( EXIT_FAILURE);
1493 * Move from the current TAP state to the current TAP end state.
1495 * @param device pointer to struct ulink identifying ULINK driver instance.
1496 * @return on success: ERROR_OK
1497 * @return on failure: ERROR_FAIL
1499 int ulink_queue_statemove(struct ulink *device)
1501 uint8_t tms_sequence, tms_count;
1504 if (tap_get_state() == tap_get_end_state()) {
1505 /* Do nothing if we are already there */
1509 tms_sequence = tap_get_tms_path(tap_get_state(), tap_get_end_state());
1510 tms_count = tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1512 ret = ulink_append_clock_tms_cmd(device, tms_count, tms_sequence);
1514 if (ret == ERROR_OK) {
1515 tap_set_state(tap_get_end_state());
1522 * Perform a scan operation on a JTAG register.
1524 * @param device pointer to struct ulink identifying ULINK driver instance.
1525 * @param cmd pointer to the command that shall be executed.
1526 * @return on success: ERROR_OK
1527 * @return on failure: ERROR_FAIL
1529 int ulink_queue_scan(struct ulink *device, struct jtag_command *cmd)
1531 uint32_t scan_size_bits, scan_size_bytes, bits_last_scan;
1532 uint32_t scans_max_payload, bytecount;
1533 uint8_t *tdi_buffer_start = NULL, *tdi_buffer = NULL;
1534 uint8_t *tdo_buffer_start = NULL, *tdo_buffer = NULL;
1536 uint8_t first_tms_count, first_tms_sequence;
1537 uint8_t last_tms_count, last_tms_sequence;
1539 uint8_t tms_count_pause, tms_sequence_pause;
1540 uint8_t tms_count_resume, tms_sequence_resume;
1542 uint8_t tms_count_start, tms_sequence_start;
1543 uint8_t tms_count_end, tms_sequence_end;
1545 enum scan_type type;
1548 /* Determine scan size */
1549 scan_size_bits = jtag_scan_size(cmd->cmd.scan);
1550 scan_size_bytes = DIV_ROUND_UP(scan_size_bits, 8);
1552 /* Determine scan type (IN/OUT/IO) */
1553 type = jtag_scan_type(cmd->cmd.scan);
1555 /* Determine number of scan commands with maximum payload */
1556 scans_max_payload = scan_size_bytes / 58;
1558 /* Determine size of last shift command */
1559 bits_last_scan = scan_size_bits - (scans_max_payload * 58 * 8);
1561 /* Allocate TDO buffer if required */
1562 if ((type == SCAN_IN) || (type == SCAN_IO)) {
1563 tdo_buffer_start = calloc(sizeof(uint8_t), scan_size_bytes);
1565 if (tdo_buffer_start == NULL) {
1569 tdo_buffer = tdo_buffer_start;
1572 /* Fill TDI buffer if required */
1573 if ((type == SCAN_OUT) || (type == SCAN_IO)) {
1574 jtag_build_buffer(cmd->cmd.scan, &tdi_buffer_start);
1575 tdi_buffer = tdi_buffer_start;
1578 /* Get TAP state transitions */
1579 if (cmd->cmd.scan->ir_scan) {
1580 ulink_set_end_state(TAP_IRSHIFT);
1581 first_tms_count = tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1582 first_tms_sequence = tap_get_tms_path(tap_get_state(), tap_get_end_state());
1584 tap_set_state(TAP_IRSHIFT);
1585 tap_set_end_state(cmd->cmd.scan->end_state);
1586 last_tms_count = tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1587 last_tms_sequence = tap_get_tms_path(tap_get_state(), tap_get_end_state());
1589 /* TAP state transitions for split scans */
1590 tms_count_pause = tap_get_tms_path_len(TAP_IRSHIFT, TAP_IRPAUSE);
1591 tms_sequence_pause = tap_get_tms_path(TAP_IRSHIFT, TAP_IRPAUSE);
1592 tms_count_resume = tap_get_tms_path_len(TAP_IRPAUSE, TAP_IRSHIFT);
1593 tms_sequence_resume = tap_get_tms_path(TAP_IRPAUSE, TAP_IRSHIFT);
1596 ulink_set_end_state(TAP_DRSHIFT);
1597 first_tms_count = tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1598 first_tms_sequence = tap_get_tms_path(tap_get_state(), tap_get_end_state());
1600 tap_set_state(TAP_DRSHIFT);
1601 tap_set_end_state(cmd->cmd.scan->end_state);
1602 last_tms_count = tap_get_tms_path_len(tap_get_state(), tap_get_end_state());
1603 last_tms_sequence = tap_get_tms_path(tap_get_state(), tap_get_end_state());
1605 /* TAP state transitions for split scans */
1606 tms_count_pause = tap_get_tms_path_len(TAP_DRSHIFT, TAP_DRPAUSE);
1607 tms_sequence_pause = tap_get_tms_path(TAP_DRSHIFT, TAP_DRPAUSE);
1608 tms_count_resume = tap_get_tms_path_len(TAP_DRPAUSE, TAP_DRSHIFT);
1609 tms_sequence_resume = tap_get_tms_path(TAP_DRPAUSE, TAP_DRSHIFT);
1612 /* Generate scan commands */
1613 bytecount = scan_size_bytes;
1614 while (bytecount > 0) {
1615 if (bytecount == scan_size_bytes) {
1616 /* This is the first scan */
1617 tms_count_start = first_tms_count;
1618 tms_sequence_start = first_tms_sequence;
1621 /* Resume from previous scan */
1622 tms_count_start = tms_count_resume;
1623 tms_sequence_start = tms_sequence_resume;
1626 if (bytecount > 58) { /* Full scan, at least one scan will follow */
1627 tms_count_end = tms_count_pause;
1628 tms_sequence_end = tms_sequence_pause;
1630 ret = ulink_append_scan_cmd(device, type, 58 * 8, tdi_buffer,
1631 tdo_buffer_start, tdo_buffer, tms_count_start, tms_sequence_start,
1632 tms_count_end, tms_sequence_end, cmd, false);
1636 /* Update TDI and TDO buffer pointers */
1637 if (tdi_buffer_start != NULL) {
1640 if (tdo_buffer_start != NULL) {
1644 else if (bytecount == 58) { /* Full scan, no further scans */
1645 tms_count_end = last_tms_count;
1646 tms_sequence_end = last_tms_sequence;
1648 ret = ulink_append_scan_cmd(device, type, 58 * 8, tdi_buffer,
1649 tdo_buffer_start, tdo_buffer, tms_count_start, tms_sequence_start,
1650 tms_count_end, tms_sequence_end, cmd, true);
1654 else { /* Scan with less than maximum payload, no further scans */
1655 tms_count_end = last_tms_count;
1656 tms_sequence_end = last_tms_sequence;
1658 ret = ulink_append_scan_cmd(device, type, bits_last_scan, tdi_buffer,
1659 tdo_buffer_start, tdo_buffer, tms_count_start, tms_sequence_start,
1660 tms_count_end, tms_sequence_end, cmd, true);
1665 if (ret != ERROR_OK) {
1666 free(tdi_buffer_start);
1671 free(tdi_buffer_start);
1673 /* Set current state to the end state requested by the command */
1674 tap_set_state(cmd->cmd.scan->end_state);
1680 * Move the TAP into the Test Logic Reset state.
1682 * @param device pointer to struct ulink identifying ULINK driver instance.
1683 * @param cmd pointer to the command that shall be executed.
1684 * @return on success: ERROR_OK
1685 * @return on failure: ERROR_FAIL
1687 int ulink_queue_tlr_reset(struct ulink *device, struct jtag_command *cmd)
1691 ret = ulink_append_clock_tms_cmd(device, 5, 0xff);
1693 if (ret == ERROR_OK) {
1694 tap_set_state(TAP_RESET);
1703 * Generate TCK clock cycles while remaining
1704 * in the Run-Test/Idle state.
1706 * @param device pointer to struct ulink identifying ULINK driver instance.
1707 * @param cmd pointer to the command that shall be executed.
1708 * @return on success: ERROR_OK
1709 * @return on failure: ERROR_FAIL
1711 int ulink_queue_runtest(struct ulink *device, struct jtag_command *cmd)
1715 /* Only perform statemove if the TAP currently isn't in the TAP_IDLE state */
1716 if (tap_get_state() != TAP_IDLE) {
1717 ulink_set_end_state(TAP_IDLE);
1718 ulink_queue_statemove(device);
1721 /* Generate the clock cycles */
1722 ret = ulink_append_clock_tck_cmd(device, cmd->cmd.runtest->num_cycles);
1723 if (ret != ERROR_OK) {
1727 /* Move to end state specified in command */
1728 if (cmd->cmd.runtest->end_state != tap_get_state()) {
1729 tap_set_end_state(cmd->cmd.runtest->end_state);
1730 ulink_queue_statemove(device);
1737 * Execute a JTAG_RESET command
1739 * @param cmd pointer to the command that shall be executed.
1740 * @return on success: ERROR_OK
1741 * @return on failure: ERROR_FAIL
1743 int ulink_queue_reset(struct ulink *device, struct jtag_command *cmd)
1745 uint8_t low = 0, high = 0;
1747 if (cmd->cmd.reset->trst) {
1748 tap_set_state(TAP_RESET);
1749 high |= SIGNAL_TRST;
1755 if (cmd->cmd.reset->srst) {
1756 high |= SIGNAL_RESET;
1759 low |= SIGNAL_RESET;
1762 return ulink_append_set_signals_cmd(device, low, high);
1766 * Move to one TAP state or several states in succession.
1768 * @param device pointer to struct ulink identifying ULINK driver instance.
1769 * @param cmd pointer to the command that shall be executed.
1770 * @return on success: ERROR_OK
1771 * @return on failure: ERROR_FAIL
1773 int ulink_queue_pathmove(struct ulink *device, struct jtag_command *cmd)
1775 int ret, i, num_states, batch_size, state_count;
1777 uint8_t tms_sequence;
1779 num_states = cmd->cmd.pathmove->num_states;
1780 path = cmd->cmd.pathmove->path;
1783 while (num_states > 0) {
1786 /* Determine batch size */
1787 if (num_states >= 8) {
1791 batch_size = num_states;
1794 for (i = 0; i < batch_size; i++) {
1795 if (tap_state_transition(tap_get_state(), false) == path[state_count]) {
1796 /* Append '0' transition: clear bit 'i' in tms_sequence */
1797 buf_set_u32(&tms_sequence, i, 1, 0x0);
1799 else if (tap_state_transition(tap_get_state(), true)
1800 == path[state_count]) {
1801 /* Append '1' transition: set bit 'i' in tms_sequence */
1802 buf_set_u32(&tms_sequence, i, 1, 0x1);
1805 /* Invalid state transition */
1806 LOG_ERROR("BUG: %s -> %s isn't a valid TAP state transition",
1807 tap_state_name(tap_get_state()),
1808 tap_state_name(path[state_count]));
1812 tap_set_state(path[state_count]);
1817 /* Append CLOCK_TMS command to OpenULINK command queue */
1819 "pathmove batch: count = %i, sequence = 0x%x", batch_size, tms_sequence);
1820 ret = ulink_append_clock_tms_cmd(ulink_handle, batch_size, tms_sequence);
1821 if (ret != ERROR_OK) {
1830 * Sleep for a specific amount of time.
1832 * @param device pointer to struct ulink identifying ULINK driver instance.
1833 * @param cmd pointer to the command that shall be executed.
1834 * @return on success: ERROR_OK
1835 * @return on failure: ERROR_FAIL
1837 int ulink_queue_sleep(struct ulink *device, struct jtag_command *cmd)
1839 /* IMPORTANT! Due to the time offset in command execution introduced by
1840 * command queueing, this needs to be implemented in the ULINK device */
1841 return ulink_append_sleep_cmd(device, cmd->cmd.sleep->us);
1845 * Generate TCK cycles while remaining in a stable state.
1847 * @param device pointer to struct ulink identifying ULINK driver instance.
1848 * @param cmd pointer to the command that shall be executed.
1850 int ulink_queue_stableclocks(struct ulink *device, struct jtag_command *cmd)
1853 unsigned num_cycles;
1855 if (!tap_is_state_stable(tap_get_state())) {
1856 LOG_ERROR("JTAG_STABLECLOCKS: state not stable");
1860 num_cycles = cmd->cmd.stableclocks->num_cycles;
1862 /* TMS stays either high (Test Logic Reset state) or low (all other states) */
1863 if (tap_get_state() == TAP_RESET) {
1864 ret = ulink_append_set_signals_cmd(device, 0, SIGNAL_TMS);
1867 ret = ulink_append_set_signals_cmd(device, SIGNAL_TMS, 0);
1870 if (ret != ERROR_OK) {
1874 while (num_cycles > 0) {
1875 if (num_cycles > 0xFFFF) {
1876 /* OpenULINK CMD_CLOCK_TCK can generate up to 0xFFFF (uint16_t) cycles */
1877 ret = ulink_append_clock_tck_cmd(device, 0xFFFF);
1878 num_cycles -= 0xFFFF;
1881 ret = ulink_append_clock_tck_cmd(device, num_cycles);
1885 if (ret != ERROR_OK) {
1894 * Post-process JTAG_SCAN command
1896 * @param ulink_cmd pointer to OpenULINK command that shall be processed.
1897 * @return on success: ERROR_OK
1898 * @return on failure: ERROR_FAIL
1900 int ulink_post_process_scan(ulink_cmd_t *ulink_cmd)
1902 struct jtag_command *cmd = ulink_cmd->cmd_origin;
1905 switch (jtag_scan_type(cmd->cmd.scan)) {
1908 ret = jtag_read_buffer(ulink_cmd->payload_in_start, cmd->cmd.scan);
1911 /* Nothing to do for OUT scans */
1915 LOG_ERROR("BUG: ulink_post_process_scan() encountered an unknown"
1925 * Perform post-processing of commands after OpenULINK queue has been executed.
1927 * @param device pointer to struct ulink identifying ULINK driver instance.
1928 * @return on success: ERROR_OK
1929 * @return on failure: ERROR_FAIL
1931 int ulink_post_process_queue(struct ulink *device)
1933 ulink_cmd_t *current;
1934 struct jtag_command *openocd_cmd;
1937 current = device->queue_start;
1939 while (current != NULL) {
1940 openocd_cmd = current->cmd_origin;
1942 /* Check if a corresponding OpenOCD command is stored for this
1943 * OpenULINK command */
1944 if ((current->needs_postprocessing == true) && (openocd_cmd != NULL)) {
1945 switch (openocd_cmd->type) {
1947 ret = ulink_post_process_scan(current);
1949 case JTAG_TLR_RESET:
1954 case JTAG_STABLECLOCKS:
1955 /* Nothing to do for these commands */
1960 LOG_ERROR("BUG: ulink_post_process_queue() encountered unknown JTAG "
1965 if (ret != ERROR_OK) {
1970 current = current->next;
1976 /**************************** JTAG driver functions ***************************/
1979 * Executes the JTAG Command Queue.
1981 * This is done in three stages: First, all OpenOCD commands are processed into
1982 * queued OpenULINK commands. Next, the OpenULINK command queue is sent to the
1983 * ULINK device and data received from the ULINK device is cached. Finally,
1984 * the post-processing function writes back data to the corresponding OpenOCD
1987 * @return on success: ERROR_OK
1988 * @return on failure: ERROR_FAIL
1990 static int ulink_execute_queue(void)
1992 struct jtag_command *cmd = jtag_command_queue;
1996 switch (cmd->type) {
1998 ret = ulink_queue_scan(ulink_handle, cmd);
2000 case JTAG_TLR_RESET:
2001 ret = ulink_queue_tlr_reset(ulink_handle, cmd);
2004 ret = ulink_queue_runtest(ulink_handle, cmd);
2007 ret = ulink_queue_reset(ulink_handle, cmd);
2010 ret = ulink_queue_pathmove(ulink_handle, cmd);
2013 ret = ulink_queue_sleep(ulink_handle, cmd);
2015 case JTAG_STABLECLOCKS:
2016 ret = ulink_queue_stableclocks(ulink_handle, cmd);
2020 LOG_ERROR("BUG: encountered unknown JTAG command type");
2024 if (ret != ERROR_OK) {
2031 if (ulink_handle->commands_in_queue > 0) {
2032 ret = ulink_execute_queued_commands(ulink_handle, USB_TIMEOUT);
2033 if (ret != ERROR_OK) {
2037 ret = ulink_post_process_queue(ulink_handle);
2038 if (ret != ERROR_OK) {
2042 ulink_clear_queue(ulink_handle);
2049 * Set the TCK frequency of the ULINK adapter.
2051 * @param khz desired JTAG TCK frequency.
2052 * @param jtag_speed where to store corresponding adapter-specific speed value.
2053 * @return on success: ERROR_OK
2054 * @return on failure: ERROR_FAIL
2056 static int ulink_khz(int khz, int *jtag_speed)
2061 LOG_ERROR("RCLK not supported");
2065 /* CLOCK_TCK commands are decoupled from others. Therefore, the frequency
2066 * setting can be done independently from all other commands. */
2068 ulink_handle->delay_clock_tck = -1;
2071 ret = ulink_calculate_delay(DELAY_CLOCK_TCK, khz * 1000,
2072 &ulink_handle->delay_clock_tck);
2073 if (ret != ERROR_OK) {
2078 /* SCAN_{IN,OUT,IO} commands invoke CLOCK_TMS commands. Therefore, if the
2079 * requested frequency goes below the maximum frequency for SLOW_CLOCK_TMS
2080 * commands, all SCAN commands MUST also use the variable frequency
2081 * implementation! */
2083 ulink_handle->delay_clock_tms = -1;
2084 ulink_handle->delay_scan_in = -1;
2085 ulink_handle->delay_scan_out = -1;
2086 ulink_handle->delay_scan_io = -1;
2089 ret = ulink_calculate_delay(DELAY_CLOCK_TMS, khz * 1000,
2090 &ulink_handle->delay_clock_tms);
2091 if (ret != ERROR_OK) {
2095 ret = ulink_calculate_delay(DELAY_SCAN_IN, khz * 1000,
2096 &ulink_handle->delay_scan_in);
2097 if (ret != ERROR_OK) {
2101 ret = ulink_calculate_delay(DELAY_SCAN_OUT, khz * 1000,
2102 &ulink_handle->delay_scan_out);
2103 if (ret != ERROR_OK) {
2107 ret = ulink_calculate_delay(DELAY_SCAN_IO, khz * 1000,
2108 &ulink_handle->delay_scan_io);
2109 if (ret != ERROR_OK) {
2114 #ifdef _DEBUG_JTAG_IO_
2115 long f_tck, f_tms, f_scan_in, f_scan_out, f_scan_io;
2117 ulink_calculate_frequency(DELAY_CLOCK_TCK, ulink_handle->delay_clock_tck,
2119 ulink_calculate_frequency(DELAY_CLOCK_TMS, ulink_handle->delay_clock_tms,
2121 ulink_calculate_frequency(DELAY_SCAN_IN, ulink_handle->delay_scan_in,
2123 ulink_calculate_frequency(DELAY_SCAN_OUT, ulink_handle->delay_scan_out,
2125 ulink_calculate_frequency(DELAY_SCAN_IO, ulink_handle->delay_scan_io,
2128 DEBUG_JTAG_IO("ULINK TCK setup: delay_tck = %i (%li Hz),",
2129 ulink_handle->delay_clock_tck, f_tck);
2130 DEBUG_JTAG_IO(" delay_tms = %i (%li Hz),",
2131 ulink_handle->delay_clock_tms, f_tms);
2132 DEBUG_JTAG_IO(" delay_scan_in = %i (%li Hz),",
2133 ulink_handle->delay_scan_in, f_scan_in);
2134 DEBUG_JTAG_IO(" delay_scan_out = %i (%li Hz),",
2135 ulink_handle->delay_scan_out, f_scan_out);
2136 DEBUG_JTAG_IO(" delay_scan_io = %i (%li Hz),",
2137 ulink_handle->delay_scan_io, f_scan_io);
2140 /* Configure the ULINK device with the new delay values */
2141 ret = ulink_append_configure_tck_cmd(ulink_handle,
2142 ulink_handle->delay_scan_in,
2143 ulink_handle->delay_scan_out,
2144 ulink_handle->delay_scan_io,
2145 ulink_handle->delay_clock_tck,
2146 ulink_handle->delay_clock_tms);
2148 if (ret != ERROR_OK) {
2158 * Set the TCK frequency of the ULINK adapter.
2160 * Because of the way the TCK frequency is set up in the OpenULINK firmware,
2161 * there are five different speed settings. To simplify things, the
2162 * adapter-specific speed setting value is identical to the TCK frequency in
2165 * @param speed desired adapter-specific speed value.
2166 * @return on success: ERROR_OK
2167 * @return on failure: ERROR_FAIL
2169 static int ulink_speed(int speed)
2173 return ulink_khz(speed, &dummy);
2177 * Convert adapter-specific speed value to corresponding TCK frequency in kHz.
2179 * Because of the way the TCK frequency is set up in the OpenULINK firmware,
2180 * there are five different speed settings. To simplify things, the
2181 * adapter-specific speed setting value is identical to the TCK frequency in
2184 * @param speed adapter-specific speed value.
2185 * @param khz where to store corresponding TCK frequency in kHz.
2186 * @return on success: ERROR_OK
2187 * @return on failure: ERROR_FAIL
2189 static int ulink_speed_div(int speed, int *khz)
2197 * Initiates the firmware download to the ULINK adapter and prepares
2200 * @return on success: ERROR_OK
2201 * @return on failure: ERROR_FAIL
2203 static int ulink_init(void)
2206 char str_manufacturer[20];
2207 bool download_firmware = false;
2209 uint8_t input_signals, output_signals;
2211 ulink_handle = calloc(1, sizeof(struct ulink));
2212 if (ulink_handle == NULL) {
2218 ret = ulink_usb_open(&ulink_handle);
2219 if (ret != ERROR_OK) {
2220 LOG_ERROR("Could not open ULINK device");
2224 /* Get String Descriptor to determine if firmware needs to be loaded */
2225 ret = usb_get_string_simple(ulink_handle->usb_handle, 1, str_manufacturer, 20);
2227 /* Could not get descriptor -> Unconfigured or original Keil firmware */
2228 download_firmware = true;
2231 /* We got a String Descriptor, check if it is the correct one */
2232 if (strncmp(str_manufacturer, "OpenULINK", 9) != 0) {
2233 download_firmware = true;
2237 if (download_firmware == true) {
2238 LOG_INFO("Loading OpenULINK firmware. This is reversible by power-cycling"
2240 ret = ulink_load_firmware_and_renumerate(&ulink_handle,
2241 ULINK_FIRMWARE_FILE, ULINK_RENUMERATION_DELAY);
2242 if (ret != ERROR_OK) {
2243 LOG_ERROR("Could not download firmware and re-numerate ULINK");
2248 LOG_INFO("ULINK device is already running OpenULINK firmware");
2251 /* Initialize OpenULINK command queue */
2252 ulink_clear_queue(ulink_handle);
2254 /* Issue one test command with short timeout */
2255 ret = ulink_append_test_cmd(ulink_handle);
2256 if (ret != ERROR_OK) {
2260 ret = ulink_execute_queued_commands(ulink_handle, 200);
2261 if (ret != ERROR_OK) {
2262 /* Sending test command failed. The ULINK device may be forever waiting for
2263 * the host to fetch an USB Bulk IN packet (e. g. OpenOCD crashed or was
2264 * shut down by the user via Ctrl-C. Try to retrieve this Bulk IN packet. */
2265 dummy = calloc(64, sizeof(uint8_t));
2267 ret = usb_bulk_read(ulink_handle->usb_handle, (2 | USB_ENDPOINT_IN),
2268 (char *)dummy, 64, 200);
2273 /* Bulk IN transfer failed -> unrecoverable error condition */
2274 LOG_ERROR("Cannot communicate with ULINK device. Disconnect ULINK from "
2275 "the USB port and re-connect, then re-run OpenOCD");
2278 #ifdef _DEBUG_USB_COMMS_
2280 /* Successfully received Bulk IN packet -> continue */
2281 LOG_INFO("Recovered from lost Bulk IN packet");
2285 ulink_clear_queue(ulink_handle);
2287 ulink_append_get_signals_cmd(ulink_handle);
2288 ulink_execute_queued_commands(ulink_handle, 200);
2290 /* Post-process the single CMD_GET_SIGNALS command */
2291 input_signals = ulink_handle->queue_start->payload_in[0];
2292 output_signals = ulink_handle->queue_start->payload_in[1];
2294 ulink_print_signal_states(input_signals, output_signals);
2296 ulink_clear_queue(ulink_handle);
2302 * Closes the USB handle for the ULINK device.
2304 * @return on success: ERROR_OK
2305 * @return on failure: ERROR_FAIL
2307 static int ulink_quit(void)
2311 ret = ulink_usb_close(&ulink_handle);
2318 * Set a custom path to ULINK firmware image and force downloading to ULINK.
2320 COMMAND_HANDLER(ulink_download_firmware_handler)
2324 if (CMD_ARGC != 1) {
2325 LOG_ERROR("Need exactly one argument to ulink_download_firmware");
2329 LOG_INFO("Downloading ULINK firmware image %s", CMD_ARGV[0]);
2331 /* Download firmware image in CMD_ARGV[0] */
2332 ret = ulink_load_firmware_and_renumerate(&ulink_handle, (char *)CMD_ARGV[0],
2333 ULINK_RENUMERATION_DELAY);
2338 /*************************** Command Registration **************************/
2340 static const struct command_registration ulink_command_handlers[] = {
2342 .name = "ulink_download_firmware",
2343 .handler = &ulink_download_firmware_handler,
2344 .mode = COMMAND_EXEC,
2345 .help = "download firmware image to ULINK device",
2346 .usage = "path/to/ulink_firmware.hex",
2348 COMMAND_REGISTRATION_DONE,
2351 struct jtag_interface ulink_interface = {
2354 .commands = ulink_command_handlers,
2355 .transports = jtag_only,
2357 .execute_queue = ulink_execute_queue,
2359 .speed = ulink_speed,
2360 .speed_div = ulink_speed_div,