FreeCalypso > hg > fc-linux-patch

annotate README @ 9:824cc894e826

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