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