The Tx power levels put out by a GSM mobile station are subject to strict
specifications, and on the Calypso+Iota+Rita chipset they are produced by
writing different values into the APC DAC register.  But what value should be
written into the APC DAC in order to produce a given Tx power level in dBm?
The answer varies from one produced device unit to the next, and even more from
one board design to the next, hence these APC values need to be calibrated.

The general procedure for calibrating Tx power levels is described in both Sara
and LoCosto calibration documents (see TI-docs), but the LoCosto document adds
one crucial detail which the Sara one fails to describe.  The instructions given
in the Sara document appear to be perfectly intuitive at first: go through all
power levels in turn (PL numbers 5-19 for EGSM and GSM850 or 0-15 for DCS and
PCS), and for each power level command the DUT to transmit at that level,
measure the actual Tx output power with the CMU200 or other RF test equipment,
and adjust the APC DAC value up or down to make the output power match the spec.

The problem is with the very last part: the output power you get with the
compiled-in APC DAC value is one number, the spec-defined target power is a
different number, exactly how do you adjust the APC DAC value to hit the target
power level?

The LoCosto document gives the answer which was not at all obvious to me at
first.  I draw the reader's attention to section A.3.1 on page 43 of that
document.  The trick is as follows: the relation between the APC DAC value and
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.

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
as the LoCosto document version.  If you look at the /gsm/rf/tx/levels.900 table
in Om-calibrated GTA02 units and compare it against the firmware's compiled-in
version, you will see that the APC DAC values for power levels 5-19 have been
replaced with calibrated ones as expected, but there is also this oddity: the
APC DAC value for power level 0 (not a valid number for this band) has been
replaced with 600.  Always 600, a perfect round number, on every unit.

Having understood the calibration method described in the LoCosto document, the
mystery of this fixed number 600 becomes clear: the calibration program
establishes the basis for the calibration by temporarily overwriting the APC DAC
value in the power level 0 slot with a series of fixed values, 600 being the
last of them.  It constructs the piecewise linear model for the APC from power
measurements made with these fixed DAC values, and uses this model to compute
the DAC value for each target power level.  The latter DAC values are then
written into Tx levels table slots 5-19 for EGSM and GSM850, or 0-15 for DCS
and PCS.  In the case of DCS and PCS no visible artifacts remain from the
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.

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.

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.