--- a/FC-modem-family	Thu Sep 24 02:47:14 2020 +0000
+++ b/FC-modem-family	Mon Sep 28 00:48:17 2020 +0000
@@ -1,191 +1,107 @@
-I, Mother Mychaela, have a vision for a family of FreeCalypso modem products in
-different physical form factors, possibly with variations in offered
-functionality, all sharing the same fcmodem firmware build target - meaning that
-the same FreeCalypso fw built for the fcmodem target (a proposed successor to
-the current fcdev3b build target) will run on all FC modem hw products,
-requiring some commonalities across the entire product family but also
-supporting some variations.  The following design constraints are hereby being
-laid down in order to make this common fcmodem firmware possible:
-
-* All FC modem products will be either triband or quadband: triband if the
-  current Openmoko-based RFFE is kept as is (the safer route with less effort
-  and design labor cost) or quadband if the customer commissioning a modem
-  product is more adventurous and willing to pay more and take greater risks in
-  order to get full quadband capability.  Please refer to the Quadband-ideas
-  article for further details.
-
-* Flash chip type autodetection in both fc-loadtool and firmware FFS driver code
-  allows different flash chip types to be used depending on business needs,
-  parts availability and the available physical space on the PCB.  Flash
-  capacity can range from 4 MiB (minimum fw requirement) to 16 MiB (maximum
-  Calypso addressing capability); if a 16 MiB flash chip with two 8 MiB chip
-  select banks is used, then the second bank must be on nCS2 (like on FCDEV3B),
-  not on any other Calypso chip select.
-
-* External RAM (XRAM) capacity can range from 512 KiB (minimum fw requirement)
-  to 8 MiB (maximum Calypso addressing capability), but it will always be on
-  nCS1, not on any other Calypso chip select.
-
-* The extra logic voltage level translating buffer IC that was introduced on
-  FCDEV3B V2 in order to make flash reset timing compatible with S71PL129N flash
-  may or may not be included.  The Mother's preference is to include it when
-  possible in order to increase the repertoire of usable flash chips, but if a
-  given design allows no PCB space for this extra little IC, then it will be
-  acceptable to go back to driving the flash reset line with FDP and require
-  the use of some flash chip other than S71PL129N - if the same footprint needs
-  to be kept and/or maximum flash and RAM capacity is desired, S71PL129J can be
-  used instead.
-
-MCSI
-====
+The very first FreeCalypso hardware product named FCDEV3B was conceived in 2015
+and physically produced in the first version in 2017, with the final all-bugs-
+fixed version produced in early 2019.  FCDEV3B was conceived to fulfill an
+internal project need: to replace no longer available and quite inconvenient
+Openmoko hardware, and to provide a platform for empirically learning those
+parts of TI's chipset+fw solution which were previously elusive.  The '3B' at
+the end of FCDEV3B board name stands for triband, which was a deviation from
+the Mother's original desires: ever since I first found TI's Leonardo schematics
+back in 2011, I had always wanted to make all of my FreeCalypso hw designs fully
+quadband, following TI's original Leonardo+ quadband reference design.  But in
+2015 we lacked the necessary know-how to recreate TI's quadband Leonardo from
+schematics alone, whereas for Openmoko's triband version we had not only
+schematics, but also the complete PCB layout - thus we took the only course of
+action that was viable at that time, and produced our FCDEV3B based on
+Openmoko's version of the Calypso modem.
 
