--- a/doc/Tx-cal-theory	Mon Jul 17 19:15:44 2017 +0000
+++ b/doc/Tx-cal-theory	Mon Jul 17 22:49:35 2017 +0000
@@ -48,23 +48,109 @@
 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:
+Target power level numbers
+==========================
+
+Ideally the power level numbers to be used as the targets for the calibration
+process would be the levels given in the GSM 05.05 spec: from 33 dBm down to
+5 dBm for the EGSM and GSM850 bands or from 30 dBm down to 0 dBm for DCS and
+PCS, in 2 dBm steps in each case.  However, the evidence from TI's calibration
+documents (both Sara and LoCosto) is that some devices are not able to produce
+the very highest and sometimes the very lowest power levels given in the spec,
+and getting a successful calibration requires setting the calibration targets
+to slightly shifted numbers, although still within the tolerances allowed by
+the GSM 05.05 spec.  The table in TI's Sara calibration document (page 26) has
+the highest power level reduced by 1.2 relative to the spec, the next highest
+by 0.5, whereas the lowest 4 (EGSM) or 6 (DCS) levels are raised and compacted
+together.  The table in the LoCosto document (page 44) has the highest power
+level for each band reduced by 0.8, making it 32.2 dBm for EGSM and GSM850 and
+29.2 dBm for DCS and PCS, while all other levels are set to the spec numbers.
+
+In my own experience with getting the Tx power levels calibrated on our current
+FCDEV3B boards, our hardware is able to hit all of the lowest spec power levels
+with good margin (the APC DAC value never goes below the 60-70 range), hence
+the low targets did not need to be shifted, but the highest spec power level
+could not be achieved in every band.  Following TI's practice with LoCosto, I
+set the highest power level target to 32.2 dBm for the EGSM band and to 29.2 dBm
+for PCS, but I was consistently able to get the full 30 dBm out in the DCS band,
+hence I set the DCS band highest power level target to the official number of
+30 dBm.  It needs to be emphasized, however, that these results are quite
+specific to our current flock of FCDEV3B hardware, and your results will most
+likely be different if you are working with a different hw design such as a
+non-FreeCalypso derivative of Openmoko's GTA02 design.
+
+Profiles for Tx levels calibration
+==================================
+
+Our fc-rfcal-txband program that performs the actual per-unit calibration of Tx
+power levels for each band requires a preconfigured txlevels calibration profile
+for each band as one of its inputs; if you are performing calibration on
+individual units of a board design for which the correct profiles have already
+been crafted, you simply use those given profiles (fcom1 for our current flock
+of FCDEV3B boards), but if you are doing Tx power level calibration on a new
+board design for the first time, you first need to characterize the Tx output
+level behaviour of your new board design and craft the appropriate set of
+profiles.
 
-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.
+The profiles for txlevels calibration reside in /opt/freecalypso/rfcal/txlevels;
+each per-band profile is sought in a file named profile_name-band_number, where
+profile_name is the profile name argument given to fc-rfcal-txband and
+band_number is one of 850, 900, 1800 or 1900.  For example, the profile set for
+our current FCDEV3B hardware is named fcom1 ("FreeCalypso hardware, Openmoko-
+based, version 1"), this hw platform is 900/1800/1900 MHz triband, and the
+individual profile config files are fcom1-900, fcom1-1800 and fcom1-1900.
+
+Each profile provides two key pieces of data: the list of fixed APC DAC values
+to be used as the basis set for constructing the piecewise linear model, and
+the list of power levels in dBm that will be the targets for the calibration.
+
+Crafting the txlevels calibration profiles for a new board design
+=================================================================
+
+If you are working with a new (or new-to-you) board design with no previous Tx
+levels calibration experience, you need to begin by characterizing its Tx
+output level behaviour so you can determine what APC values are appropriate for
+the basis set, whether or not you need to shift the highest and/or lowest
+target levels from their nominal spec values, and if some target shifting is
+needed, which levels need to be shifted and by how much.
+
+The tool you will need for this investigation is fc-rfcal-txbasis.  It requires
+fc-cmu200d and rvinterf to be running, talking to the CMU200 and to the DUT,
+respectively, and it takes the band number (850/900/1800/1900) and a set of
+APC DAC values on the command line; no pre-existing txlevels profile is needed.
+It commands the DUT to transmit at each of the specified APC DAC values in turn
+and reports the power output levels measured by the CMU200.
+
+VERY IMPORTANT: You need to be very sure that your CMU200 or other measuring
+instrument is itself in good calibration standing, i.e., that the measurements
+it reports are trustworthy, and that the insertion loss in your cabling setup
+(all the way from the actual DUT's antenna connector or RF test port to your
+CMU200) really matches the numbers you have put in your cable configuration file
+(see Cable-config-howto).  If you fail to ensure these prerequisites, your
+fc-rfcal-txbasis observations will be meaningless, as the cable insertion losses
+are typically of the same order of magnitude as the transmitter differences you
+are trying to determine.
+
+You will need to run fc-rfcal-txbasis with a guesstimated set of APC DAC values,
+to be revised iteratively, and get a feel for what your DUT is putting out.
+Are you able to hit the lowest spec power level consistently while the APC DAC
+value remains well above zero?  Are you able to hit the highest spec power level
+as well, or does the measured power output fall short of this target no matter
+how high you crank the APC DAC?  These observations will tell you whether or not
+you need to shift the highest and/or lowest target power levels in your new
+txlevels calibration profile.
+
+Regular calibration runs
+========================
+
+Once you have a good set of profiles for the type of Calypso GSM device you are
+calibrating, just run fc-rfcal-txband with the band number and the name of your
+profile.
+
+Checking existing calibration
+=============================
 
 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.
+power measurement at each level, and displays the measured result.