src/jtag/drivers/usb_blaster.c

   1 /***************************************************************************
   2  *   Driver for USB-JTAG, Altera USB-Blaster and compatibles               *
   3  *   Original code from Kolja Waschk's USB-JTAG project                    *
   4  *     (http://www.ixo.de/info/usb_jtag/).                                 *
   5  *   Some updates by Anthony Liu (2006).                                   *
   6  *   Minor updates and cleanup by Catalin Patulea (2009).                  *
   7  *                                                                         *
   8  *   Copyright (C) 2009 Catalin Patulea                                    *
   9  *   cat@vv.carleton.ca                                                    *
  10  *                                                                         *
  11  *   Copyright (C) 2006 Kolja Waschk                                       *
  12  *   usbjtag@ixo.de                                                        *
  13  *                                                                         *
  14  *   Based on ft2232.c and bitbang.c,                                      *
  15  *   Copyright (C) 2004,2006 by Dominic Rath                               *
  16  *                                                                         *
  17  *   This program is free software; you can redistribute it and/or modify  *
  18  *   it under the terms of the GNU General Public License as published by  *
  19  *   the Free Software Foundation; either version 2 of the License, or     *
  20  *   (at your option) any later version.                                   *
  21  *                                                                         *
  22  *   This program is distributed in the hope that it will be useful,       *
  23  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  24  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  25  *   GNU General Public License for more details.                          *
  26  *                                                                         *
  27  *   You should have received a copy of the GNU General Public License     *
  28  *   along with this program; if not, write to the                         *
  29  *   Free Software Foundation, Inc.,                                       *
  30  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  31  ***************************************************************************/
  32
  33 /*
  34  * The following information is originally from Kolja Waschk's USB-JTAG,
  35  * where it was obtained by reverse engineering an Altera USB-Blaster.
  36  * See http://www.ixo.de/info/usb_jtag/ for USB-Blaster block diagram and
  37  * usb_jtag-20080705-1200.zip#usb_jtag/host/openocd for protocol.
  38  *
  39  * The same information is also on the UrJTAG mediawiki, with some additional
  40  * notes on bits marked as "unknown" by usb_jtag.
  41  * (http://sourceforge.net/apps/mediawiki/urjtag/index.php?
  42  *    title=Cable_Altera_USB-Blaster)
  43  *
  44  * USB-JTAG, Altera USB-Blaster and compatibles are typically implemented as
  45  * an FTDIChip FT245 followed by a CPLD which handles a two-mode protocol:
  46  *
  47  *            _________
  48  *           |         |
  49  *           | AT93C46 |
  50  *           |_________|
  51  *            __|__________    _________
  52  *           |             |  |         |
  53  *      USB__| FTDI 245BM  |__| EPM7064 |__JTAG (B_TDO,B_TDI,B_TMS,B_TCK)
  54  *           |_____________|  |_________|
  55  *            __|__________    _|___________
  56  *           |             |  |             |
  57  *           | 6 MHz XTAL  |  | 24 MHz Osc. |
  58  *           |_____________|  |_____________|
  59  *
  60  * Protocol details are given in the code below.
  61  *
  62  * It is also possible to emulate this configuration using a single-chip USB
  63  * controller like the Cypress FX2 (again, see usb_jtag for details).
  64  */
  65 #ifdef HAVE_CONFIG_H
  66 #include "config.h"
  67 #endif
  68
  69 #if IS_CYGWIN == 1
  70 #include "windows.h"
  71 #undef LOG_ERROR
  72 #endif
  73
  74 /* project specific includes */
  75 #include <jtag/interface.h>
  76 #include <jtag/commands.h>
  77 #include <helper/time_support.h>
  78
  79 /* system includes */
  80 #include <string.h>
  81 #include <stdlib.h>
  82 #include <unistd.h>
  83
  84 #include "bitbang.h"
  85
  86 #if (BUILD_USB_BLASTER_FTD2XX == 1 && BUILD_USB_BLASTER_LIBFTDI == 1)
  87 #error "BUILD_USB_BLASTER_FTD2XX && BUILD_USB_BLASTER_LIBFTDI "
  88            "are mutually exclusive"
  89 #elif (BUILD_USB_BLASTER_FTD2XX != 1 && BUILD_USB_BLASTER_LIBFTDI != 1)
  90 #error "BUILD_USB_BLASTER_FTD2XX || BUILD_USB_BLASTER_LIBFTDI must be chosen"
  91 #endif
  92
  93 /* USB_BLASTER access library includes */
  94 #if BUILD_USB_BLASTER_FTD2XX == 1
  95 #include <ftd2xx.h>
  96 #elif BUILD_USB_BLASTER_LIBFTDI == 1
  97 #include <ftdi.h>
  98 #endif
  99
 100 #include <sys/time.h>
 101 #include <time.h>
 102
 103 static char *usb_blaster_device_desc;
 104 static uint16_t usb_blaster_vid = 0x09fb; /* Altera */
 105 static uint16_t usb_blaster_pid = 0x6001; /* USB-Blaster */
 106
 107 /* last output byte in simple bit banging mode */
 108 static uint8_t out_value;
 109
 110 #if BUILD_USB_BLASTER_FTD2XX == 1
 111 static FT_HANDLE ftdih;
 112 #elif BUILD_USB_BLASTER_LIBFTDI == 1
 113 static struct ftdi_context ftdic;
 114 #endif
 115
 116 static int usb_blaster_buf_write(
 117         uint8_t *buf, int size, uint32_t *bytes_written)
 118 {
 119 #if BUILD_USB_BLASTER_FTD2XX == 1
 120         FT_STATUS status;
 121         DWORD dw_bytes_written;
 122
 123 #ifdef _DEBUG_JTAG_IO_
 124         LOG_DEBUG("usb_blaster_buf_write %02X (%d)", buf[0], size);
 125 #endif
 126         status = FT_Write(ftdih, buf, size, &dw_bytes_written);
 127         if (status != FT_OK)
 128         {
 129                 *bytes_written = dw_bytes_written;
 130                 LOG_ERROR("FT_Write returned: %lu", status);
 131                 return ERROR_JTAG_DEVICE_ERROR;
 132         }
 133         *bytes_written = dw_bytes_written;
 134         return ERROR_OK;
 135 #elif BUILD_USB_BLASTER_LIBFTDI == 1
 136         int retval;
 137 #ifdef _DEBUG_JTAG_IO_
 138         LOG_DEBUG("usb_blaster_buf_write %02X (%d)", buf[0], size);
 139 #endif
 140         retval = ftdi_write_data(&ftdic, buf, size);
 141         if (retval < 0)
 142         {
 143                 *bytes_written = 0;
 144                 LOG_ERROR("ftdi_write_data: %s", ftdi_get_error_string(&ftdic));
 145                 return ERROR_JTAG_DEVICE_ERROR;
 146         }
 147         *bytes_written = retval;
 148         return ERROR_OK;
 149 #endif
 150 }
 151
 152 static int
 153 usb_blaster_buf_read(uint8_t *buf, unsigned size, uint32_t *bytes_read)
 154 {
 155 #if BUILD_USB_BLASTER_FTD2XX == 1
 156         DWORD dw_bytes_read;
 157         FT_STATUS status;
 158
 159         status = FT_Read(ftdih, buf, size, &dw_bytes_read);
 160         if (status != FT_OK)
 161         {
 162                 *bytes_read = dw_bytes_read;
 163                 LOG_ERROR("FT_Read returned: %lu", status);
 164                 return ERROR_JTAG_DEVICE_ERROR;
 165         }
 166 #ifdef _DEBUG_JTAG_IO_
 167         LOG_DEBUG("usb_blaster_buf_read %02X (%lu)", buf[0], dw_bytes_read);
 168 #endif
 169         *bytes_read = dw_bytes_read;
 170         return ERROR_OK;
 171
 172 #elif BUILD_USB_BLASTER_LIBFTDI == 1
 173         int retval;
 174         int timeout = 100;
 175
 176         *bytes_read = 0;
 177         while ((*bytes_read < size) && timeout--)
 178         {
 179                 retval = ftdi_read_data(&ftdic, buf + *bytes_read,
 180                                 size - *bytes_read);
 181                 if (retval < 0)
 182                 {
 183                         *bytes_read = 0;
 184                         LOG_ERROR("ftdi_read_data: %s",
 185                                         ftdi_get_error_string(&ftdic));
 186                         return ERROR_JTAG_DEVICE_ERROR;
 187                 }
 188                 *bytes_read += retval;
 189         }
 190 #ifdef _DEBUG_JTAG_IO_
 191         LOG_DEBUG("usb_blaster_buf_read %02X (%d)", buf[0], *bytes_read);
 192 #endif
 193         return ERROR_OK;
 194 #endif
 195 }
 196
 197 /* The following code doesn't fully utilize the possibilities of the
 198  * USB-Blaster. It writes one byte per JTAG pin state change at a time; it
 199  * doesn't even try to buffer data up to the maximum packet size of 64 bytes.
 200  *
 201  * Actually, the USB-Blaster offers a byte-shift mode to transmit up to 504 data
 202  * bits (bidirectional) in a single USB packet. A header byte has to be sent as
 203  * the first byte in a packet with the following meaning:
 204  *
 205  *   Bit 7 (0x80): Must be set to indicate byte-shift mode.
 206  *   Bit 6 (0x40): If set, the USB-Blaster will also read data, not just write.
 207  *   Bit 5..0:     Define the number N of following bytes
 208  *
 209  * All N following bytes will then be clocked out serially on TDI. If Bit 6 was
 210  * set, it will afterwards return N bytes with TDO data read while clocking out
 211  * the TDI data. LSB of the first byte after the header byte will appear first
 212  * on TDI.
 213  */
 214
 215 /* Simple bit banging mode:
 216  *
 217  *   Bit 7 (0x80): Must be zero (see byte-shift mode above)
 218  *   Bit 6 (0x40): If set, you will receive a byte indicating the state of TDO
 219  *                 in return.
 220  *   Bit 5 (0x20): Output Enable/LED.
 221  *   Bit 4 (0x10): TDI Output.
 222  *   Bit 3 (0x08): nCS Output (not used in JTAG mode).
 223  *   Bit 2 (0x04): nCE Output (not used in JTAG mode).
 224  *   Bit 1 (0x02): TMS Output.
 225  *   Bit 0 (0x01): TCK Output.
 226  *
 227  * For transmitting a single data bit, you need to write two bytes. Up to 64
 228  * bytes can be combined in a single USB packet (but this is not done in the
 229  * code below). It isn't possible to read a data without transmitting data.
 230  */
 231
 232 #define TCK                     (1 << 0)
 233 #define TMS                     (1 << 1)
 234 #define NCE                     (1 << 2)
 235 #define NCS                     (1 << 3)
 236 #define TDI                     (1 << 4)
 237 #define LED                     (1 << 5)
 238 #define READ            (1 << 6)
 239 #define SHMODE          (1 << 7)
 240 #define OTHERS          ((1 << 2) | (1 << 3) | (1 << 5))
 241
 242 #define READ_TDO        (1 << 0)
 243
 244 static void usb_blaster_write_data(void)
 245 {
 246         uint32_t bytes_written;
 247         usb_blaster_buf_write(&out_value, 1, &bytes_written);
 248 }
 249
 250 static int usb_blaster_read_data(void)
 251 {
 252         int status;
 253         uint8_t buf[1];
 254         uint32_t bytes_read;
 255
 256         out_value |= READ;
 257         usb_blaster_write_data();
 258         out_value &= ~READ;
 259
 260         status = usb_blaster_buf_read(buf, 1, &bytes_read);
 261         if (status < 0)
 262                 return 0;
 263
 264         return !!(buf[0] & READ_TDO);
 265 }
 266
 267 static void usb_blaster_write(int tck, int tms, int tdi)
 268 {
 269 #ifdef _DEBUG_JTAG_IO_
 270         LOG_DEBUG("---- usb_blaster_write(%d,%d,%d)", tck, tms, tdi);
 271 #endif
 272         out_value &= ~(TCK | TMS | TDI);
 273         if (tck)
 274                 out_value |= TCK;
 275         if (tms)
 276                 out_value |= TMS;
 277         if (tdi)
 278                 out_value |= TDI;
 279
 280         usb_blaster_write_data();
 281 }
 282
 283 static int usb_blaster_speed(int speed)
 284 {
 285 #if BUILD_USB_BLASTER_FTD2XX == 1
 286         LOG_DEBUG("TODO: usb_blaster_speed() isn't implemented for libftd2xx!");
 287 #elif BUILD_USB_BLASTER_LIBFTDI == 1
 288         LOG_DEBUG("TODO: usb_blaster_speed() isn't optimally implemented!");
 289
 290         /* TODO: libftdi's ftdi_set_baudrate chokes on high rates, use lowlevel
 291          * usb function instead! And additionally allow user to throttle.
 292          */
 293         if (ftdi_set_baudrate(&ftdic, 3000000 / 4) < 0)
 294         {
 295                 LOG_ERROR("Can't set baud rate to max: %s",
 296                         ftdi_get_error_string(&ftdic));
 297                 return ERROR_JTAG_DEVICE_ERROR;
 298         };
 299 #endif
 300
 301         return ERROR_OK;
 302 }
 303
 304 static void usb_blaster_reset(int trst, int srst)
 305 {
 306         LOG_DEBUG("TODO: usb_blaster_reset(%d,%d) isn't implemented!",
 307                         trst, srst);
 308 }
 309
 310 static void usb_blaster_blink(int state)
 311 {
 312         out_value = 0x00;
 313         if(state)
 314                 out_value |= LED;
 315         usb_blaster_write_data();
 316 }
 317
 318 static struct bitbang_interface usb_blaster_bitbang = {
 319         .read = usb_blaster_read_data,
 320         .write = usb_blaster_write,
 321         .reset = usb_blaster_reset,
 322         .blink = usb_blaster_blink,
 323 };
 324
 325 static int usb_blaster_init(void)
 326 {
 327         uint8_t latency_timer;
 328
 329 #if BUILD_USB_BLASTER_FTD2XX == 1
 330         FT_STATUS status;
 331 #endif
 332
 333 #if BUILD_USB_BLASTER_FTD2XX == 1
 334         LOG_DEBUG("'usb_blaster' interface using FTD2XX");
 335 #elif BUILD_USB_BLASTER_LIBFTDI == 1
 336         LOG_DEBUG("'usb_blaster' interface using libftdi");
 337 #endif
 338
 339 #if BUILD_USB_BLASTER_FTD2XX == 1
 340         /* Open by device description */
 341         if (usb_blaster_device_desc == NULL)
 342         {
 343                 LOG_WARNING("no usb_blaster device description specified, "
 344                                         "using default 'USB-Blaster'");
 345                 usb_blaster_device_desc = "USB-Blaster";
 346         }
 347
 348 #if IS_WIN32 == 0
 349         /* Add non-standard Vid/Pid to the linux driver */
 350         status = FT_SetVIDPID(usb_blaster_vid, usb_blaster_pid);
 351         if (status != FT_OK)
 352         {
 353                 LOG_WARNING("couldn't add %4.4x:%4.4x",
 354                         usb_blaster_vid, usb_blaster_pid);
 355         }
 356 #endif
 357
 358         status = FT_OpenEx(usb_blaster_device_desc, FT_OPEN_BY_DESCRIPTION,
 359                         &ftdih);
 360         if (status != FT_OK)
 361         {
 362                 DWORD num_devices;
 363
 364                 LOG_ERROR("unable to open ftdi device: %lu", status);
 365                 status = FT_ListDevices(&num_devices, NULL,
 366                                 FT_LIST_NUMBER_ONLY);
 367                 if (status == FT_OK)
 368                 {
 369                         char **desc_array = malloc(sizeof(char *)
 370                                                 * (num_devices + 1));
 371                         unsigned int i;
 372
 373                         for (i = 0; i < num_devices; i++)
 374                                 desc_array[i] = malloc(64);
 375                         desc_array[num_devices] = NULL;
 376
 377                         status = FT_ListDevices(desc_array, &num_devices,
 378                                 FT_LIST_ALL | FT_OPEN_BY_DESCRIPTION);
 379
 380                         if (status == FT_OK)
 381                         {
 382                                 LOG_ERROR("ListDevices: %lu", num_devices);
 383                                 for (i = 0; i < num_devices; i++)
 384                                         LOG_ERROR("%i: %s", i, desc_array[i]);
 385                         }
 386
 387                         for (i = 0; i < num_devices; i++)
 388                                 free(desc_array[i]);
 389                         free(desc_array);
 390                 }
 391                 else
 392                 {
 393                         printf("ListDevices: NONE\n");
 394                 }
 395                 return ERROR_JTAG_INIT_FAILED;
 396         }
 397
 398         status = FT_SetLatencyTimer(ftdih, 2);
 399         if (status != FT_OK)
 400         {
 401                 LOG_ERROR("unable to set latency timer: %lu", status);
 402                 return ERROR_JTAG_INIT_FAILED;
 403         }
 404
 405         status = FT_GetLatencyTimer(ftdih, &latency_timer);
 406         if (status != FT_OK)
 407         {
 408                 LOG_ERROR("unable to get latency timer: %lu", status);
 409                 return ERROR_JTAG_INIT_FAILED;
 410         }
 411         LOG_DEBUG("current latency timer: %i", latency_timer);
 412
 413         status = FT_SetBitMode(ftdih, 0x00, 0);
 414         if (status != FT_OK)
 415         {
 416                 LOG_ERROR("unable to disable bit i/o mode: %lu", status);
 417                 return ERROR_JTAG_INIT_FAILED;
 418         }
 419 #elif BUILD_USB_BLASTER_LIBFTDI == 1
 420         if (ftdi_init(&ftdic) < 0)
 421                 return ERROR_JTAG_INIT_FAILED;
 422
 423         /* context, vendor id, product id */
 424         if (ftdi_usb_open(&ftdic, usb_blaster_vid, usb_blaster_pid) < 0)
 425         {
 426                 LOG_ERROR("unable to open ftdi device: %s", ftdic.error_str);
 427                 return ERROR_JTAG_INIT_FAILED;
 428         }
 429
 430         if (ftdi_usb_reset(&ftdic) < 0)
 431         {
 432                 LOG_ERROR("unable to reset ftdi device");
 433                 return ERROR_JTAG_INIT_FAILED;
 434         }
 435
 436         if (ftdi_set_latency_timer(&ftdic, 2) < 0)
 437         {
 438                 LOG_ERROR("unable to set latency timer");
 439                 return ERROR_JTAG_INIT_FAILED;
 440         }
 441
 442         if (ftdi_get_latency_timer(&ftdic, &latency_timer) < 0)
 443         {
 444                 LOG_ERROR("unable to get latency timer");
 445                 return ERROR_JTAG_INIT_FAILED;
 446         }
 447         LOG_DEBUG("current latency timer: %u", latency_timer);
 448
 449         ftdi_disable_bitbang(&ftdic);
 450 #endif
 451
 452         bitbang_interface = &usb_blaster_bitbang;
 453
 454         int jtag_speed_var;
 455         int retval = jtag_get_speed(&jtag_speed_var);
 456         if (retval != ERROR_OK)
 457                 return retval;
 458         usb_blaster_speed(jtag_speed_var);
 459
 460 #if 0
 461 #if BUILD_USB_BLASTER_FTD2XX == 1
 462         if ((status = FT_Purge(ftdih, FT_PURGE_RX | FT_PURGE_TX)) != FT_OK)
 463         {
 464                 LOG_ERROR("error purging ftd2xx device: %i", status);
 465                 return ERROR_JTAG_INIT_FAILED;
 466         }
 467 #elif BUILD_USB_BLASTER_LIBFTDI == 1
 468         if (ftdi_usb_purge_buffers(&ftdic) < 0)
 469         {
 470                 LOG_ERROR("ftdi_purge_buffers: %s", ftdic.error_str);
 471                 return ERROR_JTAG_INIT_FAILED;
 472         }
 473 #endif
 474 #endif
 475
 476         return ERROR_OK;
 477 }
 478
 479 static int usb_blaster_quit(void)
 480 {
 481 #if BUILD_USB_BLASTER_FTD2XX == 1
 482         FT_STATUS status;
 483
 484         status = FT_Close(ftdih);
 485 #elif BUILD_USB_BLASTER_LIBFTDI == 1
 486         ftdi_usb_close(&ftdic);
 487         ftdi_deinit(&ftdic);
 488 #endif
 489
 490         return ERROR_OK;
 491 }
 492
 493 COMMAND_HANDLER(usb_blaster_handle_device_desc_command)
 494 {
 495         if (CMD_ARGC == 1)
 496                 usb_blaster_device_desc = strdup(CMD_ARGV[0]);
 497         else
 498                 LOG_ERROR("require exactly one argument to "
 499                                   "usb_blaster_device_desc <description>");
 500
 501         return ERROR_OK;
 502 }
 503
 504 COMMAND_HANDLER(usb_blaster_handle_vid_pid_command)
 505 {
 506         if (CMD_ARGC > 2)
 507         {
 508                 LOG_WARNING("ignoring extra IDs in usb_blaster_vid_pid "
 509                                         "(maximum is 1 pair)");
 510                 CMD_ARGC = 2;
 511         }
 512         if (CMD_ARGC == 2)
 513         {
 514                 COMMAND_PARSE_NUMBER(u16, CMD_ARGV[0], usb_blaster_vid);
 515                 COMMAND_PARSE_NUMBER(u16, CMD_ARGV[1], usb_blaster_pid);
 516         }
 517         else
 518                 LOG_WARNING("incomplete usb_blaster_vid_pid configuration");
 519
 520         return ERROR_OK;
 521 }
 522
 523 COMMAND_HANDLER(usb_blaster_handle_pin_command)
 524 {
 525         if (CMD_ARGC == 2)
 526         {
 527                 const char * const pin_name = CMD_ARGV[0];
 528                 uint8_t mask;
 529                 unsigned int state;
 530
 531                 if (!strcmp(pin_name, "pin6"))
 532                         mask = NCE;
 533                 else if (!strcmp(pin_name, "pin8"))
 534                         mask = NCS;
 535                 else
 536                 {
 537                         LOG_ERROR("%s: pin name must be \"pin6\" or \"pin8\"",
 538                                         CMD_NAME);
 539                         return ERROR_COMMAND_SYNTAX_ERROR;
 540                 }
 541
 542                 COMMAND_PARSE_NUMBER(uint, CMD_ARGV[1], state);
 543                 if (state == 0)
 544                 {
 545                         out_value &= ~mask;
 546                         usb_blaster_write_data();
 547                 }
 548                 else if (state == 1)
 549                 {
 550                         out_value |= mask;
 551                         usb_blaster_write_data();
 552                 }
 553                 else
 554                 {
 555                         LOG_ERROR("%s: pin state must be 0 or 1", CMD_NAME);
 556                         return ERROR_COMMAND_SYNTAX_ERROR;
 557                 }
 558
 559                 return ERROR_OK;
 560         }
 561         else
 562         {
 563                 LOG_ERROR("%s takes exactly two arguments", CMD_NAME);
 564                 return ERROR_COMMAND_SYNTAX_ERROR;
 565         }
 566 }
 567
 568 static const struct command_registration usb_blaster_command_handlers[] = {
 569         {
 570                 .name = "usb_blaster_device_desc",
 571                 .handler = usb_blaster_handle_device_desc_command,
 572                 .mode = COMMAND_CONFIG,
 573                 .help = "set the USB device description of the USB-Blaster",
 574                 .usage = "description-string",
 575         },
 576         {
 577                 .name = "usb_blaster_vid_pid",
 578                 .handler = usb_blaster_handle_vid_pid_command,
 579                 .mode = COMMAND_CONFIG,
 580                 .help = "the vendor ID and product ID of the USB-Blaster",
 581                 .usage = "vid pid",
 582         },
 583         {
 584                 .name = "usb_blaster",
 585                 .handler = usb_blaster_handle_pin_command,
 586                 .mode = COMMAND_ANY,
 587                 .help = "set pin state for the unused GPIO pins",
 588                 .usage = "(pin6|pin8) (0|1)",
 589         },
 590         COMMAND_REGISTRATION_DONE
 591 };
 592
 593 struct jtag_interface usb_blaster_interface = {
 594         .name = "usb_blaster",
 595         .commands = usb_blaster_command_handlers,
 596         .supported = DEBUG_CAP_TMS_SEQ,
 597
 598         .execute_queue = bitbang_execute_queue,
 599
 600         .speed = usb_blaster_speed,
 601         .init = usb_blaster_init,
 602         .quit = usb_blaster_quit,
 603 };