--- a/doc/Compal-calibration	Mon Nov 20 06:10:54 2017 +0000
+++ b/doc/Compal-calibration	Mon Nov 20 16:24:22 2017 +0000
@@ -38,52 +38,61 @@
 c1xx-calextr -b rfbin flashdump.bin 0x3FC000
 
 The c1xx-calextr utility locates the RF calibration records in the flash dump
-binary, extracts the specific calibration values of primary importance (Rx
-"magic gain" and Tx APC DAC values), and converts them to TI's canonical format
-for use with FreeCalypso firmware.  The numeric argument after the flash image
-filename is the offset within that image file where the magic sector should be
-sought, and the -b option directs the tool to save the converted RF calibration
-tables in binary format (the alternative is -a for ASCII format) in the
-directory named after the option, named rfbin in this example.
+binary, extracts those calibration values contained therein which we are able
+to grok, and converts them to TI's canonical format for use with FreeCalypso
+firmware.  The numeric argument after the flash image filename is the offset
+within that image file where the magic sector should be sought, and the -b
+option directs the tool to save the converted RF calibration tables in binary
+format (the alternative is -a for ASCII format) in the directory named after
+the option, named rfbin in this example.
 
 If you use the binary output option as recommended here, the resulting output
 directory will have two subdirectories in it, named rx and tx.  The rx
-subdirectory will have two files named agcparams.BAND where BAND is 900 and 1800
-for EU-band phones or 850 and 1900 for US-band ones, and the tx subdirectory
-will have two files named levels.BAND.  This directory structure and these
-names for the binary files correspond directly to the /gsm/rf directory subtree
-in the flash file system (FFS) of TI's canonical solution, hence once the C1xx
-phone in question is converted to FreeCalypso (i.e., runs FreeCalypso fw with
-an aftermarket FFS created for it), you can upload the extracted and converted
-RF calibration values into it like this:
+subdirectory will contain agcparams and calchan tables for each band, and the
+tx subdirectory will contain a levels table for each band.  This directory
+structure and these names for the binary files correspond directly to the
+/gsm/rf directory subtree in the flash file system (FFS) of TI's canonical
+solution, hence once the C1xx phone in question is converted to FreeCalypso
+(i.e., runs FreeCalypso fw with an aftermarket FFS created for it), you can
+upload the extracted and converted RF calibration values into it like this:
 
 fc-fsio upload-subtree rfbin /gsm/rf
 
-Limitations
-===========
+Rx channel correction values
+============================
 
-In the traditional RF calibration procedure performed by most GSM phone and
-modem manufacturers including Motorola, the Rx "magic gain" and the Tx APC DAC
-values (Tx power levels) are calibrated for the center frequency of each band
-at first, and then additional measurements are performed at other frequencies
-within the band to arrive at channel-dependent corrections for both Rx and Tx.
-On devices that follow TI's canonical way of doing things, you can find these
-channel correction tables in /gsm/rf/rx/calchan.* and /gsm/rf/tx/calchan.*
-files in the FFS.
+A GSM phone or modem needs to know how to derive the actual input signal level
+in dBm from the power measurements reported by the DSP; the difference between
+the two is called the "magic gain" (GMagic), and the firmware needs to know
+what it is.  The primary GMagic value for each band is calibrated at the center
+frequency of that band, and then there are channel-dependent corrections
+applied.
+
+In TI's canonical solution the complete ARFCN range of each band is divided
+into up to 10 subbands, and each of these subbands gets its own channel
+correction value.  The ARFCN boundaries between the subbands are defined by the
+external calibration system and not by the firmware code, by virtue of being
+given inside the Rx calchan table itself along with the correction values.
+
+But Motorola/Compal have made two changes:
 
-However, in the case of C1xx phones, Mot/Compal have changed the way in which
-they do these channel corrections (both Rx and Tx) from TI's canon, and the
-channel correction values stored in their factory calibration records do not
-naturally translate to TI's Rx calchan and Tx calchan tables.
+* They increased the number of subbands from 10 (TI's canon) to 21 for the
+  GSM850 band, 30 for the EGSM band, 63 for DCS and 50 for PCS, so that each
+  subband is only 6 channels (1.2 MHz).
+
+* The ARFCN boundaries for the subbands are not stored in the calibration
+  records in the flash, but are fixed in the firmware instead.
 
-In the case of Rx calibration, Mot/Compal have calibrated the channel
-corrections with much finer granularity than is called for in TI's canonical
-version.  In TI's canon each band is divided into up to 10 subbands for the
-purpose of Rx channel compensation, but Mot/Compal used much narrower subbands
-of only 6 ARFCNs each, resulting in 21 subbands in the narrowest GSM850 band
-and 63 subbands in the widest DCS (1800 MHz) band.  We can see where the
-channel correction values for each of these tiny subbands are stored, but
-making use of them in FreeCalypso is not easy.
+Changing our FreeCalypso firmware to allow up to 63 Rx AGC subbands to match
+Mot/Compal's fw would be too disruptive, hence our current c1xx-calextr
+implementation translates Mot/Compal's Rx channel correction values to TI/FC
+format by combining groups of Mot/Compal's subbands into larger subbands, and
+making a mean value out of the smaller subband correction values in Mot/Compal's
+factory calibration record.
+
+The AGC subbands defined by Mot/Compal's fw are listed below, with each numeric
+line giving the ARFCN range of each subband; blank lines separate the groupings
+made by c1xx-calextr.
 
 850 MHz band:
 
@@ -296,3 +305,24 @@
 795-800
 801-806
 807-810
+
+Tx channel correction values
+============================
+
+A similar situation holds here: in TI's canon each band is divided into 8
+subbands for the purpose of Tx channel-dependent corrections, but Mot/Compal
+seem to be using smaller subbands: 13 for the GSM850 band, 18 for EGSM, 38 for
+DCS and 30 for PCS.  We can see where these correction values are stored in the
+calibration records in the flash (immediately after the Tx levels array), but
+the ARFCN boundaries of Mot/Compal's Tx channel calibration subbands are not
+known, and the semantics of the correction values themselves are not clear:
+Mot/Compal's Tx channel correction values are centered around 0, whereas in
+TI's canonical version they are centered around 128.
+
+Because we are not able to grok Mot/Compal's Tx channel correction, we currently
+ignore this part of their factory calibration, i.e., FreeCalypso fw will run
+with all channel correction values set to 128, meaning no channel correction.
+But since we do use the Tx levels table of APC DAC values from Mot/Compal's
+factory records, and given that the tolerances for Tx power levels given in the
+GSM 05.05 spec are quite generous, we expect to still be within these tolerances
+despite the lack of channel correction.