line source
+ − The loadtools subset of FreeCalypso host tools consists of:
+ −
+ − fc-loadtool The tool for operating on Calypso GSM devices at a low
+ − level. After "breaking" into the target GSM device in
+ − its boot process and getting FreeCalypso loadagent
+ − running on the target (out of Calypso internal RAM, aka
+ − IRAM), loadtool presents an interactive command prompt
+ − with commands for peeking and poking registers and most
+ − importantly, reading and writing any part of the
+ − device's non-volatile flash memory.
+ −
+ − fc-iram & fc-xram These utilities are intended for FreeCalypso developers
+ − only. They load an S-record code image into IRAM or
+ − XRAM, respectively, induce a transfer of control to the
+ − loaded code, and then drop into a serial line pass-thru
+ − mode for the operator to interact with the thus loaded
+ − target code.
+ −
+ − The currently supported target devices are:
+ −
+ − 1) All Calypso devices (preferably with Iota ABB so we can cleanly power off
+ − after we are done) that have Calypso boot ROM (version 0200 or 0300) enabled
+ − by nIBOOT strapping on the board. This category includes TI and FreeCalypso
+ − development boards, several modems (Openmoko GTA01/02, Huawei GTM900, Tango)
+ − and other devices.
+ −
+ − 2) Motorola C1xx and Sony Ericsson J100 phones made by Compal: these phones do
+ − NOT have Calypso boot ROM enabled, but they provide a different way of
+ − gaining serial code download access which is supported by our tools.
+ −
+ − All tools in the FreeCalypso loadtools suite work by feeding pieces of code to
+ − the target device as it boots, preventing the booting of its regular firmware
+ − and diverting control to these externally-loaded code pieces. These pieces of
+ − ARM7 target code need to be installed on the host system running loadtools,
+ − normally in /opt/freecalypso/target-bin:
+ −
+ − loadagent This is the "agent" code that runs on the target device when
+ − fc-loadtool is operating on it: loadtool carries out its
+ − operations by sending commands to loadagent. There is only one
+ − version of loadagent for all currently supported Calypso
+ − targets: loadagent does not access any resources outside of the
+ − Calypso chip itself unless commanded to do so, and loadtool
+ − supports different target devices with different hardware
+ − configurations by sending different commands to loadagent as
+ − appropriate.
+ −
+ − compalstage For Compal phones only: a little piece of code that is fed to
+ − the original fw's bootloader via the serial download protocol
+ − provided by the latter; it re-enables the Calypso chip boot ROM
+ − and jumps to it, allowing our loadagent to be loaded in the
+ − same way as on freedom-enabled devices.
+ −
+ − If you are working with a development snapshot of the freecalypso-tools source
+ − tree, you will need to compile and install a GNU cross-compiler toolchain
+ − targeting ARM7 (see ../toolchain) and then use that toolchain to compile
+ − loadagent and compalstage (see ../target-utils) before you can successfully use
+ − loadtools to operate on a target device. End-user oriented releases of
+ − FreeCalypso host tools include prebuilt loadagent and compalstage binaries.
+ −
+ − Basic usage
+ − ===========
+ −
+ − The steps for bringing up fc-loadtool to operate on a target Calypso device are
+ − as follows:
+ −
+ − 1. If you are using a USB serial adapter, or operating on a Pirelli phone that
+ − has one built in, connect the USB side first so that the necessary
+ − /dev/ttyUSB* device node appears. If you are working with a target such as
+ − FCDEV3B or D-Sample on which both Calypso UARTs are equally accessible with
+ − equal convenience, you can arbitrarily pick either one for fc-loadtool - it
+ − will work exactly the same through either port.
+ −
+ − 2. Run fc-loadtool like this:
+ −
+ − fc-loadtool $TARGETOPT /dev/ttyXXX
+ −
+ − Change /dev/ttyXXX to the actual serial port you are using, and change
+ − $TARGETOPT to:
+ −
+ − Device Needed options
+ − -----------------------------------
+ − FreeCalypso FCDEV3B -h fcfam
+ − FreeCalypso Tango -h gen8 (or -h fcfam)
+ − Huawei GTM900 -h gen8
+ − iWOW TR-800 -h gen8
+ − Mot C11x/123 -h compal
+ − Mot C139/140 -h compal -c 1004
+ − Mot C155/156 -h c155
+ − Mot V17x -h c155
+ − Mot W220 -h w220
+ − Openmoko GTA01/02 -h fic
+ − Pirelli DP-L10 -h pirelli
+ − Sony Ericsson J100 -h compal -c 1004
+ − TI D-Sample -h dsample
+ − TI Leonardo -h leonardo
+ −
+ − Please refer to the Loadtool-targets article for more information about -h
+ − targets.
+ −
+ − 3. Cause the target device to execute its boot path. TI/Openmoko/FreeCalypso
+ − and other sensible targets have the Calypso boot ROM enabled, and will
+ − interrupt and divert their normal boot path when they "hear" the beacons
+ − which fc-loadtool will be sending down the serial line. Compal phones have
+ − this boot ROM disabled at the board level, but their standard firmware
+ − includes a flash-resident bootloader that offers a different way of
+ − interrupting the boot path and loading code over the serial line;
+ − fc-loadtool will be set up to speak the latter protocol when run with the
+ − corresponding options from the table above.
+ −
+ − You will see messages showing fc-loadtool's progress with feeding first
+ − compalstage (if needed), then loadagent (always needed) to the target device,
+ − followed by some target-specific initialization done via loadagent commands.
+ − If all of the above succeeds, you will land at a loadtool> prompt. Type
+ − 'help', and it will guide you from there. Alternatively, you can familiarize
+ − yourself with loadtool commands and operations without actually running it by
+ − reading the loadtool.help text file.
+ −
+ − fc-loadtool batch mode
+ − ======================
+ −
+ − In addition to the interactive mode described above, fc-loadtool can be used in
+ − a scripted or batch mode where it makes contact with the target device as it
+ − boots, interrupts and diverts the boot process to loadagent, executes a given
+ − command or script, cleans up the target state as appropriate (usually powers
+ − off) and exits. This mode is used by the FreeCalypso factory for initial flash
+ − programming on the device production line, but it can also be used by end users
+ − to install firmware updates in a more automated manner.
+ −
+ − To use the batch mode, specify an exec (command script), flash or flash2 command
+ − on the fc-loadtool invokation command line after the target tty port name. For
+ − backward compatibility, if only one extra argument (in the UNIX process argument
+ − list sense) is given after the target tty port name, it is interpreted as the
+ − name of the command script to execute, as if it was preceded by 'exec'. Only
+ − flash and flash2 commands can be given directly without going through a script;
+ − if you need to run other commands in batch mode, you will need to put them into
+ − a script file.
+ −
+ − Command line options
+ − ====================
+ −
+ − The fc-loadtool command lines shown above will usually be sufficient. However,
+ − here is the complete command line description for all 3 tools:
+ −
+ − fc-iram [options] ttyport iramimage.srec [2ndprog]
+ − fc-xram [options] ttyport xramimage.srec [2ndprog]
+ − fc-loadtool [options] ttyport [batch command]
+ −
+ − The available options are common for all 3 utilities, with a few noted
+ − exceptions:
+ −
+ − -a /path/to/loadagent
+ −
+ − This option applies only to fc-loadtool and fc-xram. It specifies the
+ − pathname at which the required loadagent.srec image should be sought,
+ − overriding the compiled-in default.
+ −
+ − -b baud
+ −
+ − This option is common for all 3 utilities. It selects the baud rate
+ − to be used when pushing the IRAM image to the Calypso boot ROM. In the
+ − case of fc-iram, the selected baud rate will be in effect when the
+ − loaded IRAM image is jumped to and fc-iram drops into the serial tty
+ − pass-thru mode; in the case of fc-loadtool, it will be the initial baud
+ − rate for communicating with loadagent, which can be switched later with
+ − the baud command. The default is 115200 baud.
+ −
+ − -B baud (fc-loadtool)
+ −
+ − This option is specific to the batch mode of fc-loadtool, and has no
+ − effect when no batch mode command script is specified on the command
+ − line. In the batch mode this option commands a baud rate switch to be
+ − performed before the command script is executed.
+ −
+ − -B baud (fc-xram)
+ −
+ − This option is specific to fc-xram. It selects the baud rate to be
+ − used when pushing the XRAM image to loadagent. If no -B option is
+ − specified, fc-xram will communicate with loadagent at the same baud
+ − rate that was used to load loadagent itself via the Calypso boot ROM
+ − download protocol, i.e., the rate selected with -b, defaulting to
+ − 115200 baud if no -b option was given either. Neither -b nor -B
+ − affects the baud rate that will be in effect when the loaded XRAM image
+ − is jumped to and fc-xram drops into the serial tty pass-thru mode: that
+ − baud rate independently defaults to 115200 baud and can only be changed
+ − with the -r option.
+ −
+ − -c <compalstage flavor>
+ −
+ − This option is common for all 3 utilities. It directs the tools to
+ − perform the Compal loading stage before proceeding with the Calypso
+ − boot ROM serial protocol, and selects the "flavor" of compalstage to
+ − use. As you can see in the source, compalstage is built in 3 different
+ − versions, for different C1xx models which exhibit different quirks.
+ −
+ − This option overrides the compal-stage setting given in the hardware
+ − parameter file selected with -h or -H; the -c or -C option must be given
+ − after -h or -H in order to take effect. -c none disables the Compal
+ − stage and causes the tools to proceed directly to the Calypso boot ROM
+ − phase, even on targets for which the hardware parameter file specifies
+ − compal-stage.
+ −
+ − -C /path/to/compalstage-binary
+ −
+ − This option is just like -c, except that the given argument is used
+ − directly as the compalstage binary file pathname (absolute or relative)
+ − without checking or alteration.
+ −
+ − -h hwtype
+ −
+ − This option is common for all 3 utilities. It selects the specific
+ − target device configuration to be used. More precisely, it constructs
+ − a pathname of the form /opt/freecalypso/loadtools/%s.config, where %s
+ − is the argument given to this option, and uses that file as the hardware
+ − parameter file.
+ −
+ − The hardware configurations known to the present release of FreeCalypso
+ − loadtools are listed in the Loadtool-targets article.
+ −
+ − -H /path/to/hwparam-file
+ −
+ − This option is just like -h, except that the given argument is used
+ − directly as the hardware parameter file pathname (absolute or relative)
+ − without alteration.
+ −
+ − -i num
+ −
+ − This option is common for all 3 utilities. It specifies the interval
+ − in milliseconds at which the tool will send "please interrupt the boot
+ − process" beacons out the serial port, hoping to catch the Calypso
+ − internal boot ROM. The default is 13 ms.
+ −
+ − -j
+ −
+ − This option is specific to fc-xram; it selects the special JTAG mode.
+ − In this mode the jump command to start executing the loaded image is
+ − skipped and the target is left in loadagent, allowing the developer to
+ − connect via JTAG, halt the ARM7 core, set whatever breakpoints or
+ − watchpoints are needed and resume at the image start address.
+ −
+ − -P <boot control name>
+ −
+ − This option is common for all utilities in the loadtools suite; it
+ − tells the tools to perform target boot control as described in the
+ − Target-boot-control article.
+ −
+ − -r baud (fc-loadtool)
+ −
+ − This option is specific to fc-loadtool. It causes the tool to skip its
+ − normal steps of feeding loadagent and possibly compalstage to the target
+ − via special serial protocols, and instead assume that the target is
+ − already running loadagent, communicating at the specified baud rate.
+ − In other words, reattach to an already running loadagent. Use this
+ − option if your fc-loadtool session has been terminated ungracefully and
+ − you would like to reattach and resume, rather than forcibly reset the
+ − target by yanking and reinserting the battery and restart from the
+ − beginning.
+ −
+ − -r baud (fc-xram)
+ −
+ − This option is specific to fc-xram. It selects the serial line baud
+ − rate which should be set just before the loaded XRAM image is jumped
+ − to; the default is 115200 baud.
+ −
+ − -t num
+ −
+ − This option is common for all utilities in the loadtools suite; it sets
+ − the timeout to be applied to the wait for the Calypso boot ROM response.
+ − Normally the tools wait forever for the Calypso boot ROM to respond to
+ − the interrupt-boot beacons that are being sent continuously at the
+ − interval set with -i; this -t option sets a timeout in ms instead.
+ − This option is intended for automated (unattended) environments where
+ − it is used together with some kind of target boot control, either -P or
+ − external.
+ −
+ − fc-iram & fc-xram 2nd program invokation
+ − ========================================
+ −
+ − Our fc-iram and fc-xram utilities can take two possible actions after they have
+ − loaded the specified S-record image into RAM:
+ −
+ − * The default action, in the absence of additional command line arguments, is
+ − to drop into a serial tty pass-thru mode.
+ −
+ − * The alternative action is to invoke a 2nd program and pass the serial
+ − communication channel to it. This 2nd program invokation facility is intended
+ − primarily for passing the serial communication channel to rvinterf or rvtdump
+ − from the FreeCalypso host tools suite, not for launching any arbitrary
+ − 3rd-party programs from fc-xram or fc-iram.
+ −
+ − This feature was originally implemented in fc-xram only, and the intended usage
+ − scenario is that one builds a version of one of our FreeCalypso GSM firmwares
+ − (or some subset thereof, such as an "in vivo" FFS editing agent) in the ramImage
+ − configuration, fc-xram is used to load that ramImage into the target device,
+ − and then the serial communication channel (RVTMUX) is immediately taken over by
+ − rvinterf or rvtdump.
+ −
+ − This second program invokation capability was later extended to fc-iram for no
+ − purpose other than to facilitate a boot hack that was only needed on one (1)
+ − defective FCDEV3B board - see the Flash-boot-wa article.