--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Mon Dec 11 08:24:49 2023 +0000
@@ -0,0 +1,72 @@
+Patches to Linux kernel ftdi_sio driver: add support for USB device 0403:7152
+=============================================================================
+
+The present repository contains many different versions (made to apply against
+different versions of Linux kernel) of the same series of patches to ftdi_sio
+driver: adding support for a new, previously unsupported USB-serial device,
+distinctly identified by a new, previously unsupported USB ID code.  This ID
+code (a PID out of FTDI's VID) has been officially allocated by FTDI to
+Falconia Partners LLC.
+
+Q: What is the physical hardware in question?
+
+A: The one hardware device that already exists physically and requires the
+   present series of patches is the 'C' configuration of FreeCalypso DUART28
+   adapter.  However, we expect to have other hardware products in the near
+   future that will have the same control signal wiring, require the same
+   special handling from the Linux kernel, share the same USB ID code and be
+   supported by the same patch.
+
+Q: What is so special about this family of USB-serial devices?
+
+A: All devices that may share the same USB ID code and will therefore be
+   automatically supported by the same patch have the same essential properties:
+   it is a two-channel FTDI device (FT2232D or FT2232H) with Channel A wired
+   normally (100% standard ttyUSB handling is appropriate), but special wiring
+   on Channel B.  The latter channel on these devices is a hybrid UART+GPIO
+   entity: a ttyUSB device is needed (the same binary serial protocols that are
+   spoken over TxD/RxD lines on this device are also spoken over myriad other
+   standard serial ports), but this ttyUSB device needs to operate with a
+   special quirk.  The quirk is that standard POSIX etc behavior for this one
+   particular ttyUSB device needs to be intentionally broken: the usual
+   automatic assertion of DTR & RTS upon ttyUSB device open MUST be suppressed
+   - but these two signals must still be controllable via explicit TIOCMBIS and
+   TIOCMBIC ioctls, issued by custom userspace tools.
+
+Q: What behavioral changes are effected by the present series of patches to
+   Linux kernel ftdi_sio driver?
+
+A: The only change is purely additive: USB device 0403:7152, previously
+   unsupported, becomes supported and recognized as needing the special quirk
+   described in the previous catechism.  Absolutely no behavioral changes are
+   applied to anything else other than this one USB device.
+
+Q: If the change does nothing more than add support for a new USB device, why
+   is it not mainlined?
+
+A: I, Mychaela Nadezhda Falconia, the designer of the hardware in question and
+   the author of the present patches, made several good-faith attempts over the
+   years to get these patches mainlined.  The first formal submission attempt
+   was made back in 2020, multiple revision iterations were made, responding to
+   each and every nitpick from maintainers, multiple different approaches were
+   tried - but in the end a most senior Linux kernel maintainer took the
+   attitude of "screw you" toward our users, declaring that the hardware device
+   will not be supported as a matter of ideological principle.
+
+For more detailed background information and a deeper analysis of the problem,
+please read the following article:
+
+https://www.freecalypso.org/hg/freecalypso-docs/file/tip/Linux-DTR-RTS-flaw
+
+Instructions for end users
+==========================
+
+Any end user who wishes to make use of the optional boot control feature of
+FreeCalypso DUART28, or wishes to use any of our planned future FreeCalypso
+hardware devices with the same wiring must apply our DUART28C support patches
+locally to their Linux kernel - or more precisely, to their ftdi_sio driver.
+Patches are provided that apply cleanly to all mainline kernels since 5.10 (the
+first version in which a basic, much less controversial prerequisite patch was
+merged), and to some stable kernel lines going back to 4.4.y.  Please see
+LTS-versions article for a table showing which patch version goes with which
+long-term-supported versions of Linux kernel.