# HG changeset patch # User Mychaela Falconia # Date 1495147932 0 # Node ID 5433349a6e2cc602659d9e71a8da92e02d389772 # Parent 4022bfbaafd474ab5f165ec12e9e041e27643d72 doc/Loadtools-usage: replacing loadtools/README diff -r 4022bfbaafd4 -r 5433349a6e2c doc/Loadtools-usage --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Loadtools-usage Thu May 18 22:52:12 2017 +0000 @@ -0,0 +1,239 @@ +The loadtools subset of FreeCalypso host tools 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 (in the order of decreasing +preference) official Calypso development boards (TI's D-Sample and our own +FCDEV3B), Openmoko's GTA0x GSM modem, and two "alien" Calypso phone families: +Mot C1xx by Compal and Pirelli DP-L10 by Foxconn. + +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 /opt/freecalypso/target-bin: + +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 include prebuilt loadagent and compalstage binaries. + +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. If you are working with a target such as + FCDEV3B or D-Sample on which both Calypso UARTs are equally accessible with + equal convenience, you can arbitrarily pick either one for fc-loadtool - it + will work exactly the same through either port. + +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 + ----------------------------------- + FreeCalypso FCDEV3B -h fcfam + 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 + TI D-Sample -h dsample + +3. Cause the target device to execute its boot path. TI/Openmoko/FreeCalypso + and Pirelli 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 [2ndprog] +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 + + 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 /opt/freecalypso/loadtools/%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-iram & fc-xram 2nd program invokation +======================================== + +Our fc-iram and fc-xram utilities can take two possible actions after they have +loaded the specified S-record image into RAM: + +* The default action, in the absence of additional command line arguments, is + to drop into a serial tty pass-thru mode. + +* 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 host tools suite, not for launching any arbitrary + 3rd-party programs from fc-xram or fc-iram. + +This feature was originally implemented in fc-xram only, and the intended usage +scenario is that one builds a version of one of our FreeCalypso GSM firmwares +(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. + +This second program invokation capability was later extended to fc-iram for no +purpose other than to support a hack described in the Flash-boot-defect article.