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