OpenOCD
ulink.c File Reference
Include dependency graph for ulink.c:

Go to the source code of this file.

Data Structures

struct  ulink
 Describes one driver instance. More...
 
struct  ulink_cmd
 OpenULINK command (OpenULINK command queue element). More...
 

Macros

#define CPU_RESET   0x01
 Value to write into CPUCS to put EZ-USB into reset. More...
 
#define CPU_START   0x00
 Value to write into CPUCS to put EZ-USB out of reset. More...
 
#define CPUCS_REG   0x7F92
 Address of EZ-USB CPU Control & Status register. More...
 
#define FIRMWARE_ADDR   0x0000
 Base address of firmware in EZ-USB code space. More...
 
#define REQUEST_FIRMWARE_LOAD   0xA0
 USB Control EP0 bRequest: "Firmware Load". More...
 
#define SECTION_BUFFERSIZE   8192
 Maximum size of a single firmware section. More...
 
#define SPLIT_SCAN_THRESHOLD   10
 Tuning of OpenOCD SCAN commands split into multiple OpenULINK commands. More...
 
#define ULINK_FIRMWARE_FILE   PKGDATADIR "/OpenULINK/ulink_firmware.hex"
 Default location of OpenULINK firmware image. More...
 
#define ULINK_PID   0x2710
 USB Product ID of ULINK device in unconfigured state (no firmware loaded yet) or with OpenULINK firmware. More...
 
#define ULINK_RENUMERATION_DELAY   1500000
 Delay (in microseconds) to wait while EZ-USB performs ReNumeration. More...
 
#define ULINK_VID   0xC251
 USB Vendor ID of ULINK device in unconfigured state (no firmware loaded yet) or with OpenULINK firmware. More...
 
#define USB_INTERFACE   0
 USB interface number. More...
 

Enumerations

enum  ulink_delay_type {
  DELAY_CLOCK_TCK , DELAY_CLOCK_TMS , DELAY_SCAN_IN , DELAY_SCAN_OUT ,
  DELAY_SCAN_IO
}
 
enum  ulink_payload_direction { PAYLOAD_DIRECTION_OUT , PAYLOAD_DIRECTION_IN }
 
enum  ulink_type { ULINK_1 , ULINK_2 , ULINK_PRO , ULINK_ME }
 ULINK hardware type. More...
 

Functions

static int __attribute__ ((unused))
 Opens the ULINK device. More...
 
 COMMAND_HANDLER (ulink_download_firmware_handler)
 Set a custom path to ULINK firmware image and force downloading to ULINK. More...
 
static int ulink_allocate_payload (struct ulink_cmd *ulink_cmd, int size, enum ulink_payload_direction direction)
 Allocate and initialize space in memory for OpenULINK command payload. More...
 
static int ulink_append_clock_tck_cmd (struct ulink *device, uint16_t count)
 Generate a defined amount of TCK clock cycles. More...
 
static int ulink_append_clock_tms_cmd (struct ulink *device, uint8_t count, uint8_t sequence)
 Perform TAP state transitions. More...
 
static int ulink_append_configure_tck_cmd (struct ulink *device, int delay_scan_in, int delay_scan_out, int delay_scan_io, int delay_tck, int delay_tms)
 Set TCK delay counters. More...
 
static int ulink_append_get_signals_cmd (struct ulink *device)
 Read JTAG signals. More...
 
static int ulink_append_led_cmd (struct ulink *device, uint8_t led_state)
 Turn on/off ULINK LEDs. More...
 
static int ulink_append_queue (struct ulink *device, struct ulink_cmd *ulink_cmd)
 Add a command to the OpenULINK command queue. More...
 
static int ulink_append_scan_cmd (struct ulink *device, enum scan_type scan_type, int scan_size_bits, uint8_t *tdi, uint8_t *tdo_start, uint8_t *tdo, uint8_t tms_count_start, uint8_t tms_sequence_start, uint8_t tms_count_end, uint8_t tms_sequence_end, struct jtag_command *origin, bool postprocess)
 
static int ulink_append_scan_cmd (struct ulink *device, enum scan_type scan_type, int scan_size_bits, uint8_t *tdi, uint8_t *tdo_start, uint8_t *tdo, uint8_t tms_count_start, uint8_t tms_sequence_start, uint8_t tms_count_end, uint8_t tms_sequence_end, struct jtag_command *origin, bool postprocess)
 Perform JTAG scan. More...
 
static int ulink_append_set_signals_cmd (struct ulink *device, uint8_t low, uint8_t high)
 Arbitrarily set JTAG output signals. More...
 
static int ulink_append_sleep_cmd (struct ulink *device, uint32_t us)
 Sleep for a pre-defined number of microseconds. More...
 
static int ulink_append_test_cmd (struct ulink *device)
 Test command. More...
 
static int ulink_calculate_delay (enum ulink_delay_type type, long f, int *delay)
 Calculate delay values for a given TCK frequency. More...
 
static long ulink_calculate_frequency (enum ulink_delay_type type, int delay)
 Calculate frequency for a given delay value. More...
 
static void ulink_clear_queue (struct ulink *device)
 Clear the OpenULINK command queue. More...
 
static const char * ulink_cmd_id_string (uint8_t id)
 Convert an OpenULINK command ID (id) to a human-readable string. More...
 
static int ulink_cpu_reset (struct ulink *device, unsigned char reset_bit)
 Writes '0' or '1' to the CPUCS register, putting the EZ-USB CPU into reset or out of reset. More...
 
