--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/VCXO-vs-VCTCXO	Sun May 28 05:02:24 2017 +0000
@@ -0,0 +1,62 @@
+Some TI-based GSM mobile station devices use VCTCXOs (voltage-controlled,
+temperature-compensated crystal oscillators), while others use "plain" VCXOs
+without the TC part.  The Leonardo reference design for the Calypso+Iota+Rita
+chipset, adopted first by Openmoko and then by FreeCalypso, uses a "plain" VCXO,
+and the Rita RF chip itself was designed with non-TC VCXOs in mind, as it
+includes the active part of the XO on-chip, with the external VCXO circuit
+becoming purely passive.  The same Rita chip does support the option of
+disabling its internal active XO part and using an external VCTCXO; this
+approach is used in the Pirelli DP-L10 GSM+WiFi dual mode phone - but it is no
+longer Leonardo, and not properly supported by our available TCS211 reference
+firmware.
+
+However, it appears that Rita was TI's first RF chip to include the on-chip
+active part for a non-TC VCXO, whereas Clara (D-Sample) and earlier RF chips
+always required the VCXO or the VCTCXO to be external.  Furthermore, it appears
+that TI's original approach in the days of Sara RF (before Clara) was to use
+VCTCXOs mandatorily, then later they improved their AFC (automatic frequency
+control) algorithm to work with the cheaper non-TC VCXOs, and eventually the
+non-TC VCXO approach became standard.
+
+It also appears that the requirements for VC(TC)XO calibration changed with the
+transition from VCTCXOs to "plain" VCXOs: of the two TI calibration documents
+we have (see TI-docs), the Sara document seems to assume a VCTCXO, whereas
+LoCosto's DCXO is apparently more like the Leonardo VCXO.
+
+TI's Layer 1 sources we have include a C preprocessor symbol called VCXO_ALGO,
+defined to 1 in TCS211, and it is my (Mychaela's) guess that this preprocessor
+symbol enables the new code developed for non-TC VCXOs.  The dac_center,
+dac_min and dac_max fields in the afcparams table (T_AFC_PARAMS) exist only
+when VCXO_ALGO is nonzero, and these numbers are calibrated per unit on Openmoko
+devices.  Without VCXO_ALGO the afcparams table contains only Psi constants,
+and it is my guess that in the days of Sara VCTCXOs these Psi constants were
+calculated theoretically and hard-coded, rather than calibrated per unit, hence
+the lack of corresponding calibration instructions in the Sara
+rf_calibration.pdf document.  Only the "EEPROM" DAC value set with rfpw 10
+needed to be calibrated back then, apparently.
+
+It is not particularly clear to me whether or not the non-TC VCXO used with
+VCXO_ALGO really needs to be calibrated on a per-unit basis, or if it would be
+sufficient to calibrate it on a per-design basis and put these per-design
+calibrated values in the firmware image.  My own experience indicates that the
+frequency put out by the non-TC VCXO varies quite significantly with
+temperature, thus even if the factory calibration is done in a temperature-
+controlled chamber, it is not clear how much this calibration helps in
+subsequent end user operation when the phone can be used in a very cold
+environment or a very hot one, and must work flawlessly nonetheless.
+
+The truth may very well be that TI supplied their chipset customers with their
+standard production calibration software that includes the VCXO calibration
+step before Rx and Tx calibrations, and it was easier for the device
+manufacturers to just run this production calibration software as-is than to
+understand the meaning of various numbers in the afcparams table and come up
+with some good-for-all values.  TCS211 firmware does not work without VCXO
+calibration on Openmoko's modem or on our semi-clone thereof (FCDEV3B) because
+the hard-coded values of the Psi constants (which Openmoko couldn't change
+because they were shackled by binary-only libs) are too far from the correct
+values for the VCXO featured in this design, but the calibrated Psi values
+differ very little from one unit to the next.
+
+We no longer have the binary-only problem that Openmoko faced, but our current
+approach is to replicate Om's factory per-unit calibration procedures pretty
+closely, including the VCXO calibration.