# HG changeset patch # User Michael Spacefalcon # Date 1379090829 0 # Node ID 8b44e806b6e18ce93db043a33d225e0095f68c0c # Parent ae4921a3aa333f71c41585577578c5837db7a971 loadtools/README: documentation for loadtools should now be complete diff -r ae4921a3aa33 -r 8b44e806b6e1 loadtools/README --- a/loadtools/README Wed Sep 11 17:58:55 2013 +0000 +++ b/loadtools/README Fri Sep 13 16:47:09 2013 +0000 @@ -26,6 +26,7 @@ (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 @@ -44,6 +45,7 @@ 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 @@ -75,6 +77,14 @@ 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 @@ -84,6 +94,7 @@ 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: @@ -101,6 +112,7 @@ 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: @@ -109,13 +121,124 @@ 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 ", 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.