--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Rx-cal-theory	Sun May 28 03:21:34 2017 +0000
@@ -0,0 +1,92 @@
+The incoming radio signal from the antenna passes through a chain of amplifiers
+before it reaches the Calypso DSP, and the dBm power measurement reported by the
+latter is significantly greater than the actual power level at the antenna
+connector.  The mobile station firmware needs to be able to determine the actual
+input level from the DSP's power measurement (not only for reporting purposes,
+but also to select the proper AGC setting), hence it needs to know the
+difference in dB between the DSP's power measurement and the input signal level
+in dBm.  For this purpose the firmware maintains a constant called GMagic,
+defined as:
+
+GMagic = PM - IL - AGC
+
+where PM is the DSP's power measurement in notional dBm, IL is the input level
+in actual dBm, and AGC is the AGC programmable gain setting in dB.  GMagic is
+the sum of all amplifier gains and insertion losses along the Rx signal path,
+and is on the order of about 100 dB, although the fw reckons it in half-dB
+units.
+
+Some Calypso device manufacters have calibrated the GMagic constant for each
+band on a per-unit basis, and the unit-to-unit difference is on the order of
+1-2 half-dB units, i.e., rarely more than 1 dB.  The difference from one board
+design to another tends to be a little greater, on the order of 10 half-dB
+units, and is probably due to the difference in insertion losses at various
+points in the Rx signal path.  (Ideally these insertion losses should be zero,
+but the world is not ideal.)
+
+GMagic calibration is done by connecting a signal generator putting out a
+precisely controlled signal to the DUT's antenna connector or RF test port,
+making a power measurement with the Calypso DSP and computing GMagic per the
+simple equation above.
+
+Our FreeCalypso version of the GMagic calibration procedure is closely based on
+the Sara version, described on pages 28-32 of the Sara document
+rf_calibration.pdf (see TI-docs).  The LoCosto calibration document does not
+include a GMagic calibration procedure, but LoCosto is a very different beast,
+with both the baseband processor and the RF transceiver in the same chip, and
+using that mysterious DRP - perhaps LoCosto doesn't need GMagic calibration,
+perhaps it is absorbed into DRP calibration instead.
+
+Per the available Sara RF calibration document, we set the signal generator's
+output level to -74.5 dBm, and set the AGC in the Rita RF chip to 34 dB for the
+GMagic calibration step.  However, we use the ARFCNs from the LoCosto document:
+37 for the EGSM band, 698 for DCS, 661 for PCS and 189 for GSM850.  The old Sara
+document covers only 900 and 1800 MHz bands (I'm guessing Sara probably did not
+support 1900 MHz, let alone 850), the LoCosto document is quadband throughout,
+and the LoCosto ARFCNs are closer to the true centre of each band.
+
+RSSI channel compensation
+=========================
+
+The GMagic constant is calibrated at the centre frequency for each downlink
+band, but the true value of this "magic gain" varies slightly with the frequency
+channel.  The drawing on page 34 of the Sara document suggests that this
+frequency channel-dependent variation is caused by frequency-dependent variation
+in the insertion loss of the Rx SAW filters.  This frequency channel-dependent
+variation in the "magic gain" is customarily calibrated on a per-unit basis
+(even on LoCosto, apparently), and the available documents suggest that this
+calibration is done in order to make RSSI reporting more accurate.
+
+Once again our FreeCalypso version of this RSSI channel calibration procedure
+is based on the Sara document, rather than LoCosto, except for the ARFCNs.  The
+LoCosto document gives ARFCN ranges for Rx channel calibration for all 4 bands,
+and these ranges fully agree with what Openmoko's factory programmed in their
+/gsm/rf/rx/calchan.* files, thus we have adopted the ARFCN ranges and test
+ARFCNs from LoCosto for all 4 bands.
+
+Note that the LoCosto document indicates the use of a different signal generator
+level (-68.5 dBm instead of -74.5), and tells the operator to set the AGC gain
+to 0 dB.  The latter must be a LoCosto-ism, as it is definitely not correct for
+our Calypso+Iota+Rita chipset.  If we set the signal generator level to
+-68.5 dBm, we would need to get the Rita AGC to 28 dB, but the Mother of
+FreeCalypso decided to go with the safer choice of using the Sara settings of
+-74.5 dBm generator level, 34 dB AGC.
+
+FreeCalypso Rx calibration tools
+================================
+
+The present suite of RF calibration tools includes two programs for Rx path
+calibration:
+
+fc-rfcal-gmagic
+
+	This program is a study-only tool.  It measures the GMagic constant for
+	the user-specified band (either at that band's default ARFCN or at a
+	user-specified ARFCN) and prints it out, but does not write anything
+	into the Calypso device's FFS.
+
+fc-rfcal-rxband
+
+	This program is intended for production use.  It performs both the
+	GMagic and the RSSI channel compensation calibration steps, uploads the
+	results to the DUT and saves them in FFS.