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