--- a/doc/Tx-cal-theory	Wed Feb 14 02:18:20 2018 +0000
+++ b/doc/Tx-cal-theory	Wed Feb 14 03:46:34 2018 +0000
@@ -25,7 +25,12 @@
 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.
+set of APC DAC values.  Looking at the Vout/LSB slope in each segment of this
+constructed piecewise linear function, one can see that the relation stays
+mostly linear throughout most of the RF PA's valid control range, and at least
+in the case of GSM MS devices made by Openmoko, the factory-calibrated power
+levels all fall into this "good" range in which the PA's response to the APC DAC
+control value is mostly linear.
 
 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
@@ -54,7 +59,7 @@
 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
+PCS, in 2 dB 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
@@ -75,16 +80,36 @@
 level at 7 dBm instead of 5 dBm, and the lowest DCS and PCS power levels at
 3 dBm instead of 0 dBm.
 
-It appears that OM/FIC were using some TI-provided calibration software without
-taking the time and effort to tune its settings for their own hardware: when we
-recalibrate these OM-made devices in our own lab, we are able to hit all of the
-highest and lowest power levels given in the GSM 05.05 spec.  On our own FCDEV3B
-hardware we are likewise able to get the full 30 dBm in the DCS and PCS bands,
-but we are not able to get the full 33 dBm in the low band.  Following TI's
-practice with LoCosto, I set the highest power level target to 32.2 dBm for the
-EGSM and GSM850 bands; for DCS and PCS the highest power level target is 30 dBm
-per the spec.  On the low end the power level targets are the official ones
-from the GSM 05.05 spec.
+When it comes to the highest power levels, my (Mychaela's) first thought was
+that OM's calibration had them reduced to 31.8/28.8 dBm for no good reason other
+than OM/FIC mindlessly using some TI-provided calibration software that had
+those settings by default, as a leftover from some much older hw platform that
+was poorer in this department than OM's GTA0x hardware.  As a matter of fact,
+it *is* possible to make an Openmoko-made GTA02 device put out the full 33 dBm
+in the EGSM band and the full 30 dBm in the DCS and PCS bands by setting the
+APC DAC to higher values than those used by OM's factory calibration.  However,
+a closer look reveals that those higher-than-OM's APC DAC values which produce
+the full 33/30 dBm output put the PA outside of its linear range, i.e., the
+relation between the APC DAC control value and the resulting RF Vout no longer
+has the same linearity as is maintained at the lower power levels.  In our own
+FreeCalypso calibration, we used to set the higher 32.2/29.2 or even the full
+33/30 dBm targets for the highest power levels prior to the discovery of the
+linearity issue, but our current rf3166 profile set (see below) uses the same
+conversative upper-end targets as OM's original: 31.8/28.8 dBm for the highest
+power level and 30.5/27.5 dBm for the next one down.
+
+When it comes to the lowest power levels, the empirical observation is that the
+official spec bottom power levels of 5 dBm for the low bands and 0 dBm for the
+high bands are perfectly attainable both on Openmoko-made units and on our own
+FCDEV3B, with APC DAC values that are only a tiny bit lower than the lowest
+values in OM's calibration.  We currently use 70 as the lowest basis point in
+the EGSM and GSM850 bands and 60 as the lowest basis point for DCS and PCS,
+following the LoCosto document; we are consistently able to get 5 dBm for the
+low bands or 0 dBm for the high bands within our basis range, and examination
+of the piecewise Vout/LSB slopes shows that the PA appears to be happily linear
+in this range.  Therefore, we use the official spec numbers for the lowest
+power level targets in our current rf3166 profile set, not the raised target
+numbers from TI's older platforms.
 
 Profiles for Tx levels calibration
 ==================================
@@ -93,19 +118,20 @@
 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 (see the txlevels directory
-in the source tree for our current offerings), 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.
+been crafted, you simply use those given profiles (rf3166 for Openmoko and
+OM-based FreeCalypso hardware), 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.
 
 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, if you are using
-the rf3166-ideal profile set (appropriate for recalibrating Openmoko GTA02
-devices), the individual profile config files are rf3166-ideal-900,
-rf3166-ideal-1800 and rf3166-ideal-1900 for the tri900 band configuration.
+the rf3166 profile set (appropriate for recalibrating Openmoko GTA02 devices
+and for factory production of new FreeCalypso devices with the same RF PA), the
+individual profile config files are rf3166-900, rf3166-1800 and rf3166-1900 for
+the tri900 band configuration.
 
 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