# HG changeset patch # User Mychaela Falconia # Date 1686543676 0 # Node ID 9e7ca43275eb5c1d0c9b050e13d6ea4df441074c # Parent f98ca59c079d5bdc989e693e8a69e6a871676aee doc/Pirelli-VPM-howto: new article diff -r f98ca59c079d -r 9e7ca43275eb doc/Pirelli-VPM-howto --- /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.