--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/FC-modem-family	Wed Oct 23 00:11:37 2019 +0000
@@ -0,0 +1,191 @@
+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
+====
+
+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;
+
+* 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:
+
+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 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.
+
+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.
+
+* 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:
+
+* 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;
+
+* 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;
+
+* 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.
+
+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
+=========================================
+
+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.
+
+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.