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

comparison doc/FTDI-EEPROM-tools @ 35:f548ae912622

doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version

author	Mychaela Falconia <falcon@freecalypso.org>
date	Sun, 10 Sep 2023 00:18:20 +0000
parents	f5fbcf1ff032
children	9cfe3223fbf8

comparison

equal deleted inserted replaced

-:f5fbcf1ff032
+:f548ae912622
 * 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,
 for FT2232H and for FT232R, with the last one considered experimental and not
 proven.
-libftdi dependency
+No more libftdi dependency!
-==================
+===========================
-We use libftdi (which is in turn layered on libusb) to issue the special USB
+Our initial implementation of fteeprom-* tools was based on libftdi; more
-control pipe commands to FTDI chips which are needed to read and write their
+specifically, one had to use an old libftdi-0.x version, as these old versions
-EEPROMs.  We use old-style libftdi-0.x (-lftdi on the link line) as opposed to
+were the only ones that allowed writing to the EEPROM directly with
-libftdi1 (-lftdi1) because the new versions took away the ability to write to
+ftdi_write_eeprom_location() API calls.  However, the present version has been
-the EEPROM directly with ftdi_write_eeprom_location() calls, forcing users to
+reimplemented to NOT use libftdi at all - instead we have our own minilibs,
-go through libftdi1's own EEPROM smarts, which we don't want to do - our tools
+maintained as part of fc-usbser-tools package, that are built on top of
-are all about more direct user empowerment at the lowest level.
+libusb-0.x API.  (The version of libftdi we used previously was also built on
+top of the same libusb-0.x API, hence no change in that dependency.)  The
+libusb-0.x API we use consists of <usb.h> include header and -lusb link library
+pull-in; on "modern" systems these pieces will typically be provided by
+libusb-compat-0.1 package wrapping around libusb-1.x, but in the spirit of Holy
+retrocomputing, really old systems can be used with native libusb-0.1.
 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
+argument, selecting the device to operate on.  The design of this device
-string to be passed to the ftdi_usb_open_string() function in libftdi, allowing
+selector mechanism has been copied from libftdi; while we no longer use libftdi,
-the device to be operated on to be selected in one of several ways.  Copying
+we found its device selector mechanism to be a really good design and we have
-from libftdi documentation, the available formats are:
+fully reimplemented it.  The device selector argument is a string in one of the
+following formats (some wording copied from libftdi documentation):
-d:<devicenode> - path of bus and device-node (e.g. "003/001") within usb device
-tree (usually at /proc/bus/usb/)
+d:<devicenode> - path of bus and device-node (e.g. "003/001") within USB device
+tree as enumerated via libusb-0.x API.  Libftdi documentation said
+/proc/bus/usb, but at least on Mother's Slackware 14.2 system, the observed
+location of this device tree is /dev/bus/usb.
 i:<vendor>:<product> - first device with given vendor and product id, ids can
 be decimal, octal (preceded by "0") or hex (preceded by "0x")
 i:<vendor>:<product>:<index> - as above with index being the number of the
 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.
-It also needs to be noted that if the FTDI device has the kernel's ftdi_sio
+Change from previous version
-driver attached to it (ttyUSB device present) when you run fteeprom-read (same
+----------------------------
-for fteeprom-prog and fteeprom-erase), the act of running any of our EEPROM
-tools will cause it to unbind, i.e., the ttyUSB device will disappear.  If the
+In the original libftdi-based implementation of fteeprom-read, the act of
-device being operated on is a dual-channel FT2232x, then only the ttyUSB device
+reading the EEPROM was invasive: libftdi's open function would unbind the
-corresponding to Channel A will disappear, while the Channel B ttyUSB device
+kernel's ftdi_sio driver (Channel A ttyUSB device disappears) and
-will stay.
+reset/reinitialize the SIO channel itself.  However, it turns out that these
+invasive steps aren't needed if the goal is only to read the EEPROM - the
+necessary USB control endpoint transactions can be done while the kernel's
+ftdi_sio driver remains attached with ttyUSBx devices intact on all channels.
+The current version of fteeprom-read has been fixed to be non-invasive in this
+regard: you can now freely read the EEPROM of any connected FTDI device
+*without* bumping off that device's ttyUSB.
 Programming the EEPROM
 ======================
 In terms of the primitives provided over USB, writing to EEPROMs sitting behind
 what does one need a bigger EEPROM for...
 For the format of config files read by our ftee-gen2232[ch] tools and what
 settings can be tweaked, read the source code.
