# HG changeset patch # User Mychaela Falconia # Date 1593024385 0 # Node ID 52ee171ff5e4805e49014be4e14e12f70c521be3 # Parent edaceb78719ab4bd230266210d12273c5e1b55df doc/Tango-pinmux: definitions laid down diff -r edaceb78719a -r 52ee171ff5e4 doc/Tango-pinmux --- /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.