--- a/doc/Unbuffered-FT2232x-JTAG	Mon Sep 11 06:51:05 2023 +0000
+++ b/doc/Unbuffered-FT2232x-JTAG	Mon Sep 11 07:23:18 2023 +0000
@@ -1,6 +1,10 @@
 How to make a safe JTAG adapter out of a generic unbuffered FT2232x board
 =========================================================================
 
+[This guide was originally written in 2019; it has been updated slightly for
+ the move of FTDI EEPROM utilities to fc-usbser-tools, plus other minor updates
+ for the situation in 2023, but the principal ideas are all from 2019.]
+
 Among the FOSS community of tinkerers who use OpenOCD to operate on the JTAG
 interfaces of various hardware targets, one of the most common JTAG adapter
 choices (if not the most common) is to use some adapter gadget based on an FTDI
@@ -13,22 +17,15 @@
 buffer inserted between FT2232x I/O pins and the target connection interface)
 would be strongly preferable for a whole host of reasons.  However, to this
 author's disappointment, there are very few community vendors who make such
-adapters, and I was NOT able to find any high-quality buffered JTAG adapter
-which can be bought in the present and which comes with published schematics.
-(There is one very well-known vendor of "community" JTAG adapters who refuses
-to publish schematics for their current model; they have an older model for
-which they did publish schematics, but it is discontinued and they are not
-interested in bringing it back into production or handing the complete design
-over to the community - probably because it would then compete with their
-current sans-schematics product!  Selling JTAG adapters to the community while
-keeping their schematics secret is just assinine, and I refuse to give my
-business to such vendors.)
+adapters, and when I last looked in 2019, I was NOT able to find any high-
+quality buffered JTAG adapter which could be readily bought and which comes
+with published schematics.
 
-Given the current sorry state of availability of buffered JTAG adapters, I have
-given more thought to the unbuffered option, and I found what appears to be a
-way to make them safe - but my method requires programming the EEPROM on the
-FT2232x board with a special custom configuration, and in this article I am
-going to provide the full details and instructions.
+Given the sorry state of availability of buffered JTAG adapters, I gave more
+thought to the unbuffered option, and I found what appears to be a way to make
+them safe - but my method requires programming the EEPROM on the FT2232x board
+with a special custom configuration, and in this article I am going to provide
+the full details and instructions.
 
 To begin with, an unbuffered JTAG adapter (one in which the target JTAG signals
 are connected directly to FT2232x I/O pins without any buffer in between) can
@@ -86,34 +83,37 @@
 
 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=6cf87e5edd9944e1d3b6efd966ea401effc304ee
 
