FreeCalypso > hg > freecalypso-tools
diff loadtools/old/README.older @ 577:62a91abc0300
loadtools: no-longer-working stuff moved into old subdir
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 02 Feb 2020 21:18:37 +0000 |
parents | loadtools/README.older@d5d6992897cf |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/loadtools/old/README.older Sun Feb 02 21:18:37 2020 +0000 @@ -0,0 +1,271 @@ +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 [2ndprog] +fc-loadtool [options] ttyport + +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 + with the -r option. + +-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 known 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. + +-r baud + + 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-xram 2nd program invokation +============================== + +The fc-xram utility can take two possible actions after it has loaded the +specified S-record image into XRAM: + +* The default action, in the absence of additional command line arguments, is + to drop into a serial tty pass-thru mode, just like fc-iram. + +* 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 software suite, not for launching any arbitrary 3rd-party + programs from fc-xram. + +The intended usage scenario is that one builds a version of the FreeCalypso GSM +firmware (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. + +More detailed usage instructions will be written when the rvinterf tools reach +a point of being usable by more than just the original developer; until then, +read the source code.