FreeCalypso > hg > freecalypso-tools
view doc/DUART28-boot-control @ 955:803e926e0699
doc/Pirelli-loadtools-entry: new article
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Wed, 07 Jun 2023 23:52:09 +0000 |
parents | 78101799417c |
children | 4a153059abbb |
line wrap: on
line source
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.