static int ulink_execute_queue (struct jtag_command *cmd_queue)
 Executes the JTAG Command Queue. More...
 
static int ulink_execute_queued_commands (struct ulink *device, int timeout)
 Sends all queued OpenULINK commands to the ULINK for execution. More...
 
static int ulink_get_queue_size (struct ulink *device, enum ulink_payload_direction direction)
 Get the current number of bytes in the queue, including command IDs. More...
 
static int ulink_init (void)
 Initiates the firmware download to the ULINK adapter and prepares the USB handle. More...
 
static int ulink_khz (int khz, int *jtag_speed)
 Set the TCK frequency of the ULINK adapter. More...
 
static int ulink_load_firmware (struct ulink *device, const char *filename)
 Downloads a firmware image to the ULINK's EZ-USB microcontroller over the USB bus. More...
 
static int ulink_load_firmware_and_renumerate (struct ulink **device, const char *filename, uint32_t delay)
 Puts the ULINK's EZ-USB microcontroller into reset state, downloads the firmware image, resumes the microcontroller and re-enumerates USB devices. More...
 
static int ulink_post_process_queue (struct ulink *device)
 Perform post-processing of commands after OpenULINK queue has been executed. More...
 
static int ulink_post_process_scan (struct ulink_cmd *ulink_cmd)
 Post-process JTAG_SCAN command. More...
 
static void ulink_print_command (struct ulink_cmd *ulink_cmd)
 Print one OpenULINK command to stdout. More...
 
static void ulink_print_queue (struct ulink *device)
 Print the OpenULINK command queue to stdout. More...
 
static void ulink_print_signal_states (uint8_t input_signals, uint8_t output_signals)
 Print state of interesting signals via LOG_INFO(). More...
 
static int ulink_queue_pathmove (struct ulink *device, struct jtag_command *cmd)
 Move to one TAP state or several states in succession. More...
 
static int ulink_queue_reset (struct ulink *device, struct jtag_command *cmd)
 Execute a JTAG_RESET command. More...
 
static int ulink_queue_runtest (struct ulink *device, struct jtag_command *cmd)
 Run Test. More...
 
static int ulink_queue_scan (struct ulink *device, struct jtag_command *cmd)
 Perform a scan operation on a JTAG register. More...
 
static int ulink_queue_sleep (struct ulink *device, struct jtag_command *cmd)
 Sleep for a specific amount of time. More...
 
static int ulink_queue_stableclocks (struct ulink *device, struct jtag_command *cmd)
 Generate TCK cycles while remaining in a stable state. More...
 
static int ulink_queue_statemove (struct ulink *device)
 Move from the current TAP state to the current TAP end state. More...
 
static int ulink_queue_tlr_reset (struct ulink *device, struct jtag_command *cmd)
 Move the TAP into the Test Logic Reset state. More...
 
static int ulink_quit (void)
 Closes the USB handle for the ULINK device. More...
 
static void ulink_set_end_state (tap_state_t endstate)
 Sets the end state follower (see interface.h) if endstate is a stable state. More...
 
static int ulink_speed (int speed)
 Set the TCK frequency of the ULINK adapter. More...
 
static int ulink_speed_div (int speed, int *khz)
 Convert adapter-specific speed value to corresponding TCK frequency in kHz. More...
 
static int ulink_usb_close (struct ulink **device)
 Releases the ULINK interface and closes the USB device handle. More...
 
static int ulink_usb_open (struct ulink **device)
 
static int ulink_write_firmware_section (struct ulink *device, struct image *firmware_image, int section_index)
 Send one contiguous firmware section to the ULINK's EZ-USB microcontroller over the USB bus. More...
 

Variables

struct adapter_driver ulink_adapter_driver
 
static const struct command_registration ulink_command_handlers []
 
static struct jtag_interface ulink_interface
 
static const struct command_registration ulink_subcommand_handlers []
 

Macro Definition Documentation

◆ CPU_RESET

#define CPU_RESET   0x01

Value to write into CPUCS to put EZ-USB into reset.

Definition at line 37 of file ulink.c.

◆ CPU_START

#define CPU_START   0x00

Value to write into CPUCS to put EZ-USB out of reset.

Definition at line 40 of file ulink.c.

◆ CPUCS_REG

#define CPUCS_REG   0x7F92

Address of EZ-USB CPU Control & Status register.

This register can be written by issuing a Control EP0 vendor request.

Definition at line 31 of file ulink.c.

◆ FIRMWARE_ADDR

#define FIRMWARE_ADDR   0x0000

Base address of firmware in EZ-USB code space.

Definition at line 43 of file ulink.c.

◆ REQUEST_FIRMWARE_LOAD

#define REQUEST_FIRMWARE_LOAD   0xA0

USB Control EP0 bRequest: "Firmware Load".

Definition at line 34 of file ulink.c.

◆ SECTION_BUFFERSIZE

#define SECTION_BUFFERSIZE   8192

Maximum size of a single firmware section.

Entire EZ-USB code space = 8kB

Definition at line 55 of file ulink.c.

◆ SPLIT_SCAN_THRESHOLD

#define SPLIT_SCAN_THRESHOLD   10

Tuning of OpenOCD SCAN commands split into multiple OpenULINK commands.

Definition at line 58 of file ulink.c.

◆ ULINK_FIRMWARE_FILE

#define ULINK_FIRMWARE_FILE   PKGDATADIR "/OpenULINK/ulink_firmware.hex"

Default location of OpenULINK firmware image.

Definition at line 52 of file ulink.c.

