--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/DUART28-boot-control	Wed Sep 16 06:10:39 2020 +0000
@@ -0,0 +1,116 @@
+FreeCalypso DUART28 adapter is a new piece of hardware that became available in
+2020-09.  In principal terms it is a drop-in replacement for the PLDkit FT2232D
+adapter we've been using previously, but made specifically for working with
+Calypso targets, rather than generic.  However, in addition to providing this
+drop-in replacement for our previous solution, our DUART28 also provides one
+new optional feature: target boot control.
+
+The target boot control feature of FreeCalypso DUART28 consists of CTL1 and CTL2
+open drain outputs driven by FT2232D Channel B RTS and DTR, respectively, and
+this feature is optional in that you don't have to connect these signals: if you
+leave them unconnected, they won't do anything, and you can completely ignore
+the existence of this additional feature.  However, if you find this new feature
+useful, you can make the necessary wire connections, apply the necessary patch
+to your Linux kernel ftdi_sio driver and reprogram the EEPROM to the DUART28C
+configuration - and then you will gain the ability to control your Calypso
+board's PWON and RESET from your host computer.
+
+Hardware connections
+====================
+
+The official FreeCalypso convention is that DUART28 CTL1 output should be
+connected to PWON on the Calypso board, and CTL2 should be connected to RESET.
+However, these wire connections can be made ONLY if you are going to also apply
+the necessary patch to your Linux kernel ftdi_sio driver and reprogram the
+EEPROM to the DUART28C configuration - if you connect CTL1 and CTL2 to Calypso
+PWON and RESET without doing the other necessary steps, your setup won't work
+at all: the Calypso+Iota chipset will be held down in test reset and thus
+inoperable whenever you open Channel B ttyUSB device for regular serial
+communication.
+
+Linux kernel driver patch
+=========================
+
+FreeCalypso DUART28 adapter is based on the FT2232D chip from FTDI, and all
+FTDI-based USB-serial adapters are supported by the ftdi_sio kernel driver
+under Linux.  This driver contains a table of all supported USB IDs, and this
+table needs to be extended (meaning that the driver needs to be patched)
+whenever a new (previously unknown) USB ID needs to be supported.  The internal
+architecture of this driver and its USB ID table also allows various quirks to
+be associated with specific USB IDs, meaning that the standard behaviour of the
+driver can be modified in special ways for specific ID-distinguishable USB
+devices.
+
+The way in which we have creatively repurposed otherwise unused Channel B RTS
+and DTR outputs into PWON and RESET controls is not compatible with the standard
+unpatched ftdi_sio driver, or rather with the standard unpatched Linux tty
+serial port subsystem in general: the standard Linux tty behaviour (apparently
+stipulated by POSIX) is that whenever any given ttyUSB device is opened, its
+DTR and RTS outputs are immediately asserted, and userspace is not given any
+opportunity to intervene prior to this automatic assertion of DTR & RTS.  On our
+non-standard hardware this standard Linux behaviour would cause an unstoppable
+superdeep reset to be triggered whenever the second serial channel is opened for
+regular communication, which is clearly not acceptable.
+
+Our solution to this problem consists of a custom USB ID that makes the standard
+unpatched ftdi_sio driver not recognize our DUART28C adapter (DUART28 hardware
+with DUART28C EEPROM config) at all, and a custom patch to the ftdi_sio driver
+that teaches it to recognize our custom USB ID *and* apply a special quirk for
+it.  The quirk suppresses automatic assertion of DTR & RTS on ttyUSB device
+open, thereby giving userspace applications full control of these UART outputs
+via TIOCMBIS and TIOCMBIC ioctls.
+
+The patch has been submitted to the ftdi_sio maintainer for inclusion in
+mainline Linux, but we should not set our hopes too high: while the patch should
+be non-controversial given that it adds support for an entirely new USB ID (one
+that was officially allocated to Falconia Partners LLC by FTDI, mind you) and
+does not disrupt anything pre-existing in any way whatsoever, getting ANY kind
+of patch accepted into mainline is generally tantamount to the Seven Circles of
+Hell.  And even if we do get our patch accepted into bleeding-edge mainline
+Linux, it does not help Slackware users running older kernels without updates -
+thus serious FreeCalypso users should be prepared to apply our ftdi_sio driver
+patch locally on their own systems.
+
+The official Slackware-applicable version of the needed ftdi_sio driver patch
+can be found in our freecalypso-hwlab Hg repository.
+
+EEPROM configuration
+====================
+
+In order to make our DUART28 adapter an acceptable replacement for generic "raw"
+FT2232x adapters (or CP2105-based Sysmocom mv-uart) which are supported out of
+the box by standard unpatched ftdi_sio and cp210x drivers, we ship our DUART28
+boards with DUART28S configuration in the EEPROM, rather than DUART28C.  The S
+configuration sets the USB ID to FT2232x default of 0x0403:0x6010, which the
+standard unpatched ftdi_sio driver recognizes as a completely vanilla USB to
+dual UART adapter - but CTL outputs must be left unconnected in this
+configuration, as they cannot function correctly with this unpatched driver.
+
+If you have applied our DUART28C support patch to your ftdi_sio driver, then
+you can reprogram the EEPROM on your board into the C configuration and start
+using CTL outputs.  The necessary EEPROM config files and tools can be found in
+our freecalypso-hwlab Hg repository.
+
+Support in FC host tools
+========================
+
+If you have gone through all of the above, you get the following Calypso target
+boot control capabilities with FC host tools:
+
+* If you run any of our loadtools programs (fc-loadtool, fc-iram, fc-xram etc)
+  or rvinterf on the ttyUSB device corresponding to DUART28 Channel B, which
+  will normally be connected to Calypso IrDA UART, adding a -Prts option will
+  make the tool pulse RTS, triggering PWON, or adding a -Pdtr option will make
+  the tool pulse DTR, triggering RESET.
+
+* Standalone fc-pulse-dtr and fc-pulse-rts utilities are also provided, doing
+  the obvious.
+
+Note the -P option: prior to this DUART28C support addition, the string argument
+to the -P option (boot control name) was an arbitrary user-defined short name
+to be looked up in /opt/freecalypso/bootctrl.conf, a user-created configuration
+file directing our tools to run a user-provided external boot control command.
+The new logic is that -Pdtr and -Prts are special reserved names for the
+built-in DUART28C boot control function, whereas any other name will be looked
+up in the configuration file and the associated user-provided external command
+will be executed.