-This commit is included in stable kernel versions 4.4.240, 4.9.240, 4.14.202,
-4.19.152, 5.4.72, 5.8.16 and 5.9.1, and it will appear in mainline kernels from
-5.10 onward.  If your Linux kernel version (or rather ftdi_sio driver version
-if it's a module) includes this commit, the ftdi_sio driver will create a
-ttyUSB device for Channel B, allowing that channel to function as a UART if
-desired, but Channel A will be left alone by the kernel driver, reserved for
-userspace applications like OpenOCD.  If your kernel/driver version does not
-include the newly added commit, both FT2232x channels will be left alone by the
-kernel driver, i.e., no ttyUSB devices will be created.  If you are interested
-only in JTAG and don't need an extra UART on Channel B, it should not matter
-whether your ftdi_sio driver knows about the new custom USB ID or not - you
-simply configure your OpenOCD in userspace to find your unbuffered and ad-hoc-
-wired JTAG adapter at USB ID 0403:7151.  If you do need the UART on Channel B
-but your Linux kernel version does not include the recent addition, you will
-need to manually apply the trivial patch from the commit linked above.
+This commit is included in mainline kernel versions from 5.10 onward, and in
+stable kernel versions 4.4.240, 4.9.240, 4.14.202, 4.19.152, 5.4.72, 5.8.16 and
+5.9.1.  If your Linux kernel version (or rather ftdi_sio driver version if it's
+a module) includes this commit, the ftdi_sio driver will create a ttyUSB device
+for Channel B, allowing that channel to function as a UART if desired, but
+Channel A will be left alone by the kernel driver, reserved for userspace
+applications like OpenOCD.  If your kernel/driver version (older than late 2020)
+does not include the commit in question, both FT2232x channels will be left
+alone by the kernel driver, i.e., no ttyUSB devices will be created.  If you are
+interested only in JTAG and don't need an extra UART on Channel B, it should not
+matter whether your ftdi_sio driver knows about the new custom USB ID or not -
+you simply configure your OpenOCD in userspace to find your unbuffered and
+ad-hoc-wired JTAG adapter at USB ID 0403:7151.  If you do need the UART on
+Channel B but your Linux kernel version is old, you will need to manually apply
+the trivial patch from the commit linked above.
 
 Choice of FT2232x breakout board
 ================================
 
-Here at FreeCalypso HQ we make very extensive use of FT2232C/D breakout boards
-by PLDkit, and I officially recommend and endorse this vendor:
-
-http://pldkit.com/other/ft2232d-module
+In earlier years we made heavy use of generic FT2232D breakout boards made by
+PLDkit OU in Estonia.  We are not sure if that original company still makes
+them or not, but the person behind that company name did eventually sell us
+their Gerber files, and we have published them here:
 
-These modules were originally made with FT2232D chips, then the vendor found a
-stash of old but still good FT2232C chips, and some modules were made with these
-FT2232C chips.  Now it looks like the vendor has gone back to FT2232D - but this
-distinction makes no difference for the present purpose.
+ftp://ftp.freecalypso.org/pub/USB/FTDI/
+or
+https://www.freecalypso.org/pub/USB/FTDI/
+
+Given that we have a stash of FT2232D chips and given that we still have use
+cases for these generic breakout boards, we have a tentative plan to produce
+our own Falconia-branded version of the same adapter/breakout board.
 
 These days FT2232H chips and FT2232H breakout boards are much more popular, but
 I generally prefer FT2232C/D for classicness and simplicity.  Additionally,
@@ -126,27 +126,27 @@
 Programming the EEPROM
 ======================
 
-The officially recommended FT2232D breakout boards from PLDkit have 93C46
-EEPROMs on them, and the boards are shipped with blank EEPROMs.  The blank
-EEPROM state is perfectly good for operating the board as a dual UART, but our
-JTAG application calls for custom EEPROM programming.  A number of people in
-the FOSS community have produced several different tools for programming FTDI
+The boards we used to buy from PLDkit (FT2232D breakout) have 93C46 EEPROMs on
+them, and the boards were shipped with blank EEPROMs.  The blank EEPROM state
+is perfectly good for operating the board as a dual UART, but our JTAG
+application calls for custom EEPROM programming.  A number of people in the
+FOSS community have produced several different tools for programming FTDI
 EEPROMs, and you could even use FTDI's official Winblows tools if you like, but
 I am going to describe how to program the EEPROM using the tools which I
-developed and which are used in production here at Falconia Partners LLC.
+developed and which are used in production here at FreeCalypso HQ.
+
+FreeCalypso FTDI EEPROM tools reside in this Hg repository:
 
-To compile my FTDI EEPROM tools, go into the fteeprom directory and run make
-there; you will need to have libftdi (the classic one, not libftdi1) installed
-on your system.  If all you seek to do is to program this one EEPROM, you don't
-need to install my tools system-wide - you can just run them from the directory
-where they are compiled.
+https://www.freecalypso.org/hg/fc-usbser-tools/
+
+You will need to compile and install these tools, then continue.
 
 If you have the FT2232D board in its initial blank-EEPROM state plugged into
 your system and you don't have any other FT2232x devices with 0403:6010 IDs,
-you can program the EEPROM for JTAG as follows - run this pipeline from the top
-directory of this code repository:
+you can program the EEPROM for JTAG as follows (the command is a shell
+pipeline):
 
-fteeprom/ftee-gen2232c eeproms/jtag-unbuf | fteeprom/fteeprom-prog i:0x0403:0x6010
+ftee-gen2232c jtag-unbuf | fteeprom-prog i:0x0403:0x6010
 
 Then unplug and replug the FT2232D board, and it should come back with the new
 0403:7151 USB ID.  If you wish to bring it back to its original blank-EEPROM