developer.intra2net.com Git - libftdi/blob - src/ftdi.c

   1 /***************************************************************************
   2                           ftdi.c  -  description
   3                              -------------------
   4     begin                : Fri Apr 4 2003
   5     copyright            : (C) 2003-2008 by Intra2net AG
   6     email                : opensource@intra2net.com
   7  ***************************************************************************/
   8
   9 /***************************************************************************
  10  *                                                                         *
  11  *   This program is free software; you can redistribute it and/or modify  *
  12  *   it under the terms of the GNU Lesser General Public License           *
  13  *   version 2.1 as published by the Free Software Foundation;             *
  14  *                                                                         *
  15  ***************************************************************************/
  16
  17 /**
  18     \mainpage libftdi API documentation
  19
  20     Library to talk to FTDI chips. You find the latest versions of libftdi at
  21     http://www.intra2net.com/en/developer/libftdi/
  22
  23     The library is easy to use. Have a look at this short example:
  24     \include simple.c
  25
  26     More examples can be found in the "examples" directory.
  27 */
  28 /** \addtogroup libftdi */
  29 /* @{ */
  30
  31 #include <usb.h>
  32 #include <string.h>
  33 #include <errno.h>
  34 #include <stdio.h>
  35
  36 #include "ftdi.h"
  37
  38 /* stuff needed for async write */
  39 #ifdef LIBFTDI_LINUX_ASYNC_MODE
  40 #include <sys/ioctl.h>
  41 #include <sys/time.h>
  42 #include <sys/select.h>
  43 #include <sys/types.h>
  44 #include <unistd.h>
  45 #include <linux/usbdevice_fs.h>
  46 #endif
  47
  48 #define ftdi_error_return(code, str) do {  \
  49         ftdi->error_str = str;             \
  50         return code;                       \
  51    } while(0);
  52
  53 /**
  54     Internal function to close usb device pointer.
  55     Sets ftdi->usb_dev to NULL.
  56     \internal
  57
  58     \param ftdi pointer to ftdi_context
  59
  60     \retval  zero if all is fine, otherwise error code from usb_close()
  61 */
  62 static int ftdi_usb_close_internal (struct ftdi_context *ftdi)
  63 {
  64     int ret = 0;
  65
  66     if (ftdi->usb_dev)
  67     {
  68        ret = usb_close (ftdi->usb_dev);
  69        ftdi->usb_dev = NULL;
  70     }
  71
  72     return ret;
  73 }
  74
  75 /**
  76     Initializes a ftdi_context.
  77
  78     \param ftdi pointer to ftdi_context
  79
  80     \retval  0: all fine
  81     \retval -1: couldn't allocate read buffer
  82
  83     \remark This should be called before all functions
  84 */
  85 int ftdi_init(struct ftdi_context *ftdi)
  86 {
  87     unsigned int i;
  88
  89     ftdi->usb_dev = NULL;
  90     ftdi->usb_read_timeout = 5000;
  91     ftdi->usb_write_timeout = 5000;
  92
  93     ftdi->type = TYPE_BM;    /* chip type */
  94     ftdi->baudrate = -1;
  95     ftdi->bitbang_enabled = 0;
  96
  97     ftdi->readbuffer = NULL;
  98     ftdi->readbuffer_offset = 0;
  99     ftdi->readbuffer_remaining = 0;
 100     ftdi->writebuffer_chunksize = 4096;
 101     ftdi->max_packet_size = 0;
 102
 103     ftdi->interface = 0;
 104     ftdi->index = 0;
 105     ftdi->in_ep = 0x02;
 106     ftdi->out_ep = 0x81;
 107     ftdi->bitbang_mode = 1; /* 1: Normal bitbang mode, 2: SPI bitbang mode */
 108
 109     ftdi->error_str = NULL;
 110
 111 #ifdef LIBFTDI_LINUX_ASYNC_MODE
 112     ftdi->async_usb_buffer_size=10;
 113     if ((ftdi->async_usb_buffer=malloc(sizeof(struct usbdevfs_urb)*ftdi->async_usb_buffer_size)) == NULL)
 114         ftdi_error_return(-1, "out of memory for async usb buffer");
 115
 116     /* initialize async usb buffer with unused-marker */
 117     for (i=0; i < ftdi->async_usb_buffer_size; i++)
 118         ((struct usbdevfs_urb*)ftdi->async_usb_buffer)[i].usercontext = FTDI_URB_USERCONTEXT_COOKIE;
 119 #else
 120     ftdi->async_usb_buffer_size=0;
 121     ftdi->async_usb_buffer = NULL;
 122 #endif
 123
 124     ftdi->eeprom_size = FTDI_DEFAULT_EEPROM_SIZE;
 125
 126     /* All fine. Now allocate the readbuffer */
 127     return ftdi_read_data_set_chunksize(ftdi, 4096);
 128 }
 129
 130 /**
 131     Allocate and initialize a new ftdi_context
 132
 133     \return a pointer to a new ftdi_context, or NULL on failure
 134 */
 135 struct ftdi_context *ftdi_new(void)
 136 {
 137     struct ftdi_context * ftdi = (struct ftdi_context *)malloc(sizeof(struct ftdi_context));
 138
 139     if (ftdi == NULL)
 140     {
 141         return NULL;
 142     }
 143
 144     if (ftdi_init(ftdi) != 0)
 145     {
 146         free(ftdi);
 147         return NULL;
 148     }
 149
 150     return ftdi;
 151 }
 152
 153 /**
 154     Open selected channels on a chip, otherwise use first channel.
 155
 156     \param ftdi pointer to ftdi_context
 157     \param interface Interface to use for FT2232C/2232H/4232H chips.
 158
 159     \retval  0: all fine
 160     \retval -1: unknown interface
 161 */
 162 int ftdi_set_interface(struct ftdi_context *ftdi, enum ftdi_interface interface)
 163 {
 164     switch (interface)
 165     {
 166         case INTERFACE_ANY:
 167         case INTERFACE_A:
 168             /* ftdi_usb_open_desc cares to set the right index, depending on the found chip */
 169             break;
 170         case INTERFACE_B:
 171             ftdi->interface = 1;
 172             ftdi->index     = INTERFACE_B;
 173             ftdi->in_ep     = 0x04;
 174             ftdi->out_ep    = 0x83;
 175             break;
 176         case INTERFACE_C:
 177             ftdi->interface = 2;
 178             ftdi->index     = INTERFACE_C;
 179             ftdi->in_ep     = 0x06;
 180             ftdi->out_ep    = 0x85;
 181             break;
 182         case INTERFACE_D:
 183             ftdi->interface = 3;
 184             ftdi->index     = INTERFACE_D;
 185             ftdi->in_ep     = 0x08;
 186             ftdi->out_ep    = 0x87;
 187             break;
 188         default:
 189             ftdi_error_return(-1, "Unknown interface");
 190     }
 191     return 0;
 192 }
 193
 194 /**
 195     Deinitializes a ftdi_context.
 196
 197     \param ftdi pointer to ftdi_context
 198 */
 199 void ftdi_deinit(struct ftdi_context *ftdi)
 200 {
 201     ftdi_usb_close_internal (ftdi);
 202
 203     if (ftdi->async_usb_buffer != NULL)
 204     {
 205         free(ftdi->async_usb_buffer);
 206         ftdi->async_usb_buffer = NULL;
 207     }
 208
 209     if (ftdi->readbuffer != NULL)
 210     {
 211         free(ftdi->readbuffer);
 212         ftdi->readbuffer = NULL;
 213     }
 214 }
 215
 216 /**
 217     Deinitialize and free an ftdi_context.
 218
 219     \param ftdi pointer to ftdi_context
 220 */
 221 void ftdi_free(struct ftdi_context *ftdi)
 222 {
 223     ftdi_deinit(ftdi);
 224     free(ftdi);
 225 }
 226
 227 /**
 228     Use an already open libusb device.
 229
 230     \param ftdi pointer to ftdi_context
 231     \param usb libusb usb_dev_handle to use
 232 */
 233 void ftdi_set_usbdev (struct ftdi_context *ftdi, usb_dev_handle *usb)
 234 {
 235     ftdi->usb_dev = usb;
 236 }
 237
 238
 239 /**
 240     Finds all ftdi devices on the usb bus. Creates a new ftdi_device_list which
 241     needs to be deallocated by ftdi_list_free() after use.
 242
 243     \param ftdi pointer to ftdi_context
 244     \param devlist Pointer where to store list of found devices
 245     \param vendor Vendor ID to search for
 246     \param product Product ID to search for
 247
 248     \retval >0: number of devices found
 249     \retval -1: usb_find_busses() failed
 250     \retval -2: usb_find_devices() failed
 251     \retval -3: out of memory
 252 */
 253 int ftdi_usb_find_all(struct ftdi_context *ftdi, struct ftdi_device_list **devlist, int vendor, int product)
 254 {
 255     struct ftdi_device_list **curdev;
 256     struct usb_bus *bus;
 257     struct usb_device *dev;
 258     int count = 0;
 259
 260     usb_init();
 261     if (usb_find_busses() < 0)
 262         ftdi_error_return(-1, "usb_find_busses() failed");
 263     if (usb_find_devices() < 0)
 264         ftdi_error_return(-2, "usb_find_devices() failed");
 265
 266     curdev = devlist;
 267     *curdev = NULL;
 268     for (bus = usb_get_busses(); bus; bus = bus->next)
 269     {
 270         for (dev = bus->devices; dev; dev = dev->next)
 271         {
 272             if (dev->descriptor.idVendor == vendor
 273                     && dev->descriptor.idProduct == product)
 274             {
 275                 *curdev = (struct ftdi_device_list*)malloc(sizeof(struct ftdi_device_list));
 276                 if (!*curdev)
 277                     ftdi_error_return(-3, "out of memory");
 278
 279                 (*curdev)->next = NULL;
 280                 (*curdev)->dev = dev;
 281
 282                 curdev = &(*curdev)->next;
 283                 count++;
 284             }
 285         }
 286     }
 287
 288     return count;
 289 }
 290
 291 /**
 292     Frees a usb device list.
 293
 294     \param devlist USB device list created by ftdi_usb_find_all()
 295 */
 296 void ftdi_list_free(struct ftdi_device_list **devlist)
 297 {
 298     struct ftdi_device_list *curdev, *next;
 299
 300     for (curdev = *devlist; curdev != NULL;)
 301     {
 302         next = curdev->next;
 303         free(curdev);
 304         curdev = next;
 305     }
 306
 307     *devlist = NULL;
 308 }
 309
 310 /**
 311     Frees a usb device list.
 312
 313     \param devlist USB device list created by ftdi_usb_find_all()
 314 */
 315 void ftdi_list_free2(struct ftdi_device_list *devlist)
 316 {
 317     ftdi_list_free(&devlist);
 318 }
 319
 320 /**
 321     Return device ID strings from the usb device.
 322
 323     The parameters manufacturer, description and serial may be NULL
 324     or pointer to buffers to store the fetched strings.
 325
 326     \note Use this function only in combination with ftdi_usb_find_all()
 327           as it closes the internal "usb_dev" after use.
 328
 329     \param ftdi pointer to ftdi_context
 330     \param dev libusb usb_dev to use
 331     \param manufacturer Store manufacturer string here if not NULL
 332     \param mnf_len Buffer size of manufacturer string
 333     \param description Store product description string here if not NULL
 334     \param desc_len Buffer size of product description string
 335     \param serial Store serial string here if not NULL
 336     \param serial_len Buffer size of serial string
 337
 338     \retval   0: all fine
 339     \retval  -1: wrong arguments
 340     \retval  -4: unable to open device
 341     \retval  -7: get product manufacturer failed
 342     \retval  -8: get product description failed
 343     \retval  -9: get serial number failed
 344     \retval -10: unable to close device
 345 */
 346 int ftdi_usb_get_strings(struct ftdi_context * ftdi, struct usb_device * dev,
 347                          char * manufacturer, int mnf_len, char * description, int desc_len, char * serial, int serial_len)
 348 {
 349     if ((ftdi==NULL) || (dev==NULL))
 350         return -1;
 351
 352     if (!(ftdi->usb_dev = usb_open(dev)))
 353         ftdi_error_return(-4, usb_strerror());
 354
 355     if (manufacturer != NULL)
 356     {
 357         if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iManufacturer, manufacturer, mnf_len) <= 0)
 358         {
 359             ftdi_usb_close_internal (ftdi);
 360             ftdi_error_return(-7, usb_strerror());
 361         }
 362     }
 363
 364     if (description != NULL)
 365     {
 366         if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, description, desc_len) <= 0)
 367         {
 368             ftdi_usb_close_internal (ftdi);
 369             ftdi_error_return(-8, usb_strerror());
 370         }
 371     }
 372
 373     if (serial != NULL)
 374     {
 375         if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, serial, serial_len) <= 0)
 376         {
 377             ftdi_usb_close_internal (ftdi);
 378             ftdi_error_return(-9, usb_strerror());
 379         }
 380     }
 381
 382     if (ftdi_usb_close_internal (ftdi) != 0)
 383         ftdi_error_return(-10, usb_strerror());
 384
 385     return 0;
 386 }
 387
 388 /**
 389  * Internal function to determine the maximum packet size.
 390  * \param ftdi pointer to ftdi_context
 391  * \param dev libusb usb_dev to use
 392  * \retval Maximum packet size for this device
 393  */
 394 static unsigned int _ftdi_determine_max_packet_size(struct ftdi_context *ftdi, struct usb_device *dev)
 395 {
 396     unsigned int packet_size;
 397
 398     // Determine maximum packet size. Init with default value.
 399     // New hi-speed devices from FTDI use a packet size of 512 bytes
 400     // but could be connected to a normal speed USB hub -> 64 bytes packet size.
 401     if (ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
 402         packet_size = 512;
 403     else
 404         packet_size = 64;
 405
 406     if (dev->descriptor.bNumConfigurations > 0 && dev->config)
 407     {
 408         struct usb_config_descriptor config = dev->config[0];
 409
 410         if (ftdi->interface < config.bNumInterfaces)
 411         {
 412             struct usb_interface interface = config.interface[ftdi->interface];
 413             if (interface.num_altsetting > 0)
 414             {
 415                 struct usb_interface_descriptor descriptor = interface.altsetting[0];
 416                 if (descriptor.bNumEndpoints > 0)
 417                 {
 418                     packet_size = descriptor.endpoint[0].wMaxPacketSize;
 419                 }
 420             }
 421         }
 422     }
 423
 424     return packet_size;
 425 }
 426
 427 /**
 428     Opens a ftdi device given by a usb_device.
 429
 430     \param ftdi pointer to ftdi_context
 431     \param dev libusb usb_dev to use
 432
 433     \retval  0: all fine
 434     \retval -3: unable to config device
 435     \retval -4: unable to open device
 436     \retval -5: unable to claim device
 437     \retval -6: reset failed
 438     \retval -7: set baudrate failed
 439 */
 440 int ftdi_usb_open_dev(struct ftdi_context *ftdi, struct usb_device *dev)
 441 {
 442     int detach_errno = 0;
 443     int config_val = 1;
 444     if (!(ftdi->usb_dev = usb_open(dev)))
 445         ftdi_error_return(-4, "usb_open() failed");
 446
 447 #ifdef LIBUSB_HAS_GET_DRIVER_NP
 448     // Try to detach ftdi_sio kernel module.
 449     // Returns ENODATA if driver is not loaded.
 450     //
 451     // The return code is kept in a separate variable and only parsed
 452     // if usb_set_configuration() or usb_claim_interface() fails as the
 453     // detach operation might be denied and everything still works fine.
 454     // Likely scenario is a static ftdi_sio kernel module.
 455     if (usb_detach_kernel_driver_np(ftdi->usb_dev, ftdi->interface) != 0 && errno != ENODATA)
 456         detach_errno = errno;
 457 #endif
 458
 459 #ifdef __WIN32__
 460     // set configuration (needed especially for windows)
 461     // tolerate EBUSY: one device with one configuration, but two interfaces
 462     //    and libftdi sessions to both interfaces (e.g. FT2232)
 463
 464     if (dev->descriptor.bNumConfigurations > 0)
 465     {
 466         // libusb-win32 on Windows 64 can return a null pointer for a valid device
 467         if (dev->config)
 468             config_val = dev->config[0].bConfigurationValue;
 469
 470         if (usb_set_configuration(ftdi->usb_dev, config_val) &&
 471             errno != EBUSY)
 472         {
 473             ftdi_usb_close_internal (ftdi);
 474             if (detach_errno == EPERM)
 475             {
 476                 ftdi_error_return(-8, "inappropriate permissions on device!");
 477             }
 478             else
 479             {
 480                 ftdi_error_return(-3, "unable to set usb configuration. Make sure ftdi_sio is unloaded!");
 481             }
 482         }
 483     }
 484 #endif
 485
 486     if (usb_claim_interface(ftdi->usb_dev, ftdi->interface) != 0)
 487     {
 488         ftdi_usb_close_internal (ftdi);
 489         if (detach_errno == EPERM)
 490         {
 491             ftdi_error_return(-8, "inappropriate permissions on device!");
 492         }
 493         else
 494         {
 495             ftdi_error_return(-5, "unable to claim usb device. Make sure ftdi_sio is unloaded!");
 496         }
 497     }
 498
 499     if (ftdi_usb_reset (ftdi) != 0)
 500     {
 501         ftdi_usb_close_internal (ftdi);
 502         ftdi_error_return(-6, "ftdi_usb_reset failed");
 503     }
 504
 505     // Try to guess chip type
 506     // Bug in the BM type chips: bcdDevice is 0x200 for serial == 0
 507     if (dev->descriptor.bcdDevice == 0x400 || (dev->descriptor.bcdDevice == 0x200
 508             && dev->descriptor.iSerialNumber == 0))
 509         ftdi->type = TYPE_BM;
 510     else if (dev->descriptor.bcdDevice == 0x200)
 511         ftdi->type = TYPE_AM;
 512     else if (dev->descriptor.bcdDevice == 0x500)
 513         ftdi->type = TYPE_2232C;
 514     else if (dev->descriptor.bcdDevice == 0x600)
 515         ftdi->type = TYPE_R;
 516     else if (dev->descriptor.bcdDevice == 0x700)
 517         ftdi->type = TYPE_2232H;
 518     else if (dev->descriptor.bcdDevice == 0x800)
 519         ftdi->type = TYPE_4232H;
 520
 521     // Set default interface on dual/quad type chips
 522     switch(ftdi->type)
 523     {
 524         case TYPE_2232C:
 525         case TYPE_2232H:
 526         case TYPE_4232H:
 527             if (!ftdi->index)
 528                 ftdi->index = INTERFACE_A;
 529             break;
 530         default:
 531             break;
 532     }
 533
 534     // Determine maximum packet size
 535     ftdi->max_packet_size = _ftdi_determine_max_packet_size(ftdi, dev);
 536
 537     if (ftdi_set_baudrate (ftdi, 9600) != 0)
 538     {
 539         ftdi_usb_close_internal (ftdi);
 540         ftdi_error_return(-7, "set baudrate failed");
 541     }
 542
 543     ftdi_error_return(0, "all fine");
 544 }
 545
 546 /**
 547     Opens the first device with a given vendor and product ids.
 548
 549     \param ftdi pointer to ftdi_context
 550     \param vendor Vendor ID
 551     \param product Product ID
 552
 553     \retval same as ftdi_usb_open_desc()
 554 */
 555 int ftdi_usb_open(struct ftdi_context *ftdi, int vendor, int product)
 556 {
 557     return ftdi_usb_open_desc(ftdi, vendor, product, NULL, NULL);
 558 }
 559
 560 /**
 561     Opens the first device with a given, vendor id, product id,
 562     description and serial.
 563
 564     \param ftdi pointer to ftdi_context
 565     \param vendor Vendor ID
 566     \param product Product ID
 567     \param description Description to search for. Use NULL if not needed.
 568     \param serial Serial to search for. Use NULL if not needed.
 569
 570     \retval  0: all fine
 571     \retval -1: usb_find_busses() failed
 572     \retval -2: usb_find_devices() failed
 573     \retval -3: usb device not found
 574     \retval -4: unable to open device
 575     \retval -5: unable to claim device
 576     \retval -6: reset failed
 577     \retval -7: set baudrate failed
 578     \retval -8: get product description failed
 579     \retval -9: get serial number failed
 580     \retval -10: unable to close device
 581 */
 582 int ftdi_usb_open_desc(struct ftdi_context *ftdi, int vendor, int product,
 583                        const char* description, const char* serial)
 584 {
 585     return ftdi_usb_open_desc_index(ftdi,vendor,product,description,serial,0);
 586 }
 587
 588 /**
 589     Opens the index-th device with a given, vendor id, product id,
 590     description and serial.
 591
 592     \param ftdi pointer to ftdi_context
 593     \param vendor Vendor ID
 594     \param product Product ID
 595     \param description Description to search for. Use NULL if not needed.
 596     \param serial Serial to search for. Use NULL if not needed.
 597     \param index Number of matching device to open if there are more than one, starts with 0.
 598
 599     \retval  0: all fine
 600     \retval -1: usb_find_busses() failed
 601     \retval -2: usb_find_devices() failed
 602     \retval -3: usb device not found
 603     \retval -4: unable to open device
 604     \retval -5: unable to claim device
 605     \retval -6: reset failed
 606     \retval -7: set baudrate failed
 607     \retval -8: get product description failed
 608     \retval -9: get serial number failed
 609     \retval -10: unable to close device
 610 */
 611 int ftdi_usb_open_desc_index(struct ftdi_context *ftdi, int vendor, int product,
 612                        const char* description, const char* serial, unsigned int index)
 613 {
 614     struct usb_bus *bus;
 615     struct usb_device *dev;
 616     char string[256];
 617
 618     usb_init();
 619
 620     if (usb_find_busses() < 0)
 621         ftdi_error_return(-1, "usb_find_busses() failed");
 622     if (usb_find_devices() < 0)
 623         ftdi_error_return(-2, "usb_find_devices() failed");
 624
 625     for (bus = usb_get_busses(); bus; bus = bus->next)
 626     {
 627         for (dev = bus->devices; dev; dev = dev->next)
 628         {
 629             if (dev->descriptor.idVendor == vendor
 630                     && dev->descriptor.idProduct == product)
 631             {
 632                 if (!(ftdi->usb_dev = usb_open(dev)))
 633                     ftdi_error_return(-4, "usb_open() failed");
 634
 635                 if (description != NULL)
 636                 {
 637                     if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, string, sizeof(string)) <= 0)
 638                     {
 639                         ftdi_usb_close_internal (ftdi);
 640                         ftdi_error_return(-8, "unable to fetch product description");
 641                     }
 642                     if (strncmp(string, description, sizeof(string)) != 0)
 643                     {
 644                         if (ftdi_usb_close_internal (ftdi) != 0)
 645                             ftdi_error_return(-10, "unable to close device");
 646                         continue;
 647                     }
 648                 }
 649                 if (serial != NULL)
 650                 {
 651                     if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, string, sizeof(string)) <= 0)
 652                     {
 653                         ftdi_usb_close_internal (ftdi);
 654                         ftdi_error_return(-9, "unable to fetch serial number");
 655                     }
 656                     if (strncmp(string, serial, sizeof(string)) != 0)
 657                     {
 658                         if (ftdi_usb_close_internal (ftdi) != 0)
 659                             ftdi_error_return(-10, "unable to close device");
 660                         continue;
 661                     }
 662                 }
 663
 664                 if (ftdi_usb_close_internal (ftdi) != 0)
 665                     ftdi_error_return(-10, "unable to close device");
 666
 667                 if (index > 0)
 668                 {
 669                     index--;
 670                     continue;
 671                 }
 672
 673                 return ftdi_usb_open_dev(ftdi, dev);
 674             }
 675         }
 676     }
 677
 678     // device not found
 679     ftdi_error_return(-3, "device not found");
 680 }
 681
 682 /**
 683     Opens the ftdi-device described by a description-string.
 684     Intended to be used for parsing a device-description given as commandline argument.
 685
 686     \param ftdi pointer to ftdi_context
 687     \param description NULL-terminated description-string, using this format:
 688         \li <tt>d:\<devicenode></tt> path of bus and device-node (e.g. "003/001") within usb device tree (usually at /proc/bus/usb/)
 689         \li <tt>i:\<vendor>:\<product></tt> first device with given vendor and product id, ids can be decimal, octal (preceded by "0") or hex (preceded by "0x")
 690         \li <tt>i:\<vendor>:\<product>:\<index></tt> as above with index being the number of the device (starting with 0) if there are more than one
 691         \li <tt>s:\<vendor>:\<product>:\<serial></tt> first device with given vendor id, product id and serial string
 692
 693     \note The description format may be extended in later versions.
 694
 695     \retval  0: all fine
 696     \retval -1: usb_find_busses() failed
 697     \retval -2: usb_find_devices() failed
 698     \retval -3: usb device not found
 699     \retval -4: unable to open device
 700     \retval -5: unable to claim device
 701     \retval -6: reset failed
 702     \retval -7: set baudrate failed
 703     \retval -8: get product description failed
 704     \retval -9: get serial number failed
 705     \retval -10: unable to close device
 706     \retval -11: illegal description format
 707 */
 708 int ftdi_usb_open_string(struct ftdi_context *ftdi, const char* description)
 709 {
 710     if (description[0] == 0 || description[1] != ':')
 711         ftdi_error_return(-11, "illegal description format");
 712
 713     if (description[0] == 'd')
 714     {
 715         struct usb_bus *bus;
 716         struct usb_device *dev;
 717         char dev_name[PATH_MAX+1];
 718
 719         usb_init();
 720
 721         if (usb_find_busses() < 0)
 722             ftdi_error_return(-1, "usb_find_busses() failed");
 723         if (usb_find_devices() < 0)
 724             ftdi_error_return(-2, "usb_find_devices() failed");
 725
 726         for (bus = usb_get_busses(); bus; bus = bus->next)
 727         {
 728             for (dev = bus->devices; dev; dev = dev->next)
 729             {
 730                 snprintf(dev_name, sizeof(dev_name), "%s/%s",bus->dirname,dev->filename);
 731                 if (strcmp(description+2,dev_name) == 0)
 732                     return ftdi_usb_open_dev(ftdi, dev);
 733             }
 734         }
 735
 736         // device not found
 737         ftdi_error_return(-3, "device not found");
 738     }
 739     else if (description[0] == 'i' || description[0] == 's')
 740     {
 741         unsigned int vendor;
 742         unsigned int product;
 743         unsigned int index=0;
 744         const char *serial=NULL;
 745         const char *startp, *endp;
 746
 747         errno=0;
 748         startp=description+2;
 749         vendor=strtoul((char*)startp,(char**)&endp,0);
 750         if (*endp != ':' || endp == startp || errno != 0)
 751             ftdi_error_return(-11, "illegal description format");
 752
 753         startp=endp+1;
 754         product=strtoul((char*)startp,(char**)&endp,0);
 755         if (endp == startp || errno != 0)
 756             ftdi_error_return(-11, "illegal description format");
 757
 758         if (description[0] == 'i' && *endp != 0)
 759         {
 760             /* optional index field in i-mode */
 761             if (*endp != ':')
 762                 ftdi_error_return(-11, "illegal description format");
 763
 764             startp=endp+1;
 765             index=strtoul((char*)startp,(char**)&endp,0);
 766             if (*endp != 0 || endp == startp || errno != 0)
 767                 ftdi_error_return(-11, "illegal description format");
 768         }
 769         if (description[0] == 's')
 770         {
 771             if (*endp != ':')
 772                 ftdi_error_return(-11, "illegal description format");
 773
 774             /* rest of the description is the serial */
 775             serial=endp+1;
 776         }
 777
 778         return ftdi_usb_open_desc_index(ftdi, vendor, product, NULL, serial, index);
 779     }
 780     else
 781     {
 782         ftdi_error_return(-11, "illegal description format");
 783     }
 784 }
 785
 786 /**
 787     Resets the ftdi device.
 788
 789     \param ftdi pointer to ftdi_context
 790
 791     \retval  0: all fine
 792     \retval -1: FTDI reset failed
 793 */
 794 int ftdi_usb_reset(struct ftdi_context *ftdi)
 795 {
 796     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
 797                         SIO_RESET_REQUEST, SIO_RESET_SIO,
 798                         ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
 799         ftdi_error_return(-1,"FTDI reset failed");
 800
 801     // Invalidate data in the readbuffer
 802     ftdi->readbuffer_offset = 0;
 803     ftdi->readbuffer_remaining = 0;
 804
 805     return 0;
 806 }
 807
 808 /**
 809     Clears the read buffer on the chip and the internal read buffer.
 810
 811     \param ftdi pointer to ftdi_context
 812
 813     \retval  0: all fine
 814     \retval -1: read buffer purge failed
 815 */
 816 int ftdi_usb_purge_rx_buffer(struct ftdi_context *ftdi)
 817 {
 818     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
 819                         SIO_RESET_REQUEST, SIO_RESET_PURGE_RX,
 820                         ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
 821         ftdi_error_return(-1, "FTDI purge of RX buffer failed");
 822
 823     // Invalidate data in the readbuffer
 824     ftdi->readbuffer_offset = 0;
 825     ftdi->readbuffer_remaining = 0;
 826
 827     return 0;
 828 }
 829
 830 /**
 831     Clears the write buffer on the chip.
 832
 833     \param ftdi pointer to ftdi_context
 834
 835     \retval  0: all fine
 836     \retval -1: write buffer purge failed
 837 */
 838 int ftdi_usb_purge_tx_buffer(struct ftdi_context *ftdi)
 839 {
 840     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
 841                         SIO_RESET_REQUEST, SIO_RESET_PURGE_TX,
 842                         ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
 843         ftdi_error_return(-1, "FTDI purge of TX buffer failed");
 844
 845     return 0;
 846 }
 847
 848 /**
 849     Clears the buffers on the chip and the internal read buffer.
 850
 851     \param ftdi pointer to ftdi_context
 852
 853     \retval  0: all fine
 854     \retval -1: read buffer purge failed
 855     \retval -2: write buffer purge failed
 856 */
 857 int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
 858 {
 859     int result;
 860
 861     result = ftdi_usb_purge_rx_buffer(ftdi);
 862     if (result < 0)
 863         return -1;
 864
 865     result = ftdi_usb_purge_tx_buffer(ftdi);
 866     if (result < 0)
 867         return -2;
 868
 869     return 0;
 870 }
 871
 872
 873
 874 /**
 875     Closes the ftdi device. Call ftdi_deinit() if you're cleaning up.
 876
 877     \param ftdi pointer to ftdi_context
 878
 879     \retval  0: all fine
 880     \retval -1: usb_release failed
 881     \retval -2: usb_close failed
 882 */
 883 int ftdi_usb_close(struct ftdi_context *ftdi)
 884 {
 885     int rtn = 0;
 886
 887 #ifdef LIBFTDI_LINUX_ASYNC_MODE
 888     /* try to release some kernel resources */
 889     ftdi_async_complete(ftdi,1);
 890 #endif
 891
 892     if (ftdi->usb_dev != NULL)
 893         if (usb_release_interface(ftdi->usb_dev, ftdi->interface) != 0)
 894             rtn = -1;
 895
 896     if (ftdi_usb_close_internal (ftdi) != 0)
 897         rtn = -2;
 898
 899     return rtn;
 900 }
 901
 902 /*
 903     ftdi_convert_baudrate returns nearest supported baud rate to that requested.
 904     Function is only used internally
 905     \internal
 906 */
 907 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
 908                                  unsigned short *value, unsigned short *index)
 909 {
 910     static const char am_adjust_up[8] = {0, 0, 0, 1, 0, 3, 2, 1};
 911     static const char am_adjust_dn[8] = {0, 0, 0, 1, 0, 1, 2, 3};
 912     static const char frac_code[8] = {0, 3, 2, 4, 1, 5, 6, 7};
 913     int divisor, best_divisor, best_baud, best_baud_diff;
 914     unsigned long encoded_divisor;
 915     int i;
 916
 917     if (baudrate <= 0)
 918     {
 919         // Return error
 920         return -1;
 921     }
 922
 923     divisor = 24000000 / baudrate;
 924
 925     if (ftdi->type == TYPE_AM)
 926     {
 927         // Round down to supported fraction (AM only)
 928         divisor -= am_adjust_dn[divisor & 7];
 929     }
 930
 931     // Try this divisor and the one above it (because division rounds down)
 932     best_divisor = 0;
 933     best_baud = 0;
 934     best_baud_diff = 0;
 935     for (i = 0; i < 2; i++)
 936     {
 937         int try_divisor = divisor + i;
 938         int baud_estimate;
 939         int baud_diff;
 940
 941         // Round up to supported divisor value
 942         if (try_divisor <= 8)
 943         {
 944             // Round up to minimum supported divisor
 945             try_divisor = 8;
 946         }
 947         else if (ftdi->type != TYPE_AM && try_divisor < 12)
 948         {
 949             // BM doesn't support divisors 9 through 11 inclusive
 950             try_divisor = 12;
 951         }
 952         else if (divisor < 16)
 953         {
 954             // AM doesn't support divisors 9 through 15 inclusive
 955             try_divisor = 16;
 956         }
 957         else
 958         {
 959             if (ftdi->type == TYPE_AM)
 960             {
 961                 // Round up to supported fraction (AM only)
 962                 try_divisor += am_adjust_up[try_divisor & 7];
 963                 if (try_divisor > 0x1FFF8)
 964                 {
 965                     // Round down to maximum supported divisor value (for AM)
 966                     try_divisor = 0x1FFF8;
 967                 }
 968             }
 969             else
 970             {
 971                 if (try_divisor > 0x1FFFF)
 972                 {
 973                     // Round down to maximum supported divisor value (for BM)
 974                     try_divisor = 0x1FFFF;
 975                 }
 976             }
 977         }
 978         // Get estimated baud rate (to nearest integer)
 979         baud_estimate = (24000000 + (try_divisor / 2)) / try_divisor;
 980         // Get absolute difference from requested baud rate
 981         if (baud_estimate < baudrate)
 982         {
 983             baud_diff = baudrate - baud_estimate;
 984         }
 985         else
 986         {
 987             baud_diff = baud_estimate - baudrate;
 988         }
 989         if (i == 0 || baud_diff < best_baud_diff)
 990         {
 991             // Closest to requested baud rate so far
 992             best_divisor = try_divisor;
 993             best_baud = baud_estimate;
 994             best_baud_diff = baud_diff;
 995             if (baud_diff == 0)
 996             {
 997                 // Spot on! No point trying
 998                 break;
 999             }
1000         }
1001     }
1002     // Encode the best divisor value
1003     encoded_divisor = (best_divisor >> 3) | (frac_code[best_divisor & 7] << 14);
1004     // Deal with special cases for encoded value
1005     if (encoded_divisor == 1)
1006     {
1007         encoded_divisor = 0;    // 3000000 baud
1008     }
1009     else if (encoded_divisor == 0x4001)
1010     {
1011         encoded_divisor = 1;    // 2000000 baud (BM only)
1012     }
1013     // Split into "value" and "index" values
1014     *value = (unsigned short)(encoded_divisor & 0xFFFF);
1015     if (ftdi->type == TYPE_2232C || ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
1016     {
1017         *index = (unsigned short)(encoded_divisor >> 8);
1018         *index &= 0xFF00;
1019         *index |= ftdi->index;
1020     }
1021     else
1022         *index = (unsigned short)(encoded_divisor >> 16);
1023
1024     // Return the nearest baud rate
1025     return best_baud;
1026 }
1027
1028 /**
1029     Sets the chip baud rate
1030
1031     \param ftdi pointer to ftdi_context
1032     \param baudrate baud rate to set
1033
1034     \retval  0: all fine
1035     \retval -1: invalid baudrate
1036     \retval -2: setting baudrate failed
1037 */
1038 int ftdi_set_baudrate(struct ftdi_context *ftdi, int baudrate)
1039 {
1040     unsigned short value, index;
1041     int actual_baudrate;
1042
1043     if (ftdi->bitbang_enabled)
1044     {
1045         baudrate = baudrate*4;
1046     }
1047
1048     actual_baudrate = ftdi_convert_baudrate(baudrate, ftdi, &value, &index);
1049     if (actual_baudrate <= 0)
1050         ftdi_error_return (-1, "Silly baudrate <= 0.");
1051
1052     // Check within tolerance (about 5%)
1053     if ((actual_baudrate * 2 < baudrate /* Catch overflows */ )
1054             || ((actual_baudrate < baudrate)
1055                 ? (actual_baudrate * 21 < baudrate * 20)
1056                 : (baudrate * 21 < actual_baudrate * 20)))
1057         ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
1058
1059     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1060                         SIO_SET_BAUDRATE_REQUEST, value,
1061                         index, NULL, 0, ftdi->usb_write_timeout) != 0)
1062         ftdi_error_return (-2, "Setting new baudrate failed");
1063
1064     ftdi->baudrate = baudrate;
1065     return 0;
1066 }
1067
1068 /**
1069     Set (RS232) line characteristics.
1070     The break type can only be set via ftdi_set_line_property2()
1071     and defaults to "off".
1072
1073     \param ftdi pointer to ftdi_context
1074     \param bits Number of bits
1075     \param sbit Number of stop bits
1076     \param parity Parity mode
1077
1078     \retval  0: all fine
1079     \retval -1: Setting line property failed
1080 */
1081 int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1082                            enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
1083 {
1084     return ftdi_set_line_property2(ftdi, bits, sbit, parity, BREAK_OFF);
1085 }
1086
1087 /**
1088     Set (RS232) line characteristics
1089
1090     \param ftdi pointer to ftdi_context
1091     \param bits Number of bits
1092     \param sbit Number of stop bits
1093     \param parity Parity mode
1094     \param break_type Break type
1095
1096     \retval  0: all fine
1097     \retval -1: Setting line property failed
1098 */
1099 int ftdi_set_line_property2(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1100                             enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity,
1101                             enum ftdi_break_type break_type)
1102 {
1103     unsigned short value = bits;
1104
1105     switch (parity)
1106     {
1107         case NONE:
1108             value |= (0x00 << 8);
1109             break;
1110         case ODD:
1111             value |= (0x01 << 8);
1112             break;
1113         case EVEN:
1114             value |= (0x02 << 8);
1115             break;
1116         case MARK:
1117             value |= (0x03 << 8);
1118             break;
1119         case SPACE:
1120             value |= (0x04 << 8);
1121             break;
1122     }
1123
1124     switch (sbit)
1125     {
1126         case STOP_BIT_1:
1127             value |= (0x00 << 11);
1128             break;
1129         case STOP_BIT_15:
1130             value |= (0x01 << 11);
1131             break;
1132         case STOP_BIT_2:
1133             value |= (0x02 << 11);
1134             break;
1135     }
1136
1137     switch (break_type)
1138     {
1139         case BREAK_OFF:
1140             value |= (0x00 << 14);
1141             break;
1142         case BREAK_ON:
1143             value |= (0x01 << 14);
1144             break;
1145     }
1146
1147     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1148                         SIO_SET_DATA_REQUEST, value,
1149                         ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1150         ftdi_error_return (-1, "Setting new line property failed");
1151
1152     return 0;
1153 }
1154
1155 /**
1156     Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip
1157
1158     \param ftdi pointer to ftdi_context
1159     \param buf Buffer with the data
1160     \param size Size of the buffer
1161
1162     \retval <0: error code from usb_bulk_write()
1163     \retval >0: number of bytes written
1164 */
1165 int ftdi_write_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1166 {
1167     int ret;
1168     int offset = 0;
1169     int total_written = 0;
1170
1171     while (offset < size)
1172     {
1173         int write_size = ftdi->writebuffer_chunksize;
1174
1175         if (offset+write_size > size)
1176             write_size = size-offset;
1177
1178         ret = usb_bulk_write(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size, ftdi->usb_write_timeout);
1179         if (ret < 0)
1180             ftdi_error_return(ret, "usb bulk write failed");
1181
1182         total_written += ret;
1183         offset += write_size;
1184     }
1185
1186     return total_written;
1187 }
1188
1189 #ifdef LIBFTDI_LINUX_ASYNC_MODE
1190 #ifdef USB_CLASS_PTP
1191 #error LIBFTDI_LINUX_ASYNC_MODE is not compatible with libusb-compat-0.1!
1192 #endif
1193 /* this is strongly dependent on libusb using the same struct layout. If libusb
1194    changes in some later version this may break horribly (this is for libusb 0.1.12) */
1195 struct usb_dev_handle
1196 {
1197     int fd;
1198     // some other stuff coming here we don't need
1199 };
1200
1201 /**
1202     Check for pending async urbs
1203     \internal
1204 */
1205 static int _usb_get_async_urbs_pending(struct ftdi_context *ftdi)
1206 {
1207     struct usbdevfs_urb *urb;
1208     int pending=0;
1209     unsigned int i;
1210
1211     for (i=0; i < ftdi->async_usb_buffer_size; i++)
1212     {
1213         urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1214         if (urb->usercontext != FTDI_URB_USERCONTEXT_COOKIE)
1215             pending++;
1216     }
1217
1218     return pending;
1219 }
1220
1221 /**
1222     Wait until one or more async URBs are completed by the kernel and mark their
1223     positions in the async-buffer as unused
1224
1225     \param ftdi pointer to ftdi_context
1226     \param wait_for_more if != 0 wait for more than one write to complete
1227     \param timeout_msec max milliseconds to wait
1228
1229     \internal
1230 */
1231 static void _usb_async_cleanup(struct ftdi_context *ftdi, int wait_for_more, int timeout_msec)
1232 {
1233     struct timeval tv;
1234     struct usbdevfs_urb *urb=NULL;
1235     int ret;
1236     fd_set writefds;
1237     int keep_going=0;
1238
1239     FD_ZERO(&writefds);
1240     FD_SET(ftdi->usb_dev->fd, &writefds);
1241
1242     /* init timeout only once, select writes time left after call */
1243     tv.tv_sec = timeout_msec / 1000;
1244     tv.tv_usec = (timeout_msec % 1000) * 1000;
1245
1246     do
1247     {
1248         while (_usb_get_async_urbs_pending(ftdi)
1249                 && (ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_REAPURBNDELAY, &urb)) == -1
1250                 && errno == EAGAIN)
1251         {
1252             if (keep_going && !wait_for_more)
1253             {
1254                 /* don't wait if repeating only for keep_going */
1255                 keep_going=0;
1256                 break;
1257             }
1258
1259             /* wait for timeout msec or something written ready */
1260             select(ftdi->usb_dev->fd+1, NULL, &writefds, NULL, &tv);
1261         }
1262
1263         if (ret == 0 && urb != NULL)
1264         {
1265             /* got a free urb, mark it */
1266             urb->usercontext = FTDI_URB_USERCONTEXT_COOKIE;
1267
1268             /* try to get more urbs that are ready now, but don't wait anymore */
1269             urb=NULL;
1270             keep_going=1;
1271         }
1272         else
1273         {
1274             /* no more urbs waiting */
1275             keep_going=0;
1276         }
1277     }
1278     while (keep_going);
1279 }
1280
1281 /**
1282     Wait until one or more async URBs are completed by the kernel and mark their
1283     positions in the async-buffer as unused.
1284
1285     \param ftdi pointer to ftdi_context
1286     \param wait_for_more if != 0 wait for more than one write to complete (until write timeout)
1287 */
1288 void ftdi_async_complete(struct ftdi_context *ftdi, int wait_for_more)
1289 {
1290     _usb_async_cleanup(ftdi,wait_for_more,ftdi->usb_write_timeout);
1291 }
1292
1293 /**
1294     Stupid libusb does not offer async writes nor does it allow
1295     access to its fd - so we need some hacks here.
1296     \internal
1297 */
1298 static int _usb_bulk_write_async(struct ftdi_context *ftdi, int ep, char *bytes, int size)
1299 {
1300     struct usbdevfs_urb *urb;
1301     int bytesdone = 0, requested;
1302     int ret, cleanup_count;
1303     unsigned int i;
1304
1305     do
1306     {
1307         /* find a free urb buffer we can use */
1308         urb=NULL;
1309         for (cleanup_count=0; urb==NULL && cleanup_count <= 1; cleanup_count++)
1310         {
1311             if (i==ftdi->async_usb_buffer_size)
1312             {
1313                 /* wait until some buffers are free */
1314                 _usb_async_cleanup(ftdi,0,ftdi->usb_write_timeout);
1315             }
1316
1317             for (i=0; i < ftdi->async_usb_buffer_size; i++)
1318             {
1319                 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1320                 if (urb->usercontext == FTDI_URB_USERCONTEXT_COOKIE)
1321                     break;  /* found a free urb position */
1322                 urb=NULL;
1323             }
1324         }
1325
1326         /* no free urb position found */
1327         if (urb==NULL)
1328             return -1;
1329
1330         requested = size - bytesdone;
1331         if (requested > 4096)
1332             requested = 4096;
1333
1334         memset(urb,0,sizeof(urb));
1335
1336         urb->type = USBDEVFS_URB_TYPE_BULK;
1337         urb->endpoint = ep;
1338         urb->flags = 0;
1339         urb->buffer = bytes + bytesdone;
1340         urb->buffer_length = requested;
1341         urb->signr = 0;
1342         urb->actual_length = 0;
1343         urb->number_of_packets = 0;
1344         urb->usercontext = 0;
1345
1346         do
1347         {
1348             ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_SUBMITURB, urb);
1349         }
1350         while (ret < 0 && errno == EINTR);
1351         if (ret < 0)
1352             return ret;       /* the caller can read errno to get more info */
1353
1354         bytesdone += requested;
1355     }
1356     while (bytesdone < size);
1357     return bytesdone;
1358 }
1359
1360 /**
1361     Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip.
1362     Does not wait for completion of the transfer nor does it make sure that
1363     the transfer was successful.
1364
1365     This function could be extended to use signals and callbacks to inform the
1366     caller of completion or error - but this is not done yet, volunteers welcome.
1367
1368     Works around libusb and directly accesses functions only available on Linux.
1369     Only available if compiled with --with-async-mode.
1370
1371     \param ftdi pointer to ftdi_context
1372     \param buf Buffer with the data
1373     \param size Size of the buffer
1374
1375     \retval <0: error code from usb_bulk_write()
1376     \retval >0: number of bytes written
1377 */
1378 int ftdi_write_data_async(struct ftdi_context *ftdi, unsigned char *buf, int size)
1379 {
1380     int ret;
1381     int offset = 0;
1382     int total_written = 0;
1383
1384     while (offset < size)
1385     {
1386         int write_size = ftdi->writebuffer_chunksize;
1387
1388         if (offset+write_size > size)
1389             write_size = size-offset;
1390
1391         ret = _usb_bulk_write_async(ftdi, ftdi->in_ep, buf+offset, write_size);
1392         if (ret < 0)
1393             ftdi_error_return(ret, "usb bulk write async failed");
1394
1395         total_written += ret;
1396         offset += write_size;
1397     }
1398
1399     return total_written;
1400 }
1401 #endif // LIBFTDI_LINUX_ASYNC_MODE
1402
1403 /**
1404     Configure write buffer chunk size.
1405     Default is 4096.
1406
1407     \param ftdi pointer to ftdi_context
1408     \param chunksize Chunk size
1409
1410     \retval 0: all fine
1411 */
1412 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1413 {
1414     ftdi->writebuffer_chunksize = chunksize;
1415     return 0;
1416 }
1417
1418 /**
1419     Get write buffer chunk size.
1420
1421     \param ftdi pointer to ftdi_context
1422     \param chunksize Pointer to store chunk size in
1423
1424     \retval 0: all fine
1425 */
1426 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1427 {
1428     *chunksize = ftdi->writebuffer_chunksize;
1429     return 0;
1430 }
1431
1432 /**
1433     Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
1434
1435     Automatically strips the two modem status bytes transfered during every read.
1436
1437     \param ftdi pointer to ftdi_context
1438     \param buf Buffer to store data in
1439     \param size Size of the buffer
1440
1441     \retval <0: error code from usb_bulk_read()
1442     \retval  0: no data was available
1443     \retval >0: number of bytes read
1444
1445     \remark This function is not useful in bitbang mode.
1446             Use ftdi_read_pins() to get the current state of the pins.
1447 */
1448 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1449 {
1450     int offset = 0, ret = 1, i, num_of_chunks, chunk_remains;
1451     int packet_size = ftdi->max_packet_size;
1452
1453     // Packet size sanity check (avoid division by zero)
1454     if (packet_size == 0)
1455         ftdi_error_return(-1, "max_packet_size is bogus (zero)");
1456
1457     // everything we want is still in the readbuffer?
1458     if (size <= ftdi->readbuffer_remaining)
1459     {
1460         memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1461
1462         // Fix offsets
1463         ftdi->readbuffer_remaining -= size;
1464         ftdi->readbuffer_offset += size;
1465
1466         /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1467
1468         return size;
1469     }
1470     // something still in the readbuffer, but not enough to satisfy 'size'?
1471     if (ftdi->readbuffer_remaining != 0)
1472     {
1473         memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1474
1475         // Fix offset
1476         offset += ftdi->readbuffer_remaining;
1477     }
1478     // do the actual USB read
1479     while (offset < size && ret > 0)
1480     {
1481         ftdi->readbuffer_remaining = 0;
1482         ftdi->readbuffer_offset = 0;
1483         /* returns how much received */
1484         ret = usb_bulk_read (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, ftdi->usb_read_timeout);
1485         if (ret < 0)
1486             ftdi_error_return(ret, "usb bulk read failed");
1487
1488         if (ret > 2)
1489         {
1490             // skip FTDI status bytes.
1491             // Maybe stored in the future to enable modem use
1492             num_of_chunks = ret / packet_size;
1493             chunk_remains = ret % packet_size;
1494             //printf("ret = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", ret, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
1495
1496             ftdi->readbuffer_offset += 2;
1497             ret -= 2;
1498
1499             if (ret > packet_size - 2)
1500             {
1501                 for (i = 1; i < num_of_chunks; i++)
1502                     memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1503                              ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1504                              packet_size - 2);
1505                 if (chunk_remains > 2)
1506                 {
1507                     memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1508                              ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1509                              chunk_remains-2);
1510                     ret -= 2*num_of_chunks;
1511                 }
1512                 else
1513                     ret -= 2*(num_of_chunks-1)+chunk_remains;
1514             }
1515         }
1516         else if (ret <= 2)
1517         {
1518             // no more data to read?
1519             return offset;
1520         }
1521         if (ret > 0)
1522         {
1523             // data still fits in buf?
1524             if (offset+ret <= size)
1525             {
1526                 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, ret);
1527                 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1528                 offset += ret;
1529
1530                 /* Did we read exactly the right amount of bytes? */
1531                 if (offset == size)
1532                     //printf("read_data exact rem %d offset %d\n",
1533                     //ftdi->readbuffer_remaining, offset);
1534                     return offset;
1535             }
1536             else
1537             {
1538                 // only copy part of the data or size <= readbuffer_chunksize
1539                 int part_size = size-offset;
1540                 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
1541
1542                 ftdi->readbuffer_offset += part_size;
1543                 ftdi->readbuffer_remaining = ret-part_size;
1544                 offset += part_size;
1545
1546                 /* printf("Returning part: %d - size: %d - offset: %d - ret: %d - remaining: %d\n",
1547                 part_size, size, offset, ret, ftdi->readbuffer_remaining); */
1548
1549                 return offset;
1550             }
1551         }
1552     }
1553     // never reached
1554     return -127;
1555 }
1556
1557 /**
1558     Configure read buffer chunk size.
1559     Default is 4096.
1560
1561     Automatically reallocates the buffer.
1562
1563     \param ftdi pointer to ftdi_context
1564     \param chunksize Chunk size
1565
1566     \retval 0: all fine
1567 */
1568 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1569 {
1570     unsigned char *new_buf;
1571
1572     // Invalidate all remaining data
1573     ftdi->readbuffer_offset = 0;
1574     ftdi->readbuffer_remaining = 0;
1575
1576     if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
1577         ftdi_error_return(-1, "out of memory for readbuffer");
1578
1579     ftdi->readbuffer = new_buf;
1580     ftdi->readbuffer_chunksize = chunksize;
1581
1582     return 0;
1583 }
1584
1585 /**
1586     Get read buffer chunk size.
1587
1588     \param ftdi pointer to ftdi_context
1589     \param chunksize Pointer to store chunk size in
1590
1591     \retval 0: all fine
1592 */
1593 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1594 {
1595     *chunksize = ftdi->readbuffer_chunksize;
1596     return 0;
1597 }
1598
1599
1600 /**
1601     Enable bitbang mode.
1602
1603     For advanced bitbang modes of the FT2232C chip use ftdi_set_bitmode().
1604
1605     \param ftdi pointer to ftdi_context
1606     \param bitmask Bitmask to configure lines.
1607            HIGH/ON value configures a line as output.
1608
1609     \retval  0: all fine
1610     \retval -1: can't enable bitbang mode
1611 */
1612 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
1613 {
1614     unsigned short usb_val;
1615
1616     usb_val = bitmask; // low byte: bitmask
1617     /* FT2232C: Set bitbang_mode to 2 to enable SPI */
1618     usb_val |= (ftdi->bitbang_mode << 8);
1619
1620     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1621                         SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index,
1622                         NULL, 0, ftdi->usb_write_timeout) != 0)
1623         ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
1624
1625     ftdi->bitbang_enabled = 1;
1626     return 0;
1627 }
1628
1629 /**
1630     Disable bitbang mode.
1631
1632     \param ftdi pointer to ftdi_context
1633
1634     \retval  0: all fine
1635     \retval -1: can't disable bitbang mode
1636 */
1637 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
1638 {
1639     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_BITMODE_REQUEST, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1640         ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
1641
1642     ftdi->bitbang_enabled = 0;
1643     return 0;
1644 }
1645
1646 /**
1647     Enable advanced bitbang mode for FT2232C chips.
1648
1649     \param ftdi pointer to ftdi_context
1650     \param bitmask Bitmask to configure lines.
1651            HIGH/ON value configures a line as output.
1652     \param mode Bitbang mode: 1 for normal mode, 2 for SPI mode
1653
1654     \retval  0: all fine
1655     \retval -1: can't enable bitbang mode
1656 */
1657 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
1658 {
1659     unsigned short usb_val;
1660
1661     usb_val = bitmask; // low byte: bitmask
1662     usb_val |= (mode << 8);
1663     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1664         ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps not a 2232C type chip?");
1665
1666     ftdi->bitbang_mode = mode;
1667     ftdi->bitbang_enabled = (mode == BITMODE_BITBANG || mode == BITMODE_SYNCBB)?1:0;
1668     return 0;
1669 }
1670
1671 /**
1672     Directly read pin state. Useful for bitbang mode.
1673
1674     \param ftdi pointer to ftdi_context
1675     \param pins Pointer to store pins into
1676
1677     \retval  0: all fine
1678     \retval -1: read pins failed
1679 */
1680 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
1681 {
1682     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_PINS_REQUEST, 0, ftdi->index, (char *)pins, 1, ftdi->usb_read_timeout) != 1)
1683         ftdi_error_return(-1, "read pins failed");
1684
1685     return 0;
1686 }
1687
1688 /**
1689     Set latency timer
1690
1691     The FTDI chip keeps data in the internal buffer for a specific
1692     amount of time if the buffer is not full yet to decrease
1693     load on the usb bus.
1694
1695     \param ftdi pointer to ftdi_context
1696     \param latency Value between 1 and 255
1697
1698     \retval  0: all fine
1699     \retval -1: latency out of range
1700     \retval -2: unable to set latency timer
1701 */
1702 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
1703 {
1704     unsigned short usb_val;
1705
1706     if (latency < 1)
1707         ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
1708
1709     usb_val = latency;
1710     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_LATENCY_TIMER_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1711         ftdi_error_return(-2, "unable to set latency timer");
1712
1713     return 0;
1714 }
1715
1716 /**
1717     Get latency timer
1718
1719     \param ftdi pointer to ftdi_context
1720     \param latency Pointer to store latency value in
1721
1722     \retval  0: all fine
1723     \retval -1: unable to get latency timer
1724 */
1725 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1726 {
1727     unsigned short usb_val;
1728     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_GET_LATENCY_TIMER_REQUEST, 0, ftdi->index, (char *)&usb_val, 1, ftdi->usb_read_timeout) != 1)
1729         ftdi_error_return(-1, "reading latency timer failed");
1730
1731     *latency = (unsigned char)usb_val;
1732     return 0;
1733 }
1734
1735 /**
1736     Poll modem status information
1737
1738     This function allows the retrieve the two status bytes of the device.
1739     The device sends these bytes also as a header for each read access
1740     where they are discarded by ftdi_read_data(). The chip generates
1741     the two stripped status bytes in the absence of data every 40 ms.
1742
1743     Layout of the first byte:
1744     - B0..B3 - must be 0
1745     - B4       Clear to send (CTS)
1746                  0 = inactive
1747                  1 = active
1748     - B5       Data set ready (DTS)
1749                  0 = inactive
1750                  1 = active
1751     - B6       Ring indicator (RI)
1752                  0 = inactive
1753                  1 = active
1754     - B7       Receive line signal detect (RLSD)
1755                  0 = inactive
1756                  1 = active
1757
1758     Layout of the second byte:
1759     - B0       Data ready (DR)
1760     - B1       Overrun error (OE)
1761     - B2       Parity error (PE)
1762     - B3       Framing error (FE)
1763     - B4       Break interrupt (BI)
1764     - B5       Transmitter holding register (THRE)
1765     - B6       Transmitter empty (TEMT)
1766     - B7       Error in RCVR FIFO
1767
1768     \param ftdi pointer to ftdi_context
1769     \param status Pointer to store status information in. Must be two bytes.
1770
1771     \retval  0: all fine
1772     \retval -1: unable to retrieve status information
1773 */
1774 int ftdi_poll_modem_status(struct ftdi_context *ftdi, unsigned short *status)
1775 {
1776     char usb_val[2];
1777
1778     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_POLL_MODEM_STATUS_REQUEST, 0, ftdi->index, usb_val, 2, ftdi->usb_read_timeout) != 2)
1779         ftdi_error_return(-1, "getting modem status failed");
1780
1781     *status = (usb_val[1] << 8) | usb_val[0];
1782
1783     return 0;
1784 }
1785
1786 /**
1787     Set flowcontrol for ftdi chip
1788
1789     \param ftdi pointer to ftdi_context
1790     \param flowctrl flow control to use. should be
1791            SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1792
1793     \retval  0: all fine
1794     \retval -1: set flow control failed
1795 */
1796 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1797 {
1798     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1799                         SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->index),
1800                         NULL, 0, ftdi->usb_write_timeout) != 0)
1801         ftdi_error_return(-1, "set flow control failed");
1802
1803     return 0;
1804 }
1805
1806 /**
1807     Set dtr line
1808
1809     \param ftdi pointer to ftdi_context
1810     \param state state to set line to (1 or 0)
1811
1812     \retval  0: all fine
1813     \retval -1: set dtr failed
1814 */
1815 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
1816 {
1817     unsigned short usb_val;
1818
1819     if (state)
1820         usb_val = SIO_SET_DTR_HIGH;
1821     else
1822         usb_val = SIO_SET_DTR_LOW;
1823
1824     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1825                         SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1826                         NULL, 0, ftdi->usb_write_timeout) != 0)
1827         ftdi_error_return(-1, "set dtr failed");
1828
1829     return 0;
1830 }
1831
1832 /**
1833     Set rts line
1834
1835     \param ftdi pointer to ftdi_context
1836     \param state state to set line to (1 or 0)
1837
1838     \retval  0: all fine
1839     \retval -1 set rts failed
1840 */
1841 int ftdi_setrts(struct ftdi_context *ftdi, int state)
1842 {
1843     unsigned short usb_val;
1844
1845     if (state)
1846         usb_val = SIO_SET_RTS_HIGH;
1847     else
1848         usb_val = SIO_SET_RTS_LOW;
1849
1850     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1851                         SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1852                         NULL, 0, ftdi->usb_write_timeout) != 0)
1853         ftdi_error_return(-1, "set of rts failed");
1854
1855     return 0;
1856 }
1857
1858 /**
1859  Set dtr and rts line in one pass
1860
1861  \param ftdi pointer to ftdi_context
1862  \param dtr  DTR state to set line to (1 or 0)
1863  \param rts  RTS state to set line to (1 or 0)
1864
1865  \retval  0: all fine
1866  \retval -1 set dtr/rts failed
1867  */
1868 int ftdi_setdtr_rts(struct ftdi_context *ftdi, int dtr, int rts)
1869 {
1870     unsigned short usb_val;
1871
1872     if (dtr)
1873         usb_val = SIO_SET_DTR_HIGH;
1874     else
1875         usb_val = SIO_SET_DTR_LOW;
1876
1877     if (rts)
1878         usb_val |= SIO_SET_RTS_HIGH;
1879     else
1880         usb_val |= SIO_SET_RTS_LOW;
1881
1882     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1883                         SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1884                         NULL, 0, ftdi->usb_write_timeout) != 0)
1885         ftdi_error_return(-1, "set of rts/dtr failed");
1886
1887     return 0;
1888 }
1889
1890 /**
1891     Set the special event character
1892
1893     \param ftdi pointer to ftdi_context
1894     \param eventch Event character
1895     \param enable 0 to disable the event character, non-zero otherwise
1896
1897     \retval  0: all fine
1898     \retval -1: unable to set event character
1899 */
1900 int ftdi_set_event_char(struct ftdi_context *ftdi,
1901                         unsigned char eventch, unsigned char enable)
1902 {
1903     unsigned short usb_val;
1904
1905     usb_val = eventch;
1906     if (enable)
1907         usb_val |= 1 << 8;
1908
1909     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_EVENT_CHAR_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1910         ftdi_error_return(-1, "setting event character failed");
1911
1912     return 0;
1913 }
1914
1915 /**
1916     Set error character
1917
1918     \param ftdi pointer to ftdi_context
1919     \param errorch Error character
1920     \param enable 0 to disable the error character, non-zero otherwise
1921
1922     \retval  0: all fine
1923     \retval -1: unable to set error character
1924 */
1925 int ftdi_set_error_char(struct ftdi_context *ftdi,
1926                         unsigned char errorch, unsigned char enable)
1927 {
1928     unsigned short usb_val;
1929
1930     usb_val = errorch;
1931     if (enable)
1932         usb_val |= 1 << 8;
1933
1934     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_ERROR_CHAR_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1935         ftdi_error_return(-1, "setting error character failed");
1936
1937     return 0;
1938 }
1939
1940 /**
1941    Set the eeprom size
1942
1943    \param ftdi pointer to ftdi_context
1944    \param eeprom Pointer to ftdi_eeprom
1945    \param size
1946
1947 */
1948 void ftdi_eeprom_setsize(struct ftdi_context *ftdi, struct ftdi_eeprom *eeprom, int size)
1949 {
1950     ftdi->eeprom_size=size;
1951     eeprom->size=size;
1952 }
1953
1954 /**
1955     Init eeprom with default values.
1956
1957     \param eeprom Pointer to ftdi_eeprom
1958 */
1959 void ftdi_eeprom_initdefaults(struct ftdi_eeprom *eeprom)
1960 {
1961     eeprom->vendor_id = 0x0403;
1962     eeprom->product_id = 0x6001;
1963
1964     eeprom->self_powered = 1;
1965     eeprom->remote_wakeup = 1;
1966     eeprom->BM_type_chip = 1;
1967
1968     eeprom->in_is_isochronous = 0;
1969     eeprom->out_is_isochronous = 0;
1970     eeprom->suspend_pull_downs = 0;
1971
1972     eeprom->use_serial = 0;
1973     eeprom->change_usb_version = 0;
1974     eeprom->usb_version = 0x0200;
1975     eeprom->max_power = 0;
1976
1977     eeprom->manufacturer = NULL;
1978     eeprom->product = NULL;
1979     eeprom->serial = NULL;
1980
1981     eeprom->size = FTDI_DEFAULT_EEPROM_SIZE;
1982 }
1983
1984 /**
1985    Build binary output from ftdi_eeprom structure.
1986    Output is suitable for ftdi_write_eeprom().
1987
1988    \param eeprom Pointer to ftdi_eeprom
1989    \param output Buffer of 128 bytes to store eeprom image to
1990
1991    \retval >0: used eeprom size
1992    \retval -1: eeprom size (128 bytes) exceeded by custom strings
1993 */
1994 int ftdi_eeprom_build(struct ftdi_eeprom *eeprom, unsigned char *output)
1995 {
1996     unsigned char i, j;
1997     unsigned short checksum, value;
1998     unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
1999     int size_check;
2000
2001     if (eeprom->manufacturer != NULL)
2002         manufacturer_size = strlen(eeprom->manufacturer);
2003     if (eeprom->product != NULL)
2004         product_size = strlen(eeprom->product);
2005     if (eeprom->serial != NULL)
2006         serial_size = strlen(eeprom->serial);
2007
2008     size_check = eeprom->size;
2009     size_check -= 28; // 28 are always in use (fixed)
2010
2011     // Top half of a 256byte eeprom is used just for strings and checksum
2012     // it seems that the FTDI chip will not read these strings from the lower half
2013     // Each string starts with two bytes; offset and type (0x03 for string)
2014     // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2015     if (eeprom->size>=256)size_check = 120;
2016     size_check -= manufacturer_size*2;
2017     size_check -= product_size*2;
2018     size_check -= serial_size*2;
2019
2020     // eeprom size exceeded?
2021     if (size_check < 0)
2022         return (-1);
2023
2024     // empty eeprom
2025     memset (output, 0, eeprom->size);
2026
2027     // Addr 00: Stay 00 00
2028     // Addr 02: Vendor ID
2029     output[0x02] = eeprom->vendor_id;
2030     output[0x03] = eeprom->vendor_id >> 8;
2031
2032     // Addr 04: Product ID
2033     output[0x04] = eeprom->product_id;
2034     output[0x05] = eeprom->product_id >> 8;
2035
2036     // Addr 06: Device release number (0400h for BM features)
2037     output[0x06] = 0x00;
2038
2039     if (eeprom->BM_type_chip == 1)
2040         output[0x07] = 0x04;
2041     else
2042         output[0x07] = 0x02;
2043
2044     // Addr 08: Config descriptor
2045     // Bit 7: always 1
2046     // Bit 6: 1 if this device is self powered, 0 if bus powered
2047     // Bit 5: 1 if this device uses remote wakeup
2048     // Bit 4: 1 if this device is battery powered
2049     j = 0x80;
2050     if (eeprom->self_powered == 1)
2051         j |= 0x40;
2052     if (eeprom->remote_wakeup == 1)
2053         j |= 0x20;
2054     output[0x08] = j;
2055
2056     // Addr 09: Max power consumption: max power = value * 2 mA
2057     output[0x09] = eeprom->max_power;
2058
2059     // Addr 0A: Chip configuration
2060     // Bit 7: 0 - reserved
2061     // Bit 6: 0 - reserved
2062     // Bit 5: 0 - reserved
2063     // Bit 4: 1 - Change USB version
2064     // Bit 3: 1 - Use the serial number string
2065     // Bit 2: 1 - Enable suspend pull downs for lower power
2066     // Bit 1: 1 - Out EndPoint is Isochronous
2067     // Bit 0: 1 - In EndPoint is Isochronous
2068     //
2069     j = 0;
2070     if (eeprom->in_is_isochronous == 1)
2071         j = j | 1;
2072     if (eeprom->out_is_isochronous == 1)
2073         j = j | 2;
2074     if (eeprom->suspend_pull_downs == 1)
2075         j = j | 4;
2076     if (eeprom->use_serial == 1)
2077         j = j | 8;
2078     if (eeprom->change_usb_version == 1)
2079         j = j | 16;
2080     output[0x0A] = j;
2081
2082     // Addr 0B: reserved
2083     output[0x0B] = 0x00;
2084
2085     // Addr 0C: USB version low byte when 0x0A bit 4 is set
2086     // Addr 0D: USB version high byte when 0x0A bit 4 is set
2087     if (eeprom->change_usb_version == 1)
2088     {
2089         output[0x0C] = eeprom->usb_version;
2090         output[0x0D] = eeprom->usb_version >> 8;
2091     }
2092
2093
2094     // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2095     // Addr 0F: Length of manufacturer string
2096     output[0x0F] = manufacturer_size*2 + 2;
2097
2098     // Addr 10: Offset of the product string + 0x80, calculated later
2099     // Addr 11: Length of product string
2100     output[0x11] = product_size*2 + 2;
2101
2102     // Addr 12: Offset of the serial string + 0x80, calculated later
2103     // Addr 13: Length of serial string
2104     output[0x13] = serial_size*2 + 2;
2105
2106     // Dynamic content
2107     i=0x14;
2108     if (eeprom->size>=256) i = 0x80;
2109
2110
2111     // Output manufacturer
2112     output[0x0E] = i | 0x80;  // calculate offset
2113     output[i++] = manufacturer_size*2 + 2;
2114     output[i++] = 0x03; // type: string
2115     for (j = 0; j < manufacturer_size; j++)
2116     {
2117         output[i] = eeprom->manufacturer[j], i++;
2118         output[i] = 0x00, i++;
2119     }
2120
2121     // Output product name
2122     output[0x10] = i | 0x80;  // calculate offset
2123     output[i] = product_size*2 + 2, i++;
2124     output[i] = 0x03, i++;
2125     for (j = 0; j < product_size; j++)
2126     {
2127         output[i] = eeprom->product[j], i++;
2128         output[i] = 0x00, i++;
2129     }
2130
2131     // Output serial
2132     output[0x12] = i | 0x80; // calculate offset
2133     output[i] = serial_size*2 + 2, i++;
2134     output[i] = 0x03, i++;
2135     for (j = 0; j < serial_size; j++)
2136     {
2137         output[i] = eeprom->serial[j], i++;
2138         output[i] = 0x00, i++;
2139     }
2140
2141     // calculate checksum
2142     checksum = 0xAAAA;
2143
2144     for (i = 0; i < eeprom->size/2-1; i++)
2145     {
2146         value = output[i*2];
2147         value += output[(i*2)+1] << 8;
2148
2149         checksum = value^checksum;
2150         checksum = (checksum << 1) | (checksum >> 15);
2151     }
2152
2153     output[eeprom->size-2] = checksum;
2154     output[eeprom->size-1] = checksum >> 8;
2155
2156     return size_check;
2157 }
2158
2159 /**
2160    Decode binary EEPROM image into an ftdi_eeprom structure.
2161
2162    \param eeprom Pointer to ftdi_eeprom which will be filled in.
2163    \param buf Buffer of \a size bytes of raw eeprom data
2164    \param size size size of eeprom data in bytes
2165
2166    \retval 0: all fine
2167    \retval -1: something went wrong
2168
2169    FIXME: How to pass size? How to handle size field in ftdi_eeprom?
2170    FIXME: Strings are malloc'ed here and should be freed somewhere
2171 */
2172 int ftdi_eeprom_decode(struct ftdi_eeprom *eeprom, unsigned char *buf, int size)
2173 {
2174     unsigned char i, j;
2175     unsigned short checksum, eeprom_checksum, value;
2176     unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2177     int size_check;
2178     int eeprom_size = 128;
2179 #if 0
2180     size_check = eeprom->size;
2181     size_check -= 28; // 28 are always in use (fixed)
2182
2183     // Top half of a 256byte eeprom is used just for strings and checksum
2184     // it seems that the FTDI chip will not read these strings from the lower half
2185     // Each string starts with two bytes; offset and type (0x03 for string)
2186     // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2187     if (eeprom->size>=256)size_check = 120;
2188     size_check -= manufacturer_size*2;
2189     size_check -= product_size*2;
2190     size_check -= serial_size*2;
2191
2192     // eeprom size exceeded?
2193     if (size_check < 0)
2194         return (-1);
2195 #endif
2196
2197     // empty eeprom struct
2198     memset(eeprom, 0, sizeof(struct ftdi_eeprom));
2199
2200     // Addr 00: Stay 00 00
2201
2202     // Addr 02: Vendor ID
2203     eeprom->vendor_id = buf[0x02] + (buf[0x03] << 8);
2204
2205     // Addr 04: Product ID
2206     eeprom->product_id = buf[0x04] + (buf[0x05] << 8);
2207
2208     value = buf[0x06] + (buf[0x07]<<8);
2209     switch (value)
2210     {
2211         case 0x0400:
2212             eeprom->BM_type_chip = 1;
2213             break;
2214         case 0x0200:
2215             eeprom->BM_type_chip = 0;
2216             break;
2217         default: // Unknown device
2218             eeprom->BM_type_chip = 0;
2219             break;
2220     }
2221
2222     // Addr 08: Config descriptor
2223     // Bit 7: always 1
2224     // Bit 6: 1 if this device is self powered, 0 if bus powered
2225     // Bit 5: 1 if this device uses remote wakeup
2226     // Bit 4: 1 if this device is battery powered
2227     j = buf[0x08];
2228     if (j&0x40) eeprom->self_powered = 1;
2229     if (j&0x20) eeprom->remote_wakeup = 1;
2230
2231     // Addr 09: Max power consumption: max power = value * 2 mA
2232     eeprom->max_power = buf[0x09];
2233
2234     // Addr 0A: Chip configuration
2235     // Bit 7: 0 - reserved
2236     // Bit 6: 0 - reserved
2237     // Bit 5: 0 - reserved
2238     // Bit 4: 1 - Change USB version
2239     // Bit 3: 1 - Use the serial number string
2240     // Bit 2: 1 - Enable suspend pull downs for lower power
2241     // Bit 1: 1 - Out EndPoint is Isochronous
2242     // Bit 0: 1 - In EndPoint is Isochronous
2243     //
2244     j = buf[0x0A];
2245     if (j&0x01) eeprom->in_is_isochronous = 1;
2246     if (j&0x02) eeprom->out_is_isochronous = 1;
2247     if (j&0x04) eeprom->suspend_pull_downs = 1;
2248     if (j&0x08) eeprom->use_serial = 1;
2249     if (j&0x10) eeprom->change_usb_version = 1;
2250
2251     // Addr 0B: reserved
2252
2253     // Addr 0C: USB version low byte when 0x0A bit 4 is set
2254     // Addr 0D: USB version high byte when 0x0A bit 4 is set
2255     if (eeprom->change_usb_version == 1)
2256     {
2257         eeprom->usb_version = buf[0x0C] + (buf[0x0D] << 8);
2258     }
2259
2260     // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2261     // Addr 0F: Length of manufacturer string
2262     manufacturer_size = buf[0x0F]/2;
2263     if (manufacturer_size > 0) eeprom->manufacturer = malloc(manufacturer_size);
2264     else eeprom->manufacturer = NULL;
2265
2266     // Addr 10: Offset of the product string + 0x80, calculated later
2267     // Addr 11: Length of product string
2268     product_size = buf[0x11]/2;
2269     if (product_size > 0) eeprom->product = malloc(product_size);
2270     else eeprom->product = NULL;
2271
2272     // Addr 12: Offset of the serial string + 0x80, calculated later
2273     // Addr 13: Length of serial string
2274     serial_size = buf[0x13]/2;
2275     if (serial_size > 0) eeprom->serial = malloc(serial_size);
2276     else eeprom->serial = NULL;
2277
2278     // Decode manufacturer
2279     i = buf[0x0E] & 0x7f; // offset
2280     for (j=0;j<manufacturer_size-1;j++)
2281     {
2282         eeprom->manufacturer[j] = buf[2*j+i+2];
2283     }
2284     eeprom->manufacturer[j] = '\0';
2285
2286     // Decode product name
2287     i = buf[0x10] & 0x7f; // offset
2288     for (j=0;j<product_size-1;j++)
2289     {
2290         eeprom->product[j] = buf[2*j+i+2];
2291     }
2292     eeprom->product[j] = '\0';
2293
2294     // Decode serial
2295     i = buf[0x12] & 0x7f; // offset
2296     for (j=0;j<serial_size-1;j++)
2297     {
2298         eeprom->serial[j] = buf[2*j+i+2];
2299     }
2300     eeprom->serial[j] = '\0';
2301
2302     // verify checksum
2303     checksum = 0xAAAA;
2304
2305     for (i = 0; i < eeprom_size/2-1; i++)
2306     {
2307         value = buf[i*2];
2308         value += buf[(i*2)+1] << 8;
2309
2310         checksum = value^checksum;
2311         checksum = (checksum << 1) | (checksum >> 15);
2312     }
2313
2314     eeprom_checksum = buf[eeprom_size-2] + (buf[eeprom_size-1] << 8);
2315
2316     if (eeprom_checksum != checksum)
2317     {
2318         fprintf(stderr, "Checksum Error: %04x %04x\n", checksum, eeprom_checksum);
2319         return -1;
2320     }
2321
2322     return 0;
2323 }
2324
2325 /**
2326     Read eeprom location
2327
2328     \param ftdi pointer to ftdi_context
2329     \param eeprom_addr Address of eeprom location to be read
2330     \param eeprom_val Pointer to store read eeprom location
2331
2332     \retval  0: all fine
2333     \retval -1: read failed
2334 */
2335 int ftdi_read_eeprom_location (struct ftdi_context *ftdi, int eeprom_addr, unsigned short *eeprom_val)
2336 {
2337     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, eeprom_addr, (char *)eeprom_val, 2, ftdi->usb_read_timeout) != 2)
2338         ftdi_error_return(-1, "reading eeprom failed");
2339
2340     return 0;
2341 }
2342
2343 /**
2344     Read eeprom
2345
2346     \param ftdi pointer to ftdi_context
2347     \param eeprom Pointer to store eeprom into
2348
2349     \retval  0: all fine
2350     \retval -1: read failed
2351 */
2352 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2353 {
2354     int i;
2355
2356     for (i = 0; i < ftdi->eeprom_size/2; i++)
2357     {
2358         if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, i, eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2359             ftdi_error_return(-1, "reading eeprom failed");
2360     }
2361
2362     return 0;
2363 }
2364
2365 /*
2366     ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
2367     Function is only used internally
2368     \internal
2369 */
2370 static unsigned char ftdi_read_chipid_shift(unsigned char value)
2371 {
2372     return ((value & 1) << 1) |
2373            ((value & 2) << 5) |
2374            ((value & 4) >> 2) |
2375            ((value & 8) << 4) |
2376            ((value & 16) >> 1) |
2377            ((value & 32) >> 1) |
2378            ((value & 64) >> 4) |
2379            ((value & 128) >> 2);
2380 }
2381
2382 /**
2383     Read the FTDIChip-ID from R-type devices
2384
2385     \param ftdi pointer to ftdi_context
2386     \param chipid Pointer to store FTDIChip-ID
2387
2388     \retval  0: all fine
2389     \retval -1: read failed
2390 */
2391 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
2392 {
2393     unsigned int a = 0, b = 0;
2394
2395     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, 0x43, (char *)&a, 2, ftdi->usb_read_timeout) == 2)
2396     {
2397         a = a << 8 | a >> 8;
2398         if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, 0x44, (char *)&b, 2, ftdi->usb_read_timeout) == 2)
2399         {
2400             b = b << 8 | b >> 8;
2401             a = (a << 16) | (b & 0xFFFF);
2402             a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8
2403                 | ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
2404             *chipid = a ^ 0xa5f0f7d1;
2405             return 0;
2406         }
2407     }
2408
2409     ftdi_error_return(-1, "read of FTDIChip-ID failed");
2410 }
2411
2412 /**
2413    Guesses size of eeprom by reading eeprom and comparing halves - will not work with blank eeprom
2414    Call this function then do a write then call again to see if size changes, if so write again.
2415
2416    \param ftdi pointer to ftdi_context
2417    \param eeprom Pointer to store eeprom into
2418    \param maxsize the size of the buffer to read into
2419
2420    \retval size of eeprom
2421 */
2422 int ftdi_read_eeprom_getsize(struct ftdi_context *ftdi, unsigned char *eeprom, int maxsize)
2423 {
2424     int i=0,j,minsize=32;
2425     int size=minsize;
2426
2427     do
2428     {
2429         for (j = 0; i < maxsize/2 && j<size; j++)
2430         {
2431             if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE,
2432                                 SIO_READ_EEPROM_REQUEST, 0, i,
2433                                 eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2434                 ftdi_error_return(-1, "reading eeprom failed");
2435             i++;
2436         }
2437         size*=2;
2438     }
2439     while (size<=maxsize && memcmp(eeprom,&eeprom[size/2],size/2)!=0);
2440
2441     return size/2;
2442 }
2443
2444 /**
2445     Write eeprom location
2446
2447     \param ftdi pointer to ftdi_context
2448     \param eeprom_addr Address of eeprom location to be written
2449     \param eeprom_val Value to be written
2450
2451     \retval  0: all fine
2452     \retval -1: read failed
2453 */
2454 int ftdi_write_eeprom_location(struct ftdi_context *ftdi, int eeprom_addr, unsigned short eeprom_val)
2455 {
2456     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2457                                     SIO_WRITE_EEPROM_REQUEST, eeprom_val, eeprom_addr,
2458                                     NULL, 0, ftdi->usb_write_timeout) != 0)
2459         ftdi_error_return(-1, "unable to write eeprom");
2460
2461     return 0;
2462 }
2463
2464 /**
2465     Write eeprom
2466
2467     \param ftdi pointer to ftdi_context
2468     \param eeprom Pointer to read eeprom from
2469
2470     \retval  0: all fine
2471     \retval -1: read failed
2472 */
2473 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2474 {
2475     unsigned short usb_val, status;
2476     int i, ret;
2477
2478     /* These commands were traced while running MProg */
2479     if ((ret = ftdi_usb_reset(ftdi)) != 0)
2480         return ret;
2481     if ((ret = ftdi_poll_modem_status(ftdi, &status)) != 0)
2482         return ret;
2483     if ((ret = ftdi_set_latency_timer(ftdi, 0x77)) != 0)
2484         return ret;
2485
2486     for (i = 0; i < ftdi->eeprom_size/2; i++)
2487     {
2488         usb_val = eeprom[i*2];
2489         usb_val += eeprom[(i*2)+1] << 8;
2490         if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2491                             SIO_WRITE_EEPROM_REQUEST, usb_val, i,
2492                             NULL, 0, ftdi->usb_write_timeout) != 0)
2493             ftdi_error_return(-1, "unable to write eeprom");
2494     }
2495
2496     return 0;
2497 }
2498
2499 /**
2500     Erase eeprom
2501
2502     This is not supported on FT232R/FT245R according to the MProg manual from FTDI.
2503
2504     \param ftdi pointer to ftdi_context
2505
2506     \retval  0: all fine
2507     \retval -1: erase failed
2508 */
2509 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
2510 {
2511     if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_ERASE_EEPROM_REQUEST, 0, 0, NULL, 0, ftdi->usb_write_timeout) != 0)
2512         ftdi_error_return(-1, "unable to erase eeprom");
2513
2514     return 0;
2515 }
2516
2517 /**
2518     Get string representation for last error code
2519
2520     \param ftdi pointer to ftdi_context
2521
2522     \retval Pointer to error string
2523 */
2524 char *ftdi_get_error_string (struct ftdi_context *ftdi)
2525 {
2526     return ftdi->error_str;
2527 }
2528
2529 /* @} end of doxygen libftdi group */