FreeCalypso > hg > freecalypso-tools

comparison loadtools/loadtool.help @ 0:e7502631a0f9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial import from freecalypso-sw rev 1033:5ab737ac3ad7
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 11 Jun 2016 00:13:35 +0000
parents
children 6178a3d3cf74
comparison
equal deleted inserted replaced
-1:000000000000 0:e7502631a0f9
1 This is the help file for fc-loadtool. See lthelp.c for the code
2 that parses and displays it. The parsing code is the only
3 documentation for the format of this help file - if you are going to
4 edit this help text, read the parsing code first.
5
6 === main
7 This utility allows you to perform the following operations
8 on your Calypso GSM device:
9
10 * Peek and poke registers
11 * Dump any part of memory
12 * Read and program flash
13
14 See the following help topics for more information:
15
16 help peekpoke Register peek and poke commands
17 help flash Flash operation commands
18 help all List of all implemented commands
19 help exit Controlling the cleanup on exit
20
21 === all
22 abbr Read an ABB register
23 abbw Write an ABB register
24 baud Switch the serial comm with loadagent to a different baud rate
25 crc32 Get CRC-32 of a memory area on the target
26 dieid Read the Calypso die ID
27 dump Dump a target memory region in hex and ASCII
28 dump2bin Dump a target memory region to a file in binary format
29 dump2srec Dump a target memory region to a file in S-record format
30 exec Execute a command script
31 exit Exit from loadtool and clean up the target device state
32 flash Flash operations
33 flash2 Operations on the 2nd flash bank (Pirelli phone only)
34 quit Alias for exit
35 r8 Read an 8-bit register or memory location
36 r16 Read a 16-bit register or memory location
37 r32 Read a 32-bit register or memory location
38 w8 Write an 8-bit register or memory location
39 w16 Write a 16-bit register or memory location
40 w32 Write a 32-bit register or memory location
41
42 To get help on any command, type help and the command keyword.
43
44 === abbr
45 === abbw
46 abbr pg reg Read ABB register <reg> on page <pg>
47 abbw pg reg val Write <val> into register <reg> on page <pg>
48
49 The <pg> and <reg> arguments default to decimal unless prefixed with 0x;
50 the <val> argument to abbw is always hexadecimal.
51
52 === baud
53 baud Display the current baud rate
54 baud <rate> Switch the baud rate to <rate> (number in bps)
55
56 The supported baud rates are:
57
58 Standard: 19200, 38400, 57600, 115200
59 Calypso special: 203125, 406250, 812500
60
61 The baud command coordinates the necessary simultaneous switching of the
62 baud rate on both the host and the target (loadagent). Loadagent always
63 supports all of the listed rates and will switch happily, but in the case
64 of the higher non-standard baud rates fc-loadtool has no way of knowing
65 ahead of time whether or not the requested baud rate is supported by your
66 usb2serial adapter or whatever other serial port hardware and driver
67 you are using. If the baud rate switch fails, the communication link with
68 the target will be broken and fc-loadtool will exit ungracefully.
69
70 === crc32
71 crc32 hex-start hex-len
72
73 The first argument is the starting target memory address in hex; the second
74 argument is the length of the area to CRC, also in hex. The command will be
75 sent to loadagent; CRC-32 of the requested range will be computed on the target
76 and displayed in hex.
77
78 === dieid
79 dieid Display the Calypso die ID
80 dieid <filename> Display the Calypso die ID, and also save it in the
81 named file
82
83 The Calypso die ID resides in 4 16-bit registers at target addresses
84 0xFFFEF010 through 0xFFFEF016. It is displayed on the terminal and optionally
85 saved to a file in this simple form:
86
87 FFFEF010: xxxx
88 FFFEF012: xxxx
89 FFFEF014: xxxx
90 FFFEF016: xxxx
91
92 === dump
93 dump hex-start hex-len
94
95 The first argument is the starting target memory address in hex; the second
96 argument is the length of the area to dump, also in hex. The dump will be
97 displayed on the terminal in hex and ASCII.
98
99 === dump2bin
100 === dump2srec
101 dump2bin hex-start hex-len outfile
102 dump2srec hex-start hex-len outfile
103
104 The first argument is the starting target memory address in hex; the second
105 argument is the length of the area to dump, also in hex; the third argument
106 is the name of the output file to be created/written. The dump will be saved
107 in binary or S-records as per the chosen command, always in the native byte
108 order of the Calypso ARM7 target (little-endian).
109
110 === exec
111 exec <script-file>
112
113 Read and execute commands from the named file. If the given file name contains
114 no slashes, the script file is sought in the default directory (normally
115 /usr/local/share/freecalypso unless changed in the code); otherwise the given
116 name is used directly as the pathname.
117
118 === exit
119 === quit
120 exit Clean up the target in the default manner and exit
121 exit bare Exit loadtool without doing anything to the target
122 exit iota-off Exit loadtool and command an ABB power-off on the target
123 exit jump0 Exit loadtool and command the target to reboot via jump to 0
124
125 The default method of cleaning up the target device state upon exit is set
126 in the hardware parameters file selected with the -h or -H command line
127 option; it is the exit-mode setting. On the Pirelli phone the default exit
128 mode is jump0: it causes the phone to reboot and enter the "charging boot"
129 mode, as the USB cable is connected and VBUS is present. On Compal phones the
130 default exit mode is iota-off.
131
132 If your device is a GTA02 and you are running fc-loadtool from inside the phone
133 (from the AP), the exit command will power off the modem from the AP. If you
134 are talking to GTA02 Calypso from an external host via the headset jack, there
135 is nothing that fc-loadtool can currently do to power the modem off (exit is
136 the same as exit bare in this case) - power it off yourself from the AP.
137
138 If you do an exit bare without powering the target device off in some other
139 way, the device will still be running loadagent, which is probably not what you
140 want. However, it is the proper exit mode if you have powered off or reset the
141 target device by brute force (yanking the battery).
142
143 === flash
144 === flash2
145 The primary end use of fc-loadtool is for reading and writing the NOR flash
146 memories of the supported GSM devices. Compal phones and the GTA0x GSM modem
147 have only one flash bank (as in chip select), and are manipulated with the
148 flash command. The Pirelli phone has two flash banks (as in chip selects) of
149 8 MiB each; they are manipulated with the flash and flash2 commands.
150
151 The following flash operations are available on all target devices:
152
153 flash blankchk Blank-check a region of flash
154 flash dump2bin Dump flash content to a file in binary format
155 flash dump2srec Dump flash content to a file in S-record format
156 flash erase Erase a region of flash
157 flash info Display flash configuration info
158 flash program-bin Program flash with a binary file
159 flash program-m0 Program flash with an image in TI's *.m0 format
160 flash program-srec Program flash with an image in standard S-record format
161 flash quickprog Program a few flash words from the command line
162 flash reset Reset flash chip to read array mode
163 flash sectors Display the list of flash sector addresses and sizes
164
165 Substitute flash2 instead of flash when operating on the 2nd flash chip select
166 of Pirelli-style flash memory configurations. Prepend help before a command to
167 get usage information, e.g., help flash program-bin. See help compal for some
168 additional info specific to Compal targets.
169
170 === compal
171 === compalflash
172 === flash:compal
173 Compal phones have Intel or Intel-style flash chips; other Calypso targets for
174 which loadtool was originally designed have AMD-style flash chips. The author
175 of the present software has a personal bias toward AMD-style flash, hence the
176 support for Intel-style flash is not as clean. Compal phones also have the
177 Calypso boot ROM disabled, and depend on flash-resident boot code instead.
178 This property makes them brickable.
179
180 The following additional loadtool commands apply only to Compal targets with
181 Intel-style flash:
182
183 flash erase-program-boot Erase and reprogram the boot sector
184 flash status Read Intel flash Status Register
185 flash unlock Unlock flash sectors
186
187 === flash:blankchk
188 flash[2] blankchk hex-start-offset hex-length
189
190 Blank-checks an area of flash starting at the specified hex offset (from the
191 base address of the flash bank) and extending for the specified hex length.
192 Reports whether the checked region is blank or not. Flash must be blank (FF in
193 all bytes) before it can be programmed.
194
195 === flash:dump2bin
196 flash[2] dump2bin outfile [offset [length]]
197
198 Read device flash content and save it to a file. If only a filename is
199 specified, the full flash bank is dumped; one can optionally specify a starting
200 offset and an explicit length, both in hex.
201
202 This command is merely a user-friendly front-end to the plain dump2bin command;
203 see help dump2bin.
204
205 === flash:dump2srec
206 flash[2] dump2srec outfile [offset [length]]
207
208 Read device flash content and save it to a file. If only a filename is
209 specified, the full flash bank is dumped; one can optionally specify a starting
210 offset and an explicit length, both in hex.
211
212 This command is merely a user-friendly front-end to the plain dump2srec command;
213 see help dump2srec.
214
215 === flash:erase
216 flash[2] erase hex-start-offset hex-length
217
218 Erases an area of flash starting at the specified hex offset (from the base
219 address of the flash bank) and extending for the specified hex length.
220
221 Flash memory can only be erased (turning 0 bits back to 1s) in units of
222 sectors, as set in stone by the design of the flash chip in use. Loadtool
223 knows the sector layout of the flash chip in your device from CFI or from the
224 hardware parameters file (you can display it with the flash[2] sectors
225 command), and enforces that both arguments to the flash[2] erase command lie
226 on sector boundaries.
227
228 === flash:erase-program-boot
229 flash erase-program-boot binfile [length]
230
231 This operation is applicable to Compal targets only. This command erases and
232 reprograms flash sector 0 (the boot sector) with minimized vulnerability to
233 bricking by loading the new boot code into a scratchpad RAM area on the target,
234 then commanding loadagent (running on the target) to erase and reprogram the
235 dangerous flash sector without requiring further interaction with loadtool.
236 (In contrast, loadtool's "regular" flash erase and program operations are
237 driven primarily by loadtool, with loadagent providing only low-level
238 functions.)
239
240 The new bits to be programmed are taken from the specified binary file. Byte 0
241 of the file goes into byte 0 of the flash and so on, for the specified length.
242 If no length argument is given, it defaults to the length of the file, which
243 must not exceed the length of flash sector 0: 64 KiB on the "basic" Compal
244 phones or 8 KiB on C155/156.
245
246 === flash:info
247 This command displays summary information about the flash memory configuration
248 of the Calypso target device loadtool thinks it's talking to.
249
250 === flash:program-bin
251 flash[2] program-bin flash-offset binfile [file-offset [length]]
252
253 This command programs flash, using a binary file as the data source. One must
254 always specify the starting flash offset (from the base address of the flash
255 bank), but the starting file offset and length are optional, defaulting to the
256 whole file.
257
258 The binary file must be in the native byte order of the Calypso ARM7 processor,
259 which is little-endian. Images produced by flash[2] dump2bin are suitable.
260
261 === flash:program-m0
262 flash[2] program-m0 image.m0
263
264 *.m0 is the format that has been used by companies like TI and Closedmoko for
265 their proprietary firmware images. It is emitted by TI's hex470 tool, and in
266 the proprietary environment it is fed as an input to FLUID. (The latter is
267 TI's Flash Loader Utility Independent of Device, and fc-loadtool can be seen as
268 an independent reimplementation thereof - although it doesn't have the same
269 level of device-independence.) The *.m0 format is actually a variant of
270 Motorola's SREC, but with a different byte order: each 16-bit word is
271 byte-reversed relative to the native byte order of the ARM7 processor.
272 (This strange byte order actually makes some sense if one views the image as a
273 long array of 16-bit hex values; 16 bits is the width of the flash memory on
274 Calypso GSM devices and thus the natural unit size for flash programming.)
275
276 Because each S-record contains an address, no addresses or offsets need to be
277 specified in the flash[2] program-m0 command, only the image file.
278
279 === flash:program-srec
280 flash[2] program-srec image.srec
281
282 This command programs the flash with an image in the standard S-record format,
283 in the native little-endian byte order of the Calypso ARM7 processor. It is
284 the opposite byte order from that used by TI's *.m0 files -
285 see help flash program-m0. Images produced by flash[2] dump2srec are suitable
286 for flash[2] program-srec.
287
288 Because each S-record contains an address, no addresses or offsets need to be
289 specified in the flash[2] program-srec command, only the image file.
290
291 === flash:quickprog
292 flash[2] quickprog hex-offset hex-data-string
293
294 This command is intended only for developers; it provides raw access to
295 loadagent's basic flash write primitive. Read the source code for more
296 information.
297
298 === flash:reset
299 Intel-style flash memory chips (found in Compal phones) have two "stable" or
300 "quiescent" states: reading array data and reading the status register (SR).
301 After an erase or program operation the flash chip is "parked" in the Read SR
302 state; the flash reset command switches it back to reading array data.
303
304 This command works for AMD-style flash as well (found in Openmoko and Pirelli
305 phones), but it is normally not needed, as AMD-style flash chips automatically
306 return to the read-array-data state after every erase or program operation.
307
308 === flash:sectors
309 This command displays the list of sector offsets and sizes for the flash chip
310 in the Calypso target device loadtool thinks it's talking to.
311
312 === flash:status
313 This command is only applicable to Intel-style flash as found in Compal phones.
314 It reads the flash chip's Status Register, which can be used to diagnose errors
315 incurred by previous erase or program operations.
316
317 === flash:unlock
318 flash unlock hex-start-offset hex-length
319
320 This command is only applicable to Intel-style flash as found in Compal phones.
321 These flash chips power up with each sector (erase block) in the "locked" state;
322 each sector needs to be unlocked before it can be erased or programmed.
323
324 This command is normally not needed, as the flash erase command unlocks each
325 sector before erasing it. However, if you are going to perform program
326 operations in some sectors without erasing them, you will need to unlock them
327 explicitly first.
328
329 This command operates only on sector boundaries just like flash erase.
330
331 === r8
332 === r16
333 === r32
334 === w8
335 === w16
336 === w32
337 === peekpoke
338 The register peek and poke commands are:
339
340 r8 addr Read an 8-bit register or memory location
341 r16 addr Read a 16-bit register or memory location
342 r32 addr Read a 32-bit register or memory location
343 w8 addr data Write an 8-bit register or memory location
344 w16 addr data Write a 16-bit register or memory location
345 w32 addr data Write a 32-bit register or memory location
346
347 All addresses and data values are in hex.
348