FreeCalypso > hg > freecalypso-tools

annotate doc/DUART28-boot-control @ 1011:6d9b10633f10 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
etmsync Pirelli IMEI retrieval: fix poor use of printf() Bug reported by Vadim Yanitskiy <fixeria@osmocom.org>: the construct where a static-allocated string was passed to printf() without any format arguments causes newer compilers to report a security problem. Given that formatted output is not needed here, just fixed string output, change printf() to fputs(), and direct the error message to stderr while at it.
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 23 May 2024 17:29:57 +0000
parents 4a153059abbb
children
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
1009
4a153059abbb doc/DUART28-boot-control: update for fc-linux-patch and fc-usbser-tools
Mychaela Falconia <falcon@freecalypso.org>
parents: 766
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
1009
4a153059abbb doc/DUART28-boot-control: update for fc-linux-patch and fc-usbser-tools
Mychaela Falconia <falcon@freecalypso.org>
parents: 766
diff changeset
75 https://www.freecalypso.org/hg/fc-linux-patch/
737
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
1009
4a153059abbb doc/DUART28-boot-control: update for fc-linux-patch and fc-usbser-tools
Mychaela Falconia <falcon@freecalypso.org>
parents: 766
diff changeset
91 using CTL outputs. You will need to use fc-duart28-conf utility, maintained as
4a153059abbb doc/DUART28-boot-control: update for fc-linux-patch and fc-usbser-tools
Mychaela Falconia <falcon@freecalypso.org>
parents: 766
diff changeset
92 part of our fc-usbser-tools package:
4a153059abbb doc/DUART28-boot-control: update for fc-linux-patch and fc-usbser-tools
Mychaela Falconia <falcon@freecalypso.org>
parents: 766
diff changeset
93
4a153059abbb doc/DUART28-boot-control: update for fc-linux-patch and fc-usbser-tools
Mychaela Falconia <falcon@freecalypso.org>
parents: 766
diff changeset
94 https://www.freecalypso.org/pub/GSM/FreeCalypso/fc-usbser-tools-latest.tar.bz2
737
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 Support in FC host tools
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
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 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
100 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
101
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 * 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
103 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
104 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
105 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
106 the tool pulse DTR, triggering RESET.
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 * 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
109 the obvious.
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110
6d97866bad79 first round of documentation for DUART28C boot control addition
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 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
112 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
113 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
114 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
115 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
116 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
117 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
118 will be executed.