--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Tango-pinmux	Wed Jun 24 18:46:25 2020 +0000
@@ -0,0 +1,128 @@
+FreeCalypso Tango is a Calypso core module with the special quality of having
+many Calypso signals brought out on the user interface connector.  Out of the
+great many Calypso signals that are brought out, the following 8 pins are
+subject to functional multiplexing concerns:
+
+GPIO1
+GPIO2
+GPIO3
+RESET_OUT/GPIO7
+MCSI_TXD/GPIO9
+MCSI_RXD/GPIO10
+MCSI_CLK/GPIO11
+MCSI_FSYNCH/GPIO12
+
+All 8 are capable of functioning as GPIOs, meaning that a Tango-based custom
+application board designer can use them for whatever purpose they like, but
+some of them can also be configured as dedicated Calypso peripheral pins,
+particularly MCSI.  Others (GPIO1-3) have software-defined conventional
+functions based on long-standing tradition.
+
+The special complication that arises for our firmware with regard to these GPIO
+and multifunction pins is that it is not our place as the firmware vendor to
+dictate to our potential customers how they should wire these pins on their
+boards.  Instead an FC Tango customer should be able to wire up their board as
+their application calls for, subject to constraints imposed by hardware (not by
+firmware!), and our standard fw needs to work with every reasonable possibility
+for user wiring of our GPIO and multifunction pins.  The following practical
+cases need to be addressed:
+
+* If a customer chooses to use any of our GPIOs as an input, feeding some
+external output to it, there needs to be a way to tell our fw to leave that GPIO
+as an input and not switch it to an output.
+
+* Conversely, if a given GPIO or multifunction pin is unused or not needed in a
+given application, the app board designer should have the freedom to either tie
+it off or leave it unconnected.  If some of our GPIO or multifunction pins are
+left unconnected, this fact needs to be communicated to our fw so it can
+configure them as dummy outputs, preventing floating inputs.
+
+* Some applications will use MCSI, while others won't.  If a given application
+does not use MCSI, the 4 pins (or any subset of them) can be used as GPIOs,
+either inputs or outputs, or the unused pins may be left unconnected.
+
+* GPIO3 is traditionally defined (by conventions going back to TI) as DTR input
+- but not every application will have a sensible DTR signal to feed to this pin.
+If there is no DTR signal in a given application, the app board designer should
+be able to either use GPIO3 for some unrelated purpose, or leave it unconnected.
+
+* GPIO2 is similarly defined as DCD output by the same traditional conventions.
+Because it is an output from Calypso, it can be simply ignored and left
+unconnected if it is not needed - but a user should also be able to use the GPIO
+for unrelated purposes.
+
+* There exist several historical conventional functions for GPIO1 output:
+loudspeaker control (D-Sample, Leonardo, FCDEV3B), Openmoko's application
+processor wake-up signal, or RI modem control output.  We allow any of these
+options, plus other arbitrary uses.
+
+FreeCalypso solution
+====================
+
+Our solution for firmware build target tangomdm (standard shipping fw for Tango
+modems) is that our fw will look on boot for a file in FFS named
+/etc/tango-pinmux; it will be a binary file of 4 bytes, defining pin
+multiplexing configuration as follows:
+
+Byte 0: GPIO1 config
+
+The following values are defined:
+
+0x00: GPIO1 is left as an input from power-up
+0x80: GPIO1 is switched to an output, initial value 0
+0x81: GPIO1 is switched to an output, initial value 1
+0x82: GPIO1 is wake-up output per Openmoko GTA01/02 convention
+0x83: GPIO1 is RI output
+
+Byte 1: GPIO2 and GPIO3 config
+
+Bit 7: if 1, GPIO3 is DTR input, other bits in this nibble ignored
+       if 0, GPIO3 is a "generic" GPIO (undefined function) per bits 5 and 4
+Bit 5: if 1, GPIO3 is an output, otherwise it's an input
+Bit 4: initial output value if GPIO3 is an output
+
+Bit 3: if 1, GPIO2 is DCD output, other bits in this nibble ignored
+       if 0, GPIO2 is a "generic" GPIO (undefined function) per bits 1 and 0
+Bit 1: if 1, GPIO2 is an output, otherwise it's an input
+Bit 0: initial output value if GPIO2 is a generic (not DCD) output
+
+Byte 2: Peripheral pin mux config
+
+Bit 7: if 0, MCSI pins retain their default power-up functions
+       if 1, MCSI pins are switched to being GPIOs
+
+Bit 3: if 0, RESET_OUT pin retains its default power-up function
+       if 1, RESET_OUT pin is switched to being GPIO7
+Bit 1: if 1, GPIO7 is an output, otherwise it's an input
+bit 0: initial output value of GPIO7
+
+Byte 3: I/O config of MCSI pins turned into GPIOs
+
+This byte will be considered only if Byte 2 Bit 7 is set to 1, and will be
+ignored otherwise.
+
+Bit 7: GPIO12 direction: 1 means output, 0 means input
+Bit 6: GPIO11 direction: 1 means output, 0 means input
+Bit 5: GPIO10 direction: 1 means output, 0 means input
+Bit 4: GPIO9 direction: 1 means output, 0 means input
+
+Bit 3: GPIO12 initial output value
+Bit 2: GPIO11 initial output value
+Bit 1: GPIO10 initial output value
+Bit 0: GPIO9 initial output value
+
+If the /etc/tango-pinmux file is missing, the effect will be the same as if all
+four bytes are equal to zero: GPIO1-3 will be functionally-undefined inputs,
+RESET_OUT/GPIO7 will be left as RESET_OUT from power-up, and all 4 MCSI pins
+will be likewise left in their power-up default MCSI function.
+
+Any GPIO that is configured as an input can be read with AT+IOR, and any GPIO
+that is configured as a generic (not built-in function) output can be set with
+AT+IOW.
+
+Other GPIO pins
+===============
+
+Calypso pins GPIO0, TSPDI/GPIO4, BCLKX/GPIO6, MCUEN1/GPIO8 and MCUEN2/GPIO13
+are not brought out externally on Tango modules, thus they don't need to be
+considered.  Our fw configures them as dummy outputs to prevent floating inputs.