FreeCalypso > hg > freecalypso-tools
changeset 213:d5d6992897cf
loadtools/README renamed to README.old, previous README.old to README.older
| author | Mychaela Falconia <falcon@freecalypso.org> |
|---|---|
| date | Fri, 19 May 2017 06:11:27 +0000 |
| parents | abe21d7b1226 |
| children | b0de6d36e84c |
| files | loadtools/README loadtools/README.old loadtools/README.older |
| diffstat | 3 files changed, 417 insertions(+), 417 deletions(-) [+] |
line wrap: on
line diff
--- a/loadtools/README Fri May 19 05:41:12 2017 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,265 +0,0 @@ -The set of host tools built in this directory consists of: - -fc-loadtool The tool for operating on Calypso GSM devices at a low - level. After "breaking" into the target GSM device in - its boot process and getting FreeCalypso loadagent - running on the target (out of Calypso internal RAM, aka - IRAM), loadtool presents an interactive command prompt - with commands for peeking and poking registers and most - importantly, reading and writing any part of the - device's non-volatile flash memory. - -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. - -The currently supported target devices are the Compal family of basic -dumbphones, the Openmoko GTA0x GSM modem and the Pirelli DP-L10 feature phone. - -All tools in the FreeCalypso loadtools suite work by feeding pieces of code to -the target device as it boots, preventing the booting of its regular firmware -and diverting control to these externally-loaded code pieces. These pieces of -ARM7 target code need to be installed on the host system running loadtools, -normally in /usr/local/share/freecalypso: - -loadagent This is the "agent" code that runs on the target device when - fc-loadtool is operating on it: loadtool carries out its - operations by sending commands to loadagent. There is only one - version of loadagent for all currently supported Calypso - targets: loadagent does not access any resources outside of the - Calypso chip itself unless commanded to do so, and loadtool - supports different target devices with different hardware - configurations by sending different commands to loadagent as - appropriate. - -compalstage For Compal phones only: a little piece of code that is fed to - the original fw's bootloader via the serial download protocol - provided by the latter; it re-enables the Calypso chip boot ROM - and jumps to it, allowing our loadagent to be loaded in the - same way as on freedom-enabled devices. - -If you are working with a development snapshot of the freecalypso-tools source -tree, you will need to compile and install a GNU cross-compiler toolchain -targeting ARM7 (see ../toolchain) and then use that toolchain to compile -loadagent and compalstage (see ../target-utils) before you can successfully use -loadtools to operate on a target device. End-user oriented releases of -FreeCalypso host tools will include prebuilt loadagent and compalstage binaries -in the target-binaries subdirectory. - -Installing -========== - -Just run 'make' and 'make install' as usual. If the target-binaries directory -is present, your installation will be complete and ready to use. If you are -building these pieces yourself from source, do a 'make' and 'make install' in -../target-utils, after you have the ARM7 gcc toolchain installed and working. - -Basic usage -=========== - -The steps for bringing up fc-loadtool to operate on a target Calypso device are -as follows: - -1. If you are using a USB serial adapter, or operating on a Pirelli phone that - has one built in, connect the USB side first so that the necessary - /dev/ttyUSB* device node appears. - -2. Run fc-loadtool like this: - - fc-loadtool $TARGETOPT /dev/ttyXXX - - Change /dev/ttyXXX to the actual serial port you are using, and change - $TARGETOPT to: - - Device Needed options - ----------------------------------- - Mot C11x/123 -h compal - Mot C139/140 -h compal -c 1004 - Mot C155/156 -h c155 - Openmoko GTA02 -h gta02 - Pirelli DP-L10 -h pirelli - -3. Cause the target device to execute its boot path. Openmoko GTA0x and - Pirelli DP-L10 targets have the Calypso boot ROM enabled, and will interrupt - and divert their normal boot path when they "hear" the beacons which - fc-loadtool will be sending down the serial line. Compal phones have this - boot ROM disabled at the board level, but their standard firmware includes a - flash-resident bootloader that offers a different way of interrupting the - boot path and loading code over the serial line; fc-loadtool will be set up - to speak the latter protocol when run with the corresponding options from - the table above. - -You will see messages showing fc-loadtool's progress with feeding first -compalstage (if needed), then loadagent (always needed) to the target device, -followed by some target-specific initialization done via loadagent commands. -If all of the above succeeds, you will land at a loadtool> prompt. Type -'help', and it will guide you from there. Alternatively, you can familiarize -yourself with loadtool commands and operations without actually running it by -reading the loadtool.help text file. - -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. - --c <compalstage flavor> - - This option is common for all 3 utilities. It directs the tools to - perform the Compal loading stage before proceeding with the Calypso - boot ROM serial protocol, and selects the "flavor" of compalstage to - use. As you can see in the source, compalstage is built in 3 different - versions, for different C1xx models which exhibit different quirks. - - This option overrides the compal-stage setting given in the hardware - parameter file selected with -h or -H; the -c or -C option must be given - after -h or -H in order to take effect. -c none disables the Compal - stage and causes the tools to proceed directly to the Calypso boot ROM - phase, even on targets for which the hardware parameter file specifies - compal-stage. - --C /path/to/compalstage-binary - - This option is just like -c, except that the given argument is used - directly as the compalstage binary file pathname (absolute or relative) - without checking or alteration. - --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 - parameter file. - - The hardware configurations known to the present release of FreeCalypso - loadtools are listed in the "Basic usage" section above. - --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 (see the corresponding section below). 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 (fc-loadtool) - - This option is specific to fc-loadtool. It causes the tool to skip its - normal steps of feeding loadagent and possibly compalstage to the target - via special serial protocols, and instead assume that the target is - already running loadagent, communicating at the specified baud rate. - In other words, reattach to an already running loadagent. Use this - option if your fc-loadtool session has been terminated ungracefully and - you would like to reattach and resume, rather than forcibly reset the - target by yanking and reinserting the battery and restart from the - beginning. - --r baud (fc-xram) - - 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. - -Openmoko GTA0x -============== - -All of the above instructions assume that you are running these loadtools on a -general-purpose host system such as a GNU/Linux PC or laptop, and will -potentially use them to operate on multiple Calypso targets of different kinds. -If instead you are building loadtools to run on the application processor of a -smartphone such as Openmoko GTA0x, then it makes no sense for that special build -of loadtools to support any target other than the specific modem in that -smartphone. Loadtools can be built with compalstage support excluded and with -GTA0x-specific modem power control included instead. This build will still -include a bunch of functions of no relevance to GTA0x, but oh well.. - -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= from listing compalload.o to listing compaldummy.o and - gtapower.o instead. - -See gta-ap-build.sed for an example.
--- a/loadtools/README.old Fri May 19 05:41:12 2017 +0000 +++ b/loadtools/README.old Fri May 19 06:11:27 2017 +0000 @@ -1,15 +1,13 @@ -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 set of host tools built in this directory consists of: -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-loadtool The tool for operating on Calypso GSM devices at a low + level. After "breaking" into the target GSM device in + its boot process and getting FreeCalypso loadagent + running on the target (out of Calypso internal RAM, aka + IRAM), loadtool presents an interactive command prompt + with commands for peeking and poking registers and most + importantly, reading and writing any part of the + device's non-volatile flash memory. fc-iram & fc-xram These utilities are intended for FreeCalypso developers only. They load an S-record code image into IRAM or @@ -18,150 +16,89 @@ 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 -========= +The currently supported target devices are the Compal family of basic +dumbphones, the Openmoko GTA0x GSM modem and the Pirelli DP-L10 feature phone. -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. +All tools in the FreeCalypso loadtools suite work by feeding pieces of code to +the target device as it boots, preventing the booting of its regular firmware +and diverting control to these externally-loaded code pieces. These pieces of +ARM7 target code need to be installed on the host system running loadtools, +normally in /usr/local/share/freecalypso: -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: +loadagent This is the "agent" code that runs on the target device when + fc-loadtool is operating on it: loadtool carries out its + operations by sending commands to loadagent. There is only one + version of loadagent for all currently supported Calypso + targets: loadagent does not access any resources outside of the + Calypso chip itself unless commanded to do so, and loadtool + supports different target devices with different hardware + configurations by sending different commands to loadagent as + appropriate. -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. +compalstage For Compal phones only: a little piece of code that is fed to + the original fw's bootloader via the serial download protocol + provided by the latter; it re-enables the Calypso chip boot ROM + and jumps to it, allowing our loadagent to be loaded in the + same way as on freedom-enabled devices. -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: +If you are working with a development snapshot of the freecalypso-tools source +tree, you will need to compile and install a GNU cross-compiler toolchain +targeting ARM7 (see ../toolchain) and then use that toolchain to compile +loadagent and compalstage (see ../target-utils) before you can successfully use +loadtools to operate on a target device. End-user oriented releases of +FreeCalypso host tools will include prebuilt loadagent and compalstage binaries +in the target-binaries subdirectory. -* 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. +Installing +========== -* 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. +Just run 'make' and 'make install' as usual. If the target-binaries directory +is present, your installation will be complete and ready to use. If you are +building these pieces yourself from source, do a 'make' and 'make install' in +../target-utils, after you have the ARM7 gcc toolchain installed and working. -Running fc-loadtool -=================== +Basic usage +=========== -Once you've got loadtools built and installed, you can run fc-loadtool +The steps for bringing up fc-loadtool to operate on a target Calypso device are 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. If you are using a USB serial adapter, or operating on a Pirelli phone that + has one built in, connect the USB side first so that the necessary + /dev/ttyUSB* device node appears. -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. Run fc-loadtool like this: -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. + fc-loadtool $TARGETOPT /dev/ttyXXX + + Change /dev/ttyXXX to the actual serial port you are using, and change + $TARGETOPT to: -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. + Device Needed options + ----------------------------------- + Mot C11x/123 -h compal + Mot C139/140 -h compal -c 1004 + Mot C155/156 -h c155 + Openmoko GTA02 -h gta02 + Pirelli DP-L10 -h pirelli -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 +3. Cause the target device to execute its boot path. Openmoko GTA0x and + Pirelli DP-L10 targets have the Calypso boot ROM enabled, and will interrupt + and divert their normal boot path when they "hear" the beacons which + fc-loadtool will be sending down the serial line. Compal phones have this + boot ROM disabled at the board level, but their standard firmware includes a + flash-resident bootloader that offers a different way of interrupting the + boot path and loading code over the serial line; fc-loadtool will be set up + to speak the latter protocol when run with the corresponding options from + the table above. -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. +You will see messages showing fc-loadtool's progress with feeding first +compalstage (if needed), then loadagent (always needed) to the target device, +followed by some target-specific initialization done via loadagent commands. +If all of the above succeeds, you will land at a loadtool> prompt. Type +'help', and it will guide you from there. Alternatively, you can familiarize +yourself with loadtool commands and operations without actually running it by +reading the loadtool.help text file. Command line options ==================== @@ -205,16 +142,37 @@ baud rate independently defaults to 115200 baud and can only be changed with the -r option. +-c <compalstage flavor> + + This option is common for all 3 utilities. It directs the tools to + perform the Compal loading stage before proceeding with the Calypso + boot ROM serial protocol, and selects the "flavor" of compalstage to + use. As you can see in the source, compalstage is built in 3 different + versions, for different C1xx models which exhibit different quirks. + + This option overrides the compal-stage setting given in the hardware + parameter file selected with -h or -H; the -c or -C option must be given + after -h or -H in order to take effect. -c none disables the Compal + stage and causes the tools to proceed directly to the Calypso boot ROM + phase, even on targets for which the hardware parameter file specifies + compal-stage. + +-C /path/to/compalstage-binary + + This option is just like -c, except that the given argument is used + directly as the compalstage binary file pathname (absolute or relative) + without checking or alteration. + -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. + parameter file. The hardware configurations known to the present release of FreeCalypso - loadtools are gta02 and pirelli. + loadtools are listed in the "Basic usage" section above. -H /path/to/hwparam-file @@ -232,14 +190,26 @@ -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. + on GTA0x AP (see the corresponding section below). 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 (fc-loadtool) --r baud + This option is specific to fc-loadtool. It causes the tool to skip its + normal steps of feeding loadagent and possibly compalstage to the target + via special serial protocols, and instead assume that the target is + already running loadagent, communicating at the specified baud rate. + In other words, reattach to an already running loadagent. Use this + option if your fc-loadtool session has been terminated ungracefully and + you would like to reattach and resume, rather than forcibly reset the + target by yanking and reinserting the battery and restart from the + beginning. + +-r baud (fc-xram) 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 @@ -266,6 +236,30 @@ 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. +Openmoko GTA0x +============== + +All of the above instructions assume that you are running these loadtools on a +general-purpose host system such as a GNU/Linux PC or laptop, and will +potentially use them to operate on multiple Calypso targets of different kinds. +If instead you are building loadtools to run on the application processor of a +smartphone such as Openmoko GTA0x, then it makes no sense for that special build +of loadtools to support any target other than the specific modem in that +smartphone. Loadtools can be built with compalstage support excluded and with +GTA0x-specific modem power control included instead. This build will still +include a bunch of functions of no relevance to GTA0x, but oh well.. + +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= from listing compalload.o to listing compaldummy.o and + gtapower.o instead. + +See gta-ap-build.sed for an example.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/loadtools/README.older Fri May 19 06:11:27 2017 +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.