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

The Pirelli DP-L10 is a neat target for playing with FreeCalypso for two
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.

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

When compiling our Magnetite firmware for the Pirelli target, you will need to
select the l1reconst configuration - it is the only currently available
configuration that works on this target.  Therefore, you configure.sh command
should be:

./configure.sh pirelli l1reconst

To build a RAM-loadable image for the Pirelli, run 'make ram' in the build
directory created by the configure script - see the Compiling write-up for
more details.

Because we have not deblobbed the G23M firmware component yet (the l1reconst
configuration uses G23M binary blobs from TCS211/Sotovik), your Magnetite fw
build will include FAX_AND_DATA and GPRS functionality.  In the FreeCalypso
environment where we are not doing WAP or MMS this functionality can only be
exercised on targets that bring out a classic modem UART with the classic AT
command interface to the external host, but the Pirelli is not one of those
targets - hence on this target all FAX_AND_DATA and GPRS code is nothing but
dead weight.  We will only be able to remove this dead weight when and if we
fully deblob all of L1 and G23M, so it will be a while before we get there,
and we'll have to carry the dead weight until then.

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: the following instructions are based on the new version of fc-fsio that
  has not yet made its way into a packaged fc-host-tools release as of this
  writing.  Therefore, please get the latest development version here:

  https://bitbucket.org/falconian/freecalypso-tools

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.