+
−You are looking at the source for the FreeCalypso loadtools package.  You may
+
−have downloaded it either as a separate package or as part of the larger
+
−freecalypso-sw suite.
+
−
+
−The tools in this package are written to run on some Unix/Linux machine
+
−(normally a PC/Linux desktop or laptop) that acts as a host for operating on
+
−Calypso target devices.  All of these tools communicate with the Calypso target
+
−through a serial port; each tool begins its operation by sending special byte
+
−sequences to this serial port which are designed to interrupt the Calypso
+
−device boot process in the ROM bootloader.
+
−
+
−Three utilities are currently built as part of FreeCalypso loadtools:
+
−
+
−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.
+
−
+
−fc-loadtool		This utility is intended for both developers and end
+
−			users.  After establishing communication with the
+
−			target, fc-loadtool drops into interactive operation.
+
−			Once at the loadtool> prompt, you can peek and poke
+
−			registers, and most importantly, dump (read) and load
+
−			(program) the flash memory of the target device.
+
−
+
−Loadagent
+
−=========
+
−
+
−Both fc-loadtool and fc-xram work by first feeding a FreeCalypso-developed
+
−program called loadagent to the Calypso ROM bootloader; all further operations
+
−(loading code into XRAM or flash) are done via this loadagent.  An S-record
+
−image of the loadagent program is required for fc-loadtool and fc-xram to work.
+
−That program is in turn built with the ARM7 toolchain.
+
−
+
−If you are working with the full freecalypso-sw suite, you presumably already
+
−have the proper ARM7 toolchain built and installed.  To build loadagent, simply
+
−run 'make' in the ../target-utils tree.
+
−
+
−If you have downloaded a separately-packaged version of FreeCalypso loadtools,
+
−the package should have a prebuilt loadagent.srec image included, sparing
+
−non-developer users the nontrivial hurdle of having to build and install a
+
−special cross-compilation toolchain.  The same loadagent binary is designed to
+
−work on all supported Calypso targets.
+
−
+
−Building and installing loadtools
+
−=================================
+
−
+
−Normally the machine on which you build and install fc-loadtools would be your
+
−PC/Linux desktop or laptop, the system you would use to program or otherwise
+
−interact with Calypso phones by way of appropriate USB-to-phone cables.  Just
+
−like loadagent, the host utilities you are going to build and install aren't
+
−specific to a particular target device; instead you will select the target
+
−device at run time via a command line option.  Hence you can build and install
+
−the host utilities (usual 'make' and 'make install') without limiting your
+
−setup to just one target phone type.
+
−
+
−However, if your intended target device is an Openmoko GTA02 (or GTA01)
+
−smartphone, there is one additional complication: one cannot directly access
+
−the Calypso part of these phones from the outside without going through the
+
−phone's application processor first.  If you would like to use fc-loadtool to
+
−read or write the GSM flash memory of your GTA0x (load a different firmware
+
−image, dump the flash file system for backup or examination, restore a previous
+
−backup etc), there are two ways to do it:
+
−
+
−1. The recommended way for FreeCalypso developers is to get a special serial
+
−   cable (low voltage, as in 3.3V or lower - *NOT* RS-232 levels - please don't
+
−   fry your precious phone!) that would plug into the 2.5mm jack on the left
+
−   side of the phone that is normally intended for a wired headset.  This way
+
−   you can use your regular build of fc-loadtool (and fc-iram & fc-xram) on
+
−   your PC/Linux (or other) development host, no need to build anything for
+
−   GTA0x AP, and all communication happens directly between your development
+
−   host and the Calypso part of your target phone - not going through the AP
+
−   at all.  You still need working software on the GTA0x AP to do battery
+
−   management, to power the Calypso block on and off, and to enable the headset
+
−   jack "download" path, but it is much less burdensome than having to do the
+
−   actual FreeCalypso work from the AP.
+
−
+
−Having the headset jack do double duty as a programming port is actually a
+
−standard practice in the world of basic (non-smart) cellular phones, and
+
−furthermore, the pinout used by FIC on the GTA0x phones just happens to be
+
−exactly the same as that used by Compal/Motorola - hence the same headset jack
+
−serial cables that are used by OsmocomBB with the latter phones (the famous
+
−"T191 unlock cable") will also work for connecting from an external host
+
−directly to the Calypso part of GTA0x phones.
+
−
+
−2. If you are an end user who simply wishes to reflash a different GSM firmware
+
−   image, it can be done from inside the phone (from the AP) without having to
+
−   acquire special hardware (as in the cable described above).  However, the
+
−   trade-off is that in return for saving on the special hardware, you have to
+
−   do more work on the software.  You will have to use a cross-compiler
+
−   targeting the ARM/Linux AP environment (*not* the ARM7 cross-compiler used
+
−   for the GSM firmware itself!) to build fc-loadtools to run on the GTA0x AP.
+
−
+
−Building loadtools for GTA0x AP
+
−===============================
+
−
+
−If you've decided to build loadtools for the GTA0x AP, you'll need to make the
+
−following modifications to the Makefile:
+
−
+
−* Change the CC= line to point to the appropriate cross-compiler (which you'll
+
−  need to provide yourself);
+
−
+
−* Change the CFLAGS= line: add the right options to target the ARM920T core in
+
−  the GTA0x AP (e.g., -march=armv4t -mtune=arm920t), and add -DGTA0x_AP_BUILD
+
−  to enable some code that makes sense only when running on the GTA0x AP.
+
−
+
−* Change EXTRA_OBJ= to EXTRA_OBJ=gtapower.o, i.e., add gtapower.c (compiling
+
−  into gtapower.o) to the build.
+
−
+
−See gta-ap-build.sed for an example.
+
−
+
−Running fc-loadtool
+
−===================
+
−
+
−Once you've got loadtools built and installed, you can run fc-loadtool
+
−as follows:
+
−
+
−To operate on a Pirelli DP-L10 that appears as /dev/ttyUSB0:
+
−
+
−fc-loadtool -h pirelli /dev/ttyUSB0
+
−
+
−The usb2serial chip inside the phone is bus-powered and will be visible as
+
−/dev/ttyUSBx whether the phone battery is present or not.  There are two ways
+
−to break into the bootloader:
+
−
+
−1. Run the fc-loadtool command given above with the USB cable connected, but no
+
−   battery present.  Once loadtool says "Sending beacons to <port>", insert the
+
−   battery.
+
−
+
−2. Connect the USB cable to a powered-on phone running its original factory
+
−   firmware.  (If the phone was off, it will power up and boot in the "charging
+
−   only" mode - it is not possible for a Calypso/Iota phone to be completely
+
−   off when both the battery and the charging voltage are present.)  Run
+
−   fc-loadtool as above - it will start sending its beacons, which will be
+
−   ignored by the running fw.  Then execute the "power off" operation from the
+
−   UI (unlock the keypad, then press and hold the red button).  The presence of
+
−   USB VBUS (used as the charging power source on this phone) will turn the
+
−   power-off into a reboot, and you'll break into the bootloader.
+
−
+
−To operate on the Calypso block of a GTA02, accessing it from an external
+
−PC/Linux host via a USB-to-headset-jack serial cable that appears as
+
−/dev/ttyUSB0:
+
−
+
−fc-loadtool -h gta02 /dev/ttyUSB0
+
−
+
−Run the above command first, then power on the GSM modem from the AP - or power
+
−it off, then on if it was on already.  The "download" path needs to be enabled
+
−(controlled from the AP) and fc-loadtool needs to be running on the external
+
−host when the modem is powered on.
+
−
+
−To operate on the Calypso block of a GTA02, running fc-loadtool from inside the
+
−phone, i.e., from the AP of the same GTA02:
+
−
+
−fc-loadtool -h gta02 /dev/ttySAC0
+
−
+
−In this last scenario the specially built version of fc-loadtool running on the
+
−AP takes care of manipulating the modem power to induce entry into the
+
−bootloader, thus no extra manual steps are needed.
+
−
+
−See loadtool.help for a detailed description of the functionality and commands
+
−that are available once loadtool is running and communicating with loadagent on
+
−the target device.
+
−
+
−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
+
−fc-xram [options] ttyport xramimage.srec [runbaud]
+
−fc-loadtool [options] ttyport
+
−
+
−The last optional argument to fc-xram selects the serial line baud rate which
+
−should be set just before the loaded XRAM image is jumped to; the default is
+
−115200 baud.
+
−
+
−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
+
−
+
−	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
+
−	by the last optional argument on the fc-xram command line.
+
−
+
−-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 /usr/local/share/freecalypso/%s.config, where %s
+
−	is the argument given to this option, and uses that file as the hardware
+
−	parameters file.
+
−
+
−	The hardware configurations knows to the present release of FreeCalypso
+
−	loadtools are gta02 and pirelli.
+
−
+
−-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.  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.