+Installation directory for EEPROM config files
+----------------------------------------------
+If the name of the config file passed to ftee-gen* does not contain any '/'
+characters, the named file is sought first in an installation directory
+(/opt/freecalypso/ftdi) and then in the current directory.  To suppress this
+search path and read EEPROM config files only from the current directory,
+specify your config file as ./name - filenames (pathnames) containing slashes
+are read as-is.
+This installation directory and search mechanism have been added in order to
+allow standard (usually developed at FreeCalypso HQ) FTDI EEPROM configs which
+end users can then program into their boards by executing a fixed command line
+given in a manual.
+FT232R differences
+==================
+The EEPROM generator tool for FT232R is ftee-gen232r; it works on the same
+principle as ftee-gen2232[ch] for FT2232x.  However, when you run fteeprom-prog
+to program FT232R's internal EEPROM (whether you are restoring a backup or
+programming the output of ftee-gen232r), you need to add -r option before the
+device selector string.  This option tells fteeprom-prog to execute the
+FT232R-specific magic sequence (documented in FT232R-notes) before proceeding
+to actual EEPROM writes - without this option the EEPROM content will be garbage
+(bitwise AND of old and new EEPROM images), producing the appearance of a
+bricked chip.
+In the previous libftdi-based version of fteeprom-prog the magic sequence in
+question was executed unconditionally - however, because it is needed only for
+FT232R and because we could simplify our new sans-libftdi code by implementing
+it in an FT232R-only manner (no support for different "index" values for
+multichannel FTDI devices), we've changed it from unconditional to -r option.
+Experiments show that fteeprom-prog -r option appears to be harmless (though
+unnecessary) on FT2232D and FT2232H - however, Mother's recommendation is to
+use it only on FT232R devices.
 Erasing the EEPROM (making it blank)
 ====================================
 If you are playing with a "generic" FT2232x breakout board that is made for
 tinkering, as opposed to a more finished product, such boards are typically
 pipelines:
 ftee-mkblank | fteeprom-prog <device-selector>		-- blank a 93C46 EEPROM
 ftee-mkblank -b | fteeprom-prog <device-selector>	-- blank a 93C56 EEPROM
 ftee-mkblank -B | fteeprom-prog <device-selector>	-- blank a 93C66 EEPROM
+USB replug after EEPROM programming or erasure
+==============================================
+Unlike fteeprom-read, our fteeprom-prog and fteeprom-erase utilities do command
+the kernel's ftdi_sio driver to unbind.  On single-channel devices the effect
+is that the sole ttyUSB character device associated with the given USB device
+disappears; on multichannel devices the effect is that ttyUSB corresponding to
+Channel A disappears, while Channel B ttyUSB device remains.  In order to bring
+back the bumped-off ttyUSB device, and in order to make the FTDI chip itself
+reread and apply the new EEPROM config, you have to physically unplug and replug
+the USB device.
+Why is physical plug/unplug manipulation needed, why can't we command the needed
+effect via software?  As it turns out, there are no *valid* reasons why it can't
+be done - but we are not currently able to do so because Linux kernel USB
+maintainers are being pricks and won't support functionality that doesn't fit
+into their worldview.  Given that Harald Welte discovered this problem back in
+2017:
+https://laforge.gnumonks.org/blog/20170524-usb-port-powercycle/
+https://marc.info/?l=linux-usb&m=149557709602259&w=2
+(the thread shows Harald's good-faith attempt to reason with those pricks and
+their dismissive responses) and given my own (Mother Mychaela's) sour experience
+with trying to get a simple patch into ftdi_sio (adding support for a quirk-
+requiring FT2232x-based hardware device), the situation with Linux currently
+looks hopeless.

FreeCalypso > hg > fc-usbser-tools

comparison doc/FTDI-EEPROM-tools @ 35:f548ae912622