Improve in-source documentation that was causing Doxygen warnings.
[fw/openocd] / src / jtag / ft2232.c
index 779923ec1d9941e5a51d0ed7f1af2e48bc4b687e..b6b812d90e84de915bfdc7a82c3e5bdb9b976947 100644 (file)
@@ -40,7 +40,8 @@
 #endif
 
 /* project specific includes */
-#include "jtag.h"
+#define INCLUDE_JTAG_INTERFACE_H
+#include "interface.h"
 #include "time_support.h"
 
 #if IS_CYGWIN == 1
@@ -82,15 +83,19 @@ static int ft2232_handle_latency_command(struct command_context_s* cmd_ctx, char
 
 
 /**
- * Function ft2232_stableclocks
- * will send out \a num_cycles on the TCK line while the TAP(s)
- * are in a stable state.  Calling code must ensure that current state is
- * stable, that verification is not done in here.
- * @param num_cycles is the count of clocks cycles to send.
- * @return int - ERROR_OK or ERROR_JTAG_QUEUE_FAILED
+ * Send out \a num_cycles on the TCK line while the TAP(s) are in a
+ * stable state.  Calling code must ensure that current state is stable,
+ * that verification is not done in here.
+ *
+ * @param num_cycles The number of clocks cycles to send.
+ * @param cmd The command to send.
+ *
+ * @returns ERROR_OK on success, or ERROR_JTAG_QUEUE_FAILED on failure.
  */
 static int ft2232_stableclocks(int num_cycles, jtag_command_t* cmd);
 
+/* max TCK for the high speed devices 30000 kHz */
+#define        FTDI_2232H_4232H_MAX_TCK        30000
 
 static char *       ft2232_device_desc_A = NULL;
 static char*        ft2232_device_desc = NULL;
@@ -173,6 +178,7 @@ static u8                  high_direction = 0x0;
 
 #if BUILD_FT2232_FTD2XX == 1
 static FT_HANDLE       ftdih = NULL;
+static FT_DEVICE       ftdi_device = 0;
 #elif BUILD_FT2232_LIBFTDI == 1
 static struct ftdi_context ftdic;
 #endif
@@ -227,19 +233,21 @@ static inline u8 buffer_read(void)
 
 
 /**
- * Function clock_tms
- * clocks out \a bit_count bits on the TMS line, starting with the least
+ * Clocks out \a bit_count bits on the TMS line, starting with the least
  * significant bit of tms_bits and progressing to more significant bits.
  * Rigorous state transition logging is done here via tap_set_state().
  *
- * @param pmsse_cmd is one of the MPSSE TMS oriented commands such as 0x4b or 0x6b.  See
- *   the MPSSE spec referenced above for their functionality. The MPSSE command
- *   "Clock Data to TMS/CS Pin (no Read)" is often used for this, 0x4b.
+ * @param mpsse_cmd One of the MPSSE TMS oriented commands such as
+ *     0x4b or 0x6b.  See the MPSSE spec referenced above for their
+ *     functionality. The MPSSE command "Clock Data to TMS/CS Pin (no Read)"
+ *     is often used for this, 0x4b.
+ *
+ * @param tms_bits Holds the sequence of bits to send.
+ * @param tms_count Tells how many bits in the sequence.
+ * @param tdi_bit A single bit to pass on to TDI before the first TCK
+ *     cycle and held static for the duration of TMS clocking.
  *
- * @param tms_bits holds the sequence of bits to send.
- * @param tms_count tells how many bits in the sequence.
- * @param tdi_bit is a single bit which is passed on to TDI before the first TCK cycle
- *   and is held static for the duration of TMS clocking.  See the MPSSE spec referenced above.
+ * See the MPSSE spec referenced above.
  */
 static void clock_tms( u8 mpsse_cmd, int tms_bits, int tms_count, bool tdi_bit )
 {
@@ -410,6 +418,46 @@ static int ft2232_read(u8* buf, u32 size, u32* bytes_read)
        return ERROR_OK;
 }
 
+#ifdef BUILD_FTD2XX_HIGHSPEED
+static bool ft2232_device_is_highspeed(void)
+{
+       return (ftdi_device == FT_DEVICE_2232H) || (ftdi_device == FT_DEVICE_4232H);
+}
+
+static int ft2232_adaptive_clocking(int speed)
+{
+       bool use_adaptive_clocking = FALSE;
+       if (0 == speed)
+       {
+               if (ft2232_device_is_highspeed())
+                       use_adaptive_clocking = TRUE;
+               else
+               {
+                       LOG_ERROR("ft2232 device %lu does not support RTCK", ftdi_device);
+                       return ERROR_OK;
+               }
+       }
+
+       u8  buf = use_adaptive_clocking ? 0x96 : 0x97;
+       LOG_DEBUG("%2.2x", buf);
+
+       u32 bytes_written;
+       int retval = ft2232_write(&buf, 1, &bytes_written);
+       if (ERROR_OK != retval || bytes_written != 1)
+       {
+               LOG_ERROR("unable to set adative clocking: %d", retval);
+               return retval;
+       }
+
+       return ERROR_OK;
+}
+#else
+static int ft2232_adaptive_clocking(int speed)
+{
+       // not implemented on low-speed devices
+       return speed ? ERROR_OK : -1234;
+}
+#endif
 
 static int ft2232_speed(int speed)
 {
@@ -417,6 +465,8 @@ static int ft2232_speed(int speed)
        int retval;
        u32 bytes_written;
 
+       ft2232_adaptive_clocking(speed);
+
        buf[0] = 0x86;                          /* command "set divisor" */
        buf[1] = speed & 0xff;          /* valueL (0=6MHz, 1=3MHz, 2=2.0MHz, ...*/
        buf[2] = (speed >> 8) & 0xff;   /* valueH */
@@ -448,8 +498,15 @@ static int ft2232_khz(int khz, int* jtag_speed)
 {
        if (khz==0)
        {
-               LOG_DEBUG("RTCK not supported");
+#ifdef BUILD_FTD2XX_HIGHSPEED
+               *jtag_speed = 0;
+               return ERROR_OK;
+#else
+               LOG_DEBUG("RCLK not supported");
+               LOG_DEBUG("If you have a high-speed FTDI device, then "
+                       "OpenOCD may be built with --enable-ftd2xx-highspeed.");
                return ERROR_FAIL;
+#endif
        }
 
        /* Take a look in the FT2232 manual,
@@ -1427,9 +1484,9 @@ static int ft2232_execute_runtest(jtag_command_t *cmd)
        if (tap_get_state() != TAP_IDLE)
                predicted_size += 3;
        predicted_size += 3 * CEIL(cmd->cmd.runtest->num_cycles, 7);
-       if ( (cmd->cmd.runtest->end_state != TAP_INVALID) && (cmd->cmd.runtest->end_state != TAP_IDLE) )
+       if ( cmd->cmd.runtest->end_state != TAP_IDLE)
                predicted_size += 3;
-       if ( (cmd->cmd.runtest->end_state == TAP_INVALID) && (tap_get_end_state() != TAP_IDLE) )
+       if ( tap_get_end_state() != TAP_IDLE)
                predicted_size += 3;
        if (ft2232_buffer_size + predicted_size + 1 > FT2232_BUFFER_SIZE)
        {
@@ -1462,8 +1519,7 @@ static int ft2232_execute_runtest(jtag_command_t *cmd)
                /* LOG_DEBUG("added TMS scan (no read)"); */
        }
 
-       if (cmd->cmd.runtest->end_state != TAP_INVALID)
-               ft2232_end_state(cmd->cmd.runtest->end_state);
+       ft2232_end_state(cmd->cmd.runtest->end_state);
 
        if ( tap_get_state() != tap_get_end_state() )
        {
@@ -1495,8 +1551,7 @@ static int ft2232_execute_statemove(jtag_command_t *cmd)
                require_send = 0;
                first_unsent = cmd;
        }
-       if (cmd->cmd.statemove->end_state != TAP_INVALID)
-               ft2232_end_state(cmd->cmd.statemove->end_state);
+       ft2232_end_state(cmd->cmd.statemove->end_state);
 
        /* move to end state */
        if ( tap_get_state() != tap_get_end_state() )
@@ -1562,8 +1617,7 @@ static int ft2232_execute_scan(jtag_command_t *cmd)
                                retval = ERROR_JTAG_QUEUE_FAILED;
 
                /* current command */
-               if (cmd->cmd.scan->end_state != TAP_INVALID)
-                       ft2232_end_state(cmd->cmd.scan->end_state);
+               ft2232_end_state(cmd->cmd.scan->end_state);
                ft2232_large_scan(cmd->cmd.scan, type, buffer, scan_size);
                require_send = 0;
                first_unsent = cmd->next;
@@ -1583,8 +1637,7 @@ static int ft2232_execute_scan(jtag_command_t *cmd)
        }
        ft2232_expect_read += ft2232_predict_scan_in(scan_size, type);
        /* LOG_DEBUG("new read size: %i", ft2232_expect_read); */
-       if (cmd->cmd.scan->end_state != TAP_INVALID)
-               ft2232_end_state(cmd->cmd.scan->end_state);
+       ft2232_end_state(cmd->cmd.scan->end_state);
        ft2232_add_scan(cmd->cmd.scan->ir_scan, type, buffer, scan_size);
        require_send = 1;
        if (buffer)
@@ -1727,6 +1780,9 @@ static int ft2232_execute_queue()
 static int ft2232_init_ftd2xx(u16 vid, u16 pid, int more, int* try_more)
 {
        FT_STATUS       status;
+       DWORD           deviceID;
+       char            SerialNumber[16];
+       char            Description[64]; 
        DWORD           openex_flags  = 0;
        char*           openex_string = NULL;
        u8              latency_timer;
@@ -1857,6 +1913,27 @@ static int ft2232_init_ftd2xx(u16 vid, u16 pid, int more, int* try_more)
                return ERROR_JTAG_INIT_FAILED;
        }
 
+       if ( ( status = FT_GetDeviceInfo(ftdih, &ftdi_device, &deviceID, SerialNumber, Description, NULL) ) != FT_OK )
+       {
+               LOG_ERROR("unable to get FT_GetDeviceInfo: %lu", status);
+               return ERROR_JTAG_INIT_FAILED;
+       }
+       else
+       {
+               LOG_INFO("device: %lu", ftdi_device);
+               LOG_INFO("deviceID: %lu", deviceID);
+               LOG_INFO("SerialNumber: %s", SerialNumber);
+               LOG_INFO("Description: %s", Description);
+
+#ifdef BUILD_FTD2XX_HIGHSPEED
+               if (ft2232_device_is_highspeed())
+               {
+                       ft2232_max_tck = FTDI_2232H_4232H_MAX_TCK;
+                       LOG_INFO("max TCK change to: %u kHz", ft2232_max_tck);
+               }
+#endif
+       }
+
        return ERROR_OK;
 }