1 /***************************************************************************
5 copyright : (C) 2003-2010 by Intra2net AG
6 email : opensource@intra2net.com
7 ***************************************************************************/
9 /***************************************************************************
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; *
15 ***************************************************************************/
18 \mainpage libftdi API documentation
20 Library to talk to FTDI chips. You find the latest versions of libftdi at
21 http://www.intra2net.com/en/developer/libftdi/
23 The library is easy to use. Have a look at this short example:
26 More examples can be found in the "examples" directory.
28 /** \addtogroup libftdi */
39 #define ftdi_error_return(code, str) do { \
40 ftdi->error_str = str; \
44 #define ftdi_error_return_free_device_list(code, str, devs) do { \
45 libusb_free_device_list(devs,1); \
46 ftdi->error_str = str; \
52 Internal function to close usb device pointer.
53 Sets ftdi->usb_dev to NULL.
56 \param ftdi pointer to ftdi_context
60 static void ftdi_usb_close_internal (struct ftdi_context *ftdi)
62 if (ftdi && ftdi->usb_dev)
64 libusb_close (ftdi->usb_dev);
70 Initializes a ftdi_context.
72 \param ftdi pointer to ftdi_context
75 \retval -1: couldn't allocate read buffer
77 \remark This should be called before all functions
79 int ftdi_init(struct ftdi_context *ftdi)
83 ftdi->usb_read_timeout = 5000;
84 ftdi->usb_write_timeout = 5000;
86 ftdi->type = TYPE_BM; /* chip type */
88 ftdi->bitbang_enabled = 0; /* 0: normal mode 1: any of the bitbang modes enabled */
90 ftdi->readbuffer = NULL;
91 ftdi->readbuffer_offset = 0;
92 ftdi->readbuffer_remaining = 0;
93 ftdi->writebuffer_chunksize = 4096;
94 ftdi->max_packet_size = 0;
100 ftdi->bitbang_mode = 1; /* when bitbang is enabled this holds the number of the mode */
102 ftdi->error_str = NULL;
104 ftdi->eeprom_size = FTDI_DEFAULT_EEPROM_SIZE;
106 /* All fine. Now allocate the readbuffer */
107 return ftdi_read_data_set_chunksize(ftdi, 4096);
111 Allocate and initialize a new ftdi_context
113 \return a pointer to a new ftdi_context, or NULL on failure
115 struct ftdi_context *ftdi_new(void)
117 struct ftdi_context * ftdi = (struct ftdi_context *)malloc(sizeof(struct ftdi_context));
124 if (ftdi_init(ftdi) != 0)
134 Open selected channels on a chip, otherwise use first channel.
136 \param ftdi pointer to ftdi_context
137 \param interface Interface to use for FT2232C/2232H/4232H chips.
140 \retval -1: unknown interface
141 \retval -2: USB device unavailable
143 int ftdi_set_interface(struct ftdi_context *ftdi, enum ftdi_interface interface)
146 ftdi_error_return(-2, "USB device unavailable");
152 /* ftdi_usb_open_desc cares to set the right index, depending on the found chip */
156 ftdi->index = INTERFACE_B;
162 ftdi->index = INTERFACE_C;
168 ftdi->index = INTERFACE_D;
173 ftdi_error_return(-1, "Unknown interface");
179 Deinitializes a ftdi_context.
181 \param ftdi pointer to ftdi_context
183 void ftdi_deinit(struct ftdi_context *ftdi)
188 ftdi_usb_close_internal (ftdi);
190 if (ftdi->readbuffer != NULL)
192 free(ftdi->readbuffer);
193 ftdi->readbuffer = NULL;
195 libusb_exit(ftdi->usb_ctx);
199 Deinitialize and free an ftdi_context.
201 \param ftdi pointer to ftdi_context
203 void ftdi_free(struct ftdi_context *ftdi)
210 Use an already open libusb device.
212 \param ftdi pointer to ftdi_context
213 \param usb libusb libusb_device_handle to use
215 void ftdi_set_usbdev (struct ftdi_context *ftdi, libusb_device_handle *usb)
225 Finds all ftdi devices on the usb bus. Creates a new ftdi_device_list which
226 needs to be deallocated by ftdi_list_free() after use.
228 \param ftdi pointer to ftdi_context
229 \param devlist Pointer where to store list of found devices
230 \param vendor Vendor ID to search for
231 \param product Product ID to search for
233 \retval >0: number of devices found
234 \retval -3: out of memory
235 \retval -4: libusb_init() failed
236 \retval -5: libusb_get_device_list() failed
237 \retval -6: libusb_get_device_descriptor() failed
239 int ftdi_usb_find_all(struct ftdi_context *ftdi, struct ftdi_device_list **devlist, int vendor, int product)
241 struct ftdi_device_list **curdev;
243 libusb_device **devs;
247 if (libusb_init(&ftdi->usb_ctx) < 0)
248 ftdi_error_return(-4, "libusb_init() failed");
250 if (libusb_get_device_list(ftdi->usb_ctx, &devs) < 0)
251 ftdi_error_return(-5, "libusb_get_device_list() failed");
256 while ((dev = devs[i++]) != NULL)
258 struct libusb_device_descriptor desc;
260 if (libusb_get_device_descriptor(dev, &desc) < 0)
261 ftdi_error_return(-6, "libusb_get_device_descriptor() failed");
263 if (desc.idVendor == vendor && desc.idProduct == product)
265 *curdev = (struct ftdi_device_list*)malloc(sizeof(struct ftdi_device_list));
267 ftdi_error_return(-3, "out of memory");
269 (*curdev)->next = NULL;
270 (*curdev)->dev = dev;
272 curdev = &(*curdev)->next;
281 Frees a usb device list.
283 \param devlist USB device list created by ftdi_usb_find_all()
285 void ftdi_list_free(struct ftdi_device_list **devlist)
287 struct ftdi_device_list *curdev, *next;
289 for (curdev = *devlist; curdev != NULL;)
300 Frees a usb device list.
302 \param devlist USB device list created by ftdi_usb_find_all()
304 void ftdi_list_free2(struct ftdi_device_list *devlist)
306 ftdi_list_free(&devlist);
310 Return device ID strings from the usb device.
312 The parameters manufacturer, description and serial may be NULL
313 or pointer to buffers to store the fetched strings.
315 \note Use this function only in combination with ftdi_usb_find_all()
316 as it closes the internal "usb_dev" after use.
318 \param ftdi pointer to ftdi_context
319 \param dev libusb usb_dev to use
320 \param manufacturer Store manufacturer string here if not NULL
321 \param mnf_len Buffer size of manufacturer string
322 \param description Store product description string here if not NULL
323 \param desc_len Buffer size of product description string
324 \param serial Store serial string here if not NULL
325 \param serial_len Buffer size of serial string
328 \retval -1: wrong arguments
329 \retval -4: unable to open device
330 \retval -7: get product manufacturer failed
331 \retval -8: get product description failed
332 \retval -9: get serial number failed
333 \retval -11: libusb_get_device_descriptor() failed
335 int ftdi_usb_get_strings(struct ftdi_context * ftdi, struct libusb_device * dev,
336 char * manufacturer, int mnf_len, char * description, int desc_len, char * serial, int serial_len)
338 struct libusb_device_descriptor desc;
340 if ((ftdi==NULL) || (dev==NULL))
343 if (libusb_open(dev, &ftdi->usb_dev) < 0)
344 ftdi_error_return(-4, "libusb_open() failed");
346 if (libusb_get_device_descriptor(dev, &desc) < 0)
347 ftdi_error_return(-11, "libusb_get_device_descriptor() failed");
349 if (manufacturer != NULL)
351 if (libusb_get_string_descriptor_ascii(ftdi->usb_dev, desc.iManufacturer, (unsigned char *)manufacturer, mnf_len) < 0)
353 ftdi_usb_close_internal (ftdi);
354 ftdi_error_return(-7, "libusb_get_string_descriptor_ascii() failed");
358 if (description != NULL)
360 if (libusb_get_string_descriptor_ascii(ftdi->usb_dev, desc.iProduct, (unsigned char *)description, desc_len) < 0)
362 ftdi_usb_close_internal (ftdi);
363 ftdi_error_return(-8, "libusb_get_string_descriptor_ascii() failed");
369 if (libusb_get_string_descriptor_ascii(ftdi->usb_dev, desc.iSerialNumber, (unsigned char *)serial, serial_len) < 0)
371 ftdi_usb_close_internal (ftdi);
372 ftdi_error_return(-9, "libusb_get_string_descriptor_ascii() failed");
376 ftdi_usb_close_internal (ftdi);
382 * Internal function to determine the maximum packet size.
383 * \param ftdi pointer to ftdi_context
384 * \param dev libusb usb_dev to use
385 * \retval Maximum packet size for this device
387 static unsigned int _ftdi_determine_max_packet_size(struct ftdi_context *ftdi, libusb_device *dev)
389 struct libusb_device_descriptor desc;
390 struct libusb_config_descriptor *config0;
391 unsigned int packet_size;
394 if (ftdi == NULL || dev == NULL)
397 // Determine maximum packet size. Init with default value.
398 // New hi-speed devices from FTDI use a packet size of 512 bytes
399 // but could be connected to a normal speed USB hub -> 64 bytes packet size.
400 if (ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
405 if (libusb_get_device_descriptor(dev, &desc) < 0)
408 if (libusb_get_config_descriptor(dev, 0, &config0) < 0)
411 if (desc.bNumConfigurations > 0)
413 if (ftdi->interface < config0->bNumInterfaces)
415 struct libusb_interface interface = config0->interface[ftdi->interface];
416 if (interface.num_altsetting > 0)
418 struct libusb_interface_descriptor descriptor = interface.altsetting[0];
419 if (descriptor.bNumEndpoints > 0)
421 packet_size = descriptor.endpoint[0].wMaxPacketSize;
427 libusb_free_config_descriptor (config0);
432 Opens a ftdi device given by an usb_device.
434 \param ftdi pointer to ftdi_context
435 \param dev libusb usb_dev to use
438 \retval -3: unable to config device
439 \retval -4: unable to open device
440 \retval -5: unable to claim device
441 \retval -6: reset failed
442 \retval -7: set baudrate failed
443 \retval -8: ftdi context invalid
444 \retval -9: libusb_get_device_descriptor() failed
445 \retval -10: libusb_get_config_descriptor() failed
446 \retval -11: libusb_etach_kernel_driver() failed
447 \retval -12: libusb_get_configuration() failed
449 int ftdi_usb_open_dev(struct ftdi_context *ftdi, libusb_device *dev)
451 struct libusb_device_descriptor desc;
452 struct libusb_config_descriptor *config0;
453 int cfg, cfg0, detach_errno = 0;
456 ftdi_error_return(-8, "ftdi context invalid");
458 if (libusb_open(dev, &ftdi->usb_dev) < 0)
459 ftdi_error_return(-4, "libusb_open() failed");
461 if (libusb_get_device_descriptor(dev, &desc) < 0)
462 ftdi_error_return(-9, "libusb_get_device_descriptor() failed");
464 if (libusb_get_config_descriptor(dev, 0, &config0) < 0)
465 ftdi_error_return(-10, "libusb_get_config_descriptor() failed");
466 cfg0 = config0->bConfigurationValue;
467 libusb_free_config_descriptor (config0);
469 // Try to detach ftdi_sio kernel module.
471 // The return code is kept in a separate variable and only parsed
472 // if usb_set_configuration() or usb_claim_interface() fails as the
473 // detach operation might be denied and everything still works fine.
474 // Likely scenario is a static ftdi_sio kernel module.
475 if (libusb_detach_kernel_driver(ftdi->usb_dev, ftdi->interface) !=0)
476 detach_errno = errno;
478 if (libusb_get_configuration (ftdi->usb_dev, &cfg) < 0)
479 ftdi_error_return(-12, "libusb_get_configuration () failed");
480 // set configuration (needed especially for windows)
481 // tolerate EBUSY: one device with one configuration, but two interfaces
482 // and libftdi sessions to both interfaces (e.g. FT2232)
483 if (desc.bNumConfigurations > 0 && cfg != cfg0)
485 if (libusb_set_configuration(ftdi->usb_dev, cfg0) < 0)
487 ftdi_usb_close_internal (ftdi);
488 if(detach_errno == EPERM)
490 ftdi_error_return(-8, "inappropriate permissions on device!");
494 ftdi_error_return(-3, "unable to set usb configuration. Make sure the default FTDI driver is not in use");
499 if (libusb_claim_interface(ftdi->usb_dev, ftdi->interface) < 0)
501 ftdi_usb_close_internal (ftdi);
502 if(detach_errno == EPERM)
504 ftdi_error_return(-8, "inappropriate permissions on device!");
508 ftdi_error_return(-5, "unable to claim usb device. Make sure the default FTDI driver is not in use");
512 if (ftdi_usb_reset (ftdi) != 0)
514 ftdi_usb_close_internal (ftdi);
515 ftdi_error_return(-6, "ftdi_usb_reset failed");
518 // Try to guess chip type
519 // Bug in the BM type chips: bcdDevice is 0x200 for serial == 0
520 if (desc.bcdDevice == 0x400 || (desc.bcdDevice == 0x200
521 && desc.iSerialNumber == 0))
522 ftdi->type = TYPE_BM;
523 else if (desc.bcdDevice == 0x200)
524 ftdi->type = TYPE_AM;
525 else if (desc.bcdDevice == 0x500)
526 ftdi->type = TYPE_2232C;
527 else if (desc.bcdDevice == 0x600)
529 else if (desc.bcdDevice == 0x700)
530 ftdi->type = TYPE_2232H;
531 else if (desc.bcdDevice == 0x800)
532 ftdi->type = TYPE_4232H;
534 // Set default interface on dual/quad type chips
541 ftdi->index = INTERFACE_A;
547 // Determine maximum packet size
548 ftdi->max_packet_size = _ftdi_determine_max_packet_size(ftdi, dev);
550 if (ftdi_set_baudrate (ftdi, 9600) != 0)
552 ftdi_usb_close_internal (ftdi);
553 ftdi_error_return(-7, "set baudrate failed");
556 ftdi_error_return(0, "all fine");
560 Opens the first device with a given vendor and product ids.
562 \param ftdi pointer to ftdi_context
563 \param vendor Vendor ID
564 \param product Product ID
566 \retval same as ftdi_usb_open_desc()
568 int ftdi_usb_open(struct ftdi_context *ftdi, int vendor, int product)
570 return ftdi_usb_open_desc(ftdi, vendor, product, NULL, NULL);
574 Opens the first device with a given, vendor id, product id,
575 description and serial.
577 \param ftdi pointer to ftdi_context
578 \param vendor Vendor ID
579 \param product Product ID
580 \param description Description to search for. Use NULL if not needed.
581 \param serial Serial to search for. Use NULL if not needed.
584 \retval -3: usb device not found
585 \retval -4: unable to open device
586 \retval -5: unable to claim device
587 \retval -6: reset failed
588 \retval -7: set baudrate failed
589 \retval -8: get product description failed
590 \retval -9: get serial number failed
591 \retval -11: libusb_init() failed
592 \retval -12: libusb_get_device_list() failed
593 \retval -13: libusb_get_device_descriptor() failed
595 int ftdi_usb_open_desc(struct ftdi_context *ftdi, int vendor, int product,
596 const char* description, const char* serial)
598 return ftdi_usb_open_desc_index(ftdi,vendor,product,description,serial,0);
602 Opens the index-th device with a given, vendor id, product id,
603 description and serial.
605 \param ftdi pointer to ftdi_context
606 \param vendor Vendor ID
607 \param product Product ID
608 \param description Description to search for. Use NULL if not needed.
609 \param serial Serial to search for. Use NULL if not needed.
610 \param index Number of matching device to open if there are more than one, starts with 0.
613 \retval -1: usb_find_busses() failed
614 \retval -2: usb_find_devices() failed
615 \retval -3: usb device not found
616 \retval -4: unable to open device
617 \retval -5: unable to claim device
618 \retval -6: reset failed
619 \retval -7: set baudrate failed
620 \retval -8: get product description failed
621 \retval -9: get serial number failed
622 \retval -10: unable to close device
623 \retval -11: ftdi context invalid
625 int ftdi_usb_open_desc_index(struct ftdi_context *ftdi, int vendor, int product,
626 const char* description, const char* serial, unsigned int index)
629 libusb_device **devs;
633 if (libusb_init(&ftdi->usb_ctx) < 0)
634 ftdi_error_return(-11, "libusb_init() failed");
637 ftdi_error_return(-11, "ftdi context invalid");
639 if (libusb_get_device_list(ftdi->usb_ctx, &devs) < 0)
640 ftdi_error_return(-12, "libusb_get_device_list() failed");
642 while ((dev = devs[i++]) != NULL)
644 struct libusb_device_descriptor desc;
647 if (libusb_get_device_descriptor(dev, &desc) < 0)
648 ftdi_error_return_free_device_list(-13, "libusb_get_device_descriptor() failed", devs);
650 if (desc.idVendor == vendor && desc.idProduct == product)
652 if (libusb_open(dev, &ftdi->usb_dev) < 0)
653 ftdi_error_return_free_device_list(-4, "usb_open() failed", devs);
655 if (description != NULL)
657 if (libusb_get_string_descriptor_ascii(ftdi->usb_dev, desc.iProduct, (unsigned char *)string, sizeof(string)) < 0)
659 libusb_close (ftdi->usb_dev);
660 ftdi_error_return_free_device_list(-8, "unable to fetch product description", devs);
662 if (strncmp(string, description, sizeof(string)) != 0)
664 libusb_close (ftdi->usb_dev);
670 if (libusb_get_string_descriptor_ascii(ftdi->usb_dev, desc.iSerialNumber, (unsigned char *)string, sizeof(string)) < 0)
672 ftdi_usb_close_internal (ftdi);
673 ftdi_error_return_free_device_list(-9, "unable to fetch serial number", devs);
675 if (strncmp(string, serial, sizeof(string)) != 0)
677 ftdi_usb_close_internal (ftdi);
682 ftdi_usb_close_internal (ftdi);
690 res = ftdi_usb_open_dev(ftdi, dev);
691 libusb_free_device_list(devs,1);
697 ftdi_error_return_free_device_list(-3, "device not found", devs);
701 Opens the ftdi-device described by a description-string.
702 Intended to be used for parsing a device-description given as commandline argument.
704 \param ftdi pointer to ftdi_context
705 \param description NULL-terminated description-string, using this format:
706 \li <tt>d:\<devicenode></tt> path of bus and device-node (e.g. "003/001") within usb device tree (usually at /proc/bus/usb/)
707 \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")
708 \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
709 \li <tt>s:\<vendor>:\<product>:\<serial></tt> first device with given vendor id, product id and serial string
711 \note The description format may be extended in later versions.
714 \retval -1: libusb_init() failed
715 \retval -2: libusb_get_device_list() failed
716 \retval -3: usb device not found
717 \retval -4: unable to open device
718 \retval -5: unable to claim device
719 \retval -6: reset failed
720 \retval -7: set baudrate failed
721 \retval -8: get product description failed
722 \retval -9: get serial number failed
723 \retval -10: unable to close device
724 \retval -11: illegal description format
725 \retval -12: ftdi context invalid
727 int ftdi_usb_open_string(struct ftdi_context *ftdi, const char* description)
730 ftdi_error_return(-12, "ftdi context invalid");
732 if (description[0] == 0 || description[1] != ':')
733 ftdi_error_return(-11, "illegal description format");
735 if (description[0] == 'd')
738 libusb_device **devs;
739 unsigned int bus_number, device_address;
742 if (libusb_init (&ftdi->usb_ctx) < 0)
743 ftdi_error_return(-1, "libusb_init() failed");
745 if (libusb_get_device_list(ftdi->usb_ctx, &devs) < 0)
746 ftdi_error_return(-2, "libusb_get_device_list() failed");
748 /* XXX: This doesn't handle symlinks/odd paths/etc... */
749 if (sscanf (description + 2, "%u/%u", &bus_number, &device_address) != 2)
750 ftdi_error_return_free_device_list(-11, "illegal description format", devs);
752 while ((dev = devs[i++]) != NULL)
755 if (bus_number == libusb_get_bus_number (dev)
756 && device_address == libusb_get_device_address (dev))
758 ret = ftdi_usb_open_dev(ftdi, dev);
759 libusb_free_device_list(devs,1);
765 ftdi_error_return_free_device_list(-3, "device not found", devs);
767 else if (description[0] == 'i' || description[0] == 's')
770 unsigned int product;
771 unsigned int index=0;
772 const char *serial=NULL;
773 const char *startp, *endp;
776 startp=description+2;
777 vendor=strtoul((char*)startp,(char**)&endp,0);
778 if (*endp != ':' || endp == startp || errno != 0)
779 ftdi_error_return(-11, "illegal description format");
782 product=strtoul((char*)startp,(char**)&endp,0);
783 if (endp == startp || errno != 0)
784 ftdi_error_return(-11, "illegal description format");
786 if (description[0] == 'i' && *endp != 0)
788 /* optional index field in i-mode */
790 ftdi_error_return(-11, "illegal description format");
793 index=strtoul((char*)startp,(char**)&endp,0);
794 if (*endp != 0 || endp == startp || errno != 0)
795 ftdi_error_return(-11, "illegal description format");
797 if (description[0] == 's')
800 ftdi_error_return(-11, "illegal description format");
802 /* rest of the description is the serial */
806 return ftdi_usb_open_desc_index(ftdi, vendor, product, NULL, serial, index);
810 ftdi_error_return(-11, "illegal description format");
815 Resets the ftdi device.
817 \param ftdi pointer to ftdi_context
820 \retval -1: FTDI reset failed
821 \retval -2: USB device unavailable
823 int ftdi_usb_reset(struct ftdi_context *ftdi)
825 if (ftdi == NULL || ftdi->usb_dev == NULL)
826 ftdi_error_return(-2, "USB device unavailable");
828 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
829 SIO_RESET_REQUEST, SIO_RESET_SIO,
830 ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
831 ftdi_error_return(-1,"FTDI reset failed");
833 // Invalidate data in the readbuffer
834 ftdi->readbuffer_offset = 0;
835 ftdi->readbuffer_remaining = 0;
841 Clears the read buffer on the chip and the internal read buffer.
843 \param ftdi pointer to ftdi_context
846 \retval -1: read buffer purge failed
847 \retval -2: USB device unavailable
849 int ftdi_usb_purge_rx_buffer(struct ftdi_context *ftdi)
851 if (ftdi == NULL || ftdi->usb_dev == NULL)
852 ftdi_error_return(-2, "USB device unavailable");
854 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
855 SIO_RESET_REQUEST, SIO_RESET_PURGE_RX,
856 ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
857 ftdi_error_return(-1, "FTDI purge of RX buffer failed");
859 // Invalidate data in the readbuffer
860 ftdi->readbuffer_offset = 0;
861 ftdi->readbuffer_remaining = 0;
867 Clears the write buffer on the chip.
869 \param ftdi pointer to ftdi_context
872 \retval -1: write buffer purge failed
873 \retval -2: USB device unavailable
875 int ftdi_usb_purge_tx_buffer(struct ftdi_context *ftdi)
877 if (ftdi == NULL || ftdi->usb_dev == NULL)
878 ftdi_error_return(-2, "USB device unavailable");
880 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
881 SIO_RESET_REQUEST, SIO_RESET_PURGE_TX,
882 ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
883 ftdi_error_return(-1, "FTDI purge of TX buffer failed");
889 Clears the buffers on the chip and the internal read buffer.
891 \param ftdi pointer to ftdi_context
894 \retval -1: read buffer purge failed
895 \retval -2: write buffer purge failed
896 \retval -3: USB device unavailable
898 int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
902 if (ftdi == NULL || ftdi->usb_dev == NULL)
903 ftdi_error_return(-3, "USB device unavailable");
905 result = ftdi_usb_purge_rx_buffer(ftdi);
909 result = ftdi_usb_purge_tx_buffer(ftdi);
919 Closes the ftdi device. Call ftdi_deinit() if you're cleaning up.
921 \param ftdi pointer to ftdi_context
924 \retval -1: usb_release failed
925 \retval -3: ftdi context invalid
927 int ftdi_usb_close(struct ftdi_context *ftdi)
932 ftdi_error_return(-3, "ftdi context invalid");
934 if (ftdi->usb_dev != NULL)
935 if (libusb_release_interface(ftdi->usb_dev, ftdi->interface) < 0)
938 ftdi_usb_close_internal (ftdi);
944 ftdi_convert_baudrate returns nearest supported baud rate to that requested.
945 Function is only used internally
948 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
949 unsigned short *value, unsigned short *index)
951 static const char am_adjust_up[8] = {0, 0, 0, 1, 0, 3, 2, 1};
952 static const char am_adjust_dn[8] = {0, 0, 0, 1, 0, 1, 2, 3};
953 static const char frac_code[8] = {0, 3, 2, 4, 1, 5, 6, 7};
954 int divisor, best_divisor, best_baud, best_baud_diff;
955 unsigned long encoded_divisor;
964 divisor = 24000000 / baudrate;
966 if (ftdi->type == TYPE_AM)
968 // Round down to supported fraction (AM only)
969 divisor -= am_adjust_dn[divisor & 7];
972 // Try this divisor and the one above it (because division rounds down)
976 for (i = 0; i < 2; i++)
978 int try_divisor = divisor + i;
982 // Round up to supported divisor value
983 if (try_divisor <= 8)
985 // Round up to minimum supported divisor
988 else if (ftdi->type != TYPE_AM && try_divisor < 12)
990 // BM doesn't support divisors 9 through 11 inclusive
993 else if (divisor < 16)
995 // AM doesn't support divisors 9 through 15 inclusive
1000 if (ftdi->type == TYPE_AM)
1002 // Round up to supported fraction (AM only)
1003 try_divisor += am_adjust_up[try_divisor & 7];
1004 if (try_divisor > 0x1FFF8)
1006 // Round down to maximum supported divisor value (for AM)
1007 try_divisor = 0x1FFF8;
1012 if (try_divisor > 0x1FFFF)
1014 // Round down to maximum supported divisor value (for BM)
1015 try_divisor = 0x1FFFF;
1019 // Get estimated baud rate (to nearest integer)
1020 baud_estimate = (24000000 + (try_divisor / 2)) / try_divisor;
1021 // Get absolute difference from requested baud rate
1022 if (baud_estimate < baudrate)
1024 baud_diff = baudrate - baud_estimate;
1028 baud_diff = baud_estimate - baudrate;
1030 if (i == 0 || baud_diff < best_baud_diff)
1032 // Closest to requested baud rate so far
1033 best_divisor = try_divisor;
1034 best_baud = baud_estimate;
1035 best_baud_diff = baud_diff;
1038 // Spot on! No point trying
1043 // Encode the best divisor value
1044 encoded_divisor = (best_divisor >> 3) | (frac_code[best_divisor & 7] << 14);
1045 // Deal with special cases for encoded value
1046 if (encoded_divisor == 1)
1048 encoded_divisor = 0; // 3000000 baud
1050 else if (encoded_divisor == 0x4001)
1052 encoded_divisor = 1; // 2000000 baud (BM only)
1054 // Split into "value" and "index" values
1055 *value = (unsigned short)(encoded_divisor & 0xFFFF);
1056 if (ftdi->type == TYPE_2232C || ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
1058 *index = (unsigned short)(encoded_divisor >> 8);
1060 *index |= ftdi->index;
1063 *index = (unsigned short)(encoded_divisor >> 16);
1065 // Return the nearest baud rate
1070 Sets the chip baud rate
1072 \param ftdi pointer to ftdi_context
1073 \param baudrate baud rate to set
1076 \retval -1: invalid baudrate
1077 \retval -2: setting baudrate failed
1078 \retval -3: USB device unavailable
1080 int ftdi_set_baudrate(struct ftdi_context *ftdi, int baudrate)
1082 unsigned short value, index;
1083 int actual_baudrate;
1085 if (ftdi == NULL || ftdi->usb_dev == NULL)
1086 ftdi_error_return(-3, "USB device unavailable");
1088 if (ftdi->bitbang_enabled)
1090 baudrate = baudrate*4;
1093 actual_baudrate = ftdi_convert_baudrate(baudrate, ftdi, &value, &index);
1094 if (actual_baudrate <= 0)
1095 ftdi_error_return (-1, "Silly baudrate <= 0.");
1097 // Check within tolerance (about 5%)
1098 if ((actual_baudrate * 2 < baudrate /* Catch overflows */ )
1099 || ((actual_baudrate < baudrate)
1100 ? (actual_baudrate * 21 < baudrate * 20)
1101 : (baudrate * 21 < actual_baudrate * 20)))
1102 ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
1104 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1105 SIO_SET_BAUDRATE_REQUEST, value,
1106 index, NULL, 0, ftdi->usb_write_timeout) < 0)
1107 ftdi_error_return (-2, "Setting new baudrate failed");
1109 ftdi->baudrate = baudrate;
1114 Set (RS232) line characteristics.
1115 The break type can only be set via ftdi_set_line_property2()
1116 and defaults to "off".
1118 \param ftdi pointer to ftdi_context
1119 \param bits Number of bits
1120 \param sbit Number of stop bits
1121 \param parity Parity mode
1124 \retval -1: Setting line property failed
1126 int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1127 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
1129 return ftdi_set_line_property2(ftdi, bits, sbit, parity, BREAK_OFF);
1133 Set (RS232) line characteristics
1135 \param ftdi pointer to ftdi_context
1136 \param bits Number of bits
1137 \param sbit Number of stop bits
1138 \param parity Parity mode
1139 \param break_type Break type
1142 \retval -1: Setting line property failed
1143 \retval -2: USB device unavailable
1145 int ftdi_set_line_property2(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1146 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity,
1147 enum ftdi_break_type break_type)
1149 unsigned short value = bits;
1151 if (ftdi == NULL || ftdi->usb_dev == NULL)
1152 ftdi_error_return(-2, "USB device unavailable");
1157 value |= (0x00 << 8);
1160 value |= (0x01 << 8);
1163 value |= (0x02 << 8);
1166 value |= (0x03 << 8);
1169 value |= (0x04 << 8);
1176 value |= (0x00 << 11);
1179 value |= (0x01 << 11);
1182 value |= (0x02 << 11);
1189 value |= (0x00 << 14);
1192 value |= (0x01 << 14);
1196 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1197 SIO_SET_DATA_REQUEST, value,
1198 ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
1199 ftdi_error_return (-1, "Setting new line property failed");
1205 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip
1207 \param ftdi pointer to ftdi_context
1208 \param buf Buffer with the data
1209 \param size Size of the buffer
1211 \retval -666: USB device unavailable
1212 \retval <0: error code from usb_bulk_write()
1213 \retval >0: number of bytes written
1215 int ftdi_write_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1220 if (ftdi == NULL || ftdi->usb_dev == NULL)
1221 ftdi_error_return(-666, "USB device unavailable");
1223 while (offset < size)
1225 int write_size = ftdi->writebuffer_chunksize;
1227 if (offset+write_size > size)
1228 write_size = size-offset;
1230 if (libusb_bulk_transfer(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size, &actual_length, ftdi->usb_write_timeout) < 0)
1231 ftdi_error_return(-1, "usb bulk write failed");
1233 offset += actual_length;
1239 #ifdef LIBFTDI_LINUX_ASYNC_MODE
1240 #ifdef USB_CLASS_PTP
1241 #error LIBFTDI_LINUX_ASYNC_MODE is not compatible with libusb-compat-0.1!
1243 static void ftdi_read_data_cb(struct libusb_transfer *transfer)
1245 struct ftdi_transfer_control *tc = (struct ftdi_transfer_control *) transfer->user_data;
1246 struct ftdi_context *ftdi = tc->ftdi;
1247 int packet_size, actual_length, num_of_chunks, chunk_remains, i, ret;
1249 packet_size = ftdi->max_packet_size;
1251 actual_length = transfer->actual_length;
1253 if (actual_length > 2)
1255 // skip FTDI status bytes.
1256 // Maybe stored in the future to enable modem use
1257 num_of_chunks = actual_length / packet_size;
1258 chunk_remains = actual_length % packet_size;
1259 //printf("actual_length = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", actual_length, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
1261 ftdi->readbuffer_offset += 2;
1264 if (actual_length > packet_size - 2)
1266 for (i = 1; i < num_of_chunks; i++)
1267 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1268 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1270 if (chunk_remains > 2)
1272 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1273 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1275 actual_length -= 2*num_of_chunks;
1278 actual_length -= 2*(num_of_chunks-1)+chunk_remains;
1281 if (actual_length > 0)
1283 // data still fits in buf?
1284 if (tc->offset + actual_length <= tc->size)
1286 memcpy (tc->buf + tc->offset, ftdi->readbuffer + ftdi->readbuffer_offset, actual_length);
1287 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1288 tc->offset += actual_length;
1290 ftdi->readbuffer_offset = 0;
1291 ftdi->readbuffer_remaining = 0;
1293 /* Did we read exactly the right amount of bytes? */
1294 if (tc->offset == tc->size)
1296 //printf("read_data exact rem %d offset %d\n",
1297 //ftdi->readbuffer_remaining, offset);
1304 // only copy part of the data or size <= readbuffer_chunksize
1305 int part_size = tc->size - tc->offset;
1306 memcpy (tc->buf + tc->offset, ftdi->readbuffer + ftdi->readbuffer_offset, part_size);
1307 tc->offset += part_size;
1309 ftdi->readbuffer_offset += part_size;
1310 ftdi->readbuffer_remaining = actual_length - part_size;
1312 /* printf("Returning part: %d - size: %d - offset: %d - actual_length: %d - remaining: %d\n",
1313 part_size, size, offset, actual_length, ftdi->readbuffer_remaining); */
1319 ret = libusb_submit_transfer (transfer);
1325 static void ftdi_write_data_cb(struct libusb_transfer *transfer)
1327 struct ftdi_transfer_control *tc = (struct ftdi_transfer_control *) transfer->user_data;
1328 struct ftdi_context *ftdi = tc->ftdi;
1330 tc->offset = transfer->actual_length;
1332 if (tc->offset == tc->size)
1338 int write_size = ftdi->writebuffer_chunksize;
1341 if (tc->offset + write_size > tc->size)
1342 write_size = tc->size - tc->offset;
1344 transfer->length = write_size;
1345 transfer->buffer = tc->buf + tc->offset;
1346 ret = libusb_submit_transfer (transfer);
1354 Writes data to the chip. Does not wait for completion of the transfer
1355 nor does it make sure that the transfer was successful.
1357 Use libusb 1.0 Asynchronous API.
1358 Only available if compiled with --with-async-mode.
1360 \param ftdi pointer to ftdi_context
1361 \param buf Buffer with the data
1362 \param size Size of the buffer
1364 \retval NULL: Some error happens when submit transfer
1365 \retval !NULL: Pointer to a ftdi_transfer_control
1368 struct ftdi_transfer_control *ftdi_write_data_submit(struct ftdi_context *ftdi, unsigned char *buf, int size)
1370 struct ftdi_transfer_control *tc;
1371 struct libusb_transfer *transfer = libusb_alloc_transfer(0);
1372 int write_size, ret;
1374 if (ftdi == NULL || ftdi->usb_dev == NULL)
1376 libusb_free_transfer(transfer);
1380 tc = (struct ftdi_transfer_control *) malloc (sizeof (*tc));
1382 if (!tc || !transfer)
1391 if (size < ftdi->writebuffer_chunksize)
1394 write_size = ftdi->writebuffer_chunksize;
1396 libusb_fill_bulk_transfer(transfer, ftdi->usb_dev, ftdi->in_ep, buf, write_size, ftdi_write_data_cb, tc, ftdi->usb_write_timeout);
1397 transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
1399 ret = libusb_submit_transfer(transfer);
1402 libusb_free_transfer(transfer);
1404 tc->transfer = NULL;
1407 tc->transfer = transfer;
1413 Reads data from the chip. Does not wait for completion of the transfer
1414 nor does it make sure that the transfer was successful.
1416 Use libusb 1.0 Asynchronous API.
1417 Only available if compiled with --with-async-mode.
1419 \param ftdi pointer to ftdi_context
1420 \param buf Buffer with the data
1421 \param size Size of the buffer
1423 \retval NULL: Some error happens when submit transfer
1424 \retval !NULL: Pointer to a ftdi_transfer_control
1427 struct ftdi_transfer_control *ftdi_read_data_submit(struct ftdi_context *ftdi, unsigned char *buf, int size)
1429 struct ftdi_transfer_control *tc;
1430 struct libusb_transfer *transfer;
1433 if (ftdi == NULL || ftdi->usb_dev == NULL)
1436 tc = (struct ftdi_transfer_control *) malloc (sizeof (*tc));
1444 if (size <= ftdi->readbuffer_remaining)
1446 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1449 ftdi->readbuffer_remaining -= size;
1450 ftdi->readbuffer_offset += size;
1452 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1456 tc->transfer = NULL;
1461 if (ftdi->readbuffer_remaining != 0)
1463 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1465 tc->offset = ftdi->readbuffer_remaining;
1470 transfer = libusb_alloc_transfer(0);
1477 ftdi->readbuffer_remaining = 0;
1478 ftdi->readbuffer_offset = 0;
1480 libusb_fill_bulk_transfer(transfer, ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, ftdi_read_data_cb, tc, ftdi->usb_read_timeout);
1481 transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
1483 ret = libusb_submit_transfer(transfer);
1486 libusb_free_transfer(transfer);
1490 tc->transfer = transfer;
1496 Wait for completion of the transfer.
1498 Use libusb 1.0 Asynchronous API.
1499 Only available if compiled with --with-async-mode.
1501 \param tc pointer to ftdi_transfer_control
1503 \retval < 0: Some error happens
1504 \retval >= 0: Data size transferred
1507 int ftdi_transfer_data_done(struct ftdi_transfer_control *tc)
1511 while (!tc->completed)
1513 ret = libusb_handle_events(tc->ftdi->usb_ctx);
1516 if (ret == LIBUSB_ERROR_INTERRUPTED)
1518 libusb_cancel_transfer(tc->transfer);
1519 while (!tc->completed)
1520 if (libusb_handle_events(tc->ftdi->usb_ctx) < 0)
1522 libusb_free_transfer(tc->transfer);
1529 if (tc->transfer->status == LIBUSB_TRANSFER_COMPLETED)
1534 libusb_free_transfer(tc->transfer);
1539 #endif // LIBFTDI_LINUX_ASYNC_MODE
1542 Configure write buffer chunk size.
1545 \param ftdi pointer to ftdi_context
1546 \param chunksize Chunk size
1549 \retval -1: ftdi context invalid
1551 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1554 ftdi_error_return(-1, "ftdi context invalid");
1556 ftdi->writebuffer_chunksize = chunksize;
1561 Get write buffer chunk size.
1563 \param ftdi pointer to ftdi_context
1564 \param chunksize Pointer to store chunk size in
1567 \retval -1: ftdi context invalid
1569 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1572 ftdi_error_return(-1, "ftdi context invalid");
1574 *chunksize = ftdi->writebuffer_chunksize;
1579 Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
1581 Automatically strips the two modem status bytes transfered during every read.
1583 \param ftdi pointer to ftdi_context
1584 \param buf Buffer to store data in
1585 \param size Size of the buffer
1587 \retval -666: USB device unavailable
1588 \retval <0: error code from libusb_bulk_transfer()
1589 \retval 0: no data was available
1590 \retval >0: number of bytes read
1593 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1595 int offset = 0, ret, i, num_of_chunks, chunk_remains;
1596 int packet_size = ftdi->max_packet_size;
1597 int actual_length = 1;
1599 if (ftdi == NULL || ftdi->usb_dev == NULL)
1600 ftdi_error_return(-666, "USB device unavailable");
1602 // Packet size sanity check (avoid division by zero)
1603 if (packet_size == 0)
1604 ftdi_error_return(-1, "max_packet_size is bogus (zero)");
1606 // everything we want is still in the readbuffer?
1607 if (size <= ftdi->readbuffer_remaining)
1609 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1612 ftdi->readbuffer_remaining -= size;
1613 ftdi->readbuffer_offset += size;
1615 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1619 // something still in the readbuffer, but not enough to satisfy 'size'?
1620 if (ftdi->readbuffer_remaining != 0)
1622 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1625 offset += ftdi->readbuffer_remaining;
1627 // do the actual USB read
1628 while (offset < size && actual_length > 0)
1630 ftdi->readbuffer_remaining = 0;
1631 ftdi->readbuffer_offset = 0;
1632 /* returns how much received */
1633 ret = libusb_bulk_transfer (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, &actual_length, ftdi->usb_read_timeout);
1635 ftdi_error_return(ret, "usb bulk read failed");
1637 if (actual_length > 2)
1639 // skip FTDI status bytes.
1640 // Maybe stored in the future to enable modem use
1641 num_of_chunks = actual_length / packet_size;
1642 chunk_remains = actual_length % packet_size;
1643 //printf("actual_length = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", actual_length, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
1645 ftdi->readbuffer_offset += 2;
1648 if (actual_length > packet_size - 2)
1650 for (i = 1; i < num_of_chunks; i++)
1651 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1652 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1654 if (chunk_remains > 2)
1656 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1657 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1659 actual_length -= 2*num_of_chunks;
1662 actual_length -= 2*(num_of_chunks-1)+chunk_remains;
1665 else if (actual_length <= 2)
1667 // no more data to read?
1670 if (actual_length > 0)
1672 // data still fits in buf?
1673 if (offset+actual_length <= size)
1675 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, actual_length);
1676 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1677 offset += actual_length;
1679 /* Did we read exactly the right amount of bytes? */
1681 //printf("read_data exact rem %d offset %d\n",
1682 //ftdi->readbuffer_remaining, offset);
1687 // only copy part of the data or size <= readbuffer_chunksize
1688 int part_size = size-offset;
1689 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
1691 ftdi->readbuffer_offset += part_size;
1692 ftdi->readbuffer_remaining = actual_length-part_size;
1693 offset += part_size;
1695 /* printf("Returning part: %d - size: %d - offset: %d - actual_length: %d - remaining: %d\n",
1696 part_size, size, offset, actual_length, ftdi->readbuffer_remaining); */
1707 Configure read buffer chunk size.
1710 Automatically reallocates the buffer.
1712 \param ftdi pointer to ftdi_context
1713 \param chunksize Chunk size
1716 \retval -1: ftdi context invalid
1718 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1720 unsigned char *new_buf;
1723 ftdi_error_return(-1, "ftdi context invalid");
1725 // Invalidate all remaining data
1726 ftdi->readbuffer_offset = 0;
1727 ftdi->readbuffer_remaining = 0;
1729 /* We can't set readbuffer_chunksize larger than MAX_BULK_BUFFER_LENGTH,
1730 which is defined in libusb-1.0. Otherwise, each USB read request will
1731 be divided into multiple URBs. This will cause issues on Linux kernel
1732 older than 2.6.32. */
1733 if (chunksize > 16384)
1737 if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
1738 ftdi_error_return(-1, "out of memory for readbuffer");
1740 ftdi->readbuffer = new_buf;
1741 ftdi->readbuffer_chunksize = chunksize;
1747 Get read buffer chunk size.
1749 \param ftdi pointer to ftdi_context
1750 \param chunksize Pointer to store chunk size in
1753 \retval -1: FTDI context invalid
1755 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1758 ftdi_error_return(-1, "FTDI context invalid");
1760 *chunksize = ftdi->readbuffer_chunksize;
1766 Enable bitbang mode.
1768 \deprecated use \ref ftdi_set_bitmode with mode BITMODE_BITBANG instead
1770 \param ftdi pointer to ftdi_context
1771 \param bitmask Bitmask to configure lines.
1772 HIGH/ON value configures a line as output.
1775 \retval -1: can't enable bitbang mode
1776 \retval -2: USB device unavailable
1778 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
1780 unsigned short usb_val;
1782 if (ftdi == NULL || ftdi->usb_dev == NULL)
1783 ftdi_error_return(-2, "USB device unavailable");
1785 usb_val = bitmask; // low byte: bitmask
1786 /* FT2232C: Set bitbang_mode to 2 to enable SPI */
1787 usb_val |= (ftdi->bitbang_mode << 8);
1789 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1790 SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index,
1791 NULL, 0, ftdi->usb_write_timeout) < 0)
1792 ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
1794 ftdi->bitbang_enabled = 1;
1799 Disable bitbang mode.
1801 \param ftdi pointer to ftdi_context
1804 \retval -1: can't disable bitbang mode
1805 \retval -2: USB device unavailable
1807 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
1809 if (ftdi == NULL || ftdi->usb_dev == NULL)
1810 ftdi_error_return(-2, "USB device unavailable");
1812 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_BITMODE_REQUEST, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
1813 ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
1815 ftdi->bitbang_enabled = 0;
1820 Enable/disable bitbang modes.
1822 \param ftdi pointer to ftdi_context
1823 \param bitmask Bitmask to configure lines.
1824 HIGH/ON value configures a line as output.
1825 \param mode Bitbang mode: use the values defined in \ref ftdi_mpsse_mode
1828 \retval -1: can't enable bitbang mode
1829 \retval -2: USB device unavailable
1831 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
1833 unsigned short usb_val;
1835 if (ftdi == NULL || ftdi->usb_dev == NULL)
1836 ftdi_error_return(-2, "USB device unavailable");
1838 usb_val = bitmask; // low byte: bitmask
1839 usb_val |= (mode << 8);
1840 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
1841 ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps not a 2232C type chip?");
1843 ftdi->bitbang_mode = mode;
1844 ftdi->bitbang_enabled = (mode == BITMODE_RESET) ? 0 : 1;
1849 Directly read pin state, circumventing the read buffer. Useful for bitbang mode.
1851 \param ftdi pointer to ftdi_context
1852 \param pins Pointer to store pins into
1855 \retval -1: read pins failed
1856 \retval -2: USB device unavailable
1858 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
1860 if (ftdi == NULL || ftdi->usb_dev == NULL)
1861 ftdi_error_return(-2, "USB device unavailable");
1863 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_PINS_REQUEST, 0, ftdi->index, (unsigned char *)pins, 1, ftdi->usb_read_timeout) != 1)
1864 ftdi_error_return(-1, "read pins failed");
1872 The FTDI chip keeps data in the internal buffer for a specific
1873 amount of time if the buffer is not full yet to decrease
1874 load on the usb bus.
1876 \param ftdi pointer to ftdi_context
1877 \param latency Value between 1 and 255
1880 \retval -1: latency out of range
1881 \retval -2: unable to set latency timer
1882 \retval -3: USB device unavailable
1884 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
1886 unsigned short usb_val;
1889 ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
1891 if (ftdi == NULL || ftdi->usb_dev == NULL)
1892 ftdi_error_return(-3, "USB device unavailable");
1895 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_LATENCY_TIMER_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
1896 ftdi_error_return(-2, "unable to set latency timer");
1904 \param ftdi pointer to ftdi_context
1905 \param latency Pointer to store latency value in
1908 \retval -1: unable to get latency timer
1909 \retval -2: USB device unavailable
1911 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1913 unsigned short usb_val;
1915 if (ftdi == NULL || ftdi->usb_dev == NULL)
1916 ftdi_error_return(-2, "USB device unavailable");
1918 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_GET_LATENCY_TIMER_REQUEST, 0, ftdi->index, (unsigned char *)&usb_val, 1, ftdi->usb_read_timeout) != 1)
1919 ftdi_error_return(-1, "reading latency timer failed");
1921 *latency = (unsigned char)usb_val;
1926 Poll modem status information
1928 This function allows the retrieve the two status bytes of the device.
1929 The device sends these bytes also as a header for each read access
1930 where they are discarded by ftdi_read_data(). The chip generates
1931 the two stripped status bytes in the absence of data every 40 ms.
1933 Layout of the first byte:
1934 - B0..B3 - must be 0
1935 - B4 Clear to send (CTS)
1938 - B5 Data set ready (DTS)
1941 - B6 Ring indicator (RI)
1944 - B7 Receive line signal detect (RLSD)
1948 Layout of the second byte:
1949 - B0 Data ready (DR)
1950 - B1 Overrun error (OE)
1951 - B2 Parity error (PE)
1952 - B3 Framing error (FE)
1953 - B4 Break interrupt (BI)
1954 - B5 Transmitter holding register (THRE)
1955 - B6 Transmitter empty (TEMT)
1956 - B7 Error in RCVR FIFO
1958 \param ftdi pointer to ftdi_context
1959 \param status Pointer to store status information in. Must be two bytes.
1962 \retval -1: unable to retrieve status information
1963 \retval -2: USB device unavailable
1965 int ftdi_poll_modem_status(struct ftdi_context *ftdi, unsigned short *status)
1969 if (ftdi == NULL || ftdi->usb_dev == NULL)
1970 ftdi_error_return(-2, "USB device unavailable");
1972 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_POLL_MODEM_STATUS_REQUEST, 0, ftdi->index, (unsigned char *)usb_val, 2, ftdi->usb_read_timeout) != 2)
1973 ftdi_error_return(-1, "getting modem status failed");
1975 *status = (usb_val[1] << 8) | usb_val[0];
1981 Set flowcontrol for ftdi chip
1983 \param ftdi pointer to ftdi_context
1984 \param flowctrl flow control to use. should be
1985 SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1988 \retval -1: set flow control failed
1989 \retval -2: USB device unavailable
1991 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1993 if (ftdi == NULL || ftdi->usb_dev == NULL)
1994 ftdi_error_return(-2, "USB device unavailable");
1996 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1997 SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->index),
1998 NULL, 0, ftdi->usb_write_timeout) < 0)
1999 ftdi_error_return(-1, "set flow control failed");
2007 \param ftdi pointer to ftdi_context
2008 \param state state to set line to (1 or 0)
2011 \retval -1: set dtr failed
2012 \retval -2: USB device unavailable
2014 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
2016 unsigned short usb_val;
2018 if (ftdi == NULL || ftdi->usb_dev == NULL)
2019 ftdi_error_return(-2, "USB device unavailable");
2022 usb_val = SIO_SET_DTR_HIGH;
2024 usb_val = SIO_SET_DTR_LOW;
2026 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2027 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
2028 NULL, 0, ftdi->usb_write_timeout) < 0)
2029 ftdi_error_return(-1, "set dtr failed");
2037 \param ftdi pointer to ftdi_context
2038 \param state state to set line to (1 or 0)
2041 \retval -1: set rts failed
2042 \retval -2: USB device unavailable
2044 int ftdi_setrts(struct ftdi_context *ftdi, int state)
2046 unsigned short usb_val;
2048 if (ftdi == NULL || ftdi->usb_dev == NULL)
2049 ftdi_error_return(-2, "USB device unavailable");
2052 usb_val = SIO_SET_RTS_HIGH;
2054 usb_val = SIO_SET_RTS_LOW;
2056 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2057 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
2058 NULL, 0, ftdi->usb_write_timeout) < 0)
2059 ftdi_error_return(-1, "set of rts failed");
2065 Set dtr and rts line in one pass
2067 \param ftdi pointer to ftdi_context
2068 \param dtr DTR state to set line to (1 or 0)
2069 \param rts RTS state to set line to (1 or 0)
2072 \retval -1: set dtr/rts failed
2073 \retval -2: USB device unavailable
2075 int ftdi_setdtr_rts(struct ftdi_context *ftdi, int dtr, int rts)
2077 unsigned short usb_val;
2079 if (ftdi == NULL || ftdi->usb_dev == NULL)
2080 ftdi_error_return(-2, "USB device unavailable");
2083 usb_val = SIO_SET_DTR_HIGH;
2085 usb_val = SIO_SET_DTR_LOW;
2088 usb_val |= SIO_SET_RTS_HIGH;
2090 usb_val |= SIO_SET_RTS_LOW;
2092 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2093 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
2094 NULL, 0, ftdi->usb_write_timeout) < 0)
2095 ftdi_error_return(-1, "set of rts/dtr failed");
2101 Set the special event character
2103 \param ftdi pointer to ftdi_context
2104 \param eventch Event character
2105 \param enable 0 to disable the event character, non-zero otherwise
2108 \retval -1: unable to set event character
2109 \retval -2: USB device unavailable
2111 int ftdi_set_event_char(struct ftdi_context *ftdi,
2112 unsigned char eventch, unsigned char enable)
2114 unsigned short usb_val;
2116 if (ftdi == NULL || ftdi->usb_dev == NULL)
2117 ftdi_error_return(-2, "USB device unavailable");
2123 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_EVENT_CHAR_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
2124 ftdi_error_return(-1, "setting event character failed");
2132 \param ftdi pointer to ftdi_context
2133 \param errorch Error character
2134 \param enable 0 to disable the error character, non-zero otherwise
2137 \retval -1: unable to set error character
2138 \retval -2: USB device unavailable
2140 int ftdi_set_error_char(struct ftdi_context *ftdi,
2141 unsigned char errorch, unsigned char enable)
2143 unsigned short usb_val;
2145 if (ftdi == NULL || ftdi->usb_dev == NULL)
2146 ftdi_error_return(-2, "USB device unavailable");
2152 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_ERROR_CHAR_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) < 0)
2153 ftdi_error_return(-1, "setting error character failed");
2161 \param ftdi pointer to ftdi_context
2162 \param eeprom Pointer to ftdi_eeprom
2166 void ftdi_eeprom_setsize(struct ftdi_context *ftdi, struct ftdi_eeprom *eeprom, int size)
2171 ftdi->eeprom_size=size;
2176 Init eeprom with default values.
2178 \param eeprom Pointer to ftdi_eeprom
2180 void ftdi_eeprom_initdefaults(struct ftdi_eeprom *eeprom)
2185 eeprom->vendor_id = 0x0403;
2186 eeprom->product_id = 0x6001;
2188 eeprom->self_powered = 1;
2189 eeprom->remote_wakeup = 1;
2190 eeprom->BM_type_chip = 1;
2192 eeprom->in_is_isochronous = 0;
2193 eeprom->out_is_isochronous = 0;
2194 eeprom->suspend_pull_downs = 0;
2196 eeprom->use_serial = 0;
2197 eeprom->change_usb_version = 0;
2198 eeprom->usb_version = 0x0200;
2199 eeprom->max_power = 0;
2201 eeprom->manufacturer = NULL;
2202 eeprom->product = NULL;
2203 eeprom->serial = NULL;
2205 eeprom->size = FTDI_DEFAULT_EEPROM_SIZE;
2209 Frees allocated memory in eeprom.
2211 \param eeprom Pointer to ftdi_eeprom
2213 void ftdi_eeprom_free(struct ftdi_eeprom *eeprom)
2215 if (eeprom->manufacturer != 0) {
2216 free(eeprom->manufacturer);
2217 eeprom->manufacturer = 0;
2219 if (eeprom->product != 0) {
2220 free(eeprom->product);
2221 eeprom->product = 0;
2223 if (eeprom->serial != 0) {
2224 free(eeprom->serial);
2230 Build binary output from ftdi_eeprom structure.
2231 Output is suitable for ftdi_write_eeprom().
2233 \param eeprom Pointer to ftdi_eeprom
2234 \param output Buffer of 128 bytes to store eeprom image to
2236 \retval >0: used eeprom size
2237 \retval -1: eeprom size (128 bytes) exceeded by custom strings
2238 \retval -2: Invalid eeprom pointer
2240 int ftdi_eeprom_build(struct ftdi_eeprom *eeprom, unsigned char *output)
2243 unsigned short checksum, value;
2244 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2250 if (eeprom->manufacturer != NULL)
2251 manufacturer_size = strlen(eeprom->manufacturer);
2252 if (eeprom->product != NULL)
2253 product_size = strlen(eeprom->product);
2254 if (eeprom->serial != NULL)
2255 serial_size = strlen(eeprom->serial);
2257 size_check = eeprom->size;
2258 size_check -= 28; // 28 are always in use (fixed)
2260 // Top half of a 256byte eeprom is used just for strings and checksum
2261 // it seems that the FTDI chip will not read these strings from the lower half
2262 // Each string starts with two bytes; offset and type (0x03 for string)
2263 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2264 if (eeprom->size>=256)size_check = 120;
2265 size_check -= manufacturer_size*2;
2266 size_check -= product_size*2;
2267 size_check -= serial_size*2;
2269 // eeprom size exceeded?
2274 memset (output, 0, eeprom->size);
2276 // Addr 00: Stay 00 00
2277 // Addr 02: Vendor ID
2278 output[0x02] = eeprom->vendor_id;
2279 output[0x03] = eeprom->vendor_id >> 8;
2281 // Addr 04: Product ID
2282 output[0x04] = eeprom->product_id;
2283 output[0x05] = eeprom->product_id >> 8;
2285 // Addr 06: Device release number (0400h for BM features)
2286 output[0x06] = 0x00;
2288 if (eeprom->BM_type_chip == 1)
2289 output[0x07] = 0x04;
2291 output[0x07] = 0x02;
2293 // Addr 08: Config descriptor
2295 // Bit 6: 1 if this device is self powered, 0 if bus powered
2296 // Bit 5: 1 if this device uses remote wakeup
2297 // Bit 4: 1 if this device is battery powered
2299 if (eeprom->self_powered == 1)
2301 if (eeprom->remote_wakeup == 1)
2305 // Addr 09: Max power consumption: max power = value * 2 mA
2306 output[0x09] = eeprom->max_power;
2308 // Addr 0A: Chip configuration
2309 // Bit 7: 0 - reserved
2310 // Bit 6: 0 - reserved
2311 // Bit 5: 0 - reserved
2312 // Bit 4: 1 - Change USB version
2313 // Bit 3: 1 - Use the serial number string
2314 // Bit 2: 1 - Enable suspend pull downs for lower power
2315 // Bit 1: 1 - Out EndPoint is Isochronous
2316 // Bit 0: 1 - In EndPoint is Isochronous
2319 if (eeprom->in_is_isochronous == 1)
2321 if (eeprom->out_is_isochronous == 1)
2323 if (eeprom->suspend_pull_downs == 1)
2325 if (eeprom->use_serial == 1)
2327 if (eeprom->change_usb_version == 1)
2331 // Addr 0B: reserved
2332 output[0x0B] = 0x00;
2334 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2335 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2336 if (eeprom->change_usb_version == 1)
2338 output[0x0C] = eeprom->usb_version;
2339 output[0x0D] = eeprom->usb_version >> 8;
2343 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2344 // Addr 0F: Length of manufacturer string
2345 output[0x0F] = manufacturer_size*2 + 2;
2347 // Addr 10: Offset of the product string + 0x80, calculated later
2348 // Addr 11: Length of product string
2349 output[0x11] = product_size*2 + 2;
2351 // Addr 12: Offset of the serial string + 0x80, calculated later
2352 // Addr 13: Length of serial string
2353 output[0x13] = serial_size*2 + 2;
2357 if (eeprom->size>=256) i = 0x80;
2360 // Output manufacturer
2361 output[0x0E] = i | 0x80; // calculate offset
2362 output[i++] = manufacturer_size*2 + 2;
2363 output[i++] = 0x03; // type: string
2364 for (j = 0; j < manufacturer_size; j++)
2366 output[i] = eeprom->manufacturer[j], i++;
2367 output[i] = 0x00, i++;
2370 // Output product name
2371 output[0x10] = i | 0x80; // calculate offset
2372 output[i] = product_size*2 + 2, i++;
2373 output[i] = 0x03, i++;
2374 for (j = 0; j < product_size; j++)
2376 output[i] = eeprom->product[j], i++;
2377 output[i] = 0x00, i++;
2381 output[0x12] = i | 0x80; // calculate offset
2382 output[i] = serial_size*2 + 2, i++;
2383 output[i] = 0x03, i++;
2384 for (j = 0; j < serial_size; j++)
2386 output[i] = eeprom->serial[j], i++;
2387 output[i] = 0x00, i++;
2390 // calculate checksum
2393 for (i = 0; i < eeprom->size/2-1; i++)
2395 value = output[i*2];
2396 value += output[(i*2)+1] << 8;
2398 checksum = value^checksum;
2399 checksum = (checksum << 1) | (checksum >> 15);
2402 output[eeprom->size-2] = checksum;
2403 output[eeprom->size-1] = checksum >> 8;
2409 Decode binary EEPROM image into an ftdi_eeprom structure.
2411 \param eeprom Pointer to ftdi_eeprom which will be filled in.
2412 \param buf Buffer of \a size bytes of raw eeprom data
2413 \param size size size of eeprom data in bytes
2416 \retval -1: something went wrong
2418 FIXME: How to pass size? How to handle size field in ftdi_eeprom?
2419 FIXME: Strings are malloc'ed here and should be freed somewhere
2421 int ftdi_eeprom_decode(struct ftdi_eeprom *eeprom, unsigned char *buf, int size)
2424 unsigned short checksum, eeprom_checksum, value;
2425 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2426 int eeprom_size = 128;
2431 size_check = eeprom->size;
2432 size_check -= 28; // 28 are always in use (fixed)
2434 // Top half of a 256byte eeprom is used just for strings and checksum
2435 // it seems that the FTDI chip will not read these strings from the lower half
2436 // Each string starts with two bytes; offset and type (0x03 for string)
2437 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2438 if (eeprom->size>=256)size_check = 120;
2439 size_check -= manufacturer_size*2;
2440 size_check -= product_size*2;
2441 size_check -= serial_size*2;
2443 // eeprom size exceeded?
2448 // empty eeprom struct
2449 memset(eeprom, 0, sizeof(struct ftdi_eeprom));
2451 // Addr 00: Stay 00 00
2453 // Addr 02: Vendor ID
2454 eeprom->vendor_id = buf[0x02] + (buf[0x03] << 8);
2456 // Addr 04: Product ID
2457 eeprom->product_id = buf[0x04] + (buf[0x05] << 8);
2459 value = buf[0x06] + (buf[0x07]<<8);
2463 eeprom->BM_type_chip = 1;
2466 eeprom->BM_type_chip = 0;
2468 default: // Unknown device
2469 eeprom->BM_type_chip = 0;
2473 // Addr 08: Config descriptor
2475 // Bit 6: 1 if this device is self powered, 0 if bus powered
2476 // Bit 5: 1 if this device uses remote wakeup
2477 // Bit 4: 1 if this device is battery powered
2479 if (j&0x40) eeprom->self_powered = 1;
2480 if (j&0x20) eeprom->remote_wakeup = 1;
2482 // Addr 09: Max power consumption: max power = value * 2 mA
2483 eeprom->max_power = buf[0x09];
2485 // Addr 0A: Chip configuration
2486 // Bit 7: 0 - reserved
2487 // Bit 6: 0 - reserved
2488 // Bit 5: 0 - reserved
2489 // Bit 4: 1 - Change USB version
2490 // Bit 3: 1 - Use the serial number string
2491 // Bit 2: 1 - Enable suspend pull downs for lower power
2492 // Bit 1: 1 - Out EndPoint is Isochronous
2493 // Bit 0: 1 - In EndPoint is Isochronous
2496 if (j&0x01) eeprom->in_is_isochronous = 1;
2497 if (j&0x02) eeprom->out_is_isochronous = 1;
2498 if (j&0x04) eeprom->suspend_pull_downs = 1;
2499 if (j&0x08) eeprom->use_serial = 1;
2500 if (j&0x10) eeprom->change_usb_version = 1;
2502 // Addr 0B: reserved
2504 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2505 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2506 if (eeprom->change_usb_version == 1)
2508 eeprom->usb_version = buf[0x0C] + (buf[0x0D] << 8);
2511 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2512 // Addr 0F: Length of manufacturer string
2513 manufacturer_size = buf[0x0F]/2;
2514 if (manufacturer_size > 0) eeprom->manufacturer = malloc(manufacturer_size);
2515 else eeprom->manufacturer = NULL;
2517 // Addr 10: Offset of the product string + 0x80, calculated later
2518 // Addr 11: Length of product string
2519 product_size = buf[0x11]/2;
2520 if (product_size > 0) eeprom->product = malloc(product_size);
2521 else eeprom->product = NULL;
2523 // Addr 12: Offset of the serial string + 0x80, calculated later
2524 // Addr 13: Length of serial string
2525 serial_size = buf[0x13]/2;
2526 if (serial_size > 0) eeprom->serial = malloc(serial_size);
2527 else eeprom->serial = NULL;
2529 // Decode manufacturer
2530 i = buf[0x0E] & 0x7f; // offset
2531 for (j=0;j<manufacturer_size-1;j++)
2533 eeprom->manufacturer[j] = buf[2*j+i+2];
2535 eeprom->manufacturer[j] = '\0';
2537 // Decode product name
2538 i = buf[0x10] & 0x7f; // offset
2539 for (j=0;j<product_size-1;j++)
2541 eeprom->product[j] = buf[2*j+i+2];
2543 eeprom->product[j] = '\0';
2546 i = buf[0x12] & 0x7f; // offset
2547 for (j=0;j<serial_size-1;j++)
2549 eeprom->serial[j] = buf[2*j+i+2];
2551 eeprom->serial[j] = '\0';
2556 for (i = 0; i < eeprom_size/2-1; i++)
2559 value += buf[(i*2)+1] << 8;
2561 checksum = value^checksum;
2562 checksum = (checksum << 1) | (checksum >> 15);
2565 eeprom_checksum = buf[eeprom_size-2] + (buf[eeprom_size-1] << 8);
2567 if (eeprom_checksum != checksum)
2569 fprintf(stderr, "Checksum Error: %04x %04x\n", checksum, eeprom_checksum);
2577 Read eeprom location
2579 \param ftdi pointer to ftdi_context
2580 \param eeprom_addr Address of eeprom location to be read
2581 \param eeprom_val Pointer to store read eeprom location
2584 \retval -1: read failed
2585 \retval -2: USB device unavailable
2587 int ftdi_read_eeprom_location (struct ftdi_context *ftdi, int eeprom_addr, unsigned short *eeprom_val)
2589 if (ftdi == NULL || ftdi->usb_dev == NULL)
2590 ftdi_error_return(-2, "USB device unavailable");
2592 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, eeprom_addr, (char *)eeprom_val, 2, ftdi->usb_read_timeout) != 2)
2593 ftdi_error_return(-1, "reading eeprom failed");
2601 \param ftdi pointer to ftdi_context
2602 \param eeprom Pointer to store eeprom into
2605 \retval -1: read failed
2606 \retval -2: USB device unavailable
2608 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2612 if (ftdi == NULL || ftdi->usb_dev == NULL)
2613 ftdi_error_return(-2, "USB device unavailable");
2615 for (i = 0; i < ftdi->eeprom_size/2; i++)
2617 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, i, eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2618 ftdi_error_return(-1, "reading eeprom failed");
2625 ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
2626 Function is only used internally
2629 static unsigned char ftdi_read_chipid_shift(unsigned char value)
2631 return ((value & 1) << 1) |
2632 ((value & 2) << 5) |
2633 ((value & 4) >> 2) |
2634 ((value & 8) << 4) |
2635 ((value & 16) >> 1) |
2636 ((value & 32) >> 1) |
2637 ((value & 64) >> 4) |
2638 ((value & 128) >> 2);
2642 Read the FTDIChip-ID from R-type devices
2644 \param ftdi pointer to ftdi_context
2645 \param chipid Pointer to store FTDIChip-ID
2648 \retval -1: read failed
2649 \retval -2: USB device unavailable
2651 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
2653 unsigned int a = 0, b = 0;
2655 if (ftdi == NULL || ftdi->usb_dev == NULL)
2656 ftdi_error_return(-2, "USB device unavailable");
2658 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, 0x43, (unsigned char *)&a, 2, ftdi->usb_read_timeout) == 2)
2660 a = a << 8 | a >> 8;
2661 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, 0x44, (unsigned char *)&b, 2, ftdi->usb_read_timeout) == 2)
2663 b = b << 8 | b >> 8;
2664 a = (a << 16) | (b & 0xFFFF);
2665 a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8
2666 | ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
2667 *chipid = a ^ 0xa5f0f7d1;
2672 ftdi_error_return(-1, "read of FTDIChip-ID failed");
2676 Guesses size of eeprom by reading eeprom and comparing halves - will not work with blank eeprom
2677 Call this function then do a write then call again to see if size changes, if so write again.
2679 \param ftdi pointer to ftdi_context
2680 \param eeprom Pointer to store eeprom into
2681 \param maxsize the size of the buffer to read into
2683 \retval -1: eeprom read failed
2684 \retval -2: USB device unavailable
2685 \retval >=0: size of eeprom
2687 int ftdi_read_eeprom_getsize(struct ftdi_context *ftdi, unsigned char *eeprom, int maxsize)
2689 int i=0,j,minsize=32;
2692 if (ftdi == NULL || ftdi->usb_dev == NULL)
2693 ftdi_error_return(-2, "USB device unavailable");
2697 for (j = 0; i < maxsize/2 && j<size; j++)
2699 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE,
2700 SIO_READ_EEPROM_REQUEST, 0, i,
2701 eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2702 ftdi_error_return(-1, "eeprom read failed");
2707 while (size<=maxsize && memcmp(eeprom,&eeprom[size/2],size/2)!=0);
2713 Write eeprom location
2715 \param ftdi pointer to ftdi_context
2716 \param eeprom_addr Address of eeprom location to be written
2717 \param eeprom_val Value to be written
2720 \retval -1: read failed
2721 \retval -2: USB device unavailable
2723 int ftdi_write_eeprom_location(struct ftdi_context *ftdi, int eeprom_addr, unsigned short eeprom_val)
2725 if (ftdi == NULL || ftdi->usb_dev == NULL)
2726 ftdi_error_return(-2, "USB device unavailable");
2728 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2729 SIO_WRITE_EEPROM_REQUEST, eeprom_val, eeprom_addr,
2730 NULL, 0, ftdi->usb_write_timeout) != 0)
2731 ftdi_error_return(-1, "unable to write eeprom");
2739 \param ftdi pointer to ftdi_context
2740 \param eeprom Pointer to read eeprom from
2743 \retval -1: read failed
2744 \retval -2: USB device unavailable
2746 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2748 unsigned short usb_val, status;
2751 if (ftdi == NULL || ftdi->usb_dev == NULL)
2752 ftdi_error_return(-2, "USB device unavailable");
2754 /* These commands were traced while running MProg */
2755 if ((ret = ftdi_usb_reset(ftdi)) != 0)
2757 if ((ret = ftdi_poll_modem_status(ftdi, &status)) != 0)
2759 if ((ret = ftdi_set_latency_timer(ftdi, 0x77)) != 0)
2762 for (i = 0; i < ftdi->eeprom_size/2; i++)
2764 usb_val = eeprom[i*2];
2765 usb_val += eeprom[(i*2)+1] << 8;
2766 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2767 SIO_WRITE_EEPROM_REQUEST, usb_val, i,
2768 NULL, 0, ftdi->usb_write_timeout) < 0)
2769 ftdi_error_return(-1, "unable to write eeprom");
2778 This is not supported on FT232R/FT245R according to the MProg manual from FTDI.
2780 \param ftdi pointer to ftdi_context
2783 \retval -1: erase failed
2784 \retval -2: USB device unavailable
2786 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
2788 if (ftdi == NULL || ftdi->usb_dev == NULL)
2789 ftdi_error_return(-2, "USB device unavailable");
2791 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_ERASE_EEPROM_REQUEST, 0, 0, NULL, 0, ftdi->usb_write_timeout) < 0)
2792 ftdi_error_return(-1, "unable to erase eeprom");
2798 Get string representation for last error code
2800 \param ftdi pointer to ftdi_context
2802 \retval Pointer to error string
2804 char *ftdi_get_error_string (struct ftdi_context *ftdi)
2809 return ftdi->error_str;
2812 /* @} end of doxygen libftdi group */