--- a/doc/FTDI-EEPROM-tools	Sat Sep 09 21:28:02 2023 +0000
+++ b/doc/FTDI-EEPROM-tools	Sun Sep 10 00:18:20 2023 +0000
@@ -39,28 +39,36 @@
   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
-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.
+Our initial implementation of fteeprom-* tools was based on libftdi; more
+specifically, one had to use an old libftdi-0.x version, as these old versions
+were the only ones that allowed writing to the EEPROM directly with
+ftdi_write_eeprom_location() API calls.  However, the present version has been
+reimplemented to NOT use libftdi at all - instead we have our own minilibs,
+maintained as part of fc-usbser-tools package, that are built on top of
+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
-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:
+argument, selecting the device to operate on.  The design of this device
+selector mechanism has been copied from libftdi; while we no longer use libftdi,
+we found its device selector mechanism to be a really good design and we have
+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")
@@ -112,13 +120,19 @@
 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
-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
-device being operated on is a dual-channel FT2232x, then only the ttyUSB device
-corresponding to Channel A will disappear, while the Channel B ttyUSB device
-will stay.
+Change from previous version
+----------------------------
+
+In the original libftdi-based implementation of fteeprom-read, the act of
+reading the EEPROM was invasive: libftdi's open function would unbind the
+kernel's ftdi_sio driver (Channel A ttyUSB device disappears) and
+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
 ======================
@@ -212,6 +226,44 @@
 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)
 ====================================
 
@@ -241,3 +293,31 @@
 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.