-It is envisioned that most FC modem products will provide a digital voice
-interface via MCSI as a major feature, but some may not.  If a given product
-does feature MCSI, pull-down resistors for MCSI_CLK and MCSI_FSYNCH will need
-to be included on the modem module itself, so that the user always sees them as
-non-floating outputs from the modem.  MCSI_RXD will be a pure input without
-on-board pull-up or pull-down resistors, i.e., the user will be responsible for
-tying it off or pulling it to a stable logic level if it is unused.
-
-However, if a given product does not feature MCSI, then it will be an unwelcome
-burden to require extra pull-down resistors on the PCB, hence a different
-provision is planned.  If and when we ever produce a FreeCalypso modem without
-MCSI, we will program a /etc/fc-pinmux file in FFS telling our fcmodem firmware
-to switch the MCSI pins into GPIO mode and to drive all 4 of them as dummy
-outputs, eliminating floating I/O pins without any effort from the hardware
-side.
-
-Why would a FreeCalypso modem product not feature MCSI?  Two use cases are
-envisioned here:
-
-* The new GTA02-like smartphone motherboard thought experiment - see the
-  corresponding section at the end of this article;
+At the same time when our first FCDEV3B boards were being produced and debugged,
+there was talk about producing a derivative version that would be packaged as a
+component to be integrated into other people's systems and projects, as opposed
+to a standalone development board for use on a lab bench.  I also did not feel
+like staying triband forever, and the thought of a future quadband successor was
+on my mind even as FCDEV3B was being designed.  Thus there was an intent to have
+a family of FreeCalypso modem products, eventually evolving from triband to
+quadband, and being made in different form factors for different use cases.
+But none of these ideas ever came to fruition because no one ever funded any of
+them.
 
-* If we ever produce a FreeCalypso modem in the form factor of a USB dongle for
-  laptops, it would be very easy to incorporate an FT2232x adapter presenting
-  both Calypso UARTs to the USB host, but adding a USB-to-MCSI bridge would
-  entail much greater complexity, hence it may make sense to omit MCSI for this
-  product and instead provide an analog headset jack for voice calls.
-
-GPIO
-====
-
-Our firmware configures Calypso GPIO 3 as an input; GPIOs 0-2 and those
-multifunction pins which are unused and configured as GPIOs (TSPDI/IO4,
-BCLKX/IO6, MCUEN1/IO8 and MCUEN2/IO13) are configured as outputs.  Board wiring
-must be compatible with these directions: those pins which our fw drives as
-outputs can be simply left unconnected, while GPIO 3 needs to be sensibly driven
-or tied off as explained below.
-
-Openmoko's modem puts out an application processor wakeup signal (asserted by
-the fw when the modem needs to send something to the host but is blocked by CTS
-being held high) on GPIO 1.  In order to have full feature parity, our FC modems
-will provide an equivalent signal as well, but we are moving it to GPIO 0
-because in FreeCalypso GPIO 1 is already taken for the loudspeaker control
-signal like on TI's D-Sample and Leonardo boards.  Our firmware's complete GPIO
-usage thus becomes:
+The situation changed drastically with the discovery of already existing Tango
+modem modules, discovery that was made in December of 2019 and fully accepted
+as the new reality over the course of 2020.  The newly discovered Tango modem
+module is essentially a mass-produced version of TI's Leonardo+ quadband
+reference design, and it is a very good module, even more capable than what we
+would have produced if someone had funded our ideas in the 2017 to 2019 period.
 
-GPIO0: application processor wakeup signal
-GPIO1: loudspeaker amplifier on/off control
-GPIO2: DCD modem control output
-GPIO3: DTR modem control input
-all others: dummy outputs
-
-Because GPIO3/DTR is an input, it needs to be either sensibly driven or tied
-off.  On our current FCDEV3B this line has a 100 kOhm pull-down resistor to GND,
-but it is not accessible to the user in any way - this design aspect was copied
-from TI's Leonardo board before I thought better.  Most of our future FC modem
-products are planned to have DTR as a user input signal (which the user can tie
-off if it is not used or needed in a given application), but if there is no DTR
-user input signal on a given modem product, then GPIO3 will be grounded inside
-the modem to keep the firmware happy.
-
-Calypso's unused DSR_MODEM/LPG pin was left unconnected in Openmoko's version
-but on our FCDEV3B it is tied to GND on the board.  Future FC modem family
-boards will also need to have this pin tied to GND: our firmware leaves this
-pin in its default power-up config of DSR_MODEM input and does not change it to
-LPG output, thus leaving it unconnected would cause it to float.
+In this new Tango reality it makes absolutely no business sense to produce any
+new FreeCalypso modem modules, so instead we decided on a different and quite
+novel course of action: we are officially adopting this already existing Tango
+module into our FreeCalypso family by way of rebranding - we are going to resell
+these modules as FreeCalypso Tango, flashed with our FreeCalypso firmware and
+differentiated from non-FC-sourced modules with a sticker bearing our trademark.
+Our rebranded and reflashed FC Tango modules are expected to become available
+in December of 2020.
 