◆ ULINK_PID

#define ULINK_PID   0x2710

USB Product ID of ULINK device in unconfigured state (no firmware loaded yet) or with OpenULINK firmware.

Definition at line 27 of file ulink.c.

◆ ULINK_RENUMERATION_DELAY

#define ULINK_RENUMERATION_DELAY   1500000

Delay (in microseconds) to wait while EZ-USB performs ReNumeration.

Definition at line 49 of file ulink.c.

◆ ULINK_VID

#define ULINK_VID   0xC251

USB Vendor ID of ULINK device in unconfigured state (no firmware loaded yet) or with OpenULINK firmware.

Definition at line 23 of file ulink.c.

◆ USB_INTERFACE

#define USB_INTERFACE   0

USB interface number.

Definition at line 46 of file ulink.c.

Enumeration Type Documentation

◆ ulink_delay_type

Enumerator
DELAY_CLOCK_TCK 
DELAY_CLOCK_TMS 
DELAY_SCAN_IN 
DELAY_SCAN_OUT 
DELAY_SCAN_IO 

Definition at line 81 of file ulink.c.

◆ ulink_payload_direction

Enumerator
PAYLOAD_DIRECTION_OUT 
PAYLOAD_DIRECTION_IN 

Definition at line 76 of file ulink.c.

◆ ulink_type

enum ulink_type

ULINK hardware type.

Enumerator
ULINK_1 

Original ULINK adapter, based on Cypress EZ-USB (AN2131): Full JTAG support, no SWD support.

ULINK_2 

Newer ULINK adapter, based on NXP LPC2148.

Currently unsupported.

ULINK_PRO 

Newer ULINK adapter, based on EZ-USB FX2 + FPGA.

Currently unsupported.

ULINK_ME 

Newer ULINK adapter, possibly based on ULINK 2.

Currently unsupported.

Definition at line 61 of file ulink.c.

Function Documentation

◆ __attribute__()

static int __attribute__ ( (unused)  )
static

Opens the ULINK device.

Currently, only the original ULINK is supported

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 208 of file ulink.c.

◆ COMMAND_HANDLER()

COMMAND_HANDLER ( ulink_download_firmware_handler  )

Set a custom path to ULINK firmware image and force downloading to ULINK.

Definition at line 2226 of file ulink.c.

References CMD_ARGC, CMD_ARGV, ERROR_COMMAND_SYNTAX_ERROR, LOG_INFO, ulink_load_firmware_and_renumerate(), and ULINK_RENUMERATION_DELAY.

◆ ulink_allocate_payload()

static int ulink_allocate_payload ( struct ulink_cmd ulink_cmd,
int  size,
enum ulink_payload_direction  direction 
)
static

Allocate and initialize space in memory for OpenULINK command payload.

Parameters
ulink_cmdpointer to command whose payload should be allocated.
sizethe amount of memory to allocate (bytes).
directionwhich payload to allocate.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 513 of file ulink.c.

References direction, ERROR_FAIL, ERROR_OK, ulink_cmd::free_payload_in_start, LOG_ERROR, PAYLOAD_DIRECTION_IN, PAYLOAD_DIRECTION_OUT, ulink_cmd::payload_in, ulink_cmd::payload_in_size, ulink_cmd::payload_in_start, ulink_cmd::payload_out, ulink_cmd::payload_out_size, and size.

Referenced by ulink_append_clock_tck_cmd(), ulink_append_clock_tms_cmd(), ulink_append_configure_tck_cmd(), ulink_append_get_signals_cmd(), ulink_append_led_cmd(), ulink_append_scan_cmd(), ulink_append_set_signals_cmd(), ulink_append_sleep_cmd(), and ulink_append_test_cmd().

◆ ulink_append_clock_tck_cmd()

static int ulink_append_clock_tck_cmd ( struct ulink device,
uint16_t  count 
)
static

Generate a defined amount of TCK clock cycles.

All other JTAG signals are left unchanged.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
countthe number of TCK clock cycles to generate.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 993 of file ulink.c.

References cmd, CMD_CLOCK_TCK, CMD_SLOW_CLOCK_TCK, count, device, ERROR_FAIL, ERROR_OK, PAYLOAD_DIRECTION_OUT, ulink_allocate_payload(), and ulink_append_queue().

Referenced by ulink_queue_runtest(), and ulink_queue_stableclocks().

◆ ulink_append_clock_tms_cmd()

static int ulink_append_clock_tms_cmd ( struct ulink device,
uint8_t  count,
uint8_t  sequence 
)
static

Perform TAP state transitions.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
countdefines the number of TCK clock cycles generated (up to 8).
sequencedefines the TMS pin levels for each state transition. The Least-Significant Bit is read first.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 956 of file ulink.c.

References cmd, CMD_CLOCK_TMS, CMD_SLOW_CLOCK_TMS, count, device, ERROR_FAIL, ERROR_OK, PAYLOAD_DIRECTION_OUT, ulink_allocate_payload(), and ulink_append_queue().

Referenced by ulink_queue_pathmove(), ulink_queue_statemove(), and ulink_queue_tlr_reset().

◆ ulink_append_configure_tck_cmd()

static int ulink_append_configure_tck_cmd ( struct ulink device,
int  delay_scan_in,
int  delay_scan_out,
int  delay_scan_io,
int  delay_tck,
int  delay_tms 
)
static

