# HG changeset patch # User Mychaela Falconia # Date 1600236639 0 # Node ID 6d97866bad79a525adf9641402ed7b99544f55a1 # Parent 7d1df6d831e42cfcf3573c4cb5853e6a16f27215 first round of documentation for DUART28C boot control addition diff -r 7d1df6d831e4 -r 6d97866bad79 CHANGES --- a/CHANGES Wed Sep 16 03:40:51 2020 +0000 +++ b/CHANGES Wed Sep 16 06:10:39 2020 +0000 @@ -7,6 +7,9 @@ * fc-iram second program invokation mode fix: options for the second program are no longer misinterpreted as fc-iram options. +* New support for target boot control via DTR and RTS modem control outputs as + implemented on our new DUART28 adapter - see doc/DUART28-boot-control. + * ADC calibration table /sys/adccal is now supported much like various RF parameter tables: it can be decoded from binary to our own ASCII format with fc-bin2rftab, it can be compiled back into binary with fc-cal2bin, and it can diff -r 7d1df6d831e4 -r 6d97866bad79 doc/DUART28-boot-control --- /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. diff -r 7d1df6d831e4 -r 6d97866bad79 doc/Host-tools-overview --- a/doc/Host-tools-overview Wed Sep 16 03:40:51 2020 +0000 +++ b/doc/Host-tools-overview Wed Sep 16 06:10:39 2020 +0000 @@ -143,6 +143,14 @@ predate ETM, and with Mot C1xx original firmwares. It works through rvinterf. +fc-pulse-dtr This trivial utility opens a serial port, asserts DTR for 50 ms, + then negates it and exits. See the DUART28-boot-control article + for the explanation. + +fc-pulse-rts This trivial utility opens a serial port, asserts RTS for 50 ms, + then negates it and exits. See the DUART28-boot-control article + for the explanation. + fc-readcal This program attempts to read a bunch of RF calibration tables out of a running firmware through Test Mode commands: first tms 1, then rfpw 7 for each band, then rftr and ttr commands to