FreeCalypso > hg > freecalypso-tools

annotate doc/DUART28-boot-control @ 995:74024eb17e04

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fc-loadtool help: improve language regarding 16 MiB flash chips In FC project history, 16 MiB flash originally meant Pirelli DP-L10. Then we got FCDEV3B with the same flash (our own design), but now we are discovering more Calypso devices that used such large flash, both late Calypso era (Sony Ericsson K2x0) as well as much earlier ones (FIC FLUID devices.txt file with 2004 dates, Leonardo+ rev 5). Hence we need to migrate to more generic or neutral language in associated documentation, without giving elevated status to specific examples that drove our early project history.
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 03 Dec 2023 21:11:12 +0000
parents 78101799417c
children 4a153059abbb
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
764
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
63 The first version of our DUART28C support patch was submitted to ftdi_sio
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
64 maintainer Johan Hovold in 2020-09. Minor refinements were made in late 2020-09
766
78101799417c doc/DUART28-boot-control: update for current patch situation
Mychaela Falconia <falcon@freecalypso.org>
parents: 764
diff changeset
65 into early 2020-10, but then after dragging for several more months, the
78101799417c doc/DUART28-boot-control: update for current patch situation
Mychaela Falconia <falcon@freecalypso.org>
parents: 764
diff changeset
66 maintainers essentially rejected the patch on ideological grounds, rather than
78101799417c doc/DUART28-boot-control: update for current patch situation
Mychaela Falconia <falcon@freecalypso.org>
parents: 764
diff changeset
67 any code quality issues:
737
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
764
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
69 https://lore.kernel.org/linux-serial/X8iuCXYhOBVMGvXv@localhost/T/
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
70
766
78101799417c doc/DUART28-boot-control: update for current patch situation
Mychaela Falconia <falcon@freecalypso.org>
parents: 764
diff changeset
71 For the next several decades until these maintainers retire of old age and get
78101799417c doc/DUART28-boot-control: update for current patch situation
Mychaela Falconia <falcon@freecalypso.org>
parents: 764
diff changeset
72 replaced by someone more reasonable and cooperative, our only available solution
78101799417c doc/DUART28-boot-control: update for current patch situation
Mychaela Falconia <falcon@freecalypso.org>
parents: 764
diff changeset
73 is to apply the necessary patch locally on our own systems.
764
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
74
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
75 For those FreeCalypso DUART28 users who are like the Mother, desiring to use
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
76 the boot control feature now without waiting indefinitely for Linux kernel
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
77 maintainers to get their act together, the linux-patch directory in our
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
78 freecalypso-hwlab Hg repository contains several versions of our DUART28C
26daa2720bda doc/DUART28-boot-control: update on the Linux driver patch status
Mychaela Falconia <falcon@freecalypso.org>
parents: 737
diff changeset
79 support patch that are meant to be applied locally by end users.
737
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 EEPROM configuration
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 ====================
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 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
85 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
86 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
87 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
88 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
89 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
90 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
91 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
92
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 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
94 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
95 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
96 our freecalypso-hwlab Hg repository.
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 Support in 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
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 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
102 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
103
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 * 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
105 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
106 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
107 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
108 the tool pulse DTR, triggering RESET.
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 * 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
111 the obvious.
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 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
114 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
115 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
116 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
117 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
118 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
119 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
120 will be executed.