--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Compal-calibration	Sun Nov 19 21:45:12 2017 +0000
@@ -0,0 +1,86 @@
+Reading factory RF calibration values out of Mot C1xx phones
+============================================================
+
+Motorola C1xx phones are based on the Calypso+Iota+Rita chipset from TI and
+their firmware is also loosely based on TI's reference, but Compal (Motorola's
+ODM and the maker of these phones) have made lots and lots of changes moving
+away from TI's canonical way of doing things.  When it comes to RF calibration,
+Mot/Compal have performed it on each individual unit on their factory production
+line just like all other GSM phone and modem manufacturers, but instead of
+storing the results of this calibration in TI's flash file system, Mot/Compal
+have put these calibration values into a completely different flash data
+structure of their own invention.
+
+We don't know the proper name for Mot/Compal's flash data structure that has no
+counterpart in TI's canonical solution, but we know its location in the flash:
+
+* On C1xx phones with 2 MiB flash (most C11x/12x variants), it is the 8 KiB
+  flash sector at 0x1FC000;
+
+* On C139/140 phones and the rare C11x/12x variants with 4 MiB flash, it is the
+  8 KiB flash sector at 0x3FC000;
+
+* On C155/156 phones with 8 MiB flash, the data structure in question is
+  contained in the first 8 KiB of the 64 KiB physical flash sector at 0x7E0000.
+
+The flash sector in question contains record-structured data; we don't know the
+meaning of most of these records, but we have been able to find the RF
+calibration records among them and locate the actual calibration values of
+interest inside those records.
+
+In order to extract the RF calibration values from your C1xx phone for use with
+FreeCalypso, you will need a dump of your phone's flash, or at least a dump of
+the specific 8 KiB sector at the model-dependent offset given above.  As a
+specific example, if your phone is a C139/140 or a C11x/12x variant with 4 MiB
+flash and you have a complete dump of that flash, execute a command like the
+following:
+
+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.
+
+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:
+
+fc-fsio upload-subtree rfbin /gsm/rf
+
+Limitations
+===========
+
+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.
+
+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.
+
+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.

--- a/doc/Host-tools-overview	Sat Nov 18 18:02:42 2017 +0000
+++ b/doc/Host-tools-overview	Sun Nov 19 21:45:12 2017 +0000
@@ -50,6 +50,12 @@
 		phones that exercises their peripheral hardware: LCD, keypad
 		backlight, buzzer and vibrator.
 
+c1xx-calextr	This utility extracts the factory RF calibration values for
+		Mot C1xx phones from the records contained in a special sector
+		of their flash and converts them to FreeCalypso format, to be
+		used when running our own firmware on these phones.  See the
+		Compal-calibration article for more details.
+
 ctracedec	GSM firmwares built in TI's Windows environment (official ones
 		as well as our own hacks based on the TCS211 semi-src) have a
 		"compressed trace" misfeature whereby many of the ASCII strings