# HG changeset patch # User Mychaela Falconia # Date 1475522639 0 # Node ID ffa25a27fa273f03d259460de2675141c88052d5 # Parent 9fb9f896bd772020dab4fc9b9c23571bdec2f7af doc/Pirelli-Howto written diff -r 9fb9f896bd77 -r ffa25a27fa27 doc/Pirelli-Howto --- 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 ============================================================ - +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.