Set TCK delay counters.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
delay_scan_indelay count top value in jtag_slow_scan_in() function.
delay_scan_outdelay count top value in jtag_slow_scan_out() function.
delay_scan_iodelay count top value in jtag_slow_scan_io() function.
delay_tckdelay count top value in jtag_clock_tck() function.
delay_tmsdelay count top value in jtag_slow_clock_tms() function.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1134 of file ulink.c.

References cmd, CMD_CONFIGURE_TCK_FREQ, delay_scan_in, delay_scan_io, delay_scan_out, delay_tck, delay_tms, device, ERROR_FAIL, ERROR_OK, PAYLOAD_DIRECTION_OUT, ulink_allocate_payload(), and ulink_append_queue().

Referenced by ulink_khz().

◆ ulink_append_get_signals_cmd()

static int ulink_append_get_signals_cmd ( struct ulink device)
static

Read JTAG signals.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1026 of file ulink.c.

References cmd, CMD_GET_SIGNALS, device, ERROR_FAIL, ERROR_OK, PAYLOAD_DIRECTION_IN, ulink_allocate_payload(), and ulink_append_queue().

Referenced by ulink_init().

◆ ulink_append_led_cmd()

static int ulink_append_led_cmd ( struct ulink device,
uint8_t  led_state 
)
static

Turn on/off ULINK LEDs.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
led_statewhich LED(s) to turn on or off. The following bits influence the LEDS:
  • Bit 0: Turn COM LED on
  • Bit 1: Turn RUN LED on
  • Bit 2: Turn COM LED off
  • Bit 3: Turn RUN LED off If both the on-bit and the off-bit for the same LED is set, the LED is turned off.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1196 of file ulink.c.

References cmd, CMD_SET_LEDS, device, ERROR_FAIL, ERROR_OK, PAYLOAD_DIRECTION_OUT, ulink_allocate_payload(), and ulink_append_queue().

◆ ulink_append_queue()

static int ulink_append_queue ( struct ulink device,
struct ulink_cmd ulink_cmd 
)
static

Add a command to the OpenULINK command queue.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
ulink_cmdpointer to command that shall be appended to the OpenULINK command queue.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 636 of file ulink.c.

References device, ERROR_OK, LIBUSB_TIMEOUT_MS, PAYLOAD_DIRECTION_IN, PAYLOAD_DIRECTION_OUT, ulink_cmd::payload_in_size, ulink_cmd::payload_out_size, ulink_clear_queue(), ulink_execute_queued_commands(), ulink_get_queue_size(), and ulink_post_process_queue().

Referenced by ulink_append_clock_tck_cmd(), ulink_append_clock_tms_cmd(), ulink_append_configure_tck_cmd(), ulink_append_get_signals_cmd(), ulink_append_led_cmd(), ulink_append_scan_cmd(), ulink_append_set_signals_cmd(), ulink_append_sleep_cmd(), and ulink_append_test_cmd().

◆ ulink_append_scan_cmd() [1/2]

static int ulink_append_scan_cmd ( struct ulink device,
enum scan_type  scan_type,
int  scan_size_bits,
uint8_t *  tdi,
uint8_t *  tdo_start,
uint8_t *  tdo,
uint8_t  tms_count_start,
uint8_t  tms_sequence_start,
uint8_t  tms_count_end,
uint8_t  tms_sequence_end,
struct jtag_command origin,
bool  postprocess 
)
static

Referenced by ulink_queue_scan().

◆ ulink_append_scan_cmd() [2/2]

static int ulink_append_scan_cmd ( struct ulink device,
enum scan_type  scan_type,
int  scan_size_bits,
uint8_t *  tdi,
uint8_t *  tdo_start,
uint8_t *  tdo,
uint8_t  tms_count_start,
uint8_t  tms_sequence_start,
uint8_t  tms_count_end,
uint8_t  tms_sequence_end,
struct jtag_command origin,
bool  postprocess 
)
static

Perform JTAG scan.

Creates and appends a JTAG scan command to the OpenULINK command queue. A JTAG scan consists of three steps:

  • Move to the desired SHIFT state, depending on scan type (IR/DR scan).
  • Shift TDI data into the JTAG chain, optionally reading the TDO pin.
  • Move to the desired end state.
Parameters
devicepointer to struct ulink identifying ULINK driver instance.
scan_typethe type of the scan (IN, OUT, IO (bidirectional)).
scan_size_bitsnumber of bits to shift into the JTAG chain.
tdipointer to array containing TDI data.
tdo_startpointer to first element of array where TDO data shall be stored. See ulink_cmd for details.
tdopointer to array where TDO data shall be stored
tms_count_startnumber of TMS state transitions to perform BEFORE shifting data into the JTAG chain.
tms_sequence_startsequence of TMS state transitions that will be performed BEFORE shifting data into the JTAG chain.
tms_count_endnumber of TMS state transitions to perform AFTER shifting data into the JTAG chain.
tms_sequence_endsequence of TMS state transitions that will be performed AFTER shifting data into the JTAG chain.
originpointer to OpenOCD command that generated this scan command.
postprocesswhether this command needs to be post-processed after execution.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 855 of file ulink.c.

References cmd, CMD_SCAN_IN, CMD_SCAN_IO, CMD_SCAN_OUT, CMD_SLOW_SCAN_IN, CMD_SLOW_SCAN_IO, CMD_SLOW_SCAN_OUT, device, DIV_ROUND_UP, ERROR_FAIL, ERROR_OK, LOG_ERROR, PAYLOAD_DIRECTION_OUT, SCAN_IN, SCAN_IO, SCAN_OUT, ulink_allocate_payload(), and ulink_append_queue().

