TI's primary development platform for TCS211 firmware was D-Sample - see our
D-Sample article for explanation of our current limited support for that target
in FC Magnetite - but they also had another platform called Leonardo.  The
primary difference is the RF section: D-Sample had Clara RF (the one for which
we lack support), whereas Leonardo was TI's reference platform for Rita RF and
for the complete Calypso+Iota+Rita chipset.  Another major difference is that
D-Sample was a single stable platform, whereas Leonardo was made in a
bewildering assortment of different variants.

We (FreeCalypso core team) never succeeded in getting our hands on a real
TI-made Leonardo board of any variant, but we do have a Leonardo build target
in FC Magnetite for two reasons:

1) Adding this build target was trivial: our starting hw target for which we
   got our original starting-point fw was Openmoko's embedded GSM/GPRS modem,
   and that modem is a very close derivative of Leonardo.  The only firmware-
   affecting diff between Leonardo and OM's modem is FIC/OM's reshuffling of
   TSPACT control lines for their triband RFFE; producing a build configuration
   with these TSPACT control signals put back into their original Leonardo
   arrangement became trivial once our reconstruction of tpudrv12.c from
   disassembly of tpudrv12.obj reached production quality.

2) At the end of 2019 we discovered a certain modem module which we call Tango,
   and this Tango module is essentially a mass-produced version of TI's Leonardo
   core.  Tango is just the core of Leonardo, without any peripherals, thus a
   proper fw build target for any given Tango-based platform is going to be a
   little different from Leonardo in terms of GPIO and other peripheral config
   (see our tangomdm target), but initially we ran our Magnetite-Leonardo fw
   (built for target leonardo) on our Caramel board - it runs just fine except
   for GPIO config being slightly wrong, leaving a few GPIO lines floating.

Supported Leonardo variants
===========================

RF bands: there were several Leonardo variants with full quadband RF using Epcos
M034F FEM, and there were several more variants with artifically restricted RF,
using a dual-band/single-region FEM and supporting only the two EU bands.  The
two versions should be firmware-compatible according to our available schematics
(the same TSPACT signals are used for Tx control), thus our Magnetite-Leonardo
fw should run on any Leonardo variant that matches any of our known schematic
versions at least in the principal aspects.

Flash memory: our Magnetite-Leonardo fw supports the following flash chips for
FFS:

4 MiB: Fujitsu MBM29DL320FB or MBM29DL320FT
8 MiB: Am29DL640G or its Fujitsu equivalent, or any MCP containing this flash
16 MiB: Spansion PL129J or its AMD predecessor, second bank on nCS2

If anyone finds a Leonardo variant with some other flash, it may not be
supported out of the box - but our included FFS configs for the Leonardo target
come directly from TI's original TCS211 version (it is highly unlikely that OM
changed anything other than adding their Samsung flash), thus we support
everything that TI's own TCS211 supported out of the box.

Memory size limits
==================

The linker script template we use for target leonardo has memory region size
limits set as follows: 8 MiB of flash, 2 MiB of XRAM and 512 KiB of IRAM.  If
you are working with a Leonardo or Leonardo-compatible board that has smaller
flash or XRAM, or has a Calypso Lite chip with only 256 KiB of IRAM, then you
have to manually ensure that you stay within your actual memory limits, as you
won't get a failing link unless you exceed the larger linker script limits.

If you are building a modem-only fw configuration (l1reconst or hybrid), it
will fit into under 3 MiB of flash (fitting into a 4 MiB flash chip together
with FFS), 512 KiB of XRAM and 256 KiB of IRAM, so you are safe unless you are
going to add a lot of your own code or data space.  But if you are going to
build a UI-enabled fw config (2092 or hybrid-ui), then you will need at least
an 8 MiB flash chip (won't fit into a 4 MiB chip together with FFS) and at least
1 MiB of XRAM.  So far all of our configs fit into 256 KiB of IRAM.

Different Calypso chip versions
===============================

If you specify the build target as just leonardo, your fw will be configured
and built for the leonardo-dsp36 target.  If you actually need leonardo-c05b or
leonardo-dsp34 because your board has an older Calypso chip version on it, then
you will need to specify the build target as just stated - see the
Calypso-version-override article.

Calypso GPIO 2 configuration
============================

On TI's C-Sample and D-Sample boards Calypso GPIO 2 is wired to serve as the DCD
output for the MODEM UART (Calypso device as DCE), and our FC Magnetite firmware
drives it as such on D-Sample, FCDEV3B and GTM900 targets.  But this same config
does NOT apply to Leonardo: on the latter boards GPIO 2 is wired in a way that
requires it to be configured as an input to Calypso, not an output.

TI's TCS211 firmware had this Leonardo GPIO 2 situation handled in a very
bizarre manner: the main GPIO init code in AI_InitIOConfig() in armio.c made no
differentiation between D-Sample and Leonardo and configured GPIO 2 as an
output, then the init code in uartfax.c did the same setup again, but at the
end of the Init_Serial_Flows() function in the init module (which we only got
as init.obj, with init.c censored out) they inserted a bit of code that switches
GPIO 2 to be an input.  What a mess.

Our handling of this GPIO 2 situation in FC Magnetite is much cleaner: we have
put an #ifndef CONFIG_TARGET_LEONARDO around the AI_ConfigBitAsOutput(2) call
in AI_InitIOConfig() so this GPIO line never becomes an output in the first
place, and our targets/leonardo.h configuration header defines
UARTFAX_CLASSIC_DTR_DCD to 0 on this target, disabling that code in the
uartfax.c driver.

This peculiar GPIO 2 situation applies only to real Leonardo boards, not to
Tango modems: a custom design using a Tango module can use this GPIO line for
anything, but on Caramel boards it drives RS-232 DCD like on D-Sample and thus
should be configured as a Calypso output.

Other GPIO and multifunction pins
=================================

Our Magnetite-Leonardo fw is unchanged from TI's TCS211 original in that GPIO0,
TSPDI/GPIO4 and DSR_MODEM/LPG pins are left configured as inputs, even though
the schematics we've got show GPIO0 as an output and the other two pins as
unconnected, in which case they should also be configured as outputs in order
to not float.  We are leaving this aspect unchanged currently because this
Magnetite-Leonardo fw build target is really just a reference for practically
non-existent hw, and given the unknown of what other Leonardo variants may have
existed once beyond our known schematics, we would rather leave a few floating
inputs than risk causing a driver conflict on some unknown board.

In the case of Tango these 3 just-mentioned Calypso signals are contained inside
the module (not brought out), and it is currently unknown if they are simply
unconnected or if perhaps they are tied to either GND or V-IO inside the module.
The Tango manuf's original fw leaves these signals in their power-up default as
Calypso inputs, hence we do the same currently in order to not risk causing a
short.  At some later time when our finances allow doing so, we may send a
sacrificial Tango module for destructive PCB reverse eng and see what is really
done with these Calypso signals - if they are really unconnected, then we can
change the code to switch them to outputs, just like we have done for the
gtamodem target where the original manuf's official fw also left a bunch of
floating inputs.