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 */
37 #define ftdi_error_return(code, str) do { \
38 ftdi->error_str = str; \
44 Initializes a ftdi_context.
46 \param ftdi pointer to ftdi_context
49 \retval -1: couldn't allocate read buffer
51 \remark This should be called before all functions
53 int ftdi_init(struct ftdi_context *ftdi)
56 ftdi->usb_read_timeout = 5000;
57 ftdi->usb_write_timeout = 5000;
59 ftdi->type = TYPE_BM; /* chip type */
61 ftdi->bitbang_enabled = 0;
63 ftdi->readbuffer = NULL;
64 ftdi->readbuffer_offset = 0;
65 ftdi->readbuffer_remaining = 0;
66 ftdi->writebuffer_chunksize = 4096;
72 ftdi->bitbang_mode = 1; /* 1: Normal bitbang mode, 2: SPI bitbang mode */
74 ftdi->error_str = NULL;
76 /* All fine. Now allocate the readbuffer */
77 return ftdi_read_data_set_chunksize(ftdi, 4096);
81 Open selected channels on a chip, otherwise use first channel.
83 \param ftdi pointer to ftdi_context
84 \param interface Interface to use for FT2232C chips.
87 \retval -1: unknown interface
89 int ftdi_set_interface(struct ftdi_context *ftdi, enum ftdi_interface interface)
94 /* ftdi_usb_open_desc cares to set the right index, depending on the found chip */
98 ftdi->index = INTERFACE_B;
103 ftdi_error_return(-1, "Unknown interface");
109 Deinitializes a ftdi_context.
111 \param ftdi pointer to ftdi_context
113 void ftdi_deinit(struct ftdi_context *ftdi)
115 if (ftdi->readbuffer != NULL) {
116 free(ftdi->readbuffer);
117 ftdi->readbuffer = NULL;
122 Use an already open libusb device.
124 \param ftdi pointer to ftdi_context
125 \param usb libusb usb_dev_handle to use
127 void ftdi_set_usbdev (struct ftdi_context *ftdi, usb_dev_handle *usb)
134 Finds all ftdi devices on the usb bus. Creates a new ftdi_device_list which
135 needs to be deallocated by ftdi_list_free() after use.
137 \param ftdi pointer to ftdi_context
138 \param devlist Pointer where to store list of found devices
139 \param vendor Vendor ID to search for
140 \param product Product ID to search for
142 \retval >0: number of devices found
143 \retval -1: usb_find_busses() failed
144 \retval -2: usb_find_devices() failed
145 \retval -3: out of memory
147 int ftdi_usb_find_all(struct ftdi_context *ftdi, struct ftdi_device_list **devlist, int vendor, int product)
149 struct ftdi_device_list **curdev;
151 struct usb_device *dev;
155 if (usb_find_busses() < 0)
156 ftdi_error_return(-1, "usb_find_busses() failed");
157 if (usb_find_devices() < 0)
158 ftdi_error_return(-2, "usb_find_devices() failed");
162 for (bus = usb_busses; bus; bus = bus->next) {
163 for (dev = bus->devices; dev; dev = dev->next) {
164 if (dev->descriptor.idVendor == vendor
165 && dev->descriptor.idProduct == product)
167 *curdev = (struct ftdi_device_list*)malloc(sizeof(struct ftdi_device_list));
169 ftdi_error_return(-3, "out of memory");
171 (*curdev)->next = NULL;
172 (*curdev)->dev = dev;
174 curdev = &(*curdev)->next;
184 Frees a usb device list.
186 \param devlist USB device list created by ftdi_usb_find_all()
188 void ftdi_list_free(struct ftdi_device_list **devlist)
190 struct ftdi_device_list *curdev, *next;
192 for (curdev = *devlist; curdev != NULL;) {
202 Return device ID strings from the usb device.
204 The parameters manufacturer, description and serial may be NULL
205 or pointer to buffers to store the fetched strings.
207 \note Use this function only in combination with ftdi_usb_find_all()
208 as it closes the internal "usb_dev" after use.
210 \param ftdi pointer to ftdi_context
211 \param dev libusb usb_dev to use
212 \param manufacturer Store manufacturer string here if not NULL
213 \param mnf_len Buffer size of manufacturer string
214 \param description Store product description string here if not NULL
215 \param desc_len Buffer size of product description string
216 \param serial Store serial string here if not NULL
217 \param serial_len Buffer size of serial string
220 \retval -1: wrong arguments
221 \retval -4: unable to open device
222 \retval -7: get product manufacturer failed
223 \retval -8: get product description failed
224 \retval -9: get serial number failed
225 \retval -10: unable to close device
227 int ftdi_usb_get_strings(struct ftdi_context * ftdi, struct usb_device * dev,
228 char * manufacturer, int mnf_len, char * description, int desc_len, char * serial, int serial_len)
230 if ((ftdi==NULL) || (dev==NULL))
233 if (!(ftdi->usb_dev = usb_open(dev)))
234 ftdi_error_return(-4, usb_strerror());
236 if (manufacturer != NULL) {
237 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iManufacturer, manufacturer, mnf_len) <= 0) {
238 usb_close (ftdi->usb_dev);
239 ftdi_error_return(-7, usb_strerror());
243 if (description != NULL) {
244 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, description, desc_len) <= 0) {
245 usb_close (ftdi->usb_dev);
246 ftdi_error_return(-8, usb_strerror());
250 if (serial != NULL) {
251 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, serial, serial_len) <= 0) {
252 usb_close (ftdi->usb_dev);
253 ftdi_error_return(-9, usb_strerror());
257 if (usb_close (ftdi->usb_dev) != 0)
258 ftdi_error_return(-10, usb_strerror());
264 Opens a ftdi device given by a usb_device.
266 \param ftdi pointer to ftdi_context
267 \param dev libusb usb_dev to use
270 \retval -4: unable to open device
271 \retval -5: unable to claim device
272 \retval -6: reset failed
273 \retval -7: set baudrate failed
275 int ftdi_usb_open_dev(struct ftdi_context *ftdi, struct usb_device *dev)
277 int detach_errno = 0;
278 if (!(ftdi->usb_dev = usb_open(dev)))
279 ftdi_error_return(-4, "usb_open() failed");
281 #ifdef LIBUSB_HAS_GET_DRIVER_NP
282 // Try to detach ftdi_sio kernel module
283 // Returns ENODATA if driver is not loaded
284 if (usb_detach_kernel_driver_np(ftdi->usb_dev, ftdi->interface) != 0 && errno != ENODATA)
285 detach_errno = errno;
288 if (usb_claim_interface(ftdi->usb_dev, ftdi->interface) != 0) {
289 usb_close (ftdi->usb_dev);
290 if (detach_errno == EPERM) {
291 ftdi_error_return(-8, "inappropriate permissions on device!");
293 ftdi_error_return(-5, "unable to claim usb device. Make sure ftdi_sio is unloaded!");
297 if (ftdi_usb_reset (ftdi) != 0) {
298 usb_close (ftdi->usb_dev);
299 ftdi_error_return(-6, "ftdi_usb_reset failed");
302 if (ftdi_set_baudrate (ftdi, 9600) != 0) {
303 usb_close (ftdi->usb_dev);
304 ftdi_error_return(-7, "set baudrate failed");
307 // Try to guess chip type
308 // Bug in the BM type chips: bcdDevice is 0x200 for serial == 0
309 if (dev->descriptor.bcdDevice == 0x400 || (dev->descriptor.bcdDevice == 0x200
310 && dev->descriptor.iSerialNumber == 0))
311 ftdi->type = TYPE_BM;
312 else if (dev->descriptor.bcdDevice == 0x200)
313 ftdi->type = TYPE_AM;
314 else if (dev->descriptor.bcdDevice == 0x500) {
315 ftdi->type = TYPE_2232C;
317 ftdi->index = INTERFACE_A;
318 } else if (dev->descriptor.bcdDevice == 0x600)
321 ftdi_error_return(0, "all fine");
325 Opens the first device with a given vendor and product ids.
327 \param ftdi pointer to ftdi_context
328 \param vendor Vendor ID
329 \param product Product ID
331 \retval same as ftdi_usb_open_desc()
333 int ftdi_usb_open(struct ftdi_context *ftdi, int vendor, int product)
335 return ftdi_usb_open_desc(ftdi, vendor, product, NULL, NULL);
339 Opens the first device with a given, vendor id, product id,
340 description and serial.
342 \param ftdi pointer to ftdi_context
343 \param vendor Vendor ID
344 \param product Product ID
345 \param description Description to search for. Use NULL if not needed.
346 \param serial Serial to search for. Use NULL if not needed.
349 \retval -1: usb_find_busses() failed
350 \retval -2: usb_find_devices() failed
351 \retval -3: usb device not found
352 \retval -4: unable to open device
353 \retval -5: unable to claim device
354 \retval -6: reset failed
355 \retval -7: set baudrate failed
356 \retval -8: get product description failed
357 \retval -9: get serial number failed
358 \retval -10: unable to close device
360 int ftdi_usb_open_desc(struct ftdi_context *ftdi, int vendor, int product,
361 const char* description, const char* serial)
364 struct usb_device *dev;
369 if (usb_find_busses() < 0)
370 ftdi_error_return(-1, "usb_find_busses() failed");
371 if (usb_find_devices() < 0)
372 ftdi_error_return(-2, "usb_find_devices() failed");
374 for (bus = usb_busses; bus; bus = bus->next) {
375 for (dev = bus->devices; dev; dev = dev->next) {
376 if (dev->descriptor.idVendor == vendor
377 && dev->descriptor.idProduct == product) {
378 if (!(ftdi->usb_dev = usb_open(dev)))
379 ftdi_error_return(-4, "usb_open() failed");
381 if (description != NULL) {
382 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iProduct, string, sizeof(string)) <= 0) {
383 usb_close (ftdi->usb_dev);
384 ftdi_error_return(-8, "unable to fetch product description");
386 if (strncmp(string, description, sizeof(string)) != 0) {
387 if (usb_close (ftdi->usb_dev) != 0)
388 ftdi_error_return(-10, "unable to close device");
392 if (serial != NULL) {
393 if (usb_get_string_simple(ftdi->usb_dev, dev->descriptor.iSerialNumber, string, sizeof(string)) <= 0) {
394 usb_close (ftdi->usb_dev);
395 ftdi_error_return(-9, "unable to fetch serial number");
397 if (strncmp(string, serial, sizeof(string)) != 0) {
398 if (usb_close (ftdi->usb_dev) != 0)
399 ftdi_error_return(-10, "unable to close device");
404 if (usb_close (ftdi->usb_dev) != 0)
405 ftdi_error_return(-10, "unable to close device");
407 return ftdi_usb_open_dev(ftdi, dev);
413 ftdi_error_return(-3, "device not found");
417 Resets the ftdi device.
419 \param ftdi pointer to ftdi_context
422 \retval -1: FTDI reset failed
424 int ftdi_usb_reset(struct ftdi_context *ftdi)
426 if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
427 ftdi_error_return(-1,"FTDI reset failed");
429 // Invalidate data in the readbuffer
430 ftdi->readbuffer_offset = 0;
431 ftdi->readbuffer_remaining = 0;
437 Clears the buffers on the chip.
439 \param ftdi pointer to ftdi_context
442 \retval -1: write buffer purge failed
443 \retval -2: read buffer purge failed
445 int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
447 if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 1, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
448 ftdi_error_return(-1, "FTDI purge of RX buffer failed");
450 // Invalidate data in the readbuffer
451 ftdi->readbuffer_offset = 0;
452 ftdi->readbuffer_remaining = 0;
454 if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 2, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
455 ftdi_error_return(-2, "FTDI purge of TX buffer failed");
461 Closes the ftdi device. Call ftdi_deinit() if you're cleaning up.
463 \param ftdi pointer to ftdi_context
466 \retval -1: usb_release failed
467 \retval -2: usb_close failed
469 int ftdi_usb_close(struct ftdi_context *ftdi)
473 if (usb_release_interface(ftdi->usb_dev, ftdi->interface) != 0)
476 if (usb_close (ftdi->usb_dev) != 0)
483 ftdi_convert_baudrate returns nearest supported baud rate to that requested.
484 Function is only used internally
487 static int ftdi_convert_baudrate(int baudrate, struct ftdi_context *ftdi,
488 unsigned short *value, unsigned short *index)
490 static const char am_adjust_up[8] = {0, 0, 0, 1, 0, 3, 2, 1};
491 static const char am_adjust_dn[8] = {0, 0, 0, 1, 0, 1, 2, 3};
492 static const char frac_code[8] = {0, 3, 2, 4, 1, 5, 6, 7};
493 int divisor, best_divisor, best_baud, best_baud_diff;
494 unsigned long encoded_divisor;
502 divisor = 24000000 / baudrate;
504 if (ftdi->type == TYPE_AM) {
505 // Round down to supported fraction (AM only)
506 divisor -= am_adjust_dn[divisor & 7];
509 // Try this divisor and the one above it (because division rounds down)
513 for (i = 0; i < 2; i++) {
514 int try_divisor = divisor + i;
518 // Round up to supported divisor value
519 if (try_divisor <= 8) {
520 // Round up to minimum supported divisor
522 } else if (ftdi->type != TYPE_AM && try_divisor < 12) {
523 // BM doesn't support divisors 9 through 11 inclusive
525 } else if (divisor < 16) {
526 // AM doesn't support divisors 9 through 15 inclusive
529 if (ftdi->type == TYPE_AM) {
530 // Round up to supported fraction (AM only)
531 try_divisor += am_adjust_up[try_divisor & 7];
532 if (try_divisor > 0x1FFF8) {
533 // Round down to maximum supported divisor value (for AM)
534 try_divisor = 0x1FFF8;
537 if (try_divisor > 0x1FFFF) {
538 // Round down to maximum supported divisor value (for BM)
539 try_divisor = 0x1FFFF;
543 // Get estimated baud rate (to nearest integer)
544 baud_estimate = (24000000 + (try_divisor / 2)) / try_divisor;
545 // Get absolute difference from requested baud rate
546 if (baud_estimate < baudrate) {
547 baud_diff = baudrate - baud_estimate;
549 baud_diff = baud_estimate - baudrate;
551 if (i == 0 || baud_diff < best_baud_diff) {
552 // Closest to requested baud rate so far
553 best_divisor = try_divisor;
554 best_baud = baud_estimate;
555 best_baud_diff = baud_diff;
556 if (baud_diff == 0) {
557 // Spot on! No point trying
562 // Encode the best divisor value
563 encoded_divisor = (best_divisor >> 3) | (frac_code[best_divisor & 7] << 14);
564 // Deal with special cases for encoded value
565 if (encoded_divisor == 1) {
566 encoded_divisor = 0; // 3000000 baud
567 } else if (encoded_divisor == 0x4001) {
568 encoded_divisor = 1; // 2000000 baud (BM only)
570 // Split into "value" and "index" values
571 *value = (unsigned short)(encoded_divisor & 0xFFFF);
572 if(ftdi->type == TYPE_2232C) {
573 *index = (unsigned short)(encoded_divisor >> 8);
575 *index |= ftdi->index;
578 *index = (unsigned short)(encoded_divisor >> 16);
580 // Return the nearest baud rate
585 Sets the chip baud rate
587 \param ftdi pointer to ftdi_context
588 \param baudrate baud rate to set
591 \retval -1: invalid baudrate
592 \retval -2: setting baudrate failed
594 int ftdi_set_baudrate(struct ftdi_context *ftdi, int baudrate)
596 unsigned short value, index;
599 if (ftdi->bitbang_enabled) {
600 baudrate = baudrate*4;
603 actual_baudrate = ftdi_convert_baudrate(baudrate, ftdi, &value, &index);
604 if (actual_baudrate <= 0)
605 ftdi_error_return (-1, "Silly baudrate <= 0.");
607 // Check within tolerance (about 5%)
608 if ((actual_baudrate * 2 < baudrate /* Catch overflows */ )
609 || ((actual_baudrate < baudrate)
610 ? (actual_baudrate * 21 < baudrate * 20)
611 : (baudrate * 21 < actual_baudrate * 20)))
612 ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
614 if (usb_control_msg(ftdi->usb_dev, 0x40, 3, value, index, NULL, 0, ftdi->usb_write_timeout) != 0)
615 ftdi_error_return (-2, "Setting new baudrate failed");
617 ftdi->baudrate = baudrate;
622 Set (RS232) line characteristics by Alain Abbas
624 \param ftdi pointer to ftdi_context
625 \param bits Number of bits
626 \param sbit Number of stop bits
627 \param parity Parity mode
630 \retval -1: Setting line property failed
632 int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
633 enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
635 unsigned short value = bits;
639 value |= (0x00 << 8);
642 value |= (0x01 << 8);
645 value |= (0x02 << 8);
648 value |= (0x03 << 8);
651 value |= (0x04 << 8);
657 value |= (0x00 << 11);
660 value |= (0x01 << 11);
663 value |= (0x02 << 11);
667 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x04, value, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
668 ftdi_error_return (-1, "Setting new line property failed");
674 Writes data in chunks (see ftdi_write_data_set_chunksize()) to the chip
676 \param ftdi pointer to ftdi_context
677 \param buf Buffer with the data
678 \param size Size of the buffer
680 \retval <0: error code from usb_bulk_write()
681 \retval >0: number of bytes written
683 int ftdi_write_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
687 int total_written = 0;
689 while (offset < size) {
690 int write_size = ftdi->writebuffer_chunksize;
692 if (offset+write_size > size)
693 write_size = size-offset;
695 ret = usb_bulk_write(ftdi->usb_dev, ftdi->in_ep, buf+offset, write_size, ftdi->usb_write_timeout);
697 ftdi_error_return(ret, "usb bulk write failed");
699 total_written += ret;
700 offset += write_size;
703 return total_written;
707 Configure write buffer chunk size.
710 \param ftdi pointer to ftdi_context
711 \param chunksize Chunk size
715 int ftdi_write_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
717 ftdi->writebuffer_chunksize = chunksize;
722 Get write buffer chunk size.
724 \param ftdi pointer to ftdi_context
725 \param chunksize Pointer to store chunk size in
729 int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
731 *chunksize = ftdi->writebuffer_chunksize;
736 Reads data in chunks (see ftdi_read_data_set_chunksize()) from the chip.
738 Automatically strips the two modem status bytes transfered during every read.
740 \param ftdi pointer to ftdi_context
741 \param buf Buffer to store data in
742 \param size Size of the buffer
744 \retval <0: error code from usb_bulk_read()
745 \retval 0: no data was available
746 \retval >0: number of bytes read
748 \remark This function is not useful in bitbang mode.
749 Use ftdi_read_pins() to get the current state of the pins.
751 int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size)
753 int offset = 0, ret = 1, i, num_of_chunks, chunk_remains;
755 // everything we want is still in the readbuffer?
756 if (size <= ftdi->readbuffer_remaining) {
757 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, size);
760 ftdi->readbuffer_remaining -= size;
761 ftdi->readbuffer_offset += size;
763 /* printf("Returning bytes from buffer: %d - remaining: %d\n", size, ftdi->readbuffer_remaining); */
767 // something still in the readbuffer, but not enough to satisfy 'size'?
768 if (ftdi->readbuffer_remaining != 0) {
769 memcpy (buf, ftdi->readbuffer+ftdi->readbuffer_offset, ftdi->readbuffer_remaining);
772 offset += ftdi->readbuffer_remaining;
774 // do the actual USB read
775 while (offset < size && ret > 0) {
776 ftdi->readbuffer_remaining = 0;
777 ftdi->readbuffer_offset = 0;
778 /* returns how much received */
779 ret = usb_bulk_read (ftdi->usb_dev, ftdi->out_ep, ftdi->readbuffer, ftdi->readbuffer_chunksize, ftdi->usb_read_timeout);
781 ftdi_error_return(ret, "usb bulk read failed");
784 // skip FTDI status bytes.
785 // Maybe stored in the future to enable modem use
786 num_of_chunks = ret / 64;
787 chunk_remains = ret % 64;
788 //printf("ret = %X, num_of_chunks = %X, chunk_remains = %X, readbuffer_offset = %X\n", ret, num_of_chunks, chunk_remains, ftdi->readbuffer_offset);
790 ftdi->readbuffer_offset += 2;
794 for (i = 1; i < num_of_chunks; i++)
795 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+62*i,
796 ftdi->readbuffer+ftdi->readbuffer_offset+64*i,
798 if (chunk_remains > 2) {
799 memmove (ftdi->readbuffer+ftdi->readbuffer_offset+62*i,
800 ftdi->readbuffer+ftdi->readbuffer_offset+64*i,
802 ret -= 2*num_of_chunks;
804 ret -= 2*(num_of_chunks-1)+chunk_remains;
806 } else if (ret <= 2) {
807 // no more data to read?
811 // data still fits in buf?
812 if (offset+ret <= size) {
813 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, ret);
814 //printf("buf[0] = %X, buf[1] = %X\n", buf[0], buf[1]);
817 /* Did we read exactly the right amount of bytes? */
819 //printf("read_data exact rem %d offset %d\n",
820 //ftdi->readbuffer_remaining, offset);
823 // only copy part of the data or size <= readbuffer_chunksize
824 int part_size = size-offset;
825 memcpy (buf+offset, ftdi->readbuffer+ftdi->readbuffer_offset, part_size);
827 ftdi->readbuffer_offset += part_size;
828 ftdi->readbuffer_remaining = ret-part_size;
831 /* printf("Returning part: %d - size: %d - offset: %d - ret: %d - remaining: %d\n",
832 part_size, size, offset, ret, ftdi->readbuffer_remaining); */
843 Configure read buffer chunk size.
846 Automatically reallocates the buffer.
848 \param ftdi pointer to ftdi_context
849 \param chunksize Chunk size
853 int ftdi_read_data_set_chunksize(struct ftdi_context *ftdi, unsigned int chunksize)
855 unsigned char *new_buf;
857 // Invalidate all remaining data
858 ftdi->readbuffer_offset = 0;
859 ftdi->readbuffer_remaining = 0;
861 if ((new_buf = (unsigned char *)realloc(ftdi->readbuffer, chunksize)) == NULL)
862 ftdi_error_return(-1, "out of memory for readbuffer");
864 ftdi->readbuffer = new_buf;
865 ftdi->readbuffer_chunksize = chunksize;
871 Get read buffer chunk size.
873 \param ftdi pointer to ftdi_context
874 \param chunksize Pointer to store chunk size in
878 int ftdi_read_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize)
880 *chunksize = ftdi->readbuffer_chunksize;
888 For advanced bitbang modes of the FT2232C chip use ftdi_set_bitmode().
890 \param ftdi pointer to ftdi_context
891 \param bitmask Bitmask to configure lines.
892 HIGH/ON value configures a line as output.
895 \retval -1: can't enable bitbang mode
897 int ftdi_enable_bitbang(struct ftdi_context *ftdi, unsigned char bitmask)
899 unsigned short usb_val;
901 usb_val = bitmask; // low byte: bitmask
902 /* FT2232C: Set bitbang_mode to 2 to enable SPI */
903 usb_val |= (ftdi->bitbang_mode << 8);
905 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x0B, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
906 ftdi_error_return(-1, "unable to enter bitbang mode. Perhaps not a BM type chip?");
908 ftdi->bitbang_enabled = 1;
913 Disable bitbang mode.
915 \param ftdi pointer to ftdi_context
918 \retval -1: can't disable bitbang mode
920 int ftdi_disable_bitbang(struct ftdi_context *ftdi)
922 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x0B, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
923 ftdi_error_return(-1, "unable to leave bitbang mode. Perhaps not a BM type chip?");
925 ftdi->bitbang_enabled = 0;
930 Enable advanced bitbang mode for FT2232C chips.
932 \param ftdi pointer to ftdi_context
933 \param bitmask Bitmask to configure lines.
934 HIGH/ON value configures a line as output.
935 \param mode Bitbang mode: 1 for normal mode, 2 for SPI mode
938 \retval -1: can't enable bitbang mode
940 int ftdi_set_bitmode(struct ftdi_context *ftdi, unsigned char bitmask, unsigned char mode)
942 unsigned short usb_val;
944 usb_val = bitmask; // low byte: bitmask
945 usb_val |= (mode << 8);
946 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x0B, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
947 ftdi_error_return(-1, "unable to configure bitbang mode. Perhaps not a 2232C type chip?");
949 ftdi->bitbang_mode = mode;
950 ftdi->bitbang_enabled = (mode == BITMODE_BITBANG || mode == BITMODE_SYNCBB)?1:0;
955 Directly read pin state. Useful for bitbang mode.
957 \param ftdi pointer to ftdi_context
958 \param pins Pointer to store pins into
961 \retval -1: read pins failed
963 int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins)
965 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x0C, 0, ftdi->index, (char *)pins, 1, ftdi->usb_read_timeout) != 1)
966 ftdi_error_return(-1, "read pins failed");
974 The FTDI chip keeps data in the internal buffer for a specific
975 amount of time if the buffer is not full yet to decrease
978 \param ftdi pointer to ftdi_context
979 \param latency Value between 1 and 255
982 \retval -1: latency out of range
983 \retval -2: unable to set latency timer
985 int ftdi_set_latency_timer(struct ftdi_context *ftdi, unsigned char latency)
987 unsigned short usb_val;
990 ftdi_error_return(-1, "latency out of range. Only valid for 1-255");
993 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x09, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
994 ftdi_error_return(-2, "unable to set latency timer");
1002 \param ftdi pointer to ftdi_context
1003 \param latency Pointer to store latency value in
1006 \retval -1: unable to get latency timer
1008 int ftdi_get_latency_timer(struct ftdi_context *ftdi, unsigned char *latency)
1010 unsigned short usb_val;
1011 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x0A, 0, ftdi->index, (char *)&usb_val, 1, ftdi->usb_read_timeout) != 1)
1012 ftdi_error_return(-1, "reading latency timer failed");
1014 *latency = (unsigned char)usb_val;
1019 Init eeprom with default values.
1021 \param eeprom Pointer to ftdi_eeprom
1023 void ftdi_eeprom_initdefaults(struct ftdi_eeprom *eeprom)
1025 eeprom->vendor_id = 0x0403;
1026 eeprom->product_id = 0x6001;
1028 eeprom->self_powered = 1;
1029 eeprom->remote_wakeup = 1;
1030 eeprom->BM_type_chip = 1;
1032 eeprom->in_is_isochronous = 0;
1033 eeprom->out_is_isochronous = 0;
1034 eeprom->suspend_pull_downs = 0;
1036 eeprom->use_serial = 0;
1037 eeprom->change_usb_version = 0;
1038 eeprom->usb_version = 0x0200;
1039 eeprom->max_power = 0;
1041 eeprom->manufacturer = NULL;
1042 eeprom->product = NULL;
1043 eeprom->serial = NULL;
1047 Build binary output from ftdi_eeprom structure.
1048 Output is suitable for ftdi_write_eeprom().
1050 \param eeprom Pointer to ftdi_eeprom
1051 \param output Buffer of 128 bytes to store eeprom image to
1053 \retval >0: used eeprom size
1054 \retval -1: eeprom size (128 bytes) exceeded by custom strings
1056 int ftdi_eeprom_build(struct ftdi_eeprom *eeprom, unsigned char *output)
1059 unsigned short checksum, value;
1060 unsigned char manufacturer_size = 0, product_size = 0, serial_size = 0;
1063 if (eeprom->manufacturer != NULL)
1064 manufacturer_size = strlen(eeprom->manufacturer);
1065 if (eeprom->product != NULL)
1066 product_size = strlen(eeprom->product);
1067 if (eeprom->serial != NULL)
1068 serial_size = strlen(eeprom->serial);
1070 size_check = 128; // eeprom is 128 bytes
1071 size_check -= 28; // 28 are always in use (fixed)
1072 size_check -= manufacturer_size*2;
1073 size_check -= product_size*2;
1074 size_check -= serial_size*2;
1076 // eeprom size exceeded?
1081 memset (output, 0, 128);
1083 // Addr 00: Stay 00 00
1084 // Addr 02: Vendor ID
1085 output[0x02] = eeprom->vendor_id;
1086 output[0x03] = eeprom->vendor_id >> 8;
1088 // Addr 04: Product ID
1089 output[0x04] = eeprom->product_id;
1090 output[0x05] = eeprom->product_id >> 8;
1092 // Addr 06: Device release number (0400h for BM features)
1093 output[0x06] = 0x00;
1095 if (eeprom->BM_type_chip == 1)
1096 output[0x07] = 0x04;
1098 output[0x07] = 0x02;
1100 // Addr 08: Config descriptor
1101 // Bit 1: remote wakeup if 1
1102 // Bit 0: self powered if 1
1105 if (eeprom->self_powered == 1)
1107 if (eeprom->remote_wakeup == 1)
1111 // Addr 09: Max power consumption: max power = value * 2 mA
1112 output[0x09] = eeprom->max_power;
1115 // Addr 0A: Chip configuration
1116 // Bit 7: 0 - reserved
1117 // Bit 6: 0 - reserved
1118 // Bit 5: 0 - reserved
1119 // Bit 4: 1 - Change USB version
1120 // Bit 3: 1 - Use the serial number string
1121 // Bit 2: 1 - Enable suspend pull downs for lower power
1122 // Bit 1: 1 - Out EndPoint is Isochronous
1123 // Bit 0: 1 - In EndPoint is Isochronous
1126 if (eeprom->in_is_isochronous == 1)
1128 if (eeprom->out_is_isochronous == 1)
1130 if (eeprom->suspend_pull_downs == 1)
1132 if (eeprom->use_serial == 1)
1134 if (eeprom->change_usb_version == 1)
1138 // Addr 0B: reserved
1139 output[0x0B] = 0x00;
1141 // Addr 0C: USB version low byte when 0x0A bit 4 is set
1142 // Addr 0D: USB version high byte when 0x0A bit 4 is set
1143 if (eeprom->change_usb_version == 1) {
1144 output[0x0C] = eeprom->usb_version;
1145 output[0x0D] = eeprom->usb_version >> 8;
1149 // Addr 0E: Offset of the manufacturer string + 0x80
1150 output[0x0E] = 0x14 + 0x80;
1152 // Addr 0F: Length of manufacturer string
1153 output[0x0F] = manufacturer_size*2 + 2;
1155 // Addr 10: Offset of the product string + 0x80, calculated later
1156 // Addr 11: Length of product string
1157 output[0x11] = product_size*2 + 2;
1159 // Addr 12: Offset of the serial string + 0x80, calculated later
1160 // Addr 13: Length of serial string
1161 output[0x13] = serial_size*2 + 2;
1164 output[0x14] = manufacturer_size*2 + 2;
1165 output[0x15] = 0x03; // type: string
1169 // Output manufacturer
1170 for (j = 0; j < manufacturer_size; j++) {
1171 output[i] = eeprom->manufacturer[j], i++;
1172 output[i] = 0x00, i++;
1175 // Output product name
1176 output[0x10] = i + 0x80; // calculate offset
1177 output[i] = product_size*2 + 2, i++;
1178 output[i] = 0x03, i++;
1179 for (j = 0; j < product_size; j++) {
1180 output[i] = eeprom->product[j], i++;
1181 output[i] = 0x00, i++;
1185 output[0x12] = i + 0x80; // calculate offset
1186 output[i] = serial_size*2 + 2, i++;
1187 output[i] = 0x03, i++;
1188 for (j = 0; j < serial_size; j++) {
1189 output[i] = eeprom->serial[j], i++;
1190 output[i] = 0x00, i++;
1193 // calculate checksum
1196 for (i = 0; i < 63; i++) {
1197 value = output[i*2];
1198 value += output[(i*2)+1] << 8;
1200 checksum = value^checksum;
1201 checksum = (checksum << 1) | (checksum >> 15);
1204 output[0x7E] = checksum;
1205 output[0x7F] = checksum >> 8;
1213 \param ftdi pointer to ftdi_context
1214 \param eeprom Pointer to store eeprom into
1217 \retval -1: read failed
1219 int ftdi_read_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
1223 for (i = 0; i < 64; i++) {
1224 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x90, 0, i, eeprom+(i*2), 2, ftdi->usb_read_timeout) != 2)
1225 ftdi_error_return(-1, "reading eeprom failed");
1232 ftdi_read_chipid_shift does the bitshift operation needed for the FTDIChip-ID
1233 Function is only used internally
1236 static unsigned char ftdi_read_chipid_shift(unsigned char value)
1238 return ((value & 1) << 1) |
1239 ((value & 2) << 5) |
1240 ((value & 4) >> 2) |
1241 ((value & 8) << 4) |
1242 ((value & 16) >> 1) |
1243 ((value & 32) >> 1) |
1244 ((value & 64) >> 4) |
1245 ((value & 128) >> 2);
1249 Read the FTDIChip-ID from R-type devices
1251 \param ftdi pointer to ftdi_context
1252 \param chipid Pointer to store FTDIChip-ID
1255 \retval -1: read failed
1257 int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid)
1259 unsigned int a = 0, b = 0, result = -1;
1261 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x90, 0, 0x43, (char *)&a, 2, ftdi->usb_read_timeout) == 2)
1263 a = a << 8 | a >> 8;
1264 if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x90, 0, 0x44, (char *)&b, 2, ftdi->usb_read_timeout) == 2)
1266 b = b << 8 | b >> 8;
1268 a = ftdi_read_chipid_shift(a) | ftdi_read_chipid_shift(a>>8)<<8;
1269 a |= ftdi_read_chipid_shift(a>>16)<<16 | ftdi_read_chipid_shift(a>>24)<<24;
1270 *chipid = a ^ 0xa5f0f7d1;
1276 ftdi_error_return(result, "read of FTDIChip-ID failed");
1284 \param ftdi pointer to ftdi_context
1285 \param eeprom Pointer to read eeprom from
1288 \retval -1: read failed
1290 int ftdi_write_eeprom(struct ftdi_context *ftdi, unsigned char *eeprom)
1292 unsigned short usb_val;
1295 for (i = 0; i < 64; i++) {
1296 usb_val = eeprom[i*2];
1297 usb_val += eeprom[(i*2)+1] << 8;
1298 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x91, usb_val, i, NULL, 0, ftdi->usb_write_timeout) != 0)
1299 ftdi_error_return(-1, "unable to write eeprom");
1308 \param ftdi pointer to ftdi_context
1311 \retval -1: erase failed
1313 int ftdi_erase_eeprom(struct ftdi_context *ftdi)
1315 if (usb_control_msg(ftdi->usb_dev, 0x40, 0x92, 0, 0, NULL, 0, ftdi->usb_write_timeout) != 0)
1316 ftdi_error_return(-1, "unable to erase eeprom");
1322 Get string representation for last error code
1324 \param ftdi pointer to ftdi_context
1326 \retval Pointer to error string
1328 char *ftdi_get_error_string (struct ftdi_context *ftdi)
1330 return ftdi->error_str;
1334 Flow control code by Lorenz Moesenlechner (lorenz@hcilab.org)
1335 and Matthias Kranz (matthias@hcilab.org)
1338 Set flowcontrol for ftdi chip
1340 \param ftdi pointer to ftdi_context
1341 \param flowctrl flow control to use. should be
1342 SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
1345 \retval -1: set flow control failed
1347 int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
1349 if (usb_control_msg(ftdi->usb_dev, SIO_SET_FLOW_CTRL_REQUEST_TYPE,
1350 SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->interface),
1351 NULL, 0, ftdi->usb_write_timeout) != 0)
1352 ftdi_error_return(-1, "set flow control failed");
1360 \param ftdi pointer to ftdi_context
1361 \param state state to set line to (1 or 0)
1364 \retval -1: set dtr failed
1366 int ftdi_setdtr(struct ftdi_context *ftdi, int state)
1368 unsigned short usb_val;
1371 usb_val = SIO_SET_DTR_HIGH;
1373 usb_val = SIO_SET_DTR_LOW;
1375 if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
1376 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->interface,
1377 NULL, 0, ftdi->usb_write_timeout) != 0)
1378 ftdi_error_return(-1, "set dtr failed");
1386 \param ftdi pointer to ftdi_context
1387 \param state state to set line to (1 or 0)
1390 \retval -1 set rts failed
1392 int ftdi_setrts(struct ftdi_context *ftdi, int state)
1394 unsigned short usb_val;
1397 usb_val = SIO_SET_RTS_HIGH;
1399 usb_val = SIO_SET_RTS_LOW;
1401 if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
1402 SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->interface,
1403 NULL, 0, ftdi->usb_write_timeout) != 0)
1404 ftdi_error_return(-1, "set of rts failed");
1409 /* @} end of doxygen libftdi group */