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 first version of our DUART28C support patch was submitted to ftdi_sio
maintainer Johan Hovold in 2020-09.  Minor refinements were made in late 2020-09
into early 2020-10, but then after dragging for several more months, the
maintainers essentially rejected the patch on ideological grounds, rather than
any code quality issues:

https://lore.kernel.org/linux-serial/X8iuCXYhOBVMGvXv@localhost/T/

For the next several decades until these maintainers retire of old age and get
replaced by someone more reasonable and cooperative, our only available solution
is to apply the necessary patch locally on our own systems.

For those FreeCalypso DUART28 users who are like the Mother, desiring to use
the boot control feature now without waiting indefinitely for Linux kernel
maintainers to get their act together, the linux-patch directory in our
freecalypso-hwlab Hg repository contains several versions of our DUART28C
support patch that are meant to be applied locally by end users.

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.