FreeCalypso > hg > freecalypso-sw

comparison loadtools/README @ 97:a2e793f6b8c4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
some README files added
author Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
date Sun, 01 Sep 2013 12:54:42 +0000
parents
children 8b44e806b6e1
comparison
equal deleted inserted replaced
96:57b8dbb029c2 97:a2e793f6b8c4
1 You are looking at the source for the FreeCalypso loadtools package. You may
2 have downloaded it either as a separate package or as part of the larger
3 freecalypso-sw suite.
4
5 The tools in this package are written to run on some Unix/Linux machine
6 (normally a PC/Linux desktop or laptop) that acts as a host for operating on
7 Calypso target devices. All of these tools communicate with the Calypso target
8 through a serial port; each tool begins its operation by sending special byte
9 sequences to this serial port which are designed to interrupt the Calypso
10 device boot process in the ROM bootloader.
11
12 Three utilities are currently built as part of FreeCalypso loadtools:
13
14 fc-iram & fc-xram These utilities are intended for FreeCalypso developers
15 only. They load an S-record code image into IRAM or
16 XRAM, respectively, induce a transfer of control to the
17 loaded code, and then drop into a serial line pass-thru
18 mode for the operator to interact with the thus loaded
19 target code.
20
21 fc-loadtool This utility is intended for both developers and end
22 users. After establishing communication with the
23 target, fc-loadtool drops into interactive operation.
24 Once at the loadtool> prompt, you can peek and poke
25 registers, and most importantly, dump (read) and load
26 (program) the flash memory of the target device.
27
28 Loadagent
29
30 Both fc-loadtool and fc-xram work by first feeding a FreeCalypso-developed
31 program called loadagent to the Calypso ROM bootloader; all further operations
32 (loading code into XRAM or flash) are done via this loadagent. An S-record
33 image of the loadagent program is required for fc-loadtool and fc-xram to work.
34 That program is in turn built with the ARM7 toolchain.
35
36 If you are working with the full freecalypso-sw suite, you presumably already
37 have the proper ARM7 toolchain built and installed. To build loadagent, simply
38 run 'make' in the ../target-utils tree.
39
40 If you have downloaded a separately-packaged version of FreeCalypso loadtools,
41 the package should have a prebuilt loadagent.srec image included, sparing
42 non-developer users the nontrivial hurdle of having to build and install a
43 special cross-compilation toolchain. The same loadagent binary is designed to
44 work on all supported Calypso targets.
45
46 Building and installing loadtools
47
48 Normally the machine on which you build and install fc-loadtools would be your
49 PC/Linux desktop or laptop, the system you would use to program or otherwise
50 interact with Calypso phones by way of appropriate USB-to-phone cables. Just
51 like loadagent, the host utilities you are going to build and install aren't
52 specific to a particular target device; instead you will select the target
53 device at run time via a command line option. Hence you can build and install
54 the host utilities (usual 'make' and 'make install') without limiting your
55 setup to just one target phone type.
56
57 However, if your intended target device is an Openmoko GTA02 (or GTA01)
58 smartphone, there is one additional complication: one cannot directly access
59 the Calypso part of these phones from the outside without going through the
60 phone's application processor first. If you would like to use fc-loadtool to
61 read or write the GSM flash memory of your GTA0x (load a different firmware
62 image, dump the flash file system for backup or examination, restore a previous
63 backup etc), there are two ways to do it:
64
65 1. The recommended way for FreeCalypso developers is to get a special serial
66 cable (low voltage, as in 3.3V or lower - *NOT* RS-232 levels - please don't
67 fry your precious phone!) that would plug into the 2.5mm jack on the left
68 side of the phone that is normally intended for a wired headset. This way
69 you can use your regular build of fc-loadtool (and fc-iram & fc-xram) on
70 your PC/Linux (or other) development host, no need to build anything for
71 GTA0x AP, and all communication happens directly between your development
72 host and the Calypso part of your target phone - not going through the AP
73 at all. You still need working software on the GTA0x AP to do battery
74 management, to power the Calypso block on and off, and to enable the headset
75 jack "download" path, but it is much less burdensome than having to do the
76 actual FreeCalypso work from the AP.
77
78 2. If you are an end user who simply wishes to reflash a different GSM firmware
79 image, it can be done from inside the phone (from the AP) without having to
80 acquire special hardware (as in the cable described above). However, the
81 trade-off is that in return for saving on the special hardware, you have to
82 do more work on the software. You will have to use a cross-compiler
83 targeting the ARM/Linux AP environment (*not* the ARM7 cross-compiler used
84 for the GSM firmware itself!) to build fc-loadtools to run on the GTA0x AP.
85
86 Building loadtools for GTA0x AP
87
88 If you've decided to build loadtools for the GTA0x AP, you'll need to make the
89 following modifications to the Makefile:
90
91 * Change the CC= line to point to the appropriate cross-compiler (which you'll
92 need to provide yourself);
93
94 * Change the CFLAGS= line: add the right options to target the ARM920T core in
95 the GTA0x AP (e.g., -march=armv4t -mtune=arm920t), and add -DGTA0x_AP_BUILD
96 to enable some code that makes sense only when running on the GTA0x AP.
97
98 * Change EXTRA_OBJ= to EXTRA_OBJ=gtapower.o, i.e., add gtapower.c (compiling
99 into gtapower.o) to the build.
100
101 See gta-ap-build.sed for an example.
102
103 Running fc-loadtool
104
105 Once you've got loadtools built and installed, you can run fc-loadtool
106 as follows:
107
108 To operate on a Pirelli DP-L10 that appears as /dev/ttyUSB0:
109
110 fc-loadtool -h pirelli /dev/ttyUSB0
111
112 To operate on the Calypso block of a GTA02, accessing it from an external
113 PC/Linux host via a USB-to-headset-jack serial cable that appears as
114 /dev/ttyUSB0:
115
116 fc-loadtool -h gta02 /dev/ttyUSB0
117
118 To operate on the Calypso block of a GTA02, running fc-loadtool from inside the
119 phone, i.e., from the AP of the same GTA02:
120
121 fc-loadtool -h gta02 /dev/ttySAC0