FreeCalypso > hg > freecalypso-tools

comparison doc/DUART28-boot-control @ 737:6d97866bad79

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
first round of documentation for DUART28C boot control addition
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 16 Sep 2020 06:10:39 +0000
parents
children 26daa2720bda
comparison
equal deleted inserted replaced
736:7d1df6d831e4 737:6d97866bad79
1 FreeCalypso DUART28 adapter is a new piece of hardware that became available in
2 2020-09. In principal terms it is a drop-in replacement for the PLDkit FT2232D
3 adapter we've been using previously, but made specifically for working with
4 Calypso targets, rather than generic. However, in addition to providing this
5 drop-in replacement for our previous solution, our DUART28 also provides one
6 new optional feature: target boot control.
7
8 The target boot control feature of FreeCalypso DUART28 consists of CTL1 and CTL2
9 open drain outputs driven by FT2232D Channel B RTS and DTR, respectively, and
10 this feature is optional in that you don't have to connect these signals: if you
11 leave them unconnected, they won't do anything, and you can completely ignore
12 the existence of this additional feature. However, if you find this new feature
13 useful, you can make the necessary wire connections, apply the necessary patch
14 to your Linux kernel ftdi_sio driver and reprogram the EEPROM to the DUART28C
15 configuration - and then you will gain the ability to control your Calypso
16 board's PWON and RESET from your host computer.
17
18 Hardware connections
19 ====================
20
21 The official FreeCalypso convention is that DUART28 CTL1 output should be
22 connected to PWON on the Calypso board, and CTL2 should be connected to RESET.
23 However, these wire connections can be made ONLY if you are going to also apply
24 the necessary patch to your Linux kernel ftdi_sio driver and reprogram the
25 EEPROM to the DUART28C configuration - if you connect CTL1 and CTL2 to Calypso
26 PWON and RESET without doing the other necessary steps, your setup won't work
27 at all: the Calypso+Iota chipset will be held down in test reset and thus
28 inoperable whenever you open Channel B ttyUSB device for regular serial
29 communication.
30
31 Linux kernel driver patch
32 =========================
33
34 FreeCalypso DUART28 adapter is based on the FT2232D chip from FTDI, and all
35 FTDI-based USB-serial adapters are supported by the ftdi_sio kernel driver
36 under Linux. This driver contains a table of all supported USB IDs, and this
37 table needs to be extended (meaning that the driver needs to be patched)
38 whenever a new (previously unknown) USB ID needs to be supported. The internal
39 architecture of this driver and its USB ID table also allows various quirks to
40 be associated with specific USB IDs, meaning that the standard behaviour of the
41 driver can be modified in special ways for specific ID-distinguishable USB
42 devices.
43
44 The way in which we have creatively repurposed otherwise unused Channel B RTS
45 and DTR outputs into PWON and RESET controls is not compatible with the standard
46 unpatched ftdi_sio driver, or rather with the standard unpatched Linux tty
47 serial port subsystem in general: the standard Linux tty behaviour (apparently
48 stipulated by POSIX) is that whenever any given ttyUSB device is opened, its
49 DTR and RTS outputs are immediately asserted, and userspace is not given any
50 opportunity to intervene prior to this automatic assertion of DTR & RTS. On our
51 non-standard hardware this standard Linux behaviour would cause an unstoppable
52 superdeep reset to be triggered whenever the second serial channel is opened for
53 regular communication, which is clearly not acceptable.
54
55 Our solution to this problem consists of a custom USB ID that makes the standard
56 unpatched ftdi_sio driver not recognize our DUART28C adapter (DUART28 hardware
57 with DUART28C EEPROM config) at all, and a custom patch to the ftdi_sio driver
58 that teaches it to recognize our custom USB ID *and* apply a special quirk for
59 it. The quirk suppresses automatic assertion of DTR & RTS on ttyUSB device
60 open, thereby giving userspace applications full control of these UART outputs
61 via TIOCMBIS and TIOCMBIC ioctls.
62
63 The patch has been submitted to the ftdi_sio maintainer for inclusion in
64 mainline Linux, but we should not set our hopes too high: while the patch should
65 be non-controversial given that it adds support for an entirely new USB ID (one
66 that was officially allocated to Falconia Partners LLC by FTDI, mind you) and
67 does not disrupt anything pre-existing in any way whatsoever, getting ANY kind
68 of patch accepted into mainline is generally tantamount to the Seven Circles of
69 Hell. And even if we do get our patch accepted into bleeding-edge mainline
70 Linux, it does not help Slackware users running older kernels without updates -
71 thus serious FreeCalypso users should be prepared to apply our ftdi_sio driver
72 patch locally on their own systems.
73
74 The official Slackware-applicable version of the needed ftdi_sio driver patch
75 can be found in our freecalypso-hwlab Hg repository.
76
77 EEPROM configuration
78 ====================
79
80 In order to make our DUART28 adapter an acceptable replacement for generic "raw"
81 FT2232x adapters (or CP2105-based Sysmocom mv-uart) which are supported out of
82 the box by standard unpatched ftdi_sio and cp210x drivers, we ship our DUART28
83 boards with DUART28S configuration in the EEPROM, rather than DUART28C. The S
84 configuration sets the USB ID to FT2232x default of 0x0403:0x6010, which the
85 standard unpatched ftdi_sio driver recognizes as a completely vanilla USB to
86 dual UART adapter - but CTL outputs must be left unconnected in this
87 configuration, as they cannot function correctly with this unpatched driver.
88
89 If you have applied our DUART28C support patch to your ftdi_sio driver, then
90 you can reprogram the EEPROM on your board into the C configuration and start
91 using CTL outputs. The necessary EEPROM config files and tools can be found in
92 our freecalypso-hwlab Hg repository.
93
94 Support in FC host tools
95 ========================
96
97 If you have gone through all of the above, you get the following Calypso target
98 boot control capabilities with FC host tools:
99
100 * If you run any of our loadtools programs (fc-loadtool, fc-iram, fc-xram etc)
101 or rvinterf on the ttyUSB device corresponding to DUART28 Channel B, which
102 will normally be connected to Calypso IrDA UART, adding a -Prts option will
103 make the tool pulse RTS, triggering PWON, or adding a -Pdtr option will make
104 the tool pulse DTR, triggering RESET.
105
106 * Standalone fc-pulse-dtr and fc-pulse-rts utilities are also provided, doing
107 the obvious.
108
109 Note the -P option: prior to this DUART28C support addition, the string argument
110 to the -P option (boot control name) was an arbitrary user-defined short name
111 to be looked up in /opt/freecalypso/bootctrl.conf, a user-created configuration
112 file directing our tools to run a user-provided external boot control command.
113 The new logic is that -Pdtr and -Prts are special reserved names for the
114 built-in DUART28C boot control function, whereas any other name will be looked
115 up in the configuration file and the associated user-provided external command
116 will be executed.