--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Calypso-digital-voice	Thu Mar 28 08:04:00 2019 +0000
@@ -0,0 +1,244 @@
+Digital voice on FreeCalypso modems via MCSI
+============================================
+
+The Calypso chip provides a little-used auxiliary synchronous serial interface
+called MCSI.  It is an auxiliary interface to the DSP part of the Calypso
+(controlled solely by the DSP and not directly accessible to the ARM part); it
+is not clear what other uses TI may have had in mind for this interface, but
+one advertised feature of TI's TCS211 chipset+firmware solution is Bluetooth
+support in the form of using MCSI as a digital voice channel to be connected to
+TI's Bluetooth Island chip.  In FreeCalypso we are not interested in Bluetooth
+per se, but we are interested in getting a digital voice channel out of our
+modem for GSM voice calls in order to compete with the mainstream proprietary
+GSM modem modules which do provide such digital voice channels.
+
+Our current development board (FCDEV3B) has MCSI brought out on a header for
+experimentation, and as of 2019-03 we finally got this MCSI working as a proper
+digital voice interface.
+
+Hardware interface
+==================
+
+MCSI consists of 4 hardware signals:
+
+* MCSI_CLK is the bit clock output from the Calypso; in pure hardware terms
+  this signal is bidirectional, but unless you are going to develop your own
+  DSP code patches, its direction is determined by the DSP ROM code, which
+  configures MCSI_CLK as an output, i.e., the Calypso acts as the clock master.
+
+* MCSI_FSYNCH is the frame sync output from the Calypso; it is the same deal as
+  with MCSI_CLK: bidirectional in pure hardware terms, but if you are not
+  changing the DSP code with your own custom patches, it is an output from the
+  Calypso.
+
+* MCSI_RXD is the voice uplink bits input to the Calypso: the user's application
+  processor needs to feed voice uplink bits to this pin as timed by MCSI_CLK
+  and MCSI_FSYNCH.
+
+* MCSI_TXD is the voice downlink output from the Calypso: as the vocoder in the
+  Calypso DSP decodes received downlink speech from GSM codecs into linear PCM,
+  this PCM voice downlink is put out on this MCSI_TXD pin, in synchrony with
+  MCSI_CLK and MCSI_FSYNCH.
+
+The format in which digital voice samples are exchanged via MCSI between the
+Calypso and the user's application processor is 16-bit linear PCM, 8000 samples
+per second, thus requiring 128 kbps of bandwidth.  The synchronous serial
+interface details are as follows:
+
+* When MCSI is enabled, the Calypso puts out a 520 kHz clock on MCSI_CLK,
+  produced by dividing the 13 MHz master clock by 25.  This clock as put out by
+  the Calypso has a perfect 50% duty cycle.
+
+* Given that a new pair of samples (uplink and downlink) needs to be transferred
+  once every 125 us (1/8000th of a second, for 8000 samples per second), this
+  520 kHz bit clock is further divided by 65 to produce an 8 kHz clock on
+  MCSI_FSYNCH, i.e., every 65 bits there is a frame synchronization pulse on
+  MCSI_FSYNCH.  The width of this frame sync pulse is one full bit time, the
+  pulse is active high, and the MCSI_FSYNCH line stays low the rest of the time.
+
+* Calypso outputs MCSI_FSYNCH and MCSI_TXD are updated on the rising edge of
+  MCSI_CLK and should be sampled on the falling edge of the same clock by the
+  user's application processor.  The MCSI_RXD input is sampled on the falling
+  edge of MCSI_CLK by the Calypso, and should be updated on the rising edge of
+  the same clock by the user's application processor.
+
+* Each voice sample (both uplink and downlink) is transferred from the most
+  significant bit to the least significant bit (MSB first), starting with the
+  clock cycle immediately following the frame sync cycle, i.e., the cycle in
+  which MCSI_FSYNCH is asserted by the Calypso.
+
+* Given that each frame is 65 bits long (520 kHz bit clock divided by 8 kHz
+  frame rate) and that 16 bit slots out of every frame are used to transfer
+  voice sample bits, plus one bit slot for frame sync, it follows that 48 bit
+  slots out of every frame are dummies.  The Calypso puts out 0 bits on MCSI_TXD
+  in all bit slots that don't carry voice sample bits.
+
+A graphical depiction of what I just described verbally can be found on page
+3074 of this TI OMAP document:
+
+ftp://ftp.freecalypso.org/pub/ARM/OMAP/sprugn4r.pdf
+
+Calypso MCSI corresponds to what this OMAP document calls "Mode 1", i.e.,
+Figure 21-14 at the top of the page, NOT the other one below it.
+
+Enabling and disabling MCSI for digital voice
+=============================================
+
+TI's DSP ROM code supports two modes of operation in which MCSI is activated,
+called "Bluetooth cordless" and "Bluetooth headset".  In the "BT cordless" mode
+the voice path is connected between the chipset's native analog voice hw and
+MCSI, with GSM out of the picture; in the "BT headset" mode the voice path is
+connected between the GSM vocoder and MCSI, with the local analog voice hw out
+of the picture.  The latter "BT headset" mode is the only one which we currently
+support in FreeCalypso; the "BT cordless" mode does not work properly as of this
+writing - the step of enabling the Voice Band Codec block in the Iota ABB for
+this mode is currently missing.  Proper support for the "BT cordless" mode can
+be added if a real need for it ever arises, but it would take some work, and
+right now there is no business case for it.
+
+In TI's TCS211 firmware architecture (see TCS211-fw-arch document) entry into
+and exit from these "Bluetooth" MCSI voice routing modes is handled via the
+RiViera Audio Service fw component, specifically its Audio Mode facility,
+usually via the audio_full_access_write() API call.  When asked to switch voice
+routing modes, this RV Audio Service component sends an MMI_AUDIO_MODE_REQ
+message to L1, the L1A component passes the request to L1S, and L1S finally
+twiddles the magic control bits in the DSP API RAM.
+
+In FreeCalypso we currently provide two ways for the end user to enter the
+"BT headset" mode for digital access to GSM voice:
+
+* The original way is the AT@VPATH=n command, which provides "raw" access to
+  the RV Audio Service's voice routing mode switch call.  Setting AT@VPATH=2
+  enters the "BT headset" mode, AT@VPATH=0 returns to the normal "GSM only"
+  mode (MCSI disabled), and AT@VPATH=1 enters the currently not-working
+  "BT cordless" mode.
+
+* The new way is the session-long AT@VSEL=n boolean setting.  In the default
+  AT@VSEL=0 mode the firmware functions like before (MCSI disabled, voice calls
+  go to the analog voice hw), but if your application needs the digital voice
+  interface instead of analog, you can set AT@VSEL=1 once at the beginning of
+  your modem session.  In this AT@VSEL=1 mode, whenever a GSM voice call is
+  connected (dialed or answered), the MCSI clocks are switched on (MCSI_CLK and
+  MCSI_FSYNCH outputs come to life) and the "BT headset" voice routing mode is
+  entered at the appropriate point in the call establishment process; when the
+  call disconnects (either side hangs up), MCSI is turned off.  The new logic
+  internally performs the equivalent of AT@VPATH=2 and AT@VPATH=0 at appropriate
+  times.
+
+Why does one need our new AT@VSEL=1 logic for dynamic switching into and out of
+MCSI "BT headset" mode, why not simply set AT@VPATH=2 upfront and run with it?
+Two reasons:
+
+1) If MCSI is enabled continuously and not just when needed during voice calls,
+   the DSP never goes quiescent during idle periods, and the Calypso is not
+   allowed to enter deep sleep.  Both of these factors are detrimental to proper
+   power management - the whole idea is that when a GSM modem is idle (not in a
+   call, but listening to paging and ready to accept incoming calls), most of
+   the hw needs to be powered down as much as possible, to reduce power
+   consumption to a minimum and prolong standby battery life.
+
+2) There is a bug in the DSP code (present in the ROM and not corrected by the
+   patches we are using) that manifests if MCSI is already running when the very
+   first voice call after system boot is connected.  Our AT@VSEL=1 mechanism
+   reliably avoids this DSP bug (ensured by the timing sequence of when we turn
+   on the vocoder and when we turn on MCSI), and it is my (Mother Mychaela's)
+   guess that TI probably missed this DSP bug because their own Bluetooth
+   handling code most likely worked very similarly to my AT@VSEL=1
+   implementation.
+
+Thus the short story is that if you are using the digital voice interface via
+MCSI, just set AT@VSEL=1 at the beginning of your modem session, and whatever
+hardware you connect to MCSI needs to be OK with the clocks (MCSI_CLK and
+MCSI_FSYNCH) appearing only during active voice calls, and being off at other
+times.
+
+It should also be noted that the new AT@VSEL=1 mechanism is implemented properly
+only in our new hybrid firmwares, i.e., Magnetite hybrid and Selenite.  The
+legacy configs (l1reconst etc) using the blob version of G23M PS and ACI from
+Openmoko (maintained only for regression testing and debugging purposes) also
+implement the AT@VSEL command, but the AT@VSEL=1 mode will work somewhat
+erratically in that version: the modem may enable MCSI at the wrong time, and
+it will sometimes fail to turn it off at the end of a call.  The implementation
+of this functionality resides entirely in the "high-level audio driver" module
+in ACI, this module is different between TCS2 and TCS3 versions of ACI, and
+there is no justification for expending the effort to make the new feature work
+in the old version of ACI: it is an entirely new feature added in FreeCalypso,
+not present in any old Calypso modems, hybrid fw is the way forward in FC, thus
+we only need to support new features in our hybrid firmwares.
+
+The alternative approach of tapping VSP
+=======================================
+
+MCSI is not the only digital voice interface in the Calypso chipset: there is
+also another interface called VSP (Voice Serial Port), which is a private
+interface between Calypso and Iota chips.  Because it was always intended to be
+a private interface internal to the core chipset, not an external application
+interface like MCSI, none of the standard Calypso-based phone or modem board
+designs expose it in any accessible way - instead it goes from one BGA to the
+other on inner PCB layers with zero accessibility for probing.  Our FCDEV3B is
+no exception in this regard, as our modem core is based on a commercial modem
+design from a decade before our time.
+
+Because it took us a very long time to get MCSI working as a practically usable
+digital voice interface (the new AT@VSEL=1 mechanism is the key, without this
+firmware piece NCSI is not practically usable), much thought has been given
+earlier to the alternative idea of tapping into VSP.  There are two
+possibilities with that one:
+
+1) Given that Calypso VSP is a clock slave (it expects the ABB chip to provide
+   the clock and frame sync signals), those who desire their digital voice i/f
+   to be a PCM slave (not a PCM master like TI's "BT headset" function over
+   MCSI) will likely be very tempted to disconnect Calypso VSP from the Iota
+   chip entirely and to connect it to their own application instead.  However,
+   in the absence of source code for the DSP ROM this approach would be
+   incredibly risky (if the DSP is not too happy with the non-Calypso-sourced
+   timing you feed to the VSP, how are you going to debug it deep within the
+   DSP black box?), and I (Mother Mychaela) consider it so risky that if anyone
+   wants to do it, you will be entirely on your own - don't expect any help
+   from me.
+
+2) A much safer approach would be to keep the VSP clock and frame sync
+   connections between Calypso and Iota chips, but also make them available
+   externally, i.e., have your application logic sync itself to these clocks.
+   Voice downlink could then be received just by passively tapping VSP lines,
+   and sending your own voice uplink via VSP would require cutting only the one
+   line that carries voice uplink bits from Iota to Calypso.  It would then
+   effectively be just like MCSI (a PCM master to the user's application), but
+   without requiring any support in the firmware, instead being completely
+   invisible to the Calypso firmware and to the DSP.
+
+However, because we don't have any board on which VSP signals are accessible to
+probing, there are several unknowns with this interface:
+
+* Is the VSP clock produced by the Iota chip 500 kHz (13 MHz master clock
+  divided by 26) or 520 kHz (same master clock divided by 25)?  The available
+  Iota datasheet says 500 kHz, but if that is correct, how is the frame sync
+  handled?  500 kHz does not divide evenly by 8 kHz.  Does Iota's clock + frame
+  sync output alternate between 62-bit and 63-bit frames, producing an 8 kHz
+  frame rate on average?  Sounds messy and convoluted...
+
+* It is not clear at all exactly when Iota's VSP clocks are started and stopped,
+  and whether the bit clock runs continuously during an active call (like
+  MCSI_CLK does), or if it is gated on only for those bit slots that carry
+  actual voice sample bits.
+
+If we are going to produce a new FreeCalypso modem based on our current FCDEV3B,
+but repackaged into some end use form factor, as things stand today (2019-03),
+we are going to use MCSI rather than VSP for the digital voice interface.  While
+MCSI has definitely been a huge hassle and requires the user to issue one extra
+setup command (AT@VSEL=1) at the beginning of each modem session, at least it
+is now a known beast, and a known-working one.  Committing to VSP in a
+commercial product design without ever having seen these VSP signals on an
+oscilloscope would be very irresponsible; if someone really wishes to go with
+VSP instead of MCSI, the responsible approach would be to first design and build
+another development board with VSP signals brought out for experimentation, and
+only then possibly use it in a commercial product design after it becomes a
+known beast.
+
+From the standpoint of pure curiosity, I would be very interested in a
+development board with VSP access, just to answer the above questions and fill
+that gap in my Calypso knowledge.  But switching to a more practical hat,
+spending some 10 to 15 kUSD just to satisfy that curiosity would be very
+difficult to justify - thus there is a very strong chance that VSP will never
+be explored,  Which is not really a problem at all, as for a practically usable
+external digital voice channel we now have working MCSI.