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;
718 char dev_name[PATH_MAX+1];
722 if (usb_find_busses() < 0)
723 ftdi_error_return(-1, "usb_find_busses() failed");
724 if (usb_find_devices() < 0)
725 ftdi_error_return(-2, "usb_find_devices() failed");
727 for (bus = usb_get_busses(); bus; bus = bus->next)
729 for (dev = bus->devices; dev; dev = dev->next)
731 snprintf(dev_name, sizeof(dev_name), "%s/%s",bus->dirname,dev->filename);
732 if (strcmp(description+2,dev_name) == 0)
733 return ftdi_usb_open_dev(ftdi, dev);
738 ftdi_error_return(-3, "device not found");
740 else if (description[0] == 'i' || description[0] == 's')
743 unsigned int product;
744 unsigned int index=0;
745 const char *serial=NULL;
746 const char *startp, *endp;
749 startp=description+2;
750 vendor=strtoul((char*)startp,(char**)&endp,0);
751 if (*endp != ':' || endp == startp || errno != 0)
752 ftdi_error_return(-11, "illegal description format");
755 product=strtoul((char*)startp,(char**)&endp,0);
756 if (endp == startp || errno != 0)
757 ftdi_error_return(-11, "illegal description format");
759 if (description[0] == 'i' && *endp != 0)
761 /* optional index field in i-mode */
763 ftdi_error_return(-11, "illegal description format");
766 index=strtoul((char*)startp,(char**)&endp,0);
767 if (*endp != 0 || endp == startp || errno != 0)
768 ftdi_error_return(-11, "illegal description format");
770 if (description[0] == 's')
773 ftdi_error_return(-11, "illegal description format");
775 /* rest of the description is the serial */
779 return ftdi_usb_open_desc_index(ftdi, vendor, product, NULL, serial, index);
783 ftdi_error_return(-11, "illegal description format");
788 Resets the ftdi device.
790 \param ftdi pointer to ftdi_context
793 \retval -1: FTDI reset failed
795 int ftdi_usb_reset(struct ftdi_context *ftdi)
797 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
798 SIO_RESET_REQUEST, SIO_RESET_SIO,
799 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
800 ftdi_error_return(-1,"FTDI reset failed");
802 // Invalidate data in the readbuffer
803 ftdi->readbuffer_offset = 0;
804 ftdi->readbuffer_remaining = 0;
810 Clears the read buffer on the chip and the internal read buffer.
812 \param ftdi pointer to ftdi_context
815 \retval -1: read buffer purge failed
817 int ftdi_usb_purge_rx_buffer(struct ftdi_context *ftdi)
819 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
820 SIO_RESET_REQUEST, SIO_RESET_PURGE_RX,
821 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
822 ftdi_error_return(-1, "FTDI purge of RX buffer failed");
824 // Invalidate data in the readbuffer
825 ftdi->readbuffer_offset = 0;
826 ftdi->readbuffer_remaining = 0;
832 Clears the write buffer on the chip.
834 \param ftdi pointer to ftdi_context
837 \retval -1: write buffer purge failed
839 int ftdi_usb_purge_tx_buffer(struct ftdi_context *ftdi)
841 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
842 SIO_RESET_REQUEST, SIO_RESET_PURGE_TX,
843 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
844 ftdi_error_return(-1, "FTDI purge of TX buffer failed");
850 Clears the buffers on the chip and the internal read buffer.
852 \param ftdi pointer to ftdi_context
855 \retval -1: read buffer purge failed
856 \retval -2: write buffer purge failed
858 int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
862 result = ftdi_usb_purge_rx_buffer(ftdi);
866 result = ftdi_usb_purge_tx_buffer(ftdi);
876 Closes the ftdi device. Call ftdi_deinit() if you're cleaning up.
878 \param ftdi pointer to ftdi_context
881 \retval -1: usb_release failed
882 \retval -2: usb_close failed
884 int ftdi_usb_close(struct ftdi_context *ftdi)
888 #ifdef LIBFTDI_LINUX_ASYNC_MODE
889 /* try to release some kernel resources */
890 ftdi_async_complete(ftdi,1);
893 if (ftdi->usb_dev != NULL)
894 if (usb_release_interface(ftdi->usb_dev, ftdi->interface) != 0)
897 if (ftdi_usb_close_internal (ftdi) != 0)
904 ftdi_convert_baudrate returns nearest supported baud rate to that requested.
905 Function is only used internally
908 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
909 unsigned short *value, unsigned short *index)
911 static const char am_adjust_up[8] = {0, 0, 0, 1, 0, 3, 2, 1};
912 static const char am_adjust_dn[8] = {0, 0, 0, 1, 0, 1, 2, 3};
913 static const char frac_code[8] = {0, 3, 2, 4, 1, 5, 6, 7};
914 int divisor, best_divisor, best_baud, best_baud_diff;
915 unsigned long encoded_divisor;
924 divisor = 24000000 / baudrate;
926 if (ftdi->type == TYPE_AM)
928 // Round down to supported fraction (AM only)
929 divisor -= am_adjust_dn[divisor & 7];
932 // Try this divisor and the one above it (because division rounds down)
936 for (i = 0; i < 2; i++)
938 int try_divisor = divisor + i;
942 // Round up to supported divisor value
943 if (try_divisor <= 8)
945 // Round up to minimum supported divisor
948 else if (ftdi->type != TYPE_AM && try_divisor < 12)
950 // BM doesn't support divisors 9 through 11 inclusive
953 else if (divisor < 16)
955 // AM doesn't support divisors 9 through 15 inclusive
960 if (ftdi->type == TYPE_AM)
962 // Round up to supported fraction (AM only)
963 try_divisor += am_adjust_up[try_divisor & 7];
964 if (try_divisor > 0x1FFF8)
966 // Round down to maximum supported divisor value (for AM)
967 try_divisor = 0x1FFF8;
972 if (try_divisor > 0x1FFFF)
974 // Round down to maximum supported divisor value (for BM)
975 try_divisor = 0x1FFFF;
979 // Get estimated baud rate (to nearest integer)
980 baud_estimate = (24000000 + (try_divisor / 2)) / try_divisor;
981 // Get absolute difference from requested baud rate
982 if (baud_estimate < baudrate)
984 baud_diff = baudrate - baud_estimate;
988 baud_diff = baud_estimate - baudrate;
990 if (i == 0 || baud_diff < best_baud_diff)
992 // Closest to requested baud rate so far
993 best_divisor = try_divisor;
994 best_baud = baud_estimate;
995 best_baud_diff = baud_diff;
998 // Spot on! No point trying
1003 // Encode the best divisor value
1004 encoded_divisor = (best_divisor >> 3) | (frac_code[best_divisor & 7] << 14);
1005 // Deal with special cases for encoded value
1006 if (encoded_divisor == 1)
1008 encoded_divisor = 0; // 3000000 baud
1010 else if (encoded_divisor == 0x4001)
1012 encoded_divisor = 1; // 2000000 baud (BM only)
1014 // Split into "value" and "index" values
1015 *value = (unsigned short)(encoded_divisor & 0xFFFF);
1016 if (ftdi->type == TYPE_2232C || ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
1018 *index = (unsigned short)(encoded_divisor >> 8);
1020 *index |= ftdi->index;
1023 *index = (unsigned short)(encoded_divisor >> 16);
1025 // Return the nearest baud rate
1030 Sets the chip baud rate
1032 \param ftdi pointer to ftdi_context
1033 \param baudrate baud rate to set
1036 \retval -1: invalid baudrate
1037 \retval -2: setting baudrate failed
1039 int ftdi_set_baudrate(struct ftdi_context *ftdi, int baudrate)
1041 unsigned short value, index;
1042 int actual_baudrate;
1044 if (ftdi->bitbang_enabled)
1046 baudrate = baudrate*4;
1049 actual_baudrate = ftdi_convert_baudrate(baudrate, ftdi, &value, &index);
1050 if (actual_baudrate <= 0)
1051 ftdi_error_return (-1, "Silly baudrate <= 0.");
1053 // Check within tolerance (about 5%)
1054 if ((actual_baudrate * 2 < baudrate /* Catch overflows */ )
1055 || ((actual_baudrate < baudrate)
1056 ? (actual_baudrate * 21 < baudrate * 20)
1057 : (baudrate * 21 < actual_baudrate * 20)))
1058 ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
1060 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1061 SIO_SET_BAUDRATE_REQUEST, value,
1062 index, NULL, 0, ftdi->usb_write_timeout) != 0)
1063 ftdi_error_return (-2, "Setting new baudrate failed");
1065 ftdi->baudrate = baudrate;
1070 Set (RS232) line characteristics.
1071 The break type can only be set via ftdi_set_line_property2()
1072 and defaults to "off".
1074 \param ftdi pointer to ftdi_context
1075 \param bits Number of bits
1076 \param sbit Number of stop bits
1077 \param parity Parity mode
1080 \retval -1: Setting line property failed
1082 int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1083 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
1085 return ftdi_set_line_property2(ftdi, bits, sbit, parity, BREAK_OFF);
1089 Set (RS232) line characteristics
1091 \param ftdi pointer to ftdi_context
1092 \param bits Number of bits
1093 \param sbit Number of stop bits
1094 \param parity Parity mode
1095 \param break_type Break type
1098 \retval -1: Setting line property failed
1100 int ftdi_set_line_property2(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1101 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity,
1102 enum ftdi_break_type break_type)
1104 unsigned short value = bits;
1109 value |= (0x00 << 8);
1112 value |= (0x01 << 8);
1115 value |= (0x02 << 8);
1118 value |= (0x03 << 8);
1121 value |= (0x04 << 8);
1128 value |= (0x00 << 11);
1131 value |= (0x01 << 11);
1134 value |= (0x02 << 11);
1141 value |= (0x00 << 14);
1144 value |= (0x01 << 14);
1148 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1149 SIO_SET_DATA_REQUEST, value,
1150 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1151 ftdi_error_return (-1, "Setting new line property failed");
1157 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip
1159 \param ftdi pointer to ftdi_context
1160 \param buf Buffer with the data
1161 \param size Size of the buffer
1163 \retval <0: error code from usb_bulk_write()
1164 \retval >0: number of bytes written
1166 int ftdi_write_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1170 int total_written = 0;
1172 while (offset < size)
1174 int write_size = ftdi->writebuffer_chunksize;
1176 if (offset+write_size > size)
1177 write_size = size-offset;
1179 ret = usb_bulk_write(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size, ftdi->usb_write_timeout);
1181 ftdi_error_return(ret, "usb bulk write failed");
1183 total_written += ret;
1184 offset += write_size;
1187 return total_written;
1190 #ifdef LIBFTDI_LINUX_ASYNC_MODE
1191 #ifdef USB_CLASS_PTP
1192 #error LIBFTDI_LINUX_ASYNC_MODE is not compatible with libusb-compat-0.1!
1194 /* this is strongly dependent on libusb using the same struct layout. If libusb
1195 changes in some later version this may break horribly (this is for libusb 0.1.12) */
1196 struct usb_dev_handle
1199 // some other stuff coming here we don't need
1203 Check for pending async urbs
1206 static int _usb_get_async_urbs_pending(struct ftdi_context *ftdi)
1208 struct usbdevfs_urb *urb;
1212 for (i=0; i < ftdi->async_usb_buffer_size; i++)
1214 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1215 if (urb->usercontext != FTDI_URB_USERCONTEXT_COOKIE)
1223 Wait until one or more async URBs are completed by the kernel and mark their
1224 positions in the async-buffer as unused
1226 \param ftdi pointer to ftdi_context
1227 \param wait_for_more if != 0 wait for more than one write to complete
1228 \param timeout_msec max milliseconds to wait
1232 static void _usb_async_cleanup(struct ftdi_context *ftdi, int wait_for_more, int timeout_msec)
1235 struct usbdevfs_urb *urb=NULL;
1241 FD_SET(ftdi->usb_dev->fd, &writefds);
1243 /* init timeout only once, select writes time left after call */
1244 tv.tv_sec = timeout_msec / 1000;
1245 tv.tv_usec = (timeout_msec % 1000) * 1000;
1249 while (_usb_get_async_urbs_pending(ftdi)
1250 && (ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_REAPURBNDELAY, &urb)) == -1
1253 if (keep_going && !wait_for_more)
1255 /* don't wait if repeating only for keep_going */
1260 /* wait for timeout msec or something written ready */
1261 select(ftdi->usb_dev->fd+1, NULL, &writefds, NULL, &tv);
1264 if (ret == 0 && urb != NULL)
1266 /* got a free urb, mark it */
1267 urb->usercontext = FTDI_URB_USERCONTEXT_COOKIE;
1269 /* try to get more urbs that are ready now, but don't wait anymore */
1275 /* no more urbs waiting */
1283 Wait until one or more async URBs are completed by the kernel and mark their
1284 positions in the async-buffer as unused.
1286 \param ftdi pointer to ftdi_context
1287 \param wait_for_more if != 0 wait for more than one write to complete (until write timeout)
1289 void ftdi_async_complete(struct ftdi_context *ftdi, int wait_for_more)
1291 _usb_async_cleanup(ftdi,wait_for_more,ftdi->usb_write_timeout);
1295 Stupid libusb does not offer async writes nor does it allow
1296 access to its fd - so we need some hacks here.
1299 static int _usb_bulk_write_async(struct ftdi_context *ftdi, int ep, char *bytes, int size)
1301 struct usbdevfs_urb *urb;
1302 int bytesdone = 0, requested;
1303 int ret, cleanup_count;
1308 /* find a free urb buffer we can use */
1310 for (cleanup_count=0; urb==NULL && cleanup_count <= 1; cleanup_count++)
1312 if (i==ftdi->async_usb_buffer_size)
1314 /* wait until some buffers are free */
1315 _usb_async_cleanup(ftdi,0,ftdi->usb_write_timeout);
1318 for (i=0; i < ftdi->async_usb_buffer_size; i++)
1320 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1321 if (urb->usercontext == FTDI_URB_USERCONTEXT_COOKIE)
1322 break; /* found a free urb position */
1327 /* no free urb position found */
1331 requested = size - bytesdone;
1332 if (requested > 4096)
1335 memset(urb,0,sizeof(urb));
1337 urb->type = USBDEVFS_URB_TYPE_BULK;
1340 urb->buffer = bytes + bytesdone;
1341 urb->buffer_length = requested;
1343 urb->actual_length = 0;
1344 urb->number_of_packets = 0;
1345 urb->usercontext = 0;
1349 ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_SUBMITURB, urb);
1351 while (ret < 0 && errno == EINTR);
1353 return ret; /* the caller can read errno to get more info */
1355 bytesdone += requested;
1357 while (bytesdone < size);
1362 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip.
1363 Does not wait for completion of the transfer nor does it make sure that
1364 the transfer was successful.
1366 This function could be extended to use signals and callbacks to inform the
1367 caller of completion or error - but this is not done yet, volunteers welcome.
1369 Works around libusb and directly accesses functions only available on Linux.
1370 Only available if compiled with --with-async-mode.
1372 \param ftdi pointer to ftdi_context
1373 \param buf Buffer with the data
1374 \param size Size of the buffer
1376 \retval <0: error code from usb_bulk_write()
1377 \retval >0: number of bytes written
1379 int ftdi_write_data_async(struct ftdi_context *ftdi, unsigned char *buf, int size)
1383 int total_written = 0;
1385 while (offset < size)
1387 int write_size = ftdi->writebuffer_chunksize;
1389 if (offset+write_size > size)
1390 write_size = size-offset;
1392 ret = _usb_bulk_write_async(ftdi, ftdi->in_ep, buf+offset, write_size);
1394 ftdi_error_return(ret, "usb bulk write async failed");
1396 total_written += ret;
1397 offset += write_size;
1400 return total_written;
1402 #endif // LIBFTDI_LINUX_ASYNC_MODE
1405 Configure write buffer chunk size.
1408 \param ftdi pointer to ftdi_context
1409 \param chunksize Chunk size
1413 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1415 ftdi->writebuffer_chunksize = chunksize;
1420 Get write buffer chunk size.
1422 \param ftdi pointer to ftdi_context
1423 \param chunksize Pointer to store chunk size in
1427 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1429 *chunksize = ftdi->writebuffer_chunksize;
1434 Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
1436 Automatically strips the two modem status bytes transfered during every read.
1438 \param ftdi pointer to ftdi_context
1439 \param buf Buffer to store data in
1440 \param size Size of the buffer
1442 \retval <0: error code from usb_bulk_read()
1443 \retval 0: no data was available
1444 \retval >0: number of bytes read
1447 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1449 int offset = 0, ret = 1, i, num_of_chunks, chunk_remains;
1450 int packet_size = ftdi->max_packet_size;
1452 // Packet size sanity check (avoid division by zero)
1453 if (packet_size == 0)
1454 ftdi_error_return(-1, "max_packet_size is bogus (zero)");
1456 // everything we want is still in the readbuffer?
1457 if (size <= ftdi->readbuffer_remaining)
1459 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1462 ftdi->readbuffer_remaining -= size;
1463 ftdi->readbuffer_offset += size;
1465 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1469 // something still in the readbuffer, but not enough to satisfy 'size'?
1470 if (ftdi->readbuffer_remaining != 0)
1472 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1475 offset += ftdi->readbuffer_remaining;
1477 // do the actual USB read
1478 while (offset < size && ret > 0)
1480 ftdi->readbuffer_remaining = 0;
1481 ftdi->readbuffer_offset = 0;
1482 /* returns how much received */
1483 ret = usb_bulk_read (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, ftdi->usb_read_timeout);
1485 ftdi_error_return(ret, "usb bulk read failed");
1489 // skip FTDI status bytes.
1490 // Maybe stored in the future to enable modem use
1491 num_of_chunks = ret / packet_size;
1492 chunk_remains = ret % packet_size;
1493 //printf("ret = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", ret, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
1495 ftdi->readbuffer_offset += 2;
1498 if (ret > packet_size - 2)
1500 for (i = 1; i < num_of_chunks; i++)
1501 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1502 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1504 if (chunk_remains > 2)
1506 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1507 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1509 ret -= 2*num_of_chunks;
1512 ret -= 2*(num_of_chunks-1)+chunk_remains;
1517 // no more data to read?
1522 // data still fits in buf?
1523 if (offset+ret <= size)
1525 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, ret);
1526 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1529 /* Did we read exactly the right amount of bytes? */
1531 //printf("read_data exact rem %d offset %d\n",
1532 //ftdi->readbuffer_remaining, offset);
1537 // only copy part of the data or size <= readbuffer_chunksize
1538 int part_size = size-offset;
1539 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
1541 ftdi->readbuffer_offset += part_size;
1542 ftdi->readbuffer_remaining = ret-part_size;
1543 offset += part_size;
1545 /* printf("Returning part: %d - size: %d - offset: %d - ret: %d - remaining: %d\n",
1546 part_size, size, offset, ret, ftdi->readbuffer_remaining); */
1557 Configure read buffer chunk size.
1560 Automatically reallocates the buffer.
1562 \param ftdi pointer to ftdi_context
1563 \param chunksize Chunk size
1567 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1569 unsigned char *new_buf;
1571 // Invalidate all remaining data
1572 ftdi->readbuffer_offset = 0;
1573 ftdi->readbuffer_remaining = 0;
1575 if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
1576 ftdi_error_return(-1, "out of memory for readbuffer");
1578 ftdi->readbuffer = new_buf;
1579 ftdi->readbuffer_chunksize = chunksize;
1585 Get read buffer chunk size.
1587 \param ftdi pointer to ftdi_context
1588 \param chunksize Pointer to store chunk size in
1592 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1594 *chunksize = ftdi->readbuffer_chunksize;
1600 Enable bitbang mode.
1602 \deprecated use \ref ftdi_set_bitmode with mode BITMODE_BITBANG instead
1604 \param ftdi pointer to ftdi_context
1605 \param bitmask Bitmask to configure lines.
1606 HIGH/ON value configures a line as output.
1609 \retval -1: can't enable bitbang mode
1611 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
1613 unsigned short usb_val;
1615 usb_val = bitmask; // low byte: bitmask
1616 /* FT2232C: Set bitbang_mode to 2 to enable SPI */
1617 usb_val |= (ftdi->bitbang_mode << 8);
1619 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1620 SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index,
1621 NULL, 0, ftdi->usb_write_timeout) != 0)
1622 ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
1624 ftdi->bitbang_enabled = 1;
1629 Disable bitbang mode.
1631 \param ftdi pointer to ftdi_context
1634 \retval -1: can't disable bitbang mode
1636 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
1638 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_BITMODE_REQUEST, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1639 ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
1641 ftdi->bitbang_enabled = 0;
1646 Enable/disable bitbang modes.
1648 \param ftdi pointer to ftdi_context
1649 \param bitmask Bitmask to configure lines.
1650 HIGH/ON value configures a line as output.
1651 \param mode Bitbang mode: use the values defined in \ref ftdi_mpsse_mode
1654 \retval -1: can't enable bitbang mode
1656 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
1658 unsigned short usb_val;
1660 usb_val = bitmask; // low byte: bitmask
1661 usb_val |= (mode << 8);
1662 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1663 ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps selected mode not supported on your chip?");
1665 ftdi->bitbang_mode = mode;
1666 ftdi->bitbang_enabled = (mode == BITMODE_RESET) ? 0 : 1;
1671 Directly read pin state, circumventing the read buffer. Useful for bitbang mode.
1673 \param ftdi pointer to ftdi_context
1674 \param pins Pointer to store pins into
1677 \retval -1: read pins failed
1679 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
1681 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_PINS_REQUEST, 0, ftdi->index, (char *)pins, 1, ftdi->usb_read_timeout) != 1)
1682 ftdi_error_return(-1, "read pins failed");
1690 The FTDI chip keeps data in the internal buffer for a specific
1691 amount of time if the buffer is not full yet to decrease
1692 load on the usb bus.
1694 \param ftdi pointer to ftdi_context
1695 \param latency Value between 1 and 255
1698 \retval -1: latency out of range
1699 \retval -2: unable to set latency timer
1701 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
1703 unsigned short usb_val;
1706 ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
1709 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_LATENCY_TIMER_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1710 ftdi_error_return(-2, "unable to set latency timer");
1718 \param ftdi pointer to ftdi_context
1719 \param latency Pointer to store latency value in
1722 \retval -1: unable to get latency timer
1724 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1726 unsigned short usb_val;
1727 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_GET_LATENCY_TIMER_REQUEST, 0, ftdi->index, (char *)&usb_val, 1, ftdi->usb_read_timeout) != 1)
1728 ftdi_error_return(-1, "reading latency timer failed");
1730 *latency = (unsigned char)usb_val;
1735 Poll modem status information
1737 This function allows the retrieve the two status bytes of the device.
1738 The device sends these bytes also as a header for each read access
1739 where they are discarded by ftdi_read_data(). The chip generates
1740 the two stripped status bytes in the absence of data every 40 ms.
1742 Layout of the first byte:
1743 - B0..B3 - must be 0
1744 - B4 Clear to send (CTS)
1747 - B5 Data set ready (DTS)
1750 - B6 Ring indicator (RI)
1753 - B7 Receive line signal detect (RLSD)
1757 Layout of the second byte:
1758 - B0 Data ready (DR)
1759 - B1 Overrun error (OE)
1760 - B2 Parity error (PE)
1761 - B3 Framing error (FE)
1762 - B4 Break interrupt (BI)
1763 - B5 Transmitter holding register (THRE)
1764 - B6 Transmitter empty (TEMT)
1765 - B7 Error in RCVR FIFO
1767 \param ftdi pointer to ftdi_context
1768 \param status Pointer to store status information in. Must be two bytes.
1771 \retval -1: unable to retrieve status information
1773 int ftdi_poll_modem_status(struct ftdi_context *ftdi, unsigned short *status)
1777 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_POLL_MODEM_STATUS_REQUEST, 0, ftdi->index, usb_val, 2, ftdi->usb_read_timeout) != 2)
1778 ftdi_error_return(-1, "getting modem status failed");
1780 *status = (usb_val[1] << 8) | usb_val[0];
1786 Set flowcontrol for ftdi chip
1788 \param ftdi pointer to ftdi_context
1789 \param flowctrl flow control to use. should be
1790 SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1793 \retval -1: set flow control failed
1795 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1797 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1798 SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->index),
1799 NULL, 0, ftdi->usb_write_timeout) != 0)
1800 ftdi_error_return(-1, "set flow control failed");
1808 \param ftdi pointer to ftdi_context
1809 \param state state to set line to (1 or 0)
1812 \retval -1: set dtr failed
1814 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
1816 unsigned short usb_val;
1819 usb_val = SIO_SET_DTR_HIGH;
1821 usb_val = SIO_SET_DTR_LOW;
1823 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1824 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1825 NULL, 0, ftdi->usb_write_timeout) != 0)
1826 ftdi_error_return(-1, "set dtr failed");
1834 \param ftdi pointer to ftdi_context
1835 \param state state to set line to (1 or 0)
1838 \retval -1 set rts failed
1840 int ftdi_setrts(struct ftdi_context *ftdi, int state)
1842 unsigned short usb_val;
1845 usb_val = SIO_SET_RTS_HIGH;
1847 usb_val = SIO_SET_RTS_LOW;
1849 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1850 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1851 NULL, 0, ftdi->usb_write_timeout) != 0)
1852 ftdi_error_return(-1, "set of rts failed");
1858 Set dtr and rts line in one pass
1860 \param ftdi pointer to ftdi_context
1861 \param dtr DTR state to set line to (1 or 0)
1862 \param rts RTS state to set line to (1 or 0)
1865 \retval -1 set dtr/rts failed
1867 int ftdi_setdtr_rts(struct ftdi_context *ftdi, int dtr, int rts)
1869 unsigned short usb_val;
1872 usb_val = SIO_SET_DTR_HIGH;
1874 usb_val = SIO_SET_DTR_LOW;
1877 usb_val |= SIO_SET_RTS_HIGH;
1879 usb_val |= SIO_SET_RTS_LOW;
1881 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1882 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1883 NULL, 0, ftdi->usb_write_timeout) != 0)
1884 ftdi_error_return(-1, "set of rts/dtr failed");
1890 Set the special event character
1892 \param ftdi pointer to ftdi_context
1893 \param eventch Event character
1894 \param enable 0 to disable the event character, non-zero otherwise
1897 \retval -1: unable to set event character
1899 int ftdi_set_event_char(struct ftdi_context *ftdi,
1900 unsigned char eventch, unsigned char enable)
1902 unsigned short usb_val;
1908 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_EVENT_CHAR_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1909 ftdi_error_return(-1, "setting event character failed");
1917 \param ftdi pointer to ftdi_context
1918 \param errorch Error character
1919 \param enable 0 to disable the error character, non-zero otherwise
1922 \retval -1: unable to set error character
1924 int ftdi_set_error_char(struct ftdi_context *ftdi,
1925 unsigned char errorch, unsigned char enable)
1927 unsigned short usb_val;
1933 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_SET_ERROR_CHAR_REQUEST, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1934 ftdi_error_return(-1, "setting error character failed");
1942 \param ftdi pointer to ftdi_context
1943 \param eeprom Pointer to ftdi_eeprom
1947 void ftdi_eeprom_setsize(struct ftdi_context *ftdi, struct ftdi_eeprom *eeprom, int size)
1949 ftdi->eeprom_size=size;
1954 Init eeprom with default values.
1956 \param eeprom Pointer to ftdi_eeprom
1958 void ftdi_eeprom_initdefaults(struct ftdi_eeprom *eeprom)
1960 eeprom->vendor_id = 0x0403;
1961 eeprom->product_id = 0x6001;
1963 eeprom->self_powered = 1;
1964 eeprom->remote_wakeup = 1;
1965 eeprom->BM_type_chip = 1;
1967 eeprom->in_is_isochronous = 0;
1968 eeprom->out_is_isochronous = 0;
1969 eeprom->suspend_pull_downs = 0;
1971 eeprom->use_serial = 0;
1972 eeprom->change_usb_version = 0;
1973 eeprom->usb_version = 0x0200;
1974 eeprom->max_power = 0;
1976 eeprom->manufacturer = NULL;
1977 eeprom->product = NULL;
1978 eeprom->serial = NULL;
1980 eeprom->size = FTDI_DEFAULT_EEPROM_SIZE;
1984 Build binary output from ftdi_eeprom structure.
1985 Output is suitable for ftdi_write_eeprom().
1987 \param eeprom Pointer to ftdi_eeprom
1988 \param output Buffer of 128 bytes to store eeprom image to
1990 \retval >0: used eeprom size
1991 \retval -1: eeprom size (128 bytes) exceeded by custom strings
1993 int ftdi_eeprom_build(struct ftdi_eeprom *eeprom, unsigned char *output)
1996 unsigned short checksum, value;
1997 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2000 if (eeprom->manufacturer != NULL)
2001 manufacturer_size = strlen(eeprom->manufacturer);
2002 if (eeprom->product != NULL)
2003 product_size = strlen(eeprom->product);
2004 if (eeprom->serial != NULL)
2005 serial_size = strlen(eeprom->serial);
2007 size_check = eeprom->size;
2008 size_check -= 28; // 28 are always in use (fixed)
2010 // Top half of a 256byte eeprom is used just for strings and checksum
2011 // it seems that the FTDI chip will not read these strings from the lower half
2012 // Each string starts with two bytes; offset and type (0x03 for string)
2013 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2014 if (eeprom->size>=256)size_check = 120;
2015 size_check -= manufacturer_size*2;
2016 size_check -= product_size*2;
2017 size_check -= serial_size*2;
2019 // eeprom size exceeded?
2024 memset (output, 0, eeprom->size);
2026 // Addr 00: Stay 00 00
2027 // Addr 02: Vendor ID
2028 output[0x02] = eeprom->vendor_id;
2029 output[0x03] = eeprom->vendor_id >> 8;
2031 // Addr 04: Product ID
2032 output[0x04] = eeprom->product_id;
2033 output[0x05] = eeprom->product_id >> 8;
2035 // Addr 06: Device release number (0400h for BM features)
2036 output[0x06] = 0x00;
2038 if (eeprom->BM_type_chip == 1)
2039 output[0x07] = 0x04;
2041 output[0x07] = 0x02;
2043 // Addr 08: Config descriptor
2045 // Bit 6: 1 if this device is self powered, 0 if bus powered
2046 // Bit 5: 1 if this device uses remote wakeup
2047 // Bit 4: 1 if this device is battery powered
2049 if (eeprom->self_powered == 1)
2051 if (eeprom->remote_wakeup == 1)
2055 // Addr 09: Max power consumption: max power = value * 2 mA
2056 output[0x09] = eeprom->max_power;
2058 // Addr 0A: Chip configuration
2059 // Bit 7: 0 - reserved
2060 // Bit 6: 0 - reserved
2061 // Bit 5: 0 - reserved
2062 // Bit 4: 1 - Change USB version
2063 // Bit 3: 1 - Use the serial number string
2064 // Bit 2: 1 - Enable suspend pull downs for lower power
2065 // Bit 1: 1 - Out EndPoint is Isochronous
2066 // Bit 0: 1 - In EndPoint is Isochronous
2069 if (eeprom->in_is_isochronous == 1)
2071 if (eeprom->out_is_isochronous == 1)
2073 if (eeprom->suspend_pull_downs == 1)
2075 if (eeprom->use_serial == 1)
2077 if (eeprom->change_usb_version == 1)
2081 // Addr 0B: reserved
2082 output[0x0B] = 0x00;
2084 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2085 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2086 if (eeprom->change_usb_version == 1)
2088 output[0x0C] = eeprom->usb_version;
2089 output[0x0D] = eeprom->usb_version >> 8;
2093 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2094 // Addr 0F: Length of manufacturer string
2095 output[0x0F] = manufacturer_size*2 + 2;
2097 // Addr 10: Offset of the product string + 0x80, calculated later
2098 // Addr 11: Length of product string
2099 output[0x11] = product_size*2 + 2;
2101 // Addr 12: Offset of the serial string + 0x80, calculated later
2102 // Addr 13: Length of serial string
2103 output[0x13] = serial_size*2 + 2;
2107 if (eeprom->size>=256) i = 0x80;
2110 // Output manufacturer
2111 output[0x0E] = i | 0x80; // calculate offset
2112 output[i++] = manufacturer_size*2 + 2;
2113 output[i++] = 0x03; // type: string
2114 for (j = 0; j < manufacturer_size; j++)
2116 output[i] = eeprom->manufacturer[j], i++;
2117 output[i] = 0x00, i++;
2120 // Output product name
2121 output[0x10] = i | 0x80; // calculate offset
2122 output[i] = product_size*2 + 2, i++;
2123 output[i] = 0x03, i++;
2124 for (j = 0; j < product_size; j++)
2126 output[i] = eeprom->product[j], i++;
2127 output[i] = 0x00, i++;
2131 output[0x12] = i | 0x80; // calculate offset
2132 output[i] = serial_size*2 + 2, i++;
2133 output[i] = 0x03, i++;
2134 for (j = 0; j < serial_size; j++)
2136 output[i] = eeprom->serial[j], i++;
2137 output[i] = 0x00, i++;
2140 // calculate checksum
2143 for (i = 0; i < eeprom->size/2-1; i++)
2145 value = output[i*2];
2146 value += output[(i*2)+1] << 8;
2148 checksum = value^checksum;
2149 checksum = (checksum << 1) | (checksum >> 15);
2152 output[eeprom->size-2] = checksum;
2153 output[eeprom->size-1] = checksum >> 8;
2159 Decode binary EEPROM image into an ftdi_eeprom structure.
2161 \param eeprom Pointer to ftdi_eeprom which will be filled in.
2162 \param buf Buffer of \a size bytes of raw eeprom data
2163 \param size size size of eeprom data in bytes
2166 \retval -1: something went wrong
2168 FIXME: How to pass size? How to handle size field in ftdi_eeprom?
2169 FIXME: Strings are malloc'ed here and should be freed somewhere
2171 int ftdi_eeprom_decode(struct ftdi_eeprom *eeprom, unsigned char *buf, int size)
2174 unsigned short checksum, eeprom_checksum, value;
2175 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2177 int eeprom_size = 128;
2179 size_check = eeprom->size;
2180 size_check -= 28; // 28 are always in use (fixed)
2182 // Top half of a 256byte eeprom is used just for strings and checksum
2183 // it seems that the FTDI chip will not read these strings from the lower half
2184 // Each string starts with two bytes; offset and type (0x03 for string)
2185 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2186 if (eeprom->size>=256)size_check = 120;
2187 size_check -= manufacturer_size*2;
2188 size_check -= product_size*2;
2189 size_check -= serial_size*2;
2191 // eeprom size exceeded?
2196 // empty eeprom struct
2197 memset(eeprom, 0, sizeof(struct ftdi_eeprom));
2199 // Addr 00: Stay 00 00
2201 // Addr 02: Vendor ID
2202 eeprom->vendor_id = buf[0x02] + (buf[0x03] << 8);
2204 // Addr 04: Product ID
2205 eeprom->product_id = buf[0x04] + (buf[0x05] << 8);
2207 value = buf[0x06] + (buf[0x07]<<8);
2211 eeprom->BM_type_chip = 1;
2214 eeprom->BM_type_chip = 0;
2216 default: // Unknown device
2217 eeprom->BM_type_chip = 0;
2221 // Addr 08: Config descriptor
2223 // Bit 6: 1 if this device is self powered, 0 if bus powered
2224 // Bit 5: 1 if this device uses remote wakeup
2225 // Bit 4: 1 if this device is battery powered
2227 if (j&0x40) eeprom->self_powered = 1;
2228 if (j&0x20) eeprom->remote_wakeup = 1;
2230 // Addr 09: Max power consumption: max power = value * 2 mA
2231 eeprom->max_power = buf[0x09];
2233 // Addr 0A: Chip configuration
2234 // Bit 7: 0 - reserved
2235 // Bit 6: 0 - reserved
2236 // Bit 5: 0 - reserved
2237 // Bit 4: 1 - Change USB version
2238 // Bit 3: 1 - Use the serial number string
2239 // Bit 2: 1 - Enable suspend pull downs for lower power
2240 // Bit 1: 1 - Out EndPoint is Isochronous
2241 // Bit 0: 1 - In EndPoint is Isochronous
2244 if (j&0x01) eeprom->in_is_isochronous = 1;
2245 if (j&0x02) eeprom->out_is_isochronous = 1;
2246 if (j&0x04) eeprom->suspend_pull_downs = 1;
2247 if (j&0x08) eeprom->use_serial = 1;
2248 if (j&0x10) eeprom->change_usb_version = 1;
2250 // Addr 0B: reserved
2252 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2253 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2254 if (eeprom->change_usb_version == 1)
2256 eeprom->usb_version = buf[0x0C] + (buf[0x0D] << 8);
2259 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2260 // Addr 0F: Length of manufacturer string
2261 manufacturer_size = buf[0x0F]/2;
2262 if (manufacturer_size > 0) eeprom->manufacturer = malloc(manufacturer_size);
2263 else eeprom->manufacturer = NULL;
2265 // Addr 10: Offset of the product string + 0x80, calculated later
2266 // Addr 11: Length of product string
2267 product_size = buf[0x11]/2;
2268 if (product_size > 0) eeprom->product = malloc(product_size);
2269 else eeprom->product = NULL;
2271 // Addr 12: Offset of the serial string + 0x80, calculated later
2272 // Addr 13: Length of serial string
2273 serial_size = buf[0x13]/2;
2274 if (serial_size > 0) eeprom->serial = malloc(serial_size);
2275 else eeprom->serial = NULL;
2277 // Decode manufacturer
2278 i = buf[0x0E] & 0x7f; // offset
2279 for (j=0;j<manufacturer_size-1;j++)
2281 eeprom->manufacturer[j] = buf[2*j+i+2];
2283 eeprom->manufacturer[j] = '\0';
2285 // Decode product name
2286 i = buf[0x10] & 0x7f; // offset
2287 for (j=0;j<product_size-1;j++)
2289 eeprom->product[j] = buf[2*j+i+2];
2291 eeprom->product[j] = '\0';
2294 i = buf[0x12] & 0x7f; // offset
2295 for (j=0;j<serial_size-1;j++)
2297 eeprom->serial[j] = buf[2*j+i+2];
2299 eeprom->serial[j] = '\0';
2304 for (i = 0; i < eeprom_size/2-1; i++)
2307 value += buf[(i*2)+1] << 8;
2309 checksum = value^checksum;
2310 checksum = (checksum << 1) | (checksum >> 15);
2313 eeprom_checksum = buf[eeprom_size-2] + (buf[eeprom_size-1] << 8);
2315 if (eeprom_checksum != checksum)
2317 fprintf(stderr, "Checksum Error: %04x %04x\n", checksum, eeprom_checksum);
2325 Read eeprom location
2327 \param ftdi pointer to ftdi_context
2328 \param eeprom_addr Address of eeprom location to be read
2329 \param eeprom_val Pointer to store read eeprom location
2332 \retval -1: read failed
2334 int ftdi_read_eeprom_location (struct ftdi_context *ftdi, int eeprom_addr, unsigned short *eeprom_val)
2336 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, eeprom_addr, (char *)eeprom_val, 2, ftdi->usb_read_timeout) != 2)
2337 ftdi_error_return(-1, "reading eeprom failed");
2345 \param ftdi pointer to ftdi_context
2346 \param eeprom Pointer to store eeprom into
2349 \retval -1: read failed
2351 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2355 for (i = 0; i < ftdi->eeprom_size/2; i++)
2357 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, i, eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2358 ftdi_error_return(-1, "reading eeprom failed");
2365 ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
2366 Function is only used internally
2369 static unsigned char ftdi_read_chipid_shift(unsigned char value)
2371 return ((value & 1) << 1) |
2372 ((value & 2) << 5) |
2373 ((value & 4) >> 2) |
2374 ((value & 8) << 4) |
2375 ((value & 16) >> 1) |
2376 ((value & 32) >> 1) |
2377 ((value & 64) >> 4) |
2378 ((value & 128) >> 2);
2382 Read the FTDIChip-ID from R-type devices
2384 \param ftdi pointer to ftdi_context
2385 \param chipid Pointer to store FTDIChip-ID
2388 \retval -1: read failed
2390 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
2392 unsigned int a = 0, b = 0;
2394 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, 0x43, (char *)&a, 2, ftdi->usb_read_timeout) == 2)
2396 a = a << 8 | a >> 8;
2397 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE, SIO_READ_EEPROM_REQUEST, 0, 0x44, (char *)&b, 2, ftdi->usb_read_timeout) == 2)
2399 b = b << 8 | b >> 8;
2400 a = (a << 16) | (b & 0xFFFF);
2401 a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8
2402 | ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
2403 *chipid = a ^ 0xa5f0f7d1;
2408 ftdi_error_return(-1, "read of FTDIChip-ID failed");
2412 Guesses size of eeprom by reading eeprom and comparing halves - will not work with blank eeprom
2413 Call this function then do a write then call again to see if size changes, if so write again.
2415 \param ftdi pointer to ftdi_context
2416 \param eeprom Pointer to store eeprom into
2417 \param maxsize the size of the buffer to read into
2419 \retval size of eeprom
2421 int ftdi_read_eeprom_getsize(struct ftdi_context *ftdi, unsigned char *eeprom, int maxsize)
2423 int i=0,j,minsize=32;
2428 for (j = 0; i < maxsize/2 && j<size; j++)
2430 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE,
2431 SIO_READ_EEPROM_REQUEST, 0, i,
2432 eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2433 ftdi_error_return(-1, "reading eeprom failed");
2438 while (size<=maxsize && memcmp(eeprom,&eeprom[size/2],size/2)!=0);
2444 Write eeprom location
2446 \param ftdi pointer to ftdi_context
2447 \param eeprom_addr Address of eeprom location to be written
2448 \param eeprom_val Value to be written
2451 \retval -1: read failed
2453 int ftdi_write_eeprom_location(struct ftdi_context *ftdi, int eeprom_addr, unsigned short eeprom_val)
2455 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2456 SIO_WRITE_EEPROM_REQUEST, eeprom_val, eeprom_addr,
2457 NULL, 0, ftdi->usb_write_timeout) != 0)
2458 ftdi_error_return(-1, "unable to write eeprom");
2466 \param ftdi pointer to ftdi_context
2467 \param eeprom Pointer to read eeprom from
2470 \retval -1: read failed
2472 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2474 unsigned short usb_val, status;
2477 /* These commands were traced while running MProg */
2478 if ((ret = ftdi_usb_reset(ftdi)) != 0)
2480 if ((ret = ftdi_poll_modem_status(ftdi, &status)) != 0)
2482 if ((ret = ftdi_set_latency_timer(ftdi, 0x77)) != 0)
2485 for (i = 0; i < ftdi->eeprom_size/2; i++)
2487 usb_val = eeprom[i*2];
2488 usb_val += eeprom[(i*2)+1] << 8;
2489 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2490 SIO_WRITE_EEPROM_REQUEST, usb_val, i,
2491 NULL, 0, ftdi->usb_write_timeout) != 0)
2492 ftdi_error_return(-1, "unable to write eeprom");
2501 This is not supported on FT232R/FT245R according to the MProg manual from FTDI.
2503 \param ftdi pointer to ftdi_context
2506 \retval -1: erase failed
2508 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
2510 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_ERASE_EEPROM_REQUEST, 0, 0, NULL, 0, ftdi->usb_write_timeout) != 0)
2511 ftdi_error_return(-1, "unable to erase eeprom");
2517 Get string representation for last error code
2519 \param ftdi pointer to ftdi_context
2521 \retval Pointer to error string
2523 char *ftdi_get_error_string (struct ftdi_context *ftdi)
2525 return ftdi->error_str;
2528 /* @} end of doxygen libftdi group */