--- a/FCDEV3B-repackaging	Wed Oct 23 00:26:36 2019 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,305 +0,0 @@
-Repackaging FreeCalypso modem into different physical form factors
-==================================================================
-
-[This document was originally written in 2018-10; subsequent updates
- are noted inline in the same bracketed form as this note.]
-
-As of this writing, our FreeCalypso Triband Modem Solution has reached the
-status of a finished product: it is no longer experimental or developmental,
-it is now fully fit for operational use on live public GSM networks in end user
-applications that need a standards-compliant GSM+GPRS modem.  However, at the
-present moment it is only available in the physical form factor of a development
-board (FCDEV3B) that was originally designed to serve as a software/firmware
-development platform, and as such it is not ideally suited for use as an end
-product.  For end use applications it would be highly desirable to take our
-proven FC Triband Modem Solution (FC-TMS) as realized on the FCDEV3B and
-repackage it into other physical form factors.  This repackaging can be done
-in two ways:
-
-Approach 1 (strongly preferred): the party who desires to have our FC-TMS in a
-particular form factor gets in touch with FreeCalypso Central, engages in a
-discussion with us to arrive at the new form factor to be implemented (it needs
-to satisfy your requirements and be feasible for us to implement), then funds
-the cost of PCB layout labor to turn the new form factor modem into reality.
-More specifically, we would do the design at the schematics+BOM level while the
-the PCB layout step would have to be outsourced at cost.
-
-Approach 2 (NOT preferred, but can sometimes be agreed to in limited cases):
-someone else does the repackaging work under their own control.
-
-In the case of Approach 1 the new modem product will always be guaranteed to
-work flawlessly and be fully compatible with our FreeCalypso sw and fw
-architecture because in this case the hardware design is personally supervised
-by the Mother of FreeCalypso and must receive her approval prior to being
-released to layout and then to fabrication.  In the case of Approach 2 this
-assurance is lacking.  This document provides some technical guidelines that
-MUST be followed in order for a new modem hw product to stand a chance at being
-compatible with FreeCalypso; anyone who follows Approach 2 against our
-recommendation but still wishes to have a chance at receiving support from us
-MUST follow these design guidelines.
-
-LEGAL NOTICE: Following these technical guidelines does NOT by itself grant you
-a license to use our FreeCalypso trademark on your hardware products; this
-trademark is personally owned by Mychaela N. Falconia and only she has the
-authority to license its use at her sole discretion.  Similarly our agreement
-with GSMA does NOT allow us to sublet any part of our IMEI number range to any
-other parties; any IMEI number ranges that may be allocated by GSMA to
-FreeCalypso products may ONLY be used for those products that are physically
-produced by Falconia Partners LLC from start to finish and not any others.
-
-Basic technical guidelines
-==========================
-
-The purpose of these guidelines is to make it possible for the same firmware
-build configuration to support both our existing FCDEV3B and various
-repackagings of the underlying core modem solution (FC-TMS), i.e., to have the
-same official FC Magnetite firmware builds for target fcdev3b run not only on
-the original development board, but on all physical repackagings of the same
-core modem solution.  To make such firmware reuse possible, the following
-hardware design constraints MUST be followed:
-
-* The flash+RAM chip must be the same Spansion S71PL129NC0HFW4B as used on our
-  FCDEV3B, and it must be wired the same way: first flash chip select on Calypso
-  nCS0, RAM on nCS1, second flash chip select on nCS2.  The flash reset line
-  needs to be wired the same way as on FCDEV3B V2, otherwise Calypso sleep modes
-  will be broken.  We realize that this flash and RAM capacity (16 MiB and
-  8 MiB, respectively) is extreme overkill for typical modem applications
-  outside of development, but supporting multiple flash chip types would
-  introduce a configuration management burden which we are not willing to
-  take on.
-
-[2019-03 update: we now have working flash chip type autodetection, and
- commercial modem products can use a smaller flash+RAM chip, specifically
- Samsung K5A3240CTM or K5A3281CTM as used by Openmoko.]
-
-* 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.  Other boards seeking to
-  be FreeCalypso-compatible need to have this pin tied to GND as well because
-  our firmware leaves this pin in its default power-up config of DSR_MODEM input
-  and does not change it to LPG output - leaving it unconnected would cause it
-  to float.
-
-* 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.
-
-* If someone needs a modem that produces an Openmoko-style 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), this signal should be
-  connected to GPIO 0.  Openmoko used GPIO 1 for this purpose, but in
-  FreeCalypso GPIO 1 is taken because we use it for the loudspeaker control
-  signal like on TI's D-Sample and Leonardo boards, hence we are moving the AP
-  wakeup signal to GPIO 0, to be implemented if and when anyone builds a modem
-  based on FC-TMS that needs to provide such a signal.
-
-* If your product includes a loudspeaker amplifier like on our FCDEV3B, connect
-  its on/off control input to GPIO 1, otherwise leave our GPIO 1 output
-  unconnected.
-
-* Our fw produces a DCD modem control output on GPIO 2; if you are connecting
-  the MODEM UART channel to an RS-232 port or to a USB-serial chip with a full
-  set of modem control signals, connect DCD to GPIO 2.
-
-* Our fw treats GPIO 3 as a DTR modem control input following TI's C-Sample and
-  D-Sample boards.  If your product has a real DTR signal coming from an RS-232
-  interface or from a USB-serial chip, connect it to GPIO 3, otherwise GPIO 3
-  needs to be pulled down to GND like on Leonardo and FCDEV3B.
-
-* If you are connecting the MODEM UART channel to a full RS-232 port or to a
-  USB-serial chip with a full set of modem control signals, you should connect
-  DSR and RI to TSPDI/IO4 and MCUEN1/IO8, respectively.  Right now our fw
-  drives IO4 low and IO8 high, corresponding to DSR asserted and RI negated
-  (normal quiescent state), and connecting the signals in this way allows the
-  possibility of extending the fw to drive them in some more intelligent manner
-  if need be.
-
-* Both Calypso UARTs need to be wired in an accessible way so that our standard
-  FC Magnetite firmware can be used with the AT command interface on the MODEM
-  UART and RVTMUX on the IrDA UART.
-
-* Our fw configures the MODEM UART with hardware flow control enabled; if your
-  application lacks RTS/CTS signals, then Calypso's CTS_MODEM signal needs to
-  be pulled down to GND so it is seen as asserted.
-
-* Our fw configures the 4 MCSI/GPIO pins as MCSI rather than GPIO.  If your
-  board does not use MCSI because you are tapping VSP instead or not using any
-  digital voice interface at all, then you should put pull-down resistors on
-  MCSI_RXD, MCSI_CLK and MCSI_FSYNCH, otherwise these signals will float.
-  MCSI_RXD can be directly tied to GND without a resistor as it is always an
-  input to the Calypso, but MCSI_CLK and MCSI_FSYNCH need to be pulled down
-  with resistors: our fw can enable TI's "Bluetooth headset" and "Bluetooth
-  cordless" modes, in which case these signals become outputs.  If the signals
-  are switched to being outputs by software command but are tied to GND on the
-  board, the result will be a shorted output driver which could damage the chip,
-  and it is clearly not acceptable to produce hardware that can be damaged by
-  an AT command, even an obscure and non-standard one.
-
-Cost increment
-==============
-
-If you don't need huge flash and XRAM capacity, don't have a DTR input and are
-not using MCSI, then the incremental cost of being firmware-compatible with
-FCDEV3B compared to Openmoko's approach of leaving all unused signals
-unconnected and using a smaller flash+RAM chip consists of:
-
-* A logic voltage level translating buffer to provide a reset to the flash chip
-  that meets its timing requirements;
-
-[2019-03 update: the above is no longer required, you can now use one of the
- smaller flash chips which are compatible with TI's silly FDP scheme and thus
- don't need the extra translating buffer IC for reset.]
-
-* 3 pull-down resistors on GPIO3, MCSI_CLK and MCSI_FSYNCH;
-
-* Direct connections to GND on DSR_MODEM and MCSI_RXD pins.
-
-For parties other than the Mother, it is up to you to decide if being firmware-
-compatible is worth the cost increment or not, but all modem repackagings
-produced by us under the FreeCalypso brand will follow these software and
-firmware configuration management compatibility guidelines, and the same is
-required for anyone else who wishes for their hardware variant to be accepted
-into the FreeCalypso family.
-
-Tapping VSP for the digital voice interface
-===========================================
-
-The Calypso+Iota chipset includes an interface called VSP for Voice Serial Port;
-per TI's design intent it is a strictly private interface between Calypso and
-Iota chips, but it is possible to tap into this interface to get an external
-digital voice channel.  TI's official method for getting a digital voice channel
-out of a Calypso modem is to use MCSI in their so-called "Bluetooth headset"
-mode, however, our experiments on the FCDEV3B have revealed that this interface
-does not work the way one would naively expect.  Unless we can convince TI to
-dig up and release the sources for the Calypso DSP ROM, which we obviously
-cannot count on, we won't be able to use MCSI reliably until and unless we
-undertake to fully reverse their DSP ROM code from disassembly, which would be
-an extremely major and very costly undertaking.  Because of this unfortunate
-situation, the alternative way of tapping into VSP needs to be given
-consideration.
-
-[2019-03 update: we got MCSI working now, please read the Calypso-digital-voice
- article for more info about both MCSI and VSP options.]
-
-Tapping into VSP is absolutely not possible on our current FCDEV3B, as the
-signals in question are currently routed directly from one BGA to another and
-do not come up to the surface at any accessible point.  The same situation holds
-on every other existing Calypso phone and modem known to us - after all, VSP was
-meant to be a private chip-to-chip interface.  Instead we are presenting the
-idea of tapping VSP as a possibility for anyone who undertakes to repackage our
-FC-TMS into some new form factor and desires a digital voice channel while at
-it.
-
-In TI's standard solution VSP clock and frame sync signals are generated by the
-Iota ABB and are inputs to the Calypso DBB.  Because they are inputs to the
-Calypso, it may be tempting to disconnect them from the ABB and have them
-originate from an external source instead - however, TI's DSP code in the ROM
-was most certainly written with the assumption that these signals will only
-ever be driven by their ABB and never by anyone else, hence having them come
-from a source whose timing does not come from the Calypso can cause all kinds
-of strangeness which we will never be able to debug properly because the DSP is
-a mysterious black box.  Therefore, my (Mother Mychaela's) stance is that if
-you break the VSP connection between Calypso and Iota, then you are entirely on
-your own - don't expect any help from me.  Instead my idea is to tap into VSP
-without breaking it, specifically:
-
-* Keep the clock and frame sync connection between Calypso and Iota, with Iota
-  remaining the driver on these nets - but also bring these signals out
-  externally, so external logic can sync itself to this interface as well.
-
-* Do likewise for the line that carries downlink voice from the DBB to the ABB:
-  let the ABB receive it and use it to drive the analogue earpiece output (which
-  would be unconnected in a digital voice application), but let external logic
-  receive it too.
-
-* Break only the line that carries uplink voice from the ABB to the DBB: bring
-  the Iota output side on one external interface pin and the Calypso input side
-  on another external interface pin.  Putting a jumper on these adjacent header
-  pins would restore TI's original configuration and allow uplink voice to come
-  from an analogue microphone connected to the ABB, and if a digital uplink
-  voice source is desired, remove the jumper and have an external source provide
-  the bits which would otherwise come from Iota's voice ADC.
-
-The above approach would provide a usable digital voice interface that would be
-completely transparent (invisible) to the Calypso DSP and even to the ARM-side
-firmware, hence it should work without any nasty surprises.
-
-Triband vs. quadband
-====================
-
-One shortcoming of our current FreeCalypso modem solution is that it is triband
-and not quadband; more specifically our standard hw build omits the GSM850 band,
-or we can build a different configuration that supports GSM850 but omits EGSM
-(the 900 MHz band).  To the best of our knowledge the GSM850 band is used very
-little these days, but being only triband makes us look bad compared to the
-competition: all of the mainstream proprietary GSM modem modules are fully
-quadband these days.
-
-It *is* possible to make a Calypso-based quadband modem, as TI had one: their
-Leonardo reference board for the Calypso+Iota+Rita chipset existed in several
-versions some of which were quadband, and their E-Sample board (Calypso+) which
-used the same Rita RF block was also quadband.  However, changing our current
-FC modem design from triband to quadband would involve a highly invasive PCB
-layout change: basically our entire modem PCB layout and particularly the GHz RF
-section would have to be ripped up and reshuffled into a different arrangement.
-Furthermore, if we as the FreeCalypso community do decide that we wish to
-produce a quadband modem, I (Mother Mychaela) would NOT be comfortable with
-entrusting the needed re-layout work to an "ordinary" PCB layout contractor who
-is not a cellphone RF design expert, instead we would need to get a consultation
-from an RF PCB design expert who has experience very specifically with GSM
-cellphone design and not any other applications.  Finding such an expert would
-be a major task in itself, and that expert most certainly won't come cheap.
-Therefore, a quadband FreeCalypso modem probably won't happen unless we get
-someone with a lot of money to throw around.
-
-There is one exception, though: if anyone would like to see our FreeCalypso
-modem repackaged into the SMT module form factor copied from BenQ M32 and pays
-for that venture, the result would be naturally quadband as the layout of BenQ's
-module follows the same floorplan in the RF section as TI's quadband Leonardo
-and E-Sample layout.  However, that approach would involve a step to reverse-
-engineer BenQ's layout by slicing their board and imaging its inner layers,
-hence anyone seeking this approach would need to be prepared to pay for that
-step.
-
-If anyone ever does pay for the creation of a quadband version of our
-FreeCalypso modem solution, be it in BenQ's physical form factor or some other,
-what about the firmware?  For a long time I thought that a quadband modem would
-need a different firmware build configuration because of incompatible TSPACT
-signals.  Our current triband modem (copied from Openmoko) has them wired like
-this:
-
-TSPACT2 = Tx high bands
-TSPACT1 = Rx PCS band
-TSPACT4 = Tx low bands
-
-But TI's original TSPACT wiring for the quadband RFFE on their Leonardo and
-E-Sample boards was different:
-
-TSPACT2 = Tx low bands
-TSPACT1 = Tx high bands
-TSPACT4 = Rx GSM850 band
-
-These two TSPACT signal assignments are mutually incompatible, hence if we make
-a quadband modem following TI's original Leonardo/E-Sample TSPACT wiring, it
-won't be able to share the same fw with our triband modems.  But then I got an
-idea: what if we wire them up in our own creative way as follows:
-
-TSPACT2 = Tx high bands
-TSPACT4 = Tx low bands
-TSPACT5 = Rx GSM850 band
-
-Then we can have the same fw build configuration support both triband and
-quadband FreeCalypso modems by driving the signals as follows:
-
-TSPACT1 = Rx PCS band
-TSPACT2 = Tx high bands
-TSPACT4 = Tx low bands
-TSPACT5 = Rx GSM850 band
-
-TSPACT1 will be driven but unused on quadband modems, whereas TSPACT5 will be
-driven but unused on triband ones like our current FCDEV3B.  To me (Mother
-Mychaela) being able to have the same fw among *all* FreeCalypso modem variants,
-both triband and quadband, is more valuable than the symbolic act of recreating
-TI's original RFFE wiring, hence I am now leaning toward this new approach.