1 /***************************************************************************
5 copyright : (C) 2003 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/de/produkte/opensource/ftdi/
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 */
34 #include <sys/ioctl.h>
38 #define ftdi_error_return(code, str) do { \
39 ftdi->error_str = str; \
45 Initializes a ftdi_context.
47 \param ftdi pointer to ftdi_context
50 \retval -1: couldn't allocate read buffer
52 \remark This should be called before all functions
54 int ftdi_init(struct ftdi_context *ftdi)
57 ftdi->usb_read_timeout = 5000;
58 ftdi->usb_write_timeout = 5000;
60 ftdi->type = TYPE_BM; /* chip type */
62 ftdi->bitbang_enabled = 0;
64 ftdi->readbuffer = NULL;
65 ftdi->readbuffer_offset = 0;
66 ftdi->readbuffer_remaining = 0;
67 ftdi->writebuffer_chunksize = 4096;
73 ftdi->bitbang_mode = 1; /* 1: Normal bitbang mode, 2: SPI bitbang mode */
75 ftdi->error_str = NULL;
77 /* All fine. Now allocate the readbuffer */
78 return ftdi_read_data_set_chunksize(ftdi, 4096);
82 Open selected channels on a chip, otherwise use first channel.
84 \param ftdi pointer to ftdi_context
85 \param interface Interface to use for FT2232C chips.
88 \retval -1: unknown interface
90 int ftdi_set_interface(struct ftdi_context *ftdi, enum ftdi_interface interface)
95 /* ftdi_usb_open_desc cares to set the right index, depending on the found chip */
99 ftdi->index = INTERFACE_B;
104 ftdi_error_return(-1, "Unknown interface");
110 Deinitializes a ftdi_context.
112 \param ftdi pointer to ftdi_context
114 void ftdi_deinit(struct ftdi_context *ftdi)
116 if (ftdi->readbuffer != NULL) {
117 free(ftdi->readbuffer);
118 ftdi->readbuffer = NULL;
123 Use an already open libusb device.
125 \param ftdi pointer to ftdi_context
126 \param usb libusb usb_dev_handle to use
128 void ftdi_set_usbdev (struct ftdi_context *ftdi, usb_dev_handle *usb)
135 Finds all ftdi devices on the usb bus. Creates a new ftdi_device_list which
136 needs to be deallocated by ftdi_list_free() after use.
138 \param ftdi pointer to ftdi_context
139 \param devlist Pointer where to store list of found devices
140 \param vendor Vendor ID to search for
141 \param product Product ID to search for
143 \retval >0: number of devices found
144 \retval -1: usb_find_busses() failed
145 \retval -2: usb_find_devices() failed
146 \retval -3: out of memory
148 int ftdi_usb_find_all(struct ftdi_context *ftdi, struct ftdi_device_list **devlist, int vendor, int product)
150 struct ftdi_device_list **curdev;
152 struct usb_device *dev;
156 if (usb_find_busses() < 0)
157 ftdi_error_return(-1, "usb_find_busses() failed");
158 if (usb_find_devices() < 0)
159 ftdi_error_return(-2, "usb_find_devices() failed");
163 for (bus = usb_busses; bus; bus = bus->next) {
164 for (dev = bus->devices; dev; dev = dev->next) {
165 if (dev->descriptor.idVendor == vendor
166 && dev->descriptor.idProduct == product)
168 *curdev = (struct ftdi_device_list*)malloc(sizeof(struct ftdi_device_list));
170 ftdi_error_return(-3, "out of memory");
172 (*curdev)->next = NULL;
173 (*curdev)->dev = dev;
175 curdev = &(*curdev)->next;
185 Frees a usb device list.
187 \param devlist USB device list created by ftdi_usb_find_all()
189 void ftdi_list_free(struct ftdi_device_list **devlist)
191 struct ftdi_device_list *curdev, *next;
193 for (curdev = *devlist; curdev != NULL;) {
203 Return device ID strings from the usb device.
205 The parameters manufacturer, description and serial may be NULL
206 or pointer to buffers to store the fetched strings.
208 \note Use this function only in combination with ftdi_usb_find_all()
209 as it closes the internal "usb_dev" after use.
211 \param ftdi pointer to ftdi_context
212 \param dev libusb usb_dev to use
213 \param manufacturer Store manufacturer string here if not NULL
214 \param mnf_len Buffer size of manufacturer string
215 \param description Store product description string here if not NULL
216 \param desc_len Buffer size of product description string
217 \param serial Store serial string here if not NULL
218 \param serial_len Buffer size of serial string
221 \retval -1: wrong arguments
222 \retval -4: unable to open device
223 \retval -7: get product manufacturer failed
224 \retval -8: get product description failed
225 \retval -9: get serial number failed
226 \retval -10: unable to close device
228 int ftdi_usb_get_strings(struct ftdi_context * ftdi, struct usb_device * dev,
229 char * manufacturer, int mnf_len, char * description, int desc_len, char * serial, int serial_len)
231 if ((ftdi==NULL) || (dev==NULL))
234 if (!(ftdi->usb_dev = usb_open(dev)))
235 ftdi_error_return(-4, usb_strerror());
237 if (manufacturer != NULL) {
238 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iManufacturer, manufacturer, mnf_len) <= 0) {
239 usb_close (ftdi->usb_dev);
240 ftdi_error_return(-7, usb_strerror());
244 if (description != NULL) {
245 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, description, desc_len) <= 0) {
246 usb_close (ftdi->usb_dev);
247 ftdi_error_return(-8, usb_strerror());
251 if (serial != NULL) {
252 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, serial, serial_len) <= 0) {
253 usb_close (ftdi->usb_dev);
254 ftdi_error_return(-9, usb_strerror());
258 if (usb_close (ftdi->usb_dev) != 0)
259 ftdi_error_return(-10, usb_strerror());
265 Opens a ftdi device given by a usb_device.
267 \param ftdi pointer to ftdi_context
268 \param dev libusb usb_dev to use
271 \retval -4: unable to open device
272 \retval -5: unable to claim device
273 \retval -6: reset failed
274 \retval -7: set baudrate failed
276 int ftdi_usb_open_dev(struct ftdi_context *ftdi, struct usb_device *dev)
278 int detach_errno = 0;
279 if (!(ftdi->usb_dev = usb_open(dev)))
280 ftdi_error_return(-4, "usb_open() failed");
282 #ifdef LIBUSB_HAS_GET_DRIVER_NP
283 // Try to detach ftdi_sio kernel module
284 // Returns ENODATA if driver is not loaded
285 if (usb_detach_kernel_driver_np(ftdi->usb_dev, ftdi->interface) != 0 && errno != ENODATA)
286 detach_errno = errno;
289 if (usb_claim_interface(ftdi->usb_dev, ftdi->interface) != 0) {
290 usb_close (ftdi->usb_dev);
291 if (detach_errno == EPERM) {
292 ftdi_error_return(-8, "inappropriate permissions on device!");
294 ftdi_error_return(-5, "unable to claim usb device. Make sure ftdi_sio is unloaded!");
298 if (ftdi_usb_reset (ftdi) != 0) {
299 usb_close (ftdi->usb_dev);
300 ftdi_error_return(-6, "ftdi_usb_reset failed");
303 if (ftdi_set_baudrate (ftdi, 9600) != 0) {
304 usb_close (ftdi->usb_dev);
305 ftdi_error_return(-7, "set baudrate failed");
308 // Try to guess chip type
309 // Bug in the BM type chips: bcdDevice is 0x200 for serial == 0
310 if (dev->descriptor.bcdDevice == 0x400 || (dev->descriptor.bcdDevice == 0x200
311 && dev->descriptor.iSerialNumber == 0))
312 ftdi->type = TYPE_BM;
313 else if (dev->descriptor.bcdDevice == 0x200)
314 ftdi->type = TYPE_AM;
315 else if (dev->descriptor.bcdDevice == 0x500) {
316 ftdi->type = TYPE_2232C;
318 ftdi->index = INTERFACE_A;
319 } else if (dev->descriptor.bcdDevice == 0x600)
322 ftdi_error_return(0, "all fine");
326 Opens the first device with a given vendor and product ids.
328 \param ftdi pointer to ftdi_context
329 \param vendor Vendor ID
330 \param product Product ID
332 \retval same as ftdi_usb_open_desc()
334 int ftdi_usb_open(struct ftdi_context *ftdi, int vendor, int product)
336 return ftdi_usb_open_desc(ftdi, vendor, product, NULL, NULL);
340 Opens the first device with a given, vendor id, product id,
341 description and serial.
343 \param ftdi pointer to ftdi_context
344 \param vendor Vendor ID
345 \param product Product ID
346 \param description Description to search for. Use NULL if not needed.
347 \param serial Serial to search for. Use NULL if not needed.
350 \retval -1: usb_find_busses() failed
351 \retval -2: usb_find_devices() failed
352 \retval -3: usb device not found
353 \retval -4: unable to open device
354 \retval -5: unable to claim device
355 \retval -6: reset failed
356 \retval -7: set baudrate failed
357 \retval -8: get product description failed
358 \retval -9: get serial number failed
359 \retval -10: unable to close device
361 int ftdi_usb_open_desc(struct ftdi_context *ftdi, int vendor, int product,
362 const char* description, const char* serial)
365 struct usb_device *dev;
370 if (usb_find_busses() < 0)
371 ftdi_error_return(-1, "usb_find_busses() failed");
372 if (usb_find_devices() < 0)
373 ftdi_error_return(-2, "usb_find_devices() failed");
375 for (bus = usb_busses; bus; bus = bus->next) {
376 for (dev = bus->devices; dev; dev = dev->next) {
377 if (dev->descriptor.idVendor == vendor
378 && dev->descriptor.idProduct == product) {
379 if (!(ftdi->usb_dev = usb_open(dev)))
380 ftdi_error_return(-4, "usb_open() failed");
382 if (description != NULL) {
383 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, string, sizeof(string)) <= 0) {
384 usb_close (ftdi->usb_dev);
385 ftdi_error_return(-8, "unable to fetch product description");
387 if (strncmp(string, description, sizeof(string)) != 0) {
388 if (usb_close (ftdi->usb_dev) != 0)
389 ftdi_error_return(-10, "unable to close device");
393 if (serial != NULL) {
394 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, string, sizeof(string)) <= 0) {
395 usb_close (ftdi->usb_dev);
396 ftdi_error_return(-9, "unable to fetch serial number");
398 if (strncmp(string, serial, sizeof(string)) != 0) {
399 if (usb_close (ftdi->usb_dev) != 0)
400 ftdi_error_return(-10, "unable to close device");
405 if (usb_close (ftdi->usb_dev) != 0)
406 ftdi_error_return(-10, "unable to close device");
408 return ftdi_usb_open_dev(ftdi, dev);
414 ftdi_error_return(-3, "device not found");
418 Resets the ftdi device.
420 \param ftdi pointer to ftdi_context
423 \retval -1: FTDI reset failed
425 int ftdi_usb_reset(struct ftdi_context *ftdi)
427 if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
428 ftdi_error_return(-1,"FTDI reset failed");
430 // Invalidate data in the readbuffer
431 ftdi->readbuffer_offset = 0;
432 ftdi->readbuffer_remaining = 0;
438 Clears the buffers on the chip.
440 \param ftdi pointer to ftdi_context
443 \retval -1: write buffer purge failed
444 \retval -2: read buffer purge failed
446 int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
448 if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 1, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
449 ftdi_error_return(-1, "FTDI purge of RX buffer failed");
451 // Invalidate data in the readbuffer
452 ftdi->readbuffer_offset = 0;
453 ftdi->readbuffer_remaining = 0;
455 if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 2, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
456 ftdi_error_return(-2, "FTDI purge of TX buffer failed");
462 Closes the ftdi device. Call ftdi_deinit() if you're cleaning up.
464 \param ftdi pointer to ftdi_context
467 \retval -1: usb_release failed
468 \retval -2: usb_close failed
470 int ftdi_usb_close(struct ftdi_context *ftdi)
474 if (usb_release_interface(ftdi->usb_dev, ftdi->interface) != 0)
477 if (usb_close (ftdi->usb_dev) != 0)
484 ftdi_convert_baudrate returns nearest supported baud rate to that requested.
485 Function is only used internally
488 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
489 unsigned short *value, unsigned short *index)
491 static const char am_adjust_up[8] = {0, 0, 0, 1, 0, 3, 2, 1};
492 static const char am_adjust_dn[8] = {0, 0, 0, 1, 0, 1, 2, 3};
493 static const char frac_code[8] = {0, 3, 2, 4, 1, 5, 6, 7};
494 int divisor, best_divisor, best_baud, best_baud_diff;
495 unsigned long encoded_divisor;
503 divisor = 24000000 / baudrate;
505 if (ftdi->type == TYPE_AM) {
506 // Round down to supported fraction (AM only)
507 divisor -= am_adjust_dn[divisor & 7];
510 // Try this divisor and the one above it (because division rounds down)
514 for (i = 0; i < 2; i++) {
515 int try_divisor = divisor + i;
519 // Round up to supported divisor value
520 if (try_divisor <= 8) {
521 // Round up to minimum supported divisor
523 } else if (ftdi->type != TYPE_AM && try_divisor < 12) {
524 // BM doesn't support divisors 9 through 11 inclusive
526 } else if (divisor < 16) {
527 // AM doesn't support divisors 9 through 15 inclusive
530 if (ftdi->type == TYPE_AM) {
531 // Round up to supported fraction (AM only)
532 try_divisor += am_adjust_up[try_divisor & 7];
533 if (try_divisor > 0x1FFF8) {
534 // Round down to maximum supported divisor value (for AM)
535 try_divisor = 0x1FFF8;
538 if (try_divisor > 0x1FFFF) {
539 // Round down to maximum supported divisor value (for BM)
540 try_divisor = 0x1FFFF;
544 // Get estimated baud rate (to nearest integer)
545 baud_estimate = (24000000 + (try_divisor / 2)) / try_divisor;
546 // Get absolute difference from requested baud rate
547 if (baud_estimate < baudrate) {
548 baud_diff = baudrate - baud_estimate;
550 baud_diff = baud_estimate - baudrate;
552 if (i == 0 || baud_diff < best_baud_diff) {
553 // Closest to requested baud rate so far
554 best_divisor = try_divisor;
555 best_baud = baud_estimate;
556 best_baud_diff = baud_diff;
557 if (baud_diff == 0) {
558 // Spot on! No point trying
563 // Encode the best divisor value
564 encoded_divisor = (best_divisor >> 3) | (frac_code[best_divisor & 7] << 14);
565 // Deal with special cases for encoded value
566 if (encoded_divisor == 1) {
567 encoded_divisor = 0; // 3000000 baud
568 } else if (encoded_divisor == 0x4001) {
569 encoded_divisor = 1; // 2000000 baud (BM only)
571 // Split into "value" and "index" values
572 *value = (unsigned short)(encoded_divisor & 0xFFFF);
573 if(ftdi->type == TYPE_2232C) {
574 *index = (unsigned short)(encoded_divisor >> 8);
576 *index |= ftdi->index;
579 *index = (unsigned short)(encoded_divisor >> 16);
581 // Return the nearest baud rate
586 Sets the chip baud rate
588 \param ftdi pointer to ftdi_context
589 \param baudrate baud rate to set
592 \retval -1: invalid baudrate
593 \retval -2: setting baudrate failed
595 int ftdi_set_baudrate(struct ftdi_context *ftdi, int baudrate)
597 unsigned short value, index;
600 if (ftdi->bitbang_enabled) {
601 baudrate = baudrate*4;
604 actual_baudrate = ftdi_convert_baudrate(baudrate, ftdi, &value, &index);
605 if (actual_baudrate <= 0)
606 ftdi_error_return (-1, "Silly baudrate <= 0.");
608 // Check within tolerance (about 5%)
609 if ((actual_baudrate * 2 < baudrate /* Catch overflows */ )
610 || ((actual_baudrate < baudrate)
611 ? (actual_baudrate * 21 < baudrate * 20)
612 : (baudrate * 21 < actual_baudrate * 20)))
613 ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
615 if (usb_control_msg(ftdi->usb_dev, 0x40, 3, value, index, NULL, 0, ftdi->usb_write_timeout) != 0)
616 ftdi_error_return (-2, "Setting new baudrate failed");
618 ftdi->baudrate = baudrate;
623 Set (RS232) line characteristics by Alain Abbas
625 \param ftdi pointer to ftdi_context
626 \param bits Number of bits
627 \param sbit Number of stop bits
628 \param parity Parity mode
631 \retval -1: Setting line property failed
633 int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
634 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
636 unsigned short value = bits;
640 value |= (0x00 << 8);
643 value |= (0x01 << 8);
646 value |= (0x02 << 8);
649 value |= (0x03 << 8);
652 value |= (0x04 << 8);
658 value |= (0x00 << 11);
661 value |= (0x01 << 11);
664 value |= (0x02 << 11);
668 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x04, value, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
669 ftdi_error_return (-1, "Setting new line property failed");
675 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip
677 \param ftdi pointer to ftdi_context
678 \param buf Buffer with the data
679 \param size Size of the buffer
681 \retval <0: error code from usb_bulk_write()
682 \retval >0: number of bytes written
684 int ftdi_write_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
688 int total_written = 0;
690 while (offset < size) {
691 int write_size = ftdi->writebuffer_chunksize;
693 if (offset+write_size > size)
694 write_size = size-offset;
696 ret = usb_bulk_write(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size, ftdi->usb_write_timeout);
698 ftdi_error_return(ret, "usb bulk write failed");
700 total_written += ret;
701 offset += write_size;
704 return total_written;
707 /* these structs are stolen from libusb linux implementation
708 they are needed to directly access usbfs and offer async
711 struct usb_iso_packet_desc {
713 unsigned int actual_length;
719 unsigned char endpoint;
726 int number_of_packets;
728 unsigned int signr; /* signal to be sent on error, -1 if none should be sent */
730 struct usb_iso_packet_desc iso_frame_desc[0];
733 /* this is strongly dependent on libusb using the same struct layout. If libusb
734 changes in some later version this may break horribly (this is for libusb 0.1.12) */
735 struct usb_dev_handle {
737 // some other stuff coming here we don't need
740 // some defines for direct usb access, taken from libusb
741 #define MAX_READ_WRITE (16 * 1024)
742 #define IOCTL_USB_SUBMITURB _IOR('U', 10, struct usb_urb)
743 #define USB_URB_TYPE_BULK 3
746 Stupid libusb does not offer async writes nor does it allow
747 access to its fd - so we need some hacks here.
749 static int usb_bulk_write_async(usb_dev_handle *dev, int ep, char *bytes, int size)
752 int bytesdone = 0, requested;
753 struct usb_urb *context;
759 requested = size - bytesdone;
760 if (requested > MAX_READ_WRITE)
761 requested = MAX_READ_WRITE;
763 urb.type = USB_URB_TYPE_BULK;
766 urb.buffer = bytes + bytesdone;
767 urb.buffer_length = requested;
769 urb.actual_length = 0;
770 urb.number_of_packets = 0; /* don't do isochronous yet */
771 urb.usercontext = (void*)1000; /* use something else than libusb... */
773 ret = ioctl(dev->fd, IOCTL_USB_SUBMITURB, &urb);
775 return ret; /* the caller can read errno to get more info */
777 bytesdone += requested;
778 } while (bytesdone < size);
783 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip.
784 Does not wait for completion of the transfer nor does it make sure that
785 the transfer was successful.
787 This function could be extended to use signals and callbacks to inform the
788 caller of completion or error - but this is not done yet, volunteers welcome.
790 Works around libusb and directly accesses functions only available on Linux.
792 \param ftdi pointer to ftdi_context
793 \param buf Buffer with the data
794 \param size Size of the buffer
796 \retval <0: error code from usb_bulk_write()
797 \retval >0: number of bytes written
799 int ftdi_write_data_async(struct ftdi_context *ftdi, unsigned char *buf, int size)
803 int total_written = 0;
805 while (offset < size) {
806 int write_size = ftdi->writebuffer_chunksize;
808 if (offset+write_size > size)
809 write_size = size-offset;
811 ret = usb_bulk_write_async(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size);
813 ftdi_error_return(ret, "usb bulk write async failed");
815 total_written += ret;
816 offset += write_size;
819 return total_written;
824 Configure write buffer chunk size.
827 \param ftdi pointer to ftdi_context
828 \param chunksize Chunk size
832 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
834 ftdi->writebuffer_chunksize = chunksize;
839 Get write buffer chunk size.
841 \param ftdi pointer to ftdi_context
842 \param chunksize Pointer to store chunk size in
846 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
848 *chunksize = ftdi->writebuffer_chunksize;
853 Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
855 Automatically strips the two modem status bytes transfered during every read.
857 \param ftdi pointer to ftdi_context
858 \param buf Buffer to store data in
859 \param size Size of the buffer
861 \retval <0: error code from usb_bulk_read()
862 \retval 0: no data was available
863 \retval >0: number of bytes read
865 \remark This function is not useful in bitbang mode.
866 Use ftdi_read_pins() to get the current state of the pins.
868 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
870 int offset = 0, ret = 1, i, num_of_chunks, chunk_remains;
872 // everything we want is still in the readbuffer?
873 if (size <= ftdi->readbuffer_remaining) {
874 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
877 ftdi->readbuffer_remaining -= size;
878 ftdi->readbuffer_offset += size;
880 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
884 // something still in the readbuffer, but not enough to satisfy 'size'?
885 if (ftdi->readbuffer_remaining != 0) {
886 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
889 offset += ftdi->readbuffer_remaining;
891 // do the actual USB read
892 while (offset < size && ret > 0) {
893 ftdi->readbuffer_remaining = 0;
894 ftdi->readbuffer_offset = 0;
895 /* returns how much received */
896 ret = usb_bulk_read (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, ftdi->usb_read_timeout);
898 ftdi_error_return(ret, "usb bulk read failed");
901 // skip FTDI status bytes.
902 // Maybe stored in the future to enable modem use
903 num_of_chunks = ret / 64;
904 chunk_remains = ret % 64;
905 //printf("ret = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", ret, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
907 ftdi->readbuffer_offset += 2;
911 for (i = 1; i < num_of_chunks; i++)
912 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+62*i,
913 ftdi->readbuffer+ftdi->readbuffer_offset+64*i,
915 if (chunk_remains > 2) {
916 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+62*i,
917 ftdi->readbuffer+ftdi->readbuffer_offset+64*i,
919 ret -= 2*num_of_chunks;
921 ret -= 2*(num_of_chunks-1)+chunk_remains;
923 } else if (ret <= 2) {
924 // no more data to read?
928 // data still fits in buf?
929 if (offset+ret <= size) {
930 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, ret);
931 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
934 /* Did we read exactly the right amount of bytes? */
936 //printf("read_data exact rem %d offset %d\n",
937 //ftdi->readbuffer_remaining, offset);
940 // only copy part of the data or size <= readbuffer_chunksize
941 int part_size = size-offset;
942 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
944 ftdi->readbuffer_offset += part_size;
945 ftdi->readbuffer_remaining = ret-part_size;
948 /* printf("Returning part: %d - size: %d - offset: %d - ret: %d - remaining: %d\n",
949 part_size, size, offset, ret, ftdi->readbuffer_remaining); */
960 Configure read buffer chunk size.
963 Automatically reallocates the buffer.
965 \param ftdi pointer to ftdi_context
966 \param chunksize Chunk size
970 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
972 unsigned char *new_buf;
974 // Invalidate all remaining data
975 ftdi->readbuffer_offset = 0;
976 ftdi->readbuffer_remaining = 0;
978 if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
979 ftdi_error_return(-1, "out of memory for readbuffer");
981 ftdi->readbuffer = new_buf;
982 ftdi->readbuffer_chunksize = chunksize;
988 Get read buffer chunk size.
990 \param ftdi pointer to ftdi_context
991 \param chunksize Pointer to store chunk size in
995 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
997 *chunksize = ftdi->readbuffer_chunksize;
1003 Enable bitbang mode.
1005 For advanced bitbang modes of the FT2232C chip use ftdi_set_bitmode().
1007 \param ftdi pointer to ftdi_context
1008 \param bitmask Bitmask to configure lines.
1009 HIGH/ON value configures a line as output.
1012 \retval -1: can't enable bitbang mode
1014 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
1016 unsigned short usb_val;
1018 usb_val = bitmask; // low byte: bitmask
1019 /* FT2232C: Set bitbang_mode to 2 to enable SPI */
1020 usb_val |= (ftdi->bitbang_mode << 8);
1022 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x0B, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1023 ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
1025 ftdi->bitbang_enabled = 1;
1030 Disable bitbang mode.
1032 \param ftdi pointer to ftdi_context
1035 \retval -1: can't disable bitbang mode
1037 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
1039 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x0B, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1040 ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
1042 ftdi->bitbang_enabled = 0;
1047 Enable advanced bitbang mode for FT2232C chips.
1049 \param ftdi pointer to ftdi_context
1050 \param bitmask Bitmask to configure lines.
1051 HIGH/ON value configures a line as output.
1052 \param mode Bitbang mode: 1 for normal mode, 2 for SPI mode
1055 \retval -1: can't enable bitbang mode
1057 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
1059 unsigned short usb_val;
1061 usb_val = bitmask; // low byte: bitmask
1062 usb_val |= (mode << 8);
1063 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x0B, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1064 ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps not a 2232C type chip?");
1066 ftdi->bitbang_mode = mode;
1067 ftdi->bitbang_enabled = (mode == BITMODE_BITBANG || mode == BITMODE_SYNCBB)?1:0;
1072 Directly read pin state. Useful for bitbang mode.
1074 \param ftdi pointer to ftdi_context
1075 \param pins Pointer to store pins into
1078 \retval -1: read pins failed
1080 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
1082 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x0C, 0, ftdi->index, (char *)pins, 1, ftdi->usb_read_timeout) != 1)
1083 ftdi_error_return(-1, "read pins failed");
1091 The FTDI chip keeps data in the internal buffer for a specific
1092 amount of time if the buffer is not full yet to decrease
1093 load on the usb bus.
1095 \param ftdi pointer to ftdi_context
1096 \param latency Value between 1 and 255
1099 \retval -1: latency out of range
1100 \retval -2: unable to set latency timer
1102 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
1104 unsigned short usb_val;
1107 ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
1110 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x09, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
1111 ftdi_error_return(-2, "unable to set latency timer");
1119 \param ftdi pointer to ftdi_context
1120 \param latency Pointer to store latency value in
1123 \retval -1: unable to get latency timer
1125 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1127 unsigned short usb_val;
1128 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x0A, 0, ftdi->index, (char *)&usb_val, 1, ftdi->usb_read_timeout) != 1)
1129 ftdi_error_return(-1, "reading latency timer failed");
1131 *latency = (unsigned char)usb_val;
1136 Init eeprom with default values.
1138 \param eeprom Pointer to ftdi_eeprom
1140 void ftdi_eeprom_initdefaults(struct ftdi_eeprom *eeprom)
1142 eeprom->vendor_id = 0x0403;
1143 eeprom->product_id = 0x6001;
1145 eeprom->self_powered = 1;
1146 eeprom->remote_wakeup = 1;
1147 eeprom->BM_type_chip = 1;
1149 eeprom->in_is_isochronous = 0;
1150 eeprom->out_is_isochronous = 0;
1151 eeprom->suspend_pull_downs = 0;
1153 eeprom->use_serial = 0;
1154 eeprom->change_usb_version = 0;
1155 eeprom->usb_version = 0x0200;
1156 eeprom->max_power = 0;
1158 eeprom->manufacturer = NULL;
1159 eeprom->product = NULL;
1160 eeprom->serial = NULL;
1164 Build binary output from ftdi_eeprom structure.
1165 Output is suitable for ftdi_write_eeprom().
1167 \param eeprom Pointer to ftdi_eeprom
1168 \param output Buffer of 128 bytes to store eeprom image to
1170 \retval >0: used eeprom size
1171 \retval -1: eeprom size (128 bytes) exceeded by custom strings
1173 int ftdi_eeprom_build(struct ftdi_eeprom *eeprom, unsigned char *output)
1176 unsigned short checksum, value;
1177 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
1180 if (eeprom->manufacturer != NULL)
1181 manufacturer_size = strlen(eeprom->manufacturer);
1182 if (eeprom->product != NULL)
1183 product_size = strlen(eeprom->product);
1184 if (eeprom->serial != NULL)
1185 serial_size = strlen(eeprom->serial);
1187 size_check = 128; // eeprom is 128 bytes
1188 size_check -= 28; // 28 are always in use (fixed)
1189 size_check -= manufacturer_size*2;
1190 size_check -= product_size*2;
1191 size_check -= serial_size*2;
1193 // eeprom size exceeded?
1198 memset (output, 0, 128);
1200 // Addr 00: Stay 00 00
1201 // Addr 02: Vendor ID
1202 output[0x02] = eeprom->vendor_id;
1203 output[0x03] = eeprom->vendor_id >> 8;
1205 // Addr 04: Product ID
1206 output[0x04] = eeprom->product_id;
1207 output[0x05] = eeprom->product_id >> 8;
1209 // Addr 06: Device release number (0400h for BM features)
1210 output[0x06] = 0x00;
1212 if (eeprom->BM_type_chip == 1)
1213 output[0x07] = 0x04;
1215 output[0x07] = 0x02;
1217 // Addr 08: Config descriptor
1218 // Bit 1: remote wakeup if 1
1219 // Bit 0: self powered if 1
1222 if (eeprom->self_powered == 1)
1224 if (eeprom->remote_wakeup == 1)
1228 // Addr 09: Max power consumption: max power = value * 2 mA
1229 output[0x09] = eeprom->max_power;
1232 // Addr 0A: Chip configuration
1233 // Bit 7: 0 - reserved
1234 // Bit 6: 0 - reserved
1235 // Bit 5: 0 - reserved
1236 // Bit 4: 1 - Change USB version
1237 // Bit 3: 1 - Use the serial number string
1238 // Bit 2: 1 - Enable suspend pull downs for lower power
1239 // Bit 1: 1 - Out EndPoint is Isochronous
1240 // Bit 0: 1 - In EndPoint is Isochronous
1243 if (eeprom->in_is_isochronous == 1)
1245 if (eeprom->out_is_isochronous == 1)
1247 if (eeprom->suspend_pull_downs == 1)
1249 if (eeprom->use_serial == 1)
1251 if (eeprom->change_usb_version == 1)
1255 // Addr 0B: reserved
1256 output[0x0B] = 0x00;
1258 // Addr 0C: USB version low byte when 0x0A bit 4 is set
1259 // Addr 0D: USB version high byte when 0x0A bit 4 is set
1260 if (eeprom->change_usb_version == 1) {
1261 output[0x0C] = eeprom->usb_version;
1262 output[0x0D] = eeprom->usb_version >> 8;
1266 // Addr 0E: Offset of the manufacturer string + 0x80
1267 output[0x0E] = 0x14 + 0x80;
1269 // Addr 0F: Length of manufacturer string
1270 output[0x0F] = manufacturer_size*2 + 2;
1272 // Addr 10: Offset of the product string + 0x80, calculated later
1273 // Addr 11: Length of product string
1274 output[0x11] = product_size*2 + 2;
1276 // Addr 12: Offset of the serial string + 0x80, calculated later
1277 // Addr 13: Length of serial string
1278 output[0x13] = serial_size*2 + 2;
1281 output[0x14] = manufacturer_size*2 + 2;
1282 output[0x15] = 0x03; // type: string
1286 // Output manufacturer
1287 for (j = 0; j < manufacturer_size; j++) {
1288 output[i] = eeprom->manufacturer[j], i++;
1289 output[i] = 0x00, i++;
1292 // Output product name
1293 output[0x10] = i + 0x80; // calculate offset
1294 output[i] = product_size*2 + 2, i++;
1295 output[i] = 0x03, i++;
1296 for (j = 0; j < product_size; j++) {
1297 output[i] = eeprom->product[j], i++;
1298 output[i] = 0x00, i++;
1302 output[0x12] = i + 0x80; // calculate offset
1303 output[i] = serial_size*2 + 2, i++;
1304 output[i] = 0x03, i++;
1305 for (j = 0; j < serial_size; j++) {
1306 output[i] = eeprom->serial[j], i++;
1307 output[i] = 0x00, i++;
1310 // calculate checksum
1313 for (i = 0; i < 63; i++) {
1314 value = output[i*2];
1315 value += output[(i*2)+1] << 8;
1317 checksum = value^checksum;
1318 checksum = (checksum << 1) | (checksum >> 15);
1321 output[0x7E] = checksum;
1322 output[0x7F] = checksum >> 8;
1330 \param ftdi pointer to ftdi_context
1331 \param eeprom Pointer to store eeprom into
1334 \retval -1: read failed
1336 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
1340 for (i = 0; i < 64; i++) {
1341 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x90, 0, i, eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
1342 ftdi_error_return(-1, "reading eeprom failed");
1349 ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
1350 Function is only used internally
1353 static unsigned char ftdi_read_chipid_shift(unsigned char value)
1355 return ((value & 1) << 1) |
1356 ((value & 2) << 5) |
1357 ((value & 4) >> 2) |
1358 ((value & 8) << 4) |
1359 ((value & 16) >> 1) |
1360 ((value & 32) >> 1) |
1361 ((value & 64) >> 4) |
1362 ((value & 128) >> 2);
1366 Read the FTDIChip-ID from R-type devices
1368 \param ftdi pointer to ftdi_context
1369 \param chipid Pointer to store FTDIChip-ID
1372 \retval -1: read failed
1374 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
1376 unsigned int a = 0, b = 0;
1378 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x90, 0, 0x43, (char *)&a, 2, ftdi->usb_read_timeout) == 2)
1380 a = a << 8 | a >> 8;
1381 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x90, 0, 0x44, (char *)&b, 2, ftdi->usb_read_timeout) == 2)
1383 b = b << 8 | b >> 8;
1385 a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8
1386 | ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
1387 *chipid = a ^ 0xa5f0f7d1;
1392 ftdi_error_return(-1, "read of FTDIChip-ID failed");
1398 \param ftdi pointer to ftdi_context
1399 \param eeprom Pointer to read eeprom from
1402 \retval -1: read failed
1404 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
1406 unsigned short usb_val;
1409 for (i = 0; i < 64; i++) {
1410 usb_val = eeprom[i*2];
1411 usb_val += eeprom[(i*2)+1] << 8;
1412 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x91, usb_val, i, NULL, 0, ftdi->usb_write_timeout) != 0)
1413 ftdi_error_return(-1, "unable to write eeprom");
1422 \param ftdi pointer to ftdi_context
1425 \retval -1: erase failed
1427 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
1429 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x92, 0, 0, NULL, 0, ftdi->usb_write_timeout) != 0)
1430 ftdi_error_return(-1, "unable to erase eeprom");
1436 Get string representation for last error code
1438 \param ftdi pointer to ftdi_context
1440 \retval Pointer to error string
1442 char *ftdi_get_error_string (struct ftdi_context *ftdi)
1444 return ftdi->error_str;
1448 Flow control code by Lorenz Moesenlechner (lorenz@hcilab.org)
1449 and Matthias Kranz (matthias@hcilab.org)
1452 Set flowcontrol for ftdi chip
1454 \param ftdi pointer to ftdi_context
1455 \param flowctrl flow control to use. should be
1456 SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1459 \retval -1: set flow control failed
1461 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1463 if (usb_control_msg(ftdi->usb_dev, SIO_SET_FLOW_CTRL_REQUEST_TYPE,
1464 SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->interface),
1465 NULL, 0, ftdi->usb_write_timeout) != 0)
1466 ftdi_error_return(-1, "set flow control failed");
1474 \param ftdi pointer to ftdi_context
1475 \param state state to set line to (1 or 0)
1478 \retval -1: set dtr failed
1480 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
1482 unsigned short usb_val;
1485 usb_val = SIO_SET_DTR_HIGH;
1487 usb_val = SIO_SET_DTR_LOW;
1489 if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
1490 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->interface,
1491 NULL, 0, ftdi->usb_write_timeout) != 0)
1492 ftdi_error_return(-1, "set dtr failed");
1500 \param ftdi pointer to ftdi_context
1501 \param state state to set line to (1 or 0)
1504 \retval -1 set rts failed
1506 int ftdi_setrts(struct ftdi_context *ftdi, int state)
1508 unsigned short usb_val;
1511 usb_val = SIO_SET_RTS_HIGH;
1513 usb_val = SIO_SET_RTS_LOW;
1515 if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
1516 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->interface,
1517 NULL, 0, ftdi->usb_write_timeout) != 0)
1518 ftdi_error_return(-1, "set of rts failed");
1523 /* @} end of doxygen libftdi group */