IMEI vs. IMEISV
===============

There is a subtle distinction between an IMEI and an IMEISV.  The first 14
digits are the same between the two: the supposedly-world-unique number of a
given piece of hardware.  In a traditional IMEI 15-digit number the significant
14 digits are followed by a Luhn check digit, whereas an IMEISV has 16 digits:
the 14 significant digits of the IMEI, *no* Luhn check digit, and two digits of
"software version".

It is up to device manufacturers and firmware designers to decide whether or
not to store the Luhn check digit in the GSM device's flash or EEPROM or
whatever, but it is not sent over the air: instead the IMEISV is sent.  It
appears that the GSM standard authors' intent was that the IMEI part is stored
immutably in each manufactured device whereas the SV digits are added by the
running firmware to indicate its version, but the IMEI handling scheme
implemented in TI's reference firmware and retained by many of the TI-based GSM
device manufacturers (at least FIC/Openmoko and Foxconn/Pirelli) dispenses away
with the IMEI vs. IMEISV distinction.

IMEI storage and retrieval in TI's reference firmware
=====================================================

When running on the plain Calypso as opposed to Calypso+, TI's TCS211 reference
firmware supports two ways of storing and retrieving the IMEI: obfuscated and
unobfuscated.  In both schemes the IMEI datum is stored as a file in the
device's flash file system (FFS), and even though the FFS filename calls it the
IMEI, the content of this file is really treated as the IMEISV: 16 digits are
stored, the firmware function responsible for reading the IMEI datum out of FFS
and passing it on to the rest of the fw is called cl_get_imeisv(), the code in
this function does not transform the 16 digits in any way, and the downstream
recipients of these digits treat them as the IMEISV.

The two specific schemes offered by TCS211 fw are as follows:

In the unobfuscated scheme (FF_PROTECTED_IMEI not defined), the so-called IMEI
but really IMEISV is stored in an FFS file named /pcm/IMEI.  The file is 8 bytes
long, each byte stores two IMEISV digits, and the order of the digits within
each byte is reversed relative to the natural order: first the least significant
nibble is used, then the most significant nibble.

In the obfuscated scheme (FF_PROTECTED_IMEI is defined), the so-called IMEI but
really IMEISV is stored in an FFS file named /gsm/imei.enc.  The file is 16
bytes long: the first 8 bytes store the 16-digit IMEISV encrypted with DES,
using the Calypso die ID as the key, and the last 8 bytes store that Calypso die
ID DES-encrypted with itself.  Underneath the obfuscation, the 16 IMEISV digits
are stored in the 8 bytes in the natural order: first the most significant
nibble is used, then the least significant nibble.

IMEI storage and retrieval schemes implemented by device manufacturers
======================================================================

Openmoko devices use the unobfuscated IMEI storage method unchanged from TI's
reference fw: the factory-assigned IMEI is stored in an FFS file named
/pcm/IMEI, and that is where the original mokoN firmwares look for it.  Further
blurring the distinction between the IMEI and the IMEISV, the 16 digits stored
in /pcm/IMEI (which the fw treats as the IMEISV) were factory-programmed as the
15-digit IMEI (with the Luhn check digit) with an appended 0, i.e., the SV
digits get set to x0 where x is the Luhn check digit.

Foxconn, the makers of the Pirelli DP-L10, have used the obfuscated version of
TI's IMEI handling mechanism instead, with an additional twist: instead of
storing the 16-byte encrypted datum in /gsm/imei.enc in FFS, they have moved it
into their own factory data record stored in a non-FFS sector of the flash.
The content of the 16 digits treated as the IMEISV by the G23M component of the
fw is the same as Openmoko's: 15-digit IMEI with the Luhn check digit followed
by a 0 digit.

Compal, the makers of Motorola C1xx phones, have similarly moved their IMEI out
of FFS into their own proprietary flash data structures, and we have never
decoded the latter, hence we don't know exactly where and how their IMEI is
stored.  If you wish to run FreeCalypso firmware on these phones, you have to
set your own IMEISV for our fw even if you are not seeking to make it different
from the factory-assigned one, as we don't know how to retrieve the latter.

Changing the IMEI
=================

When someone says that they wish to change the IMEI on their phone, they need
to be a little clearer as to what they really mean, as there are two possible
interpretations of the just-stated wish:

1. Transmitting a different IMEISV toward the network by running your own
   firmware on the device,

or

2. Changing the IMEI seen by the device's original proprietary firmware.

Interpretation 1 is much easier than interpretation 2: when you are writing your
own firmware for an "alien" GSM device (hardware designed and made by someone
other than you), it is much easier to just set your own IMEISV and be done with
it than to figure out how to retrieve the factory-assigned one.  Thus those
device manufacturers who try to make it more difficult to change their IMEIs
are actually creating the opposite effect: people will just set their own IMEISV
when running their own fw on their hw.

Openmoko devices are a rare exception in that if you write your own IMEISV into
/pcm/IMEI in FFS, your new IMEISV will take effect not only with FreeCalypso
firmware, but also with the legacy mokoN fw versions, because they all look in
/pcm/IMEI.  The same does NOT hold with Compal/Motorola or Foxconn/Pirelli
phones, however: if you wish to change their IMEI to be seen by their original
proprietary firmwares, you are on your own, as we do not currently have any
tools for accomplishing such a feat.

IMEI handling in FreeCalypso
============================

The FreeCalypso family of projects has adopted the following IMEI storage and
retrieval scheme both for our own FreeCalypso-made hardware and for FreeCalypso
firmwares running on alien hardware: all of our firmware versions regardless of
target will look first in /etc/IMEISV, then in /pcm/IMEI when needing to obtain
the IMEISV for GSM operation.  This is the new unified convention; previously
we used varying IMEISV retrieval schemes depending on the target and in
different FC firmware projects.  The new unified convention is backward-
compatible with our previous schemes on every target.

The /etc/IMEISV file is a FreeCalypso invention.  The file is 8 bytes long, and
stores the 16 digits of the IMEISV in the natural order: first the most
significant nibble is used, then the least significant nibble.  This nibble
order makes the IMEISV number directly readable in a hex dump of the file, and
the filename /etc/IMEISV makes it clear that the last two digits are the SV and
are not required to be equal to the Luhn check digit and 0.

Both /etc/IMEISV and /pcm/IMEI can be written with the fc-fsio utility's
set-imeisv command:

set-imeisv fc  XXXXXXXX-YYYYYY-ZZ	# write /etc/IMEISV
set-imeisv pcm XXXXXXXX-YYYYYY-ZZ	# write /pcm/IMEI

When working on Openmoko devices, we recommend writing your IMEISV into
/pcm/IMEI (set-imeisv pcm command) and not creating an /etc/IMEISV file: newer
FC firmware versions will look in both locations, but older FC fw versions and
the legacy mokoN ones look only in /pcm/IMEI.  On all other targets we recommend
using the new /etc/IMEISV storage format, i.e., you should use the set-imeisv fc
variant.