annotate doc/Leonardo-target @ 696:2d310cfce661

targets/*.h: sync with Tourmaline: new preprocessor symbols CONFIG_TARGET_LEO_RFFE and ABB_SLEEP_RESTRICTION
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 09 Jun 2021 17:05:01 +0000
parents edaceb78719a
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
626
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 TI's primary development platform for TCS211 firmware was D-Sample - see our
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 D-Sample article for explanation of our current limited support for that target
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 in FC Magnetite - but they also had another platform called Leonardo. The
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 primary difference is the RF section: D-Sample had Clara RF (the one for which
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 we lack support), whereas Leonardo was TI's reference platform for Rita RF and
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 for the complete Calypso+Iota+Rita chipset. Another major difference is that
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 D-Sample was a single stable platform, whereas Leonardo was made in a
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 bewildering assortment of different variants.
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 We (FreeCalypso core team) never succeeded in getting our hands on a real
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 TI-made Leonardo board of any variant, but we do have a Leonardo build target
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 in FC Magnetite for two reasons:
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 1) Adding this build target was trivial: our starting hw target for which we
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 got our original starting-point fw was Openmoko's embedded GSM/GPRS modem,
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 and that modem is a very close derivative of Leonardo. The only firmware-
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 affecting diff between Leonardo and OM's modem is FIC/OM's reshuffling of
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 TSPACT control lines for their triband RFFE; producing a build configuration
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 with these TSPACT control signals put back into their original Leonardo
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 arrangement became trivial once our reconstruction of tpudrv12.c from
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 disassembly of tpudrv12.obj reached production quality.
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22
634
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
23 2) At the end of 2019 we discovered a certain modem module which we call Tango,
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
24 and this Tango module is essentially a mass-produced version of TI's Leonardo
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
25 core. Tango is just the core of Leonardo, without any peripherals, thus a
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
26 proper fw build target for any given Tango-based platform is going to be a
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
27 little different from Leonardo in terms of GPIO and other peripheral config
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
28 (see our tangomdm target), but initially we ran our Magnetite-Leonardo fw
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
29 (built for target leonardo) on our Caramel board - it runs just fine except
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
30 for GPIO config being slightly wrong, leaving a few GPIO lines floating.
626
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 Supported Leonardo variants
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 ===========================
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 RF bands: there were several Leonardo variants with full quadband RF using Epcos
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 M034F FEM, and there were several more variants with artifically restricted RF,
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 using a dual-band/single-region FEM and supporting only the two EU bands. The
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 two versions should be firmware-compatible according to our available schematics
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 (the same TSPACT signals are used for Tx control), thus our Magnetite-Leonardo
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 fw should run on any Leonardo variant that matches any of our known schematic
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 versions at least in the principal aspects.
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 Flash memory: our Magnetite-Leonardo fw supports the following flash chips for
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 FFS:
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 4 MiB: Fujitsu MBM29DL320FB or MBM29DL320FT
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 8 MiB: Am29DL640G or its Fujitsu equivalent, or any MCP containing this flash
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 16 MiB: Spansion PL129J or its AMD predecessor, second bank on nCS2
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 If anyone finds a Leonardo variant with some other flash, it may not be
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 supported out of the box - but our included FFS configs for the Leonardo target
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 come directly from TI's original TCS211 version (it is highly unlikely that OM
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 changed anything other than adding their Samsung flash), thus we support
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 everything that TI's own TCS211 supported out of the box.
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 Memory size limits
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 ==================
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 The linker script template we use for target leonardo has memory region size
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 limits set as follows: 8 MiB of flash, 2 MiB of XRAM and 512 KiB of IRAM. If
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 you are working with a Leonardo or Leonardo-compatible board that has smaller
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 flash or XRAM, or has a Calypso Lite chip with only 256 KiB of IRAM, then you
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 have to manually ensure that you stay within your actual memory limits, as you
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 won't get a failing link unless you exceed the larger linker script limits.
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 If you are building a modem-only fw configuration (l1reconst or hybrid), it
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 will fit into under 3 MiB of flash (fitting into a 4 MiB flash chip together
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 with FFS), 512 KiB of XRAM and 256 KiB of IRAM, so you are safe unless you are
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 going to add a lot of your own code or data space. But if you are going to
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 build a UI-enabled fw config (2092 or hybrid-ui), then you will need at least
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 an 8 MiB flash chip (won't fit into a 4 MiB chip together with FFS) and at least
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 1 MiB of XRAM. So far all of our configs fit into 256 KiB of IRAM.
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 Different Calypso chip versions
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 ===============================
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 If you specify the build target as just leonardo, your fw will be configured
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 and built for the leonardo-dsp36 target. If you actually need leonardo-c05b or
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 leonardo-dsp34 because your board has an older Calypso chip version on it, then
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 you will need to specify the build target as just stated - see the
41238a8e140c Leonardo target documented
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 Calypso-version-override article.
630
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
82
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
83 Calypso GPIO 2 configuration
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
84 ============================
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
85
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
86 On TI's C-Sample and D-Sample boards Calypso GPIO 2 is wired to serve as the DCD
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
87 output for the MODEM UART (Calypso device as DCE), and our FC Magnetite firmware
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
88 drives it as such on D-Sample, FCDEV3B and GTM900 targets. But this same config
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
89 does NOT apply to Leonardo: on the latter boards GPIO 2 is wired in a way that
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
90 requires it to be configured as an input to Calypso, not an output.
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
91
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
92 TI's TCS211 firmware had this Leonardo GPIO 2 situation handled in a very
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
93 bizarre manner: the main GPIO init code in AI_InitIOConfig() in armio.c made no
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
94 differentiation between D-Sample and Leonardo and configured GPIO 2 as an
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
95 output, then the init code in uartfax.c did the same setup again, but at the
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
96 end of the Init_Serial_Flows() function in the init module (which we only got
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
97 as init.obj, with init.c censored out) they inserted a bit of code that switches
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
98 GPIO 2 to be an input. What a mess.
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
99
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
100 Our handling of this GPIO 2 situation in FC Magnetite is much cleaner: we have
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
101 put an #ifndef CONFIG_TARGET_LEONARDO around the AI_ConfigBitAsOutput(2) call
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
102 in AI_InitIOConfig() so this GPIO line never becomes an output in the first
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
103 place, and our targets/leonardo.h configuration header defines
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
104 UARTFAX_CLASSIC_DTR_DCD to 0 on this target, disabling that code in the
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
105 uartfax.c driver.
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
106
634
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
107 This peculiar GPIO 2 situation applies only to real Leonardo boards, not to
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
108 Tango modems: a custom design using a Tango module can use this GPIO line for
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
109 anything, but on Caramel boards it drives RS-232 DCD like on D-Sample and thus
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
110 should be configured as a Calypso output.
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
111
630
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
112 Other GPIO and multifunction pins
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
113 =================================
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
114
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
115 Our Magnetite-Leonardo fw is unchanged from TI's TCS211 original in that GPIO0,
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
116 TSPDI/GPIO4 and DSR_MODEM/LPG pins are left configured as inputs, even though
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
117 the schematics we've got show GPIO0 as an output and the other two pins as
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
118 unconnected, in which case they should also be configured as outputs in order
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
119 to not float. We are leaving this aspect unchanged currently because this
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
120 Magnetite-Leonardo fw build target is really just a reference for practically
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
121 non-existent hw, and given the unknown of what other Leonardo variants may have
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
122 existed once beyond our known schematics, we would rather leave a few floating
b639f7ab0007 Leonardo GPIO 2 fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 626
diff changeset
123 inputs than risk causing a driver conflict on some unknown board.
634
6edd9be81b94 doc/Leonardo-target: update for Tango and Caramel
Mychaela Falconia <falcon@freecalypso.org>
parents: 630
diff changeset
124
678
edaceb78719a doc/Leonardo-target: Tango unused Calypso signals update
Mychaela Falconia <falcon@freecalypso.org>
parents: 634
diff changeset
125 In the case of Tango these 3 just-mentioned Calypso signals (as well as
edaceb78719a doc/Leonardo-target: Tango unused Calypso signals update
Mychaela Falconia <falcon@freecalypso.org>
parents: 634
diff changeset
126 BCLKX/GPIO6) have been confirmed to be unconnected at their Calypso ball pads
edaceb78719a doc/Leonardo-target: Tango unused Calypso signals update
Mychaela Falconia <falcon@freecalypso.org>
parents: 634
diff changeset
127 (not brought out externally, not used internally for anything, not tied or
edaceb78719a doc/Leonardo-target: Tango unused Calypso signals update
Mychaela Falconia <falcon@freecalypso.org>
parents: 634
diff changeset
128 pulled to either GND or V-IO), thus we configure them as dummy outputs,
edaceb78719a doc/Leonardo-target: Tango unused Calypso signals update
Mychaela Falconia <falcon@freecalypso.org>
parents: 634
diff changeset
129 eliminating floating inputs.