--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Replug-after-EEPROM-write	Mon Sep 11 03:40:58 2023 +0000
@@ -0,0 +1,36 @@
+USB replug after EEPROM modification
+====================================
+
+With the current state of software, if you use any of the tools provided in
+this package to modify the configuration EEPROM content of your USB-serial
+adapter device (FTDI, CP2102, possibly others to be supported in the future),
+you then have to physically unplug and replug the USB device.  This unplug-
+replug sequence is needed because:
+
+* Most USB-serial chips require a deep reset in order to reread their EEPROM
+  and fully apply the new configuration, which may include a new USB VID:PID
+  or other USB descriptor changes.
+
+* With some chips safe and correct EEPROM programming requires unbinding the
+  kernel's usb-serial driver, causing the ttyUSB device for the USB-serial chip
+  (or multiple ttyUSB devices for multichannel chips) to disappear.  With the
+  current state of Linux, we can command the kernel to unbind its drivers from
+  a specific interface on a specific chip (*without* rmmod of the responsible
+  driver, killing all other devices of the same tyoe), but we have no way to
+  tell the kernel to rebind everything when we are done.
+
+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 (failed attempt to mainline the
+patch adding support for DUART28C), the situation with Linux currently looks
+hopeless.