◆ ulink_append_set_signals_cmd()

static int ulink_append_set_signals_cmd ( struct ulink device,
uint8_t  low,
uint8_t  high 
)
static

Arbitrarily set JTAG output signals.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
lowdefines which signals will be de-asserted. Each bit corresponds to a JTAG signal:
  • SIGNAL_TDI
  • SIGNAL_TMS
  • SIGNAL_TCK
  • SIGNAL_TRST
  • SIGNAL_BRKIN
  • SIGNAL_RESET
  • SIGNAL_OCDSE
highdefines which signals will be asserted.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1065 of file ulink.c.

References cmd, CMD_SET_SIGNALS, device, ERROR_FAIL, ERROR_OK, low, PAYLOAD_DIRECTION_OUT, ulink_allocate_payload(), and ulink_append_queue().

Referenced by ulink_queue_reset(), and ulink_queue_stableclocks().

◆ ulink_append_sleep_cmd()

static int ulink_append_sleep_cmd ( struct ulink device,
uint32_t  us 
)
static

Sleep for a pre-defined number of microseconds.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
usthe number microseconds to sleep.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1098 of file ulink.c.

References cmd, CMD_SLEEP_US, device, ERROR_FAIL, ERROR_OK, PAYLOAD_DIRECTION_OUT, ulink_allocate_payload(), and ulink_append_queue().

Referenced by ulink_queue_sleep().

◆ ulink_append_test_cmd()

static int ulink_append_test_cmd ( struct ulink device)
static

Test command.

Used to check if the ULINK device is ready to accept new commands.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1226 of file ulink.c.

References cmd, CMD_TEST, device, ERROR_FAIL, ERROR_OK, PAYLOAD_DIRECTION_OUT, ulink_allocate_payload(), and ulink_append_queue().

Referenced by ulink_init().

◆ ulink_calculate_delay()

static int ulink_calculate_delay ( enum ulink_delay_type  type,
long  f,
int *  delay 
)
static

Calculate delay values for a given TCK frequency.

The OpenULINK firmware uses five different speed values for different commands. These speed values are calculated in these functions.

The five different commands which support variable TCK frequency are implemented twice in the firmware:

  1. Maximum possible frequency without any artificial delay
  2. Variable frequency with artificial linear delay loop

To set the ULINK to maximum frequency, it is only necessary to use the corresponding command IDs. To set the ULINK to a lower frequency, the delay loop top values have to be calculated first. Then, a CMD_CONFIGURE_TCK_FREQ command needs to be sent to the ULINK device.

The delay values are described by linear equations: t = k * x + d (t = period, k = constant, x = delay value, d = constant)

Thus, the delay can be calculated as in the following equation: x = (t - d) / k

The constants in these equations have been determined and validated by measuring the frequency resulting from different delay values.

Parameters
typefor which command to calculate the delay value.
fTCK frequency for which to calculate the delay value in Hz.
delaywhere to store resulting delay value.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1282 of file ulink.c.

References DELAY_CLOCK_TCK, DELAY_CLOCK_TMS, DELAY_SCAN_IN, DELAY_SCAN_IO, DELAY_SCAN_OUT, ERROR_FAIL, ERROR_OK, and type.

Referenced by ulink_khz().

◆ ulink_calculate_frequency()

static long ulink_calculate_frequency ( enum ulink_delay_type  type,
int  delay 
)
static

Calculate frequency for a given delay value.

Similar to the ulink_calculate_delay function, this function calculates the TCK frequency for a given delay value by using linear equations of the form: t = k * x + d (t = period, k = constant, x = delay value, d = constant)

Parameters
typefor which command to calculate the delay value.
delaydelay value for which to calculate the resulting TCK frequency.
Returns
the resulting TCK frequency

Definition at line 1342 of file ulink.c.

References DELAY_CLOCK_TCK, DELAY_CLOCK_TMS, DELAY_SCAN_IN, DELAY_SCAN_IO, DELAY_SCAN_OUT, and type.

Referenced by ulink_khz().

◆ ulink_clear_queue()

static void ulink_clear_queue ( struct ulink device)
static

Clear the OpenULINK command queue.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.

Definition at line 594 of file ulink.c.

References device, ulink_cmd::free_payload_in_start, ulink_cmd::next, NULL, ulink_cmd::payload_in, ulink_cmd::payload_in_start, and ulink_cmd::payload_out.

Referenced by ulink_append_queue(), ulink_execute_queue(), and ulink_init().

◆ ulink_cmd_id_string()

static const char* ulink_cmd_id_string ( uint8_t  id)
static

Convert an OpenULINK command ID (id) to a human-readable string.

Parameters
idthe OpenULINK command ID.
Returns
the corresponding human-readable string.

Definition at line 750 of file ulink.c.

References CMD_CLOCK_TCK, CMD_CLOCK_TMS, CMD_CONFIGURE_TCK_FREQ, CMD_GET_SIGNALS, CMD_SCAN_IN, CMD_SCAN_IO, CMD_SCAN_OUT, CMD_SET_LEDS, CMD_SET_SIGNALS, CMD_SLEEP_MS, CMD_SLEEP_US, CMD_SLOW_CLOCK_TCK, CMD_SLOW_CLOCK_TMS, CMD_SLOW_SCAN_IN, CMD_SLOW_SCAN_IO, CMD_SLOW_SCAN_OUT, and CMD_TEST.

Referenced by ulink_print_command().

◆ ulink_cpu_reset()

static int ulink_cpu_reset ( struct ulink device,
unsigned char  reset_bit 
)
static

