--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/TIFFS	Sun Jan 12 07:59:00 2014 +0000
@@ -0,0 +1,50 @@
+All TI GSM firmwares known to this author (FreeCalypso developer Space Falcon)
+implement some kind of flash file system, or FFS.  Several different FFS code
+implementations, and correspondingly several different on-flash data formats,
+have been used throughout the history of TI's involvement in the wireless
+terminal business.  The FFS incarnation of primary interest to the FreeCalypso
+project is the one invented by Mads Meisner-Jensen at TI in the early 2000s
+(at least according to the comments in the sources available to us), and it is
+relevant to us in the following ways:
+
+* When targeting the GSM modem in Openmoko's GTA01/02 smartphones, we need to
+  work with the original FFS from the factory (call it MokoFFS), the same FFS
+  as used by the mokoN firmwares: this FFS contains the IMEI and the RF
+  calibration values from the factory, which we most certainly don't want to go
+  without.
+
+* The Leonardo firmware semi-src which we are using as the reference for
+  building our own full source, multi-target GSM fw contains a turnkey-working
+  implementation of this very FFS, using the on-flash format in question and
+  providing run-time APIs expected by the rest of the GSM fw suite.  Following
+  the principle of ``if it ain't broke, don't fix it'', we can use this FFS not
+  only on the gtamodem target, but also on other targets, including those where
+  we would be starting from a blank state and thus have the freedom to use
+  whatever FFS we like.
+
+* The original proprietary fw on the Pirelli DP-L10 phone also happens to use
+  an FFS in the same format.  Pirelli's FFS does *not* contain the IMEI or any
+  of the RF calibration values though, and trying to reuse it directly for our
+  own FC GSM fw seems to be more trouble than benefit - so we'll probably have
+  our fw start with a blank TIFFS instead - but there is still insight to be
+  gained from in-vitro examination of captured Pirelli FFS images.
+
+Naming
+======
+
+I have previously referred to the FFS format in question as Mokopir-FFS or
+MPFFS, from "Moko" and "Pirelli".  I was originally hesitant to call it TIFFS,
+as lacking the source code, I had no way of knowing whether the FFS format and
+implementation were of TI's own invention, or something that TI licensed as a
+black box from one of their many proprietary software partners.  (I was unable
+to identify it as any well-known, industry-standard FFS format, but absence of
+evidence is not evidence of absence.)  But now that we have TI's original source
+code which implements this FFS (first the MV100-0.1.rar source, then the full
+Leonardo one), complete with comments and a HISTORY file, we know that our FFS
+was invented and implemented by someone named Mads Meisner-Jensen at TI - I'm
+guessing in the SSA group in Nice, France.
+
+I am now making a naming transition from MPFFS to TIFFS: there is really no
+link between this FFS format and the Openmoko+Pirelli duo, other than the
+happenstance of me having first encountered this FFS on these two GSM device
+brands, and the name TIFFS is more neutrally-descriptive.