About the Pirelli DP-L10 target
===============================

The Pirelli target is currently seen as a dead end for future FreeCalypso
development.  The hardware is very attractive from an end user's perspective
(nice LCD, hands-free loudspeaker, USB port that combines charging with serial
data access by way of a built-in CP2102), thus we had high hopes for a long
time of being able to turn these Pirellis into libre phones by putting our own
aftermarket firmware on them.  However, the following serious problems make
this prospect less and less likely:

* The inexplicable behaviour around deep sleep will probably be a show-stopper
  to any attempts at on-board UI integration.  Experiments revealed that even
  when running TCS211 fw with deep sleep that works on other targets, deep sleep
  must be disabled on the Pirelli, otherwise the phone spontaneously reboots.
  Obviously Pirelli's own fw does something to avoid this problem, as it uses
  deep sleep just fine, but we don't have any source for their fw, hence it
  doesn't help.  However, if one disables deep sleep at compile time (in
  cst_pei.c), then something else breaks - the DSP fails in non-understood ways
  when trying to find a GSM network to connect to.  So it's a "damned if you do,
  damned if you don't" situation with deep sleep on the Pirelli target.  The
  only approach that works is to build the fw with deep sleep enabled at compile
  time, but then disable it with AT%SLEEP=2 before issuing AT+COPS=0.  This
  method is tolerable for manual AT command operation, but I have very little
  confidence in being able to make it work with phone UI integration.

* We never attempted to play at all with Pirelli's Winbond W56940 MIDI player
  and loudspeaker driver chip.  Even if one is willing to sacrifice the hands-
  free loudspeaker function (which is one of the main attractions of the Pirelli
  over Mot C139), the loudspeaker is still needed in order to play ringtones -
  a phone that can't ring won't be very useful.  Whether we want to play MIDI
  ringtones through the W56940 itself or put that chip into the same analog
  pass-through mode in which Pirelli's own fw must put it for loudspeaker calls
  and play Melody E1/E2 ringtones through the Calypso DSP, either way some
  programming of the W56940 will almost certainly be required.  When I tried to
  trace out the PCB connections to this chip, a red flag was raised: its reset
  line appears to be driven by what seems to be a GPIO off the SPCA552E camera
  chip.  There are no docs for the latter, hence it is not clear if we'll be
  able to control the reset line to the W56940, and without it we may be out of
  luck as far as emitting a ringtone from the loudspeaker.

* There is a lot of complex and unwanted (from our perspective) hardware in the
  Pirelli DP-L10 dealing with its non-GSM functions (WLAN and camera); this
  hardware is completely undocumented and there are no schematics for the phone.
  Trying to build a libre phone atop of an undocumented and poorly understood
  hardware platform which just happens to include one familiar component (the
  Calypso GSM chipset) would be building a house on quicksand.

All of the above notwithstanding, a lot of work has already been put in toward
support for the Pirelli target in FreeCalypso, and the AT-command-controlled
voice+SMS pseudo-modem functionality of our current gcc-built GSM firmware
works no worse on the Pirelli than it does on Mot C1xx.  Therefore, we shall
proceed with the howto:

How to play with FreeCalypso GSM firmware on a Pirelli DP-L10
=============================================================

One very useful special feature of the Pirelli DP-L10 is its very large RAM:
8 MiB.  Having such large RAM allows us to run our experimental fw on this
target entirely from RAM, without touching the flash.  When you compile a
FreeCalypso gsm-fw image for the Pirelli target, by default a ramImage will be
built instead of a flashImage.  It is possible to build a flashable image of
the fw in the same configuration and program it into flash with fc-loadtool,
but doing so is not recommended: our current fw has no battery management code,
so the charging hardware circuit will never be enabled and the battery will
discharge even with a USB power source connected; keeping Pirelli's original
fw in flash will allow the phone to charge its battery and otherwise function
normally when you are not in the middle of a FreeCalypso firmware experiment.

If you are ready to play with our experimental GSM pseudo-modem fw on your
Pirelli, the steps are as follows:

1. Build the firmware in the pirelli-gsm-rvtat configuration - see the
   Compiling document for more details.

2. 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.

3. Run a command like the following:

   fc-xram -h pirelli /dev/ttyUSB0 finlink/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.

4. 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.

To exercise our firmware further, you will need to 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%SLEEP=2	-- disable deep sleep (always required on the Pirelli)
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.