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.