# HG changeset patch # User Mychaela Falconia # Date 1555961551 0 # Node ID 1f3a4115375f61b6037d6875ce15d29df4c9b36e # Parent 6a2886f9943ee3b478faad01410541e0636d8c0d doc/FTDI-EEPROM-tools: article started diff -r 6a2886f9943e -r 1f3a4115375f doc/FTDI-EEPROM-tools --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/FTDI-EEPROM-tools Mon Apr 22 19:32:31 2019 +0000 @@ -0,0 +1,128 @@ +Mother Mychaela has developed a set of Linux command line tools for manipulating +configuration EEPROMs that are attached to FT2232x devices and accessed in-band +via USB. This document describes these tools. + +Supported FTDI chips and EEPROMs +================================ + +The present tools work with 93C46, 93C56 and 93C66 EEPROMs attached behind +FT2232x dual-channel UART/FIFO/MPSSE/etc chips, both FT2232C/D and FT2232H. +We can read these EEPROMs for examination or backup, and we can program them +with new bits, either restoring a previously saved backup or creating a new +from-scratch configuration. These EEPROM configurations (which we can save, +restore or create from scratch) set the USB VID:PID and the textual strings +naming the manufacturer, the product model and an optional serial number, +select whether each FT2232x channel will come up in the default UART mode or +one of the other EEPROM-configurable modes (245 FIFO, CPU-style FIFO or fast +opto-isolated serial), and allow a few other obscure chip settings to be +tweaked. + +Some work has also been done toward the goal of being able to program the +internal EEPROM in FT232R chips (a very popular single-channel USB to UART +converter needing no external components), but this work has not been finished +yet, and the present tools should NOT be used to attempt an EEPROM write on +that chip - the risking of bricking the chip is too high. + +More generally, our fteeprom-read tool should be able to read out the EEPROM +content from just about any FTDI chip including FT232R, whereas our +fteeprom-prog tool should be able to program a user-supplied set of bits into +any FTDI+EEPROM combo where the EEPROM is a separate chip - but it is NOT safe +to use on FTDI chips like FT232R or FT-X that have their EEPROM built in. +Furthermore, if the goal is to generate a new EEPROM config from scratch, as +opposed to restoring a saved backup, we currently have generators only for +FT2232C/D and for FT2232H. (We also have a generator program for FT232R, but +it is of no use for as long as fteeprom-prog is not safe to use on FT232R +chips.) + +libftdi dependency +================== + +We use libftdi (which is in turn layered on libusb) to issue the special USB +control pipe commands to FTDI chips which are needed to read and write their +EEPROMs. We use old-style libftdi-0.x (-lftdi on the link line) as opposed to +libftdi1 (-lftdi1) because the new versions took away the ability to write to +the EEPROM directly with ftdi_write_eeprom_location() calls, forcing users to +go through libftdi1's own EEPROM smarts, which we don't want to do - our tools +are all about more direct user empowerment at the lowest level. + +Selecting the device to operate on +================================== + +Our fteeprom-read, fteeprom-prog and fteeprom-erase tools take a device selector +argument, selecting the device to operate on. This required argument is the +string to be passed to the ftdi_usb_open_string() function in libftdi, allowing +the device to be operated on to be selected in one of several ways. Copying +from libftdi documentation, the available formats are: + +d: - path of bus and device-node (e.g. "003/001") within usb device +tree (usually at /proc/bus/usb/) + +i:: - first device with given vendor and product id, ids can +be decimal, octal (preceded by "0") or hex (preceded by "0x") + +i::: - as above with index being the number of the +device (starting with 0) if there are more than one + +s::: - first device with given vendor id, product id +and serial string + +If you have only one FTDI device connected to your PC or laptop at the time of +your EEPROM manipulation session (generally a good idea to avoid hitting the +wrong device by mistake) and if that FTDI device has some sensible starting +USB VID:PID (either from the previous EEPROM config or the chip's sans-EEPROM +default) that doesn't clash with anything else, then the i: form will probably +be the most convenient, e.g.: + +i:0x0403:0x6001 for single-channel FT232x devices running with the default ID +i:0x0403:0x6010 for dual-channel FT2232x devices running with the default ID +i:0x0403:0xPPPP for custom PIDs assigned out of FTDI's VID range +i:0xVVVV:0xPPPP for totally custom USB IDs + +Or if the current device config is totally hosed (the EEPROM has a passing +checksum, but sets some completely bogus USB ID), then the d: form will +probably be required for recovery. + +Reading the EEPROM +================== + +The basic EEPROM read command is as follows: + +fteeprom-read + +See the previous section for the device selector argument. In this default +form the tool will read the first 64 EEPROM words, which is appropriate for +93C46 external EEPROMs or for the internal 1024-bit EEPROM in the FT232R chip. +However, if you are working with an FT2232x board with an external EEPROM and +that EEPROM is of a larger variety (93C56 or 93C66), this basic form with give +you an incomplete (truncated) read, and you will need one of the following +extended forms to read the complete EEPROM: + +fteeprom-read -b -- read 128 EEPROM words (93C56) +fteeprom-read -B -- read 256 EEPROM words (93C66) + +(If you use one of the extended forms on a smaller EEPROM, you will get 2 or 4 + copies of the same bits.) + +The output of fteeprom-read is in the same format as the input to fteeprom-prog, +thus you can redirect the output to a file and get a restorable backup copy of +your EEPROM. + +Programming the EEPROM +====================== + +In terms of the primitives provided over USB, writing to EEPROMs behind FTDI +chips is accomplished by writing one 16-bit word at a time: the +SIO_WRITE_EEPROM_REQUEST command writes a user-supplied word at a user-supplied +EEPROM address. However, our fteeprom-prog tool currently supports only writing +complete EEPROMs (64 or 128 or 256 16-bit words starting at address 0) and we +do not currently provide any kind of "random access write" utility; the primary +reason for this design decision is practical usefulness: FTDI's EEPROM structure +includes a checksum over the first 64 words for 1024-bit EEPROMs or over the +first 128 words for larger ones, and if this checksum fails to match, the entire +structure is deemed to be invalid - hence there is no practical use case for +selectively rewriting individual words. The only exception may be with 93C66 +EEPROMs: on these giants only the first half would be subject to the checksum, +and the second half could be used arbitrarily. However, we have not yet +encountered any boards out in the wild with such big EEPROMs, and we have no +plans to use such in any of our own hardware designs either, hence there is no +business case at the present moment to develop tooling support for them.