Writes '0' or '1' to the CPUCS register, putting the EZ-USB CPU into reset or out of reset.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
reset_bit0 to put CPU into reset, 1 to put CPU out of reset.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 318 of file ulink.c.

References CPUCS_REG, device, ERROR_FAIL, ERROR_OK, LIBUSB_TIMEOUT_MS, and REQUEST_FIRMWARE_LOAD.

Referenced by ulink_load_firmware().

◆ ulink_execute_queue()

static int ulink_execute_queue ( struct jtag_command cmd_queue)
static

Executes the JTAG Command Queue.

This is done in three stages: First, all OpenOCD commands are processed into queued OpenULINK commands. Next, the OpenULINK command queue is sent to the ULINK device and data received from the ULINK device is cached. Finally, the post-processing function writes back data to the corresponding OpenOCD commands.

Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1908 of file ulink.c.

References cmd, ulink::commands_in_queue, ERROR_FAIL, ERROR_OK, JTAG_PATHMOVE, JTAG_RESET, JTAG_RUNTEST, JTAG_SCAN, JTAG_SLEEP, JTAG_STABLECLOCKS, JTAG_TLR_RESET, LIBUSB_TIMEOUT_MS, LOG_ERROR, ulink_clear_queue(), ulink_execute_queued_commands(), ulink_post_process_queue(), ulink_queue_pathmove(), ulink_queue_reset(), ulink_queue_runtest(), ulink_queue_scan(), ulink_queue_sleep(), ulink_queue_stableclocks(), and ulink_queue_tlr_reset().

◆ ulink_execute_queued_commands()

static int ulink_execute_queued_commands ( struct ulink device,
int  timeout 
)
static

Sends all queued OpenULINK commands to the ULINK for execution.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
timeout
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 688 of file ulink.c.

References buffer, device, ERROR_FAIL, ERROR_OK, ulink_cmd::id, LOG_LEVEL_IS, LOG_LVL_DEBUG_IO, ulink_cmd::next, ulink_cmd::payload_in, ulink_cmd::payload_in_size, ulink_cmd::payload_out, ulink_cmd::payload_out_size, and ulink_print_queue().

Referenced by ulink_append_queue(), ulink_execute_queue(), and ulink_init().

◆ ulink_get_queue_size()

static int ulink_get_queue_size ( struct ulink device,
enum ulink_payload_direction  direction 
)
static

Get the current number of bytes in the queue, including command IDs.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
directionthe transfer direction for which to get byte count.
Returns
the number of bytes currently stored in the queue for the specified direction.

Definition at line 567 of file ulink.c.

References device, direction, ulink_cmd::next, PAYLOAD_DIRECTION_IN, PAYLOAD_DIRECTION_OUT, ulink_cmd::payload_in_size, and ulink_cmd::payload_out_size.

Referenced by ulink_append_queue().

◆ ulink_init()

◆ ulink_khz()

static int ulink_khz ( int  khz,
int *  jtag_speed 
)
static

Set the TCK frequency of the ULINK adapter.

Parameters
khzdesired JTAG TCK frequency.
jtag_speedwhere to store corresponding adapter-specific speed value.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1971 of file ulink.c.

References DELAY_CLOCK_TCK, ulink::delay_clock_tck, DELAY_CLOCK_TMS, ulink::delay_clock_tms, DELAY_SCAN_IN, ulink::delay_scan_in, DELAY_SCAN_IO, ulink::delay_scan_io, DELAY_SCAN_OUT, ulink::delay_scan_out, ERROR_FAIL, ERROR_OK, LOG_DEBUG_IO, LOG_ERROR, ulink_append_configure_tck_cmd(), ulink_calculate_delay(), and ulink_calculate_frequency().

Referenced by ulink_speed().

◆ ulink_load_firmware()

static int ulink_load_firmware ( struct ulink device,
const char *  filename 
)
static

Downloads a firmware image to the ULINK's EZ-USB microcontroller over the USB bus.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
filenamean absolute or relative path to the Intel HEX file containing the firmware image.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 381 of file ulink.c.

References image::base_address, image::base_address_set, CPU_RESET, CPU_START, device, ERROR_OK, image_close(), image_open(), LOG_ERROR, image::num_sections, ulink_cpu_reset(), and ulink_write_firmware_section().

Referenced by ulink_load_firmware_and_renumerate().

◆ ulink_load_firmware_and_renumerate()

static int ulink_load_firmware_and_renumerate ( struct ulink **  device,
const char *  filename,
uint32_t  delay 
)
static

Puts the ULINK's EZ-USB microcontroller into reset state, downloads the firmware image, resumes the microcontroller and re-enumerates USB devices.

Parameters
devicepointer to struct ulink identifying ULINK driver instance. The usb_handle member will be modified during re-enumeration.
filenamepath to the Intel HEX file containing the firmware image.
delaythe delay to wait for the device to re-enumerate.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 345 of file ulink.c.

References device, ERROR_OK, ulink_load_firmware(), ulink_usb_close(), and ulink_usb_open().

Referenced by COMMAND_HANDLER(), and ulink_init().

◆ ulink_post_process_queue()

static int ulink_post_process_queue ( struct ulink device)
static

Perform post-processing of commands after OpenULINK queue has been executed.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1850 of file ulink.c.