-Extreme case: a new GTA02-like smartphone motherboard
-=====================================================
-
-A rather extreme thought-experiment test case for the FC modem family idea
-presented in this article is this thought: suppose we wanted to produce a new
-GTA02-like smartphone motherboard, bringing Openmoko's dream back from the dead.
-We could try to make a verbatim clone of GTA02-MB-A6 from OM, but for both
-technical and political reasons it would be desirable to make a few changes:
-
-* Making a strictly verbatim clone of GTA02-MB-A6 would mean populating a
-  Samsung K5A3281CTM memory chip onto OM's PCB footprint which does not really
-  fit this chip properly.  Changing the PCB footprint to fit K5A32xx more
-  properly would not be easy because there are signal traces in the PCB spots
-  where the extra mounting balls for K5A32xx would need to go.  The approach
-  that seems most naturally sensible would be to populate a better-fitting
-  memory chip, such as Spansion S71PL129JB0BAW9Z for which that footprint was
-  properly made - but then the result would no longer be a verbatim clone of
-  OM's version, and our gtamodem target configuration would no longer fit.  And
-  at that point it would make the most sense to stop following the gtamodem
-  config and to make it an fcmodem family product instead.
+On the FreeCalypso firmware side, our earlier idea of a single fcmodem target
+that would cover multiple physical hw products in the FC modem family has been
+withdrawn: our existing FCDEV3B hw is covered by firmware build target fcdev3b,
+whereas Tango modems are covered by fw build target tangomdm.  Openmoko modems
+are covered by fw build target gtamodem.  None of these 3 fw build targets are
+interchangeable: each build will only work on its one respective hw target.
 
-* It would be politically preferable if the new GTA02-like motherboard would run
-  fcmodem firmware rather than gtamodem, making a clean break from those parts
-  of OM's troubled history which caused them to be Closedmoko during certain
-  years.
-
-Hence the technical challenge: would it be possible to make a GTA02 derivative
-with absolutely minimal changes that would run fcmodem firmware instead of
-legacy mokoN or FC fw builds for the gtamodem target?  The answer is yes, and
-here is the recipe - note that *no* new components need to be added to the
-extremely tight PCB layout:
+In the unlikely event that our recently discovered Tango modules prove
+insufficient and someone commissions us to design and build a new Calypso modem
+starting from just chips, it will probably make the most sense to design that
+new modem in such a way that it would share the same fw build with Tango, rather
+than with FCDEV3B: Tango is much more versatile in terms of how the multitude
+of Calypso GPIO and multifunction pins may be configured.
 
-* Move the 2nd flash chip select connection from nCS4 to nCS2 on the Calypso;
-
-* Move the AP wakeup interrupt line from GPIO1 to GPIO0 to match fcmodem
-  firmware GPIO assignments;
-
-* Take the useless INT0 AP-to-BP connection line present in the GTA02 original
-  and move it to Calypso GPIO3, providing fcmodem firmware with the DTR input
-  it expects;
-
-* Ground Calypso's unused DSR_MODEM/LPG signal, causing it to not float when
-  our fcmodem firmware keeps the power-up default of DSR_MODEM function;
+FreeCalypso handset idea
+========================
 
-* Program /etc/fc-pinmux in FreeCalypso FFS to tell the firmware that there is
-  no MCSI on this board, so that all 4 MCSI signals will become GPIO dummy
-  outputs and won't float.
-
-Some additional changes which don't affect the firmware one way or the other:
-
-* Remove R1003 and R1004 0Rs which seem to be the root cause of bug #1024 and
-  replace them with solid PCB traces;
-
-* Up C1009 from 10 uF to 22 uF as additional guard from bug #1024;
+I (Mother Mychaela) still desire my own FreeCalypso phone handset that would
+replace my current Pirelli DP-L10 - but it is currently unknown whether or not
+my personal life circumstances will remain such that this project desire will
+remain active, or if changes in my personal life circumstances (such as loss of
+GSM service in the area where I live combined with no ability to relocate to a
+more GSM-friendly country) will invalidate this project desire.
 
