FreeCalypso > hg > fc-am-toolkit

comparison doc/Pirelli-VPM-howto @ 27:9e7ca43275eb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Pirelli-VPM-howto: new article
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 12 Jun 2023 04:21:16 +0000
parents
children
comparison
equal deleted inserted replaced
26:f98ca59c079d 27:9e7ca43275eb
1 Running FreeCalypso VPM firmware on a Pirelli DP-L10 phone is much easier and
2 much more convenient than doing the same on Mot C1xx. There are two principal
3 reasons for this difference:
4
5 * Pirelli DP-L10 has huge RAM (8 MiB), allowing our FC aftermarket fw to run
6 entirely in RAM (fc-xram) without flashing.
7
8 * In the flash layout used by official fw, there is an area that is used only
9 for high-level firmware updates over WLAN (as opposed to "surgical" firmware
10 reflashing with fc-loadtool) and remains unused otherwise. We put our
11 aftermarket FFS in this part of the flash, and this aftermarket FFS just stays
12 there, untouched by Pirelli's official fw, in between fc-xram sessions that
13 run FC VPM fw.
14
15 This article explains how to initialize the aftermarket FFS for FreeCalypso fw
16 on your Pirelli phone, and how to actually run the VPM fw afterward.
17
18 Required software components
19 ============================
20
21 You will need the following 4 FreeCalypso software packages installed on your
22 host machine:
23
24 1) FC host tools base package:
25
26 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2
27
28 2) FFS data bundle add-on:
29
30 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-data-bundle-latest.tar.bz2
31
32 3) FFS editing agent target binaries:
33
34 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/ffs-editor-latest.tar.bz2
35
36 4) The present fc-am-toolkit package.
37
38 All 4 packages install all of their files under the /opt/freecalypso directory
39 tree defined by the Mother, and you only need to do this host software
40 installation once (or when updates come out), irrespective of how many phones
41 of various kinds (both Pirelli DP-L10 and Mot C1xx) you are going to work with.
42
43 Working with Pirelli phones: general principles
44 ===============================================
45
46 In order to work with a Pirelli DP-L10 phone in any interesting way, you need
47 to connect it to your host computer via USB. However, USB VBUS rail is also
48 used as the charging power source on this phone, hence any time USB is
49 connected, the Calypso+Iota chipset gets the "charger inserted" condition
50 applied to it, and is not allowed to be fully switched off. The solution
51 adopted by the Mother of FreeCalypso consists of using the "booted for charging
52 only" mode of Pirelli's official fw, plus the -Petmoff mechanism added to
53 loadtools in fc-host-tools-r19.
54
55 Like all standard handset firmwares, Pirelli's official fw has two fundamental
56 operating modes in terms of power on/off control: it can be fully booted, in
57 which case GSM functionality is brought up (network registration, or if there
58 is no SIM, camping on whatever cell it can find for the possibility of an
59 emergency call), or it can be booted for charging only. If you plug USB into a
60 fully switched-off Pirelli phone, the firmware will boot, but it won't do
61 anything other than manage the charging process - that is what we call "booted
62 for charging only" mode. Another way to enter this mode is to plug USB into the
63 phone while it is in fully booted state (with menus working normally), and then
64 execute the power-off sequence. The firmware will actually command the same
65 regular soft power-off as it would in the absence of charging, but the presence
66 of VCHG (coming from USB VBUS) causes the chipset to immediately do another
67 switch-on - and then the firmware boots again, this time for charging only.
68
69 When the firmware is booted for charging only (and you don't give it the
70 additional button press that ungates full boot), all GSM functionality is off
71 (the SIM interface is powered off, and no radio bring-up is done, not even for
72 emergency mode), but the RVTMUX interface is fully working. Pirelli's fw
73 includes ETM, and we can send it an ETM ABB write (abbw) command that writes to
74 the VRPCDEV register in the Iota chip, commanding switch-off. We can make this
75 intrusion into Pirelli's fw in any state, but doing so in the regular fully
76 booted state (basically killing the running fw by brute force) is obviously bad.
77 However, when the fw is booted for charging only, killing it in this manner
78 causes no harm, as there is nothing running besides the charging process - and
79 the Iota chip does turn off charging when this switch-off is executed.
80
81 Thus comes our general principle: whenever you wish to use your Pirelli DP-L10
82 phone for playing with FreeCalypso VPM, begin by putting it into the "booted
83 for charging only" state. If you started with the phone off, simply plug in USB
84 but don't press the "On" button, and if you started with the phone on, you can
85 plug in USB and then turn it off. When the phone is in this state and you need
86 to run fc-loadtool, fc-simint, fc-xram or any other loadtools program, run your
87 fc-loadtool or fc-xram etc command with an added -Petmoff option, and then you
88 don't need to do any manual manipulations on the phone: the Calypso boot ROM
89 entry will happen as soon as you execute the command on the host. And when your
90 fc-loadtool or fc-simint session cleanly finishes, or when you finish an FC VPM
91 fw session with fc-shell poweroff or AT@POFF, the phone will return to the same
92 "booted for charging only" state - very convenient! This "booted for charging
93 only" state, running Pirelli's official fw in the flash, thus becomes the
94 "ground" state for FreeCalypso manipulations, corresponding to the fully
95 switched-off state on a Mot C1xx phone or a traditional TI/FC dev board.
96
97 Aftermarket FFS initialization
98 ==============================
99
100 To initialize the aftermarket FFS for FC firmware on your Pirelli phone,
101 execute this command:
102
103 pirelli-init-fc-ffs /dev/ttyUSB0
104
105 (Change ttyUSB0 to other ttyUSBx if needed.)
106
107 This command is a shell script, the script begins with an fc-loadtool batch
108 operation erasing the aftermarket FFS area, and that fc-loadtool batch command
109 invokation is made with -Petmoff option described in the previous section -
110 thus the phone needs to be in "booted for charging only" mode when you run that
111 pirelli-init-fc-ffs command.
112
113 After erasing the aftermarket FFS area with fc-loadtool, our pirelli-init-fc-ffs
114 script runs our FFS editing agent via fc-xram, and then does the actual FFS
115 initialization via fc-fsio. An fc-fsio command script stashed in
116 /opt/freecalypso/scripts/pirelli-am-ffsinit (installed by the present
117 fc-am-toolkit package) contains the actual magic commands, and these commands
118 populate the FFS with files that come from FC FFS data bundle package.
119
120 You can rerun this pirelli-init-fc-ffs operation at any time, if you need to
121 reset the aftermarket FFS to its pristine state or if you got an updated version
122 of the relevant files in the FFS data bundle.
123
124 Running VPM firmware
125 ====================
126
127 To run FC VPM firmware, once your Pirelli phone is in "booted for charging only"
128 mode and the aftermarket FFS has been initialized as above, execute a command
129 of this form:
130
131 fc-xram -h pirelli -Petmoff /dev/ttyUSB0 path/to/ramimage.srec rvinterf
132
133 The FC firmware image needs to be ramimage.srec; to build this image format (if
134 you are compiling your own fw, rather than using a released build), run
135 'make ram' in the firmware build directory. (By default the firmware build
136 system produces flash images on all targets, but on the Pirelli target you
137 really don't want to flash this fw - hence the need to run 'make ram'
138 explicitly.)
139
140 When you run the above command, the firmware image will be loaded into XRAM and
141 jumped to. The command is structured so that fc-xram will then pass the serial
142 communication channel to rvinterf, and from that point on you have a regular
143 rvinterf session, talking to an in-RAM (not flashed) firmware instance. The
144 principles and guidelines for exercising the GSM MS as a VPM are the same as
145 described in the C1xx-VPM-usage article for C1xx phones - please refer to that
146 article.
147
148 Instead of checking for a present rvinterf process via keepalive packets, the
149 Pirelli DP-L10 version of our VPM firmware periodically (every 10 s) checks
150 for still-present USB connection, by checking the "charger present" status bit
151 in Iota VRPCSTS register. If it detects USB unplug, it performs an immediate
152 power-off - and because the firmware is not flashed, only loaded in RAM, the
153 next boot cycle (be it the power button or USB plug-in) will return the phone
154 to its regular official fw.