--- a/doc/Pirelli-Howto	Mon Oct 03 19:23:25 2016 +0000
+++ b/doc/Pirelli-Howto	Mon Oct 03 19:23:59 2016 +0000
@@ -1,4 +1,153 @@
 Running FreeCalypso Magnetite firmware on the Pirelli DP-L10
 ============================================================
 
-<To be written>
+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.