FreeCalypso > hg > freecalypso-tools
view doc/DUART28-boot-control @ 749:fa6fee41f06e
fc-shell help: batt documented
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Thu, 22 Oct 2020 06:17:11 +0000 |
parents | 6d97866bad79 |
children | 26daa2720bda |
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 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.