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; \
54 Internal function to close usb device pointer.
55 Sets ftdi->usb_dev to NULL.
58 \param ftdi pointer to ftdi_context
60 \retval zero if all is fine, otherwise error code from usb_close()
62 static int ftdi_usb_close_internal (struct ftdi_context *ftdi)
68 ret = usb_close (ftdi->usb_dev);
76 Initializes a ftdi_context.
78 \param ftdi pointer to ftdi_context
81 \retval -1: couldn't allocate read buffer
83 \remark This should be called before all functions
85 int ftdi_init(struct ftdi_context *ftdi)
90 ftdi->usb_read_timeout = 5000;
91 ftdi->usb_write_timeout = 5000;
93 ftdi->type = TYPE_BM; /* chip type */
95 ftdi->bitbang_enabled = 0;
97 ftdi->readbuffer = NULL;
98 ftdi->readbuffer_offset = 0;
99 ftdi->readbuffer_remaining = 0;
100 ftdi->writebuffer_chunksize = 4096;
101 ftdi->max_packet_size = 0;
107 ftdi->bitbang_mode = 1; /* 1: Normal bitbang mode, 2: SPI bitbang mode */
109 ftdi->error_str = NULL;
111 #ifdef LIBFTDI_LINUX_ASYNC_MODE
112 ftdi->async_usb_buffer_size=10;
113 if ((ftdi->async_usb_buffer=malloc(sizeof(struct usbdevfs_urb)*ftdi->async_usb_buffer_size)) == NULL)
114 ftdi_error_return(-1, "out of memory for async usb buffer");
116 /* initialize async usb buffer with unused-marker */
117 for (i=0; i < ftdi->async_usb_buffer_size; i++)
118 ((struct usbdevfs_urb*)ftdi->async_usb_buffer)[i].usercontext = FTDI_URB_USERCONTEXT_COOKIE;
120 ftdi->async_usb_buffer_size=0;
121 ftdi->async_usb_buffer = NULL;
124 ftdi->eeprom_size = FTDI_DEFAULT_EEPROM_SIZE;
126 /* All fine. Now allocate the readbuffer */
127 return ftdi_read_data_set_chunksize(ftdi, 4096);
131 Allocate and initialize a new ftdi_context
133 \return a pointer to a new ftdi_context, or NULL on failure
135 struct ftdi_context *ftdi_new(void)
137 struct ftdi_context * ftdi = (struct ftdi_context *)malloc(sizeof(struct ftdi_context));
144 if (ftdi_init(ftdi) != 0)
154 Open selected channels on a chip, otherwise use first channel.
156 \param ftdi pointer to ftdi_context
157 \param interface Interface to use for FT2232C/2232H/4232H chips.
160 \retval -1: unknown interface
162 int ftdi_set_interface(struct ftdi_context *ftdi, enum ftdi_interface interface)
168 /* ftdi_usb_open_desc cares to set the right index, depending on the found chip */
172 ftdi->index = INTERFACE_B;
178 ftdi->index = INTERFACE_C;
184 ftdi->index = INTERFACE_D;
189 ftdi_error_return(-1, "Unknown interface");
195 Deinitializes a ftdi_context.
197 \param ftdi pointer to ftdi_context
199 void ftdi_deinit(struct ftdi_context *ftdi)
201 ftdi_usb_close_internal (ftdi);
203 if (ftdi->async_usb_buffer != NULL)
205 free(ftdi->async_usb_buffer);
206 ftdi->async_usb_buffer = NULL;
209 if (ftdi->readbuffer != NULL)
211 free(ftdi->readbuffer);
212 ftdi->readbuffer = NULL;
217 Deinitialize and free an ftdi_context.
219 \param ftdi pointer to ftdi_context
221 void ftdi_free(struct ftdi_context *ftdi)
228 Use an already open libusb device.
230 \param ftdi pointer to ftdi_context
231 \param usb libusb usb_dev_handle to use
233 void ftdi_set_usbdev (struct ftdi_context *ftdi, usb_dev_handle *usb)
240 Finds all ftdi devices on the usb bus. Creates a new ftdi_device_list which
241 needs to be deallocated by ftdi_list_free() after use.
243 \param ftdi pointer to ftdi_context
244 \param devlist Pointer where to store list of found devices
245 \param vendor Vendor ID to search for
246 \param product Product ID to search for
248 \retval >0: number of devices found
249 \retval -1: usb_find_busses() failed
250 \retval -2: usb_find_devices() failed
251 \retval -3: out of memory
253 int ftdi_usb_find_all(struct ftdi_context *ftdi, struct ftdi_device_list **devlist, int vendor, int product)
255 struct ftdi_device_list **curdev;
257 struct usb_device *dev;
261 if (usb_find_busses() < 0)
262 ftdi_error_return(-1, "usb_find_busses() failed");
263 if (usb_find_devices() < 0)
264 ftdi_error_return(-2, "usb_find_devices() failed");
268 for (bus = usb_get_busses(); bus; bus = bus->next)
270 for (dev = bus->devices; dev; dev = dev->next)
272 if (dev->descriptor.idVendor == vendor
273 && dev->descriptor.idProduct == product)
275 *curdev = (struct ftdi_device_list*)malloc(sizeof(struct ftdi_device_list));
277 ftdi_error_return(-3, "out of memory");
279 (*curdev)->next = NULL;
280 (*curdev)->dev = dev;
282 curdev = &(*curdev)->next;
292 Frees a usb device list.
294 \param devlist USB device list created by ftdi_usb_find_all()
296 void ftdi_list_free(struct ftdi_device_list **devlist)
298 struct ftdi_device_list *curdev, *next;
300 for (curdev = *devlist; curdev != NULL;)
311 Frees a usb device list.
313 \param devlist USB device list created by ftdi_usb_find_all()
315 void ftdi_list_free2(struct ftdi_device_list *devlist)
317 ftdi_list_free(&devlist);
321 Return device ID strings from the usb device.
323 The parameters manufacturer, description and serial may be NULL
324 or pointer to buffers to store the fetched strings.
326 \note Use this function only in combination with ftdi_usb_find_all()
327 as it closes the internal "usb_dev" after use.
329 \param ftdi pointer to ftdi_context
330 \param dev libusb usb_dev to use
331 \param manufacturer Store manufacturer string here if not NULL
332 \param mnf_len Buffer size of manufacturer string
333 \param description Store product description string here if not NULL
334 \param desc_len Buffer size of product description string
335 \param serial Store serial string here if not NULL
336 \param serial_len Buffer size of serial string
339 \retval -1: wrong arguments
340 \retval -4: unable to open device
341 \retval -7: get product manufacturer failed
342 \retval -8: get product description failed
343 \retval -9: get serial number failed
344 \retval -10: unable to close device
346 int ftdi_usb_get_strings(struct ftdi_context * ftdi, struct usb_device * dev,
347 char * manufacturer, int mnf_len, char * description, int desc_len, char * serial, int serial_len)
349 if ((ftdi==NULL) || (dev==NULL))
352 if (!(ftdi->usb_dev = usb_open(dev)))
353 ftdi_error_return(-4, usb_strerror());
355 if (manufacturer != NULL)
357 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iManufacturer, manufacturer, mnf_len) <= 0)
359 ftdi_usb_close_internal (ftdi);
360 ftdi_error_return(-7, usb_strerror());
364 if (description != NULL)
366 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, description, desc_len) <= 0)
368 ftdi_usb_close_internal (ftdi);
369 ftdi_error_return(-8, usb_strerror());
375 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, serial, serial_len) <= 0)
377 ftdi_usb_close_internal (ftdi);
378 ftdi_error_return(-9, usb_strerror());
382 if (ftdi_usb_close_internal (ftdi) != 0)
383 ftdi_error_return(-10, usb_strerror());
389 * Internal function to determine the maximum packet size.
390 * \param ftdi pointer to ftdi_context
391 * \param dev libusb usb_dev to use
392 * \retval Maximum packet size for this device
394 static unsigned int _ftdi_determine_max_packet_size(struct ftdi_context *ftdi, struct usb_device *dev)
396 unsigned int packet_size;
398 // Determine maximum packet size. Init with default value.
399 // New hi-speed devices from FTDI use a packet size of 512 bytes
400 // but could be connected to a normal speed USB hub -> 64 bytes packet size.
401 if (ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
406 if (dev->descriptor.bNumConfigurations > 0 && dev->config)
408 struct usb_config_descriptor config = dev->config[0];
410 if (ftdi->interface < config.bNumInterfaces)
412 struct usb_interface interface = config.interface[ftdi->interface];
413 if (interface.num_altsetting > 0)
415 struct usb_interface_descriptor descriptor = interface.altsetting[0];
416 if (descriptor.bNumEndpoints > 0)
418 packet_size = descriptor.endpoint[0].wMaxPacketSize;
428 Opens a ftdi device given by a usb_device.
430 \param ftdi pointer to ftdi_context
431 \param dev libusb usb_dev to use
434 \retval -3: unable to config device
435 \retval -4: unable to open device
436 \retval -5: unable to claim device
437 \retval -6: reset failed
438 \retval -7: set baudrate failed
440 int ftdi_usb_open_dev(struct ftdi_context *ftdi, struct usb_device *dev)
442 int detach_errno = 0;
444 if (!(ftdi->usb_dev = usb_open(dev)))
445 ftdi_error_return(-4, "usb_open() failed");
447 #ifdef LIBUSB_HAS_GET_DRIVER_NP
448 // Try to detach ftdi_sio kernel module.
449 // Returns ENODATA if driver is not loaded.
451 // The return code is kept in a separate variable and only parsed
452 // if usb_set_configuration() or usb_claim_interface() fails as the
453 // detach operation might be denied and everything still works fine.
454 // Likely scenario is a static ftdi_sio kernel module.
455 if (usb_detach_kernel_driver_np(ftdi->usb_dev, ftdi->interface) != 0 && errno != ENODATA)
456 detach_errno = errno;
460 // set configuration (needed especially for windows)
461 // tolerate EBUSY: one device with one configuration, but two interfaces
462 // and libftdi sessions to both interfaces (e.g. FT2232)
464 if (dev->descriptor.bNumConfigurations > 0)
466 // libusb-win32 on Windows 64 can return a null pointer for a valid device
468 config_val = dev->config[0].bConfigurationValue;
470 if (usb_set_configuration(ftdi->usb_dev, config_val) &&
473 ftdi_usb_close_internal (ftdi);
474 if (detach_errno == EPERM)
476 ftdi_error_return(-8, "inappropriate permissions on device!");
480 ftdi_error_return(-3, "unable to set usb configuration. Make sure ftdi_sio is unloaded!");
486 if (usb_claim_interface(ftdi->usb_dev, ftdi->interface) != 0)
488 ftdi_usb_close_internal (ftdi);
489 if (detach_errno == EPERM)
491 ftdi_error_return(-8, "inappropriate permissions on device!");
495 ftdi_error_return(-5, "unable to claim usb device. Make sure ftdi_sio is unloaded!");
499 if (ftdi_usb_reset (ftdi) != 0)
501 ftdi_usb_close_internal (ftdi);
502 ftdi_error_return(-6, "ftdi_usb_reset failed");
505 // Try to guess chip type
506 // Bug in the BM type chips: bcdDevice is 0x200 for serial == 0
507 if (dev->descriptor.bcdDevice == 0x400 || (dev->descriptor.bcdDevice == 0x200
508 && dev->descriptor.iSerialNumber == 0))
509 ftdi->type = TYPE_BM;
510 else if (dev->descriptor.bcdDevice == 0x200)
511 ftdi->type = TYPE_AM;
512 else if (dev->descriptor.bcdDevice == 0x500)
513 ftdi->type = TYPE_2232C;
514 else if (dev->descriptor.bcdDevice == 0x600)
516 else if (dev->descriptor.bcdDevice == 0x700)
517 ftdi->type = TYPE_2232H;
518 else if (dev->descriptor.bcdDevice == 0x800)
519 ftdi->type = TYPE_4232H;
521 // Set default interface on dual/quad type chips
528 ftdi->index = INTERFACE_A;
534 // Determine maximum packet size
535 ftdi->max_packet_size = _ftdi_determine_max_packet_size(ftdi, dev);
537 if (ftdi_set_baudrate (ftdi, 9600) != 0)
539 ftdi_usb_close_internal (ftdi);
540 ftdi_error_return(-7, "set baudrate failed");
543 ftdi_error_return(0, "all fine");
547 Opens the first device with a given vendor and product ids.
549 \param ftdi pointer to ftdi_context
550 \param vendor Vendor ID
551 \param product Product ID
553 \retval same as ftdi_usb_open_desc()
555 int ftdi_usb_open(struct ftdi_context *ftdi, int vendor, int product)
557 return ftdi_usb_open_desc(ftdi, vendor, product, NULL, NULL);
561 Opens the first device with a given, vendor id, product id,
562 description and serial.
564 \param ftdi pointer to ftdi_context
565 \param vendor Vendor ID
566 \param product Product ID
567 \param description Description to search for. Use NULL if not needed.
568 \param serial Serial to search for. Use NULL if not needed.
571 \retval -1: usb_find_busses() failed
572 \retval -2: usb_find_devices() failed
573 \retval -3: usb device not found
574 \retval -4: unable to open device
575 \retval -5: unable to claim device
576 \retval -6: reset failed
577 \retval -7: set baudrate failed
578 \retval -8: get product description failed
579 \retval -9: get serial number failed
580 \retval -10: unable to close device
582 int ftdi_usb_open_desc(struct ftdi_context *ftdi, int vendor, int product,
583 const char* description, const char* serial)
585 return ftdi_usb_open_desc_index(ftdi,vendor,product,description,serial,0);
589 Opens the index-th device with a given, vendor id, product id,
590 description and serial.
592 \param ftdi pointer to ftdi_context
593 \param vendor Vendor ID
594 \param product Product ID
595 \param description Description to search for. Use NULL if not needed.
596 \param serial Serial to search for. Use NULL if not needed.
597 \param index Number of matching device to open if there are more than one, starts with 0.
600 \retval -1: usb_find_busses() failed
601 \retval -2: usb_find_devices() failed
602 \retval -3: usb device not found
603 \retval -4: unable to open device
604 \retval -5: unable to claim device
605 \retval -6: reset failed
606 \retval -7: set baudrate failed
607 \retval -8: get product description failed
608 \retval -9: get serial number failed
609 \retval -10: unable to close device
611 int ftdi_usb_open_desc_index(struct ftdi_context *ftdi, int vendor, int product,
612 const char* description, const char* serial, unsigned int index)
615 struct usb_device *dev;
620 if (usb_find_busses() < 0)
621 ftdi_error_return(-1, "usb_find_busses() failed");
622 if (usb_find_devices() < 0)
623 ftdi_error_return(-2, "usb_find_devices() failed");
625 for (bus = usb_get_busses(); bus; bus = bus->next)
627 for (dev = bus->devices; dev; dev = dev->next)
629 if (dev->descriptor.idVendor == vendor
630 && dev->descriptor.idProduct == product)
632 if (!(ftdi->usb_dev = usb_open(dev)))
633 ftdi_error_return(-4, "usb_open() failed");
635 if (description != NULL)
637 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, string, sizeof(string)) <= 0)
639 ftdi_usb_close_internal (ftdi);
640 ftdi_error_return(-8, "unable to fetch product description");
642 if (strncmp(string, description, sizeof(string)) != 0)
644 if (ftdi_usb_close_internal (ftdi) != 0)
645 ftdi_error_return(-10, "unable to close device");
651 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, string, sizeof(string)) <= 0)
653 ftdi_usb_close_internal (ftdi);
654 ftdi_error_return(-9, "unable to fetch serial number");
656 if (strncmp(string, serial, sizeof(string)) != 0)
658 if (ftdi_usb_close_internal (ftdi) != 0)
659 ftdi_error_return(-10, "unable to close device");
664 if (ftdi_usb_close_internal (ftdi) != 0)
665 ftdi_error_return(-10, "unable to close device");
673 return ftdi_usb_open_dev(ftdi, dev);
679 ftdi_error_return(-3, "device not found");
683 Opens the ftdi-device described by a description-string.
684 Intended to be used for parsing a device-description given as commandline argument.
686 \param ftdi pointer to ftdi_context
687 \param description NULL-terminated description-string, using this format:
688 \li <tt>d:\<devicenode></tt> path of bus and device-node (e.g. "003/001") within usb device tree (usually at /proc/bus/usb/)
689 \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")
690 \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
691 \li <tt>s:\<vendor>:\<product>:\<serial></tt> first device with given vendor id, product id and serial string
693 \note The description format may be extended in later versions.
696 \retval -1: usb_find_busses() failed
697 \retval -2: usb_find_devices() failed
698 \retval -3: usb device not found
699 \retval -4: unable to open device
700 \retval -5: unable to claim device
701 \retval -6: reset failed
702 \retval -7: set baudrate failed
703 \retval -8: get product description failed
704 \retval -9: get serial number failed
705 \retval -10: unable to close device
706 \retval -11: illegal description format
708 int ftdi_usb_open_string(struct ftdi_context *ftdi, const char* description)
710 if (description[0] == 0 || description[1] != ':')
711 ftdi_error_return(-11, "illegal description format");
713 if (description[0] == 'd')
716 struct usb_device *dev;
717 char dev_name[PATH_MAX+1];
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 snprintf(dev_name, sizeof(dev_name), "%s/%s",bus->dirname,dev->filename);
731 if (strcmp(description+2,dev_name) == 0)
732 return ftdi_usb_open_dev(ftdi, dev);
737 ftdi_error_return(-3, "device not found");
739 else if (description[0] == 'i' || description[0] == 's')
742 unsigned int product;
743 unsigned int index=0;
744 const char *serial=NULL;
745 const char *startp, *endp;
748 startp=description+2;
749 vendor=strtoul((char*)startp,(char**)&endp,0);
750 if (*endp != ':' || endp == startp || errno != 0)
751 ftdi_error_return(-11, "illegal description format");
754 product=strtoul((char*)startp,(char**)&endp,0);
755 if (endp == startp || errno != 0)
756 ftdi_error_return(-11, "illegal description format");
758 if (description[0] == 'i' && *endp != 0)
760 /* optional index field in i-mode */
762 ftdi_error_return(-11, "illegal description format");
765 index=strtoul((char*)startp,(char**)&endp,0);
766 if (*endp != 0 || endp == startp || errno != 0)
767 ftdi_error_return(-11, "illegal description format");
769 if (description[0] == 's')
772 ftdi_error_return(-11, "illegal description format");
774 /* rest of the description is the serial */
778 return ftdi_usb_open_desc_index(ftdi, vendor, product, NULL, serial, index);
782 ftdi_error_return(-11, "illegal description format");
787 Resets the ftdi device.
789 \param ftdi pointer to ftdi_context
792 \retval -1: FTDI reset failed
794 int ftdi_usb_reset(struct ftdi_context *ftdi)
796 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
797 SIO_RESET_REQUEST, SIO_RESET_SIO,
798 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
799 ftdi_error_return(-1,"FTDI reset failed");
801 // Invalidate data in the readbuffer
802 ftdi->readbuffer_offset = 0;
803 ftdi->readbuffer_remaining = 0;
809 Clears the read buffer on the chip and the internal read buffer.
811 \param ftdi pointer to ftdi_context
814 \retval -1: read buffer purge failed
816 int ftdi_usb_purge_rx_buffer(struct ftdi_context *ftdi)
818 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
819 SIO_RESET_REQUEST, SIO_RESET_PURGE_RX,
820 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
821 ftdi_error_return(-1, "FTDI purge of RX buffer failed");
823 // Invalidate data in the readbuffer
824 ftdi->readbuffer_offset = 0;
825 ftdi->readbuffer_remaining = 0;
831 Clears the write buffer on the chip.
833 \param ftdi pointer to ftdi_context
836 \retval -1: write buffer purge failed
838 int ftdi_usb_purge_tx_buffer(struct ftdi_context *ftdi)
840 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
841 SIO_RESET_REQUEST, SIO_RESET_PURGE_TX,
842 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
843 ftdi_error_return(-1, "FTDI purge of TX buffer failed");
849 Clears the buffers on the chip and the internal read buffer.
851 \param ftdi pointer to ftdi_context
854 \retval -1: read buffer purge failed
855 \retval -2: write buffer purge failed
857 int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
861 result = ftdi_usb_purge_rx_buffer(ftdi);
865 result = ftdi_usb_purge_tx_buffer(ftdi);
875 Closes the ftdi device. Call ftdi_deinit() if you're cleaning up.
877 \param ftdi pointer to ftdi_context
880 \retval -1: usb_release failed
881 \retval -2: usb_close failed
883 int ftdi_usb_close(struct ftdi_context *ftdi)
887 #ifdef LIBFTDI_LINUX_ASYNC_MODE
888 /* try to release some kernel resources */
889 ftdi_async_complete(ftdi,1);
892 if (ftdi->usb_dev != NULL)
893 if (usb_release_interface(ftdi->usb_dev, ftdi->interface) != 0)
896 if (ftdi_usb_close_internal (ftdi) != 0)
903 ftdi_convert_baudrate returns nearest supported baud rate to that requested.
904 Function is only used internally
907 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
908 unsigned short *value, unsigned short *index)
910 static const char am_adjust_up[8] = {0, 0, 0, 1, 0, 3, 2, 1};
911 static const char am_adjust_dn[8] = {0, 0, 0, 1, 0, 1, 2, 3};
912 static const char frac_code[8] = {0, 3, 2, 4, 1, 5, 6, 7};
913 int divisor, best_divisor, best_baud, best_baud_diff;
914 unsigned long encoded_divisor;
923 divisor = 24000000 / baudrate;
925 if (ftdi->type == TYPE_AM)
927 // Round down to supported fraction (AM only)
928 divisor -= am_adjust_dn[divisor & 7];
931 // Try this divisor and the one above it (because division rounds down)
935 for (i = 0; i < 2; i++)
937 int try_divisor = divisor + i;
941 // Round up to supported divisor value
942 if (try_divisor <= 8)
944 // Round up to minimum supported divisor
947 else if (ftdi->type != TYPE_AM && try_divisor < 12)
949 // BM doesn't support divisors 9 through 11 inclusive
952 else if (divisor < 16)
954 // AM doesn't support divisors 9 through 15 inclusive
959 if (ftdi->type == TYPE_AM)
961 // Round up to supported fraction (AM only)
962 try_divisor += am_adjust_up[try_divisor & 7];
963 if (try_divisor > 0x1FFF8)
965 // Round down to maximum supported divisor value (for AM)
966 try_divisor = 0x1FFF8;
971 if (try_divisor > 0x1FFFF)
973 // Round down to maximum supported divisor value (for BM)
974 try_divisor = 0x1FFFF;
978 // Get estimated baud rate (to nearest integer)
979 baud_estimate = (24000000 + (try_divisor / 2)) / try_divisor;
980 // Get absolute difference from requested baud rate
981 if (baud_estimate < baudrate)
983 baud_diff = baudrate - baud_estimate;
987 baud_diff = baud_estimate - baudrate;
989 if (i == 0 || baud_diff < best_baud_diff)
991 // Closest to requested baud rate so far
992 best_divisor = try_divisor;
993 best_baud = baud_estimate;
994 best_baud_diff = baud_diff;
997 // Spot on! No point trying
1002 // Encode the best divisor value
1003 encoded_divisor = (best_divisor >> 3) | (frac_code[best_divisor & 7] << 14);
1004 // Deal with special cases for encoded value
1005 if (encoded_divisor == 1)
1007 encoded_divisor = 0; // 3000000 baud
1009 else if (encoded_divisor == 0x4001)
1011 encoded_divisor = 1; // 2000000 baud (BM only)
1013 // Split into "value" and "index" values
1014 *value = (unsigned short)(encoded_divisor & 0xFFFF);
1015 if (ftdi->type == TYPE_2232C || ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
1017 *index = (unsigned short)(encoded_divisor >> 8);
1019 *index |= ftdi->index;
1022 *index = (unsigned short)(encoded_divisor >> 16);
1024 // Return the nearest baud rate
1029 Sets the chip baud rate
1031 \param ftdi pointer to ftdi_context
1032 \param baudrate baud rate to set
1035 \retval -1: invalid baudrate
1036 \retval -2: setting baudrate failed
1038 int ftdi_set_baudrate(struct ftdi_context *ftdi, int baudrate)
1040 unsigned short value, index;
1041 int actual_baudrate;
1043 if (ftdi->bitbang_enabled)
1045 baudrate = baudrate*4;
1048 actual_baudrate = ftdi_convert_baudrate(baudrate, ftdi, &value, &index);
1049 if (actual_baudrate <= 0)
1050 ftdi_error_return (-1, "Silly baudrate <= 0.");
1052 // Check within tolerance (about 5%)
1053 if ((actual_baudrate * 2 < baudrate /* Catch overflows */ )
1054 || ((actual_baudrate < baudrate)
1055 ? (actual_baudrate * 21 < baudrate * 20)
1056 : (baudrate * 21 < actual_baudrate * 20)))
1057 ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
1059 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1060 SIO_SET_BAUDRATE_REQUEST, value,
1061 index, NULL, 0, ftdi->usb_write_timeout) != 0)
1062 ftdi_error_return (-2, "Setting new baudrate failed");
1064 ftdi->baudrate = baudrate;
1069 Set (RS232) line characteristics.
1070 The break type can only be set via ftdi_set_line_property2()
1071 and defaults to "off".
1073 \param ftdi pointer to ftdi_context
1074 \param bits Number of bits
1075 \param sbit Number of stop bits
1076 \param parity Parity mode
1079 \retval -1: Setting line property failed
1081 int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1082 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
1084 return ftdi_set_line_property2(ftdi, bits, sbit, parity, BREAK_OFF);
1088 Set (RS232) line characteristics
1090 \param ftdi pointer to ftdi_context
1091 \param bits Number of bits
1092 \param sbit Number of stop bits
1093 \param parity Parity mode
1094 \param break_type Break type
1097 \retval -1: Setting line property failed
1099 int ftdi_set_line_property2(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
1100 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity,
1101 enum ftdi_break_type break_type)
1103 unsigned short value = bits;
1108 value |= (0x00 << 8);
1111 value |= (0x01 << 8);
1114 value |= (0x02 << 8);
1117 value |= (0x03 << 8);
1120 value |= (0x04 << 8);
1127 value |= (0x00 << 11);
1130 value |= (0x01 << 11);
1133 value |= (0x02 << 11);
1140 value |= (0x00 << 14);
1143 value |= (0x01 << 14);
1147 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1148 SIO_SET_DATA_REQUEST, value,
1149 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1150 ftdi_error_return (-1, "Setting new line property failed");
1156 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip
1158 \param ftdi pointer to ftdi_context
1159 \param buf Buffer with the data
1160 \param size Size of the buffer
1162 \retval <0: error code from usb_bulk_write()
1163 \retval >0: number of bytes written
1165 int ftdi_write_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1169 int total_written = 0;
1171 while (offset < size)
1173 int write_size = ftdi->writebuffer_chunksize;
1175 if (offset+write_size > size)
1176 write_size = size-offset;
1178 ret = usb_bulk_write(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size, ftdi->usb_write_timeout);
1180 ftdi_error_return(ret, "usb bulk write failed");
1182 total_written += ret;
1183 offset += write_size;
1186 return total_written;
1189 #ifdef LIBFTDI_LINUX_ASYNC_MODE
1190 #ifdef USB_CLASS_PTP
1191 #error LIBFTDI_LINUX_ASYNC_MODE is not compatible with libusb-compat-0.1!
1193 /* this is strongly dependent on libusb using the same struct layout. If libusb
1194 changes in some later version this may break horribly (this is for libusb 0.1.12) */
1195 struct usb_dev_handle
1198 // some other stuff coming here we don't need
1202 Check for pending async urbs
1205 static int _usb_get_async_urbs_pending(struct ftdi_context *ftdi)
1207 struct usbdevfs_urb *urb;
1211 for (i=0; i < ftdi->async_usb_buffer_size; i++)
1213 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1214 if (urb->usercontext != FTDI_URB_USERCONTEXT_COOKIE)
1222 Wait until one or more async URBs are completed by the kernel and mark their
1223 positions in the async-buffer as unused
1225 \param ftdi pointer to ftdi_context
1226 \param wait_for_more if != 0 wait for more than one write to complete
1227 \param timeout_msec max milliseconds to wait
1231 static void _usb_async_cleanup(struct ftdi_context *ftdi, int wait_for_more, int timeout_msec)
1234 struct usbdevfs_urb *urb=NULL;
1240 FD_SET(ftdi->usb_dev->fd, &writefds);
1242 /* init timeout only once, select writes time left after call */
1243 tv.tv_sec = timeout_msec / 1000;
1244 tv.tv_usec = (timeout_msec % 1000) * 1000;
1248 while (_usb_get_async_urbs_pending(ftdi)
1249 && (ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_REAPURBNDELAY, &urb)) == -1
1252 if (keep_going && !wait_for_more)
1254 /* don't wait if repeating only for keep_going */
1259 /* wait for timeout msec or something written ready */
1260 select(ftdi->usb_dev->fd+1, NULL, &writefds, NULL, &tv);
1263 if (ret == 0 && urb != NULL)
1265 /* got a free urb, mark it */
1266 urb->usercontext = FTDI_URB_USERCONTEXT_COOKIE;
1268 /* try to get more urbs that are ready now, but don't wait anymore */
1274 /* no more urbs waiting */
1282 Wait until one or more async URBs are completed by the kernel and mark their
1283 positions in the async-buffer as unused.
1285 \param ftdi pointer to ftdi_context
1286 \param wait_for_more if != 0 wait for more than one write to complete (until write timeout)
1288 void ftdi_async_complete(struct ftdi_context *ftdi, int wait_for_more)
1290 _usb_async_cleanup(ftdi,wait_for_more,ftdi->usb_write_timeout);
1294 Stupid libusb does not offer async writes nor does it allow
1295 access to its fd - so we need some hacks here.
1298 static int _usb_bulk_write_async(struct ftdi_context *ftdi, int ep, char *bytes, int size)
1300 struct usbdevfs_urb *urb;
1301 int bytesdone = 0, requested;
1302 int ret, cleanup_count;
1307 /* find a free urb buffer we can use */
1309 for (cleanup_count=0; urb==NULL && cleanup_count <= 1; cleanup_count++)
1311 if (i==ftdi->async_usb_buffer_size)
1313 /* wait until some buffers are free */
1314 _usb_async_cleanup(ftdi,0,ftdi->usb_write_timeout);
1317 for (i=0; i < ftdi->async_usb_buffer_size; i++)
1319 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1320 if (urb->usercontext == FTDI_URB_USERCONTEXT_COOKIE)
1321 break; /* found a free urb position */
1326 /* no free urb position found */
1330 requested = size - bytesdone;
1331 if (requested > 4096)
1334 memset(urb,0,sizeof(urb));
1336 urb->type = USBDEVFS_URB_TYPE_BULK;
1339 urb->buffer = bytes + bytesdone;
1340 urb->buffer_length = requested;
1342 urb->actual_length = 0;
1343 urb->number_of_packets = 0;
1344 urb->usercontext = 0;
1348 ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_SUBMITURB, urb);
1350 while (ret < 0 && errno == EINTR);
1352 return ret; /* the caller can read errno to get more info */
1354 bytesdone += requested;
1356 while (bytesdone < size);
1361 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip.
1362 Does not wait for completion of the transfer nor does it make sure that
1363 the transfer was successful.
1365 This function could be extended to use signals and callbacks to inform the
1366 caller of completion or error - but this is not done yet, volunteers welcome.
1368 Works around libusb and directly accesses functions only available on Linux.
1369 Only available if compiled with --with-async-mode.
1371 \param ftdi pointer to ftdi_context
1372 \param buf Buffer with the data
1373 \param size Size of the buffer
1375 \retval <0: error code from usb_bulk_write()
1376 \retval >0: number of bytes written
1378 int ftdi_write_data_async(struct ftdi_context *ftdi, unsigned char *buf, int size)
1382 int total_written = 0;
1384 while (offset < size)
1386 int write_size = ftdi->writebuffer_chunksize;
1388 if (offset+write_size > size)
1389 write_size = size-offset;
1391 ret = _usb_bulk_write_async(ftdi, ftdi->in_ep, buf+offset, write_size);
1393 ftdi_error_return(ret, "usb bulk write async failed");
1395 total_written += ret;
1396 offset += write_size;
1399 return total_written;
1401 #endif // LIBFTDI_LINUX_ASYNC_MODE
1404 Configure write buffer chunk size.
1407 \param ftdi pointer to ftdi_context
1408 \param chunksize Chunk size
1412 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1414 ftdi->writebuffer_chunksize = chunksize;
1419 Get write buffer chunk size.
1421 \param ftdi pointer to ftdi_context
1422 \param chunksize Pointer to store chunk size in
1426 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1428 *chunksize = ftdi->writebuffer_chunksize;
1433 Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
1435 Automatically strips the two modem status bytes transfered during every read.
1437 \param ftdi pointer to ftdi_context
1438 \param buf Buffer to store data in
1439 \param size Size of the buffer
1441 \retval <0: error code from usb_bulk_read()
1442 \retval 0: no data was available
1443 \retval >0: number of bytes read
1445 \remark This function is not useful in bitbang mode.
1446 Use ftdi_read_pins() to get the current state of the pins.
1448 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1450 int offset = 0, ret = 1, i, num_of_chunks, chunk_remains;
1451 int packet_size = ftdi->max_packet_size;
1453 // Packet size sanity check (avoid division by zero)
1454 if (packet_size == 0)
1455 ftdi_error_return(-1, "max_packet_size is bogus (zero)");
1457 // everything we want is still in the readbuffer?
1458 if (size <= ftdi->readbuffer_remaining)
1460 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1463 ftdi->readbuffer_remaining -= size;
1464 ftdi->readbuffer_offset += size;
1466 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1470 // something still in the readbuffer, but not enough to satisfy 'size'?
1471 if (ftdi->readbuffer_remaining != 0)
1473 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1476 offset += ftdi->readbuffer_remaining;
1478 // do the actual USB read
1479 while (offset < size && ret > 0)
1481 ftdi->readbuffer_remaining = 0;
1482 ftdi->readbuffer_offset = 0;
1483 /* returns how much received */
1484 ret = usb_bulk_read (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, ftdi->usb_read_timeout);
1486 ftdi_error_return(ret, "usb bulk read failed");
1490 // skip FTDI status bytes.
1491 // Maybe stored in the future to enable modem use
1492 num_of_chunks = ret / packet_size;
1493 chunk_remains = ret % packet_size;
1494 //printf("ret = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", ret, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
1496 ftdi->readbuffer_offset += 2;
1499 if (ret > packet_size - 2)
1501 for (i = 1; i < num_of_chunks; i++)
1502 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1503 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1505 if (chunk_remains > 2)
1507 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1508 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1510 ret -= 2*num_of_chunks;
1513 ret -= 2*(num_of_chunks-1)+chunk_remains;
1518 // no more data to read?
1523 // data still fits in buf?
1524 if (offset+ret <= size)
1526 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, ret);
1527 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1530 /* Did we read exactly the right amount of bytes? */
1532 //printf("read_data exact rem %d offset %d\n",
1533 //ftdi->readbuffer_remaining, offset);
1538 // only copy part of the data or size <= readbuffer_chunksize
1539 int part_size = size-offset;
1540 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
1542 ftdi->readbuffer_offset += part_size;
1543 ftdi->readbuffer_remaining = ret-part_size;
1544 offset += part_size;
1546 /* printf("Returning part: %d - size: %d - offset: %d - ret: %d - remaining: %d\n",
1547 part_size, size, offset, ret, ftdi->readbuffer_remaining); */
1558 Configure read buffer chunk size.
1561 Automatically reallocates the buffer.
1563 \param ftdi pointer to ftdi_context
1564 \param chunksize Chunk size
1568 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1570 unsigned char *new_buf;
1572 // Invalidate all remaining data
1573 ftdi->readbuffer_offset = 0;
1574 ftdi->readbuffer_remaining = 0;
1576 if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
1577 ftdi_error_return(-1, "out of memory for readbuffer");
1579 ftdi->readbuffer = new_buf;
1580 ftdi->readbuffer_chunksize = chunksize;
1586 Get read buffer chunk size.
1588 \param ftdi pointer to ftdi_context
1589 \param chunksize Pointer to store chunk size in
1593 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1595 *chunksize = ftdi->readbuffer_chunksize;
1601 Enable bitbang mode.
1603 For advanced bitbang modes of the FT2232C chip use ftdi_set_bitmode().
1605 \param ftdi pointer to ftdi_context
1606 \param bitmask Bitmask to configure lines.
1607 HIGH/ON value configures a line as output.
1610 \retval -1: can't enable bitbang mode
1612 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
1614 unsigned short usb_val;
1616 usb_val = bitmask; // low byte: bitmask
1617 /* FT2232C: Set bitbang_mode to 2 to enable SPI */
1618 usb_val |= (ftdi->bitbang_mode << 8);
1620 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1621 SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index,
1622 NULL, 0, ftdi->usb_write_timeout) != 0)
1623 ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
1625 ftdi->bitbang_enabled = 1;
1630 Disable bitbang mode.
1632 \param ftdi pointer to ftdi_context
1635 \retval -1: can't disable bitbang mode
1637 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
1639 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)
1640 ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
1642 ftdi->bitbang_enabled = 0;
1647 Enable advanced bitbang mode for FT2232C chips.
1649 \param ftdi pointer to ftdi_context
1650 \param bitmask Bitmask to configure lines.
1651 HIGH/ON value configures a line as output.
1652 \param mode Bitbang mode: 1 for normal mode, 2 for SPI mode
1655 \retval -1: can't enable bitbang mode
1657 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
1659 unsigned short usb_val;
1661 usb_val = bitmask; // low byte: bitmask
1662 usb_val |= (mode << 8);
1663 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)
1664 ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps not a 2232C type chip?");
1666 ftdi->bitbang_mode = mode;
1667 ftdi->bitbang_enabled = (mode == BITMODE_BITBANG || mode == BITMODE_SYNCBB)?1:0;
1672 Directly read pin state. Useful for bitbang mode.
1674 \param ftdi pointer to ftdi_context
1675 \param pins Pointer to store pins into
1678 \retval -1: read pins failed
1680 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
1682 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)
1683 ftdi_error_return(-1, "read pins failed");
1691 The FTDI chip keeps data in the internal buffer for a specific
1692 amount of time if the buffer is not full yet to decrease
1693 load on the usb bus.
1695 \param ftdi pointer to ftdi_context
1696 \param latency Value between 1 and 255
1699 \retval -1: latency out of range
1700 \retval -2: unable to set latency timer
1702 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
1704 unsigned short usb_val;
1707 ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
1710 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)
1711 ftdi_error_return(-2, "unable to set latency timer");
1719 \param ftdi pointer to ftdi_context
1720 \param latency Pointer to store latency value in
1723 \retval -1: unable to get latency timer
1725 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1727 unsigned short usb_val;
1728 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)
1729 ftdi_error_return(-1, "reading latency timer failed");
1731 *latency = (unsigned char)usb_val;
1736 Poll modem status information
1738 This function allows the retrieve the two status bytes of the device.
1739 The device sends these bytes also as a header for each read access
1740 where they are discarded by ftdi_read_data(). The chip generates
1741 the two stripped status bytes in the absence of data every 40 ms.
1743 Layout of the first byte:
1744 - B0..B3 - must be 0
1745 - B4 Clear to send (CTS)
1748 - B5 Data set ready (DTS)
1751 - B6 Ring indicator (RI)
1754 - B7 Receive line signal detect (RLSD)
1758 Layout of the second byte:
1759 - B0 Data ready (DR)
1760 - B1 Overrun error (OE)
1761 - B2 Parity error (PE)
1762 - B3 Framing error (FE)
1763 - B4 Break interrupt (BI)
1764 - B5 Transmitter holding register (THRE)
1765 - B6 Transmitter empty (TEMT)
1766 - B7 Error in RCVR FIFO
1768 \param ftdi pointer to ftdi_context
1769 \param status Pointer to store status information in. Must be two bytes.
1772 \retval -1: unable to retrieve status information
1774 int ftdi_poll_modem_status(struct ftdi_context *ftdi, unsigned short *status)
1778 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)
1779 ftdi_error_return(-1, "getting modem status failed");
1781 *status = (usb_val[1] << 8) | usb_val[0];
1787 Set flowcontrol for ftdi chip
1789 \param ftdi pointer to ftdi_context
1790 \param flowctrl flow control to use. should be
1791 SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1794 \retval -1: set flow control failed
1796 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1798 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1799 SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->index),
1800 NULL, 0, ftdi->usb_write_timeout) != 0)
1801 ftdi_error_return(-1, "set flow control failed");
1809 \param ftdi pointer to ftdi_context
1810 \param state state to set line to (1 or 0)
1813 \retval -1: set dtr failed
1815 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
1817 unsigned short usb_val;
1820 usb_val = SIO_SET_DTR_HIGH;
1822 usb_val = SIO_SET_DTR_LOW;
1824 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1825 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1826 NULL, 0, ftdi->usb_write_timeout) != 0)
1827 ftdi_error_return(-1, "set dtr failed");
1835 \param ftdi pointer to ftdi_context
1836 \param state state to set line to (1 or 0)
1839 \retval -1 set rts failed
1841 int ftdi_setrts(struct ftdi_context *ftdi, int state)
1843 unsigned short usb_val;
1846 usb_val = SIO_SET_RTS_HIGH;
1848 usb_val = SIO_SET_RTS_LOW;
1850 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1851 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1852 NULL, 0, ftdi->usb_write_timeout) != 0)
1853 ftdi_error_return(-1, "set of rts failed");
1859 Set dtr and rts line in one pass
1861 \param ftdi pointer to ftdi_context
1862 \param dtr DTR state to set line to (1 or 0)
1863 \param rts RTS state to set line to (1 or 0)
1866 \retval -1 set dtr/rts failed
1868 int ftdi_setdtr_rts(struct ftdi_context *ftdi, int dtr, int rts)
1870 unsigned short usb_val;
1873 usb_val = SIO_SET_DTR_HIGH;
1875 usb_val = SIO_SET_DTR_LOW;
1878 usb_val |= SIO_SET_RTS_HIGH;
1880 usb_val |= SIO_SET_RTS_LOW;
1882 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1883 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1884 NULL, 0, ftdi->usb_write_timeout) != 0)
1885 ftdi_error_return(-1, "set of rts/dtr failed");
1891 Set the special event character
1893 \param ftdi pointer to ftdi_context
1894 \param eventch Event character
1895 \param enable 0 to disable the event character, non-zero otherwise
1898 \retval -1: unable to set event character
1900 int ftdi_set_event_char(struct ftdi_context *ftdi,
1901 unsigned char eventch, unsigned char enable)
1903 unsigned short usb_val;
1909 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)
1910 ftdi_error_return(-1, "setting event character failed");
1918 \param ftdi pointer to ftdi_context
1919 \param errorch Error character
1920 \param enable 0 to disable the error character, non-zero otherwise
1923 \retval -1: unable to set error character
1925 int ftdi_set_error_char(struct ftdi_context *ftdi,
1926 unsigned char errorch, unsigned char enable)
1928 unsigned short usb_val;
1934 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)
1935 ftdi_error_return(-1, "setting error character failed");
1943 \param ftdi pointer to ftdi_context
1944 \param eeprom Pointer to ftdi_eeprom
1948 void ftdi_eeprom_setsize(struct ftdi_context *ftdi, struct ftdi_eeprom *eeprom, int size)
1950 ftdi->eeprom_size=size;
1955 Init eeprom with default values.
1957 \param eeprom Pointer to ftdi_eeprom
1959 void ftdi_eeprom_initdefaults(struct ftdi_eeprom *eeprom)
1961 eeprom->vendor_id = 0x0403;
1962 eeprom->product_id = 0x6001;
1964 eeprom->self_powered = 1;
1965 eeprom->remote_wakeup = 1;
1966 eeprom->BM_type_chip = 1;
1968 eeprom->in_is_isochronous = 0;
1969 eeprom->out_is_isochronous = 0;
1970 eeprom->suspend_pull_downs = 0;
1972 eeprom->use_serial = 0;
1973 eeprom->change_usb_version = 0;
1974 eeprom->usb_version = 0x0200;
1975 eeprom->max_power = 0;
1977 eeprom->manufacturer = NULL;
1978 eeprom->product = NULL;
1979 eeprom->serial = NULL;
1981 eeprom->size = FTDI_DEFAULT_EEPROM_SIZE;
1985 Build binary output from ftdi_eeprom structure.
1986 Output is suitable for ftdi_write_eeprom().
1988 \param eeprom Pointer to ftdi_eeprom
1989 \param output Buffer of 128 bytes to store eeprom image to
1991 \retval >0: used eeprom size
1992 \retval -1: eeprom size (128 bytes) exceeded by custom strings
1994 int ftdi_eeprom_build(struct ftdi_eeprom *eeprom, unsigned char *output)
1997 unsigned short checksum, value;
1998 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2001 if (eeprom->manufacturer != NULL)
2002 manufacturer_size = strlen(eeprom->manufacturer);
2003 if (eeprom->product != NULL)
2004 product_size = strlen(eeprom->product);
2005 if (eeprom->serial != NULL)
2006 serial_size = strlen(eeprom->serial);
2008 size_check = eeprom->size;
2009 size_check -= 28; // 28 are always in use (fixed)
2011 // Top half of a 256byte eeprom is used just for strings and checksum
2012 // it seems that the FTDI chip will not read these strings from the lower half
2013 // Each string starts with two bytes; offset and type (0x03 for string)
2014 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2015 if (eeprom->size>=256)size_check = 120;
2016 size_check -= manufacturer_size*2;
2017 size_check -= product_size*2;
2018 size_check -= serial_size*2;
2020 // eeprom size exceeded?
2025 memset (output, 0, eeprom->size);
2027 // Addr 00: Stay 00 00
2028 // Addr 02: Vendor ID
2029 output[0x02] = eeprom->vendor_id;
2030 output[0x03] = eeprom->vendor_id >> 8;
2032 // Addr 04: Product ID
2033 output[0x04] = eeprom->product_id;
2034 output[0x05] = eeprom->product_id >> 8;
2036 // Addr 06: Device release number (0400h for BM features)
2037 output[0x06] = 0x00;
2039 if (eeprom->BM_type_chip == 1)
2040 output[0x07] = 0x04;
2042 output[0x07] = 0x02;
2044 // Addr 08: Config descriptor
2046 // Bit 6: 1 if this device is self powered, 0 if bus powered
2047 // Bit 5: 1 if this device uses remote wakeup
2048 // Bit 4: 1 if this device is battery powered
2050 if (eeprom->self_powered == 1)
2052 if (eeprom->remote_wakeup == 1)
2056 // Addr 09: Max power consumption: max power = value * 2 mA
2057 output[0x09] = eeprom->max_power;
2059 // Addr 0A: Chip configuration
2060 // Bit 7: 0 - reserved
2061 // Bit 6: 0 - reserved
2062 // Bit 5: 0 - reserved
2063 // Bit 4: 1 - Change USB version
2064 // Bit 3: 1 - Use the serial number string
2065 // Bit 2: 1 - Enable suspend pull downs for lower power
2066 // Bit 1: 1 - Out EndPoint is Isochronous
2067 // Bit 0: 1 - In EndPoint is Isochronous
2070 if (eeprom->in_is_isochronous == 1)
2072 if (eeprom->out_is_isochronous == 1)
2074 if (eeprom->suspend_pull_downs == 1)
2076 if (eeprom->use_serial == 1)
2078 if (eeprom->change_usb_version == 1)
2082 // Addr 0B: reserved
2083 output[0x0B] = 0x00;
2085 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2086 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2087 if (eeprom->change_usb_version == 1)
2089 output[0x0C] = eeprom->usb_version;
2090 output[0x0D] = eeprom->usb_version >> 8;
2094 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2095 // Addr 0F: Length of manufacturer string
2096 output[0x0F] = manufacturer_size*2 + 2;
2098 // Addr 10: Offset of the product string + 0x80, calculated later
2099 // Addr 11: Length of product string
2100 output[0x11] = product_size*2 + 2;
2102 // Addr 12: Offset of the serial string + 0x80, calculated later
2103 // Addr 13: Length of serial string
2104 output[0x13] = serial_size*2 + 2;
2108 if (eeprom->size>=256) i = 0x80;
2111 // Output manufacturer
2112 output[0x0E] = i | 0x80; // calculate offset
2113 output[i++] = manufacturer_size*2 + 2;
2114 output[i++] = 0x03; // type: string
2115 for (j = 0; j < manufacturer_size; j++)
2117 output[i] = eeprom->manufacturer[j], i++;
2118 output[i] = 0x00, i++;
2121 // Output product name
2122 output[0x10] = i | 0x80; // calculate offset
2123 output[i] = product_size*2 + 2, i++;
2124 output[i] = 0x03, i++;
2125 for (j = 0; j < product_size; j++)
2127 output[i] = eeprom->product[j], i++;
2128 output[i] = 0x00, i++;
2132 output[0x12] = i | 0x80; // calculate offset
2133 output[i] = serial_size*2 + 2, i++;
2134 output[i] = 0x03, i++;
2135 for (j = 0; j < serial_size; j++)
2137 output[i] = eeprom->serial[j], i++;
2138 output[i] = 0x00, i++;
2141 // calculate checksum
2144 for (i = 0; i < eeprom->size/2-1; i++)
2146 value = output[i*2];
2147 value += output[(i*2)+1] << 8;
2149 checksum = value^checksum;
2150 checksum = (checksum << 1) | (checksum >> 15);
2153 output[eeprom->size-2] = checksum;
2154 output[eeprom->size-1] = checksum >> 8;
2160 Decode binary EEPROM image into an ftdi_eeprom structure.
2162 \param eeprom Pointer to ftdi_eeprom which will be filled in.
2163 \param buf Buffer of \a size bytes of raw eeprom data
2164 \param size size size of eeprom data in bytes
2167 \retval -1: something went wrong
2169 FIXME: How to pass size? How to handle size field in ftdi_eeprom?
2170 FIXME: Strings are malloc'ed here and should be freed somewhere
2172 int ftdi_eeprom_decode(struct ftdi_eeprom *eeprom, unsigned char *buf, int size)
2175 unsigned short checksum, eeprom_checksum, value;
2176 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2178 int eeprom_size = 128;
2180 size_check = eeprom->size;
2181 size_check -= 28; // 28 are always in use (fixed)
2183 // Top half of a 256byte eeprom is used just for strings and checksum
2184 // it seems that the FTDI chip will not read these strings from the lower half
2185 // Each string starts with two bytes; offset and type (0x03 for string)
2186 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2187 if (eeprom->size>=256)size_check = 120;
2188 size_check -= manufacturer_size*2;
2189 size_check -= product_size*2;
2190 size_check -= serial_size*2;
2192 // eeprom size exceeded?
2197 // empty eeprom struct
2198 memset(eeprom, 0, sizeof(struct ftdi_eeprom));
2200 // Addr 00: Stay 00 00
2202 // Addr 02: Vendor ID
2203 eeprom->vendor_id = buf[0x02] + (buf[0x03] << 8);
2205 // Addr 04: Product ID
2206 eeprom->product_id = buf[0x04] + (buf[0x05] << 8);
2208 value = buf[0x06] + (buf[0x07]<<8);
2212 eeprom->BM_type_chip = 1;
2215 eeprom->BM_type_chip = 0;
2217 default: // Unknown device
2218 eeprom->BM_type_chip = 0;
2222 // Addr 08: Config descriptor
2224 // Bit 6: 1 if this device is self powered, 0 if bus powered
2225 // Bit 5: 1 if this device uses remote wakeup
2226 // Bit 4: 1 if this device is battery powered
2228 if (j&0x40) eeprom->self_powered = 1;
2229 if (j&0x20) eeprom->remote_wakeup = 1;
2231 // Addr 09: Max power consumption: max power = value * 2 mA
2232 eeprom->max_power = buf[0x09];
2234 // Addr 0A: Chip configuration
2235 // Bit 7: 0 - reserved
2236 // Bit 6: 0 - reserved
2237 // Bit 5: 0 - reserved
2238 // Bit 4: 1 - Change USB version
2239 // Bit 3: 1 - Use the serial number string
2240 // Bit 2: 1 - Enable suspend pull downs for lower power
2241 // Bit 1: 1 - Out EndPoint is Isochronous
2242 // Bit 0: 1 - In EndPoint is Isochronous
2245 if (j&0x01) eeprom->in_is_isochronous = 1;
2246 if (j&0x02) eeprom->out_is_isochronous = 1;
2247 if (j&0x04) eeprom->suspend_pull_downs = 1;
2248 if (j&0x08) eeprom->use_serial = 1;
2249 if (j&0x10) eeprom->change_usb_version = 1;
2251 // Addr 0B: reserved
2253 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2254 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2255 if (eeprom->change_usb_version == 1)
2257 eeprom->usb_version = buf[0x0C] + (buf[0x0D] << 8);
2260 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2261 // Addr 0F: Length of manufacturer string
2262 manufacturer_size = buf[0x0F]/2;
2263 if (manufacturer_size > 0) eeprom->manufacturer = malloc(manufacturer_size);
2264 else eeprom->manufacturer = NULL;
2266 // Addr 10: Offset of the product string + 0x80, calculated later
2267 // Addr 11: Length of product string
2268 product_size = buf[0x11]/2;
2269 if (product_size > 0) eeprom->product = malloc(product_size);
2270 else eeprom->product = NULL;
2272 // Addr 12: Offset of the serial string + 0x80, calculated later
2273 // Addr 13: Length of serial string
2274 serial_size = buf[0x13]/2;
2275 if (serial_size > 0) eeprom->serial = malloc(serial_size);
2276 else eeprom->serial = NULL;
2278 // Decode manufacturer
2279 i = buf[0x0E] & 0x7f; // offset
2280 for (j=0;j<manufacturer_size-1;j++)
2282 eeprom->manufacturer[j] = buf[2*j+i+2];
2284 eeprom->manufacturer[j] = '\0';
2286 // Decode product name
2287 i = buf[0x10] & 0x7f; // offset
2288 for (j=0;j<product_size-1;j++)
2290 eeprom->product[j] = buf[2*j+i+2];
2292 eeprom->product[j] = '\0';
2295 i = buf[0x12] & 0x7f; // offset
2296 for (j=0;j<serial_size-1;j++)
2298 eeprom->serial[j] = buf[2*j+i+2];
2300 eeprom->serial[j] = '\0';
2305 for (i = 0; i < eeprom_size/2-1; i++)
2308 value += buf[(i*2)+1] << 8;
2310 checksum = value^checksum;
2311 checksum = (checksum << 1) | (checksum >> 15);
2314 eeprom_checksum = buf[eeprom_size-2] + (buf[eeprom_size-1] << 8);
2316 if (eeprom_checksum != checksum)
2318 fprintf(stderr, "Checksum Error: %04x %04x\n", checksum, eeprom_checksum);
2326 Read eeprom location
2328 \param ftdi pointer to ftdi_context
2329 \param eeprom_addr Address of eeprom location to be read
2330 \param eeprom_val Pointer to store read eeprom location
2333 \retval -1: read failed
2335 int ftdi_read_eeprom_location (struct ftdi_context *ftdi, int eeprom_addr, unsigned short *eeprom_val)
2337 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)
2338 ftdi_error_return(-1, "reading eeprom failed");
2346 \param ftdi pointer to ftdi_context
2347 \param eeprom Pointer to store eeprom into
2350 \retval -1: read failed
2352 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2356 for (i = 0; i < ftdi->eeprom_size/2; i++)
2358 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)
2359 ftdi_error_return(-1, "reading eeprom failed");
2366 ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
2367 Function is only used internally
2370 static unsigned char ftdi_read_chipid_shift(unsigned char value)
2372 return ((value & 1) << 1) |
2373 ((value & 2) << 5) |
2374 ((value & 4) >> 2) |
2375 ((value & 8) << 4) |
2376 ((value & 16) >> 1) |
2377 ((value & 32) >> 1) |
2378 ((value & 64) >> 4) |
2379 ((value & 128) >> 2);
2383 Read the FTDIChip-ID from R-type devices
2385 \param ftdi pointer to ftdi_context
2386 \param chipid Pointer to store FTDIChip-ID
2389 \retval -1: read failed
2391 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
2393 unsigned int a = 0, b = 0;
2395 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)
2397 a = a << 8 | a >> 8;
2398 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)
2400 b = b << 8 | b >> 8;
2401 a = (a << 16) | (b & 0xFFFF);
2402 a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8
2403 | ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
2404 *chipid = a ^ 0xa5f0f7d1;
2409 ftdi_error_return(-1, "read of FTDIChip-ID failed");
2413 Guesses size of eeprom by reading eeprom and comparing halves - will not work with blank eeprom
2414 Call this function then do a write then call again to see if size changes, if so write again.
2416 \param ftdi pointer to ftdi_context
2417 \param eeprom Pointer to store eeprom into
2418 \param maxsize the size of the buffer to read into
2420 \retval size of eeprom
2422 int ftdi_read_eeprom_getsize(struct ftdi_context *ftdi, unsigned char *eeprom, int maxsize)
2424 int i=0,j,minsize=32;
2429 for (j = 0; i < maxsize/2 && j<size; j++)
2431 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE,
2432 SIO_READ_EEPROM_REQUEST, 0, i,
2433 eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2434 ftdi_error_return(-1, "reading eeprom failed");
2439 while (size<=maxsize && memcmp(eeprom,&eeprom[size/2],size/2)!=0);
2445 Write eeprom location
2447 \param ftdi pointer to ftdi_context
2448 \param eeprom_addr Address of eeprom location to be written
2449 \param eeprom_val Value to be written
2452 \retval -1: read failed
2454 int ftdi_write_eeprom_location(struct ftdi_context *ftdi, int eeprom_addr, unsigned short eeprom_val)
2456 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2457 SIO_WRITE_EEPROM_REQUEST, eeprom_val, eeprom_addr,
2458 NULL, 0, ftdi->usb_write_timeout) != 0)
2459 ftdi_error_return(-1, "unable to write eeprom");
2467 \param ftdi pointer to ftdi_context
2468 \param eeprom Pointer to read eeprom from
2471 \retval -1: read failed
2473 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2475 unsigned short usb_val, status;
2478 /* These commands were traced while running MProg */
2479 if ((ret = ftdi_usb_reset(ftdi)) != 0)
2481 if ((ret = ftdi_poll_modem_status(ftdi, &status)) != 0)
2483 if ((ret = ftdi_set_latency_timer(ftdi, 0x77)) != 0)
2486 for (i = 0; i < ftdi->eeprom_size/2; i++)
2488 usb_val = eeprom[i*2];
2489 usb_val += eeprom[(i*2)+1] << 8;
2490 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2491 SIO_WRITE_EEPROM_REQUEST, usb_val, i,
2492 NULL, 0, ftdi->usb_write_timeout) != 0)
2493 ftdi_error_return(-1, "unable to write eeprom");
2502 This is not supported on FT232R/FT245R according to the MProg manual from FTDI.
2504 \param ftdi pointer to ftdi_context
2507 \retval -1: erase failed
2509 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
2511 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_ERASE_EEPROM_REQUEST, 0, 0, NULL, 0, ftdi->usb_write_timeout) != 0)
2512 ftdi_error_return(-1, "unable to erase eeprom");
2518 Get string representation for last error code
2520 \param ftdi pointer to ftdi_context
2522 \retval Pointer to error string
2524 char *ftdi_get_error_string (struct ftdi_context *ftdi)
2526 return ftdi->error_str;
2529 /* @} end of doxygen libftdi group */