-* Ground Calypso's unused input RXIR_IRDA to keep it from floating - this input
-  cannot be changed to an output under firmware control without breaking other
-  functionality.
+In the now-seemingly-unlikely event that I live long enough with active GSM
+service to where I would get around to doing this FC handset project, it is my
+desire to build that handset board starting from just chips, rather than based
+on Tango.  A handset is not a modem, thus handsets and modems generally do not
+share the same firmware build targets - thus if my dream FC handset board ever
+becomes a reality, it will have its own dedicated fw build target, not shared
+with any other hw.  I definitely wish to use the same quadband RFFE as Leonardo
+and Tango, and my currently envisioned choice of flash chip is S71PL064J.
 
-At the same time it would also make a lot of sense to remove the Glamo graphics
-decelerator from the AP subsystem, connecting the LCD directly to the Samsung AP
-like it was on GTA01 - thus from the AP software perspective the new motherboard
-would also become its own new platform just like the modem, very similar to the
-GTA02 original, but not strictly identical, featuring some improvements instead.
-
-IP rights and FreeCalypso brand integrity
+CONFIG_TARGET_FCFAM C preprocessor symbol
 =========================================
 
-The present vision of having the same fcmodem firmware support all FreeCalypso
-modem products applies ONLY to those hardware products which are designed and
-physically produced by Mother Mychaela or one of her business entities.  We will
-NOT provide any support whatsoever for any pirate hardware products that may be
-produced by any persons or entities who are making, have made or are planning to
-make inappropriate use of any of our published or unpublished board design
-files.
+As of 2020-09 this C preprocessor symbol (currently defined only for build
+target fcdev3b) has only two effects:
 
-In the event that some third party buys a legitimate license to produce their
-own derived works based on FreeCalypso hardware designs, we may provide
-technical support to that specific customer as per our agreement with them, but
-any such support will be customer-specific: our generic, non-customer-specific
-public FreeCalypso firmwares will only ever support our own official
-Falconia/FreeCalypso modem products, and should not be expected to support any
-customized products made by or at the request of particular third parties.
+1) It changes the src/cs/drivers/drv_app/ffs/board/dev.c table of supported
+   flash chips and FFS configurations, as well as a few other FFS config bits
+   to support the large 16 MiB flash config used on FCDEV3B.  Targets like Tango
+   with S71PL064J or S71PL032J flash will continue to work equally well whether
+   or not CONFIG_TARGET_FCFAM is defined because these two flash chips are
+   listed in both versions of the table with the same FFS config, but 16 MiB
+   flash chips S71PL129J and S71PL129N are supported only with
+   CONFIG_TARGET_FCFAM and cannot be otherwise, as their 2nd flash chip select
+   wiring is FC-specific.  Yet on the contrary, Samsung K5A32xxCTM with
+   Openmoko's FFS config (also used by Huawei) is NOT compatible with
+   CONFIG_TARGET_FCFAM.
+
+2) It changes the default compiled-in AFC Psi parameters in L1 from TI's
+   Leonardo values to a different set of numbers that match Openmoko/FCDEV3B
+   VCXO.  But these compiled-in values are only fallbacks, and are generally
+   expected to be overridden by factory calibration written into FFS.
+
+-h fcfam target for fc-loadtool
+===============================
+
+The -h fcfam target must be used with FCDEV3B, no other loadtool configs will
+work: FCDEV3B has a 16 MiB flash chip that is only supported with -h fcfam.
+Either -h fcfam or -h gen8 will work equally well on FC Tango modems (S71PL064J
+flash chip), thus you can use whichever config you feel is more philosophically
+correct.