Running FreeCalypso Magnetite firmware on the Pirelli DP-L10
============================================================

The Pirelli DP-L10 is a neat target for playing with FreeCalypso for a few
reasons:

1. It has a USB port connected to one of Calypso's UARTs through a built-in
   CP2102 USB-serial adapter, eliminating the need for headset jack serial
   cables.

2. The huge RAM on this phone (8 MiB) makes it possible to run experimental GSM
   firmware images entirely in RAM without flashing - and we have successfully
   implemented this capability in FC Magnetite similarly to Citrine.

3. Running an experimental firmware image on the Pirelli requires nothing more
   than a laptop, a phone and a USB cable, and can therefore be done under
   less-than-ideal conditions while away from your proper FreeCalypso hardware
   lab with an FCDEV3B setup.

There is, however, one difference between our Citrine and Magnetite firmwares
when it comes to running on the Pirelli without flashing: Citrine uses a
RAM-based fake FFS, whereas Magnetite always requires a real FFS in flash, even
when the firmware code image itself is entirely RAM-based.  However, just like
on the C139, we do NOT use the same FFS which is used by Pirelli's official
firmwares - the latter contains nothing of use to our fw, hence it is best for
us to use our own separate FreeCalypso Magnetite FFS.

The flash location that's been chosen for Magnetite FFS on the Pirelli is
0x02480000 through 0x025FFFFF, i.e., offsets 0x480000 through 0x5FFFFF in the
second flash bank.  Pirelli's official firmwares use this flash area as
temporary storage during OTA (over-the-air, probably WLAN in this case) fw
reloads and leave it untouched at all other times, therefore as long as you are
not doing firmware reloads over WLAN while in the "official mode", you can use
your Pirelli phone for FreeCalypso experiments via fc-xram and go back to the
regular fw in between, and the Magnetite FFS in the flash will be preserved
from one fc-xram session to the next, not disturbed by Pirelli's fw.

Compiling
=========

We don't have a FreeCalypso firmware offering for the Pirelli that makes it
work as an untethered phone, and probably never will: there is too much
undocumented peripheral hardware in this phone.  Instead a Pirelli phone
running our FC Magnetite firmware will act as voice pseudo-modem: the LCD will
stay dark and the buttons will do nothing, and you will need to control the GSM
MS from your PC or other host system via AT commands.

As explained in the Voice-pseudo-modem article, the two most sensible firmware
configurations (in the ./configure.sh sense) for VPM targets are hybrid-vpm and
l1reconst-chg.  Because of the huge RAM, you can also compile and run our more
traditional configurations intended for proper modems like FCDEV3B (l1reconst,
hybrid or hybrid-gpf), but all data services functionality of those fw configs
(CSD and GPRS) will remain inaccessible (dead weight) when running on the
Pirelli.  Furthermore, our FreeCalypso battery charging code is only included
in the special hybrid-vpm and l1reconst-chg configs, not in the traditional
ones.

Run './configure.sh pirelli l1reconst-chg' or
'./configure.sh pirelli hybrid-vpm' depending on which configuration you would
like to play with, then run 'make ram' in the build directory created by the
configure script - see the Compiling write-up for more details.

Running on the target
=====================

1. Connect a USB cable from your GNU/Linux PC/laptop to the phone.  If the
   phone was off but the battery is present, it will go through a charger-plug
   power-on event; if the flash contains Pirelli's original fw, it will boot in
   the charging mode.  If the battery is not present, the Calypso won't power
   on (it needs VBAT and can't run on VCHG power instead), but the /dev/ttyUSBx
   device will still show up, as the CP2102 USB-serial chip inside the phone is
   powered strictly from the USB side.

2. Run a command like the following:

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

   Adjust the paths to your /dev/ttyUSBx device and your ramimage.srec as
   appropriate, and add rvinterf logging or other options as desired.
   Specifying rvinterf on the fc-xram command line directs fc-xram to exec
   rvinterf and pass the serial channel to it immediately as soon as the code
   image has been loaded into target RAM and jumped to; this direct passing of
   the serial channel from fc-xram to rvinterf is appropriate because the
   loaded fw will immediately start emitting binary trace packets in TI's RVTMUX
   format.

3. Induce the phone to execute its Calypso boot path: if the battery was
   removed, insert it now; if Pirelli's regular fw is running, execute its
   power-off sequence.

Once the Calypso chip in the Pirelli phone executes its boot path with fc-xram
running, the boot path will be diverted and our experimental firmware will be
loaded into target device RAM and jumped to.  Our fw will now run, and the
rvinterf process on the host will maintain communication with it.

FFS initialization
==================

When our Magnetite firmware boots, it will examine the state of the flash
sectors in the area we have allocated for our aftermarket FFS.  If this flash
area is completely blank the first time Magnetite boots, as it should be if you
have a "virgin" Pirelli phone, the FFS code in our fw will automatically perform
what TI called the "preformat" operation: write undifferentiated FFS block
headers (0xBF in the flags byte) into each flash sector.  However, it won't
automatically perform the "format" operation - instead you'll need to run
fc-fsio to do the format and to populate this FFS with some necessary content.
If you are not sure of the state of the Magnetite FFS flash area on your
Pirelli, you can also run fc-fsio to examine it - so run fc-fsio either way.
Run fc-fsio WITHOUT -p: let it connect to the rvinterf process you should
already have running from fc-xram.

[NOTE: you need to be running FreeCalypso host tools from the fc-host-tools-r5
release or later; earlier versions of fc-fsio won't work as described.]

Once you are in fc-fsio, check the status of your FFS like this:

fsio> ls -l /

If the FFS is already formatted, you will get a listing of the root directory;
if it is not formatted, you'll get an error like this:

opendir: FFS error 4 (EFFS_NOFORMAT: ffs not formatted)

To format and initialize your Pirelli Magnetite FFS, issue the following
commands:

fsio> format /
fsio> pirelli-magnetite-init

If you already have a formatted FFS from before, it is safe to rerun the
pirelli-magnetite-init command, but not format.  The format command will *not*
work on an already formatted FFS; if you have a messed-up FFS and you would
like to restart from a clean slate, erase the Magnetite FFS sectors with
fc-loadtool:

loadtool> flash2 erase 480000 180000

Exercising the GSM functionality
================================

Once your FFS is good, open another terminal window on your driving PC/laptop
and run fc-shell.  This program will connect to the already running rvinterf
process via a local socket, and it will enable you to send various commands to
the running fw on the target, the most important ones being standard AT
commands.  Send the following sequence of AT commands to bring up GSM
functionality:

AT+CMEE=2	-- enable verbose error responses
AT+CFUN=1	-- enable radio and SIM interfaces
AT+COPS=0	-- register to the default GSM network

When you are done playing with our experimental fw, you can either yank the
battery and kill the host side rvinterf and fc-shell processes, or you can
issue a 'tgtreset' command at the fc-shell prompt.  The latter will cause the
target to reset and boot back into its regular firmware.

A recent addition to our VPM firmware configuration is automatic power-off: if
you simply disconnect USB while our FC Magnetite VPM fw is running, without
issuing any tgtreset or poweroff commands and without yanking the battery, our
firmware should detect the disconnection of USB and power off the phone within
10 s.