+
−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.