# HG changeset patch # User Mychaela Falconia # Date 1702283089 0 # Node ID cfe0a9b081eced408fa64a7fce0c052d2444fba6 # Parent 00a3400668db8b6d91440eeb14ce801d32beedf0 add README diff -r 00a3400668db -r cfe0a9b081ec README --- /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.