FreeCalypso > hg > fc-magnetite

comparison doc/Tango-pinmux @ 679:52ee171ff5e4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Tango-pinmux: definitions laid down
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 24 Jun 2020 18:46:25 +0000
parents
children
comparison
equal deleted inserted replaced
678:edaceb78719a 679:52ee171ff5e4
1 FreeCalypso Tango is a Calypso core module with the special quality of having
2 many Calypso signals brought out on the user interface connector. Out of the
3 great many Calypso signals that are brought out, the following 8 pins are
4 subject to functional multiplexing concerns:
5
6 GPIO1
7 GPIO2
8 GPIO3
9 RESET_OUT/GPIO7
10 MCSI_TXD/GPIO9
11 MCSI_RXD/GPIO10
12 MCSI_CLK/GPIO11
13 MCSI_FSYNCH/GPIO12
14
15 All 8 are capable of functioning as GPIOs, meaning that a Tango-based custom
16 application board designer can use them for whatever purpose they like, but
17 some of them can also be configured as dedicated Calypso peripheral pins,
18 particularly MCSI. Others (GPIO1-3) have software-defined conventional
19 functions based on long-standing tradition.
20
21 The special complication that arises for our firmware with regard to these GPIO
22 and multifunction pins is that it is not our place as the firmware vendor to
23 dictate to our potential customers how they should wire these pins on their
24 boards. Instead an FC Tango customer should be able to wire up their board as
25 their application calls for, subject to constraints imposed by hardware (not by
26 firmware!), and our standard fw needs to work with every reasonable possibility
27 for user wiring of our GPIO and multifunction pins. The following practical
28 cases need to be addressed:
29
30 * If a customer chooses to use any of our GPIOs as an input, feeding some
31 external output to it, there needs to be a way to tell our fw to leave that GPIO
32 as an input and not switch it to an output.
33
34 * Conversely, if a given GPIO or multifunction pin is unused or not needed in a
35 given application, the app board designer should have the freedom to either tie
36 it off or leave it unconnected. If some of our GPIO or multifunction pins are
37 left unconnected, this fact needs to be communicated to our fw so it can
38 configure them as dummy outputs, preventing floating inputs.
39
40 * Some applications will use MCSI, while others won't. If a given application
41 does not use MCSI, the 4 pins (or any subset of them) can be used as GPIOs,
42 either inputs or outputs, or the unused pins may be left unconnected.
43
44 * GPIO3 is traditionally defined (by conventions going back to TI) as DTR input
45 - but not every application will have a sensible DTR signal to feed to this pin.
46 If there is no DTR signal in a given application, the app board designer should
47 be able to either use GPIO3 for some unrelated purpose, or leave it unconnected.
48
49 * GPIO2 is similarly defined as DCD output by the same traditional conventions.
50 Because it is an output from Calypso, it can be simply ignored and left
51 unconnected if it is not needed - but a user should also be able to use the GPIO
52 for unrelated purposes.
53
54 * There exist several historical conventional functions for GPIO1 output:
55 loudspeaker control (D-Sample, Leonardo, FCDEV3B), Openmoko's application
56 processor wake-up signal, or RI modem control output. We allow any of these
57 options, plus other arbitrary uses.
58
59 FreeCalypso solution
60 ====================
61
62 Our solution for firmware build target tangomdm (standard shipping fw for Tango
63 modems) is that our fw will look on boot for a file in FFS named
64 /etc/tango-pinmux; it will be a binary file of 4 bytes, defining pin
65 multiplexing configuration as follows:
66
67 Byte 0: GPIO1 config
68
69 The following values are defined:
70
71 0x00: GPIO1 is left as an input from power-up
72 0x80: GPIO1 is switched to an output, initial value 0
73 0x81: GPIO1 is switched to an output, initial value 1
74 0x82: GPIO1 is wake-up output per Openmoko GTA01/02 convention
75 0x83: GPIO1 is RI output
76
77 Byte 1: GPIO2 and GPIO3 config
78
79 Bit 7: if 1, GPIO3 is DTR input, other bits in this nibble ignored
80 if 0, GPIO3 is a "generic" GPIO (undefined function) per bits 5 and 4
81 Bit 5: if 1, GPIO3 is an output, otherwise it's an input
82 Bit 4: initial output value if GPIO3 is an output
83
84 Bit 3: if 1, GPIO2 is DCD output, other bits in this nibble ignored
85 if 0, GPIO2 is a "generic" GPIO (undefined function) per bits 1 and 0
86 Bit 1: if 1, GPIO2 is an output, otherwise it's an input
87 Bit 0: initial output value if GPIO2 is a generic (not DCD) output
88
89 Byte 2: Peripheral pin mux config
90
91 Bit 7: if 0, MCSI pins retain their default power-up functions
92 if 1, MCSI pins are switched to being GPIOs
93
94 Bit 3: if 0, RESET_OUT pin retains its default power-up function
95 if 1, RESET_OUT pin is switched to being GPIO7
96 Bit 1: if 1, GPIO7 is an output, otherwise it's an input
97 bit 0: initial output value of GPIO7
98
99 Byte 3: I/O config of MCSI pins turned into GPIOs
100
101 This byte will be considered only if Byte 2 Bit 7 is set to 1, and will be
102 ignored otherwise.
103
104 Bit 7: GPIO12 direction: 1 means output, 0 means input
105 Bit 6: GPIO11 direction: 1 means output, 0 means input
106 Bit 5: GPIO10 direction: 1 means output, 0 means input
107 Bit 4: GPIO9 direction: 1 means output, 0 means input
108
109 Bit 3: GPIO12 initial output value
110 Bit 2: GPIO11 initial output value
111 Bit 1: GPIO10 initial output value
112 Bit 0: GPIO9 initial output value
113
114 If the /etc/tango-pinmux file is missing, the effect will be the same as if all
115 four bytes are equal to zero: GPIO1-3 will be functionally-undefined inputs,
116 RESET_OUT/GPIO7 will be left as RESET_OUT from power-up, and all 4 MCSI pins
117 will be likewise left in their power-up default MCSI function.
118
119 Any GPIO that is configured as an input can be read with AT+IOR, and any GPIO
120 that is configured as a generic (not built-in function) output can be set with
121 AT+IOW.
122
123 Other GPIO pins
124 ===============
125
126 Calypso pins GPIO0, TSPDI/GPIO4, BCLKX/GPIO6, MCUEN1/GPIO8 and MCUEN2/GPIO13
127 are not brought out externally on Tango modules, thus they don't need to be
128 considered. Our fw configures them as dummy outputs to prevent floating inputs.