changeset 48:9cfe3223fbf8

doc/FTDI-EEPROM-tools: document -d options
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 11 Sep 2023 03:58:41 +0000
parents b6a5ee85c6a3
children 9ca4f9fa415b
files doc/FTDI-EEPROM-tools
diffstat 1 files changed, 17 insertions(+), 23 deletions(-) [+]
line wrap: on
line diff
--- a/doc/FTDI-EEPROM-tools	Mon Sep 11 03:40:58 2023 +0000
+++ b/doc/FTDI-EEPROM-tools	Mon Sep 11 03:58:41 2023 +0000
@@ -294,30 +294,24 @@
 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
-==============================================
+Unbinding of ftdi_sio ttyUSBx devices
+=====================================
 
-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.
+When invoked without any options, current versions of fteeprom-prog and
+fteeprom-erase do NOT unbind the kernel's ftdi_sio driver from any of the chip's
+interfaces, thus none of the associated ttyUSB devices disappear.  This behavior
+can be modified as follows:
 
-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:
+* Both fteeprom-prog and fteeprom-erase support -d1, -d2 and -d4 options.  These
+  options instruct the tool to command the kernel to unbind from one, two or
+  four interfaces on the target chip - they should be used with FT232x, FT2232x
+  and FT4232x, respectively.
 
-https://laforge.gnumonks.org/blog/20170524-usb-port-powercycle/
-https://marc.info/?l=linux-usb&m=149557709602259&w=2
+* fteeprom-prog running with -r option (FT232R special mode) and no -d options
+  defaults to -d1.  This default was made because -r option is intended only for
+  FT232R, which is known to be a single-channel chip, and the special magic
+  sequence is invasive/disruptive to normal UART operation, hence it isn't
+  really compatible with ttyUSB sticking around.  If you are a hacker and you
+  really know what you are doing, you can defeat this logic with -r -d0.
 
-(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.
+Please refer to Replug-after-EEPROM-write article for additional notes.