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)
586 struct usb_device *dev;
591 if (usb_find_busses() < 0)
592 ftdi_error_return(-1, "usb_find_busses() failed");
593 if (usb_find_devices() < 0)
594 ftdi_error_return(-2, "usb_find_devices() failed");
596 for (bus = usb_get_busses(); bus; bus = bus->next)
598 for (dev = bus->devices; dev; dev = dev->next)
600 if (dev->descriptor.idVendor == vendor
601 && dev->descriptor.idProduct == product)
603 if (!(ftdi->usb_dev = usb_open(dev)))
604 ftdi_error_return(-4, "usb_open() failed");
606 if (description != NULL)
608 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, string, sizeof(string)) <= 0)
610 ftdi_usb_close_internal (ftdi);
611 ftdi_error_return(-8, "unable to fetch product description");
613 if (strncmp(string, description, sizeof(string)) != 0)
615 if (ftdi_usb_close_internal (ftdi) != 0)
616 ftdi_error_return(-10, "unable to close device");
622 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, string, sizeof(string)) <= 0)
624 ftdi_usb_close_internal (ftdi);
625 ftdi_error_return(-9, "unable to fetch serial number");
627 if (strncmp(string, serial, sizeof(string)) != 0)
629 if (ftdi_usb_close_internal (ftdi) != 0)
630 ftdi_error_return(-10, "unable to close device");
635 if (ftdi_usb_close_internal (ftdi) != 0)
636 ftdi_error_return(-10, "unable to close device");
638 return ftdi_usb_open_dev(ftdi, dev);
644 ftdi_error_return(-3, "device not found");
648 Resets the ftdi device.
650 \param ftdi pointer to ftdi_context
653 \retval -1: FTDI reset failed
655 int ftdi_usb_reset(struct ftdi_context *ftdi)
657 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
658 SIO_RESET_REQUEST, SIO_RESET_SIO,
659 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
660 ftdi_error_return(-1,"FTDI reset failed");
662 // Invalidate data in the readbuffer
663 ftdi->readbuffer_offset = 0;
664 ftdi->readbuffer_remaining = 0;
670 Clears the read buffer on the chip and the internal read buffer.
672 \param ftdi pointer to ftdi_context
675 \retval -1: read buffer purge failed
677 int ftdi_usb_purge_rx_buffer(struct ftdi_context *ftdi)
679 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
680 SIO_RESET_REQUEST, SIO_RESET_PURGE_RX,
681 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
682 ftdi_error_return(-1, "FTDI purge of RX buffer failed");
684 // Invalidate data in the readbuffer
685 ftdi->readbuffer_offset = 0;
686 ftdi->readbuffer_remaining = 0;
692 Clears the write buffer on the chip.
694 \param ftdi pointer to ftdi_context
697 \retval -1: write buffer purge failed
699 int ftdi_usb_purge_tx_buffer(struct ftdi_context *ftdi)
701 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
702 SIO_RESET_REQUEST, SIO_RESET_PURGE_TX,
703 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
704 ftdi_error_return(-1, "FTDI purge of TX buffer failed");
710 Clears the buffers on the chip and the internal read buffer.
712 \param ftdi pointer to ftdi_context
715 \retval -1: read buffer purge failed
716 \retval -2: write buffer purge failed
718 int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
722 result = ftdi_usb_purge_rx_buffer(ftdi);
726 result = ftdi_usb_purge_tx_buffer(ftdi);
736 Closes the ftdi device. Call ftdi_deinit() if you're cleaning up.
738 \param ftdi pointer to ftdi_context
741 \retval -1: usb_release failed
742 \retval -2: usb_close failed
744 int ftdi_usb_close(struct ftdi_context *ftdi)
748 #ifdef LIBFTDI_LINUX_ASYNC_MODE
749 /* try to release some kernel resources */
750 ftdi_async_complete(ftdi,1);
753 if (ftdi->usb_dev != NULL)
754 if (usb_release_interface(ftdi->usb_dev, ftdi->interface) != 0)
757 if (ftdi_usb_close_internal (ftdi) != 0)
764 ftdi_convert_baudrate returns nearest supported baud rate to that requested.
765 Function is only used internally
768 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
769 unsigned short *value, unsigned short *index)
771 static const char am_adjust_up[8] = {0, 0, 0, 1, 0, 3, 2, 1};
772 static const char am_adjust_dn[8] = {0, 0, 0, 1, 0, 1, 2, 3};
773 static const char frac_code[8] = {0, 3, 2, 4, 1, 5, 6, 7};
774 int divisor, best_divisor, best_baud, best_baud_diff;
775 unsigned long encoded_divisor;
784 divisor = 24000000 / baudrate;
786 if (ftdi->type == TYPE_AM)
788 // Round down to supported fraction (AM only)
789 divisor -= am_adjust_dn[divisor & 7];
792 // Try this divisor and the one above it (because division rounds down)
796 for (i = 0; i < 2; i++)
798 int try_divisor = divisor + i;
802 // Round up to supported divisor value
803 if (try_divisor <= 8)
805 // Round up to minimum supported divisor
808 else if (ftdi->type != TYPE_AM && try_divisor < 12)
810 // BM doesn't support divisors 9 through 11 inclusive
813 else if (divisor < 16)
815 // AM doesn't support divisors 9 through 15 inclusive
820 if (ftdi->type == TYPE_AM)
822 // Round up to supported fraction (AM only)
823 try_divisor += am_adjust_up[try_divisor & 7];
824 if (try_divisor > 0x1FFF8)
826 // Round down to maximum supported divisor value (for AM)
827 try_divisor = 0x1FFF8;
832 if (try_divisor > 0x1FFFF)
834 // Round down to maximum supported divisor value (for BM)
835 try_divisor = 0x1FFFF;
839 // Get estimated baud rate (to nearest integer)
840 baud_estimate = (24000000 + (try_divisor / 2)) / try_divisor;
841 // Get absolute difference from requested baud rate
842 if (baud_estimate < baudrate)
844 baud_diff = baudrate - baud_estimate;
848 baud_diff = baud_estimate - baudrate;
850 if (i == 0 || baud_diff < best_baud_diff)
852 // Closest to requested baud rate so far
853 best_divisor = try_divisor;
854 best_baud = baud_estimate;
855 best_baud_diff = baud_diff;
858 // Spot on! No point trying
863 // Encode the best divisor value
864 encoded_divisor = (best_divisor >> 3) | (frac_code[best_divisor & 7] << 14);
865 // Deal with special cases for encoded value
866 if (encoded_divisor == 1)
868 encoded_divisor = 0; // 3000000 baud
870 else if (encoded_divisor == 0x4001)
872 encoded_divisor = 1; // 2000000 baud (BM only)
874 // Split into "value" and "index" values
875 *value = (unsigned short)(encoded_divisor & 0xFFFF);
876 if (ftdi->type == TYPE_2232C || ftdi->type == TYPE_2232H || ftdi->type == TYPE_4232H)
878 *index = (unsigned short)(encoded_divisor >> 8);
880 *index |= ftdi->index;
883 *index = (unsigned short)(encoded_divisor >> 16);
885 // Return the nearest baud rate
890 Sets the chip baud rate
892 \param ftdi pointer to ftdi_context
893 \param baudrate baud rate to set
896 \retval -1: invalid baudrate
897 \retval -2: setting baudrate failed
899 int ftdi_set_baudrate(struct ftdi_context *ftdi, int baudrate)
901 unsigned short value, index;
904 if (ftdi->bitbang_enabled)
906 baudrate = baudrate*4;
909 actual_baudrate = ftdi_convert_baudrate(baudrate, ftdi, &value, &index);
910 if (actual_baudrate <= 0)
911 ftdi_error_return (-1, "Silly baudrate <= 0.");
913 // Check within tolerance (about 5%)
914 if ((actual_baudrate * 2 < baudrate /* Catch overflows */ )
915 || ((actual_baudrate < baudrate)
916 ? (actual_baudrate * 21 < baudrate * 20)
917 : (baudrate * 21 < actual_baudrate * 20)))
918 ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
920 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
921 SIO_SET_BAUDRATE_REQUEST, value,
922 index, NULL, 0, ftdi->usb_write_timeout) != 0)
923 ftdi_error_return (-2, "Setting new baudrate failed");
925 ftdi->baudrate = baudrate;
930 Set (RS232) line characteristics.
931 The break type can only be set via ftdi_set_line_property2()
932 and defaults to "off".
934 \param ftdi pointer to ftdi_context
935 \param bits Number of bits
936 \param sbit Number of stop bits
937 \param parity Parity mode
940 \retval -1: Setting line property failed
942 int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
943 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
945 return ftdi_set_line_property2(ftdi, bits, sbit, parity, BREAK_OFF);
949 Set (RS232) line characteristics
951 \param ftdi pointer to ftdi_context
952 \param bits Number of bits
953 \param sbit Number of stop bits
954 \param parity Parity mode
955 \param break_type Break type
958 \retval -1: Setting line property failed
960 int ftdi_set_line_property2(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
961 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity,
962 enum ftdi_break_type break_type)
964 unsigned short value = bits;
969 value |= (0x00 << 8);
972 value |= (0x01 << 8);
975 value |= (0x02 << 8);
978 value |= (0x03 << 8);
981 value |= (0x04 << 8);
988 value |= (0x00 << 11);
991 value |= (0x01 << 11);
994 value |= (0x02 << 11);
1001 value |= (0x00 << 14);
1004 value |= (0x01 << 14);
1008 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1009 SIO_SET_DATA_REQUEST, value,
1010 ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1011 ftdi_error_return (-1, "Setting new line property failed");
1017 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip
1019 \param ftdi pointer to ftdi_context
1020 \param buf Buffer with the data
1021 \param size Size of the buffer
1023 \retval <0: error code from usb_bulk_write()
1024 \retval >0: number of bytes written
1026 int ftdi_write_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1030 int total_written = 0;
1032 while (offset < size)
1034 int write_size = ftdi->writebuffer_chunksize;
1036 if (offset+write_size > size)
1037 write_size = size-offset;
1039 ret = usb_bulk_write(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size, ftdi->usb_write_timeout);
1041 ftdi_error_return(ret, "usb bulk write failed");
1043 total_written += ret;
1044 offset += write_size;
1047 return total_written;
1050 #ifdef LIBFTDI_LINUX_ASYNC_MODE
1051 #ifdef USB_CLASS_PTP
1052 #error LIBFTDI_LINUX_ASYNC_MODE is not compatible with libusb-compat-0.1!
1054 /* this is strongly dependent on libusb using the same struct layout. If libusb
1055 changes in some later version this may break horribly (this is for libusb 0.1.12) */
1056 struct usb_dev_handle
1059 // some other stuff coming here we don't need
1063 Check for pending async urbs
1066 static int _usb_get_async_urbs_pending(struct ftdi_context *ftdi)
1068 struct usbdevfs_urb *urb;
1072 for (i=0; i < ftdi->async_usb_buffer_size; i++)
1074 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1075 if (urb->usercontext != FTDI_URB_USERCONTEXT_COOKIE)
1083 Wait until one or more async URBs are completed by the kernel and mark their
1084 positions in the async-buffer as unused
1086 \param ftdi pointer to ftdi_context
1087 \param wait_for_more if != 0 wait for more than one write to complete
1088 \param timeout_msec max milliseconds to wait
1092 static void _usb_async_cleanup(struct ftdi_context *ftdi, int wait_for_more, int timeout_msec)
1095 struct usbdevfs_urb *urb=NULL;
1101 FD_SET(ftdi->usb_dev->fd, &writefds);
1103 /* init timeout only once, select writes time left after call */
1104 tv.tv_sec = timeout_msec / 1000;
1105 tv.tv_usec = (timeout_msec % 1000) * 1000;
1109 while (_usb_get_async_urbs_pending(ftdi)
1110 && (ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_REAPURBNDELAY, &urb)) == -1
1113 if (keep_going && !wait_for_more)
1115 /* don't wait if repeating only for keep_going */
1120 /* wait for timeout msec or something written ready */
1121 select(ftdi->usb_dev->fd+1, NULL, &writefds, NULL, &tv);
1124 if (ret == 0 && urb != NULL)
1126 /* got a free urb, mark it */
1127 urb->usercontext = FTDI_URB_USERCONTEXT_COOKIE;
1129 /* try to get more urbs that are ready now, but don't wait anymore */
1135 /* no more urbs waiting */
1143 Wait until one or more async URBs are completed by the kernel and mark their
1144 positions in the async-buffer as unused.
1146 \param ftdi pointer to ftdi_context
1147 \param wait_for_more if != 0 wait for more than one write to complete (until write timeout)
1149 void ftdi_async_complete(struct ftdi_context *ftdi, int wait_for_more)
1151 _usb_async_cleanup(ftdi,wait_for_more,ftdi->usb_write_timeout);
1155 Stupid libusb does not offer async writes nor does it allow
1156 access to its fd - so we need some hacks here.
1159 static int _usb_bulk_write_async(struct ftdi_context *ftdi, int ep, char *bytes, int size)
1161 struct usbdevfs_urb *urb;
1162 int bytesdone = 0, requested;
1163 int ret, cleanup_count;
1168 /* find a free urb buffer we can use */
1170 for (cleanup_count=0; urb==NULL && cleanup_count <= 1; cleanup_count++)
1172 if (i==ftdi->async_usb_buffer_size)
1174 /* wait until some buffers are free */
1175 _usb_async_cleanup(ftdi,0,ftdi->usb_write_timeout);
1178 for (i=0; i < ftdi->async_usb_buffer_size; i++)
1180 urb=&((struct usbdevfs_urb *)(ftdi->async_usb_buffer))[i];
1181 if (urb->usercontext == FTDI_URB_USERCONTEXT_COOKIE)
1182 break; /* found a free urb position */
1187 /* no free urb position found */
1191 requested = size - bytesdone;
1192 if (requested > 4096)
1195 memset(urb,0,sizeof(urb));
1197 urb->type = USBDEVFS_URB_TYPE_BULK;
1200 urb->buffer = bytes + bytesdone;
1201 urb->buffer_length = requested;
1203 urb->actual_length = 0;
1204 urb->number_of_packets = 0;
1205 urb->usercontext = 0;
1209 ret = ioctl(ftdi->usb_dev->fd, USBDEVFS_SUBMITURB, urb);
1211 while (ret < 0 && errno == EINTR);
1213 return ret; /* the caller can read errno to get more info */
1215 bytesdone += requested;
1217 while (bytesdone < size);
1222 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip.
1223 Does not wait for completion of the transfer nor does it make sure that
1224 the transfer was successful.
1226 This function could be extended to use signals and callbacks to inform the
1227 caller of completion or error - but this is not done yet, volunteers welcome.
1229 Works around libusb and directly accesses functions only available on Linux.
1230 Only available if compiled with --with-async-mode.
1232 \param ftdi pointer to ftdi_context
1233 \param buf Buffer with the data
1234 \param size Size of the buffer
1236 \retval <0: error code from usb_bulk_write()
1237 \retval >0: number of bytes written
1239 int ftdi_write_data_async(struct ftdi_context *ftdi, unsigned char *buf, int size)
1243 int total_written = 0;
1245 while (offset < size)
1247 int write_size = ftdi->writebuffer_chunksize;
1249 if (offset+write_size > size)
1250 write_size = size-offset;
1252 ret = _usb_bulk_write_async(ftdi, ftdi->in_ep, buf+offset, write_size);
1254 ftdi_error_return(ret, "usb bulk write async failed");
1256 total_written += ret;
1257 offset += write_size;
1260 return total_written;
1262 #endif // LIBFTDI_LINUX_ASYNC_MODE
1265 Configure write buffer chunk size.
1268 \param ftdi pointer to ftdi_context
1269 \param chunksize Chunk size
1273 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1275 ftdi->writebuffer_chunksize = chunksize;
1280 Get write buffer chunk size.
1282 \param ftdi pointer to ftdi_context
1283 \param chunksize Pointer to store chunk size in
1287 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1289 *chunksize = ftdi->writebuffer_chunksize;
1294 Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
1296 Automatically strips the two modem status bytes transfered during every read.
1298 \param ftdi pointer to ftdi_context
1299 \param buf Buffer to store data in
1300 \param size Size of the buffer
1302 \retval <0: error code from usb_bulk_read()
1303 \retval 0: no data was available
1304 \retval >0: number of bytes read
1306 \remark This function is not useful in bitbang mode.
1307 Use ftdi_read_pins() to get the current state of the pins.
1309 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
1311 int offset = 0, ret = 1, i, num_of_chunks, chunk_remains;
1312 int packet_size = ftdi->max_packet_size;
1314 // Packet size sanity check (avoid division by zero)
1315 if (packet_size == 0)
1316 ftdi_error_return(-1, "max_packet_size is bogus (zero)");
1318 // everything we want is still in the readbuffer?
1319 if (size <= ftdi->readbuffer_remaining)
1321 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
1324 ftdi->readbuffer_remaining -= size;
1325 ftdi->readbuffer_offset += size;
1327 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
1331 // something still in the readbuffer, but not enough to satisfy 'size'?
1332 if (ftdi->readbuffer_remaining != 0)
1334 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
1337 offset += ftdi->readbuffer_remaining;
1339 // do the actual USB read
1340 while (offset < size && ret > 0)
1342 ftdi->readbuffer_remaining = 0;
1343 ftdi->readbuffer_offset = 0;
1344 /* returns how much received */
1345 ret = usb_bulk_read (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, ftdi->usb_read_timeout);
1347 ftdi_error_return(ret, "usb bulk read failed");
1351 // skip FTDI status bytes.
1352 // Maybe stored in the future to enable modem use
1353 num_of_chunks = ret / packet_size;
1354 chunk_remains = ret % packet_size;
1355 //printf("ret = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", ret, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
1357 ftdi->readbuffer_offset += 2;
1360 if (ret > packet_size - 2)
1362 for (i = 1; i < num_of_chunks; i++)
1363 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1364 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1366 if (chunk_remains > 2)
1368 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+(packet_size - 2)*i,
1369 ftdi->readbuffer+ftdi->readbuffer_offset+packet_size*i,
1371 ret -= 2*num_of_chunks;
1374 ret -= 2*(num_of_chunks-1)+chunk_remains;
1379 // no more data to read?
1384 // data still fits in buf?
1385 if (offset+ret <= size)
1387 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, ret);
1388 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
1391 /* Did we read exactly the right amount of bytes? */
1393 //printf("read_data exact rem %d offset %d\n",
1394 //ftdi->readbuffer_remaining, offset);
1399 // only copy part of the data or size <= readbuffer_chunksize
1400 int part_size = size-offset;
1401 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
1403 ftdi->readbuffer_offset += part_size;
1404 ftdi->readbuffer_remaining = ret-part_size;
1405 offset += part_size;
1407 /* printf("Returning part: %d - size: %d - offset: %d - ret: %d - remaining: %d\n",
1408 part_size, size, offset, ret, ftdi->readbuffer_remaining); */
1419 Configure read buffer chunk size.
1422 Automatically reallocates the buffer.
1424 \param ftdi pointer to ftdi_context
1425 \param chunksize Chunk size
1429 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
1431 unsigned char *new_buf;
1433 // Invalidate all remaining data
1434 ftdi->readbuffer_offset = 0;
1435 ftdi->readbuffer_remaining = 0;
1437 if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
1438 ftdi_error_return(-1, "out of memory for readbuffer");
1440 ftdi->readbuffer = new_buf;
1441 ftdi->readbuffer_chunksize = chunksize;
1447 Get read buffer chunk size.
1449 \param ftdi pointer to ftdi_context
1450 \param chunksize Pointer to store chunk size in
1454 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
1456 *chunksize = ftdi->readbuffer_chunksize;
1462 Enable bitbang mode.
1464 For advanced bitbang modes of the FT2232C chip use ftdi_set_bitmode().
1466 \param ftdi pointer to ftdi_context
1467 \param bitmask Bitmask to configure lines.
1468 HIGH/ON value configures a line as output.
1471 \retval -1: can't enable bitbang mode
1473 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
1475 unsigned short usb_val;
1477 usb_val = bitmask; // low byte: bitmask
1478 /* FT2232C: Set bitbang_mode to 2 to enable SPI */
1479 usb_val |= (ftdi->bitbang_mode << 8);
1481 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1482 SIO_SET_BITMODE_REQUEST, usb_val, ftdi->index,
1483 NULL, 0, ftdi->usb_write_timeout) != 0)
1484 ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
1486 ftdi->bitbang_enabled = 1;
1491 Disable bitbang mode.
1493 \param ftdi pointer to ftdi_context
1496 \retval -1: can't disable bitbang mode
1498 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
1500 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)
1501 ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
1503 ftdi->bitbang_enabled = 0;
1508 Enable advanced bitbang mode for FT2232C chips.
1510 \param ftdi pointer to ftdi_context
1511 \param bitmask Bitmask to configure lines.
1512 HIGH/ON value configures a line as output.
1513 \param mode Bitbang mode: 1 for normal mode, 2 for SPI mode
1516 \retval -1: can't enable bitbang mode
1518 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
1520 unsigned short usb_val;
1522 usb_val = bitmask; // low byte: bitmask
1523 usb_val |= (mode << 8);
1524 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)
1525 ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps not a 2232C type chip?");
1527 ftdi->bitbang_mode = mode;
1528 ftdi->bitbang_enabled = (mode == BITMODE_BITBANG || mode == BITMODE_SYNCBB)?1:0;
1533 Directly read pin state. Useful for bitbang mode.
1535 \param ftdi pointer to ftdi_context
1536 \param pins Pointer to store pins into
1539 \retval -1: read pins failed
1541 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
1543 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)
1544 ftdi_error_return(-1, "read pins failed");
1552 The FTDI chip keeps data in the internal buffer for a specific
1553 amount of time if the buffer is not full yet to decrease
1554 load on the usb bus.
1556 \param ftdi pointer to ftdi_context
1557 \param latency Value between 1 and 255
1560 \retval -1: latency out of range
1561 \retval -2: unable to set latency timer
1563 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
1565 unsigned short usb_val;
1568 ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
1571 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)
1572 ftdi_error_return(-2, "unable to set latency timer");
1580 \param ftdi pointer to ftdi_context
1581 \param latency Pointer to store latency value in
1584 \retval -1: unable to get latency timer
1586 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1588 unsigned short usb_val;
1589 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)
1590 ftdi_error_return(-1, "reading latency timer failed");
1592 *latency = (unsigned char)usb_val;
1597 Poll modem status information
1599 This function allows the retrieve the two status bytes of the device.
1600 The device sends these bytes also as a header for each read access
1601 where they are discarded by ftdi_read_data(). The chip generates
1602 the two stripped status bytes in the absence of data every 40 ms.
1604 Layout of the first byte:
1605 - B0..B3 - must be 0
1606 - B4 Clear to send (CTS)
1609 - B5 Data set ready (DTS)
1612 - B6 Ring indicator (RI)
1615 - B7 Receive line signal detect (RLSD)
1619 Layout of the second byte:
1620 - B0 Data ready (DR)
1621 - B1 Overrun error (OE)
1622 - B2 Parity error (PE)
1623 - B3 Framing error (FE)
1624 - B4 Break interrupt (BI)
1625 - B5 Transmitter holding register (THRE)
1626 - B6 Transmitter empty (TEMT)
1627 - B7 Error in RCVR FIFO
1629 \param ftdi pointer to ftdi_context
1630 \param status Pointer to store status information in. Must be two bytes.
1633 \retval -1: unable to retrieve status information
1635 int ftdi_poll_modem_status(struct ftdi_context *ftdi, unsigned short *status)
1639 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)
1640 ftdi_error_return(-1, "getting modem status failed");
1642 *status = (usb_val[1] << 8) | usb_val[0];
1648 Set flowcontrol for ftdi chip
1650 \param ftdi pointer to ftdi_context
1651 \param flowctrl flow control to use. should be
1652 SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1655 \retval -1: set flow control failed
1657 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1659 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1660 SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->index),
1661 NULL, 0, ftdi->usb_write_timeout) != 0)
1662 ftdi_error_return(-1, "set flow control failed");
1670 \param ftdi pointer to ftdi_context
1671 \param state state to set line to (1 or 0)
1674 \retval -1: set dtr failed
1676 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
1678 unsigned short usb_val;
1681 usb_val = SIO_SET_DTR_HIGH;
1683 usb_val = SIO_SET_DTR_LOW;
1685 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1686 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1687 NULL, 0, ftdi->usb_write_timeout) != 0)
1688 ftdi_error_return(-1, "set dtr failed");
1696 \param ftdi pointer to ftdi_context
1697 \param state state to set line to (1 or 0)
1700 \retval -1 set rts failed
1702 int ftdi_setrts(struct ftdi_context *ftdi, int state)
1704 unsigned short usb_val;
1707 usb_val = SIO_SET_RTS_HIGH;
1709 usb_val = SIO_SET_RTS_LOW;
1711 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1712 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1713 NULL, 0, ftdi->usb_write_timeout) != 0)
1714 ftdi_error_return(-1, "set of rts failed");
1720 Set dtr and rts line in one pass
1722 \param ftdi pointer to ftdi_context
1723 \param dtr DTR state to set line to (1 or 0)
1724 \param rts RTS state to set line to (1 or 0)
1727 \retval -1 set dtr/rts failed
1729 int ftdi_setdtr_rts(struct ftdi_context *ftdi, int dtr, int rts)
1731 unsigned short usb_val;
1734 usb_val = SIO_SET_DTR_HIGH;
1736 usb_val = SIO_SET_DTR_LOW;
1739 usb_val |= SIO_SET_RTS_HIGH;
1741 usb_val |= SIO_SET_RTS_LOW;
1743 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
1744 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
1745 NULL, 0, ftdi->usb_write_timeout) != 0)
1746 ftdi_error_return(-1, "set of rts/dtr failed");
1752 Set the special event character
1754 \param ftdi pointer to ftdi_context
1755 \param eventch Event character
1756 \param enable 0 to disable the event character, non-zero otherwise
1759 \retval -1: unable to set event character
1761 int ftdi_set_event_char(struct ftdi_context *ftdi,
1762 unsigned char eventch, unsigned char enable)
1764 unsigned short usb_val;
1770 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)
1771 ftdi_error_return(-1, "setting event character failed");
1779 \param ftdi pointer to ftdi_context
1780 \param errorch Error character
1781 \param enable 0 to disable the error character, non-zero otherwise
1784 \retval -1: unable to set error character
1786 int ftdi_set_error_char(struct ftdi_context *ftdi,
1787 unsigned char errorch, unsigned char enable)
1789 unsigned short usb_val;
1795 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)
1796 ftdi_error_return(-1, "setting error character failed");
1804 \param ftdi pointer to ftdi_context
1805 \param eeprom Pointer to ftdi_eeprom
1809 void ftdi_eeprom_setsize(struct ftdi_context *ftdi, struct ftdi_eeprom *eeprom, int size)
1811 ftdi->eeprom_size=size;
1816 Init eeprom with default values.
1818 \param eeprom Pointer to ftdi_eeprom
1820 void ftdi_eeprom_initdefaults(struct ftdi_eeprom *eeprom)
1822 eeprom->vendor_id = 0x0403;
1823 eeprom->product_id = 0x6001;
1825 eeprom->self_powered = 1;
1826 eeprom->remote_wakeup = 1;
1827 eeprom->BM_type_chip = 1;
1829 eeprom->in_is_isochronous = 0;
1830 eeprom->out_is_isochronous = 0;
1831 eeprom->suspend_pull_downs = 0;
1833 eeprom->use_serial = 0;
1834 eeprom->change_usb_version = 0;
1835 eeprom->usb_version = 0x0200;
1836 eeprom->max_power = 0;
1838 eeprom->manufacturer = NULL;
1839 eeprom->product = NULL;
1840 eeprom->serial = NULL;
1842 eeprom->size = FTDI_DEFAULT_EEPROM_SIZE;
1846 Build binary output from ftdi_eeprom structure.
1847 Output is suitable for ftdi_write_eeprom().
1849 \param eeprom Pointer to ftdi_eeprom
1850 \param output Buffer of 128 bytes to store eeprom image to
1852 \retval >0: used eeprom size
1853 \retval -1: eeprom size (128 bytes) exceeded by custom strings
1855 int ftdi_eeprom_build(struct ftdi_eeprom *eeprom, unsigned char *output)
1858 unsigned short checksum, value;
1859 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
1862 if (eeprom->manufacturer != NULL)
1863 manufacturer_size = strlen(eeprom->manufacturer);
1864 if (eeprom->product != NULL)
1865 product_size = strlen(eeprom->product);
1866 if (eeprom->serial != NULL)
1867 serial_size = strlen(eeprom->serial);
1869 size_check = eeprom->size;
1870 size_check -= 28; // 28 are always in use (fixed)
1872 // Top half of a 256byte eeprom is used just for strings and checksum
1873 // it seems that the FTDI chip will not read these strings from the lower half
1874 // Each string starts with two bytes; offset and type (0x03 for string)
1875 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
1876 if (eeprom->size>=256)size_check = 120;
1877 size_check -= manufacturer_size*2;
1878 size_check -= product_size*2;
1879 size_check -= serial_size*2;
1881 // eeprom size exceeded?
1886 memset (output, 0, eeprom->size);
1888 // Addr 00: Stay 00 00
1889 // Addr 02: Vendor ID
1890 output[0x02] = eeprom->vendor_id;
1891 output[0x03] = eeprom->vendor_id >> 8;
1893 // Addr 04: Product ID
1894 output[0x04] = eeprom->product_id;
1895 output[0x05] = eeprom->product_id >> 8;
1897 // Addr 06: Device release number (0400h for BM features)
1898 output[0x06] = 0x00;
1900 if (eeprom->BM_type_chip == 1)
1901 output[0x07] = 0x04;
1903 output[0x07] = 0x02;
1905 // Addr 08: Config descriptor
1907 // Bit 6: 1 if this device is self powered, 0 if bus powered
1908 // Bit 5: 1 if this device uses remote wakeup
1909 // Bit 4: 1 if this device is battery powered
1911 if (eeprom->self_powered == 1)
1913 if (eeprom->remote_wakeup == 1)
1917 // Addr 09: Max power consumption: max power = value * 2 mA
1918 output[0x09] = eeprom->max_power;
1920 // Addr 0A: Chip configuration
1921 // Bit 7: 0 - reserved
1922 // Bit 6: 0 - reserved
1923 // Bit 5: 0 - reserved
1924 // Bit 4: 1 - Change USB version
1925 // Bit 3: 1 - Use the serial number string
1926 // Bit 2: 1 - Enable suspend pull downs for lower power
1927 // Bit 1: 1 - Out EndPoint is Isochronous
1928 // Bit 0: 1 - In EndPoint is Isochronous
1931 if (eeprom->in_is_isochronous == 1)
1933 if (eeprom->out_is_isochronous == 1)
1935 if (eeprom->suspend_pull_downs == 1)
1937 if (eeprom->use_serial == 1)
1939 if (eeprom->change_usb_version == 1)
1943 // Addr 0B: reserved
1944 output[0x0B] = 0x00;
1946 // Addr 0C: USB version low byte when 0x0A bit 4 is set
1947 // Addr 0D: USB version high byte when 0x0A bit 4 is set
1948 if (eeprom->change_usb_version == 1)
1950 output[0x0C] = eeprom->usb_version;
1951 output[0x0D] = eeprom->usb_version >> 8;
1955 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
1956 // Addr 0F: Length of manufacturer string
1957 output[0x0F] = manufacturer_size*2 + 2;
1959 // Addr 10: Offset of the product string + 0x80, calculated later
1960 // Addr 11: Length of product string
1961 output[0x11] = product_size*2 + 2;
1963 // Addr 12: Offset of the serial string + 0x80, calculated later
1964 // Addr 13: Length of serial string
1965 output[0x13] = serial_size*2 + 2;
1969 if (eeprom->size>=256) i = 0x80;
1972 // Output manufacturer
1973 output[0x0E] = i | 0x80; // calculate offset
1974 output[i++] = manufacturer_size*2 + 2;
1975 output[i++] = 0x03; // type: string
1976 for (j = 0; j < manufacturer_size; j++)
1978 output[i] = eeprom->manufacturer[j], i++;
1979 output[i] = 0x00, i++;
1982 // Output product name
1983 output[0x10] = i | 0x80; // calculate offset
1984 output[i] = product_size*2 + 2, i++;
1985 output[i] = 0x03, i++;
1986 for (j = 0; j < product_size; j++)
1988 output[i] = eeprom->product[j], i++;
1989 output[i] = 0x00, i++;
1993 output[0x12] = i | 0x80; // calculate offset
1994 output[i] = serial_size*2 + 2, i++;
1995 output[i] = 0x03, i++;
1996 for (j = 0; j < serial_size; j++)
1998 output[i] = eeprom->serial[j], i++;
1999 output[i] = 0x00, i++;
2002 // calculate checksum
2005 for (i = 0; i < eeprom->size/2-1; i++)
2007 value = output[i*2];
2008 value += output[(i*2)+1] << 8;
2010 checksum = value^checksum;
2011 checksum = (checksum << 1) | (checksum >> 15);
2014 output[eeprom->size-2] = checksum;
2015 output[eeprom->size-1] = checksum >> 8;
2021 Decode binary EEPROM image into an ftdi_eeprom structure.
2023 \param eeprom Pointer to ftdi_eeprom which will be filled in.
2024 \param buf Buffer of \a size bytes of raw eeprom data
2025 \param size size size of eeprom data in bytes
2028 \retval -1: something went wrong
2030 FIXME: How to pass size? How to handle size field in ftdi_eeprom?
2031 FIXME: Strings are malloc'ed here and should be freed somewhere
2033 int ftdi_eeprom_decode(struct ftdi_eeprom *eeprom, unsigned char *buf, int size)
2036 unsigned short checksum, eeprom_checksum, value;
2037 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
2039 int eeprom_size = 128;
2041 size_check = eeprom->size;
2042 size_check -= 28; // 28 are always in use (fixed)
2044 // Top half of a 256byte eeprom is used just for strings and checksum
2045 // it seems that the FTDI chip will not read these strings from the lower half
2046 // Each string starts with two bytes; offset and type (0x03 for string)
2047 // the checksum needs two bytes, so without the string data that 8 bytes from the top half
2048 if (eeprom->size>=256)size_check = 120;
2049 size_check -= manufacturer_size*2;
2050 size_check -= product_size*2;
2051 size_check -= serial_size*2;
2053 // eeprom size exceeded?
2058 // empty eeprom struct
2059 memset(eeprom, 0, sizeof(struct ftdi_eeprom));
2061 // Addr 00: Stay 00 00
2063 // Addr 02: Vendor ID
2064 eeprom->vendor_id = buf[0x02] + (buf[0x03] << 8);
2066 // Addr 04: Product ID
2067 eeprom->product_id = buf[0x04] + (buf[0x05] << 8);
2069 value = buf[0x06] + (buf[0x07]<<8);
2073 eeprom->BM_type_chip = 1;
2076 eeprom->BM_type_chip = 0;
2078 default: // Unknown device
2079 eeprom->BM_type_chip = 0;
2083 // Addr 08: Config descriptor
2085 // Bit 6: 1 if this device is self powered, 0 if bus powered
2086 // Bit 5: 1 if this device uses remote wakeup
2087 // Bit 4: 1 if this device is battery powered
2089 if (j&0x40) eeprom->self_powered = 1;
2090 if (j&0x20) eeprom->remote_wakeup = 1;
2092 // Addr 09: Max power consumption: max power = value * 2 mA
2093 eeprom->max_power = buf[0x09];
2095 // Addr 0A: Chip configuration
2096 // Bit 7: 0 - reserved
2097 // Bit 6: 0 - reserved
2098 // Bit 5: 0 - reserved
2099 // Bit 4: 1 - Change USB version
2100 // Bit 3: 1 - Use the serial number string
2101 // Bit 2: 1 - Enable suspend pull downs for lower power
2102 // Bit 1: 1 - Out EndPoint is Isochronous
2103 // Bit 0: 1 - In EndPoint is Isochronous
2106 if (j&0x01) eeprom->in_is_isochronous = 1;
2107 if (j&0x02) eeprom->out_is_isochronous = 1;
2108 if (j&0x04) eeprom->suspend_pull_downs = 1;
2109 if (j&0x08) eeprom->use_serial = 1;
2110 if (j&0x10) eeprom->change_usb_version = 1;
2112 // Addr 0B: reserved
2114 // Addr 0C: USB version low byte when 0x0A bit 4 is set
2115 // Addr 0D: USB version high byte when 0x0A bit 4 is set
2116 if (eeprom->change_usb_version == 1)
2118 eeprom->usb_version = buf[0x0C] + (buf[0x0D] << 8);
2121 // Addr 0E: Offset of the manufacturer string + 0x80, calculated later
2122 // Addr 0F: Length of manufacturer string
2123 manufacturer_size = buf[0x0F]/2;
2124 if (manufacturer_size > 0) eeprom->manufacturer = malloc(manufacturer_size);
2125 else eeprom->manufacturer = NULL;
2127 // Addr 10: Offset of the product string + 0x80, calculated later
2128 // Addr 11: Length of product string
2129 product_size = buf[0x11]/2;
2130 if (product_size > 0) eeprom->product = malloc(product_size);
2131 else eeprom->product = NULL;
2133 // Addr 12: Offset of the serial string + 0x80, calculated later
2134 // Addr 13: Length of serial string
2135 serial_size = buf[0x13]/2;
2136 if (serial_size > 0) eeprom->serial = malloc(serial_size);
2137 else eeprom->serial = NULL;
2139 // Decode manufacturer
2140 i = buf[0x0E] & 0x7f; // offset
2141 for (j=0;j<manufacturer_size-1;j++)
2143 eeprom->manufacturer[j] = buf[2*j+i+2];
2145 eeprom->manufacturer[j] = '\0';
2147 // Decode product name
2148 i = buf[0x10] & 0x7f; // offset
2149 for (j=0;j<product_size-1;j++)
2151 eeprom->product[j] = buf[2*j+i+2];
2153 eeprom->product[j] = '\0';
2156 i = buf[0x12] & 0x7f; // offset
2157 for (j=0;j<serial_size-1;j++)
2159 eeprom->serial[j] = buf[2*j+i+2];
2161 eeprom->serial[j] = '\0';
2166 for (i = 0; i < eeprom_size/2-1; i++)
2169 value += buf[(i*2)+1] << 8;
2171 checksum = value^checksum;
2172 checksum = (checksum << 1) | (checksum >> 15);
2175 eeprom_checksum = buf[eeprom_size-2] + (buf[eeprom_size-1] << 8);
2177 if (eeprom_checksum != checksum)
2179 fprintf(stderr, "Checksum Error: %04x %04x\n", checksum, eeprom_checksum);
2187 Read eeprom location
2189 \param ftdi pointer to ftdi_context
2190 \param eeprom_addr Address of eeprom location to be read
2191 \param eeprom_val Pointer to store read eeprom location
2194 \retval -1: read failed
2196 int ftdi_read_eeprom_location (struct ftdi_context *ftdi, int eeprom_addr, unsigned short *eeprom_val)
2198 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)
2199 ftdi_error_return(-1, "reading eeprom failed");
2207 \param ftdi pointer to ftdi_context
2208 \param eeprom Pointer to store eeprom into
2211 \retval -1: read failed
2213 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2217 for (i = 0; i < ftdi->eeprom_size/2; i++)
2219 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)
2220 ftdi_error_return(-1, "reading eeprom failed");
2227 ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
2228 Function is only used internally
2231 static unsigned char ftdi_read_chipid_shift(unsigned char value)
2233 return ((value & 1) << 1) |
2234 ((value & 2) << 5) |
2235 ((value & 4) >> 2) |
2236 ((value & 8) << 4) |
2237 ((value & 16) >> 1) |
2238 ((value & 32) >> 1) |
2239 ((value & 64) >> 4) |
2240 ((value & 128) >> 2);
2244 Read the FTDIChip-ID from R-type devices
2246 \param ftdi pointer to ftdi_context
2247 \param chipid Pointer to store FTDIChip-ID
2250 \retval -1: read failed
2252 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
2254 unsigned int a = 0, b = 0;
2256 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)
2258 a = a << 8 | a >> 8;
2259 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)
2261 b = b << 8 | b >> 8;
2262 a = (a << 16) | (b & 0xFFFF);
2263 a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8
2264 | ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
2265 *chipid = a ^ 0xa5f0f7d1;
2270 ftdi_error_return(-1, "read of FTDIChip-ID failed");
2274 Guesses size of eeprom by reading eeprom and comparing halves - will not work with blank eeprom
2275 Call this function then do a write then call again to see if size changes, if so write again.
2277 \param ftdi pointer to ftdi_context
2278 \param eeprom Pointer to store eeprom into
2279 \param maxsize the size of the buffer to read into
2281 \retval size of eeprom
2283 int ftdi_read_eeprom_getsize(struct ftdi_context *ftdi, unsigned char *eeprom, int maxsize)
2285 int i=0,j,minsize=32;
2290 for (j = 0; i < maxsize/2 && j<size; j++)
2292 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_IN_REQTYPE,
2293 SIO_READ_EEPROM_REQUEST, 0, i,
2294 eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
2295 ftdi_error_return(-1, "reading eeprom failed");
2300 while (size<=maxsize && memcmp(eeprom,&eeprom[size/2],size/2)!=0);
2306 Write eeprom location
2308 \param ftdi pointer to ftdi_context
2309 \param eeprom_addr Address of eeprom location to be written
2310 \param eeprom_val Value to be written
2313 \retval -1: read failed
2315 int ftdi_write_eeprom_location(struct ftdi_context *ftdi, int eeprom_addr, unsigned short eeprom_val)
2317 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2318 SIO_WRITE_EEPROM_REQUEST, eeprom_val, eeprom_addr,
2319 NULL, 0, ftdi->usb_write_timeout) != 0)
2320 ftdi_error_return(-1, "unable to write eeprom");
2328 \param ftdi pointer to ftdi_context
2329 \param eeprom Pointer to read eeprom from
2332 \retval -1: read failed
2334 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
2336 unsigned short usb_val, status;
2339 /* These commands were traced while running MProg */
2340 if ((ret = ftdi_usb_reset(ftdi)) != 0)
2342 if ((ret = ftdi_poll_modem_status(ftdi, &status)) != 0)
2344 if ((ret = ftdi_set_latency_timer(ftdi, 0x77)) != 0)
2347 for (i = 0; i < ftdi->eeprom_size/2; i++)
2349 usb_val = eeprom[i*2];
2350 usb_val += eeprom[(i*2)+1] << 8;
2351 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE,
2352 SIO_WRITE_EEPROM_REQUEST, usb_val, i,
2353 NULL, 0, ftdi->usb_write_timeout) != 0)
2354 ftdi_error_return(-1, "unable to write eeprom");
2363 This is not supported on FT232R/FT245R according to the MProg manual from FTDI.
2365 \param ftdi pointer to ftdi_context
2368 \retval -1: erase failed
2370 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
2372 if (usb_control_msg(ftdi->usb_dev, FTDI_DEVICE_OUT_REQTYPE, SIO_ERASE_EEPROM_REQUEST, 0, 0, NULL, 0, ftdi->usb_write_timeout) != 0)
2373 ftdi_error_return(-1, "unable to erase eeprom");
2379 Get string representation for last error code
2381 \param ftdi pointer to ftdi_context
2383 \retval Pointer to error string
2385 char *ftdi_get_error_string (struct ftdi_context *ftdi)
2387 return ftdi->error_str;
2390 /* @} end of doxygen libftdi group */