FreeCalypso > hg > freecalypso-tools
view loadtools/README.older @ 526:fc3592a27317
c139explore boot delay adjusted for running at 26 MHz
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Fri, 14 Jun 2019 05:51:38 +0000 |
parents | d5d6992897cf |
children |
line wrap: on
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 [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.