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

When compiling our Magnetite firmware for the Pirelli target, you can select
one of two configurations: l1reconst or hybrid; see the Modem-configs article
for the explanation.  In both cases the phone will act as an AT-command-
controlled 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.

Run './configure.sh pirelli l1reconst' or './configure.sh pirelli hybrid'
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.

Because we have not yet produced a configuration with FAX_AND_DATA and GPRS
disabled, your Magnetite fw build will include those components.  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.  Now that we have deblobbed all of L1 with the
exception of GPRS-specific modules, we could try building a hybrid config with
GPRS and FAX_AND_DATA excluded, specifically for the benefit of Mot C1xx and
Pirelli targets, but these legacy hardware targets are no longer a priority for
the FreeCalypso family of projects.

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.