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 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.

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.