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