FreeCalypso > hg > freecalypso-sw

annotate loadtools/README @ 105:02cb0206aa47

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