FreeCalypso > hg > freecalypso-tools

annotate doc/DUART28-boot-control @ 927:4e243402f453

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
rvinterf/lowlevel: use libprint for backslash-escape output
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 23 May 2023 03:59:42 +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.