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 (in the order of decreasing
+ − preference) official Calypso development boards (TI's D-Sample and our own
+ − FCDEV3B), Openmoko's GTA0x GSM modem, and two "alien" Calypso phone families:
+ − Mot C1xx by Compal and Pirelli DP-L10 by Foxconn.
+ −
+ − 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
+ − Mot C11x/123 -h compal
+ − Mot C139/140 -h compal -c 1004
+ − Mot C155/156 -h c155
+ − Openmoko GTA02 -h gta02
+ − Pirelli DP-L10 -h pirelli
+ − TI D-Sample -h dsample
+ −
+ − 3. Cause the target device to execute its boot path. TI/Openmoko/FreeCalypso
+ − and Pirelli 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 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.
+ −
+ − The batch mode is entered when there is a command script given on the
+ − fc-loadtool invokation command line.
+ −
+ − 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-script]
+ −
+ − 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 "Basic usage" section above.
+ −
+ − -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.
+ −
+ − -n
+ −
+ − This option does anything only when loadtools have been compiled to run
+ − on GTA0x AP (see the Loadtools-on-GTA0x article). If you've compiled
+ − loadtools with the -DGTA0x_AP_BUILD option, it has an effect of making
+ − each tool automatically toggle the modem power control upon startup,
+ − removing the need for manual sequencing of the Calypso boot process.
+ − This -n option suppresses that action, making the AP build behave like
+ − the standard build in this regard.
+ −
+ − -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.
+ −
+ − 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 support a hack described in the Flash-boot-defect article.