--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/SIM-hardware-debugging	Sun Feb 10 20:40:56 2019 +0000
@@ -0,0 +1,120 @@
+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
+
+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 programs 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.