FreeCalypso > hg > freecalypso-tools
comparison loadtools/loadtool.help @ 0:e7502631a0f9
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 |