--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Pirelli-VPM-howto	Mon Jun 12 04:21:16 2023 +0000
@@ -0,0 +1,154 @@
+Running FreeCalypso VPM firmware on a Pirelli DP-L10 phone is much easier and
+much more convenient than doing the same on Mot C1xx.  There are two principal
+reasons for this difference:
+
+* Pirelli DP-L10 has huge RAM (8 MiB), allowing our FC aftermarket fw to run
+  entirely in RAM (fc-xram) without flashing.
+
+* In the flash layout used by official fw, there is an area that is used only
+  for high-level firmware updates over WLAN (as opposed to "surgical" firmware
+  reflashing with fc-loadtool) and remains unused otherwise.  We put our
+  aftermarket FFS in this part of the flash, and this aftermarket FFS just stays
+  there, untouched by Pirelli's official fw, in between fc-xram sessions that
+  run FC VPM fw.
+
+This article explains how to initialize the aftermarket FFS for FreeCalypso fw
+on your Pirelli phone, and how to actually run the VPM fw afterward.
+
+Required software components
+============================
+
+You will need the following 4 FreeCalypso software packages installed on your
+host machine:
+
+1) FC host tools base package:
+
+   ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2
+
+2) FFS data bundle add-on:
+
+   ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-data-bundle-latest.tar.bz2
+
+3) FFS editing agent target binaries:
+
+   ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-editor-latest.tar.bz2
+
+4) The present fc-am-toolkit package.
+
+All 4 packages install all of their files under the /opt/freecalypso directory
+tree defined by the Mother, and you only need to do this host software
+installation once (or when updates come out), irrespective of how many phones
+of various kinds (both Pirelli DP-L10 and Mot C1xx) you are going to work with.
+
+Working with Pirelli phones: general principles
+===============================================
+
+In order to work with a Pirelli DP-L10 phone in any interesting way, you need
+to connect it to your host computer via USB.  However, USB VBUS rail is also
+used as the charging power source on this phone, hence any time USB is
+connected, the Calypso+Iota chipset gets the "charger inserted" condition
+applied to it, and is not allowed to be fully switched off.  The solution
+adopted by the Mother of FreeCalypso consists of using the "booted for charging
+only" mode of Pirelli's official fw, plus the -Petmoff mechanism added to
+loadtools in fc-host-tools-r19.
+
+Like all standard handset firmwares, Pirelli's official fw has two fundamental
+operating modes in terms of power on/off control: it can be fully booted, in
+which case GSM functionality is brought up (network registration, or if there
+is no SIM, camping on whatever cell it can find for the possibility of an
+emergency call), or it can be booted for charging only.  If you plug USB into a
+fully switched-off Pirelli phone, the firmware will boot, but it won't do
+anything other than manage the charging process - that is what we call "booted
+for charging only" mode.  Another way to enter this mode is to plug USB into the
+phone while it is in fully booted state (with menus working normally), and then
+execute the power-off sequence.  The firmware will actually command the same
+regular soft power-off as it would in the absence of charging, but the presence
+of VCHG (coming from USB VBUS) causes the chipset to immediately do another
+switch-on - and then the firmware boots again, this time for charging only.
+
+When the firmware is booted for charging only (and you don't give it the
+additional button press that ungates full boot), all GSM functionality is off
+(the SIM interface is powered off, and no radio bring-up is done, not even for
+emergency mode), but the RVTMUX interface is fully working.  Pirelli's fw
+includes ETM, and we can send it an ETM ABB write (abbw) command that writes to
+the VRPCDEV register in the Iota chip, commanding switch-off.  We can make this
+intrusion into Pirelli's fw in any state, but doing so in the regular fully
+booted state (basically killing the running fw by brute force) is obviously bad.
+However, when the fw is booted for charging only, killing it in this manner
+causes no harm, as there is nothing running besides the charging process - and
+the Iota chip does turn off charging when this switch-off is executed.
+
+Thus comes our general principle: whenever you wish to use your Pirelli DP-L10
+phone for playing with FreeCalypso VPM, begin by putting it into the "booted
+for charging only" state.  If you started with the phone off, simply plug in USB
+but don't press the "On" button, and if you started with the phone on, you can
+plug in USB and then turn it off.  When the phone is in this state and you need
+to run fc-loadtool, fc-simint, fc-xram or any other loadtools program, run your
+fc-loadtool or fc-xram etc command with an added -Petmoff option, and then you
+don't need to do any manual manipulations on the phone: the Calypso boot ROM
+entry will happen as soon as you execute the command on the host.  And when your
+fc-loadtool or fc-simint session cleanly finishes, or when you finish an FC VPM
+fw session with fc-shell poweroff or AT@POFF, the phone will return to the same
+"booted for charging only" state - very convenient!  This "booted for charging
+only" state, running Pirelli's official fw in the flash, thus becomes the
+"ground" state for FreeCalypso manipulations, corresponding to the fully
+switched-off state on a Mot C1xx phone or a traditional TI/FC dev board.
+
+Aftermarket FFS initialization
+==============================
+
+To initialize the aftermarket FFS for FC firmware on your Pirelli phone,
+execute this command:
+
+pirelli-init-fc-ffs /dev/ttyUSB0
+
+(Change ttyUSB0 to other ttyUSBx if needed.)
+
+This command is a shell script, the script begins with an fc-loadtool batch
+operation erasing the aftermarket FFS area, and that fc-loadtool batch command
+invokation is made with -Petmoff option described in the previous section -
+thus the phone needs to be in "booted for charging only" mode when you run that
+pirelli-init-fc-ffs command.
+
+After erasing the aftermarket FFS area with fc-loadtool, our pirelli-init-fc-ffs
+script runs our FFS editing agent via fc-xram, and then does the actual FFS
+initialization via fc-fsio.  An fc-fsio command script stashed in
+/opt/freecalypso/scripts/pirelli-am-ffsinit (installed by the present
+fc-am-toolkit package) contains the actual magic commands, and these commands
+populate the FFS with files that come from FC FFS data bundle package.
+
+You can rerun this pirelli-init-fc-ffs operation at any time, if you need to
+reset the aftermarket FFS to its pristine state or if you got an updated version
+of the relevant files in the FFS data bundle.
+
+Running VPM firmware
+====================
+
+To run FC VPM firmware, once your Pirelli phone is in "booted for charging only"
+mode and the aftermarket FFS has been initialized as above, execute a command
+of this form:
+
+fc-xram -h pirelli -Petmoff /dev/ttyUSB0 path/to/ramimage.srec rvinterf
+
+The FC firmware image needs to be ramimage.srec; to build this image format (if
+you are compiling your own fw, rather than using a released build), run
+'make ram' in the firmware build directory.  (By default the firmware build
+system produces flash images on all targets, but on the Pirelli target you
+really don't want to flash this fw - hence the need to run 'make ram'
+explicitly.)
+
+When you run the above command, the firmware image will be loaded into XRAM and
+jumped to.  The command is structured so that fc-xram will then pass the serial
+communication channel to rvinterf, and from that point on you have a regular
+rvinterf session, talking to an in-RAM (not flashed) firmware instance.  The
+principles and guidelines for exercising the GSM MS as a VPM are the same as
+described in the C1xx-VPM-usage article for C1xx phones - please refer to that
+article.
+
+Instead of checking for a present rvinterf process via keepalive packets, the
+Pirelli DP-L10 version of our VPM firmware periodically (every 10 s) checks
+for still-present USB connection, by checking the "charger present" status bit
+in Iota VRPCSTS register.  If it detects USB unplug, it performs an immediate
+power-off - and because the firmware is not flashed, only loaded in RAM, the
+next boot cycle (be it the power button or USB plug-in) will return the phone
+to its regular official fw.