References ulink_cmd::cmd_origin, device, ERROR_FAIL, ERROR_OK, JTAG_PATHMOVE, JTAG_RESET, JTAG_RUNTEST, JTAG_SCAN, JTAG_SLEEP, JTAG_STABLECLOCKS, JTAG_TLR_RESET, LOG_ERROR, ulink_cmd::needs_postprocessing, ulink_cmd::next, jtag_command::type, and ulink_post_process_scan().

Referenced by ulink_append_queue(), and ulink_execute_queue().

◆ ulink_post_process_scan()

static int ulink_post_process_scan ( struct ulink_cmd ulink_cmd)
static

Post-process JTAG_SCAN command.

Parameters
ulink_cmdpointer to OpenULINK command that shall be processed.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1819 of file ulink.c.

References cmd, ulink_cmd::cmd_origin, ERROR_FAIL, ERROR_OK, jtag_read_buffer(), jtag_scan_type(), LOG_ERROR, ulink_cmd::payload_in_start, SCAN_IN, SCAN_IO, and SCAN_OUT.

Referenced by ulink_post_process_queue().

◆ ulink_print_command()

static void ulink_print_command ( struct ulink_cmd ulink_cmd)
static

Print one OpenULINK command to stdout.

Parameters
ulink_cmdpointer to OpenULINK command.

Definition at line 797 of file ulink.c.

References ulink_cmd::id, ulink_cmd::payload_in_size, ulink_cmd::payload_out, ulink_cmd::payload_out_size, and ulink_cmd_id_string().

Referenced by ulink_print_queue().

◆ ulink_print_queue()

static void ulink_print_queue ( struct ulink device)
static

Print the OpenULINK command queue to stdout.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.

Definition at line 815 of file ulink.c.

References device, ulink_cmd::next, and ulink_print_command().

Referenced by ulink_execute_queued_commands().

◆ ulink_print_signal_states()

static void ulink_print_signal_states ( uint8_t  input_signals,
uint8_t  output_signals 
)
static

Print state of interesting signals via LOG_INFO().

Parameters
input_signalsinput signal states as returned by CMD_GET_SIGNALS
output_signalsoutput signal states as returned by CMD_GET_SIGNALS

Definition at line 490 of file ulink.c.

References LOG_INFO, SIGNAL_RESET, SIGNAL_TCK, SIGNAL_TDI, SIGNAL_TDO, SIGNAL_TMS, and SIGNAL_TRST.

Referenced by ulink_init().

◆ ulink_queue_pathmove()

static int ulink_queue_pathmove ( struct ulink device,
struct jtag_command cmd 
)
static

Move to one TAP state or several states in succession.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
cmdpointer to the command that shall be executed.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1702 of file ulink.c.

References buf_set_u32(), cmd, ERROR_FAIL, ERROR_OK, LOG_ERROR, LOG_INFO, tap_get_state(), tap_set_state, tap_state_name(), tap_state_transition(), and ulink_append_clock_tms_cmd().

Referenced by ulink_execute_queue().

◆ ulink_queue_reset()

static int ulink_queue_reset ( struct ulink device,
struct jtag_command cmd 
)
static

Execute a JTAG_RESET command.

Parameters
device
cmdpointer to the command that shall be executed.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1676 of file ulink.c.

References cmd, device, low, SIGNAL_RESET, SIGNAL_TRST, TAP_RESET, tap_set_state, and ulink_append_set_signals_cmd().

Referenced by ulink_execute_queue().

◆ ulink_queue_runtest()

static int ulink_queue_runtest ( struct ulink device,
struct jtag_command cmd 
)
static

Run Test.

Generate TCK clock cycles while remaining in the Run-Test/Idle state.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
cmdpointer to the command that shall be executed.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1644 of file ulink.c.

References cmd, device, ERROR_OK, tap_get_state(), TAP_IDLE, tap_set_end_state(), ulink_append_clock_tck_cmd(), ulink_queue_statemove(), and ulink_set_end_state().

Referenced by ulink_execute_queue().

◆ ulink_queue_scan()

static int ulink_queue_scan ( struct ulink device,
struct jtag_command cmd 
)
static

Perform a scan operation on a JTAG register.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
cmdpointer to the command that shall be executed.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1442 of file ulink.c.

References cmd, device, DIV_ROUND_UP, ERROR_FAIL, ERROR_OK, jtag_build_buffer(), jtag_scan_size(), jtag_scan_type(), NULL, SCAN_IN, SCAN_IO, SCAN_OUT, TAP_DRPAUSE, TAP_DRSHIFT, tap_get_end_state(), tap_get_state(), tap_get_tms_path(), tap_get_tms_path_len(), TAP_IRPAUSE, TAP_IRSHIFT, tap_set_end_state(), tap_set_state, tdi_buffer, tdo_buffer, type, ulink_append_scan_cmd(), and ulink_set_end_state().

Referenced by ulink_execute_queue().

◆ ulink_queue_sleep()

static int ulink_queue_sleep ( struct ulink device,
struct jtag_command cmd 
)
static

Sleep for a specific amount of time.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
cmdpointer to the command that shall be executed.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1761 of file ulink.c.

References cmd, device, and ulink_append_sleep_cmd().

Referenced by ulink_execute_queue().

◆ ulink_queue_stableclocks()

static int ulink_queue_stableclocks ( struct ulink device,
struct jtag_command cmd 
)
static

Generate TCK cycles while remaining in a stable state.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
cmdpointer to the command that shall be executed.

Definition at line 1774 of file ulink.c.

References cmd, device, ERROR_FAIL, ERROR_OK, LOG_ERROR, SIGNAL_TMS, tap_get_state(), tap_is_state_stable(), TAP_RESET, ulink_append_clock_tck_cmd(), and ulink_append_set_signals_cmd().

