This article is only going to be of interest to those who are physically
producing Calypso-based hardware and therefore get to deal with the joys of
yield troubleshooting and failure analysis.  If you are a mere user or software
developer working on known-good hardware made by someone other than you, then
none of the following applies to you.

Testing the SIM interface on a Calypso device
=============================================

A basic pass/fail test of the SIM interface is quite straightforward: simply
insert a test SIM into the socket (at FreeCalypso hw manufacturing we currently
use Sysmocom SIMs for this purpose) and issue an AT+CFUN=1 command to the
standard firmware; if the SIM interface hardware is good, the command will
complete successfully with an OK response, otherwise it will throw up an error.

But what do you do when this basic test fails?  If you get a "SIM not inserted"
error even though the SIM *is* in fact inserted, how do you debug it further?
In order to facilitate lower-level debugging of SIM interface woes, we have
implemented a standalone simtest program described in this article.  To run
this simtest program on your Calypso device, run an fc-iram command like this:

fc-iram -h fcfam /dev/ttyXXX /opt/freecalypso/target-bin/simtest.srec

Like other interactive programs in our target-utils suite, this simtest program
will present a '=' prompt for you to type further commands.  The following
sequence of commands should bring up the SIM interface if the hardware is good:

abbinit
volt 1.8
setup
poll on
reset 1

(Update for fc-host-tools-r11: the explicit abbinit command is no longer needed,
 but it is harmless to issue this extra command like before.)

You can change volt 1.8 to volt 3 if needed, but all recently made SIMs prefer
1.8 V and merely tolerate higher voltages.  TI's Iota ABB chip, which is what
we target in FreeCalypso, does not support 5V SIMs - it doesn't have a charge
pump or any other boost converter to produce 5 V from lower battery voltages.
(It is not just TI but all mobile chipset vendors; it has been a very long time
since anyone made a phone that can power 5V SIMs, and any old 5V-only SIMs have
thus stopped being usable just as long ago.)

If the hardware is good and you have a working SIM inserted in the socket as
you execute the above commands, you should see ATR bytes from your SIM appear
in your terminal window the moment you issue the last reset 1 command: that
final command transitions the SIM reset line from low to high, if the SIM has
been given good power and clock prior to this event, this transition causes it
to initialize and emit its Answer To Reset, and once you issue the poll on
command, our simtest program listens for incoming bytes from the SIM at the
same time while it listens for you to type further commands.

If you execute the above command sequence with a known-good SIM inserted in the
socket and you don't see any ATR bytes on the final reset 1 command, then you
have confirmed with a lower-level tool that your SIM interface hardware is
having some issues.  Give it a poweroff command, rerun the fc-iram command to
get a fresh session, and get your oscilloscope ready.  Now execute the commands
slowly, probing with your o'scope at each step:

abbinit
volt 1.8

The volt command enables the VRSIM regulator in the Iota ABB chip and causes it
to put out the selected voltage.  You should see this voltage appear on SIM
socket contact C1 (VCC); if it fails to appear there, then trace out the circuit
coming from VRSIM, and the VRSIM regulator itself (inside the chip) may also be
suspect.

setup

This command puts the SIM interface block inside the Calypso into a sensible
state and enables the SIM interface level shifters in the Iota ABB.  After this
command you should see a good 3.25 MHz clock (13 MHz divided by 4) with selected
SIM voltage levels on the SIM CLK line (socket contact C3), the RST line (socket
contact C2) should be low, and the I/O line (socket contact C7) should be high.
The SIM clock is produced in the Calypso and then voltage-translated by a
unidirectional buffer in the Iota ABB, thus if the clock fails to appear at the
SIM socket, look for issues in that signal path.  For the I/O line to be high
at this point in the bring-up sequence, the resistor pull-ups on both DBB-to-ABB
and ABB-to-socket sides need to be working; if the I/O line is high on the
DBB-to-ABB side and the pull-up on the ABB-to-socket side is good, but the I/O
line on the ABB-to-socket side is still low, then there may be something wrong
with the level shifter in the ABB holding it low.

poll on
reset 1

(The poll on command can be omitted if you are doing o'scope probing on an empty
socket and thus not expecting any ATR.)  As you issue that reset 1 command, hold
your oscilloscope probe on SIM socket contact C2, which is the RST line - it
should go from low to high.  Our simtest utility's reset command (reset 0 or
reset 1) manipulates one bit in one Calypso register that controls the Calypso
chip's SIM_RST output, which then passes through a unidirectional level shifter
in the Iota ABB on its way to SIM socket contact C2.

On those two FCDEV3B V2 boards that have been rejected as defective because of a
non-working SIM interface and which are now being revisited for a more thorough
investigation, we have not yet seen any problems with the SIM power supply
voltage, with the SIM CLK line or with the I/O line pull-up, but on both boards
the SIM RST line is not working: we see a constant low at socket contact C2
(the only probe-able point in the entire SIM reset signal path), and reset 1
produces no effect.  Unfortunately there is no way to probe the DBBSRST signal
going from Calypso to Iota (it goes from one BGA to the other on an inner layer
without coming up to the surface except right under the two ball pads), thus it
is too difficult to tell where the breakage occurs: is it the Calypso failing
to put out a high on its SIM_RST output when commanded to do so by the register
setting, is it some fault in the PCB shorting this signal to GND before it
reaches Iota's DBBSRST input, is it some fault inside the Iota chip itself that
causes it to put out a low on its SIMRST output even though the DBBSRST input
is high, or is it some fault in the PCB shorting the ABB-to-socket SIM RST
output to GND?

Given that FCDEV3B is not intended to be a high-volume product (we only need to
make enough good boards to provide one to every interested developer or
tinkerer), it will probably make more economic sense to simply reject SIM-
defective boards and write them off as a loss than to spend astronomical amounts
on PCB microsurgery to expose the DBBSRST signal for probing or other in-depth
troubleshooting measures along those lines.  For future board designs that may
need to be produced in higher volumes, the Mother's current plan is to add
probe-able test points on DBBSCK and DBBSRST lines, so that if similar problems
recur, we'll be able to quickly isolate them to the Calypso side or the Iota
side.