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.  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
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 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
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.

The calibration that was performed by Openmoko's factory (FIC?) on their GTA02
units is similar to what the old Sara document calls for: the highest power
level is set to 31.8 dBm for EGSM or GSM850 and to 28.8 dBm for DCS and PCS,
the next one down is 30.5/27.5 dBm instead of 05.05-spec-given 31/28 dBm, and
for the lowest 4 (EGSM or GSM850) or 6 (DCS and PCS) power levels the decrement
between levels is 1.5 instead of 2, putting the lowest EGSM or GSM850 power
level at 7 dBm instead of 5 dBm, and the lowest DCS and PCS power levels at
3 dBm instead of 0 dBm.

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
==================================

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 (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 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
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
and instrument errors 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.

2018-02 addition: fc-rfcal-txbasis takes a new command line option -l; this
option causes it to compute and print the Vout/LSB slope after the second and
subsequent basis points; this option is useful for studying the linearity of
the RF PA's response to APC DAC control values.

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.

Channel correction calibration
==============================

The APC DAC values given in the levels tables apply directly only to the
channels in the centre of each band.  The transfer function from APC DAC control
values to power output levels in dBm depends on the frequency, and the APC DAC
values need to be adjusted for different subbands within each band in order to
produce the correct output power levels for all channels.  TI's RF driver code
and calibration data structures provide for a Tx channel calibration, and all
historical commercial manufacturers of Calypso GSM devices that are known to us
have performed this Tx channel calibration on a per-unit basis on their
production lines.

Our fc-rfcal-txband calibration tool implements Tx channel correction
calibration as of 2018-02, and we do it a little better than the way it was done
by the big folks Back In The Day.  TI's RF data structures allow for up to 4
channel calibration tables, to be used for different power levels, but
Openmoko's factory only did one channel calibration set (calibrated at the
highest power level for each band), using only one table out of the possible 4,
and this one table (calibrated at the highest power level) is then used for all
power levels.  As far as we can tell, other Calypso GSM device manufacturers
have done likewise.

Our Tx calibration implementation makes use of all 4 available channel
correction table slots.  We divide the 15 power levels of EGSM and GSM850 bands
or the 16 power levels of DCS and PCS into 4 groups (5-7, 8-11, 12-15, 16-19
for EGSM and GSM850; 0-3, 4-7, 8-11, 12-15 for DCS and PCS), perform channel
calibration at the highest power level in each group, and set the resulting
channel calibration table to be used for all 3 or 4 power levels in that group.
Our procedure produces Tx behaviour that is identical to Openmoko's for the
highest 3 or 4 power levels, but the lower power levels run with channel
calibration that was made closer to them, as opposed to the very highest power
level.  The price of our approach is more time spent in RF calibration for each
unit on the production line, but our approach is perfectly suited for low volume
production and aftermarket recalibration services.

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.  By default
the test is performed at the centre frequency of the specified band, but the
ARFCN to be used can also be specified on the command line.