Referenced by ulink_execute_queue().

◆ ulink_queue_statemove()

static int ulink_queue_statemove ( struct ulink device)
static

Move from the current TAP state to the current TAP end state.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1413 of file ulink.c.

References device, ERROR_OK, tap_get_end_state(), tap_get_state(), tap_get_tms_path(), tap_get_tms_path_len(), tap_set_state, and ulink_append_clock_tms_cmd().

Referenced by ulink_queue_runtest().

◆ ulink_queue_tlr_reset()

static int ulink_queue_tlr_reset ( struct ulink device,
struct jtag_command cmd 
)
static

Move the TAP into the Test Logic Reset state.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
cmdpointer to the command that shall be executed.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 1621 of file ulink.c.

References device, ERROR_OK, TAP_RESET, tap_set_state, and ulink_append_clock_tms_cmd().

Referenced by ulink_execute_queue().

◆ ulink_quit()

static int ulink_quit ( void  )
static

Closes the USB handle for the ULINK device.

Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 2213 of file ulink.c.

References ulink_usb_close().

◆ ulink_set_end_state()

static void ulink_set_end_state ( tap_state_t  endstate)
static

Sets the end state follower (see interface.h) if endstate is a stable state.

Parameters
endstatethe state the end state follower should be set to.

Definition at line 1396 of file ulink.c.

References LOG_ERROR, tap_is_state_stable(), tap_set_end_state(), and tap_state_name().

Referenced by ulink_queue_runtest(), and ulink_queue_scan().

◆ ulink_speed()

static int ulink_speed ( int  speed)
static

Set the TCK frequency of the ULINK adapter.

Because of the way the TCK frequency is set up in the OpenULINK firmware, there are five different speed settings. To simplify things, the adapter-specific speed setting value is identical to the TCK frequency in khz.

Parameters
speeddesired adapter-specific speed value.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 2066 of file ulink.c.

References dummy, and ulink_khz().

◆ ulink_speed_div()

static int ulink_speed_div ( int  speed,
int *  khz 
)
static

Convert adapter-specific speed value to corresponding TCK frequency in kHz.

Because of the way the TCK frequency is set up in the OpenULINK firmware, there are five different speed settings. To simplify things, the adapter-specific speed setting value is identical to the TCK frequency in khz.

Parameters
speedadapter-specific speed value.
khzwhere to store corresponding TCK frequency in kHz.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 2086 of file ulink.c.

References ERROR_OK.

◆ ulink_usb_close()

static int ulink_usb_close ( struct ulink **  device)
static

Releases the ULINK interface and closes the USB device handle.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 295 of file ulink.c.

References ERROR_FAIL, ERROR_OK, and NULL.

Referenced by ulink_load_firmware_and_renumerate(), and ulink_quit().

◆ ulink_usb_open()

static int ulink_usb_open ( struct ulink **  device)
static

◆ ulink_write_firmware_section()

static int ulink_write_firmware_section ( struct ulink device,
struct image firmware_image,
int  section_index 
)
static

Send one contiguous firmware section to the ULINK's EZ-USB microcontroller over the USB bus.

Parameters
devicepointer to struct ulink identifying ULINK driver instance.
firmware_imagepointer to the firmware image that contains the section which should be sent to the ULINK's EZ-USB microcontroller.
section_indexindex of the section within the firmware image.
Returns
on success: ERROR_OK
on failure: ERROR_FAIL

Definition at line 430 of file ulink.c.

References addr, imagesection::base_address, device, ERROR_FAIL, ERROR_OK, FIRMWARE_ADDR, image_read_section(), LIBUSB_TIMEOUT_MS, LOG_DEBUG, REQUEST_FIRMWARE_LOAD, SECTION_BUFFERSIZE, image::sections, size, and imagesection::size.

Referenced by ulink_load_firmware().

Variable Documentation

◆ ulink_adapter_driver

struct adapter_driver ulink_adapter_driver
Initial value:
= {
.name = "ulink",
.transports = jtag_only,
.init = ulink_init,
.quit = ulink_quit,
.speed = ulink_speed,
.khz = ulink_khz,
.speed_div = ulink_speed_div,
.jtag_ops = &ulink_interface,
}
const char *const jtag_only[]
Definition: adapter.c:27

Definition at line 2226 of file ulink.c.

◆ ulink_command_handlers

const struct command_registration ulink_command_handlers[]
static
Initial value:
= {
{
.name = "ulink",
.mode = COMMAND_ANY,
.help = "perform ulink management",
.usage = "",
},
}
#define COMMAND_REGISTRATION_DONE
Use this as the last entry in an array of command_registration records.
Definition: command.h:253
@ COMMAND_ANY
Definition: command.h:42
const char * usage
a string listing the options and arguments, required or optional
Definition: command.h:241

Definition at line 2226 of file ulink.c.

◆ ulink_interface

struct jtag_interface ulink_interface
static
Initial value:
= {
.execute_queue = ulink_execute_queue,
}

Definition at line 2226 of file ulink.c.

◆ ulink_subcommand_handlers

const struct command_registration ulink_subcommand_handlers[]
static
Initial value:
= {
{
.name = "download_firmware",
.handler = &ulink_download_firmware_handler,
.mode = COMMAND_EXEC,
.help = "download firmware image to ULINK device",
.usage = "path/to/ulink_firmware.hex",
},
}
@ COMMAND_EXEC
Definition: command.h:40

Definition at line 2226 of file ulink.c.