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.