1 /***************************************************************************
5 copyright : (C) 2003-2008 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 */
38 /* stuff needed for async write */
39 #ifdef LIBFTDI_LINUX_ASYNC_MODE
40 #include <sys/ioctl.h>
42 #include <sys/select.h>
43 #include <sys/types.h>
45 #include <linux/usbdevice_fs.h>
48 #define ftdi_error_return(code, str) do { \
49 ftdi->error_str = str; \
55 Internal function to close usb device pointer.
56 Sets ftdi->usb_dev to NULL.
59 \param ftdi pointer to ftdi_context
61 \retval zero if all is fine, otherwise error code from usb_close()
63 static int ftdi_usb_close_internal (struct ftdi_context *ftdi)
69 ret = usb_close (ftdi->usb_dev);
77 Initializes a ftdi_context.
79 \param ftdi pointer to ftdi_context
82 \retval -1: couldn't allocate read buffer
84 \remark This should be called before all functions
86 int ftdi_init(struct ftdi_context *ftdi)
91 ftdi->usb_read_timeout = 5000;
92 ftdi->usb_write_timeout = 5000;
94 ftdi->type = TYPE_BM; /* chip type */
96 ftdi->bitbang_enabled = 0; /* 0: normal mode 1: any of the bitbang modes enabled */
98 ftdi->readbuffer = NULL;
99 ftdi->readbuffer_offset = 0;
100 ftdi->readbuffer_remaining = 0;
101 ftdi->writebuffer_chunksize = 4096;
102 ftdi->max_packet_size = 0;
108 ftdi->bitbang_mode = 1; /* when bitbang is enabled this holds the number of the mode */
110 ftdi->error_str = NULL;
112 #ifdef LIBFTDI_LINUX_ASYNC_MODE
113 ftdi->async_usb_buffer_size=10;
114 if ((ftdi->async_usb_buffer=malloc(sizeof(struct usbdevfs_urb)*ftdi->async_usb_buffer_size)) == NULL)
115 ftdi_error_return(-1, "out of memory for async usb buffer");
117 /* initialize async usb buffer with unused-marker */
118 for (i=0; i < ftdi->async_usb_buffer_size; i++)
119 ((struct usbdevfs_urb*)ftdi->async_usb_buffer)[i].usercontext = FTDI_URB_USERCONTEXT_COOKIE;
121 ftdi->async_usb_buffer_size=0;
122 ftdi->async_usb_buffer = NULL;
125 ftdi->eeprom_size = FTDI_DEFAULT_EEPROM_SIZE;
127 /* All fine. Now allocate the readbuffer */
128 return ftdi_read_data_set_chunksize(ftdi, 4096);
132 Allocate and initialize a new ftdi_context
134 \return a pointer to a new ftdi_context, or NULL on failure
136 struct ftdi_context *ftdi_new(void)
138 struct ftdi_context * ftdi = (struct ftdi_context *)malloc(sizeof(struct ftdi_context));
145 if (ftdi_init(ftdi) != 0)
155 Open selected channels on a chip, otherwise use first channel.
157 \param ftdi pointer to ftdi_context
158 \param interface Interface to use for FT2232C/2232H/4232H chips.
161 \retval -1: unknown interface
163 int ftdi_set_interface(struct ftdi_context *ftdi, enum ftdi_interface interface)
169 /* ftdi_usb_open_desc cares to set the right index, depending on the found chip */
173 ftdi->index = INTERFACE_B;
179 ftdi->index = INTERFACE_C;
185 ftdi->index = INTERFACE_D;
190 ftdi_error_return(-1, "Unknown interface");
196 Deinitializes a ftdi_context.
198 \param ftdi pointer to ftdi_context
200 void ftdi_deinit(struct ftdi_context *ftdi)
202 ftdi_usb_close_internal (ftdi);
204 if (ftdi->async_usb_buffer != NULL)
206 free(ftdi->async_usb_buffer);
207 ftdi->async_usb_buffer = NULL;
210 if (ftdi->readbuffer != NULL)
212 free(ftdi->readbuffer);
213 ftdi->readbuffer = NULL;
218 Deinitialize and free an ftdi_context.
220 \param ftdi pointer to ftdi_context
222 void ftdi_free(struct ftdi_context *ftdi)
229 Use an already open libusb device.
231 \param ftdi pointer to ftdi_context
232 \param usb libusb usb_dev_handle to use
234 void ftdi_set_usbdev (struct ftdi_context *ftdi, usb_dev_handle *usb)
241 Finds all ftdi devices on the usb bus. Creates a new ftdi_device_list which
242 needs to be deallocated by ftdi_list_free() after use.
244 \param ftdi pointer to ftdi_context
245 \param devlist Pointer where to store list of found devices
246 \param vendor Vendor ID to search for
247 \param product Product ID to search for
249 \retval >0: number of devices found
250 \retval -1: usb_find_busses() failed
251 \retval -2: usb_find_devices() failed
252 \retval -3: out of memory
254 int ftdi_usb_find_all(struct ftdi_context *ftdi, struct ftdi_device_list **devlist, int vendor, int product)
256 struct ftdi_device_list **curdev;
258 struct usb_device *dev;
262 if (usb_find_busses() < 0)
263 ftdi_error_return(-1, "usb_find_busses() failed");
264 if (usb_find_devices() < 0)
265 ftdi_error_return(-2, "usb_find_devices() failed");
269 for (bus = usb_get_busses(); bus; bus = bus->next)
271 for (dev = bus->devices; dev; dev = dev->next)
273 if (dev->descriptor.idVendor == vendor
274 && dev->descriptor.idProduct == product)
276 *curdev = (struct ftdi_device_list*)malloc(sizeof(struct ftdi_device_list));
278 ftdi_error_return(-3, "out of memory");
280 (*curdev)->next = NULL;
281 (*curdev)->dev = dev;
283 curdev = &(*curdev)->next;
293 Frees a usb device list.
295 \param devlist USB device list created by ftdi_usb_find_all()
297 void ftdi_list_free(struct ftdi_device_list **devlist)
299 struct ftdi_device_list *curdev, *next;
301 for (curdev = *devlist; curdev != NULL;)
312 Frees a usb device list.
314 \param devlist USB device list created by ftdi_usb_find_all()
316 void ftdi_list_free2(struct ftdi_device_list *devlist)
318 ftdi_list_free(&devlist);
322 Return device ID strings from the usb device.
324 The parameters manufacturer, description and serial may be NULL
325 or pointer to buffers to store the fetched strings.
327 \note Use this function only in combination with ftdi_usb_find_all()
328 as it closes the internal "usb_dev" after use.
330 \param ftdi pointer to ftdi_context
331 \param dev libusb usb_dev to use
332 \param manufacturer Store manufacturer string here if not NULL
333 \param mnf_len Buffer size of manufacturer string
334 \param description Store product description string here if not NULL
335 \param desc_len Buffer size of product description string
336 \param serial Store serial string here if not NULL
337 \param serial_len Buffer size of serial string
340 \retval -1: wrong arguments
341 \retval -4: unable to open device
342 \retval -7: get product manufacturer failed
343 \retval -8: get product description failed
344 \retval -9: get serial number failed
345 \retval -10: unable to close device
347 int ftdi_usb_get_strings(struct ftdi_context * ftdi, struct usb_device * dev,
348 char * manufacturer, int mnf_len, char * description, int desc_len, char * serial, int serial_len)
350 if ((ftdi==NULL) || (dev==NULL))
353 if (!(ftdi->usb_dev = usb_open(dev)))
354 ftdi_error_return(-4, usb_strerror());
356 if (manufacturer != NULL)
358 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iManufacturer, manufacturer, mnf_len) <= 0)
360 ftdi_usb_close_internal (ftdi);
361 ftdi_error_return(-7, usb_strerror());
365 if (description != NULL)
367 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, description, desc_len) <= 0)
369 ftdi_usb_close_internal (ftdi);
370 ftdi_error_return(-8, usb_strerror());
376 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, serial, serial_len) <= 0)
378 ftdi_usb_close_internal (ftdi);
379 ftdi_error_return(-9, usb_strerror());
383 if (ftdi_usb_close_internal (ftdi) != 0)
384 ftdi_error_return(-10, usb_strerror());
390 * Internal function to determine the maximum packet size.
391 * \param ftdi pointer to ftdi_context
392 * \param dev libusb usb_dev to use
393 * \retval Maximum packet size for this device
395 static unsigned int _ftdi_determine_max_packet_size(struct ftdi_context *ftdi, struct usb_device *dev)
397 unsigned int packet_size;
399 // Determine maximum packet size. Init with default value.
400 // New hi-speed devices from FTDI use a packet size of 512 bytes
401 // but could be connected to a normal speed USB hub -> 64 bytes packet size.
402 if (ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
407 if (dev->descriptor.bNumConfigurations > 0 && dev->config)
409 struct usb_config_descriptor config = dev->config[0];
411 if (ftdi->interface < config.bNumInterfaces)
413 struct usb_interface interface = config.interface[ftdi->interface];
414 if (interface.num_altsetting > 0)
416 struct usb_interface_descriptor descriptor = interface.altsetting[0];
417 if (descriptor.bNumEndpoints > 0)
419 packet_size = descriptor.endpoint[0].wMaxPacketSize;
429 Opens a ftdi device given by an usb_device.
431 \param ftdi pointer to ftdi_context
432 \param dev libusb usb_dev to use
435 \retval -3: unable to config device
436 \retval -4: unable to open device
437 \retval -5: unable to claim device
438 \retval -6: reset failed
439 \retval -7: set baudrate failed
441 int ftdi_usb_open_dev(struct ftdi_context *ftdi, struct usb_device *dev)
443 int detach_errno = 0;
445 if (!(ftdi->usb_dev = usb_open(dev)))
446 ftdi_error_return(-4, "usb_open() failed");
448 #ifdef LIBUSB_HAS_GET_DRIVER_NP
449 // Try to detach ftdi_sio kernel module.
450 // Returns ENODATA if driver is not loaded.
452 // The return code is kept in a separate variable and only parsed
453 // if usb_set_configuration() or usb_claim_interface() fails as the
454 // detach operation might be denied and everything still works fine.
455 // Likely scenario is a static ftdi_sio kernel module.
456 if (usb_detach_kernel_driver_np(ftdi->usb_dev, ftdi->interface) != 0 && errno != ENODATA)
457 detach_errno = errno;
461 // set configuration (needed especially for windows)
462 // tolerate EBUSY: one device with one configuration, but two interfaces
463 // and libftdi sessions to both interfaces (e.g. FT2232)
465 if (dev->descriptor.bNumConfigurations > 0)
467 // libusb-win32 on Windows 64 can return a null pointer for a valid device
469 config_val = dev->config[0].bConfigurationValue;
471 if (usb_set_configuration(ftdi->usb_dev, config_val) &&
474 ftdi_usb_close_internal (ftdi);
475 if (detach_errno == EPERM)
477 ftdi_error_return(-8, "inappropriate permissions on device!");
481 ftdi_error_return(-3, "unable to set usb configuration. Make sure ftdi_sio is unloaded!");
487 if (usb_claim_interface(ftdi->usb_dev, ftdi->interface) != 0)
489 ftdi_usb_close_internal (ftdi);
490 if (detach_errno == EPERM)
492 ftdi_error_return(-8, "inappropriate permissions on device!");
496 ftdi_error_return(-5, "unable to claim usb device. Make sure ftdi_sio is unloaded!");
500 if (ftdi_usb_reset (ftdi) != 0)
502 ftdi_usb_close_internal (ftdi);
503 ftdi_error_return(-6, "ftdi_usb_reset failed");
506 // Try to guess chip type
507 // Bug in the BM type chips: bcdDevice is 0x200 for serial == 0
508 if (dev->descriptor.bcdDevice == 0x400 || (dev->descriptor.bcdDevice == 0x200
509 && dev->descriptor.iSerialNumber == 0))
510 ftdi->type = TYPE_BM;
511 else if (dev->descriptor.bcdDevice == 0x200)
512 ftdi->type = TYPE_AM;
513 else if (dev->descriptor.bcdDevice == 0x500)
514 ftdi->type = TYPE_2232C;
515 else if (dev->descriptor.bcdDevice == 0x600)
517 else if (dev->descriptor.bcdDevice == 0x700)
518 ftdi->type = TYPE_2232H;
519 else if (dev->descriptor.bcdDevice == 0x800)
520 ftdi->type = TYPE_4232H;
522 // Set default interface on dual/quad type chips
529 ftdi->index = INTERFACE_A;
535 // Determine maximum packet size
536 ftdi->max_packet_size = _ftdi_determine_max_packet_size(ftdi, dev);
538 if (ftdi_set_baudrate (ftdi, 9600) != 0)
540 ftdi_usb_close_internal (ftdi);
541 ftdi_error_return(-7, "set baudrate failed");
544 ftdi_error_return(0, "all fine");
548 Opens the first device with a given vendor and product ids.
550 \param ftdi pointer to ftdi_context
551 \param vendor Vendor ID
552 \param product Product ID
554 \retval same as ftdi_usb_open_desc()
556 int ftdi_usb_open(struct ftdi_context *ftdi, int vendor, int product)
558 return ftdi_usb_open_desc(ftdi, vendor, product, NULL, NULL);
562 Opens the first device with a given, vendor id, product id,
563 description and serial.
565 \param ftdi pointer to ftdi_context
566 \param vendor Vendor ID
567 \param product Product ID
568 \param description Description to search for. Use NULL if not needed.
569 \param serial Serial to search for. Use NULL if not needed.
572 \retval -1: usb_find_busses() failed
573 \retval -2: usb_find_devices() failed
574 \retval -3: usb device not found
575 \retval -4: unable to open device
576 \retval -5: unable to claim device
577 \retval -6: reset failed
578 \retval -7: set baudrate failed
579 \retval -8: get product description failed
580 \retval -9: get serial number failed
581 \retval -10: unable to close device
583 int ftdi_usb_open_desc(struct ftdi_context *ftdi, int vendor, int product,
584 const char* description, const char* serial)
586 return ftdi_usb_open_desc_index(ftdi,vendor,product,description,serial,0);
590 Opens the index-th device with a given, vendor id, product id,
591 description and serial.
593 \param ftdi pointer to ftdi_context
594 \param vendor Vendor ID
595 \param product Product ID
596 \param description Description to search for. Use NULL if not needed.
597 \param serial Serial to search for. Use NULL if not needed.
598 \param index Number of matching device to open if there are more than one, starts with 0.
601 \retval -1: usb_find_busses() failed
602 \retval -2: usb_find_devices() failed
603 \retval -3: usb device not found
604 \retval -4: unable to open device
605 \retval -5: unable to claim device
606 \retval -6: reset failed
607 \retval -7: set baudrate failed
608 \retval -8: get product description failed
609 \retval -9: get serial number failed
610 \retval -10: unable to close device
612 int ftdi_usb_open_desc_index(struct ftdi_context *ftdi, int vendor, int product,
613 const char* description, const char* serial, unsigned int index)
616 struct usb_device *dev;
621 if (usb_find_busses() < 0)
622 ftdi_error_return(-1, "usb_find_busses() failed");
623 if (usb_find_devices() < 0)
624 ftdi_error_return(-2, "usb_find_devices() failed");
626 for (bus = usb_get_busses(); bus; bus = bus->next)
628 for (dev = bus->devices; dev; dev = dev->next)
630 if (dev->descriptor.idVendor == vendor
631 && dev->descriptor.idProduct == product)
633 if (!(ftdi->usb_dev = usb_open(dev)))
634 ftdi_error_return(-4, "usb_open() failed");
636 if (description != NULL)
638 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, string, sizeof(string)) <= 0)
640 ftdi_usb_close_internal (ftdi);
641 ftdi_error_return(-8, "unable to fetch product description");
643 if (strncmp(string, description, sizeof(string)) != 0)
645 if (ftdi_usb_close_internal (ftdi) != 0)
646 ftdi_error_return(-10, "unable to close device");
652 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, string, sizeof(string)) <= 0)
654 ftdi_usb_close_internal (ftdi);
655 ftdi_error_return(-9, "unable to fetch serial number");
657 if (strncmp(string, serial, sizeof(string)) != 0)
659 if (ftdi_usb_close_internal (ftdi) != 0)
660 ftdi_error_return(-10, "unable to close device");
665 if (ftdi_usb_close_internal (ftdi) != 0)
666 ftdi_error_return(-10, "unable to close device");
674 return ftdi_usb_open_dev(ftdi, dev);
680 ftdi_error_return(-3, "device not found");
684 Opens the ftdi-device described by a description-string.
685 Intended to be used for parsing a device-description given as commandline argument.
687 \param ftdi pointer to ftdi_context
688 \param description NULL-terminated description-string, using this format:
689 \li <tt>d:\<devicenode></tt> path of bus and device-node (e.g. "003/001") within usb device tree (usually at /proc/bus/usb/)
690 \li <tt>i:\<vendor>:\<product></tt> first device with given vendor and product id, ids can be decimal, octal (preceded by "0") or hex (preceded by "0x")
691 \li <tt>i:\<vendor>:\<product>:\<index></tt> as above with index being the number of the device (starting with 0) if there are more than one
692 \li <tt>s:\<vendor>:\<product>:\<serial></tt> first device with given vendor id, product id and serial string
694 \note The description format may be extended in later versions.
697 \retval -1: usb_find_busses() failed
698 \retval -2: usb_find_devices() failed
699 \retval -3: usb device not found
700 \retval -4: unable to open device
701 \retval -5: unable to claim device
702 \retval -6: reset failed
703 \retval -7: set baudrate failed
704 \retval -8: get product description failed
705 \retval -9: get serial number failed
706 \retval -10: unable to close device
707 \retval -11: illegal description format
709 int ftdi_usb_open_string(struct ftdi_context *ftdi, const char* description)
711 if (description[0] == 0 || description[1] != ':')
712 ftdi_error_return(-11, "illegal description format");
714 if (description[0] == 'd')
717 struct usb_device *dev;
721 if (usb_find_busses() < 0)
722 ftdi_error_return(-1, "usb_find_busses() failed");
723 if (usb_find_devices() < 0)
724 ftdi_error_return(-2, "usb_find_devices() failed");
726 for (bus = usb_get_busses(); bus; bus = bus->next)
728 for (dev = bus->devices; dev; dev = dev->next)
730 /* XXX: This doesn't handle symlinks/odd paths/etc... */
731 const char *desc = description + 2;
732 size_t len = strlen(bus->dirname);
733 if (strncmp(desc, bus->dirname, len))
739 if (strcmp(desc, dev->filename))
741 return ftdi_usb_open_dev(ftdi, dev);
746 ftdi_error_return(-3, "device not found");
748 else if (description[0] == 'i' || description[0] == 's')
751 unsigned int product;
752 unsigned int index=0;
753 const char *serial=NULL;
754 const char *startp, *endp;
757 startp=description+2;
758 vendor=strtoul((char*)startp,(char**)&endp,0);
759 if (*endp != ':' || endp == startp || errno != 0)
760 ftdi_error_return(-11, "illegal description format");
763 product=strtoul((char*)startp,(char**)&endp,0);
764 if (endp == startp || errno != 0)
765 ftdi_error_return(-11, "illegal description format");
767 if (description[0] == 'i' && *endp != 0)
769 /* optional index field in i-mode */
771 ftdi_error_return(-11, "illegal description format");
774 index=strtoul((char*)startp,(char**)&endp,0);
775 if (*endp != 0 || endp == startp || errno != 0)
776 ftdi_error_return(-11, "illegal description format");
778 if (description[0] == 's')
781 ftdi_error_return(-11, "illegal description format");
783 /* rest of the description is the serial */
787 return ftdi_usb_open_desc_index(ftdi, vendor, product, NULL, serial, index);
791 ftdi_error_return(-11, "illegal description format");
796 Resets the ftdi device.
798 \param ftdi pointer to ftdi_context
801 \retval -1: FTDI reset failed
803 int ftdi_usb_reset(struct ftdi_context *ftdi)
805 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
806 SIO_RESET_REQUEST, SIO_RESET_SIO,
807 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
808 ftdi_error_return(-1,"FTDI reset failed");
810 // Invalidate data in the readbuffer
811 ftdi->readbuffer_offset = 0;
812 ftdi->readbuffer_remaining = 0;
818 Clears the read buffer on the chip and the internal read buffer.
820 \param ftdi pointer to ftdi_context
823 \retval -1: read buffer purge failed
825 int ftdi_usb_purge_rx_buffer(struct ftdi_context *ftdi)
827 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
828 SIO_RESET_REQUEST, SIO_RESET_PURGE_RX,
829 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
830 ftdi_error_return(-1, "FTDI purge of RX buffer failed");
832 // Invalidate data in the readbuffer
833 ftdi->readbuffer_offset = 0;
834 ftdi->readbuffer_remaining = 0;
840 Clears the write buffer on the chip.
842 \param ftdi pointer to ftdi_context
845 \retval -1: write buffer purge failed
847 int ftdi_usb_purge_tx_buffer(struct ftdi_context *ftdi)
849 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
850 SIO_RESET_REQUEST, SIO_RESET_PURGE_TX,
851 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
852 ftdi_error_return(-1, "FTDI purge of TX buffer failed");
858 Clears the buffers on the chip and the internal read buffer.
860 \param ftdi pointer to ftdi_context
863 \retval -1: read buffer purge failed
864 \retval -2: write buffer purge failed
866 int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
870 result = ftdi_usb_purge_rx_buffer(ftdi);
874 result = ftdi_usb_purge_tx_buffer(ftdi);
884 Closes the ftdi device. Call ftdi_deinit() if you're cleaning up.
886 \param ftdi pointer to ftdi_context
889 \retval -1: usb_release failed
890 \retval -2: usb_close failed
892 int ftdi_usb_close(struct ftdi_context *ftdi)
896 #ifdef LIBFTDI_LINUX_ASYNC_MODE
897 /* try to release some kernel resources */
898 ftdi_async_complete(ftdi,1);
901 if (ftdi->usb_dev != NULL)
902 if (usb_release_interface(ftdi->usb_dev, ftdi->interface) != 0)
905 if (ftdi_usb_close_internal (ftdi) != 0)
912 ftdi_convert_baudrate returns nearest supported baud rate to that requested.
913 Function is only used internally
916 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
917 unsigned short *value, unsigned short *index)
919 static const char am_adjust_up[8] = {0, 0, 0, 1, 0, 3, 2, 1};
920 static const char am_adjust_dn[8] = {0, 0, 0, 1, 0, 1, 2, 3};
921 static const char frac_code[8] = {0, 3, 2, 4, 1, 5, 6, 7};
922 int divisor, best_divisor, best_baud, best_baud_diff;
923 unsigned long encoded_divisor;
932 divisor = 24000000 / baudrate;
934 if (ftdi->type == TYPE_AM)
936 // Round down to supported fraction (AM only)
937 divisor -= am_adjust_dn[divisor & 7];
940 // Try this divisor and the one above it (because division rounds down)
944 for (i = 0; i < 2; i++)
946 int try_divisor = divisor + i;
950 // Round up to supported divisor value
951 if (try_divisor <= 8)
953 // Round up to minimum supported divisor
956 else if (ftdi->type != TYPE_AM && try_divisor < 12)
958 // BM doesn't support divisors 9 through 11 inclusive
961 else if (divisor < 16)
963 // AM doesn't support divisors 9 through 15 inclusive
968 if (ftdi->type == TYPE_AM)
970 // Round up to supported fraction (AM only)
971 try_divisor += am_adjust_up[try_divisor & 7];
972 if (try_divisor > 0x1FFF8)
974 // Round down to maximum supported divisor value (for AM)
975 try_divisor = 0x1FFF8;
980 if (try_divisor > 0x1FFFF)
982 // Round down to maximum supported divisor value (for BM)
983 try_divisor = 0x1FFFF;
987 // Get estimated baud rate (to nearest integer)
988 baud_estimate = (24000000 + (try_divisor / 2)) / try_divisor;
989 // Get absolute difference from requested baud rate
990 if (baud_estimate < baudrate)
992 baud_diff = baudrate - baud_estimate;
996 baud_diff = baud_estimate - baudrate;
998 if (i == 0 || baud_diff < best_baud_diff)
1000 // Closest to requested baud rate so far
1001 best_divisor = try_divisor;
1002 best_baud = baud_estimate;
1003 best_baud_diff = baud_diff;
1006 // Spot on! No point trying
1011 // Encode the best divisor value
1012 encoded_divisor = (best_divisor >> 3) | (frac_code[best_divisor & 7] << 14);
1013 // Deal with special cases for encoded value
1014 if (encoded_divisor == 1)
1016 encoded_divisor = 0; // 3000000 baud
1018 else if (encoded_divisor == 0x4001)
1020 encoded_divisor = 1; // 2000000 baud (BM only)
1022 // Split into "value" and "index" values
1023 *value = (unsigned short)(encoded_divisor & 0xFFFF);
1024 if (ftdi->type == TYPE_2232C || ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
1026 *index = (unsigned short)(encoded_divisor >> 8);
1028 *index |= ftdi->index;
1031 *index = (unsigned short)(encoded_divisor >> 16);
1033 // Return the nearest baud rate
1038 Sets the chip baud rate
1040 \param ftdi pointer to ftdi_context
1041 \param baudrate baud rate to set
1044 \retval -1: invalid baudrate
1045 \retval -2: setting baudrate failed
1047 int ftdi_set_baudrate(struct ftdi_context *ftdi, int baudrate)
1049 unsigned short value, index;
1050 int actual_baudrate;
1052 if (ftdi->bitbang_enabled)
1054 baudrate = baudrate*4;
1057 actual_baudrate = ftdi_convert_baudrate(baudrate, ftdi, &value, &index);
1058 if (actual_baudrate <= 0)
1059 ftdi_error_return (-1, "Silly baudrate <= 0.");
1061 // Check within tolerance (about 5%)
1062 if ((actual_baudrate * 2 < baudrate /* Catch overflows */ )
1063 || ((actual_baudrate < baudrate)
1064 ? (actual_baudrate * 21 < baudrate * 20)
1065 : (baudrate * 21 < actual_baudrate * 20)))
1066 ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
1068 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1069 SIO_SET_BAUDRATE_REQUEST, value,
1070 index, NULL, 0, ftdi->usb_write_timeout) != 0)
1071 ftdi_error_return (-2, "Setting new baudrate failed");
1073 ftdi->baudrate = baudrate;
1078 Set (RS232) line characteristics.
1079 The break type can only be set via ftdi_set_line_property2()
1080 and defaults to "off".
1082 \param ftdi pointer to ftdi_context
1083 \param bits Number of bits
1084 \param sbit Number of stop bits
1085 \param parity Parity mode
1088 \retval -1: Setting line property failed
1090 int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1091 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
1093 return ftdi_set_line_property2(ftdi, bits, sbit, parity, BREAK_OFF);
1097 Set (RS232) line characteristics
1099 \param ftdi pointer to ftdi_context
1100 \param bits Number of bits
1101 \param sbit Number of stop bits
1102 \param parity Parity mode
1103 \param break_type Break type
1106 \retval -1: Setting line property failed
1108 int ftdi_set_line_property2(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1109 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity,
1110 enum ftdi_break_type break_type)
1112 unsigned short value = bits;
1117 value |= (0x00 << 8);
1120 value |= (0x01 << 8);
1123 value |= (0x02 << 8);
1126 value |= (0x03 << 8);
1129 value |= (0x04 << 8);
1136 value |= (0x00 << 11);
1139 value |= (0x01 << 11);
1142 value |= (0x02 << 11);
1149 value |= (0x00 << 14);
1152 value |= (0x01 << 14);
1156 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1157 SIO_SET_DATA_REQUEST, value,
1158 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1159 ftdi_error_return (-1, "Setting new line property failed");
1165 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip
1167 \param ftdi pointer to ftdi_context
1168 \param buf Buffer with the data
1169 \param size Size of the buffer
1171 \retval <0: error code from usb_bulk_write()
1172 \retval >0: number of bytes written
1174 int ftdi_write_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1178 int total_written = 0;
1180 while (offset < size)
1182 int write_size = ftdi->writebuffer_chunksize;
1184 if (offset+write_size > size)
1185 write_size = size-offset;
1187 ret = usb_bulk_write(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size, ftdi->usb_write_timeout);
1189 ftdi_error_return(ret, "usb bulk write failed");
1191 total_written += ret;
1192 offset += write_size;
1195 return total_written;
1198 #ifdef LIBFTDI_LINUX_ASYNC_MODE
1199 #ifdef USB_CLASS_PTP
1200 #error LIBFTDI_LINUX_ASYNC_MODE is not compatible with libusb-compat-0.1!
1202 /* this is strongly dependent on libusb using the same struct layout. If libusb
1203 changes in some later version this may break horribly (this is for libusb 0.1.12) */
1204 struct usb_dev_handle
1207 // some other stuff coming here we don't need
1211 Check for pending async urbs
1214 static int _usb_get_async_urbs_pending(struct ftdi_context *ftdi)
1216 struct usbdevfs_urb *urb;
1220 for (i=0; i < ftdi->async_usb_buffer_size; i++)
1222 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1223 if (urb->usercontext != FTDI_URB_USERCONTEXT_COOKIE)
1231 Wait until one or more async URBs are completed by the kernel and mark their
1232 positions in the async-buffer as unused
1234 \param ftdi pointer to ftdi_context
1235 \param wait_for_more if != 0 wait for more than one write to complete
1236 \param timeout_msec max milliseconds to wait
1240 static void _usb_async_cleanup(struct ftdi_context *ftdi, int wait_for_more, int timeout_msec)
1243 struct usbdevfs_urb *urb=NULL;
1249 FD_SET(ftdi->usb_dev->fd, &writefds);
1251 /* init timeout only once, select writes time left after call */
1252 tv.tv_sec = timeout_msec / 1000;
1253 tv.tv_usec = (timeout_msec % 1000) * 1000;
1257 while (_usb_get_async_urbs_pending(ftdi)
1258 && (ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_REAPURBNDELAY, &urb)) == -1
1261 if (keep_going && !wait_for_more)
1263 /* don't wait if repeating only for keep_going */
1268 /* wait for timeout msec or something written ready */
1269 select(ftdi->usb_dev->fd+1, NULL, &writefds, NULL, &tv);
1272 if (ret == 0 && urb != NULL)
1274 /* got a free urb, mark it */
1275 urb->usercontext = FTDI_URB_USERCONTEXT_COOKIE;
1277 /* try to get more urbs that are ready now, but don't wait anymore */
1283 /* no more urbs waiting */
1291 Wait until one or more async URBs are completed by the kernel and mark their
1292 positions in the async-buffer as unused.
1294 \param ftdi pointer to ftdi_context
1295 \param wait_for_more if != 0 wait for more than one write to complete (until write timeout)
1297 void ftdi_async_complete(struct ftdi_context *ftdi, int wait_for_more)
1299 _usb_async_cleanup(ftdi,wait_for_more,ftdi->usb_write_timeout);
1303 Stupid libusb does not offer async writes nor does it allow
1304 access to its fd - so we need some hacks here.
1307 static int _usb_bulk_write_async(struct ftdi_context *ftdi, int ep, char *bytes, int size)
1309 struct usbdevfs_urb *urb;
1310 int bytesdone = 0, requested;
1311 int ret, cleanup_count;
1316 /* find a free urb buffer we can use */
1318 for (cleanup_count=0; urb==NULL && cleanup_count <= 1; cleanup_count++)
1320 if (i==ftdi->async_usb_buffer_size)
1322 /* wait until some buffers are free */
1323 _usb_async_cleanup(ftdi,0,ftdi->usb_write_timeout);
1326 for (i=0; i < ftdi->async_usb_buffer_size; i++)
1328 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1329 if (urb->usercontext == FTDI_URB_USERCONTEXT_COOKIE)
1330 break; /* found a free urb position */
1335 /* no free urb position found */
1339 requested = size - bytesdone;
1340 if (requested > 4096)
1343 memset(urb,0,sizeof(urb));
1345 urb->type = USBDEVFS_URB_TYPE_BULK;
1348 urb->buffer = bytes + bytesdone;
1349 urb->buffer_length = requested;
1351 urb->actual_length = 0;
1352 urb->number_of_packets = 0;
1353 urb->usercontext = 0;
1357 ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_SUBMITURB, urb);
1359 while (ret < 0 && errno == EINTR);
1361 return ret; /* the caller can read errno to get more info */
1363 bytesdone += requested;
1365 while (bytesdone < size);
1370 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip.
1371 Does not wait for completion of the transfer nor does it make sure that
1372 the transfer was successful.
1374 This function could be extended to use signals and callbacks to inform the
1375 caller of completion or error - but this is not done yet, volunteers welcome.
1377 Works around libusb and directly accesses functions only available on Linux.
1378 Only available if compiled with --with-async-mode.
1380 \param ftdi pointer to ftdi_context
1381 \param buf Buffer with the data
1382 \param size Size of the buffer
1384 \retval <0: error code from usb_bulk_write()
1385 \retval >0: number of bytes written
1387 int ftdi_write_data_async(struct ftdi_context *ftdi, unsigned char *buf, int size)
1391 int total_written = 0;
1393 while (offset < size)
1395 int write_size = ftdi->writebuffer_chunksize;
1397 if (offset+write_size > size)
1398 write_size = size-offset;
1400 ret = _usb_bulk_write_async(ftdi, ftdi->in_ep, buf+offset, write_size);
1402 ftdi_error_return(ret, "usb bulk write async failed");
1404 total_written += ret;
1405 offset += write_size;
1408 return total_written;
1410 #endif // LIBFTDI_LINUX_ASYNC_MODE
1413 Configure write buffer chunk size.
1416 \param ftdi pointer to ftdi_context
1417 \param chunksize Chunk size
1421 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1423 ftdi->writebuffer_chunksize = chunksize;
1428 Get write buffer chunk size.
1430 \param ftdi pointer to ftdi_context
1431 \param chunksize Pointer to store chunk size in
1435 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1437 *chunksize = ftdi->writebuffer_chunksize;
1442 Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
1444 Automatically strips the two modem status bytes transfered during every read.
1446 \param ftdi pointer to ftdi_context
1447 \param buf Buffer to store data in
1448 \param size Size of the buffer
1450 \retval <0: error code from usb_bulk_read()
1451 \retval 0: no data was available
1452 \retval >0: number of bytes read
1455 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1457 int offset = 0, ret = 1, i, num_of_chunks, chunk_remains;
1458 int packet_size = ftdi->max_packet_size;
1460 // Packet size sanity check (avoid division by zero)
1461 if (packet_size == 0)
1462 ftdi_error_return(-1, "max_packet_size is bogus (zero)");
1464 // everything we want is still in the readbuffer?
1465 if (size <= ftdi->readbuffer_remaining)
1467 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1470 ftdi->readbuffer_remaining -= size;
1471 ftdi->readbuffer_offset += size;
1473 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1477 // something still in the readbuffer, but not enough to satisfy 'size'?
1478 if (ftdi->readbuffer_remaining != 0)
1480 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1483 offset += ftdi->readbuffer_remaining;
1485 // do the actual USB read
1486 while (offset < size && ret > 0)
1488 ftdi->readbuffer_remaining = 0;
1489 ftdi->readbuffer_offset = 0;
1490 /* returns how much received */
1491 ret = usb_bulk_read (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, ftdi->usb_read_timeout);
1493 ftdi_error_return(ret, "usb bulk read failed");
1497 // skip FTDI status bytes.
1498 // Maybe stored in the future to enable modem use
1499 num_of_chunks = ret / packet_size;
1500 chunk_remains = ret % packet_size;
1501 //printf("ret = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", ret, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
1503 ftdi->readbuffer_offset += 2;
1506 if (ret > packet_size - 2)
1508 for (i = 1; i < num_of_chunks; i++)
1509 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1510 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1512 if (chunk_remains > 2)
1514 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1515 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1517 ret -= 2*num_of_chunks;
1520 ret -= 2*(num_of_chunks-1)+chunk_remains;
1525 // no more data to read?
1530 // data still fits in buf?
1531 if (offset+ret <= size)
1533 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, ret);
1534 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1537 /* Did we read exactly the right amount of bytes? */
1539 //printf("read_data exact rem %d offset %d\n",
1540 //ftdi->readbuffer_remaining, offset);
1545 // only copy part of the data or size <= readbuffer_chunksize
1546 int part_size = size-offset;
1547 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
1549 ftdi->readbuffer_offset += part_size;
1550 ftdi->readbuffer_remaining = ret-part_size;
1551 offset += part_size;
1553 /* printf("Returning part: %d - size: %d - offset: %d - ret: %d - remaining: %d\n",
1554 part_size, size, offset, ret, ftdi->readbuffer_remaining); */
1565 Configure read buffer chunk size.
1568 Automatically reallocates the buffer.
1570 \param ftdi pointer to ftdi_context
1571 \param chunksize Chunk size
1575 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1577 unsigned char *new_buf;
1579 // Invalidate all remaining data
1580 ftdi->readbuffer_offset = 0;
1581 ftdi->readbuffer_remaining = 0;
1583 if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
1584 ftdi_error_return(-1, "out of memory for readbuffer");
1586 ftdi->readbuffer = new_buf;
1587 ftdi->readbuffer_chunksize = chunksize;
1593 Get read buffer chunk size.
1595 \param ftdi pointer to ftdi_context
1596 \param chunksize Pointer to store chunk size in
1600 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1602 *chunksize = ftdi->readbuffer_chunksize;
1608 Enable bitbang mode.
1610 \deprecated use \ref ftdi_set_bitmode with mode BITMODE_BITBANG instead
1612 \param ftdi pointer to ftdi_context
1613 \param bitmask Bitmask to configure lines.
1614 HIGH/ON value configures a line as output.
1617 \retval -1: can't enable bitbang mode
1619 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
1621 unsigned short usb_val;
1623 usb_val = bitmask; // low byte: bitmask
1624 /* FT2232C: Set bitbang_mode to 2 to enable SPI */
1625 usb_val |= (ftdi->bitbang_mode << 8);
1627 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1628 SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index,
1629 NULL, 0, ftdi->usb_write_timeout) != 0)
1630 ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
1632 ftdi->bitbang_enabled = 1;
1637 Disable bitbang mode.
1639 \param ftdi pointer to ftdi_context
1642 \retval -1: can't disable bitbang mode
1644 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
1646 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_BITMODE_REQUEST, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1647 ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
1649 ftdi->bitbang_enabled = 0;
1654 Enable/disable bitbang modes.
1656 \param ftdi pointer to ftdi_context
1657 \param bitmask Bitmask to configure lines.
1658 HIGH/ON value configures a line as output.
1659 \param mode Bitbang mode: use the values defined in \ref ftdi_mpsse_mode
1662 \retval -1: can't enable bitbang mode
1664 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
1666 unsigned short usb_val;
1668 usb_val = bitmask; // low byte: bitmask
1669 usb_val |= (mode << 8);
1670 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1671 ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps selected mode not supported on your chip?");
1673 ftdi->bitbang_mode = mode;
1674 ftdi->bitbang_enabled = (mode == BITMODE_RESET) ? 0 : 1;
1679 Directly read pin state, circumventing the read buffer. Useful for bitbang mode.
1681 \param ftdi pointer to ftdi_context
1682 \param pins Pointer to store pins into
1685 \retval -1: read pins failed
1687 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
1689 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_PINS_REQUEST, 0, ftdi->index, (char *)pins, 1, ftdi->usb_read_timeout) != 1)
1690 ftdi_error_return(-1, "read pins failed");
1698 The FTDI chip keeps data in the internal buffer for a specific
1699 amount of time if the buffer is not full yet to decrease
1700 load on the usb bus.
1702 \param ftdi pointer to ftdi_context
1703 \param latency Value between 1 and 255
1706 \retval -1: latency out of range
1707 \retval -2: unable to set latency timer
1709 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
1711 unsigned short usb_val;
1714 ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
1717 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_LATENCY_TIMER_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1718 ftdi_error_return(-2, "unable to set latency timer");
1726 \param ftdi pointer to ftdi_context
1727 \param latency Pointer to store latency value in
1730 \retval -1: unable to get latency timer
1732 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1734 unsigned short usb_val;
1735 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_GET_LATENCY_TIMER_REQUEST, 0, ftdi->index, (char *)&usb_val, 1, ftdi->usb_read_timeout) != 1)
1736 ftdi_error_return(-1, "reading latency timer failed");
1738 *latency = (unsigned char)usb_val;
1743 Poll modem status information
1745 This function allows the retrieve the two status bytes of the device.
1746 The device sends these bytes also as a header for each read access
1747 where they are discarded by ftdi_read_data(). The chip generates
1748 the two stripped status bytes in the absence of data every 40 ms.
1750 Layout of the first byte:
1751 - B0..B3 - must be 0
1752 - B4 Clear to send (CTS)
1755 - B5 Data set ready (DTS)
1758 - B6 Ring indicator (RI)
1761 - B7 Receive line signal detect (RLSD)
1765 Layout of the second byte:
1766 - B0 Data ready (DR)
1767 - B1 Overrun error (OE)
1768 - B2 Parity error (PE)
1769 - B3 Framing error (FE)
1770 - B4 Break interrupt (BI)
1771 - B5 Transmitter holding register (THRE)
1772 - B6 Transmitter empty (TEMT)
1773 - B7 Error in RCVR FIFO
1775 \param ftdi pointer to ftdi_context
1776 \param status Pointer to store status information in. Must be two bytes.
1779 \retval -1: unable to retrieve status information
1781 int ftdi_poll_modem_status(struct ftdi_context *ftdi, unsigned short *status)
1785 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_POLL_MODEM_STATUS_REQUEST, 0, ftdi->index, usb_val, 2, ftdi->usb_read_timeout) != 2)
1786 ftdi_error_return(-1, "getting modem status failed");
1788 *status = (usb_val[1] << 8) | usb_val[0];
1794 Set flowcontrol for ftdi chip
1796 \param ftdi pointer to ftdi_context
1797 \param flowctrl flow control to use. should be
1798 SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1801 \retval -1: set flow control failed
1803 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1805 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1806 SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->index),
1807 NULL, 0, ftdi->usb_write_timeout) != 0)
1808 ftdi_error_return(-1, "set flow control failed");
1816 \param ftdi pointer to ftdi_context
1817 \param state state to set line to (1 or 0)
1820 \retval -1: set dtr failed
1822 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
1824 unsigned short usb_val;
1827 usb_val = SIO_SET_DTR_HIGH;
1829 usb_val = SIO_SET_DTR_LOW;
1831 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1832 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1833 NULL, 0, ftdi->usb_write_timeout) != 0)
1834 ftdi_error_return(-1, "set dtr failed");
1842 \param ftdi pointer to ftdi_context
1843 \param state state to set line to (1 or 0)
1846 \retval -1 set rts failed
1848 int ftdi_setrts(struct ftdi_context *ftdi, int state)
1850 unsigned short usb_val;
1853 usb_val = SIO_SET_RTS_HIGH;
1855 usb_val = SIO_SET_RTS_LOW;
1857 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1858 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1859 NULL, 0, ftdi->usb_write_timeout) != 0)
1860 ftdi_error_return(-1, "set of rts failed");
1866 Set dtr and rts line in one pass
1868 \param ftdi pointer to ftdi_context
1869 \param dtr DTR state to set line to (1 or 0)
1870 \param rts RTS state to set line to (1 or 0)
1873 \retval -1 set dtr/rts failed
1875 int ftdi_setdtr_rts(struct ftdi_context *ftdi, int dtr, int rts)
1877 unsigned short usb_val;
1880 usb_val = SIO_SET_DTR_HIGH;
1882 usb_val = SIO_SET_DTR_LOW;
1885 usb_val |= SIO_SET_RTS_HIGH;
1887 usb_val |= SIO_SET_RTS_LOW;
1889 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1890 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1891 NULL, 0, ftdi->usb_write_timeout) != 0)
1892 ftdi_error_return(-1, "set of rts/dtr failed");
1898 Set the special event character
1900 \param ftdi pointer to ftdi_context
1901 \param eventch Event character
1902 \param enable 0 to disable the event character, non-zero otherwise
1905 \retval -1: unable to set event character
1907 int ftdi_set_event_char(struct ftdi_context *ftdi,
1908 unsigned char eventch, unsigned char enable)
1910 unsigned short usb_val;
1916 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_EVENT_CHAR_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1917 ftdi_error_return(-1, "setting event character failed");
1925 \param ftdi pointer to ftdi_context
1926 \param errorch Error character
1927 \param enable 0 to disable the error character, non-zero otherwise
1930 \retval -1: unable to set error character
1932 int ftdi_set_error_char(struct ftdi_context *ftdi,
1933 unsigned char errorch, unsigned char enable)
1935 unsigned short usb_val;
1941 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_ERROR_CHAR_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1942 ftdi_error_return(-1, "setting error character failed");
1950 \param ftdi pointer to ftdi_context
1951 \param eeprom Pointer to ftdi_eeprom
1955 void ftdi_eeprom_setsize(struct ftdi_context *ftdi, struct ftdi_eeprom *eeprom, int size)
1957 ftdi->eeprom_size=size;
1962 Init eeprom with default values.
1964 \param eeprom Pointer to ftdi_eeprom
1966 void ftdi_eeprom_initdefaults(struct ftdi_eeprom *eeprom)
1968 eeprom->vendor_id = 0x0403;
1969 eeprom->product_id = 0x6001;
1971 eeprom->self_powered = 1;
1972 eeprom->remote_wakeup = 1;
1973 eeprom->BM_type_chip = 1;
1975 eeprom->in_is_isochronous = 0;
1976 eeprom->out_is_isochronous = 0;
1977 eeprom->suspend_pull_downs = 0;
1979 eeprom->use_serial = 0;
1980 eeprom->change_usb_version = 0;
1981 eeprom->usb_version = 0x0200;
1982 eeprom->max_power = 0;
1984 eeprom->manufacturer = NULL;
1985 eeprom->product = NULL;
1986 eeprom->serial = NULL;
1988 eeprom->size = FTDI_DEFAULT_EEPROM_SIZE;
1992 Build binary output from ftdi_eeprom structure.
1993 Output is suitable for ftdi_write_eeprom().
1995 \param eeprom Pointer to ftdi_eeprom
1996 \param output Buffer of 128 bytes to store eeprom image to
1998 \retval >0: used eeprom size
1999 \retval -1: eeprom size (128 bytes) exceeded by custom strings
2001 int ftdi_eeprom_build(struct ftdi_eeprom *eeprom, unsigned char *output)
2004 unsigned short checksum, value;
2005 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2008 if (eeprom->manufacturer != NULL)
2009 manufacturer_size = strlen(eeprom->manufacturer);
2010 if (eeprom->product != NULL)
2011 product_size = strlen(eeprom->product);
2012 if (eeprom->serial != NULL)
2013 serial_size = strlen(eeprom->serial);
2015 size_check = eeprom->size;
2016 size_check -= 28; // 28 are always in use (fixed)
2018 // Top half of a 256byte eeprom is used just for strings and checksum
2019 // it seems that the FTDI chip will not read these strings from the lower half
2020 // Each string starts with two bytes; offset and type (0x03 for string)
2021 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2022 if (eeprom->size>=256)size_check = 120;
2023 size_check -= manufacturer_size*2;
2024 size_check -= product_size*2;
2025 size_check -= serial_size*2;
2027 // eeprom size exceeded?
2032 memset (output, 0, eeprom->size);
2034 // Addr 00: Stay 00 00
2035 // Addr 02: Vendor ID
2036 output[0x02] = eeprom->vendor_id;
2037 output[0x03] = eeprom->vendor_id >> 8;
2039 // Addr 04: Product ID
2040 output[0x04] = eeprom->product_id;
2041 output[0x05] = eeprom->product_id >> 8;
2043 // Addr 06: Device release number (0400h for BM features)
2044 output[0x06] = 0x00;
2046 if (eeprom->BM_type_chip == 1)
2047 output[0x07] = 0x04;
2049 output[0x07] = 0x02;
2051 // Addr 08: Config descriptor
2053 // Bit 6: 1 if this device is self powered, 0 if bus powered
2054 // Bit 5: 1 if this device uses remote wakeup
2055 // Bit 4: 1 if this device is battery powered
2057 if (eeprom->self_powered == 1)
2059 if (eeprom->remote_wakeup == 1)
2063 // Addr 09: Max power consumption: max power = value * 2 mA
2064 output[0x09] = eeprom->max_power;
2066 // Addr 0A: Chip configuration
2067 // Bit 7: 0 - reserved
2068 // Bit 6: 0 - reserved
2069 // Bit 5: 0 - reserved
2070 // Bit 4: 1 - Change USB version
2071 // Bit 3: 1 - Use the serial number string
2072 // Bit 2: 1 - Enable suspend pull downs for lower power
2073 // Bit 1: 1 - Out EndPoint is Isochronous
2074 // Bit 0: 1 - In EndPoint is Isochronous
2077 if (eeprom->in_is_isochronous == 1)
2079 if (eeprom->out_is_isochronous == 1)
2081 if (eeprom->suspend_pull_downs == 1)
2083 if (eeprom->use_serial == 1)
2085 if (eeprom->change_usb_version == 1)
2089 // Addr 0B: reserved
2090 output[0x0B] = 0x00;
2092 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2093 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2094 if (eeprom->change_usb_version == 1)
2096 output[0x0C] = eeprom->usb_version;
2097 output[0x0D] = eeprom->usb_version >> 8;
2101 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2102 // Addr 0F: Length of manufacturer string
2103 output[0x0F] = manufacturer_size*2 + 2;
2105 // Addr 10: Offset of the product string + 0x80, calculated later
2106 // Addr 11: Length of product string
2107 output[0x11] = product_size*2 + 2;
2109 // Addr 12: Offset of the serial string + 0x80, calculated later
2110 // Addr 13: Length of serial string
2111 output[0x13] = serial_size*2 + 2;
2115 if (eeprom->size>=256) i = 0x80;
2118 // Output manufacturer
2119 output[0x0E] = i | 0x80; // calculate offset
2120 output[i++] = manufacturer_size*2 + 2;
2121 output[i++] = 0x03; // type: string
2122 for (j = 0; j < manufacturer_size; j++)
2124 output[i] = eeprom->manufacturer[j], i++;
2125 output[i] = 0x00, i++;
2128 // Output product name
2129 output[0x10] = i | 0x80; // calculate offset
2130 output[i] = product_size*2 + 2, i++;
2131 output[i] = 0x03, i++;
2132 for (j = 0; j < product_size; j++)
2134 output[i] = eeprom->product[j], i++;
2135 output[i] = 0x00, i++;
2139 output[0x12] = i | 0x80; // calculate offset
2140 output[i] = serial_size*2 + 2, i++;
2141 output[i] = 0x03, i++;
2142 for (j = 0; j < serial_size; j++)
2144 output[i] = eeprom->serial[j], i++;
2145 output[i] = 0x00, i++;
2148 // calculate checksum
2151 for (i = 0; i < eeprom->size/2-1; i++)
2153 value = output[i*2];
2154 value += output[(i*2)+1] << 8;
2156 checksum = value^checksum;
2157 checksum = (checksum << 1) | (checksum >> 15);
2160 output[eeprom->size-2] = checksum;
2161 output[eeprom->size-1] = checksum >> 8;
2167 Decode binary EEPROM image into an ftdi_eeprom structure.
2169 \param eeprom Pointer to ftdi_eeprom which will be filled in.
2170 \param buf Buffer of \a size bytes of raw eeprom data
2171 \param size size size of eeprom data in bytes
2174 \retval -1: something went wrong
2176 FIXME: How to pass size? How to handle size field in ftdi_eeprom?
2177 FIXME: Strings are malloc'ed here and should be freed somewhere
2179 int ftdi_eeprom_decode(struct ftdi_eeprom *eeprom, unsigned char *buf, int size)
2182 unsigned short checksum, eeprom_checksum, value;
2183 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2185 int eeprom_size = 128;
2187 size_check = eeprom->size;
2188 size_check -= 28; // 28 are always in use (fixed)
2190 // Top half of a 256byte eeprom is used just for strings and checksum
2191 // it seems that the FTDI chip will not read these strings from the lower half
2192 // Each string starts with two bytes; offset and type (0x03 for string)
2193 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2194 if (eeprom->size>=256)size_check = 120;
2195 size_check -= manufacturer_size*2;
2196 size_check -= product_size*2;
2197 size_check -= serial_size*2;
2199 // eeprom size exceeded?
2204 // empty eeprom struct
2205 memset(eeprom, 0, sizeof(struct ftdi_eeprom));
2207 // Addr 00: Stay 00 00
2209 // Addr 02: Vendor ID
2210 eeprom->vendor_id = buf[0x02] + (buf[0x03] << 8);
2212 // Addr 04: Product ID
2213 eeprom->product_id = buf[0x04] + (buf[0x05] << 8);
2215 value = buf[0x06] + (buf[0x07]<<8);
2219 eeprom->BM_type_chip = 1;
2222 eeprom->BM_type_chip = 0;
2224 default: // Unknown device
2225 eeprom->BM_type_chip = 0;
2229 // Addr 08: Config descriptor
2231 // Bit 6: 1 if this device is self powered, 0 if bus powered
2232 // Bit 5: 1 if this device uses remote wakeup
2233 // Bit 4: 1 if this device is battery powered
2235 if (j&0x40) eeprom->self_powered = 1;
2236 if (j&0x20) eeprom->remote_wakeup = 1;
2238 // Addr 09: Max power consumption: max power = value * 2 mA
2239 eeprom->max_power = buf[0x09];
2241 // Addr 0A: Chip configuration
2242 // Bit 7: 0 - reserved
2243 // Bit 6: 0 - reserved
2244 // Bit 5: 0 - reserved
2245 // Bit 4: 1 - Change USB version
2246 // Bit 3: 1 - Use the serial number string
2247 // Bit 2: 1 - Enable suspend pull downs for lower power
2248 // Bit 1: 1 - Out EndPoint is Isochronous
2249 // Bit 0: 1 - In EndPoint is Isochronous
2252 if (j&0x01) eeprom->in_is_isochronous = 1;
2253 if (j&0x02) eeprom->out_is_isochronous = 1;
2254 if (j&0x04) eeprom->suspend_pull_downs = 1;
2255 if (j&0x08) eeprom->use_serial = 1;
2256 if (j&0x10) eeprom->change_usb_version = 1;
2258 // Addr 0B: reserved
2260 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2261 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2262 if (eeprom->change_usb_version == 1)
2264 eeprom->usb_version = buf[0x0C] + (buf[0x0D] << 8);
2267 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2268 // Addr 0F: Length of manufacturer string
2269 manufacturer_size = buf[0x0F]/2;
2270 if (manufacturer_size > 0) eeprom->manufacturer = malloc(manufacturer_size);
2271 else eeprom->manufacturer = NULL;
2273 // Addr 10: Offset of the product string + 0x80, calculated later
2274 // Addr 11: Length of product string
2275 product_size = buf[0x11]/2;
2276 if (product_size > 0) eeprom->product = malloc(product_size);
2277 else eeprom->product = NULL;
2279 // Addr 12: Offset of the serial string + 0x80, calculated later
2280 // Addr 13: Length of serial string
2281 serial_size = buf[0x13]/2;
2282 if (serial_size > 0) eeprom->serial = malloc(serial_size);
2283 else eeprom->serial = NULL;
2285 // Decode manufacturer
2286 i = buf[0x0E] & 0x7f; // offset
2287 for (j=0;j<manufacturer_size-1;j++)
2289 eeprom->manufacturer[j] = buf[2*j+i+2];
2291 eeprom->manufacturer[j] = '\0';
2293 // Decode product name
2294 i = buf[0x10] & 0x7f; // offset
2295 for (j=0;j<product_size-1;j++)
2297 eeprom->product[j] = buf[2*j+i+2];
2299 eeprom->product[j] = '\0';
2302 i = buf[0x12] & 0x7f; // offset
2303 for (j=0;j<serial_size-1;j++)
2305 eeprom->serial[j] = buf[2*j+i+2];
2307 eeprom->serial[j] = '\0';
2312 for (i = 0; i < eeprom_size/2-1; i++)
2315 value += buf[(i*2)+1] << 8;
2317 checksum = value^checksum;
2318 checksum = (checksum << 1) | (checksum >> 15);
2321 eeprom_checksum = buf[eeprom_size-2] + (buf[eeprom_size-1] << 8);
2323 if (eeprom_checksum != checksum)
2325 fprintf(stderr, "Checksum Error: %04x %04x\n", checksum, eeprom_checksum);
2333 Read eeprom location
2335 \param ftdi pointer to ftdi_context
2336 \param eeprom_addr Address of eeprom location to be read
2337 \param eeprom_val Pointer to store read eeprom location
2340 \retval -1: read failed
2342 int ftdi_read_eeprom_location (struct ftdi_context *ftdi, int eeprom_addr, unsigned short *eeprom_val)
2344 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, eeprom_addr, (char *)eeprom_val, 2, ftdi->usb_read_timeout) != 2)
2345 ftdi_error_return(-1, "reading eeprom failed");
2353 \param ftdi pointer to ftdi_context
2354 \param eeprom Pointer to store eeprom into
2357 \retval -1: read failed
2359 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2363 for (i = 0; i < ftdi->eeprom_size/2; i++)
2365 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, i, eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2366 ftdi_error_return(-1, "reading eeprom failed");
2373 ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
2374 Function is only used internally
2377 static unsigned char ftdi_read_chipid_shift(unsigned char value)
2379 return ((value & 1) << 1) |
2380 ((value & 2) << 5) |
2381 ((value & 4) >> 2) |
2382 ((value & 8) << 4) |
2383 ((value & 16) >> 1) |
2384 ((value & 32) >> 1) |
2385 ((value & 64) >> 4) |
2386 ((value & 128) >> 2);
2390 Read the FTDIChip-ID from R-type devices
2392 \param ftdi pointer to ftdi_context
2393 \param chipid Pointer to store FTDIChip-ID
2396 \retval -1: read failed
2398 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
2400 unsigned int a = 0, b = 0;
2402 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, 0x43, (char *)&a, 2, ftdi->usb_read_timeout) == 2)
2404 a = a << 8 | a >> 8;
2405 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, 0x44, (char *)&b, 2, ftdi->usb_read_timeout) == 2)
2407 b = b << 8 | b >> 8;
2408 a = (a << 16) | (b & 0xFFFF);
2409 a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8
2410 | ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
2411 *chipid = a ^ 0xa5f0f7d1;
2416 ftdi_error_return(-1, "read of FTDIChip-ID failed");
2420 Guesses size of eeprom by reading eeprom and comparing halves - will not work with blank eeprom
2421 Call this function then do a write then call again to see if size changes, if so write again.
2423 \param ftdi pointer to ftdi_context
2424 \param eeprom Pointer to store eeprom into
2425 \param maxsize the size of the buffer to read into
2427 \retval size of eeprom
2429 int ftdi_read_eeprom_getsize(struct ftdi_context *ftdi, unsigned char *eeprom, int maxsize)
2431 int i=0,j,minsize=32;
2436 for (j = 0; i < maxsize/2 && j<size; j++)
2438 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE,
2439 SIO_READ_EEPROM_REQUEST, 0, i,
2440 eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2441 ftdi_error_return(-1, "reading eeprom failed");
2446 while (size<=maxsize && memcmp(eeprom,&eeprom[size/2],size/2)!=0);
2452 Write eeprom location
2454 \param ftdi pointer to ftdi_context
2455 \param eeprom_addr Address of eeprom location to be written
2456 \param eeprom_val Value to be written
2459 \retval -1: read failed
2461 int ftdi_write_eeprom_location(struct ftdi_context *ftdi, int eeprom_addr, unsigned short eeprom_val)
2463 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2464 SIO_WRITE_EEPROM_REQUEST, eeprom_val, eeprom_addr,
2465 NULL, 0, ftdi->usb_write_timeout) != 0)
2466 ftdi_error_return(-1, "unable to write eeprom");
2474 \param ftdi pointer to ftdi_context
2475 \param eeprom Pointer to read eeprom from
2478 \retval -1: read failed
2480 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2482 unsigned short usb_val, status;
2485 /* These commands were traced while running MProg */
2486 if ((ret = ftdi_usb_reset(ftdi)) != 0)
2488 if ((ret = ftdi_poll_modem_status(ftdi, &status)) != 0)
2490 if ((ret = ftdi_set_latency_timer(ftdi, 0x77)) != 0)
2493 for (i = 0; i < ftdi->eeprom_size/2; i++)
2495 usb_val = eeprom[i*2];
2496 usb_val += eeprom[(i*2)+1] << 8;
2497 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2498 SIO_WRITE_EEPROM_REQUEST, usb_val, i,
2499 NULL, 0, ftdi->usb_write_timeout) != 0)
2500 ftdi_error_return(-1, "unable to write eeprom");
2509 This is not supported on FT232R/FT245R according to the MProg manual from FTDI.
2511 \param ftdi pointer to ftdi_context
2514 \retval -1: erase failed
2516 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
2518 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_ERASE_EEPROM_REQUEST, 0, 0, NULL, 0, ftdi->usb_write_timeout) != 0)
2519 ftdi_error_return(-1, "unable to erase eeprom");
2525 Get string representation for last error code
2527 \param ftdi pointer to ftdi_context
2529 \retval Pointer to error string
2531 char *ftdi_get_error_string (struct ftdi_context *ftdi)
2533 return ftdi->error_str;
2536 /* @} end of doxygen libftdi group */