The Tx power levels put out by a GSM mobile station are subject to strict
specifications, and on the Calypso+Iota+Rita chipset they are produced by
writing different values into the APC DAC register.  But what value should be
written into the APC DAC in order to produce a given Tx power level in dBm?
The answer varies from one produced device unit to the next, and even more from
one board design to the next, hence these APC values need to be calibrated.

The general procedure for calibrating Tx power levels is described in both Sara
and LoCosto calibration documents (see TI-docs), but the LoCosto document adds
one crucial detail which the Sara one fails to describe.  The instructions given
in the Sara document appear to be perfectly intuitive at first: go through all
power levels in turn (PL numbers 5-19 for EGSM and GSM850 or 0-15 for DCS and
PCS), and for each power level command the DUT to transmit at that level,
measure the actual Tx output power with the CMU200 or other RF test equipment,
and adjust the APC DAC value up or down to make the output power match the spec.

The problem is with the very last part: the output power you get with the
compiled-in APC DAC value is one number, the spec-defined target power is a
different number, exactly how do you adjust the APC DAC value to hit the target
power level?

The LoCosto document gives the answer which was not at all obvious to me at
first.  I draw the reader's attention to section A.3.1 on page 43 of that
document.  The trick is as follows: the relation between the APC DAC value and
the resulting Tx output power (or rather the equivalent in terms of voltage) is
modeled as a piecewise linear function, and this piecewise linear function is
constructed from a preliminary set of output power measurements with a fixed
set of APC DAC values.

We also have a strong piece of evidence that the Tx power level calibration
procedure performed by Openmoko at their factory was based on the same principle
as the LoCosto document version.  If you look at the /gsm/rf/tx/levels.900 table
in Om-calibrated GTA02 units and compare it against the firmware's compiled-in
version, you will see that the APC DAC values for power levels 5-19 have been
replaced with calibrated ones as expected, but there is also this oddity: the
APC DAC value for power level 0 (not a valid number for this band) has been
replaced with 600.  Always 600, a perfect round number, on every unit.

Having understood the calibration method described in the LoCosto document, the
mystery of this fixed number 600 becomes clear: the calibration program
establishes the basis for the calibration by temporarily overwriting the APC DAC
value in the power level 0 slot with a series of fixed values, 600 being the
last of them.  It constructs the piecewise linear model for the APC from power
measurements made with these fixed DAC values, and uses this model to compute
the DAC value for each target power level.  The latter DAC values are then
written into Tx levels table slots 5-19 for EGSM and GSM850, or 0-15 for DCS
and PCS.  In the case of DCS and PCS no visible artifacts remain from the
calibration basis run (because slot 0 is a valid power level for these bands),
but an artifact remains in the levels.900 table in the unused slot 0.

In the present FreeCalypso RF calibration tools suite the planned
fc-rfcal-txband program that will perform the entire Tx band calibration
procedure has not been written yet.  Instead we have the following two building
blocks:

fc-rfcal-txbasis performs the preliminary "basis" step of Tx power level
calibration: it sets the APC DAC to each of the values given on the command line
in turn, and reports the resulting output power level in dBm.  The temporary
APC DAC values do get written into the Tx levels table in L1 (there is no other
way to set the APC DAC value for the active transmitter through Test Mode), but
the MISC_ENABLE command to save Tx calibration tables in FFS is NOT issued,
thus the corruption of the Tx levels table inflicted by this program will get
blown away on the next rfpw 7 (Test Mode band selection) command.

fc-rfcal-txcheck is a completely non-invasive program (does not make any writes
to any L1 RF tables or to FFS) that steps through all power levels for the
specified band (5-19 for EGSM or GSM850, or 0-15 for DCS or PCS), performs a
power measurement at each level, and displays the measured result.  An
equivalent operation will be the finishing sanity check step in the full Tx
power level calibration program.