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;
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 static void ftdi_read_data_cb(struct libusb_transfer *transfer)
1241 struct ftdi_transfer_control *tc = (struct ftdi_transfer_control *) transfer->user_data;
1242 struct ftdi_context *ftdi = tc->ftdi;
1243 int packet_size, actual_length, num_of_chunks, chunk_remains, i, ret;
1245 packet_size = ftdi->max_packet_size;
1247 actual_length = transfer->actual_length;
1249 if (actual_length > 2)
1251 // skip FTDI status bytes.
1252 // Maybe stored in the future to enable modem use
1253 num_of_chunks = actual_length / packet_size;
1254 chunk_remains = actual_length % packet_size;
1255 //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);
1257 ftdi->readbuffer_offset += 2;
1260 if (actual_length > packet_size - 2)
1262 for (i = 1; i < num_of_chunks; i++)
1263 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1264 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1266 if (chunk_remains > 2)
1268 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1269 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1271 actual_length -= 2*num_of_chunks;
1274 actual_length -= 2*(num_of_chunks-1)+chunk_remains;
1277 if (actual_length > 0)
1279 // data still fits in buf?
1280 if (tc->offset + actual_length <= tc->size)
1282 memcpy (tc->buf + tc->offset, ftdi->readbuffer + ftdi->readbuffer_offset, actual_length);
1283 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1284 tc->offset += actual_length;
1286 ftdi->readbuffer_offset = 0;
1287 ftdi->readbuffer_remaining = 0;
1289 /* Did we read exactly the right amount of bytes? */
1290 if (tc->offset == tc->size)
1292 //printf("read_data exact rem %d offset %d\n",
1293 //ftdi->readbuffer_remaining, offset);
1300 // only copy part of the data or size <= readbuffer_chunksize
1301 int part_size = tc->size - tc->offset;
1302 memcpy (tc->buf + tc->offset, ftdi->readbuffer + ftdi->readbuffer_offset, part_size);
1303 tc->offset += part_size;
1305 ftdi->readbuffer_offset += part_size;
1306 ftdi->readbuffer_remaining = actual_length - part_size;
1308 /* printf("Returning part: %d - size: %d - offset: %d - actual_length: %d - remaining: %d\n",
1309 part_size, size, offset, actual_length, ftdi->readbuffer_remaining); */
1315 ret = libusb_submit_transfer (transfer);
1321 static void ftdi_write_data_cb(struct libusb_transfer *transfer)
1323 struct ftdi_transfer_control *tc = (struct ftdi_transfer_control *) transfer->user_data;
1324 struct ftdi_context *ftdi = tc->ftdi;
1326 tc->offset += transfer->actual_length;
1328 if (tc->offset == tc->size)
1334 int write_size = ftdi->writebuffer_chunksize;
1337 if (tc->offset + write_size > tc->size)
1338 write_size = tc->size - tc->offset;
1340 transfer->length = write_size;
1341 transfer->buffer = tc->buf + tc->offset;
1342 ret = libusb_submit_transfer (transfer);
1350 Writes data to the chip. Does not wait for completion of the transfer
1351 nor does it make sure that the transfer was successful.
1353 Use libusb 1.0 asynchronous API.
1355 \param ftdi pointer to ftdi_context
1356 \param buf Buffer with the data
1357 \param size Size of the buffer
1359 \retval NULL: Some error happens when submit transfer
1360 \retval !NULL: Pointer to a ftdi_transfer_control
1363 struct ftdi_transfer_control *ftdi_write_data_submit(struct ftdi_context *ftdi, unsigned char *buf, int size)
1365 struct ftdi_transfer_control *tc;
1366 struct libusb_transfer *transfer = libusb_alloc_transfer(0);
1367 int write_size, ret;
1369 if (ftdi == NULL || ftdi->usb_dev == NULL)
1371 libusb_free_transfer(transfer);
1375 tc = (struct ftdi_transfer_control *) malloc (sizeof (*tc));
1377 if (!tc || !transfer)
1386 if (size < ftdi->writebuffer_chunksize)
1389 write_size = ftdi->writebuffer_chunksize;
1391 libusb_fill_bulk_transfer(transfer, ftdi->usb_dev, ftdi->in_ep, buf,
1392 write_size, ftdi_write_data_cb, tc,
1393 ftdi->usb_write_timeout);
1394 transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
1396 ret = libusb_submit_transfer(transfer);
1399 libusb_free_transfer(transfer);
1401 tc->transfer = NULL;
1404 tc->transfer = transfer;
1410 Reads data from the chip. Does not wait for completion of the transfer
1411 nor does it make sure that the transfer was successful.
1413 Use libusb 1.0 asynchronous API.
1415 \param ftdi pointer to ftdi_context
1416 \param buf Buffer with the data
1417 \param size Size of the buffer
1419 \retval NULL: Some error happens when submit transfer
1420 \retval !NULL: Pointer to a ftdi_transfer_control
1423 struct ftdi_transfer_control *ftdi_read_data_submit(struct ftdi_context *ftdi, unsigned char *buf, int size)
1425 struct ftdi_transfer_control *tc;
1426 struct libusb_transfer *transfer;
1429 if (ftdi == NULL || ftdi->usb_dev == NULL)
1432 tc = (struct ftdi_transfer_control *) malloc (sizeof (*tc));
1440 if (size <= ftdi->readbuffer_remaining)
1442 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1445 ftdi->readbuffer_remaining -= size;
1446 ftdi->readbuffer_offset += size;
1448 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1452 tc->transfer = NULL;
1457 if (ftdi->readbuffer_remaining != 0)
1459 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1461 tc->offset = ftdi->readbuffer_remaining;
1466 transfer = libusb_alloc_transfer(0);
1473 ftdi->readbuffer_remaining = 0;
1474 ftdi->readbuffer_offset = 0;
1476 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);
1477 transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
1479 ret = libusb_submit_transfer(transfer);
1482 libusb_free_transfer(transfer);
1486 tc->transfer = transfer;
1492 Wait for completion of the transfer.
1494 Use libusb 1.0 asynchronous API.
1496 \param tc pointer to ftdi_transfer_control
1498 \retval < 0: Some error happens
1499 \retval >= 0: Data size transferred
1502 int ftdi_transfer_data_done(struct ftdi_transfer_control *tc)
1506 while (!tc->completed)
1508 ret = libusb_handle_events(tc->ftdi->usb_ctx);
1511 if (ret == LIBUSB_ERROR_INTERRUPTED)
1513 libusb_cancel_transfer(tc->transfer);
1514 while (!tc->completed)
1515 if (libusb_handle_events(tc->ftdi->usb_ctx) < 0)
1517 libusb_free_transfer(tc->transfer);
1525 * tc->transfer could be NULL if "(size <= ftdi->readbuffer_remaining)"
1526 * at ftdi_read_data_submit(). Therefore, we need to check it here.
1530 if (tc->transfer->status != LIBUSB_TRANSFER_COMPLETED)
1532 libusb_free_transfer(tc->transfer);
1539 Configure write buffer chunk size.
1542 \param ftdi pointer to ftdi_context
1543 \param chunksize Chunk size
1546 \retval -1: ftdi context invalid
1548 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1551 ftdi_error_return(-1, "ftdi context invalid");
1553 ftdi->writebuffer_chunksize = chunksize;
1558 Get write buffer chunk size.
1560 \param ftdi pointer to ftdi_context
1561 \param chunksize Pointer to store chunk size in
1564 \retval -1: ftdi context invalid
1566 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1569 ftdi_error_return(-1, "ftdi context invalid");
1571 *chunksize = ftdi->writebuffer_chunksize;
1576 Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
1578 Automatically strips the two modem status bytes transfered during every read.
1580 \param ftdi pointer to ftdi_context
1581 \param buf Buffer to store data in
1582 \param size Size of the buffer
1584 \retval -666: USB device unavailable
1585 \retval <0: error code from libusb_bulk_transfer()
1586 \retval 0: no data was available
1587 \retval >0: number of bytes read
1590 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1592 int offset = 0, ret, i, num_of_chunks, chunk_remains;
1593 int packet_size = ftdi->max_packet_size;
1594 int actual_length = 1;
1596 if (ftdi == NULL || ftdi->usb_dev == NULL)
1597 ftdi_error_return(-666, "USB device unavailable");
1599 // Packet size sanity check (avoid division by zero)
1600 if (packet_size == 0)
1601 ftdi_error_return(-1, "max_packet_size is bogus (zero)");
1603 // everything we want is still in the readbuffer?
1604 if (size <= ftdi->readbuffer_remaining)
1606 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1609 ftdi->readbuffer_remaining -= size;
1610 ftdi->readbuffer_offset += size;
1612 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1616 // something still in the readbuffer, but not enough to satisfy 'size'?
1617 if (ftdi->readbuffer_remaining != 0)
1619 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1622 offset += ftdi->readbuffer_remaining;
1624 // do the actual USB read
1625 while (offset < size && actual_length > 0)
1627 ftdi->readbuffer_remaining = 0;
1628 ftdi->readbuffer_offset = 0;
1629 /* returns how much received */
1630 ret = libusb_bulk_transfer (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, &actual_length, ftdi->usb_read_timeout);
1632 ftdi_error_return(ret, "usb bulk read failed");
1634 if (actual_length > 2)
1636 // skip FTDI status bytes.
1637 // Maybe stored in the future to enable modem use
1638 num_of_chunks = actual_length / packet_size;
1639 chunk_remains = actual_length % packet_size;
1640 //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);
1642 ftdi->readbuffer_offset += 2;
1645 if (actual_length > packet_size - 2)
1647 for (i = 1; i < num_of_chunks; i++)
1648 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1649 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1651 if (chunk_remains > 2)
1653 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1654 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1656 actual_length -= 2*num_of_chunks;
1659 actual_length -= 2*(num_of_chunks-1)+chunk_remains;
1662 else if (actual_length <= 2)
1664 // no more data to read?
1667 if (actual_length > 0)
1669 // data still fits in buf?
1670 if (offset+actual_length <= size)
1672 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, actual_length);
1673 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1674 offset += actual_length;
1676 /* Did we read exactly the right amount of bytes? */
1678 //printf("read_data exact rem %d offset %d\n",
1679 //ftdi->readbuffer_remaining, offset);
1684 // only copy part of the data or size <= readbuffer_chunksize
1685 int part_size = size-offset;
1686 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
1688 ftdi->readbuffer_offset += part_size;
1689 ftdi->readbuffer_remaining = actual_length-part_size;
1690 offset += part_size;
1692 /* printf("Returning part: %d - size: %d - offset: %d - actual_length: %d - remaining: %d\n",
1693 part_size, size, offset, actual_length, ftdi->readbuffer_remaining); */
1704 Configure read buffer chunk size.
1707 Automatically reallocates the buffer.
1709 \param ftdi pointer to ftdi_context
1710 \param chunksize Chunk size
1713 \retval -1: ftdi context invalid
1715 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1717 unsigned char *new_buf;
1720 ftdi_error_return(-1, "ftdi context invalid");
1722 // Invalidate all remaining data
1723 ftdi->readbuffer_offset = 0;
1724 ftdi->readbuffer_remaining = 0;
1726 /* We can't set readbuffer_chunksize larger than MAX_BULK_BUFFER_LENGTH,
1727 which is defined in libusb-1.0. Otherwise, each USB read request will
1728 be divided into multiple URBs. This will cause issues on Linux kernel
1729 older than 2.6.32. */
1730 if (chunksize > 16384)
1734 if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
1735 ftdi_error_return(-1, "out of memory for readbuffer");
1737 ftdi->readbuffer = new_buf;
1738 ftdi->readbuffer_chunksize = chunksize;
1744 Get read buffer chunk size.
1746 \param ftdi pointer to ftdi_context
1747 \param chunksize Pointer to store chunk size in
1750 \retval -1: FTDI context invalid
1752 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1755 ftdi_error_return(-1, "FTDI context invalid");
1757 *chunksize = ftdi->readbuffer_chunksize;
1763 Enable bitbang mode.
1765 \deprecated use \ref ftdi_set_bitmode with mode BITMODE_BITBANG instead
1767 \param ftdi pointer to ftdi_context
1768 \param bitmask Bitmask to configure lines.
1769 HIGH/ON value configures a line as output.
1772 \retval -1: can't enable bitbang mode
1773 \retval -2: USB device unavailable
1775 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
1777 unsigned short usb_val;
1779 if (ftdi == NULL || ftdi->usb_dev == NULL)
1780 ftdi_error_return(-2, "USB device unavailable");
1782 usb_val = bitmask; // low byte: bitmask
1783 /* FT2232C: Set bitbang_mode to 2 to enable SPI */
1784 usb_val |= (ftdi->bitbang_mode << 8);
1786 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1787 SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index,
1788 NULL, 0, ftdi->usb_write_timeout) < 0)
1789 ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
1791 ftdi->bitbang_enabled = 1;
1796 Disable bitbang mode.
1798 \param ftdi pointer to ftdi_context
1801 \retval -1: can't disable bitbang mode
1802 \retval -2: USB device unavailable
1804 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
1806 if (ftdi == NULL || ftdi->usb_dev == NULL)
1807 ftdi_error_return(-2, "USB device unavailable");
1809 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)
1810 ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
1812 ftdi->bitbang_enabled = 0;
1817 Enable/disable bitbang modes.
1819 \param ftdi pointer to ftdi_context
1820 \param bitmask Bitmask to configure lines.
1821 HIGH/ON value configures a line as output.
1822 \param mode Bitbang mode: use the values defined in \ref ftdi_mpsse_mode
1825 \retval -1: can't enable bitbang mode
1826 \retval -2: USB device unavailable
1828 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
1830 unsigned short usb_val;
1832 if (ftdi == NULL || ftdi->usb_dev == NULL)
1833 ftdi_error_return(-2, "USB device unavailable");
1835 usb_val = bitmask; // low byte: bitmask
1836 usb_val |= (mode << 8);
1837 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)
1838 ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps not a 2232C type chip?");
1840 ftdi->bitbang_mode = mode;
1841 ftdi->bitbang_enabled = (mode == BITMODE_RESET) ? 0 : 1;
1846 Directly read pin state, circumventing the read buffer. Useful for bitbang mode.
1848 \param ftdi pointer to ftdi_context
1849 \param pins Pointer to store pins into
1852 \retval -1: read pins failed
1853 \retval -2: USB device unavailable
1855 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
1857 if (ftdi == NULL || ftdi->usb_dev == NULL)
1858 ftdi_error_return(-2, "USB device unavailable");
1860 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)
1861 ftdi_error_return(-1, "read pins failed");
1869 The FTDI chip keeps data in the internal buffer for a specific
1870 amount of time if the buffer is not full yet to decrease
1871 load on the usb bus.
1873 \param ftdi pointer to ftdi_context
1874 \param latency Value between 1 and 255
1877 \retval -1: latency out of range
1878 \retval -2: unable to set latency timer
1879 \retval -3: USB device unavailable
1881 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
1883 unsigned short usb_val;
1886 ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
1888 if (ftdi == NULL || ftdi->usb_dev == NULL)
1889 ftdi_error_return(-3, "USB device unavailable");
1892 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)
1893 ftdi_error_return(-2, "unable to set latency timer");
1901 \param ftdi pointer to ftdi_context
1902 \param latency Pointer to store latency value in
1905 \retval -1: unable to get latency timer
1906 \retval -2: USB device unavailable
1908 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1910 unsigned short usb_val;
1912 if (ftdi == NULL || ftdi->usb_dev == NULL)
1913 ftdi_error_return(-2, "USB device unavailable");
1915 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)
1916 ftdi_error_return(-1, "reading latency timer failed");
1918 *latency = (unsigned char)usb_val;
1923 Poll modem status information
1925 This function allows the retrieve the two status bytes of the device.
1926 The device sends these bytes also as a header for each read access
1927 where they are discarded by ftdi_read_data(). The chip generates
1928 the two stripped status bytes in the absence of data every 40 ms.
1930 Layout of the first byte:
1931 - B0..B3 - must be 0
1932 - B4 Clear to send (CTS)
1935 - B5 Data set ready (DTS)
1938 - B6 Ring indicator (RI)
1941 - B7 Receive line signal detect (RLSD)
1945 Layout of the second byte:
1946 - B0 Data ready (DR)
1947 - B1 Overrun error (OE)
1948 - B2 Parity error (PE)
1949 - B3 Framing error (FE)
1950 - B4 Break interrupt (BI)
1951 - B5 Transmitter holding register (THRE)
1952 - B6 Transmitter empty (TEMT)
1953 - B7 Error in RCVR FIFO
1955 \param ftdi pointer to ftdi_context
1956 \param status Pointer to store status information in. Must be two bytes.
1959 \retval -1: unable to retrieve status information
1960 \retval -2: USB device unavailable
1962 int ftdi_poll_modem_status(struct ftdi_context *ftdi, unsigned short *status)
1966 if (ftdi == NULL || ftdi->usb_dev == NULL)
1967 ftdi_error_return(-2, "USB device unavailable");
1969 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)
1970 ftdi_error_return(-1, "getting modem status failed");
1972 *status = (usb_val[1] << 8) | usb_val[0];
1978 Set flowcontrol for ftdi chip
1980 \param ftdi pointer to ftdi_context
1981 \param flowctrl flow control to use. should be
1982 SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1985 \retval -1: set flow control failed
1986 \retval -2: USB device unavailable
1988 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1990 if (ftdi == NULL || ftdi->usb_dev == NULL)
1991 ftdi_error_return(-2, "USB device unavailable");
1993 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1994 SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->index),
1995 NULL, 0, ftdi->usb_write_timeout) < 0)
1996 ftdi_error_return(-1, "set flow control failed");
2004 \param ftdi pointer to ftdi_context
2005 \param state state to set line to (1 or 0)
2008 \retval -1: set dtr failed
2009 \retval -2: USB device unavailable
2011 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
2013 unsigned short usb_val;
2015 if (ftdi == NULL || ftdi->usb_dev == NULL)
2016 ftdi_error_return(-2, "USB device unavailable");
2019 usb_val = SIO_SET_DTR_HIGH;
2021 usb_val = SIO_SET_DTR_LOW;
2023 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2024 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
2025 NULL, 0, ftdi->usb_write_timeout) < 0)
2026 ftdi_error_return(-1, "set dtr failed");
2034 \param ftdi pointer to ftdi_context
2035 \param state state to set line to (1 or 0)
2038 \retval -1: set rts failed
2039 \retval -2: USB device unavailable
2041 int ftdi_setrts(struct ftdi_context *ftdi, int state)
2043 unsigned short usb_val;
2045 if (ftdi == NULL || ftdi->usb_dev == NULL)
2046 ftdi_error_return(-2, "USB device unavailable");
2049 usb_val = SIO_SET_RTS_HIGH;
2051 usb_val = SIO_SET_RTS_LOW;
2053 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2054 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
2055 NULL, 0, ftdi->usb_write_timeout) < 0)
2056 ftdi_error_return(-1, "set of rts failed");
2062 Set dtr and rts line in one pass
2064 \param ftdi pointer to ftdi_context
2065 \param dtr DTR state to set line to (1 or 0)
2066 \param rts RTS state to set line to (1 or 0)
2069 \retval -1: set dtr/rts failed
2070 \retval -2: USB device unavailable
2072 int ftdi_setdtr_rts(struct ftdi_context *ftdi, int dtr, int rts)
2074 unsigned short usb_val;
2076 if (ftdi == NULL || ftdi->usb_dev == NULL)
2077 ftdi_error_return(-2, "USB device unavailable");
2080 usb_val = SIO_SET_DTR_HIGH;
2082 usb_val = SIO_SET_DTR_LOW;
2085 usb_val |= SIO_SET_RTS_HIGH;
2087 usb_val |= SIO_SET_RTS_LOW;
2089 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2090 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
2091 NULL, 0, ftdi->usb_write_timeout) < 0)
2092 ftdi_error_return(-1, "set of rts/dtr failed");
2098 Set the special event character
2100 \param ftdi pointer to ftdi_context
2101 \param eventch Event character
2102 \param enable 0 to disable the event character, non-zero otherwise
2105 \retval -1: unable to set event character
2106 \retval -2: USB device unavailable
2108 int ftdi_set_event_char(struct ftdi_context *ftdi,
2109 unsigned char eventch, unsigned char enable)
2111 unsigned short usb_val;
2113 if (ftdi == NULL || ftdi->usb_dev == NULL)
2114 ftdi_error_return(-2, "USB device unavailable");
2120 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)
2121 ftdi_error_return(-1, "setting event character failed");
2129 \param ftdi pointer to ftdi_context
2130 \param errorch Error character
2131 \param enable 0 to disable the error character, non-zero otherwise
2134 \retval -1: unable to set error character
2135 \retval -2: USB device unavailable
2137 int ftdi_set_error_char(struct ftdi_context *ftdi,
2138 unsigned char errorch, unsigned char enable)
2140 unsigned short usb_val;
2142 if (ftdi == NULL || ftdi->usb_dev == NULL)
2143 ftdi_error_return(-2, "USB device unavailable");
2149 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)
2150 ftdi_error_return(-1, "setting error character failed");
2158 \param ftdi pointer to ftdi_context
2159 \param eeprom Pointer to ftdi_eeprom
2163 void ftdi_eeprom_setsize(struct ftdi_context *ftdi, struct ftdi_eeprom *eeprom, int size)
2168 ftdi->eeprom = eeprom;
2169 ftdi->eeprom->size=size;
2173 Init eeprom with default values.
2175 \param eeprom Pointer to ftdi_eeprom
2177 void ftdi_eeprom_initdefaults(struct ftdi_context *ftdi)
2180 struct ftdi_eeprom *eeprom;
2185 if (ftdi->eeprom == NULL)
2188 eeprom = ftdi->eeprom;
2189 memset(eeprom, 0, sizeof(struct ftdi_eeprom));
2191 eeprom->vendor_id = 0x0403;
2192 eeprom->use_serial = USE_SERIAL_NUM;
2193 if((ftdi->type == TYPE_AM) || (ftdi->type == TYPE_BM) ||
2194 (ftdi->type == TYPE_R))
2195 eeprom->product_id = 0x6001;
2197 eeprom->product_id = 0x6010;
2198 if (ftdi->type == TYPE_AM)
2199 eeprom->usb_version = 0x0101;
2201 eeprom->usb_version = 0x0200;
2202 eeprom->max_power = 50;
2204 eeprom->manufacturer = NULL;
2205 eeprom->product = NULL;
2206 eeprom->serial = NULL;
2208 if(ftdi->type == TYPE_R)
2209 eeprom->size = 0x80;
2215 Frees allocated memory in eeprom.
2217 \param eeprom Pointer to ftdi_eeprom
2219 void ftdi_eeprom_free(struct ftdi_context *ftdi)
2225 struct ftdi_eeprom *eeprom = ftdi->eeprom;
2227 if (eeprom->manufacturer != 0) {
2228 free(eeprom->manufacturer);
2229 eeprom->manufacturer = 0;
2231 if (eeprom->product != 0) {
2232 free(eeprom->product);
2233 eeprom->product = 0;
2235 if (eeprom->serial != 0) {
2236 free(eeprom->serial);
2243 Build binary output from ftdi_eeprom structure.
2244 Output is suitable for ftdi_write_eeprom().
2246 \note This function doesn't handle FT2232x devices. Only FT232x.
2247 \param eeprom Pointer to ftdi_eeprom
2248 \param output Buffer of 128 bytes to store eeprom image to
2250 \retval >0: free eeprom size
2251 \retval -1: eeprom size (128 bytes) exceeded by custom strings
2252 \retval -2: Invalid eeprom pointer
2253 \retval -3: Invalid cbus function setting
2254 \retval -4: Chip doesn't support invert
2255 \retval -5: Chip doesn't support high current drive
2256 \retval -6: No connected EEPROM or EEPROM Type unknown
2258 int ftdi_eeprom_build(struct ftdi_context *ftdi, unsigned char *output)
2260 unsigned char i, j, k;
2261 unsigned short checksum, value;
2262 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2264 struct ftdi_eeprom *eeprom;
2267 ftdi_error_return(-2,"No context");
2268 if (ftdi->eeprom == NULL)
2269 ftdi_error_return(-2,"No eeprom structure");
2271 eeprom= ftdi->eeprom;
2273 if(eeprom->chip == -1)
2274 ftdi_error_return(-5,"No connected EEPROM or EEPROM Type unknown");
2276 if ((eeprom->chip == 0x56) || (eeprom->chip == 0x66))
2277 eeprom->size = 0x100;
2279 eeprom->size = 0x80;
2281 if (eeprom->manufacturer != NULL)
2282 manufacturer_size = strlen(eeprom->manufacturer);
2283 if (eeprom->product != NULL)
2284 product_size = strlen(eeprom->product);
2285 if (eeprom->serial != NULL)
2286 serial_size = strlen(eeprom->serial);
2300 size_check -= 0x14*2;
2303 size_check -= manufacturer_size*2;
2304 size_check -= product_size*2;
2305 size_check -= serial_size*2;
2307 /* Space for the string type and pointer bytes */
2310 // eeprom size exceeded?
2315 memset (output, 0, eeprom->size);
2317 // Bytes and Bits set for all Types
2319 // Addr 02: Vendor ID
2320 output[0x02] = eeprom->vendor_id;
2321 output[0x03] = eeprom->vendor_id >> 8;
2323 // Addr 04: Product ID
2324 output[0x04] = eeprom->product_id;
2325 output[0x05] = eeprom->product_id >> 8;
2327 // Addr 06: Device release number (0400h for BM features)
2328 output[0x06] = 0x00;
2329 switch (ftdi->type) {
2331 output[0x07] = 0x02;
2334 output[0x07] = 0x04;
2337 output[0x07] = 0x05;
2340 output[0x07] = 0x06;
2343 output[0x07] = 0x07;
2346 output[0x07] = 0x08;
2349 output[0x07] = 0x00;
2352 // Addr 08: Config descriptor
2354 // Bit 6: 1 if this device is self powered, 0 if bus powered
2355 // Bit 5: 1 if this device uses remote wakeup
2356 // Bit 4: 1 if this device is battery powered
2358 if (eeprom->self_powered == 1)
2360 if (eeprom->remote_wakeup == 1)
2364 // Addr 09: Max power consumption: max power = value * 2 mA
2365 output[0x09] = eeprom->max_power;
2367 if(ftdi->type != TYPE_AM)
2369 // Addr 0A: Chip configuration
2370 // Bit 7: 0 - reserved
2371 // Bit 6: 0 - reserved
2372 // Bit 5: 0 - reserved
2373 // Bit 4: 1 - Change USB version
2374 // Bit 3: 1 - Use the serial number string
2375 // Bit 2: 1 - Enable suspend pull downs for lower power
2376 // Bit 1: 1 - Out EndPoint is Isochronous
2377 // Bit 0: 1 - In EndPoint is Isochronous
2380 if (eeprom->in_is_isochronous == 1)
2382 if (eeprom->out_is_isochronous == 1)
2388 // Strings start at 0x94 (TYPE_AM, TYPE_BM)
2389 // 0x96 (TYPE_2232C), 0x98 (TYPE_R) and 0x9a (TYPE_x232H)
2404 /* Wrap around 0x80 for 128 byte EEPROMS (Internale and 93x46) */
2405 k = eeprom->size -1;
2407 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2408 // Addr 0F: Length of manufacturer string
2409 // Output manufacturer
2410 output[0x0E] = i; // calculate offset
2411 output[i++ & k] = manufacturer_size*2 + 2;
2412 output[i++ & k] = 0x03; // type: string
2413 for (j = 0; j < manufacturer_size; j++)
2415 output[i & k] = eeprom->manufacturer[j], i++;
2416 output[i & k] = 0x00, i++;
2418 output[0x0F] = manufacturer_size*2 + 2;
2420 // Addr 10: Offset of the product string + 0x80, calculated later
2421 // Addr 11: Length of product string
2422 output[0x10] = i | 0x80; // calculate offset
2423 output[i & k] = product_size*2 + 2, i++;
2424 output[i & k] = 0x03, i++;
2425 for (j = 0; j < product_size; j++)
2427 output[i & k] = eeprom->product[j], i++;
2428 output[i & k] = 0x00, i++;
2430 output[0x11] = product_size*2 + 2;
2432 // Addr 12: Offset of the serial string + 0x80, calculated later
2433 // Addr 13: Length of serial string
2434 output[0x12] = i | 0x80; // calculate offset
2435 output[i & k] = serial_size*2 + 2, i++;
2436 output[i & k] = 0x03, i++;
2437 for (j = 0; j < serial_size; j++)
2439 output[i & k] = eeprom->serial[j], i++;
2440 output[i & k] = 0x00, i++;
2442 output[0x13] = serial_size*2 + 2;
2444 /* Fixme: ftd2xx seems to append 0x02, 0x03 and 0x01 for PnP = 0 or 0x00 else */
2445 // calculate checksum
2447 /* Bytes and Bits specific to (some) types
2448 Write linear, as this allows easier fixing*/
2454 output[0x0C] = eeprom->usb_version & 0xff;
2455 output[0x0D] = (eeprom->usb_version>>8) & 0xff;
2456 if (eeprom->use_serial == 1)
2457 output[0x0A] |= 0x8;
2459 output[0x0A] &= ~0x8;
2460 output[0x14] = eeprom->chip;
2464 output[0x00] = (eeprom->channel_a_type);
2465 if ( eeprom->channel_a_driver == DRIVER_VCP)
2466 output[0x00] |= DRIVER_VCP;
2468 output[0x00] &= ~DRIVER_VCP;
2470 if ( eeprom->high_current_a == HIGH_CURRENT_DRIVE)
2471 output[0x00] |= HIGH_CURRENT_DRIVE;
2473 output[0x00] &= ~HIGH_CURRENT_DRIVE;
2475 output[0x01] = (eeprom->channel_b_type);
2476 if ( eeprom->channel_b_driver == DRIVER_VCP)
2477 output[0x01] |= DRIVER_VCP;
2479 output[0x01] &= ~DRIVER_VCP;
2481 if ( eeprom->high_current_b == HIGH_CURRENT_DRIVE)
2482 output[0x01] |= HIGH_CURRENT_DRIVE;
2484 output[0x01] &= ~HIGH_CURRENT_DRIVE;
2486 if (eeprom->in_is_isochronous == 1)
2487 output[0x0A] |= 0x1;
2489 output[0x0A] &= ~0x1;
2490 if (eeprom->out_is_isochronous == 1)
2491 output[0x0A] |= 0x2;
2493 output[0x0A] &= ~0x2;
2494 if (eeprom->suspend_pull_downs == 1)
2495 output[0x0A] |= 0x4;
2497 output[0x0A] &= ~0x4;
2498 if (eeprom->use_serial == USE_SERIAL_NUM )
2499 output[0x0A] |= USE_SERIAL_NUM;
2501 output[0x0A] &= ~0x8;
2502 output[0x0C] = eeprom->usb_version & 0xff;
2503 output[0x0D] = (eeprom->usb_version>>8) & 0xff;
2504 output[0x14] = eeprom->chip;
2507 if(eeprom->high_current == HIGH_CURRENT_DRIVE_R)
2508 output[0x00] |= HIGH_CURRENT_DRIVE_R;
2509 output[0x01] = 0x40; /* Hard coded Endpoint Size*/
2511 if (eeprom->suspend_pull_downs == 1)
2512 output[0x0A] |= 0x4;
2514 output[0x0A] &= ~0x4;
2515 if (eeprom->use_serial == USE_SERIAL_NUM)
2516 output[0x0A] |= USE_SERIAL_NUM;
2518 output[0x0A] &= ~0x8;
2519 output[0x0B] = eeprom->invert;
2520 output[0x0C] = eeprom->usb_version & 0xff;
2521 output[0x0D] = (eeprom->usb_version>>8) & 0xff;
2523 if(eeprom->cbus_function[0] > CBUS_BB)
2524 output[0x14] = CBUS_BB;
2526 output[0x14] = eeprom->cbus_function[0];
2528 if(eeprom->cbus_function[1] > CBUS_BB)
2529 output[0x14] |= CBUS_BB<<4;
2531 output[0x14] |= eeprom->cbus_function[1];
2533 if(eeprom->cbus_function[2] > CBUS_BB)
2534 output[0x15] |= CBUS_BB<<4;
2536 output[0x15] |= eeprom->cbus_function[2];
2538 if(eeprom->cbus_function[3] > CBUS_BB)
2539 output[0x15] |= CBUS_BB<<4;
2541 output[0x15] |= eeprom->cbus_function[3];
2543 if(eeprom->cbus_function[5] > CBUS_BB)
2544 output[0x16] = CBUS_BB;
2546 output[0x16] = eeprom->cbus_function[0];
2549 output[0x00] = (eeprom->channel_a_type);
2550 if ( eeprom->channel_a_driver == DRIVER_VCP)
2551 output[0x00] |= DRIVER_VCP;
2553 output[0x00] &= ~DRIVER_VCP;
2555 output[0x01] = (eeprom->channel_b_type);
2556 if ( eeprom->channel_b_driver == DRIVER_VCP)
2557 output[0x01] |= DRIVER_VCP;
2559 output[0x01] &= ~DRIVER_VCP;
2560 if(eeprom->suspend_dbus7 == SUSPEND_DBUS7)
2561 output[0x01] |= SUSPEND_DBUS7;
2563 output[0x01] &= ~SUSPEND_DBUS7;
2565 if(eeprom->group0_drive > DRIVE_16MA)
2566 output[0x0c] |= DRIVE_16MA;
2568 output[0x0c] |= eeprom->group0_drive;
2569 if (eeprom->group0_schmitt == IS_SCHMITT)
2570 output[0x0c] |= IS_SCHMITT;
2571 if (eeprom->group0_slew == SLOW_SLEW)
2572 output[0x0c] |= SLOW_SLEW;
2574 if(eeprom->group1_drive > DRIVE_16MA)
2575 output[0x0c] |= DRIVE_16MA<<4;
2577 output[0x0c] |= eeprom->group1_drive<<4;
2578 if (eeprom->group1_schmitt == IS_SCHMITT)
2579 output[0x0c] |= IS_SCHMITT<<4;
2580 if (eeprom->group1_slew == SLOW_SLEW)
2581 output[0x0c] |= SLOW_SLEW<<4;
2583 if(eeprom->group2_drive > DRIVE_16MA)
2584 output[0x0d] |= DRIVE_16MA;
2586 output[0x0d] |= eeprom->group2_drive;
2587 if (eeprom->group2_schmitt == IS_SCHMITT)
2588 output[0x0d] |= IS_SCHMITT;
2589 if (eeprom->group2_slew == SLOW_SLEW)
2590 output[0x0d] |= SLOW_SLEW;
2592 if(eeprom->group3_drive > DRIVE_16MA)
2593 output[0x0d] |= DRIVE_16MA<<4;
2595 output[0x0d] |= eeprom->group3_drive<<4;
2596 if (eeprom->group3_schmitt == IS_SCHMITT)
2597 output[0x0d] |= IS_SCHMITT<<4;
2598 if (eeprom->group3_slew == SLOW_SLEW)
2599 output[0x0d] |= SLOW_SLEW<<4;
2601 output[0x18] = eeprom->chip;
2606 // calculate checksum
2609 for (i = 0; i < eeprom->size/2-1; i++)
2611 value = output[i*2];
2612 value += output[(i*2)+1] << 8;
2614 checksum = value^checksum;
2615 checksum = (checksum << 1) | (checksum >> 15);
2618 output[eeprom->size-2] = checksum;
2619 output[eeprom->size-1] = checksum >> 8;
2625 Decode binary EEPROM image into an ftdi_eeprom structure.
2627 \param eeprom Pointer to ftdi_eeprom which will be filled in.
2628 \param buf Buffer of \a size bytes of raw eeprom data
2629 \param size size size of eeprom data in bytes
2632 \retval -1: something went wrong
2634 FIXME: How to pass size? How to handle size field in ftdi_eeprom?
2635 FIXME: Strings are malloc'ed here and should be freed somewhere
2637 int ftdi_eeprom_decode(struct ftdi_context *ftdi, unsigned char *buf, int size, int verbose)
2640 unsigned short checksum, eeprom_checksum, value;
2641 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2643 struct ftdi_eeprom *eeprom;
2647 ftdi_error_return(-1,"No context");
2648 if (ftdi->eeprom == NULL)
2649 ftdi_error_return(-1,"No eeprom structure");
2651 eeprom_size = ftdi->eeprom->size;
2652 if(ftdi->type == TYPE_R)
2654 eeprom = ftdi->eeprom;
2656 // Addr 02: Vendor ID
2657 eeprom->vendor_id = buf[0x02] + (buf[0x03] << 8);
2659 // Addr 04: Product ID
2660 eeprom->product_id = buf[0x04] + (buf[0x05] << 8);
2662 release = buf[0x06] + (buf[0x07]<<8);
2664 // Addr 08: Config descriptor
2666 // Bit 6: 1 if this device is self powered, 0 if bus powered
2667 // Bit 5: 1 if this device uses remote wakeup
2668 // Bit 4: 1 if this device is battery powered
2669 eeprom->self_powered = buf[0x08] & 0x40;
2670 eeprom->remote_wakeup = buf[0x08] & 0x20;;
2672 // Addr 09: Max power consumption: max power = value * 2 mA
2673 eeprom->max_power = buf[0x09];
2675 // Addr 0A: Chip configuration
2676 // Bit 7: 0 - reserved
2677 // Bit 6: 0 - reserved
2678 // Bit 5: 0 - reserved
2679 // Bit 4: 1 - Change USB version
2680 // Not seen on FT2232(D)
2681 // Bit 3: 1 - Use the serial number string
2682 // Bit 2: 1 - Enable suspend pull downs for lower power
2683 // Bit 1: 1 - Out EndPoint is Isochronous
2684 // Bit 0: 1 - In EndPoint is Isochronous
2686 eeprom->in_is_isochronous = buf[0x0A]&0x01;
2687 eeprom->out_is_isochronous = buf[0x0A]&0x02;
2688 eeprom->suspend_pull_downs = buf[0x0A]&0x04;
2689 eeprom->use_serial = buf[0x0A] & USE_SERIAL_NUM;
2692 "EEPROM byte[0x0a] Bit 4 unexpected set. If this happened with the EEPROM\n"
2693 "programmed by FTDI tools, please report to libftdi@developer.intra2net.com\n");
2696 // Addr 0C: USB version low byte when 0x0A
2697 // Addr 0D: USB version high byte when 0x0A
2698 eeprom->usb_version = buf[0x0C] + (buf[0x0D] << 8);
2700 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2701 // Addr 0F: Length of manufacturer string
2702 manufacturer_size = buf[0x0F]/2;
2703 if (manufacturer_size > 0)
2705 eeprom->manufacturer = malloc(manufacturer_size);
2706 if (eeprom->manufacturer)
2708 // Decode manufacturer
2709 i = buf[0x0E] & (eeprom_size -1); // offset
2710 for (j=0;j<manufacturer_size-1;j++)
2712 eeprom->manufacturer[j] = buf[2*j+i+2];
2714 eeprom->manufacturer[j] = '\0';
2717 else eeprom->manufacturer = NULL;
2719 // Addr 10: Offset of the product string + 0x80, calculated later
2720 // Addr 11: Length of product string
2721 product_size = buf[0x11]/2;
2722 if (product_size > 0)
2724 eeprom->product = malloc(product_size);
2727 // Decode product name
2728 i = buf[0x10] & (eeprom_size -1); // offset
2729 for (j=0;j<product_size-1;j++)
2731 eeprom->product[j] = buf[2*j+i+2];
2733 eeprom->product[j] = '\0';
2736 else eeprom->product = NULL;
2738 // Addr 12: Offset of the serial string + 0x80, calculated later
2739 // Addr 13: Length of serial string
2740 serial_size = buf[0x13]/2;
2741 if (serial_size > 0)
2743 eeprom->serial = malloc(serial_size);
2747 i = buf[0x12] & (eeprom_size -1); // offset
2748 for (j=0;j<serial_size-1;j++)
2750 eeprom->serial[j] = buf[2*j+i+2];
2752 eeprom->serial[j] = '\0';
2755 else eeprom->serial = NULL;
2760 for (i = 0; i < eeprom_size/2-1; i++)
2763 value += buf[(i*2)+1] << 8;
2765 checksum = value^checksum;
2766 checksum = (checksum << 1) | (checksum >> 15);
2769 eeprom_checksum = buf[eeprom_size-2] + (buf[eeprom_size-1] << 8);
2771 if (eeprom_checksum != checksum)
2773 fprintf(stderr, "Checksum Error: %04x %04x\n", checksum, eeprom_checksum);
2774 ftdi_error_return(-1,"EEPROM checksum error");
2777 eeprom->channel_a_type = 0;
2778 if ((ftdi->type == TYPE_AM) || (ftdi->type == TYPE_BM))
2782 else if(ftdi->type == TYPE_2232C)
2784 eeprom->channel_a_type = buf[0x00] & 0x7;
2785 eeprom->channel_a_driver = buf[0x00] & DRIVER_VCP;
2786 eeprom->high_current_a = buf[0x00] & HIGH_CURRENT_DRIVE;
2787 eeprom->channel_b_type = buf[0x01] & 0x7;
2788 eeprom->channel_b_driver = buf[0x01] & DRIVER_VCP;
2789 eeprom->high_current_b = buf[0x01] & HIGH_CURRENT_DRIVE;
2790 eeprom->chip = buf[0x14];
2792 else if(ftdi->type == TYPE_R)
2794 /* TYPE_R flags D2XX, not VCP as all others*/
2795 eeprom->channel_a_driver = (~buf[0x00]) & DRIVER_VCP;
2796 eeprom->high_current = buf[0x00] & HIGH_CURRENT_DRIVE_R;
2797 if( (buf[0x01]&0x40) != 0x40)
2799 "TYPE_R EEPROM byte[0x01] Bit 6 unexpected Endpoint size."
2800 " If this happened with the\n"
2801 " EEPROM programmed by FTDI tools, please report "
2802 "to libftdi@developer.intra2net.com\n");
2804 eeprom->chip = buf[0x16];
2805 // Addr 0B: Invert data lines
2806 // Works only on FT232R, not FT245R, but no way to distinguish
2807 eeprom->invert = buf[0x0B];
2808 // Addr 14: CBUS function: CBUS0, CBUS1
2809 // Addr 15: CBUS function: CBUS2, CBUS3
2810 // Addr 16: CBUS function: CBUS5
2811 eeprom->cbus_function[0] = buf[0x14] & 0x0f;
2812 eeprom->cbus_function[1] = (buf[0x14] >> 4) & 0x0f;
2813 eeprom->cbus_function[2] = buf[0x15] & 0x0f;
2814 eeprom->cbus_function[3] = (buf[0x15] >> 4) & 0x0f;
2815 eeprom->cbus_function[4] = buf[0x16] & 0x0f;
2817 else if ((ftdi->type == TYPE_2232H) ||(ftdi->type == TYPE_4232H))
2819 eeprom->high_current = buf[0x00] & HIGH_CURRENT_DRIVE_R;
2820 eeprom->channel_a_driver = buf[0x00] & DRIVER_VCP;
2821 eeprom->channel_b_type = buf[0x01] & 0x7;
2822 eeprom->channel_b_driver = buf[0x01] & DRIVER_VCP;
2824 if(ftdi->type == TYPE_2232H)
2825 eeprom->suspend_dbus7 = buf[0x01] & SUSPEND_DBUS7;
2827 eeprom->chip = buf[0x18];
2828 eeprom->group0_drive = buf[0x0c] & DRIVE_16MA;
2829 eeprom->group0_schmitt = buf[0x0c] & IS_SCHMITT;
2830 eeprom->group0_slew = buf[0x0c] & SLOW_SLEW;
2831 eeprom->group1_drive = (buf[0x0c] >> 4) & 0x3;
2832 eeprom->group1_schmitt = (buf[0x0c] >> 4) & IS_SCHMITT;
2833 eeprom->group1_slew = (buf[0x0c] >> 4) & SLOW_SLEW;
2834 eeprom->group2_drive = buf[0x0d] & DRIVE_16MA;
2835 eeprom->group2_schmitt = buf[0x0d] & IS_SCHMITT;
2836 eeprom->group2_slew = buf[0x0d] & SLOW_SLEW;
2837 eeprom->group3_drive = (buf[0x0d] >> 4) & DRIVE_16MA;
2838 eeprom->group3_schmitt = (buf[0x0d] >> 4) & IS_SCHMITT;
2839 eeprom->group3_slew = (buf[0x0d] >> 4) & SLOW_SLEW;
2844 char *channel_mode[] = {"UART","245","CPU", "unknown", "OPTO"};
2845 fprintf(stdout, "VID: 0x%04x\n",eeprom->vendor_id);
2846 fprintf(stdout, "PID: 0x%04x\n",eeprom->product_id);
2847 fprintf(stdout, "Release: 0x%04x\n",release);
2849 if(eeprom->self_powered)
2850 fprintf(stdout, "Self-Powered%s", (eeprom->remote_wakeup)?", USB Remote Wake Up\n":"\n");
2852 fprintf(stdout, "Bus Powered: %3d mA%s", eeprom->max_power * 2,
2853 (eeprom->remote_wakeup)?" USB Remote Wake Up\n":"\n");
2854 if(eeprom->manufacturer)
2855 fprintf(stdout, "Manufacturer: %s\n",eeprom->manufacturer);
2857 fprintf(stdout, "Product: %s\n",eeprom->product);
2859 fprintf(stdout, "Serial: %s\n",eeprom->serial);
2860 fprintf(stdout, "Checksum : %04x\n", checksum);
2861 if (ftdi->type == TYPE_R)
2862 fprintf(stdout, "Internal EEPROM\n");
2863 else if (eeprom->chip >= 0x46)
2864 fprintf(stdout, "Attached EEPROM: 93x%02x\n", eeprom->chip);
2865 if(eeprom->suspend_dbus7)
2866 fprintf(stdout, "Suspend on DBUS7\n");
2867 if(eeprom->suspend_pull_downs)
2868 fprintf(stdout, "Pull IO pins low during suspend\n");
2869 if(eeprom->remote_wakeup)
2870 fprintf(stdout, "Enable Remote Wake Up\n");
2871 if (ftdi->type >= TYPE_2232C)
2872 fprintf(stdout,"Channel A has Mode %s%s%s\n",
2873 channel_mode[eeprom->channel_a_type],
2874 (eeprom->channel_a_driver)?" VCP":"",
2875 (eeprom->high_current_a)?" High Current IO":"");
2876 if ((ftdi->type >= TYPE_2232C) && (ftdi->type != TYPE_R))
2877 fprintf(stdout,"Channel B has Mode %s%s%s\n",
2878 channel_mode[eeprom->channel_b_type],
2879 (eeprom->channel_b_driver)?" VCP":"",
2880 (eeprom->high_current_b)?" High Current IO":"");
2881 if ((ftdi->type == TYPE_2232H) || (ftdi->type == TYPE_4232H))
2883 fprintf(stdout,"%s has %d mA drive%s%s\n",
2884 (ftdi->type == TYPE_2232H)?"AL":"A",
2885 (eeprom->group0_drive+1) *4,
2886 (eeprom->group0_schmitt)?" Schmitt Input":"",
2887 (eeprom->group0_slew)?" Slow Slew":"");
2888 fprintf(stdout,"%s has %d mA drive%s%s\n",
2889 (ftdi->type == TYPE_2232H)?"AH":"B",
2890 (eeprom->group1_drive+1) *4,
2891 (eeprom->group1_schmitt)?" Schmitt Input":"",
2892 (eeprom->group1_slew)?" Slow Slew":"");
2893 fprintf(stdout,"%s has %d mA drive%s%s\n",
2894 (ftdi->type == TYPE_2232H)?"BL":"C",
2895 (eeprom->group2_drive+1) *4,
2896 (eeprom->group2_schmitt)?" Schmitt Input":"",
2897 (eeprom->group2_slew)?" Slow Slew":"");
2898 fprintf(stdout,"%s has %d mA drive%s%s\n",
2899 (ftdi->type == TYPE_2232H)?"BH":"D",
2900 (eeprom->group3_drive+1) *4,
2901 (eeprom->group3_schmitt)?" Schmitt Input":"",
2902 (eeprom->group3_slew)?" Slow Slew":"");
2911 Read eeprom location
2913 \param ftdi pointer to ftdi_context
2914 \param eeprom_addr Address of eeprom location to be read
2915 \param eeprom_val Pointer to store read eeprom location
2918 \retval -1: read failed
2919 \retval -2: USB device unavailable
2921 int ftdi_read_eeprom_location (struct ftdi_context *ftdi, int eeprom_addr, unsigned short *eeprom_val)
2923 if (ftdi == NULL || ftdi->usb_dev == NULL)
2924 ftdi_error_return(-2, "USB device unavailable");
2926 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, eeprom_addr, (unsigned char *)eeprom_val, 2, ftdi->usb_read_timeout) != 2)
2927 ftdi_error_return(-1, "reading eeprom failed");
2935 \param ftdi pointer to ftdi_context
2936 \param eeprom Pointer to store eeprom into
2939 \retval -1: read failed
2940 \retval -2: USB device unavailable
2942 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2946 if (ftdi == NULL || ftdi->usb_dev == NULL)
2947 ftdi_error_return(-2, "USB device unavailable");
2949 for (i = 0; i < FTDI_MAX_EEPROM_SIZE/2; i++)
2951 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)
2952 ftdi_error_return(-1, "reading eeprom failed");
2955 if (ftdi->type == TYPE_R)
2956 ftdi->eeprom->size = 0xa0;
2957 /* Guesses size of eeprom by comparing halves
2958 - will not work with blank eeprom */
2959 else if (strrchr((const char *)eeprom, 0xff) == ((const char *)eeprom +FTDI_MAX_EEPROM_SIZE -1))
2960 ftdi->eeprom->size = -1;
2961 else if(memcmp(eeprom,&eeprom[0x80],0x80) == 0)
2962 ftdi->eeprom->size = 0x80;
2963 else if(memcmp(eeprom,&eeprom[0x40],0x40) == 0)
2964 ftdi->eeprom->size = 0x40;
2966 ftdi->eeprom->size = 0x100;
2971 ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
2972 Function is only used internally
2975 static unsigned char ftdi_read_chipid_shift(unsigned char value)
2977 return ((value & 1) << 1) |
2978 ((value & 2) << 5) |
2979 ((value & 4) >> 2) |
2980 ((value & 8) << 4) |
2981 ((value & 16) >> 1) |
2982 ((value & 32) >> 1) |
2983 ((value & 64) >> 4) |
2984 ((value & 128) >> 2);
2988 Read the FTDIChip-ID from R-type devices
2990 \param ftdi pointer to ftdi_context
2991 \param chipid Pointer to store FTDIChip-ID
2994 \retval -1: read failed
2995 \retval -2: USB device unavailable
2997 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
2999 unsigned int a = 0, b = 0;
3001 if (ftdi == NULL || ftdi->usb_dev == NULL)
3002 ftdi_error_return(-2, "USB device unavailable");
3004 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)
3006 a = a << 8 | a >> 8;
3007 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)
3009 b = b << 8 | b >> 8;
3010 a = (a << 16) | (b & 0xFFFF);
3011 a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8
3012 | ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
3013 *chipid = a ^ 0xa5f0f7d1;
3018 ftdi_error_return(-1, "read of FTDIChip-ID failed");
3022 Write eeprom location
3024 \param ftdi pointer to ftdi_context
3025 \param eeprom_addr Address of eeprom location to be written
3026 \param eeprom_val Value to be written
3029 \retval -1: read failed
3030 \retval -2: USB device unavailable
3032 int ftdi_write_eeprom_location(struct ftdi_context *ftdi, int eeprom_addr, unsigned short eeprom_val)
3034 if (ftdi == NULL || ftdi->usb_dev == NULL)
3035 ftdi_error_return(-2, "USB device unavailable");
3037 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
3038 SIO_WRITE_EEPROM_REQUEST, eeprom_val, eeprom_addr,
3039 NULL, 0, ftdi->usb_write_timeout) != 0)
3040 ftdi_error_return(-1, "unable to write eeprom");
3048 \param ftdi pointer to ftdi_context
3049 \param eeprom Pointer to read eeprom from
3052 \retval -1: read failed
3053 \retval -2: USB device unavailable
3055 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
3057 unsigned short usb_val, status;
3060 if (ftdi == NULL || ftdi->usb_dev == NULL)
3061 ftdi_error_return(-2, "USB device unavailable");
3063 /* These commands were traced while running MProg */
3064 if ((ret = ftdi_usb_reset(ftdi)) != 0)
3066 if ((ret = ftdi_poll_modem_status(ftdi, &status)) != 0)
3068 if ((ret = ftdi_set_latency_timer(ftdi, 0x77)) != 0)
3071 for (i = 0; i < ftdi->eeprom->size/2; i++)
3073 usb_val = eeprom[i*2];
3074 usb_val += eeprom[(i*2)+1] << 8;
3075 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
3076 SIO_WRITE_EEPROM_REQUEST, usb_val, i,
3077 NULL, 0, ftdi->usb_write_timeout) < 0)
3078 ftdi_error_return(-1, "unable to write eeprom");
3087 This is not supported on FT232R/FT245R according to the MProg manual from FTDI.
3089 \param ftdi pointer to ftdi_context
3092 \retval -1: erase failed
3093 \retval -2: USB device unavailable
3094 \retval -3: Writing magic failed
3095 \retval -4: Read EEPROM failed
3096 \retval -5: Unexpected EEPROM value
3098 #define MAGIC 0x55aa
3099 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
3101 unsigned short eeprom_value;
3102 if (ftdi == NULL || ftdi->usb_dev == NULL)
3103 ftdi_error_return(-2, "USB device unavailable");
3105 if(ftdi->type == TYPE_R)
3107 ftdi->eeprom->chip = 0;
3111 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_ERASE_EEPROM_REQUEST,
3112 0, 0, NULL, 0, ftdi->usb_write_timeout) < 0)
3113 ftdi_error_return(-1, "unable to erase eeprom");
3116 /* detect chip type by writing 0x55AA as magic at word position 0xc0
3117 Chip is 93x46 if magic is read at word position 0x00, as wraparound happens around 0x40
3118 Chip is 93x56 if magic is read at word position 0x40, as wraparound happens around 0x80
3119 Chip is 93x66 if magic is only read at word position 0xc0*/
3120 if( ftdi_write_eeprom_location(ftdi, 0xc0, MAGIC))
3121 ftdi_error_return(-3, "Writing magic failed");
3122 if (ftdi_read_eeprom_location( ftdi, 0x00, &eeprom_value))
3123 ftdi_error_return(-4, "Reading failed failed");
3124 if(eeprom_value == MAGIC)
3126 ftdi->eeprom->chip = 0x46;
3130 if (ftdi_read_eeprom_location( ftdi, 0x40, &eeprom_value))
3131 ftdi_error_return(-4, "Reading failed failed");
3132 if(eeprom_value == MAGIC)
3133 ftdi->eeprom->chip = 0x56;
3136 if (ftdi_read_eeprom_location( ftdi, 0xc0, &eeprom_value))
3137 ftdi_error_return(-4, "Reading failed failed");
3138 if(eeprom_value == MAGIC)
3139 ftdi->eeprom->chip = 0x66;
3142 ftdi->eeprom->chip = -1;
3146 if (libusb_control_transfer(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_ERASE_EEPROM_REQUEST,
3147 0, 0, NULL, 0, ftdi->usb_write_timeout) < 0)
3148 ftdi_error_return(-1, "unable to erase eeprom");
3153 Get string representation for last error code
3155 \param ftdi pointer to ftdi_context
3157 \retval Pointer to error string
3159 char *ftdi_get_error_string (struct ftdi_context *ftdi)
3164 return ftdi->error_str;
3167 /* @} end of doxygen libftdi group */