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.

Programming /etc/tango-pinmux
=============================

To program the pinmux config file on a Tango module running any of our official
FreeCalypso firmware versions, you will need to use FC host tools.  Connect to
the RVTMUX debug trace and control interface (second UART) via rvinterf and
execute the following command in fc-fsio:

fwrite /etc/tango-pinmux hex "xx xx xx xx"

Replace xx placeholders inside the double quotes with the 4 hex bytes to be
programmed; the double quotes are required.

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.