FreeCalypso > hg > freecalypso-tools

annotate doc/Loadtools-usage @ 229:96332d875fc9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
loadtools: preparations for loadtool exit code possibly being nonzero
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 03 Aug 2017 01:33:06 +0000
parents 1a658ab756fe
children b5f2ccfdafec
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
209
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 The loadtools subset of FreeCalypso host tools consists of:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 fc-loadtool The tool for operating on Calypso GSM devices at a low
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 level. After "breaking" into the target GSM device in
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 its boot process and getting FreeCalypso loadagent
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 running on the target (out of Calypso internal RAM, aka
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 IRAM), loadtool presents an interactive command prompt
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 with commands for peeking and poking registers and most
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 importantly, reading and writing any part of the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 device's non-volatile flash memory.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 fc-iram & fc-xram These utilities are intended for FreeCalypso developers
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 only. They load an S-record code image into IRAM or
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 XRAM, respectively, induce a transfer of control to the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 loaded code, and then drop into a serial line pass-thru
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 mode for the operator to interact with the thus loaded
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 target code.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 The currently supported target devices are (in the order of decreasing
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 preference) official Calypso development boards (TI's D-Sample and our own
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 FCDEV3B), Openmoko's GTA0x GSM modem, and two "alien" Calypso phone families:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 Mot C1xx by Compal and Pirelli DP-L10 by Foxconn.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 All tools in the FreeCalypso loadtools suite work by feeding pieces of code to
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 the target device as it boots, preventing the booting of its regular firmware
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 and diverting control to these externally-loaded code pieces. These pieces of
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 ARM7 target code need to be installed on the host system running loadtools,
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 normally in /opt/freecalypso/target-bin:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 loadagent This is the "agent" code that runs on the target device when
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 fc-loadtool is operating on it: loadtool carries out its
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 operations by sending commands to loadagent. There is only one
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 version of loadagent for all currently supported Calypso
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 targets: loadagent does not access any resources outside of the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 Calypso chip itself unless commanded to do so, and loadtool
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 supports different target devices with different hardware
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 configurations by sending different commands to loadagent as
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 appropriate.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 compalstage For Compal phones only: a little piece of code that is fed to
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 the original fw's bootloader via the serial download protocol
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 provided by the latter; it re-enables the Calypso chip boot ROM
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 and jumps to it, allowing our loadagent to be loaded in the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 same way as on freedom-enabled devices.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 If you are working with a development snapshot of the freecalypso-tools source
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 tree, you will need to compile and install a GNU cross-compiler toolchain
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 targeting ARM7 (see ../toolchain) and then use that toolchain to compile
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 loadagent and compalstage (see ../target-utils) before you can successfully use
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 loadtools to operate on a target device. End-user oriented releases of
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 FreeCalypso host tools include prebuilt loadagent and compalstage binaries.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 Basic usage
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 ===========
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 The steps for bringing up fc-loadtool to operate on a target Calypso device are
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 as follows:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 1. If you are using a USB serial adapter, or operating on a Pirelli phone that
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 has one built in, connect the USB side first so that the necessary
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 /dev/ttyUSB* device node appears. If you are working with a target such as
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 FCDEV3B or D-Sample on which both Calypso UARTs are equally accessible with
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 equal convenience, you can arbitrarily pick either one for fc-loadtool - it
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 will work exactly the same through either port.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 2. Run fc-loadtool like this:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 fc-loadtool $TARGETOPT /dev/ttyXXX
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 Change /dev/ttyXXX to the actual serial port you are using, and change
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 $TARGETOPT to:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 Device Needed options
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 -----------------------------------
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 FreeCalypso FCDEV3B -h fcfam
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 Mot C11x/123 -h compal
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 Mot C139/140 -h compal -c 1004
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 Mot C155/156 -h c155
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 Openmoko GTA02 -h gta02
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 Pirelli DP-L10 -h pirelli
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 TI D-Sample -h dsample
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 3. Cause the target device to execute its boot path. TI/Openmoko/FreeCalypso
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 and Pirelli targets have the Calypso boot ROM enabled, and will interrupt
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 and divert their normal boot path when they "hear" the beacons which
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 fc-loadtool will be sending down the serial line. Compal phones have this
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 boot ROM disabled at the board level, but their standard firmware includes a
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 flash-resident bootloader that offers a different way of interrupting the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 boot path and loading code over the serial line; fc-loadtool will be set up
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 to speak the latter protocol when run with the corresponding options from
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 the table above.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 You will see messages showing fc-loadtool's progress with feeding first
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 compalstage (if needed), then loadagent (always needed) to the target device,
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 followed by some target-specific initialization done via loadagent commands.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 If all of the above succeeds, you will land at a loadtool> prompt. Type
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 'help', and it will guide you from there. Alternatively, you can familiarize
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 yourself with loadtool commands and operations without actually running it by
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 reading the loadtool.help text file.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 Command line options
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 ====================
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 The fc-loadtool command lines shown above will usually be sufficient. However,
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 here is the complete command line description for all 3 tools:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 fc-iram [options] ttyport iramimage.srec [2ndprog]
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 fc-xram [options] ttyport xramimage.srec [2ndprog]
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 fc-loadtool [options] ttyport
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 The available options are common for all 3 utilities, with a few noted
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 exceptions:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 -a /path/to/loadagent
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 This option applies only to fc-loadtool and fc-xram. It specifies the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 pathname at which the required loadagent.srec image should be sought,
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 overriding the compiled-in default.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 -b baud
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 This option is common for all 3 utilities. It selects the baud rate
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 to be used when pushing the IRAM image to the Calypso boot ROM. In the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 case of fc-iram, the selected baud rate will be in effect when the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 loaded IRAM image is jumped to and fc-iram drops into the serial tty
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 pass-thru mode; in the case of fc-loadtool, it will be the initial baud
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 rate for communicating with loadagent, which can be switched later with
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 the baud command. The default is 115200 baud.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 -B baud
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 This option is specific to fc-xram. It selects the baud rate to be
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 used when pushing the XRAM image to loadagent. If no -B option is
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 specified, fc-xram will communicate with loadagent at the same baud
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 rate that was used to load loadagent itself via the Calypso boot ROM
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136 download protocol, i.e., the rate selected with -b, defaulting to
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 115200 baud if no -b option was given either. Neither -b nor -B
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 affects the baud rate that will be in effect when the loaded XRAM image
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 is jumped to and fc-xram drops into the serial tty pass-thru mode: that
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140 baud rate independently defaults to 115200 baud and can only be changed
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 with the -r option.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143 -c <compalstage flavor>
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145 This option is common for all 3 utilities. It directs the tools to
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 perform the Compal loading stage before proceeding with the Calypso
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 boot ROM serial protocol, and selects the "flavor" of compalstage to
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 use. As you can see in the source, compalstage is built in 3 different
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149 versions, for different C1xx models which exhibit different quirks.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 This option overrides the compal-stage setting given in the hardware
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 parameter file selected with -h or -H; the -c or -C option must be given
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 after -h or -H in order to take effect. -c none disables the Compal
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 stage and causes the tools to proceed directly to the Calypso boot ROM
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 phase, even on targets for which the hardware parameter file specifies
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 compal-stage.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 -C /path/to/compalstage-binary
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160 This option is just like -c, except that the given argument is used
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 directly as the compalstage binary file pathname (absolute or relative)
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 without checking or alteration.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 -h hwtype
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166 This option is common for all 3 utilities. It selects the specific
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167 target device configuration to be used. More precisely, it constructs
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 a pathname of the form /opt/freecalypso/loadtools/%s.config, where %s
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169 is the argument given to this option, and uses that file as the hardware
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 parameter file.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172 The hardware configurations known to the present release of FreeCalypso
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 loadtools are listed in the "Basic usage" section above.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 -H /path/to/hwparam-file
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 This option is just like -h, except that the given argument is used
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178 directly as the hardware parameter file pathname (absolute or relative)
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 without alteration.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181 -i num
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183 This option is common for all 3 utilities. It specifies the interval
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 in milliseconds at which the tool will send "please interrupt the boot
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185 process" beacons out the serial port, hoping to catch the Calypso
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186 internal boot ROM. The default is 13 ms.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188 -n
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190 This option does anything only when loadtools have been compiled to run
215
1a658ab756fe doc/Loadtools-on-GTA0x article added, replacing the corresponding section
Mychaela Falconia <falcon@freecalypso.org>
parents: 209
diff changeset
191 on GTA0x AP (see the Loadtools-on-GTA0x article). If you've compiled
209
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 loadtools with the -DGTA0x_AP_BUILD option, it has an effect of making
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 each tool automatically toggle the modem power control upon startup,
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 removing the need for manual sequencing of the Calypso boot process.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195 This -n option suppresses that action, making the AP build behave like
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196 the standard build in this regard.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198 -r baud (fc-loadtool)
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 This option is specific to fc-loadtool. It causes the tool to skip its
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201 normal steps of feeding loadagent and possibly compalstage to the target
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 via special serial protocols, and instead assume that the target is
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203 already running loadagent, communicating at the specified baud rate.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204 In other words, reattach to an already running loadagent. Use this
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 option if your fc-loadtool session has been terminated ungracefully and
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206 you would like to reattach and resume, rather than forcibly reset the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
207 target by yanking and reinserting the battery and restart from the
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208 beginning.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210 -r baud (fc-xram)
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212 This option is specific to fc-xram. It selects the serial line baud
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 rate which should be set just before the loaded XRAM image is jumped
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214 to; the default is 115200 baud.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216 fc-iram & fc-xram 2nd program invokation
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217 ========================================
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
218
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
219 Our fc-iram and fc-xram utilities can take two possible actions after they have
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
220 loaded the specified S-record image into RAM:
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
221
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
222 * The default action, in the absence of additional command line arguments, is
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
223 to drop into a serial tty pass-thru mode.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
224
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
225 * The alternative action is to invoke a 2nd program and pass the serial
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
226 communication channel to it. This 2nd program invokation facility is intended
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
227 primarily for passing the serial communication channel to rvinterf or rvtdump
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
228 from the FreeCalypso host tools suite, not for launching any arbitrary
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
229 3rd-party programs from fc-xram or fc-iram.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
230
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
231 This feature was originally implemented in fc-xram only, and the intended usage
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
232 scenario is that one builds a version of one of our FreeCalypso GSM firmwares
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
233 (or some subset thereof, such as an "in vivo" FFS editing agent) in the ramImage
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
234 configuration, fc-xram is used to load that ramImage into the target device,
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
235 and then the serial communication channel (RVTMUX) is immediately taken over by
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
236 rvinterf or rvtdump.
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
237
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
238 This second program invokation capability was later extended to fc-iram for no
5433349a6e2c doc/Loadtools-usage: replacing loadtools/README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
239 purpose other than to support a hack described in the Flash-boot-defect article.