FreeCalypso > hg > freecalypso-tools

annotate doc/DUART28-boot-control @ 747:efd85963ec85

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