--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Tx-cal-theory	Sun May 28 06:42:29 2017 +0000
@@ -0,0 +1,70 @@
+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.