FreeCalypso > hg > fc-linux-patch

comparison README @ 7:cfe0a9b081ec

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add README
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 11 Dec 2023 08:24:49 +0000
parents
children
comparison
equal deleted inserted replaced
6:00a3400668db 7:cfe0a9b081ec
1 Patches to Linux kernel ftdi_sio driver: add support for USB device 0403:7152
2 =============================================================================
3
4 The present repository contains many different versions (made to apply against
5 different versions of Linux kernel) of the same series of patches to ftdi_sio
6 driver: adding support for a new, previously unsupported USB-serial device,
7 distinctly identified by a new, previously unsupported USB ID code. This ID
8 code (a PID out of FTDI's VID) has been officially allocated by FTDI to
9 Falconia Partners LLC.
10
11 Q: What is the physical hardware in question?
12
13 A: The one hardware device that already exists physically and requires the
14 present series of patches is the 'C' configuration of FreeCalypso DUART28
15 adapter. However, we expect to have other hardware products in the near
16 future that will have the same control signal wiring, require the same
17 special handling from the Linux kernel, share the same USB ID code and be
18 supported by the same patch.
19
20 Q: What is so special about this family of USB-serial devices?
21
22 A: All devices that may share the same USB ID code and will therefore be
23 automatically supported by the same patch have the same essential properties:
24 it is a two-channel FTDI device (FT2232D or FT2232H) with Channel A wired
25 normally (100% standard ttyUSB handling is appropriate), but special wiring
26 on Channel B. The latter channel on these devices is a hybrid UART+GPIO
27 entity: a ttyUSB device is needed (the same binary serial protocols that are
28 spoken over TxD/RxD lines on this device are also spoken over myriad other
29 standard serial ports), but this ttyUSB device needs to operate with a
30 special quirk. The quirk is that standard POSIX etc behavior for this one
31 particular ttyUSB device needs to be intentionally broken: the usual
32 automatic assertion of DTR & RTS upon ttyUSB device open MUST be suppressed
33 - but these two signals must still be controllable via explicit TIOCMBIS and
34 TIOCMBIC ioctls, issued by custom userspace tools.
35
36 Q: What behavioral changes are effected by the present series of patches to
37 Linux kernel ftdi_sio driver?
38
39 A: The only change is purely additive: USB device 0403:7152, previously
40 unsupported, becomes supported and recognized as needing the special quirk
41 described in the previous catechism. Absolutely no behavioral changes are
42 applied to anything else other than this one USB device.
43
44 Q: If the change does nothing more than add support for a new USB device, why
45 is it not mainlined?
46
47 A: I, Mychaela Nadezhda Falconia, the designer of the hardware in question and
48 the author of the present patches, made several good-faith attempts over the
49 years to get these patches mainlined. The first formal submission attempt
50 was made back in 2020, multiple revision iterations were made, responding to
51 each and every nitpick from maintainers, multiple different approaches were
52 tried - but in the end a most senior Linux kernel maintainer took the
53 attitude of "screw you" toward our users, declaring that the hardware device
54 will not be supported as a matter of ideological principle.
55
56 For more detailed background information and a deeper analysis of the problem,
57 please read the following article:
58
59 https://www.freecalypso.org/hg/freecalypso-docs/file/tip/Linux-DTR-RTS-flaw
60
61 Instructions for end users
62 ==========================
63
64 Any end user who wishes to make use of the optional boot control feature of
65 FreeCalypso DUART28, or wishes to use any of our planned future FreeCalypso
66 hardware devices with the same wiring must apply our DUART28C support patches
67 locally to their Linux kernel - or more precisely, to their ftdi_sio driver.
68 Patches are provided that apply cleanly to all mainline kernels since 5.10 (the
69 first version in which a basic, much less controversial prerequisite patch was
70 merged), and to some stable kernel lines going back to 4.4.y. Please see
71 LTS-versions article for a table showing which patch version goes with which
72 long-term-supported versions of Linux kernel.