Running FreeCalypso VPM firmware on a Pirelli DP-L10 phone is much easier and
much more convenient than doing the same on Mot C1xx.  There are two principal
reasons for this difference:

* Pirelli DP-L10 has huge RAM (8 MiB), allowing our FC aftermarket fw to run
  entirely in RAM (fc-xram) without flashing.

* In the flash layout used by official fw, there is an area that is used only
  for high-level firmware updates over WLAN (as opposed to "surgical" firmware
  reflashing with fc-loadtool) and remains unused otherwise.  We put our
  aftermarket FFS in this part of the flash, and this aftermarket FFS just stays
  there, untouched by Pirelli's official fw, in between fc-xram sessions that
  run FC VPM fw.

This article explains how to initialize the aftermarket FFS for FreeCalypso fw
on your Pirelli phone, and how to actually run the VPM fw afterward.

Required software components
============================

You will need the following 4 FreeCalypso software packages installed on your
host machine:

1) FC host tools base package:

   ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2

2) FFS data bundle add-on:

   ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-data-bundle-latest.tar.bz2

3) FFS editing agent target binaries:

   ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-editor-latest.tar.bz2

4) The present fc-am-toolkit package.

All 4 packages install all of their files under the /opt/freecalypso directory
tree defined by the Mother, and you only need to do this host software
installation once (or when updates come out), irrespective of how many phones
of various kinds (both Pirelli DP-L10 and Mot C1xx) you are going to work with.

Working with Pirelli phones: general principles
===============================================

In order to work with a Pirelli DP-L10 phone in any interesting way, you need
to connect it to your host computer via USB.  However, USB VBUS rail is also
used as the charging power source on this phone, hence any time USB is
connected, the Calypso+Iota chipset gets the "charger inserted" condition
applied to it, and is not allowed to be fully switched off.  The solution
adopted by the Mother of FreeCalypso consists of using the "booted for charging
only" mode of Pirelli's official fw, plus the -Petmoff mechanism added to
loadtools in fc-host-tools-r19.

Like all standard handset firmwares, Pirelli's official fw has two fundamental
operating modes in terms of power on/off control: it can be fully booted, in
which case GSM functionality is brought up (network registration, or if there
is no SIM, camping on whatever cell it can find for the possibility of an
emergency call), or it can be booted for charging only.  If you plug USB into a
fully switched-off Pirelli phone, the firmware will boot, but it won't do
anything other than manage the charging process - that is what we call "booted
for charging only" mode.  Another way to enter this mode is to plug USB into the
phone while it is in fully booted state (with menus working normally), and then
execute the power-off sequence.  The firmware will actually command the same
regular soft power-off as it would in the absence of charging, but the presence
of VCHG (coming from USB VBUS) causes the chipset to immediately do another
switch-on - and then the firmware boots again, this time for charging only.

When the firmware is booted for charging only (and you don't give it the
additional button press that ungates full boot), all GSM functionality is off
(the SIM interface is powered off, and no radio bring-up is done, not even for
emergency mode), but the RVTMUX interface is fully working.  Pirelli's fw
includes ETM, and we can send it an ETM ABB write (abbw) command that writes to
the VRPCDEV register in the Iota chip, commanding switch-off.  We can make this
intrusion into Pirelli's fw in any state, but doing so in the regular fully
booted state (basically killing the running fw by brute force) is obviously bad.
However, when the fw is booted for charging only, killing it in this manner
causes no harm, as there is nothing running besides the charging process - and
the Iota chip does turn off charging when this switch-off is executed.

Thus comes our general principle: whenever you wish to use your Pirelli DP-L10
phone for playing with FreeCalypso VPM, begin by putting it into the "booted
for charging only" state.  If you started with the phone off, simply plug in USB
but don't press the "On" button, and if you started with the phone on, you can
plug in USB and then turn it off.  When the phone is in this state and you need
to run fc-loadtool, fc-simint, fc-xram or any other loadtools program, run your
fc-loadtool or fc-xram etc command with an added -Petmoff option, and then you
don't need to do any manual manipulations on the phone: the Calypso boot ROM
entry will happen as soon as you execute the command on the host.  And when your
fc-loadtool or fc-simint session cleanly finishes, or when you finish an FC VPM
fw session with fc-shell poweroff or AT@POFF, the phone will return to the same
"booted for charging only" state - very convenient!  This "booted for charging
only" state, running Pirelli's official fw in the flash, thus becomes the
"ground" state for FreeCalypso manipulations, corresponding to the fully
switched-off state on a Mot C1xx phone or a traditional TI/FC dev board.

Aftermarket FFS initialization
==============================

To initialize the aftermarket FFS for FC firmware on your Pirelli phone,
execute this command:

pirelli-init-fc-ffs /dev/ttyUSB0

(Change ttyUSB0 to other ttyUSBx if needed.)

This command is a shell script, the script begins with an fc-loadtool batch
operation erasing the aftermarket FFS area, and that fc-loadtool batch command
invokation is made with -Petmoff option described in the previous section -
thus the phone needs to be in "booted for charging only" mode when you run that
pirelli-init-fc-ffs command.

After erasing the aftermarket FFS area with fc-loadtool, our pirelli-init-fc-ffs
script runs our FFS editing agent via fc-xram, and then does the actual FFS
initialization via fc-fsio.  An fc-fsio command script stashed in
/opt/freecalypso/scripts/pirelli-am-ffsinit (installed by the present
fc-am-toolkit package) contains the actual magic commands, and these commands
populate the FFS with files that come from FC FFS data bundle package.

You can rerun this pirelli-init-fc-ffs operation at any time, if you need to
reset the aftermarket FFS to its pristine state or if you got an updated version
of the relevant files in the FFS data bundle.

Running VPM firmware
====================

To run FC VPM firmware, once your Pirelli phone is in "booted for charging only"
mode and the aftermarket FFS has been initialized as above, execute a command
of this form:

fc-xram -h pirelli -Petmoff /dev/ttyUSB0 path/to/ramimage.srec rvinterf

The FC firmware image needs to be ramimage.srec; to build this image format (if
you are compiling your own fw, rather than using a released build), run
'make ram' in the firmware build directory.  (By default the firmware build
system produces flash images on all targets, but on the Pirelli target you
really don't want to flash this fw - hence the need to run 'make ram'
explicitly.)

When you run the above command, the firmware image will be loaded into XRAM and
jumped to.  The command is structured so that fc-xram will then pass the serial
communication channel to rvinterf, and from that point on you have a regular
rvinterf session, talking to an in-RAM (not flashed) firmware instance.  The
principles and guidelines for exercising the GSM MS as a VPM are the same as
described in the C1xx-VPM-usage article for C1xx phones - please refer to that
article.

Instead of checking for a present rvinterf process via keepalive packets, the
Pirelli DP-L10 version of our VPM firmware periodically (every 10 s) checks
for still-present USB connection, by checking the "charger present" status bit
in Iota VRPCSTS register.  If it detects USB unplug, it performs an immediate
power-off - and because the firmware is not flashed, only loaded in RAM, the
next boot cycle (be it the power button or USB plug-in) will return the phone
to its regular official fw.