fc-usbser-tools: doc/FTDI-EEPROM-tools annotate

annotate doc/FTDI-EEPROM-tools @ 68:5cbde3c80c24

fteeprom-{erase,prog}: detach logic: change to detach by default As it turns out, detaching all ttyUSB interfaces of a multichannel device does not require outside knowledge of how many channels there are, as in our previous -d option design that is being removed here - instead we can read the bNumInterfaces constant from the USB device's config descriptor and thus know how many interfaces there are in total. Based on this discovery, change the design of fteeprom-{erase,prog} as follows: * remove -d option; * flip the default to where we detach all interfaces by default; * add -n option to NOT detach any interfaces.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Wed, 13 Sep 2023 06:37:03 +0000
parents	9cfe3223fbf8
children	930bd5316d56

rev	line source
34 f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 Mother Mychaela has developed a set of Linux command line tools for manipulating
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 configuration EEPROMs that are attached to FT2232x devices and accessed in-band
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3 via USB. This document describes these tools.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5 Supported FTDI chips and EEPROMs
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 ================================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	7
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8 The present tools work with 93C46, 93C56 and 93C66 EEPROMs attached behind
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9 FT2232x dual-channel UART/FIFO/MPSSE/etc chips, both FT2232C/D and FT2232H.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 We can read these EEPROMs for examination or backup, and we can program them
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	11 with new bits, either restoring a previously saved backup or creating a new
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	12 from-scratch configuration. These EEPROM configurations (which we can save,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	13 restore or create from scratch) set the USB VID:PID and the textual strings
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	14 naming the manufacturer, the product model and an optional serial number,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	15 select whether each FT2232x channel will come up in the default UART mode or
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	16 one of the other EEPROM-configurable modes (245 FIFO, CPU-style FIFO or fast
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17 opto-isolated serial), and allow a few other obscure chip settings to be
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18 tweaked.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 Some work has also been done toward the goal of being able to program the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21 internal EEPROM in FT232R chips (a very popular single-channel USB to UART
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 converter needing no external components), but this work should be considered
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23 experimental: the tools appear to work on an UB232R module from Digi-Key
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24 (presumably containing a genuine FT232RQ chip) and on a no-name FT232RL adapter
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25 where the chip is uncertain, but because we have no real production use case
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26 yet, we are not ready to truly vouch for FT232R support.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28 More generally:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 * our fteeprom-read tool should be able to read out the EEPROM content from
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 just about any FTDI chip;
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33 * our fteeprom-prog tool should be able to program a user-supplied set of bits
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34 into any FTDI+EEPROM combo where the EEPROM is a separate chip, or into FT232R
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35 internal EEPROM - but it most likely won't work for newer FT-X chips;
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37 * if the goal is to generate a new EEPROM config from scratch, as opposed to
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38 restoring a saved backup, we currently have generators only for FT2232C/D,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	39 for FT2232H and for FT232R, with the last one considered experimental and not
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40 proven.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	42 No more libftdi dependency!
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	43 ===========================
34 f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	44
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	45 Our initial implementation of fteeprom-* tools was based on libftdi; more
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	46 specifically, one had to use an old libftdi-0.x version, as these old versions
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	47 were the only ones that allowed writing to the EEPROM directly with
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	48 ftdi_write_eeprom_location() API calls. However, the present version has been
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	49 reimplemented to NOT use libftdi at all - instead we have our own minilibs,
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	50 maintained as part of fc-usbser-tools package, that are built on top of
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	51 libusb-0.x API. (The version of libftdi we used previously was also built on
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	52 top of the same libusb-0.x API, hence no change in that dependency.) The
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	53 libusb-0.x API we use consists of <usb.h> include header and -lusb link library
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	54 pull-in; on "modern" systems these pieces will typically be provided by
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	55 libusb-compat-0.1 package wrapping around libusb-1.x, but in the spirit of Holy
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	56 retrocomputing, really old systems can be used with native libusb-0.1.
34 f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58 Selecting the device to operate on
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59 ==================================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61 Our fteeprom-read, fteeprom-prog and fteeprom-erase tools take a device selector
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	62 argument, selecting the device to operate on. The design of this device
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	63 selector mechanism has been copied from libftdi; while we no longer use libftdi,
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	64 we found its device selector mechanism to be a really good design and we have
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	65 fully reimplemented it. The device selector argument is a string in one of the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	66 following formats (some wording copied from libftdi documentation):
34 f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	68 d:<devicenode> - path of bus and device-node (e.g. "003/001") within USB device
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	69 tree as enumerated via libusb-0.x API. Libftdi documentation said
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	70 /proc/bus/usb, but at least on Mother's Slackware 14.2 system, the observed
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	71 location of this device tree is /dev/bus/usb.
34 f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73 i:<vendor>:<product> - first device with given vendor and product id, ids can
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74 be decimal, octal (preceded by "0") or hex (preceded by "0x")
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	75
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	76 i:<vendor>:<product>:<index> - as above with index being the number of the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	77 device (starting with 0) if there are more than one
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	78
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	79 s:<vendor>:<product>:<serial> - first device with given vendor id, product id
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 and serial string
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82 If you have only one FTDI device connected to your PC or laptop at the time of
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	83 your EEPROM manipulation session (generally a good idea to avoid hitting the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	84 wrong device by mistake) and if that FTDI device has some sensible starting
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	85 USB VID:PID (either from the previous EEPROM config or the chip's sans-EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	86 default) that doesn't clash with anything else, then the i: form will probably
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	87 be the most convenient, e.g.:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	88
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	89 i:0x0403:0x6001 for single-channel FT232x devices running with the default ID
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	90 i:0x0403:0x6010 for dual-channel FT2232x devices running with the default ID
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	91 i:0x0403:0xPPPP for custom PIDs assigned out of FTDI's VID range
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	92 i:0xVVVV:0xPPPP for totally custom USB IDs
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	93
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	94 Or if the current device config is totally hosed (the EEPROM has a passing
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	95 checksum, but sets some completely bogus USB ID), then the d: form will
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	96 probably be required for recovery.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	97
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	98 Reading the EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	99 ==================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	100
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	101 The basic EEPROM read command is as follows:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	102
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103 fteeprom-read <device-selector>
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	105 See the previous section for the device selector argument. In this default
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	106 form the tool will read the first 64 EEPROM words, which is appropriate for
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	107 93C46 external EEPROMs or for the internal 1024-bit EEPROM in the FT232R chip.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	108 However, if you are working with an FT2232x board with an external EEPROM and
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109 that EEPROM is of a larger variety (93C56 or 93C66), this basic form with give
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	110 you an incomplete (truncated) read, and you will need one of the following
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	111 extended forms to read the complete EEPROM:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	112
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	113 fteeprom-read -b <device-selector> -- read 128 EEPROM words (93C56)
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	114 fteeprom-read -B <device-selector> -- read 256 EEPROM words (93C66)
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	115
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	116 (If you use one of the extended forms on a smaller EEPROM, you will get 2 or 4
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	117 copies of the same bits.)
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	118
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119 The output of fteeprom-read is in the same format as the input to fteeprom-prog,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	120 thus you can redirect the output to a file and get a restorable backup copy of
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	121 your EEPROM.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	122
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	123 Change from previous version
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	124 ----------------------------
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	125
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	126 In the original libftdi-based implementation of fteeprom-read, the act of
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	127 reading the EEPROM was invasive: libftdi's open function would unbind the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	128 kernel's ftdi_sio driver (Channel A ttyUSB device disappears) and
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	129 reset/reinitialize the SIO channel itself. However, it turns out that these
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	130 invasive steps aren't needed if the goal is only to read the EEPROM - the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	131 necessary USB control endpoint transactions can be done while the kernel's
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	132 ftdi_sio driver remains attached with ttyUSBx devices intact on all channels.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	133 The current version of fteeprom-read has been fixed to be non-invasive in this
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	134 regard: you can now freely read the EEPROM of any connected FTDI device
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	135 without bumping off that device's ttyUSB.
34 f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	136
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	137 Programming the EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	138 ======================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	139
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	140 In terms of the primitives provided over USB, writing to EEPROMs sitting behind
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	141 FTDI chips is accomplished by writing one 16-bit word at a time: the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	142 SIO_WRITE_EEPROM_REQUEST command writes a user-supplied word at a user-supplied
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	143 EEPROM address. However, our fteeprom-prog tool currently supports only writing
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	144 complete EEPROMs (64 or 128 or 256 16-bit words starting at address 0) and we
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	145 do not currently provide any kind of "random access write" utility; the primary
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	146 reason for this design decision is practical usefulness: FTDI's EEPROM structure
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	147 includes a checksum over the first 64 words for 1024-bit EEPROMs or over the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	148 first 128 words for larger ones, and if this checksum fails to match, the entire
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	149 structure is deemed to be invalid - hence there is no practical use case for
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	150 selectively rewriting individual words. The only exception may be with 93C66
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	151 EEPROMs: on these giants only the first half would be subject to the checksum,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	152 and the second half could be used arbitrarily. However, we have not yet
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	153 encountered any boards out in the wild with such big EEPROMs, and we have no
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	154 plans to use such in any of our own hardware designs either, hence there is no
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	155 business case at the present moment to develop tooling support for them.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	156
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	157 There are two primary modes of usage for our fteeprom-prog tool: restoring a
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	158 saved EEPROM backup or writing a new EEPROM config which you generate yourself.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	159 To restore a saved EEPROM backup, run the tool as follows:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	160
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	161 fteeprom-prog <device-selector> <eeprom-image-file>
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	162
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	163 To program a new EEPROM config of your own, run a pipeline of this form:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	164
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	165 <generator-tool> \| fteeprom-prog <device-selector>
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	166
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	167 fteeprom-prog reads the EEPROM image from stdin if no image file is named on
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	168 the command line; the image format is the same in both cases, and the length of
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	169 this EEPROM image tells the tool how many words need to be programmed - there
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	170 are no -b or -B options to fteeprom-prog.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	171
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	172 Generator tools
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	173 ===============
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	174
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	175 Unfortunately FTDI never documented the format of their EEPROM configuration
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	176 structure - apparently they consider it a proprietary trade secret just like
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	177 the wire protocol spoken over USB between their chips and their closed-source
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	178 proprietary drivers. All FOSS community support for these chips is based on
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	179 reverse engineering, and that includes the EEPROM format.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	180
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	181 The present suite of tools includes ftee-gen2232c and ftee-gen2232h EEPROM image
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	182 generators, meant for use with FT2232C/D and FT2232H chips, respectively. These
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	183 tools are based on the knowledge extracted from other (pre-existing) community
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	184 tools, primarily the EEPROM config code built into various libftdi versions -
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	185 we haven't done any FTDI RE of our own, instead the goal of this project has
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	186 been to create a set of tools that are better fit for production use.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	187
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	188 Our ftee-gen2232c and ftee-gen2232h tools are invoked as follows:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	189
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	190 ftee-gen2232[ch] [-b\|-B] <config-file> [serial-num]
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	191
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	192 The output of these generator tools is meant to be piped directly into
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	193 fteeprom-prog.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	194
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	195 The philosophy of which settings are given in the config file vs. which ones
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	196 are given on the command line reflects configuration management and factory
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	197 production line operations. In the envisioned usage there would be a config
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	198 file for each product, giving the USB VID:PID, textual manufacturer and product
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	199 ID strings and possibly other config settings which need to be changed from the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	200 defaults, but the optional serial number string is given on the command line
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	201 because it would be different for each individual unit being programmed.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	202
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	203 The EEPROM size selection is also made on the command line, so that the same
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	204 config can be programmed into a smaller EEPROM or a bigger one. By default our
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	205 tools generate an image suitable for a 93C46 EEPROM: the generated image is 64
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	206 words long, with a checksum in word 63, and the EEPROM type byte in FTDI's
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	207 structure is set to 0x46. Running with -b produces an image for a 93C56 EEPROM:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	208 the EEPROM type byte is set to 0x56, and the checksum-covered image length is
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	209 extended to 128 words. Finally, -B sets things up for a 93C66 EEPROM: the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	210 EEPROM type byte is set to 0x66, but the generated checksum-covered image is
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	211 still 128 words long just like with -b, as that is what FT2232x chips apparently
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	212 expect. I said "apparently" because I don't have any FT2232x hardware with
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	213 93C66 EEPROMs and I don't plan on acquiring or building any, hence this minimal
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	214 93C66 support is completely untested - use at your own risk.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	215
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	216 It also needs to be noted that with our current RE-based understanding of FTDI's
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	217 undocumented EEPROM structure, using a bigger EEPROM does NOT provide more room
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	218 for strings: all that happens with -b and -B options is that a gap of 64 unused
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	219 EEPROM words is inserted between the end of the fixed structure and the
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	220 beginning of strings. The exact same arrangement has been observed in all 93C56
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	221 EEPROM images found in the wild, presumably produced with FTDI's official tools,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	222 including FTDI's own USB-COM232-PLUS2 board - thus it is not clear at all if
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	223 FT2232x chips actually support longer strings with bigger EEPROMs, and if not,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	224 what does one need a bigger EEPROM for...
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	225
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	226 For the format of config files read by our ftee-gen2232[ch] tools and what
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	227 settings can be tweaked, read the source code.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	228
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	229 Installation directory for EEPROM config files
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	230 ----------------------------------------------
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	231
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	232 If the name of the config file passed to ftee-gen* does not contain any '/'
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	233 characters, the named file is sought first in an installation directory
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	234 (/opt/freecalypso/ftdi) and then in the current directory. To suppress this
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	235 search path and read EEPROM config files only from the current directory,
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	236 specify your config file as ./name - filenames (pathnames) containing slashes
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	237 are read as-is.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	238
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	239 This installation directory and search mechanism have been added in order to
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	240 allow standard (usually developed at FreeCalypso HQ) FTDI EEPROM configs which
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	241 end users can then program into their boards by executing a fixed command line
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	242 given in a manual.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	243
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	244 FT232R differences
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	245 ==================
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	246
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	247 The EEPROM generator tool for FT232R is ftee-gen232r; it works on the same
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	248 principle as ftee-gen2232[ch] for FT2232x. However, when you run fteeprom-prog
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	249 to program FT232R's internal EEPROM (whether you are restoring a backup or
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	250 programming the output of ftee-gen232r), you need to add -r option before the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	251 device selector string. This option tells fteeprom-prog to execute the
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	252 FT232R-specific magic sequence (documented in FT232R-notes) before proceeding
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	253 to actual EEPROM writes - without this option the EEPROM content will be garbage
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	254 (bitwise AND of old and new EEPROM images), producing the appearance of a
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	255 bricked chip.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	256
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	257 In the previous libftdi-based version of fteeprom-prog the magic sequence in
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	258 question was executed unconditionally - however, because it is needed only for
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	259 FT232R and because we could simplify our new sans-libftdi code by implementing
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	260 it in an FT232R-only manner (no support for different "index" values for
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	261 multichannel FTDI devices), we've changed it from unconditional to -r option.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	262
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	263 Experiments show that fteeprom-prog -r option appears to be harmless (though
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	264 unnecessary) on FT2232D and FT2232H - however, Mother's recommendation is to
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	265 use it only on FT232R devices.
f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	266
34 f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	267 Erasing the EEPROM (making it blank)
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	268 ====================================
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	269
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	270 If you are playing with a "generic" FT2232x breakout board that is made for
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	271 tinkering, as opposed to a more finished product, such boards are typically
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	272 shipped with their EEPROMs completely blank. In that case restoring the EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	273 to its "pristine" state after playing around would mean erasing it, i.e.,
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	274 bringing it into a blank (all ones) state. FT2232x chips provide two ways to
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	275 do so: one can explicitly write 0xFFFF into each individual EEPROM word with
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	276 SIO_WRITE_EEPROM_REQUEST, or one can send a SIO_ERASE_EEPROM_REQUEST command to
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	277 the chip, and the chip then erases the entire EEPROM. But we don't know how
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	278 the latter SIO_ERASE_EEPROM_REQUEST operation is implemented by FT2232x chips:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	279 does the FT2232x chip go through and erase each word individually, or does it
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	280 issue an "erase full chip" opcode to the serial EEPROM? If the latter, then
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	281 according to some EEPROM datasheets that operation may not work if the EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	282 is powered from a 3.3V rail rather than the full USB 5V - may be an issue in
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	283 FT2232H-based designs.
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	284
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	285 In any case our tools provide both ways. To perform the "automatic full chip
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	286 erase" operation, run the following command:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	287
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	288 fteeprom-erase <device-selector>
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	289
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	290 To blank the EEPROM by writing 0xFFFF into each word, run one of the following
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	291 pipelines:
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	292
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	293 ftee-mkblank \| fteeprom-prog <device-selector> -- blank a 93C46 EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	294 ftee-mkblank -b \| fteeprom-prog <device-selector> -- blank a 93C56 EEPROM
f5fbcf1ff032 doc: initial import from freecalypso-hwlab Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	295 ftee-mkblank -B \| fteeprom-prog <device-selector> -- blank a 93C66 EEPROM
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	296
48 9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	297 Unbinding of ftdi_sio ttyUSBx devices
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	298 =====================================
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	299
48 9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	300 When invoked without any options, current versions of fteeprom-prog and
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	301 fteeprom-erase do NOT unbind the kernel's ftdi_sio driver from any of the chip's
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	302 interfaces, thus none of the associated ttyUSB devices disappear. This behavior
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	303 can be modified as follows:
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	304
48 9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	305 * Both fteeprom-prog and fteeprom-erase support -d1, -d2 and -d4 options. These
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	306 options instruct the tool to command the kernel to unbind from one, two or
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	307 four interfaces on the target chip - they should be used with FT232x, FT2232x
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	308 and FT4232x, respectively.
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	309
48 9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	310 * fteeprom-prog running with -r option (FT232R special mode) and no -d options
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	311 defaults to -d1. This default was made because -r option is intended only for
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	312 FT232R, which is known to be a single-channel chip, and the special magic
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	313 sequence is invasive/disruptive to normal UART operation, hence it isn't
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	314 really compatible with ttyUSB sticking around. If you are a hacker and you
9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	315 really know what you are doing, you can defeat this logic with -r -d0.
35 f548ae912622 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version Mychaela Falconia <falcon@freecalypso.org> parents: 34 diff changeset	316
48 9cfe3223fbf8 doc/FTDI-EEPROM-tools: document -d options Mychaela Falconia <falcon@freecalypso.org> parents: 35 diff changeset	317 Please refer to Replug-after-EEPROM-write article for additional notes.

FreeCalypso > hg > fc-usbser-tools

annotate doc/FTDI-EEPROM-tools @ 68:5cbde3c80c24