# HG changeset patch # User Mychaela Falconia # Date 1694305100 0 # Node ID f548ae9126228d4c8ce38b02673a9688e8f371ca # Parent f5fbcf1ff0320e9f89adbd779acdb304ba71df74 doc/FTDI-EEPROM-tools: update for 2023 sans-libftdi version diff -r f5fbcf1ff032 -r f548ae912622 doc/FTDI-EEPROM-tools --- 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 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: - path of bus and device-node (e.g. "003/001") within usb device -tree (usually at /proc/bus/usb/) +d: - 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:: - 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 -- blank a 93C46 EEPROM ftee-mkblank -b | fteeprom-prog -- blank a 93C56 EEPROM ftee-mkblank -B | fteeprom-prog -- 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.