--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Leonardo-target	Mon Dec 23 06:48:46 2019 +0000
@@ -0,0 +1,78 @@
+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) We are currently evaluating a certain third-party (non-TI) development board
+   which strongly appears to be a very close derivative of Leonardo, even closer
+   than Openmoko.  We are hoping to get one of these boards into Mother
+   Mychaela's lab some time in 2020-01, at which time we will try running our
+   Magnetite-Leonardo fw on it.
+
+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.